Difference between revisions of "NeTV web services"

From Studio Kousagi Wiki
Jump to: navigation, search
(Created page with "= HTTP API = The NeTV HTTP API provides a mechanism to interact with NeTV through web interface on port 80.<br> The API can be called from a standard web browser, which will also...")
(No difference)

Revision as of 16:37, 2 November 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
  • 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

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, 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>

Command demos

A demo HTML page is available at http://10.0.88.1/html_test/ (replace with NeTV's IP address).
Some commands exist in the demo page are under development and not documented in this wiki page.
It is not recommended to use them.

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>

EnableSSH

Enable/disable SSH daemon.
If NeTV is powered by a USB port of a computer, SSH will be enabled automatically. Output value can be optionally XML-escaped.
Parameters:

  • (optional) value = start-chumby/stop/reload/force-reload/restart (pick one)
  • (optional) xmlescape = true/false

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

<xml>
   <cmd>ENABLESSH</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>

Key

Simulates a single keyboard event on NeTVBrowser (and other connected TCP clients).
Parameters:

  • value = cpanel/widget/up/down/left/right/center/[a-z]/[0-9]/home/end/delete/pgup/pgdown/punctuations/... (pick one)

Full list is available here
HTTP GET example:
http://10.0.88.1/bridge?cmd=key&value=left
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>KEY</cmd>
   <status>1</status>
   
      <value>echo of the actual key 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.
Output value can be optionally XML-escaped.
Parameters:

  • (required) value = full path to a local file
  • (optional) xmlescape = true/false

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 or URI-encoded by default.

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>

UnlinkFile

Delete a file in NeTV's filesystem.
NeTV's filesystem is mounted as read-only by default except for some special locations. This command will return error condition if it is trying to delete a read-only location.
If there is a need to delete file in such locations, please first use NeCommand (with value = "mount -o remount,rw /") to mount the filesystem as read-write.
This command will return success (true) if the file does not exist.
Parameters:

  • value = full path to a local file

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

<xml>
   <cmd>UNLINKFILE</cmd>
   <status>1</status>
   
      <path>echo of the input path</path>
      <value>true</value>
   
</xml>
or 
<xml>
   <cmd>UNLINKFILE</cmd>
   <status>2</status>
   
      <path>echo of the input path</path>
      <value>false</value>
   
</xml>

UploadFile

Use HTML form to POST a file to any where in NeTV's filesystem.
Only traditional HTML <form> is supported. jQuery .post() is not supported.
NeTV's filesystem is mounted as read-only by default except for some special locations.
/psp is recommended for storing files persistently (non-volatile).
/tmp is in fact located in RAM, hence will store volatile files. It is not recommended to upload too big files here due to limited RAM.
If there is a need to upload file to other locations, please first use NeCommand (with value = "mount -o remount,rw /") to mount the filesystem as read-write.
HTML form code:

<form method="post" enctype="multipart/form-data">
    <input type="hidden" name="cmd" value="uploadfile">
    <input type="hidden" name="path" value="/tmp/abc.jpg">
    <input type="file" name="filedata">
    <input type="submit">
</form>

A demo page is available at http://10.0.88.1/html_test/index.html
HTTP GET example:
(GET is not supported)
Return:

<xml>
   <cmd>UPLOADFILE</cmd>
   <status>1</status>
   
      <path>echo of the input path</path>
      <filesize>size of the file in bytes</filesize>
   
</xml>
or
<xml>
   <cmd>UPLOADFILE</cmd>
   <status>2</status>
   
      <path>echo of the input path</path>
      <message>some helpful error messages</message>
   
</xml>

Tricks: You can upload a file to /tmp, for eg. /tmp/abc.jpg, and access it via HTTP as http://10.0.88.1/tmp/netvserver/abc.jpg

GetParam

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

  • value = name of the parameter

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

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

GetParams (firmware 22 onwards)

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

  • value = name of the parameters, comma seperated

