Difference between revisions of "NeTV web services"

From Chumby Wiki
Jump to: navigation, search
m (dataxml_ instead of xmldata_)
(add custom script execution)
Line 70: Line 70:
 
This feature was not fully tested yet. More documentation to be made available.<br/>
 
This feature was not fully tested yet. More documentation to be made available.<br/>
 
Alternatively, please use GetParam & SetParam commands to save non-volatile (persistent) data.
 
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.<br/>
 +
This allows you to create custom shell scripts & have them executed from a normal HTTP GET/POST request.<br/>
 +
There is no restrictions on which shell commands can/cannot be executed since root access is wide open.<br/>
 +
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
 +
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<br/>
 +
Gives you this response:
 +
$1 = ccccc
 +
$2 = bbbbbb
 +
$3 = aaaaaa
 +
num = 3
 +
'''Note:'''<br/>
 +
Notice the first in first out order of the parameters.<br/>
 +
Since shell script parameters doesn't use key=value pair like POST/GET, the names (param1,2,3) doesn't really matter.<br/>
 +
You can have it anything you like, eg. This has the same meaning: blah1=aaaaaa&blah2=bbbbbb&blah3=ccccc<br/>
 +
<br/>
 +
However, the lexicon order of the names are used when passed to the shell script.<br/>
 +
So, the following will give you the reversed order: http://10.0.88.1/scripts/myscript.sh?zzz=aaaaaa&yyy=bbbbbb&xxx=ccccc<br/>
 +
$1 = aaaaaa
 +
$2 = bbbbbb
 +
$3 = ccccc
 +
num = 3
  
 
= TCP & UDP interfaces =
 
= TCP & UDP interfaces =

Revision as of 19:27, 22 October 2011

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 POST Request as follow.
- POST to: http://localhost/bridge or http://xxx.xxx.xxx.xxx/bridge
- Content-Type must be set to application/x-www-form-urlencoded
- variable cmd : command name, case insensitive
- variable data : optional variable to submit arguments with the command, formatted as a XML string

Example: to send a remote control key command (single parameter)
- cmd=RemoteControl
- data=<value>right</value>
Example: to send a TickerEvent command (multiple parameters)
- cmd=TickerEvent
- data=<message>abcdefghifk</message><title>blahblah</title><image>full url to an image<image>
[The above format is deprecated]

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>
   .......
</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 "<value>...</value>"

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

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++ and Qt libraries.
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 was not fully tested yet. 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
echo "\$1 = $1"
echo "\$2 = $2"
echo "\$3 = $3"
echo "num = $#"
# you can really kill yourself too
#killall NeTVServer
#reboot

Gives you this response:

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

Note:
Notice the first in first out order of the parameters.
Since shell script parameters doesn't use key=value pair like POST/GET, the names (param1,2,3) doesn'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 reversed order: http://10.0.88.1/scripts/myscript.sh?zzz=aaaaaa&yyy=bbbbbb&xxx=ccccc

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

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, except they have to be wrapped in XML format.

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

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

One parameter

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

Multiple parameters

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


Commands list

Command names are case-insensitive.
Parameters are case-sensitive.

Hello

Returns some basic information about the device.
Parameters:

  • (optionals) type = netvbrowser/android/iphone/ipad/ipod/desktop
  • (optionals) version = some version number

These parameters are currently used by NeTVServer & NeTVBrowser to identify each other.
This is designed such that each client may function as an extension to NeTVServer.
In this case, NeTVBrowser provides UI/HTML/JavaScript extension.
HTTP GET example:
http://10.0.88.1/bridge?cmd=hello
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>HELLO</cmd>
   <status>1</status>
   
      <guid>A620123B-1F0E-B7CB-0E11-921ADB7BE22A</guid>
      <dcid>...a long string of 1024 bytes...</dcid>
      <hwver>...hardware version number...</hwver>
      <fwver>...firmware version number...</fwver>
      <internet>true/false/connecting</internet>
      <mac>48:5D:60:A3:AC:FF</mac>
      <ip>xxx.xxx.xxx.xxx</ip>
      <network>...a long XML string from network_status.sh...</network>
   
