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.
(information)
Info
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:
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:
_10
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.
(information)
Info
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
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.
(warning)
Warning
Always provide a newupdateId 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.
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.
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
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
is
true
.
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
(information)
Info
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%
(warning)
Warning
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.
_96
{
_96
"description": {
_96
"trackerId": "600a0002d7026715",
_96
"cfgTimestamp": 1651659656,
_96
"cfgSchemeVersion": "1.0",
_96
"pendingUpdateId": "62"
_96
},
_96
"configuration": {
_96
"updateId": "61",
_96
"locationTracking": {
_96
"locReadingPeriod": 30,
_96
"alwaysOn": true,
_96
"motionMonitoring": {
_96
"enabled": true,
_96
"movementAccMin": 0.15000001,
_96
"movementAccMax": 0.30000001,
_96
"movementAccDur": 0.25,
_96
"motionTime": 5,
_96
"motionDistance": 1,
_96
"motionVelocity": 0.25,
_96
"motionStopTimeout": 10
_96
},
_96
"repossessionMode": {
_96
"enabled": false,
_96
"after": 1651655116
_96
},
_96
"bleDevices": {
_96
"enabled": true,
_96
"generic": {
_96
"0C:2A:69:04:6A:49": {
_96
"lng": 16.32,
_96
"lat": 64.255997
_96
}
_96
},
_96
"iBeacon": {
_96
"0112233445566778899aabbccddeeff0": {
_96
"1800": {
_96
"1286": {
_96
"lng": 16.32,
_96
"lat": 64.26
_96
},
_96
"1287": {
_96
"lng": 16.30,
_96
"lat": 64.29
_96
}
_96
}
_96
}
_96
}
_96
},
_96
"geofence": {
_96
"enabled": true,
_96
"lat": 0,
_96
"lng": 0,
_96
"radius": 0
_96
}
_96
},
_96
"connectingPeriod": 60,
_96
"readingPeriod": 20,
_96
"alerts": {
_96
"batteryLow": {
_96
"enabled": true,
_96
"threshold": 16
_96
},
_96
"shockDetected": {
_96
"enabled": true,
_96
"threshold": 3
_96
},
_96
"tamperingDetected": {
_96
"enabled": true,
_96
"pollingPeriod": 60
_96
},
_96
"temperatureHigh": {
_96
"enabled": true,
_96
"hysteresis": 1,
_96
"threshold": 25
_96
},
_96
"temperatureLow": {
_96
"enabled": true,
_96
"hysteresis": 1,
_96
"threshold": 20
_96
}
_96
},
_96
"debug": {
_96
"logLevel": "DEBUG"
_96
}
_96
},
_96
"simUpdate": {
_96
"enabled": false,
_96
"duration": 30
_96
},
_96
"agentConfiguration": {
_96
"debug": {
_96
"logLevel": "DEBUG"
_96
}
_96
}
_96
}
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.