Difference between revisions of "NeTV web services"

From Chumby 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...")
 
Line 11: Line 11:
 
<br>
 
<br>
 
<br>
 
<br>
More complex commands can be constructed as a POST Request as follow.
+
<span style="color:#808080">
* POST to: http://localhost/bridge or http://xxx.xxx.xxx.xxx/bridge
+
More complex commands can be constructed as a POST Request as follow.<br/>
* '''Content-Type''' must be set to application/x-www-form-urlencoded
+
- POST to: http://localhost/bridge or http://xxx.xxx.xxx.xxx/bridge<br/>
* variable '''cmd''' : command name, case insensitive
+
- '''Content-Type''' must be set to application/x-www-form-urlencoded<br/>
* variable '''data''' : optional variable to submit arguments with the command, formatted as a XML string
+
- variable '''cmd''' : command name, case insensitive<br/>
 +
- variable '''data''' : optional variable to submit arguments with the command, formatted as a XML string<br/>
 
<br>
 
<br>
 +
Example: to send a remote control key command (single parameter)<br/>
 +
- cmd=RemoteControl<br/>
 +
- data=<value>right</value><br/>
 +
Example: to send a TickerEvent command (multiple parameters)<br/>
 +
- cmd=TickerEvent<br/>
 +
- data=<message>abcdefghifk</message><title>blahblah</title><image>full url to an image<image><br/>
 +
</span>
 +
<span style="color:#FF0000">[The above format is deprecated]</span><br/><br/>
 +
Variables can now be POST directly as normal POST variable (must be URI-encoded).<br/>
 
Example: to send a remote control key command (single parameter)
 
Example: to send a remote control key command (single parameter)
 
* cmd=RemoteControl
 
* cmd=RemoteControl
* data=<value>right</value>
+
* value=right
 
Example: to send a TickerEvent command (multiple parameters)
 
Example: to send a TickerEvent command (multiple parameters)
 
* cmd=TickerEvent
 
* cmd=TickerEvent
* data=<message>abcdefghifk</message><title>blahblah</title><image>full url to an image<image>
+
* message=abcdefghifk
<br>
+
* title=blahblah
 +
* image=full url to an image
 +
<br/>
 +
<br/>
 
The full list of command & arguments is available below.  
 
The full list of command & arguments is available below.  
<br>
+
<br/>
 
= Return format =
 
= Return format =
 
The return format is a XML string in the following format
 
The return format is a XML string in the following format
Line 43: Line 56:
 
= Command table =
 
= Command table =
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
! Command (cmd) !! Data (data) !! return value
+
! Command (cmd) !! Parameters!! return value
 
|-
 
|-
 
| Hello || - ||  
 
| Hello || - ||  
Line 74: Line 87:
 
   <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>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>
 
   <wifi><ssid>ChumbyWPA</ssid><qty>50/70</qty><lvl>-60</lvl><ch>1</ch><mode>Master</mode><encryption>AES</encryption><auth>WPA2PSK</auth></wifi>
</data>
 
</xml>
 
</pre>
 
|-
 
| HasFlashPlugin || - ||
 
<pre>
 
<xml>
 
<cmd>HASFLASHPLUGIN</cmd>
 
<status>...</status>
 
<data>
 
  <value>true/false</value>
 
 
</data>
 
</data>
 
</xml>
 
</xml>
Line 91: Line 93:
 
| RemoteControl ||  
 
| RemoteControl ||  
 
<pre>
 
<pre>
<value>
+
value=cpanel/widget/up/down/left/right/center (pick one)
  cpanel/widget/up/down/left/right/center
+
<value>
+
 
</pre>
 
</pre>
 
  ||  
 
  ||  
Line 108: Line 108:
 
| FileExists ||  
 
| FileExists ||  
 
<pre>
 
<pre>
<value>
+
value=full path to a local file
  full path to a local file
+
</value>
+
 
</pre>
 
</pre>
 
  ||
 
  ||
Line 125: Line 123:
 
| GetParam ||  
 
| GetParam ||  
 
<pre>
 
