SOFTWARE API

IMPORTANT: The XANDEM API is in beta and may change at any time. The API will not work unless your system software version is 0.1.21 or greater.

The XANDEM gateway includes an API that allows software developers to build their own applications using XANDEM data. The API uses a RESTful architecture - a web server running on the gateway responds to calls that are made over HTTP.

The base URL

The base URL for all calls looks like this:

http://xandem-{deviceID}/{apiVersion}/

where {deviceID} and {apiVersion} are filled in with your systems device ID and the API version that you are using. For example, if the device ID is "ABC", and the API version is "v1", the base URL for all API calls will be:

http://xandem-ABC.local/v1/

Alternatively, you can use the IP address of the gateway for the base URL. For example, if you are using API version v1, the base URL would be:

http://{local IP address of gateway}/v1/

Some routers don't support local domains, so using the IP address may be necessary to access the API. You may want to assign a static IP address to the XANDEM gateway in your router settings to avoid having it change after power cycles.

API keys and authorization header

All API calls must be authorized by including an API key in the header of the requests. The name of the header is "Authorization."

Authorization: {API_KEY_HERE}

To generate an API key for your application, do the following:

  1. Log in to the XANDEM gateway user interface at http://xandem-{deviceID}.local/.
  2. Go to the settings page, then go to the "SECURITY" tab.
  3. Click "Create New API Key."
  4. Name and save your key.
  5. Click "view" to see your newly generated key.

Reading data

The data request URL is:

http://xandem-{deviceID}/{apiVersion}/data

To read data:

  1. Create a JSON object with key data_fields and an array of strings indicating which data fields you would like to read. The data field options are listed below.
  2. Send the JSON object as the body of an http POST request to the data request URL listed above. Include an Authorization: {API_KEY_HERE} header for authentication.
  3. The server will return the values for the requested data fields in a response JSON object.

Example of requesting Data

Let's say you'd like to pull the 'motion_score' and 'motion_coordinates' from the system. The header of the POST request will look like this:

Authorization: {API_KEY_HERE}

The JSON object body of the POST request will look like this:

{ "data_fields": ["motion_score", '"motion_coordinates"] }

The POST request should be sent to:

http://xandem-{deviceID}/{apiVersion}/data

The response from the API server might look like this:

{ "motion_score": 6.28, "motion_coordinates": [3.22, 8.09, 0.0] }

Your application can then parse the response JSON object and use the requested data.

Data fields

The following is a list of read-only data fields that are available.

DATA FIELD DESCRIPTION
motion_score Returns how much motion is happening over the entire detection area as a single numerical value. Higher values indicate larger amounts of motion. For example, a crowd of people within the area will cause the motion score to be consistently high, while a single individual will only reach lower values and will be "bursty."
motion_coordinates Returns an array of [x,y,z] coordinates, indicating where people are most likely to be moving. Only one tracking coordinate will be returned in this version, but future updates to the system will enable multiple sets of coordinates. 3D tracking is not yet available, so the z-coordinate will always be 0 until an update enables this functionality.
is_motion Returns a boolean value of true or false. If true, motion is currently happening within the detection area. If false, no motion is currently happening.
node_outages Returns an array indicating which (if any) nodes are offline. Each value is 0 if the corresponding node is online, and 1 if there is an outage.
is_node_out Returns true if any node is offline, false otherwise.
node_voltages Returns an array of numbers indicating the voltage level at each node. With DC nodes, all input voltages to the nodes are regulated down to 3.3V, and power is considered critically low at 2.0V. Please see the hardware section for input power specifications.
node_connectivity Returns an array of numbers ranging 0.0 to 1.0 that indicates each node's wireless connectivity. The higher the number, the better the node is connecting to the rest of the network, including the gateway.
last_motion Returns the last time motion was detected in seconds using POSIX (Epoch) format.

 

Reading and writing settings

Reading the settings of the system is done in the same way as a data request. The settings URL is:

http://xandem-{deviceID}/{apiVersion}/settings

Reading current settings

To read settings:

  1. Create a JSON object with key setting_fields and an array of strings indicating which settings you would like to read. The setting field options are listed below.
  2. Send the JSON object as the body of an http POST request to the settings URL listed above. Include an Authorization: {API_KEY_HERE} header for authentication.
  3. The server will return the values for the requested fields in a response JSON object.

Writing settings

To write settings, use the following procedure:

  1. Create a JSON object where the setting you would like to change are listed as key/value pairs.
  2. Send the JSON object as the body of an http PUT (NOT POST) request to the settings URL listed above. Include an Authorization: {API_KEY_HERE} header for authentication.
  3. The server will echo back a JSON listing of the current settings so that you can be sure the change was made. Error messages will be sent in the appropriate JSON item if an error has occurred.

For example, let's say you would like to change the motion sensitivity threshold to 5.0. You would send the following JSON object as the body of a PUT to the settings URL.

{ "motion_threshold": 5.0 }

The server will return a JSON object containing either a success or error messages.

Settings fields

SETTING FIELD DESCRIPTION
is_armed A boolean indicating if the system is currently armed. If true, the system is armed. If false, the system is disarmed.
node_locations A 2D array of the node locations in the format [[x1, y1], [x2, y2], ..., [xN, yN]], where [xN, yN] is the x,y coordinate of the Nth node. The length must be equal to the number of nodes. All x and y must be between -100 and 100.
map_lines An array of line objects. Each line object has 4 numerical values: [x1, x2, y1, y2], where the line goes from coordinate (x1,y1) to (x2,y2). All x,y values must be between -100 and 100.
motion_threshold A numeric value (integer or float) indicating the current motion detection sensitivity threshold. When the motion_score is above this threshold, is_motion is 1, and when motion_score is below this threshold, is_motion is 0. Valid range is 1 to 100.