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

Export Status Group - Retrieve device status
Export Configuration Group - Retrieve device configuration
Import Configuration Group - Import device configuration
Take Status Action - Take device status action

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

Upgrade Firmware - Load firmware file to gateway

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.

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>