API Overview

Last Updated on Thursday, 12 January 2012 05:48 Written by admin

HTTP API

The NeTV HTTP API provides a mechanism to interact with NeTV through web interface on port 80.
The API can be called from a standard web browser, which will also display any results.
This method is probably the easiest way to experiment with the API commands.

The simplest command to try out is
http://localhost/bridge?cmd=Hello (from within NeTV)
http://xxx.xxx.xxx.xxx/bridge?cmd=Hello (from other device. Replace xxx by the IP address of NeTV)
This will give some basic status and ID information about the device.

More complex commands can be constructed as a GET/POST request.
Variables be GET/POST directly as normal HTML form variables (must be URI-encoded).
Example: to send a remote control key command (single parameter)
* cmd=RemoteControl
* value=right
Example: to send a TickerEvent command (multiple parameters)
* cmd=TickerEvent
* message=abcdefghifk
* title=blahblah
* image=full url to an image

Generic return format

The return format is a XML string in the following format

<xml>
    <status>.....</status>
    <cmd>........</cmd>
    <data>.......</data>
</xml>

* status:
** 0 – Unimplemented command
** 1 – Success
** 2 – General error
* cmd: is echo of the command name
* data: is the return data of the command, it is designed to be an array of XML elements. For single value response, this is always “

NeTVServer

These webservices are provided by NeTVServer process, which is a custom built webserver, located in ”’/usr/bin/NeTVServer”’
It hosts:
* HTTP server on port 80, document root is located in /usr/share/netvserver/docroot
* TCP server on port 8081, accepting command & response in XML format
* UDP server on port 8082, accepting command & response in XML format
* Flash security policy server on port 843, simply allowing all cross-domain access to the device. See this [url=http://www.adobe.com/devnet/flashplayer/articles/socket_policy_files.html article].
There is a helper script to start/stop/restart this process
/etc/init.d chumby-netvserver start
/etc/init.d chumby-netvserver stop
/etc/init.d chumby-netvserver restart

NeTVServer is a console application implemented with C++, Qt libraries and shell scripts.
Only 1 instance of NeTVServer is allowed to run at once. The 2nd instance starts up and return immediately.

Cookies

A simple demo of using cookies is available at http://10.0.88.1/session
This feature has not been fully tested. More documentation to be made available.
Alternatively, please use GetParam & SetParam commands to save non-volatile (persistent) data.

Execute custom scripts

NeTVServer has a mechanism to mimic behaviour of cgi-bin script execution.
This allows you to create custom shell scripts & have them executed from a normal HTTP GET/POST request.
There is no restrictions on which shell commands can/cannot be executed since root access is wide open.
Here are the steps to create a custom shell script & pass parameters to it:
* Mount read-write, create a script file, make it executable

 mount -o remount,rw /
 cd /usr/share/netvserver/docroot/scripts
 touch myscript.sh
 chmod +x myscript.sh

* Make your script do something useful. Example:

 #!/bin/bash
 uname -a
 chumby_version -f
 echo "\$1 = $1"
 echo "\$2 = $2"
 echo "\$3 = $3"
 echo "num = $#"
 # you can really kill yourself too
 #killall NeTVServer
 #reboot

* Execute it from HTTP interface http://10.0.88.1/scripts/myscript.sh?param1=aaaaaa&param2=bbbbbb&param3=ccccc
Gives you this response:

 Linux localhost.localdomain 2.6.28 #1 Mon Oct 10 17:17:41 SGT 2011 armv5tejl GNU/Linux
 19
 $1 = ccccc
 $2 = bbbbbb
 $3 = aaaaaa
 num = 3

”’Note:”’
Notice the reversed order of the parameters.
Since shell script doesn’t use key=value pair like POST/GET, the name of the parameters (param1,2,3) don’t really matter.
You can have it anything you like, eg. This has the same meaning: blah1=aaaaaa&blah2=bbbbbb&blah3=ccccc

However, the lexicon order of the names are used when passed to the shell script.
So, the following will give you the opposite order: http://10.0.88.1/scripts/myscript.sh?zzz=aaaaaa&yyy=bbbbbb&xxx=ccccc

 $1 = aaaaaa
 $2 = bbbbbb
 $3 = ccccc

TCP & UDP interfaces

NeTVServer’s TCP & UDP interfaces provide mechanisms to interact with NeTV through socket interface.
UDP interface is generally faster than HTTP & TCP and is more suitable for real-time commands like page scrolling and button events.
UDP broadcast messages are currently used by Android & iOS app for device discovery when NeTV’s IP address is not known or when there are multiple NeTV devices in the same network.
TCP interface are currently used to exchange data between NeTVServer & NeTVBrowser

For UDP messages, the client can choose to use either broadcast or unicast target IP address.
However, the reply from NeTV is always unicast back to the originating address.
* TCP socket on port 8081
* UDP socket on port 8082
All commands & parameters are identical to HTTP API.

Example messages to be transmitted to NeTV over UDP/TCP:
”’No parameter”’

<xml>
    <cmd>Hello</cmd>
</xml>

”’One parameter”’

<xml>
    <cmd>RemoteControl</cmd>
    <data>
       <value>right</value>
    </data>
</xml>

”’Multiple parameters”’

<xml>
    <cmd>Hello</cmd>
    <data>
       <type>android</type>
       <version>0.5.6</version>
    </data>
</xml>
<xml>
    <cmd>SetParam</cmd>
    <data>
       <myKey1>myValue1</myKey1>
       <myKey2>myValue2</myKey2>
    </data>
</xml>

1 Comment

  1. The UI | Kosagi Blog   |  Thursday, 12 January 2012 at 5:46 pm

    [...] Last Updated on Thursday, 12 January 2012 05:46 Written by admin Thursday, 12 January 2012 05:37 ContentsStart/stopSetting URLMultitabKeep-alive timerInject JavaScriptScreen rotationShow debug traces & JavaScript outputSimulate/Inject a keyboard eventNon-native keyboard inputNative keyboard inputNative mouse inputNeTV local UI is entirely rendered by Webkit browser, running in a chromeless/fullscreen fashion. The UI is written in JavaScript & HTML. Hardware integration is supported by submitting POST/GET request to http://localhost/bridge. (See HTTP API) [...]

Leave a Reply