<pre>
<value>
+
value=name of the parameter
  key name including group prefix if any
+
</value>
+
 
</pre>
 
</pre>
 
  ||
 
  ||
Line 142: Line 138:
 
| SetParam ||
 
| SetParam ||
 
<pre>
 
<pre>
<myKey1>myValue1</myKey1>
+
myKey1=myValue1
<myKey2>myValue2</myKey2>
+
myKey2=myValue2
<myGroup1/mySubKey1>myValue2</myGroup1/mySubKey1>
+
myKey3=myValue3
<myGroup2/mySubKey2>myValue2</myGroup1/mySubKey2>
+
 
...
 
...
 
</pre>
 
</pre>
Line 158: Line 153:
 
</xml>
 
</xml>
 
</pre>
 
</pre>
|-
 
 
|-
 
|-
 
| TickerEvent ||
 
| TickerEvent ||
 
<pre>
 
<pre>
<message>..............</message>
+
message=......
<title>......(optional)</title>
+
title=......(optional)
<image>......(optional)</image>
+
image=......(optional)
<type>system/widget (optional)</type>
+
type=system/widget (optional)
<level>critical/medium/low/default (optional)</level>
+
level=critical/medium/low/default (optional)
 
</pre>
 
</pre>
 
  ||  
 
  ||  
Line 188: Line 182:
 
* TCP socket port 8081 (Flash AS3 socket <-> NeTV)
 
* TCP socket port 8081 (Flash AS3 socket <-> NeTV)
 
* UDP Socket port 8082 (Android/iOS client <-> NeTV)
 
* UDP Socket port 8082 (Android/iOS client <-> NeTV)
All commands are identical to HTTP API, except the '''cmd''' and '''data''' variables are now wrapped in the XML as well<br>
+
All commands & parameters are identical to HTTP API, except the they have to be wrapped in XML format<br>
  
 
<br>
 
<br>
Line 214: Line 208:
 
       <myKey1>myValue1</myKey1>
 
       <myKey1>myValue1</myKey1>
 
       <myKey2>myValue2</myKey2>
 
       <myKey2>myValue2</myKey2>
      <myGroup1/mySubKey1>myValue2</myGroup1/mySubKey1>
 
      <myGroup2/mySubKey2>myValue2</myGroup1/mySubKey2>
 
 
   </data>
 
   </data>
 
</xml>
 
</xml>
 
</pre>
 
</pre>

Revision as of 02:39, 20 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]

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



The full list of command & arguments is available below.

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

Command table

Command (cmd) Parameters return value
Hello -
<xml>
<cmd>HELLO</cmd>
<status>...</status>
<data>
   <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>
   <flashplugin>0 or version number of flash plugin</flashplugin>
   <flashver>0 or version number of flash player</flashver>
   <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>
</data>
</xml>
WifiScan -
<xml>
<cmd>WIFISCAN</cmd>
<status>...</status>
<data>
   <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>
</data>
</xml>
RemoteControl
value=cpanel/widget/up/down/left/right/center (pick one)
<xml>
<cmd>REMOTECONTROL</cmd>
<status>...</status>
<data>
   <value>echo of the actual button name received</value>
</data>
</xml>
FileExists
value=full path to a local file
<xml>
<cmd>FILEEXISTS</cmd>
<status>...</status>
<data>
   <value>true/false</value>
</data>
</xml>
GetParam
value=name of the parameter
<xml>
<cmd>GETPARAM</cmd>
<status>...</status>
<data>
   <value>new value to be set</value>
</data>
</xml>
SetParam
myKey1=myValue1
myKey2=myValue2
myKey3=myValue3
...
<xml>
<cmd>SETPARAM</cmd>
<status>...</status>
<data>
   <value>number of keys received</value>
</data>
</xml>
TickerEvent
message=......
title=......(optional)
image=......(optional)
type=system/widget (optional)
level=critical/medium/low/default (optional)
<xml>
<cmd>TICKEREVENT</cmd>
<status>...</status>
<data>
   ...queue size? ETA? (TBD)...
</data>
</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>