Web API Reference

The Web APIs are RESTful APIs that allow access to a subset of gateway functions through a standard HTTP request.

xPico 240/250 provides the following APIs:

Device Actions API

File System API

  • HTTP GET - Read the contents of files and directories]
  • HTTP PUT - Create new files and update existing files
  • HTTP MKCOL - Create new directories
  • HTTP DELETE - Remove files and directories from the file system

Firmware Upgrade API

Device Actions API

The Device Actions API provide functions to export and import the configuration as well as to export status and take a status action.

These APIs specify a "-d [data]" and use an HTTP content-type of “application/x-ww-form-urlencoded”.

Export Status Group

An HTTP POST request can be sent to the device to retrieve status information.

  • Protocol: HTTP
  • Method: POST
  • Content-Type: application/x-ww-form-urlencoded
  • URL: http://<hostname>/export/status

Parameters:

  • optionalLine: Optional line index for line oriented XML groups
  • optionalGroupList: Optional list of XML groups separated by semicolon. If omitted, all status groups will be returned.

CURL example:

curl --digest -u admin:PASSWORD http://<ip-address>/export/status -X POST
curl --digest -u admin:PASSWORD http://<ip-address>/export/status -X POST -d "optionalGroupList=Device;Clock"

Javascript example:

myXmlhttprequest.open(
   "POST",
    "/export/status",
    true
);
request.send(
    "optionalGroupList=Device"
);

Export Configuration Group

An HTTP POST request can be sent to the device to retrieve configuration information.

  • Protocol: HTTP
  • Method: POST
  • Content-Type: application/x-ww-form-urlencoded
  • URL: http://<hostname>/export/config

Parameters:

  • optionalLine: Optional line index for line oriented XML groups
  • optionalGroupList: Optional list of XML groups separated by semicolon. If omitted, all configuration groups will be returned.
  • optionalBoolNonDefaultOnly: To retrieve only the configuration which is different from default, set this to “true”.

CURL example:

curl --digest -u admin:PASSWORD http://<ip-address>/export/config -X POST

curl --digest -u admin:PASSWORD http://<ip-address>/export/config -X POST -d "optionalGroupList=Interface:wlan0"

Javascript example:

myXmlhttprequest.open(
   "POST",
    "/export/config",
    true
);
request.send(
    "optionalGroupList= Interface:wlan0"
);

Import Configuration Group

An HTTP POST request can be sent to the device to set configuration.

  • Protocol: HTTP
  • Method: POST
  • Content-Type: multipart/form-data
  • URL: http://<hostname>/import/config

Parameters:

  • configrecord: Content of configuration group in XML format.

CURL example (configuration is saved in a local file config.xml):

curl --digest -u admin:PASSWORD http://<ip-address>/import/config -X POST --form configrecord=@config.xml

CURL example (configuration as part of command):