</xml>

guid - a unique ID for each device. This is generated the very first time NeTV powers up
hwver - hardware version
fwver - firmware version, changed (increases) after every software update
internet - true: connected to Internet; connection: trying to associate with WiFi network; false: cannot associate with WiFi network
mac - MAC address of the WiFi interface
ip - IP address of WiFi interface. When NeTV is in Access Point mode, the IP is always 192.168.100.1
network - raw network status from shell command 'network_status.sh' providing some useful network parameters like dns, netmask, gateway, network configuration

WifiScan

Returns a list of WiFi network found by NeTV.
Parameters:
(no parameters)
HTTP GET example:
http://10.0.88.1/bridge?cmd=wifiscan
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>WIFISCAN</cmd>
   <status>1</status>
   
      <wifi><ssid>chumby_test_ap_1</ssid><qty>54/70</qty><lvl>-56</lvl><ch>3</ch><mode>Master</mode><encryption>NONE</encryption><auth>OPEN</auth></wifi>
      <wifi><ssid>bec</ssid><qty>28/70</qty><lvl>-82</lvl><ch>6</ch><mode>Master</mode><encryption>WEP</encryption><auth>WEPAUTO</auth></wifi>
      <wifi><ssid>ChumbyWPA</ssid><qty>50/70</qty><lvl>-60</lvl><ch>1</ch><mode>Master</mode><encryption>AES</encryption><auth>WPA2PSK</auth></wifi>
   
</xml>

SetChromaKey

Enable/disable chroma color filtering on FPGA.
When enabled, any pixel with color rgb=240,0,240 or #F000F0 will be see-through (showing video feed behind)
When disable, the screen will be mostly filled with the chroma color (pink).
Parameters:

  • value = on/off (pick one)

HTTP GET example:
http://10.0.88.1/bridge?cmd=setchromakey&value=off
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>SETCHROMAKEY</cmd>
   <status>1</status>
   
      <value>some raw output from shell command</value>
   
</xml>

RemoteControl

Simulates an infra-red remote control button event.
Parameters:

  • value = cpanel/widget/up/down/left/right/center (pick one)

HTTP GET example:
http://10.0.88.1/bridge?cmd=remotecontrol&value=left
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>REMOTECONTROL</cmd>
   <status>1</status>
   
      <value>echo of the actual button name received</value>
   
</xml>

FileExists

Checks whether a file exists in local filesystem.
Parameters:

  • value = full path to a local file

HTTP GET example:
http://10.0.88.1/bridge?cmd=fileexist&value=%2Fpsp%2Fnetwork_config (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>FILEEXISTS</cmd>
   <status>1</status>
   
      <value>true/false</value>
   
</xml>

GetFileContents

Returns the content of a file in local filesystem.
Parameters:

  • value = full path to a local file

HTTP GET example:
http://10.0.88.1/bridge?cmd=getfilecontents&value=%2Fpsp%2Fnetwork_config (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>GETFILECONTENTS</cmd>
   <status>1</status>
   
      <value>......raw file content......</value>
   
</xml>
or
<xml>
   <cmd>GETFILECONTENTS</cmd>
   <status>2</status>
   
      <value>file not found</value>
   
</xml>

Note:
The returned data is neither XML-escaped nor URI-encoded. Therefore, the entire return XML string is very likely to be NOT well-formed.
It is recommended to process the entire returned data it as a string (rather than using XML parser), and perform a string split between 1st and last to get the desired result.

GetFileSize

Returns the size of a file in local filesystem.
Parameters:

  • value = full path to a local file

HTTP GET example:
http://10.0.88.1/bridge?cmd=getfilesize&value=%2Fpsp%2Fnetwork_config (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>GETFILESIZE</cmd>
   <status>1</status>
   
      <value>size of the file in bytes</value>
   
