Menu

Expand
Rate this page:

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 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/s
The value of motionDistance is the minimum movement distance to confirm motion detection, in meters. Set this to 0 to disable distance calculation. Default: 5m
The 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 coordinates
See 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"
    }
  }
}
Rate this page:

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.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif