Southbound API Reference
Programmable Asset Tracker Private Beta
The Twilio Programmable Asset Tracker is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until the Programmable Asset Tracker reaches General Availability (GA) release.
The Programmable Asset Tracker operates in conjunction with two REST APIs. One, the “Northbound” API, is essentially a template: it describes the API that the Asset Tracker expects to communicate with when it contacts a remote server to upload data. The other, the “Southbound” API, is hosted by the Asset Tracker’s cloud-resident companion app and is used to update the device’s settings remotely.
This guide focuses on the Southbound API. It also describes the structure of the configuration data relayed by the API. This structure is defined by the Asset Tracker application, not the API, but because they are used alongside each other, we have documented them together.
What follows covers the ‘standard’ Southbound API — the API defined by the open source Asset Tracker application Twilio provides. However, because the API is defined by the application, and the application is completely customizable by you, you can if you wish adjust, extend, and even replace theSouthbound API if you wish. The standard API gets you started, but it may be just the first step on your Asset Tracker development journey.
Default settings
Many of the numerical default settings, particularly those related to wake times and reporting, have been selected for testing purposes and so will not necessarily provide the Asset Tracker with an optimal battery life. In most real-world deployments these values will be set larger to increase battery life.
How to access the API
The URL
Every Asset Tracker has its own cloud companion application, called its “agent“. Every agent is accessible at a unique URL. You access the Southbound API for a given device at its agent’s configuration URL:
https://agent.electricimp.com/<unique_agent_ID>/cfg
The agent’s ID is set by the system and can be read in code or viewed in the impCentral online IDE.
You can use whichever tool you prefer to interact with the API, but for this guide we’ll be using the command line tool curl
.
Authentication
The Southbound API uses Basic authentication. The value used as the authentication credential is the string <username>:<password>
and is provided in an Authentication
HTTP request header:
Authentication: Basic <username>:<password>
You set the Asset Tracker’s Southbound API access credentials using impCentral IDE environment variables, which are compiled into your application when you build and deploy a new version. Neither environment variable has a default value and so are mandatory:
CFG_REST_API_USERNAME
CFG_REST_API_PASSWORD
Requests made to the Southbound API will fail with HTTP status code 401
if they fail authentication, because either invalid or no credentials were supplied.
To learn how to set environment variables in impCentral, the Electric Imp online IDE and device management console, please see the Electric Imp Dev Center.
The API
The Southbound API supports two HTTP request methods, GET
and PATCH
. The former is used to retrieve a Asset Tracker’s current configuration, the latter to update some or all of the settings. In each case, data is sent to the API and received from it in JSON form.
Method | Success Code | Failure Code(s) | Description |
---|---|---|---|
GET |
200 | 401 — Authentication failure | Requests and returns the Asset Tracker’s current configuration in JSON format |
PATCH |
200 | 400 — Invalid configuration 401 — Authentication failure |
Updates some or all of the Asset Tracker’s current configuration |
How to update a Asset Tracker’s configuration
When the Asset Tracker’s agent receives new settings via a PATCH
request sent to its Soundbound API, it validates the proposed update: malformed JSON will be rejected as will unrecognized keys, values of the wrong type, and missing object dependencies, such as a latitude value but no accompanying longitude.
If the update is acceptable, the agent applies any changes made to its own configuration, persists its new configuration, and stages any changes made to the Asset Tracker’s configuration for delivery to the Asset Tracker. If the Asset Tracker is online, the staged changes will be sent the update immediately. If it is offline, the changes will be queued. Pending Asset Tracker updates will be overwritten with subsequent changes if any are received and the Asset Tracker has not yet been updated.
For all device updates, you must include a unique ID to the Asset Tracker, set as the value of the updateId
key. This will initially be used to identify the staged (‘pending’) update, but will become the ID of the update when it is applied.
Always provide a new updateId
when you update the configuration data. The system checks the value of updateId
when it receives new JSON and before the new settings are validated. If the current configuration’s updateId
matches that of the update, the update will be ignored. This is designed to mitigate against accidental multiple update uploads.
Examples
Read the current configuration
curl https://agent.electricimp.com/LPoC4xOL8ESr_/cfg \
-u "$MY_USER_NAME:$MY_PASSWORD"
Pretty-print the current configuration (requires jq)
curl https://agent.electricimp.com/LPoC4xOL8ESr_/cfg \
-u "$MY_USER_NAME:$MY_PASSWORD" -s | jq
Set the agent debugging level
curl -X PATCH https://agent.electricimp.com/LPoC4xOL8ESr_/cfg \
-u "$MY_USER_NAME:$MY_PASSWORD" \
-H "content-type: application/json" \
--data '{"agentConfiguration":{"debug":{"logLevel":"DEBUG"}}}'
Apply a 500m device geofence
curl -X PATCH https://agent.electricimp.com/LPoC4xOL8ESr_/cfg \
-u "$MY_USER_NAME:$MY_PASSWORD" \
-H "content-type: application/json" \
--data '{"configuration":{"locationTracking":{"geofence":{"enabled":true,"lat":51.502857552631525,"lon":0.003137042517757941,"radius":500}}}}'
Configuration
An Asset Tracker configuration is a JSON object comprising a number of key-value pairs. All keys are case sensitive. Many pairs are optional, and some are read only. Most of the keys whose values can be changed are protected by guardrails: a range and/or list of supported values.
Schema version
The schema used in the configuration JSON is versioned. The current version is 1.0.
Primary keys
The top-level JSON object contains the following keys. In an update, you do not need to include each of the writeable keys — an agent-only update need only contain agentConfiguration
, for example — but an update lacking both of them will be rejected.
Name | Value | Permission | Notes |
---|---|---|---|
description |
Object | Read Only | Information about the tracker — see below |
configuration |
Object | Read-Write | The Asset Tracker device’s configuration — see below |
agentConfiguration |
Object | Read-Write | The Asset Tracker agent’s configuration — see below |
simUpdate |
Object | Read-Write | Manage the Asset Tracker’s SIM updates — see below |
description
This key always exists in configurations retrieved from the device. It is a read-only property so attempting to update it will cause the update to be rejected entirely.
Name | Value | Notes |
---|---|---|
trackerId |
String | The Asset Tracker’s unique hardware ID |
pendingUpdateId |
String | The unique ID of a pending update, or null if no update is pending |
cfgSchemeVersion |
String | The supported configuration schema version as <major>.<minor> . Currently this is 1.0 |
cfgTimestamp |
Number | A Unix epoch timestamp in seconds indicating when the most recent update was applied, or null if no update has yet been made |
agentConfiguration
This is configuration for the Asset Tracker’s agent. An update may include any or all of its fields. All fields will be included when the configuration is retrieved.
Name | Value | Notes |
---|---|---|
debug |
String | Debug settings as a series of key-value pairs — see below |
debug
Name | Value | Notes |
---|---|---|
logLevel |
String | The logging level. Its value is one of the following string literals: ERROR , INFO , DEBUG . Default: DEBUG |
configuration
This is the configuration of the Asset Tracker hardware. An update may include any or all of its fields. All fields will be included when the configuration is retrieved unless their values are not known, e.g., no update has yet been posted, so there will be no update ID.
Name | Value | Notes |
---|---|---|
updateId |
String | A mandatory user-specified unique ID — choose a value meaningful to you and your application — for the most recent update. This must be different from the existing ID, or the update will be rejected. This key will be absent from a retrieved configuration if no update has yet been applied. Default myDefaultCfg |
locationTracking |
Object | Location monitoring controls — see below |
connectingPeriod |
Number | How often the tracker should connect to the network, in seconds. Default: 180s |
readingPeriod |
Number | How often the tracker polls various data, in seconds. Default: 60s |
alerts |
Object | Non-tracking related alert configuration — see below |
debug |
Object | Debug settings as a series of key-value pairs — see above |
locationTracking
All of the objects listed in the table below contain the key enabled
. This has a Boolean value that indicates/sets whether the feature is activated. Other keys may be present — these are included in the table.
The Asset Tracker will monitor its location if any of the following conditions are met:
alwaysOn
istrue
.motionMonitoring
is enabled and the tracker is in motion.repossessionMode
is enabled and the current timestamp is greater than the one specified in the configuration.
Name | Value | Notes |
---|---|---|
locReadingPeriod |
Number | How often the tracker reads its location when location determination is activated, in seconds. Default: 180s |
alwaysOn |
Boolean | Whether tracking is permanently enabled (true ) or not (false ). Default: false |
motionMonitoring |
Object | Start monitoring location when the device begins moving. Enabled by default. The value of movementAccMin is the movement acceleration threshold range minimum. Default: 0.2G.The value of movementAccMax is the movement acceleration threshold range maximum. Default: 0.4G.The value of movementAccDur is the period the Asset Tracker has exceeded an acceleration threshold. Default: 0.25s.The value of motionTime is the time allowed to confirm motion after the initial movement, in seconds. Default: 15s.The value of motionVelocity is the minimum instantaneous velocity to confirm motion detection, in meters per second. Default: 0.5m/sThe value of motionDistance is the minimum movement distance to confirm motion detection, in meters. Set this to 0 to disable distance calculation. Default: 5mThe value of motionStopTimeout is time without movement for motion to be assumed to have ended, in seconds. Default: 10s |
repossessionMode |
Object | Establishes a date at which location monitoring will be enabled, allowing the Asset Tracker to be located for collection and return to base. The value of after is a Unix epoch time in seconds after which location determination is activated. Default: 1667598736 (05.11.2022 00:52:16) |
bleDevices |
Object | A set of BLE devices that can be used to determine the Asset Tracker’s location. Not enabled by default. Two types of BLE device are supported: “generic” and “iBeacon”. Keys matching these types can be included, each key’s value is an object whose keys are, respectively, MAC addresses and beacon UUIDs, which must be lowercase. Each MAC key’s value is an object comprising the keys lat and lon indicating the generic BLE device’s coordinates.Each beacon UUID key’s value is an object with the key set to the beacon’s major value. The major key value is an object containing keys set to beacon minor values. Each minor key value is an object comprising the keys lat and lon indicating the generic BLE device’s coordinatesSee Configuration examples |
geofence |
Object | A circular geofence area. Not enabled by default. The value of lat is the center point’s latitude. Default: 0.0.The value of lng is the center point’s longitude. Default: 0.0.The value of radius is the circle’s radius, in meters. Default: 0.0 |
You can update lists of BLE devices of each type, MAC or UUID, or major value. For example, if you have a series of iBeacons you can add a new UUID to the list, add a new major value to an existing UUID, or a new minor value to an existing major value.
alerts
All of the objects listed in the table below contain the keys enabled
and threshold
. The former has a Boolean value that indicates/sets whether alerts should be issued for the parent, the latter is the data point at which the alert will be triggered, described with each entry. Other keys may be present too — these are included in the table.
Name | Value | Notes |
---|---|---|
shockDetected |
Object | The Asset Tracker was moved suddenly or suffered an impact. Enabled by default. The value of threshold is the level of shock in Gs |
tamperingDetected |
Object | The Asset Tracker’s case was opened. Not enabled by default. Default: 8G |
temperatureLow |
Object | The temperature crosses the lower limit. Enabled by default. The value of threshold is the temperature limit in Celsius. Default: 10°C.The value of hysteresis is used avoid repeated alerts, in Celsius. Default: 1.0 |
temperatureHigh |
Object | The temperature crosses the upper limit. Enabled by default. The value of threshold is the temperature limit in Celsius. Default: 25°C.The value of hysteresis is used avoid repeated alerts, in Celsius. Default: 1.0 |
batteryLow |
Object | The battery level crosses the lower limit. Not enabled by default. The value of threshold is a charge level percentage. Default: 12% |
The value of shockDetected.threshold
affects the measurement range and accuracy of the accelerometer: the larger the range, the lower the accuracy.
This can affect the effectiveness of configuration.motionMonitoring.movementAccMin
. For example, if threshold
is greater than 4g, then movementAccMin
should be set to above 0.1g.
SIM updates
Use this group of settings to manage SIM over-the-air updates. Such updates usually occur automatically, but very short connection periods may prevent this: the connection is broken before a pending update can be detected and/or retrieved.
An update may include any or all of its fields. All fields will be included when the configuration is retrieved.
Name | Value | Notes |
---|---|---|
enabled |
Boolean | Set to true to force SIM OTA updates every time the tracker connects |
duration |
Number | The duration of connection retention in seconds. Only used when SIM OTA updates are forced, to allow time for the installation of pending updates |
Configuration examples
The following example is a complete Asset Tracker configuration file as received by making a GET
request to the device’s Southbound API.
{
"description": {
"trackerId": "600a0002d7026715",
"cfgTimestamp": 1651659656,
"cfgSchemeVersion": "1.0",
"pendingUpdateId": "62"
},
"configuration": {
"updateId": "61",
"locationTracking": {
"locReadingPeriod": 30,
"alwaysOn": true,
"motionMonitoring": {
"enabled": true,
"movementAccMin": 0.15000001,
"movementAccMax": 0.30000001,
"movementAccDur": 0.25,
"motionTime": 5,
"motionDistance": 1,
"motionVelocity": 0.25,
"motionStopTimeout": 10
},
"repossessionMode": {
"enabled": false,
"after": 1651655116
},
"bleDevices": {
"enabled": true,
"generic": {
"0C:2A:69:04:6A:49": {
"lng": 16.32,
"lat": 64.255997
}
},
"iBeacon": {
"0112233445566778899aabbccddeeff0": {
"1800": {
"1286": {
"lng": 16.32,
"lat": 64.26
},
"1287": {
"lng": 16.30,
"lat": 64.29
}
}
}
}
},
"geofence": {
"enabled": true,
"lat": 0,
"lng": 0,
"radius": 0
}
},
"connectingPeriod": 60,
"readingPeriod": 20,
"alerts": {
"batteryLow": {
"enabled": true,
"threshold": 16
},
"shockDetected": {
"enabled": true,
"threshold": 3
},
"tamperingDetected": {
"enabled": true,
"pollingPeriod": 60
},
"temperatureHigh": {
"enabled": true,
"hysteresis": 1,
"threshold": 25
},
"temperatureLow": {
"enabled": true,
"hysteresis": 1,
"threshold": 20
}
},
"debug": {
"logLevel": "DEBUG"
}
},
"simUpdate": {
"enabled": false,
"duration": 30
},
"agentConfiguration": {
"debug": {
"logLevel": "DEBUG"
}
}
}
The following example is typical update. It impacts the device and its agent, so contains both the configuration
and agentConfiguration
primary keys, but not the (read-only) description
key. Only those key-value pairs that have been changed are included.
{
"configuration": {
"updateId": "app_device_route_alpha_congig_update_47",
"locationTracking": {
"locReadingPeriod": 10,
"geofence": {
"enabled": true,
"lat": 51.502857552631525,
"lng": 0.003137042517757941,
"radius": 500
}
},
"connectingPeriod": 30,
},
"debug": {
"logLevel": "DEBUG"
}
},
"agentConfiguration": {
"debug": {
"logLevel": "DEBUG"
}
}
}
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.