curl --digest -u admin:PASSWORD http://<ip-address>/import/config -X POST --form-string 'configrecord=<?xml version="1.0" standalone="yes"?>'
<!-- Automatically generated XML -->
<!DOCTYPE configrecord [
   <!ELEMENT configrecord (configgroup+)>
   <!ELEMENT configgroup (configitem+)>
   <!ELEMENT configitem (value+)>
   <!ELEMENT value (#PCDATA)>
   <!ATTLIST configrecord version CDATA #IMPLIED>
   <!ATTLIST configgroup name CDATA #IMPLIED>
   <!ATTLIST configgroup instance CDATA #IMPLIED>
   <!ATTLIST configitem name CDATA #IMPLIED>
   <!ATTLIST configitem instance CDATA #IMPLIED>
   <!ATTLIST value name CDATA #IMPLIED>
]>
<configrecord version = "0.1.0.1">
   <configgroup name = "Access Point" instance = "ap0">
      <configitem name = "SSID">
         <value>MY DEVICE</value>
      </configitem>
   </configgroup>
</configrecord>'

HTTP example:

<form method="post" enctype="multipart/form-data" action="/import/config" target="_blank">
    <input name="configrecord" type="file" size="32">
     <input name="submit" type="submit" value="Import Configuration">
 </form>

Take Status Action

An HTTP POST request can be sent to the device to take a status action.

  • Protocol: HTTP
  • Method: POST
  • Content-Type: application/x-ww-form-urlencoded
  • URL: http://<hostname>/action/status

Parameters:

  • group: Required. The status group where action is defined.
  • optionalGroupInstance: Optional instance of status group.
  • optionalItem: Optional item of status group where action is defined.
  • optionalItemInstance: Optional instance of status item.
  • action: Required. The action to be taken. See Actions Definitions for a list of the actions.

CURL example:

curl --digest -u admin:PASSWORD -X POST -d
"group=Interface&optionalGroupInstance=wlan0&action=Renew"
http://<hostname>/action/status

Javascript example:

myXmlhttprequest.open(
  "POST",
  "/action/status",
  true
);
request.send(
  "group=Interface&optionalGroupInstance=wlan0&action=Renew"
);

Actions Definitions

Action definitions related to the Take Status Action API.

NOTE: When you see "NULL" after optionalGroupInstance, optionalItem, or optionalItemInstance, it means that item or instance should be omitted.

Action Groups Index

group "Clock" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Current Time <YYYY-MM-DD hh:mm:ss>"

The format for setting time is YYYY-MM-DD hh:mm:ss, where the hours are in 24-hour format.


group "CPM" optionalGroupInstance NULL

group "CPM CPs" optionalGroupInstance NULL

optionalItem "CP" optionalItemInstance Required

The optionalItemInstance may range from 1 to 8.

action "Usage <value>"

<value> may be "Input", "Output" or "Unused".

action "Assert <value>"

<value> may be "High" or "Low".

Assert reflects the logical polarity of this Configurable Pin.

"High" means that a logical "1" corresponds to a voltage high condition on the pin.

"Low" means that a logical "1" corresponds to a voltage low condition on the pin.

action "Mode <value>"

<value> may be "Push-Pull" or "Weak Pullup".

5-Volt tolerance NOTE: In order to sustain a voltage higher than VDD+0.3, the Mode must be set to "Push-Pull".

action "Value <value>"

<value> may be "0" or "1".

Value is the logical value of the Configurable Pin. Its polarity depends on Assert.

"1" represents the "Asserted" state, "0" represents "Not asserted".


group "CPM Roles" optionalGroupInstance NULL

optionalItem "Role" optionalItemInstance Required

"AP Trigger" turns on ap0 if Mode is "Triggered" or "Initial Trigger".

"HTTP Server Trigger" turns on HTTP Server if Mode is "Triggered".

"Line 1 DSR" read by application.

"Line 1 DTR" set by application.

"Radio Trigger" turns on radio if Mode is "Triggered".

"SPI.CS" pin is used when SPI State is "Enabled".

"SPI.MISO" pin is used when SPI State is "Enabled".

"SPI.MOSI" pin is used when SPI State is "Enabled".

"SPI.SCK" pin is used when SPI State is "Enabled".

"User Data Updated" is active when user data changes, till Acknowledge action.

"WLAN Active" is active while wlan0 is up.

action "State <value>"

<value> may be "Inactive" or "Active".

If an input role has no CP assigned, the State may be manipulated via the CLI or Web Manager.


group "Device" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Save"

The Save action works like the "write" command. Any cached configuration changes are committed, so they will apply after a reboot.

Without a Save, any cached configuration changes are lost after a reboot.

optionalItem NULL optionalItemInstance NULL

action "Reboot"

The Reboot action shuts the device down and restarts it. Any cached configuration changes (those which have not been saved) are lost.

optionalItem NULL optionalItemInstance NULL

action "Factory Defaults"

The Factory Defaults action restores the device configuration as it came from the factory. Any user changes to configuration are lost.


group "File System" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Compact"

Compact reorganizes data on the flash file system, recovering dirty space. File data is retained. Note that this happens automatically when attempting to write and no clean space is available, but dirty space is.

optionalItem NULL optionalItemInstance NULL

action "Format"

Format clears out the flash file system, preserving only system configuration data. Be careful! All other files are destroyed.


group "Interface" optionalGroupInstance Required

The optionalGroupInstance may be "ap0", "eth0" or "wlan0".

optionalItem NULL optionalItemInstance NULL

action "Renew"

The Renew action causes the device to drop its dynamic IP address and request an address from the DHCP server.


group "Line" optionalGroupInstance Required

The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".

optionalItem NULL optionalItemInstance NULL

action "Command <value>"

The Command action sends bytes to the Line and picks up bytes in response. The bytes are hex encoded.

Maximum number of characters to read (n) may be specified; default is unlimited.

Milliseconds total time limit (m) may be specified; default is 1000.

Terminating byte (t) may be specified; default is <None>.

Syntax of <value> is:
[n=<decimal number> ][m=<decimal number> ][t=<hex number> ]<hex bytes to send>

First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.

optionalItem "Receiver" optionalItemInstance NULL

action "Receive"

The Receive action picks up characters from the Line.

First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.

action "Hex Receive"

The Hex Receive action picks up bytes from the Line.

First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.

optionalItem "Transmitter" optionalItemInstance NULL

action "Transmit <value>"

The Transmit action sends characters to the Line.

First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.

action "Hex Transmit <value>"

The Hex Transmit action sends bytes to the Line.

First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.


group "WLAN" optionalGroupInstance Required

optionalItem NULL optionalItemInstance NULL

action "Directed scan <SSID>"

No help available.

optionalItem NULL optionalItemInstance NULL

action "Broadcast scan"

No help available.


group "Bluetooth" optionalGroupInstance NULL

group "Bluetooth Classic" optionalGroupInstance NULL

group "Bluetooth Classic Master" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Forget <MAC>"

Removes the specified MAC.

optionalItem NULL optionalItemInstance NULL

action "Directed scan <MAC>"

Scans for the specified MAC.

optionalItem NULL optionalItemInstance NULL

action "Broadcast scan"

Scans for all MACs within range.

optionalItem NULL optionalItemInstance NULL

action "Connect <MAC>[ <passphrase>]"

Connects to the specified MAC.




group "CLI Server" optionalGroupInstance NULL

optionalItem "Telnet" optionalItemInstance NULL

action "Kill"

The Kill action manually disconnects the active CLI Server connection.


group "Modem Emulation" optionalGroupInstance Required

The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".

optionalItem "Current Connection" optionalItemInstance NULL

action "Kill"

The Kill action manually disconnects an active Modem Emulation connection.


group "Monitor" optionalGroupInstance NULL

optionalItem "Control" optionalItemInstance Required

action "Send"

The Send action causes the device to send the associated control message.


group "NTP" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Sync"

The Sync action requests immediate clock synchronization with the NTP server.


group "SMTP" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Send <value>"

Note: The Send action is not available to the web API.

Example usage:

Send <ssl server hostname>  
<username>  
<password>  
<from mail address>  
<first recipient mail address>  
[optional second recipient mail address]  
[...] <-- Empty line ends recipient list  
<subject>  
<first line of body>  
[optional second line of body]  
[...] <-- Empty line ends body

group "Tunnel" optionalGroupInstance Required

The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".

optionalItem "Current Connection" optionalItemInstance Required

Possible instance names are "Accept" and "Connect <n>", where <n> is the Host number, for example "Connect 1".

action "Kill"

The Kill action manually disconnects an active Tunnel connection.


group "Custom" optionalGroupInstance NULL

optionalItem NULL optionalItemInstance NULL

action "Acknowledge"

The Acknowledge action deasserts the "User Data Updated" CP until the next configuration change.


File System Web API

The File System Web API is a RESTful cloud API which allows basic manipulation of file system nodes (files and directories). It is intended to support web-based file system access without the need of a browser, and as such can be used in scripts with HTTP programs such as cURL.

Supported file system node operations are implemented via various HTTP request types. The File System Web API uses standard HTTP requests as well as HTTP extensions from the Web Distributed Authoring and Versioning (WebDAV) standard.

Four principal HTTP requests are implemented by the API: GET, PUT, MKCOL, and DELETE.

HTTP GET

Used to obtain, or “read”, the contents of files and directories in the file system.

URL: http://<hostname>/fs/[node]

Where node can be a file, in which case the file content is returned; or a directory, in which case an XML-formatted list of directory objects is returned.

HTTP Response Codes:

  • 200: Success
  • 404: Node not found

Example:

# curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/embedded
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = directory>
    <name>main</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>modem_emulation</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>monitor</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>ntp</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>query_port</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>tunnel</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>user_data</name>
    <size>0</size>
  </dentry>
</directorylist>

HTTP PUT

Used to place new files in the file system and update existing files. Directories cannot be created using PUT; the MKCOL request must be used.

Note that PUT will overwrite an existing file by the same name.

URL: http://<hostname>/fs/[path]/file

HTTP Response Codes:

  • 201: File successfully created. This code is part of the WebDAV standard.
  • 509: Not enough space
  • 500: Other failure

Example:

> ls -l
-rw-r--r-- 1 user wheel     166 Oct 22  2013 file.txt

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/ -T file.txt

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = file>
    <name>file.txt</name>
    <size>166</size>
  </dentry>
</directorylist>

HTTP MKCOL

Used to create new directories (not files) in the file system. MKCOL (“make collection”) is an HTTP extension from the WebDAV standard.

URL: http://<hostname>/fs/[path]/directory

HTTP Response Codes:

  • 201: Directory successfully created. This code is part of the WebDAV standard.
  • 409: Directory already exists
  • 500: Other failure

Example:

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/dir1 -X MKCOL

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = file>
    <name>file.txt</name>
    <size>166</size>
  </dentry>
  <dentry type = directory>
    <name>dir1</name>
    <size>0</size>
  </dentry>
</directorylist>

HTTP DELETE

Used to remove files and directories from the file system.

URL: http://<hostname>/fs/[path]/node

Where node can be either a file or directory.

HTTP Response Codes:

  • 204: No content (node successfully removed). This code is part of the WebDAV standard.
  • 404: Node not found
  • 500: Other failure

Example:

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/file.txt -X DELETE

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = directory>
    <name>dir1</name>
    <size>0</size>
  </dentry>
</directorylist>

Firmware Upgrade API

The firmware upgrade API allows the device to upgrade the firmware image. The request format emulates a filled-in form to produce a POST request with an HTTP content-type of “multipart/form-data”.

This differs from the status/configuration APIs, which specify a "-d [data]" and use an HTTP content-type of “application/x-ww-form-urlencoded”, or the File System APIs, which use standard HTTP requests and HTTP extensions from WebDAV.

Firmware Upgrade

  • Description: Load the firmware image file
  • Protocol: HTTP
  • Method: POST
  • Content Type: multipart/form-data
  • URL: http://<hostname>/upgrade

Parameters:

  • imageFile: Name of the file containing the upgrade image.

HTTP Response Codes:

  • 200: Success
  • 507: Invalid partition size
  • 500: All other failures

CURL example:

curl --digest –u admin:PASSWORD –X POST http://<hostname>/upgrade -F imageFile=@xPico200_1.6.0.0R58