NeTV web services

From Chumby Wiki
Revision as of 08:01, 22 October 2011 by Torin (Talk | contribs)

Jump to: navigation, search

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]

Variables can now be POST directly as normal POST variable (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.

Commands

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>

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>

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

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>

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&ticker_speed=1&ticker_ypos=123
(replace with NeTV's IP address)
Return:

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

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>


TCP/UDP API

The NeTV TCP/UDP API provides a mechanism to interact with NeTV through socket interface.
For UDP messages, the client can either choose to use either broadcast or unicast. However, the reply from NeTV is always unicast.

  • TCP socket port 8081 (Flash AS3 socket <-> NeTV)
  • UDP Socket port 8082 (Android/iOS client <-> NeTV)

All commands & parameters are identical to HTTP API, except the they have to be wrapped in XML format


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

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

One parameter

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

Many parameters

<xml>
   <cmd>SetParam</cmd>
   <data>
      <myKey1>myValue1</myKey1>
      <myKey2>myValue2</myKey2>
   </data>
</xml>