</xml>
or
<xml>
   <cmd>GETFILESIZE</cmd>
   <status>2</status>
   
      <value>file not found</value>
   
</xml>

GetParam

Gets the non-volatile value of parameter saved locally in filesystem.
The parameters are saved in /psp/parameters.ini using QSettings' default implementation.
Parameters:

  • value = name of the parameter, prefixed with 'dataxml_'

HTTP GET example:
http://10.0.88.1/bridge?cmd=getparam&value=dataxml_ticker_speed
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>GETPARAM</cmd>
   <status>1</status>
   
      <value>value of the parameter</value>
   
</xml>

Note: There is a bug while migrating to new command format. Please prefix parameter name with 'dataxml_'

SetParam

Set new value(s) for non-volatile parameter(s) saved locally in filesystem.
The parameters are saved in /psp/parameters.ini using Qt QSettings' default implementation.
Parameters:

  • (required) name_of_1st_param, prefixed with 'dataxml_' = value of 1st parameter
  • (optional) name_of_2nd_param, prefixed with 'dataxml_' = value of 2nd parameter
  • (optional) name_of_3rd_param, prefixed with 'dataxml_' = value of 3rd parameter

HTTP GET example:
http://10.0.88.1/bridge?cmd=setparam&dataxml_ticker_speed=1&dataxml_ticker_ypos=123
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>SETPARAM</cmd>
   <status>1</status>
   
      <value>number of parameters received</value>
   
</xml>

Note: There is a bug while migrating to new command format. Please prefix parameter name with 'dataxml_'

TickerEvent

Shows a ticker message crawling across the screen.
Parameters:

  • (required) message = long content of message
  • (optional) title = a short title
  • (optional) image = full url to a small thumbnail image
  • (optional) type = system/widget/sms
  • (optional) level = low/high

HTTP GET example:
http://10.0.88.1/bridge?cmd=tickerevent&message=you%20should%20see%20this%20thing%20crawling%20across%20the%20screen&title=Hello%20World (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>TICKEREVENT</cmd>
   <status>1</status>
   
      <value>command forwarded to browser</value>
   
</xml>
or
<xml>
   <cmd>TICKEREVENT</cmd>
   <status>2</status>
   
      <value>no browser is running</value>
   
</xml>

GetUrl

Download the content of a URL and return as a long text string.
This command was designed mainly to over come JavaScript's restriction when getting XML content from cross-domain web services.
Internally, NeTVServer is using shell's curl command to perform the download, hence no such restrictions.
Parameters:

  • (required) url = full url to some web resource
  • (optional) post = POST data in format param1=value1&param2=value2 (URI encoded)

HTTP GET example:
http://10.0.88.1/bridge?cmd=tickerevent&message=you%20should%20see%20this%20thing%20crawling%20across%20the%20screen&title=Hello%20World (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>TICKEREVENT</cmd>
   <status>1</status>
   
      <value>......a long string of returned data......</value>
   
</xml>

Note:
The returned data is neither XML-escaped or URI-encoded. Therefore, the entire return XML string is very likely to be NOT well-formed.
It is recommended to process the entire returned data it as a string (rather than using XML parser), and perform a string split between 1st and last to get the desired result.

Multitab

NeTVBrowser supports multi-tab browsing, much like modern web browsers.
The first tab (index 0) is reserved for NeTV's Control Panel. The other tabs (index 1 to 9) can be shown/hide/load with other contents without affecting the Control Panel.
Parameters:

  • (required) tab = index of the tab (1 to 9)
  • (required) options = load/show/hide/html
  • (optional) param = [full url to load if options==load] or [raw html syntax if options==html] (URI encoded)

HTTP GET example:
http://10.0.88.1/bridge?cmd=multitab&tab=1&option=load&param=http%3A%2F%2Fwww.abc.com (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>MULTITAB</cmd>
   <status>1</status>
   
      <value>command forwarded to browser</value>
   
</xml>
or
<xml>
   <cmd>MULTITAB</cmd>
   <status>2</status>
   
      <value>browser not found</value>
   
</xml>