SOFTWARE API

The XANDEM gateway includes an API that allows software developers to build their own applications using the technology in their XANDEM systems. A web server running on the gateway responds to HTTP calls, allowing developers to change system settings and read/react to system outputs.

IMPORTANT: The XANDEM API is in beta, was recently updated, and may change at any time. The API will not work unless your system software version is 0.7.0 or greater and you must use API v2 or greater.

 

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 “v2”, the base URL for all API calls will be:

 

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

 

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}/v2/

 

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 an Authorization header with each request, e.g., 

 

Authorization: system-key:{API_KEY_HERE}

 

Note that there is a colon in the body of the header to designate the key as a “system-key”.

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, and navigate to the “SYSTEM” tab.
  3. Click the “CREATE NEW KEY” button.
  4. Name and save your key.
  5. Click the “VIEW” button to see your newly generated key.

Reading System Output


To read all available system outputs, you can make the following call:

GET http://xandem-{deviceID}/{apiVersion}/system/{deviceID}/outputs/

A JSON object containing all system outputs will be returned. To read a single specific output, make a call with to …output/{output_name}, e.g.,

GET http://xandem-{deviceID}/{apiVersion}/system/{deviceID}/output/is_motion

The API server will return the value of that specific output, e.g., “false” if there is no current motion.

The following is a list of read-only system outputs: 

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 Updating Settings

To read all available system settings, you can make the following call:

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

A JSON object containing all system settings will be returned.

To read a single specific setting, make a call to …setting/{setting_name}, e.g.,

GET http://xandem-{deviceID}/{apiVersion}/system/{deviceID}/setting/is_armed

The API server will return the value of that specific setting, e.g., “false” if the system is not currently armed. If you’d like to update a single setting, just change the HTTP method to PUT and include the value you’d like the setting to have in the body, e.g.,

PUT http://xandem-{deviceID}/{apiVersion}/system/{deviceID}/setting/is_armed

with “true” in the body to change is_armed to true.

You can also update one or more settings by making a PUT request to …settings/ with a JSON object in the body that includes the setting names as keys and the corresponding values, e.g.,

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

with a body like:

  {
"is_armed": true,
"motion_threshold": 3
}

Any PUT to the settings endpoints will return a JSON object containing the updated state of all settings. Below are the settings you can currently update via the API.

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.
Scroll to Top