NeTV web services

= 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= right Example: to send a TickerEvent command (multiple parameters) - cmd=TickerEvent - data= abcdefghifk blahblah  full url to an 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) Example: to send a TickerEvent command (multiple parameters) = Generic return format = The return format is a XML string in the following format .....    ........
 * cmd=RemoteControl
 * value=right
 * cmd=TickerEvent
 * message=abcdefghifk
 * title=blahblah
 * image=full url to an image


 * 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: 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.
 * 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].

= 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 -o remount,rw / cd /usr/share/netvserver/docroot/scripts touch myscript.sh chmod +x myscript.sh uname -a chumby_version -f echo "\$1 = $1" echo "\$2 = $2" echo "\$3 = $3" echo "num = $#" 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
 * Mount read-write, create a script file, make it executable
 * Make your script do something useful. Example:
 * 1) !/bin/bash
 * 1) you can really kill yourself too
 * 2) killall NeTVServer
 * 3) reboot
 * Execute it from HTTP interface http://10.0.88.1/scripts/myscript.sh?param1=aaaaaa&param2=bbbbbb&param3=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. 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 Hello One parameter RemoteControl Multiple parameters Hello
 * TCP socket on port 8081
 * UDP socket on port 8082

SetParam

= 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: 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: HELLO 1 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
 * (optionals) type = netvbrowser/android/iphone/ipad/ipod/desktop
 * (optionals) version = some version number

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: WIFISCAN 1

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: HTTP GET example: http://10.0.88.1/bridge?cmd=setchromakey&value=off (replace with NeTV's IP address) Return: SETCHROMAKEY 1
 * value = on/off (pick one)

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: 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: ENABLESSH 1
 * (optional) value = start-chumby/stop/reload/force-reload/restart (pick one)
 * (optional) xmlescape = true/false

RemoteControl
Simulates an infra-red remote control button event. Parameters: HTTP GET example: http://10.0.88.1/bridge?cmd=remotecontrol&value=left (replace with NeTV's IP address) Return: REMOTECONTROL 1
 * value = cpanel/widget/up/down/left/right/center (pick one)

Key
Simulates a single keyboard event on NeTVBrowser (and other connected TCP clients). Parameters: 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: KEY 1
 * value = cpanel/widget/up/down/left/right/center/[a-z]/[0-9]/home/end/delete/pgup/pgdown/punctuations/... (pick one)

FileExists
Checks whether a file exists in local filesystem. Parameters: HTTP GET example: http://10.0.88.1/bridge?cmd=fileexist&value=%2Fpsp%2Fnetwork_config (URI encoded) (replace with NeTV's IP address) Return: FILEEXISTS 1
 * value = full path to a local file

GetFileContents
Returns the content of a file in local filesystem. Output value can be optionally XML-escaped. Parameters: HTTP GET example: http://10.0.88.1/bridge?cmd=getfilecontents&value=%2Fpsp%2Fnetwork_config (URI encoded) (replace with NeTV's IP address) Return: GETFILECONTENTS 1 or    GETFILECONTENTS 2 Note: The returned data is neither XML-escaped or URI-encoded by default.
 * (required) value = full path to a local file
 * (optional) xmlescape = true/false

GetFileSize
Returns the size of a file in local filesystem. Parameters: HTTP GET example: http://10.0.88.1/bridge?cmd=getfilesize&value=%2Fpsp%2Fnetwork_config (URI encoded) (replace with NeTV's IP address) Return: GETFILESIZE 1 or    GETFILESIZE 2
 * value = full path to a local file

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: 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: UNLINKFILE 1 or     UNLINKFILE 2
 * value = full path to a local file

UploadFile
Use HTML form to POST a file to any where in NeTV's filesystem. Only traditional HTML 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:     A demo page is available at http://10.0.88.1/html_test/index.html HTTP GET example: (GET is not supported) Return: UPLOADFILE 1 or    UPLOADFILE 2 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: HTTP GET example: http://10.0.88.1/bridge?cmd=getparam&value=ticker_speed (replace with NeTV's IP address) Return: GETPARAM 1
 * value = name of the parameter

GetParams
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: HTTP GET example: http://10.0.88.1/bridge?cmd=getparam&value=myparam1%3Bmydata%3Banotherone (URI encoded) (replace with NeTV's IP address) Return: GETPARAMS 1
 * value = name of the parameters, comma seperated

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: 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: SETPARAM 1 Note: There was a bug in firmware earlier than 20. Please prefix parameter names with 'dataxml_' Firmware 20 and newer does not require this.
 * (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

TickerEvent
Shows a ticker message crawling across the screen. Parameters: 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: TICKEREVENT 1 or    TICKEREVENT 2
 * (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

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: 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: GETURL 1 Note: The returned data is neither XML-escaped or URI-encoded by default.
 * (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

SetUrl
Points the NeTVBrowser (tab 0) at a specified URL. Parameters: 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: SETURL 1 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.
 * value = full url to a web resource

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: Hide vs Close: Using 'hide' and 'hideall' option will leave the tab running in the background while showing other tabs. Using 'close' and 'closeall' option will destroy the tab and free its memory. Note: tab 0 cannot be closed. Parameter 'tab' is not used for 'hideall' & 'closeall' option. 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. 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: MULTITAB 1 or    MULTITAB 2
 * (required) tab = index of the tab (1 to 9)
 * (required) options = load/show/hide/hideall/close/closeall/html
 * (optional) param = [full url to load if options==load] or [raw html syntax if options==html] (URI encoded)
 * 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)

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: Parameters: HTTP GET example: http://10.0.88.1/bridge?cmd=keepalive&value=off (replace with NeTV's IP address) Return: KEEPALIVE 1
 * Disable keep-alive timer
 * The page must contains JavaScript function "fCheckAlive;" that returns 'true'.
 * value = on/off

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: 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: NECOMMAND 1 or    NECOMMAND 1 Note: The returned data is neither XML-escaped or URI-encoded by default.
 * (required) value = the shell command to execute
 * (optional) xmlescape = true/false

GetDocroot
Returns the current absolute path to docroot folder of control panel. From firmware 22 onwards, the control panel UI is pulled from a git repo to /media/storage/docroot every time NeTVBrowser starts/restarts. NeTVServer will switch to this path if the git pull succeeded. Otherwise, it will fallback to /usr/share/netvserver/docroot as usual. This will enable us to quickly fix any bugs in the Control Panel without having to perform big a firmware update. Parameters: (no parameters) HTTP GET example: http://10.0.88.1/bridge?cmd=getdocroot (replace with NeTV's IP address) Return: GETDOCROOT 1 Note: Although the Control Panel UI is now located in /media/storage/docroot, basic life support stuffs such as the Update UI, WiFi config UI, supporting shell scripts are still located in /usr/share/netvserver/docroot.

SetDocroot
Full path to the new docroot folder. The docroot folder must minimality contains an index.html as the starting point. Parameters: HTTP GET example: http://10.0.88.1/bridge?cmd=setdocroot&value=%2Fmedia%2Fstorage%2Fmydocroot (URI encoded) (replace with NeTV's IP address) Return: SETDOCROOT 1 Note: Although the Control Panel UI is now located in /media/storage/docroot, basic life support stuffs such as the Update UI, WiFi config UI, supporting shell scripts are still located in /usr/share/netvserver/docroot. It is NOT necessary to copy over those files to the new docroot folder.
 * value = absolute path to a local docroot folder.