HTTP GET example:
http://10.0.88.1/bridge?cmd=getparam&value=myparam1%3Bmydata%3Banotherone (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>GETPARAMS</cmd>
   <status>1</status>
   
      <myparam1>value of the myparam1</myparam1>
      <mydata>value of the mydata</mydata>
      <anotherone>value of the anotherone</anotherone>
   
</xml>

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 = value of 1st parameter
  • (optional) name_of_2nd_param = value of 2nd parameter
  • (optional) name_of_3rd_param = 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 was a bug in firmware earlier than 20. Please prefix parameter names with 'dataxml_'
Firmware 20 and newer does not require this.

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.
Output value can be optionally XML-escaped.
Parameters:

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

HTTP GET example:
http://10.0.88.1/bridge?cmd=geturl&url=http%3A%2F%2Fwww.google.com.sg%2Fsearch&post=q%3Dabc (URI encoded, encode value of 'post' variable too)
(replace with NeTV's IP address)
Return:

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

Note:
The returned data is neither XML-escaped or URI-encoded by default.

SetUrl

Points the NeTVBrowser (tab 0) at a specified URL.
Parameters:

  • value = full url to a web resource

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

<xml>
   <cmd>SETURL</cmd>
   <status>1</status>
   
      <value>Command forwarded to NeTVBrowser</value>
   
</xml>

Note: There is a keep-alive timer in NeTVBrowser running at 1 minute interval to keep URL of tab 0 pointing at a local page (http://localhost/...)
See 'KeepAlive' command for more information.

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)

Scrolling:
Scrolling is done by setting the top-left offset position of the page.
Usually x-axis is kept at 0 and y-axis (vertical) is changed as the TV screen is wide enough to accommodate the content horizontally.
The scrolling position can be set in pixel coordinate or normalized fraction (0.0 to 1.0) with respect to the content width/height.
It is recommended to use UDP to fire this command rapidly per scroll event on mobile device.

  • tab = index of the tab (1 to 9)
  • options = 'scroll' (pixel coordinate) or 'scrollf' (normalized fraction 0.0-1.0)
  • param = 'xxx,yyy' (comma-separated x,y scrolling positions)

HTTP GET example:
http://10.0.88.1/bridge?cmd=multitab&tab=1&options=load&param=http%3A%2F%2Fwww.abc.com (URI encoded)
http://10.0.88.1/bridge?cmd=multitab&tab=1&options=scrollf&param=0.0%2C0.123 (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>

KeepAlive

Enable/disable keep-alive timer in NeTVBrowser
There is a keep-alive timer in NeTVBrowser running at 1 minute interval to keep URL of tab 0 pointing at a local page (http://localhost/...)
In other to have tab 0 run an external URL, there are 2 options:

  • Disable keep-alive timer
  • The page must contains JavaScript function "fCheckAlive();" that returns 'true'.

Parameters:

  • value = on/off

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

<xml>
   <cmd>KEEPALIVE</cmd>
   <status>1</status>
   
      <value>Command forwarded to NeTVBrowser</value>
   
</xml>

NeCommand

Execute any shell command and return the output as a string.
Full path to the executable must be provided. Arguments are space-separated.
Output value can be optionally XML-escaped.
Parameters:

  • (required) value = the shell command to execute
  • (optional) xmlescape = true/false

HTTP GET example:
http://10.0.88.1/bridge?cmd=necommand&value=%2Fbin%2Funame%20-a (URI encoded)
(replace with NeTV's IP address)
Return:

<xml>
   <cmd>NECOMMAND</cmd>
   <status>1</status>
   
      <value>......output of the shell command......</value>
   
</xml>
or
<xml>
   <cmd>NECOMMAND</cmd>
   <status>1</status>
   
      <value>no permission to execute</value>
   
</xml>

Note:
The returned data is neither XML-escaped or URI-encoded by default.

Retrieved from "https://kosagi.com/w/index.php?title=NeTV_web_services&oldid=9"