BuildAX LRS Developer API

The BuildAX LRS can be programatically configured via a remote connection. API calls to the BuildAX LRS are made as RESTful HTTP requests. For you, this means that setting state on the LRS is performed via POST requests, and GET requests are used to retrieve data.

The examples in this document use the wget command to communicate with the web server on the BuildAX LRS. On Linux wget is usually installed by default, but can be downloaded for other OSes (including MacOSX and Windows) from the GNU website.

An equivalent software with much the same functionality as wget is curl, which may be used in preference to wget.

Logging In

The Web API uses a unique session key (a cookie) to authenticate users. All API sessions start when this session key is requested by making a POST request to the BuildAX LRS.

The user agent must first authenticate with the LRS and obtain a session cookie before further REST API requests can be made:

Method	Resource	Parameters	Response
POST	/WWW/login.htm	user, pass	303 redirect with SID= session cookie.

Example wget command (a backslash is used to separate the command onto multiple lines):

    wget --save-cookies cookies.txt \
        --delete-after \
        --no-http-keep-alive \
        --post-data 'user=admin&pass=password' \
        --keep-session-cookies \
        http://your-bax/WWW/login.htm

Equivalent curl command:

    curl --silent --output /dev/null \
        -c cookies.txt \
        --data 'user=admin&pass=password' \
        http://your-bax/WWW/login.htm

Changing Settings

Settings are passed to the server in the same format as the text command mode. Please refer to the LRS commands for a full description of the settings commands which may be sent to the LRS.

Settings can be concatenated with an ampersand (&) in the POST body to change multiple settings simultaneously.

Method	Resource	Parameters	Response
POST	/WWW/a_settng.htm	Setting arguments in the format specified above	200 OK Set-Cookie: update=ok

wget --load-cookies cookies.txt \
    --post-data 'setting.usb.stream=0' \
    http://your-bax/WWW/a\_settng.htm

Valid settings types are: file, usb, telnet, and udp.

Fetching Data

Data fetching is performed via GET request, so parameters are passed in the URL.

http://your-bax/fetch?type=BT&start=449622000&end=485434800

There are three parameters in a fetch request: a type, and the start/end range specifiers.

Method	Resource	Valid Parameters	Response
GET	/fetch	type, start, end	200 OK (and download)

Fetch Types

The type parameter may be specified as one of the following:

Type	Fetch mode
BT	Binary / Time range fetch
TT	Text / Time
BF	Binary / File
TF	Text / File
BS	Binary / Sample range (note: text/sample range is not implemented)
LS	Last N Samples (note: specify an empty 'end' parameter with this request)

Fetch Parameters

The parameters start and end are always present, but their value changes based on the type of request.

Fetch Type	Range specifiers
Time Range	Start and end are specified in seconds after the epoch 2000-01-01 matching the RTC timestamp
File Range	Start and end are data file numbers as stored on the external flash card storage
Sample Range	Start and end are a range of packets numbers received from the sensors
Last N Samples	Start is the number of most recent samples. Specify end as an empty string.

Time Format

To calculate the time range, take the Unix timestamp for the time required (a standard time representation) and subtract the Unix timestamp for the date 2000-01-01. Eg:

    Current Unix Time – (2000-01-01 00:00) = BuildAX RTC Timestamp
           1407940334 –      946684800     = 461255534

The reason for this difference is that the hardware real-time-clock (RTC) on the BuildAX LRS works with an epoch of the year 2000 and a 32-bit timestamp, meaning dates up to 2068 can be represented internally.

Example wget commands

Login: Remember that you must first run the Login command to get a session cookie!

Get data file 0 from the SD card (no more than 5 files (10MB) may be requested in one download):

wget --load-cookies cookies.txt \
    --no-http-keep-alive \
    --content-disposition \
    http://your-bax/fetch?type=BF\&start=0\&end=0

Get last 500 samples:

wget --load-cookies cookies.txt \
    --no-http-keep-alive \
    --content-disposition \
    http://your-bax/fetch?type=LS&start=500&end=

Get data within a time range:

wget --load-cookies cookies.txt \
    --no-http-keep-alive \
    --content-disposition \
    http://your-bax/fetch?type=BT\&start=449622000\&end=485434800

One possible 'gotcha' is that the ampersand (&) symbol has a special meaning in most command terminals, and must be escaped with a backslash (as in the above examples) so that the command is not forked.

Generic Commands

In addition to the commands listed above, some commands listed in the LRS Commands section can be sent using this interface.

Method	Resource	Valid Parameters	Response
POST	/cmd	LRS command	200 OK (even if the command failed)

A specific limitation of this HTTP interface is that it is not currently possible to include feedback from this command in the HTTP response. The server will return the response code, along with an empty response body. This means that commands (e.g. status) which are only useful for their response will not be useful to call through this interface. Commands which perform some action (e.g. save) are the use case for this feature.

Example:

http://your-bax/cmd?save

Additionally, HTTP special characters will not be parsed correctly until firmware v1.4. This will make it possible to set the RTC time via the REST interface.