Menu

Expand
Rate this page:

Programmable Asset Tracker Configuration Guide

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 Twilio Programmable Asset Tracker is a new concept in Internet of Things (IoT) product design. It’s a fully functional asset tracker device that communicates over a cellular connection, has all-direction movement sensing on board, and uses satellite navigation and other techniques to determine its location. It contains all the hardware it needs — and the production-grade software to drive it to a standard, feature-rich level of functionality. It’s ready to use right out of the box.

But here’s the good part: its application is entirely customizable by you. Maybe there’s some extra location information your use case requires, or an advanced function you’d like the device to be able to perform. By leveraging the development, testing, deployment, and fleet management capabilities of the Twilio Electric Imp IoT platform, you can extend and upgrade your armada of Asset Trackers, securely and remotely.

The first step on the path to creating your own custom Asset Tracker application is to fine-tune the baseline Asset Tracker application to the needs of your use case. The operational parameters of every key Asset Tracker feature are exposed in the Asset Tracker’s settings. You can control how every aspect of the application behaves by re-configuring any or all of the Asset Tracker’s capabilities.

This guide will introduce you to the Asset Tracker’s core functionality, its operational modes, and how its behavior can be changed by updating application- and device-level settings. It also explains how those settings are applied in the context of the two-part nature of all Asset Tracker applications.

The Asset Tracker application

Every Asset Tracker is partnered by its own in-cloud component called an “agent”. The agent runs continuously* to provide the Asset Tracker with an always-on Internet presence, even when the Asset Tracker may be disconnected (intentionally or otherwise) or is sleeping to conserve power.

The Twilio Programmable Asset Tracker architecture

As such the Asset Tracker application code comes in two parts:

  • Device Code — This is the application that runs on the physical hardware.
  • Agent Code — This is the application that runs in the cloud.

When you update and deploy the Asset Tracker application, either the standard version or one you have customized, the device code is compiled and copied to every Asset Tracker. Each Asset Tracker’s agent is running in a sandbox in the cloud; at deployment each sandbox receives the new agent code.

How the Asset Tracker’s settings are organized

The Asset Tracker application has two types of setting:

  • Application-level settings — These settings are applied using the Electric Imp online IDE and device management console, impCentral, and are intended to be used by all Asset Trackers running a given version of the standard or a custom app. Asset Trackers A and Bs will gain the same application-level settings.
    Application-level settings are set by providing values for specific environment variables in impCentral. To learn how to set environment variables, please see the Electric Imp Dev Center.
    impCentral environment vars
  • Unit-level settings – These settings affect the operation of a given Asset Tracker and its agent. Changing Asset Tracker A’s configuration will not affect the configuration of Asset Tracker B. The settings are stored as dictionaries of key-value pairs. There are several ways you can apply these settings, and these are discussed below. You can make settings changes at any time. Changes to the agent’s configuration are applied immediately; device settings are staged and applied when the Asset Tracker next comes online.
    Update an Asset Tracker's configuration via its UI

We’ll go into greater detail about how each feature is configured as we explore how each of the Asset Tracker’s features operate.

How the Asset Tracker’s settings are applied

Device-level Asset Tracker settings can be applied in either of two complementary ways. First, the Asset Tracker hosts a REST API, called the Southbound API, which can be used to upload settings values in the form of JSON. If you are going to update more than a couple of Asset Trackers at once with the same settings, then you can use the Southbound API to deliver the update to all your devices programmatically.

The Asset Tracker’s agent also hosts a web UI which you can use to update the Asset Tracker’s settings visually. You will have already seen this if you worked through the Asset Tracker Get Started Guide. Currently, the UI allows you to edit the device’s configuration as a JSON structure that mirrors the data you would upload via the Southbound API. The Asset Tracker roadmap includes UI updates that will expose these settings as on-screen controls. However, this approach, while useful during evaluation and app development phases, is only practical for updating one or two devices at a time.

The UI is available at the following URL, which is unique to each Asset Tracker:

https://agent.electricimp.com/<unique_agent-specific_id>

The agent’s ID is set by the system and can be read in code or viewed in the impCentral IDE.

The Southbound API is accessible at these same URL, at the /cfg endpoint:

https://agent.electricimp.com/<unique_agent-specific_id>/cfg

Southbound API authorization

Access to the Southbound API must be authorized. You specify the username and password that a client must use to authenticate its requests by providing them as impCentral environment variables:

  • CFG_REST_API_USERNAME
  • CFG_REST_API_PASSWORD

Requests made with no or invalid credentials will fail.

Get the current configuration

To view the Asset Tracker’s current configuration, open the UI and select its Configuration tab, or make a GET request to the Southbound API, which will return a JSON string.

For more information on the Southbound API please see the Southbound API reference.

Update the configuration

To update one or more settings, edit the JSON configuration in the UI and click the Save configuration button, or send a PATCH request to the Southbound API and include a JSON string as the request’s body. This JSON only needs to include the keys and values that are being changed.

If you change the configuration on one device and want to roll out the changes to other Programmable Asset Trackers, click the Copy JSON button. This puts an escaped string into your computer’s clipboard. You can now paste this string as the value of a DEFAULT_CFG environment variable in impCentral. You can then re-deploy the application to all your devices.

Always provide a new updateId value 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.

The Asset Tracker development environment

The Asset Tracker is built upon the Twilio Electric Imp platform. This includes an online IDE (Integrated Development Environment) and device management console called impCentral. The organization of impCentral is beyond the scope of this guide, which focuses on the Asset Tracker, but you will need to log into impCentral to apply certain application-level settings, described below and throughout this guide. For that reason — and especially if you intend to customize the Asset Tracker application at the code level or manage one or more fleet of Asset Trackers — that you take a moment to review the impCentral User Guide.

Battery life considerations

Many of the settings described below, particularly those related to wake times and reporting, use default values that have been specifically selected for testing purposes and so will not necessarily provide the Asset Tracker with an optimal battery life. Increasing certain values, such as the frequency of automatic location checks, making motion detection more aggressive or issuing more alerts, or reducing the Asset Tracker’s reporting interval, will wake the unit from sleep more often, may power up more sub-systems, and so more strongly impact battery life.

Please bear this in mind as you begin to experiment with different settings. In most real-world deployments these values will be set to increase battery life.

A note on notation

When we’re talking about settings keys and their values, we use dot syntax to express the hierarchy of keys in the configuration data. For example, the JSON element alwaysOn:

{
  "configuration": {
    "locationTracking": {
      "alwaysOn": true,
      . . .
    }
  }
}

is referenced in this guide as configuration.locationTracking.alwaysOn.

Location tracking

The Asset Tracker is able to determine its current location. It does so every time it restarts, but it can also re-acquire its location periodically. It will do so if any of the following conditions are true:

  • You have enabled location tracking.
  • You have enabled motion tracking.
  • You have enabled “repossession mode”, which is described in a later section.

Each of these options is enabled or disabled in the Asset Tracker’s settings, which also expose the data used by the Asset Tracker to manage the location process. All of these settings are accessed in the configuration.locationTracking object:

  • To enable location tracking, set configuration.locationTracking.alwaysOn to true.
  • To enable motion tracking, set configuration.locationTracking.motionMonitoring.enabled to true.
  • To enable repossession mode, set configuration.locationTracking.repossessionMode.enabled to true and set configuration.locationTracking.repossessionMode.after to a non-zero period of time in seconds after which the mode will become active.

Whatever methods the Asset Tracker uses to determine its location, this process will negatively impact battery life, so you should carefully consider how often and by what means you calculate Asset Trackers’ positions in order to maximize battery life.

Location methods

The Asset Tracker has various means at its disposal to determine its location, and applies them in a specific order. If one method fails, it moves on to the next one. As soon as it has good location data, it’s done. These are the methods the Asset Tracker uses:

  1. Scan for known BLE devices
    This will only be used if enabled and the Asset Tracker’s settings includes a list of BLE devices, which can be iBeacons or generic BLE units. These devices’ locations must be known: they have been added to the Asset Tracker’s settings using the configuration.locationTracking.bleDevices object — please see the Southbound API reference for mere details. If the Asset Tracker can detect one or more of these, it uses their known locations to establish its own. This is the first method the Asset Tracker tries because it has the lowest power consumption.
  2. Get a satellite fix
    The Asset Tracker contains a u-blox Neo-M8N GNSS module which is used to determine the Asset Tracker’s location from satellite readings. U-blox AssistNow data, if available, is used to accelerate the GNSS fix.
  3. Use nearby WiFi networks and the Google Maps Geolocation API
    This requires a Google account and a Google Maps Geolocation API key. The Asset Tracker must be online to make use of this option.
  4. Use nearby cellular towers and the Google Maps Geolocation API
    This requires a Google account and a Google Maps Geolocation API key. The Asset Tracker must be online to make use of this option.

Your Google Maps Geolocation API key, if you have one, is applied as an application-level setting: you set it using a specific environment variable in impCentral If you wish to make use of U-blox’s AssistNow service, you will need to provide your AssistNow access token, also as an environment variable.

  • Set your Google Maps Geolocation API key as the value of the environment variable GOOGLE_MAPS_API_KEY.
  • Set your u-blox AssistNow access token as the value of the environment variable UBLOX_ASSIST_NOW_TOKEN.

The Asset Tracker will update its location periodically. The period is set using configuration.locationTracking.locReadingPeriod. The default is 180s. Every time the Asset Tracker updates its location, it records the data in its non-volatile storage.

For more information on using BLE beacons, please see this separate guide.

Geofences

The Asset Tracker can be set to match its known location to that of a circular area defined by the latitude and longitude coordinates of its center and its radius.

To enable the geofencing, set configuration.locationTracking.geofence.enabled to true and define an area by providing numerical values for:

  • configuration.locationTracking.geofence.lat
  • configuration.locationTracking.geofence.lon
  • configuration.locationTracking.geofence.radius

When geofencing is enabled, the Asset Tracker will issue an alert if it moves outside of the geofence and if it comes back inside it. These will be included in status report messages as specific strings included in the array value of the JSON payload’s alerts key:

  • geofenceEntered
  • geofenceExited

Repossession mode

Repossession mode allows you to quickly locate and recover an Asset Tracker to return it to base.

To enable repossession mode, set configuration.locationTracking.repossessionMode.enabled to true and set configuration.locationTracking.repossessionMode.after to a non-zero period of time in seconds after which the mode will become active.

When repossession mode becomes active, the Asset Tracker begins periodic location checks irrespective of its other settings, and transmits its location via status report messages. The messages will report the activation of repossession by including the string repossessionActivated in the array value of the JSON payload’s alerts key.

Additionally, the value of the payload’s status.repossession key will be true.

Motion tracking

When motion tracking is enabled, the Asset Tracker uses data from its on-board accelerometer and its stored location data to determine whether it is moving or at rest.

The Asset Tracker not only checks its accelerometer for a sign of movement, but also goes on to make sure that the detected motion is continuing to take place. The Asset Tracker monitors motion for a set period and if its instantaneous velocity exceeds a set value during that time, or it moves a set distance, the Asset Tracker considers itself to be in motion.

This process is controlled through the Asset Tracker’s settings, which include all of the values mentioned above. They are accessed through the key configuration.locationTracking.motionMonitoring.

The motion tracking algorithm performs several mathematical calculations: It integrates acceleration over time to calculate the speed of velocity over time to calculate the distance traveled and allows the user to set thresholds for these. This enables the tracker application to detect not just basic tracker acceleration, but also sophisticated, use case-specific motion patterns. For more background information, see Implementing Positioning Algorithms Using Accelerometers.

Movement detection

These settings control the Asset Tracker’s movement sensing:

  • Set configuration.locationTracking.motionMonitoring.enabled to true to enable motion sensing. This enabled by default.
  • Use configuration.locationTracking.motionMonitoring.movementAccMin and configuration.locationTracking.motionMonitoring.movementAccMax to specify the range — in multiples of acceleration due to gravity, g — of detected acceleration that indicates movement. If movement is detected but motion is not confirmed, then the lower acceleration threshold is increased by 0.1g. Every time motion is confirmed, the lower acceleration threshold is reset back to movementAccMin.
  • Set configuration.locationTracking.motionMonitoring.movementAccDur to specify how long (in seconds) after exceeding the movement acceleration threshold the Asset Tracker considers that it has detected real movement.

Motion started

When movement is confirmed, the Asset Tracker applies further checks to ensure that it is actually in motion. The accelerometer is re-configured to provide data for velocity and distance calculations using the following values from the device’s settings.

  • Use configuration.locationTracking.motionMonitoring.motionTime to specify the maximum amount of time in seconds that the Asset Tracker should take to confirm motion after an initial movement is detected.
  • Use configuration.locationTracking.motionMonitoring.motionVelocity and configuration.locationTracking.motionMonitoring.motionDistance to set the parameters for the Asset Tracker’s motion check: has it exceeded the specified velocity during the check period and is non-zero after that time? Or did it moved at least the specified distance?

By default, configuration.locationTracking.motionMonitoring.motionDistance is set to zero, so no distance check is made. Setting a positive value causes this check to be made in addition to the velocity test. The Asset Tracker considers itself to be in motion as soon as it reaches the specified distance. However, the velocity check is not complete until configuration.locationTracking.motionMonitoring.motionTime has elapsed.

If motion is detected and confirmed, the Asset Tracker will issue an alert and begin periodically checking its location — if this has not already been enabled for one of the reasons listed in the Location Tracking section, above. At the same time, it will continue to monitor movement to determine if it has come to a halt. While the Asset Tracker is moving, this will be recorded in periodic status reports this way: the value of the JSON payload’s status.inMotion key will be true.

Motion stopped

Two subsequent location readings that are the same (allowing for location accuracy) indicates that the Asset Tracker may have stopped moving. This may also be the case if the Asset Tracker cannot successfully take two or more location readings in a row. If either of these events occur, the Asset Tracker uses the accelerometer to monitor sensor data for a period equal to the value of configuration.locationTracking.motionMonitoring.motionStopTimeout. If no movement occurs in that period, the Asset Tracker judges itself to have come to rest, and a motion-stopped alert will be issued. Otherwise, it once more begins to check for two adjacent location readings that are the same.

Alerts

You can configure the Asset Tracker to alert you if any of the following events take place:

  • Motion started — The Asset Tracker has begun continuous movement.
  • Motion stopped — A moving Asset Tracker has come to rest.
  • Geofence entered — The Asset Tracker has come into a defined circular area.
  • Geofence exited — The Asset Tracker has moved out of a defined circular area.
  • Repossession mode activated — A set period of time has elapsed and the Asset Tracker has begun transmitting its current location.
  • Temperature high — The measured temperature is above a set value.
  • Temperature low — The measured temperature is below a set value.
  • Shock detected — Sudden acceleration beyond a set threshold was detected.
  • Tamper detected — The Asset Tracker’s case has been opened.
  • Battery low — The battery charge falls below a set percentage.

Each alert is enabled separately in the Asset Tracker’s device configuration, which also includes the relevant threshold and other values that the Asset Tracker uses to determine whether each alert condition has occurred. The first five items on the list above are managed under the device’s configuration.locationTracking key, but the remainder are located under alerts.

  • To enable motion started and stopped alerts, set configuration.locationTracking.motionMonitoring.enabled to true and specify your movement detection parameters.
  • To enable geofence alerts, set configuration.locationTracking.geofence.enabled to true and define your fence area.
  • To enable Repossession mode alerts, set configuration.locationTracking.repossessionMode.enabled to true and specify your activation period.
  • To enable the low battery alert, set configuration.alerts.batteryLow.enabled to true and configuration.alerts.batteryLow.threshold to a percentage value. The default is 12%.
  • To enable shock detection, set configuration.alerts.shockDetected.enabled to true and configuration.alerts.shockDetected.threshold to an acceleration level expressed in multiples of g, acceleration due to gravity. The default is 8.
  • To enable tamper detection, set configuration.alerts.tamperingDetected.enabled to true.
  • To enable high temperature warnings, set configuration.alerts.temperatureHigh.enabled to true, configuration.alerts.temperatureHigh.threshold to a temperature in Celsius (default: 25°C), and configuration.alerts.temperatureHigh.hysteresis to a value in Celsius that defines a ± range the temperature must exit to trigger fresh alerts (default: ±1°C).
  • To enable low temperature warnings, set configuration.alerts.temperatureLow.enabled to true, configuration.alerts.temperatureLow.threshold to a temperature in Celsius (default: 10°C), and configuration.alerts.temperatureLow.hysteresis to a value in Celsius that defines a ± range the temperature must exit to trigger fresh alerts (default: ±1°C).

All alerts are enabled by default except geofence boundary crossing, device tampering, and low battery.

Alert checks

Some alerts are issued when an event occurs. For example, the Asset Tracker configures its on-board accelerometer to raise an interrupt if it detects a sudden, sharp but short motion — a shock. This will trigger the alert if it takes place.

Other alerts are managed by periodically polling and comparing current readings to stored threshold values. For example, the Asset Tracker polls its on-board temperature sensor and compares the current reading to high and low threshold values. If the current temperature is outside of the range established by those threshold values, an alert will be issued.

You set the poll period (in seconds) for all these checks with a single setting: configuration.readingPeriod. The default period is 60s.

Alert reports

The standard payload of every status report and alert message contains the key alerts. Its value is an array of strings indicating the alert(s) triggered since the last message was posted. The strings are:

  • temperatureHigh
  • temperatureLow
  • shockDetected
  • batteryLow
  • motionStarted
  • motionStopped
  • geofenceEntered
  • geofenceExited
  • repossessionActivated

Logs

The Asset Tracker’s device and agent code both post log messages that you can view in impCentral. Messages are categorized by the application code, and you specify which messages are emitted by setting configuration.debug.logLevel and agentConfiguration.debug.logLevel. As you can see, agent and device have separate logging levels.

The levels, specified by string literals, are:

  • ERROR — Outputs error messages only. This is the lowest log level.
  • INFO — Outputs informational and error messages.
  • DEBUG — Outputs debugging, informational and error messages. This is the highest log level.

The default for both agent and device settings is DEBUG.

Examples

If you only want to see error messages from the device, set the value of configuration.debug.logLevel to "ERROR".

If you want to see informational and error messages from the agent, set the value of agentConfiguration.debug.logLevel to "INFO".

Log messages will only be received from the device and displayed when the device is online. By default, messages are not buffered for transmission upon reconnection. Additionally, log messages are not emitted by production units unless this feature is specifically enabled for a 24-hour period.

Status reports

The Asset Tracker periodically sends status information to your server. How frequently these messages are sent is governed by the value of the key configuration.connectingPeriod. The default is a 180-second cycle but you should carefully consider how often you need to receive updates in order to maximize battery life. The more often the Asset Tracker has to post reports, the more often it has to wake and connect to the cellular network, and this has a strong negative impact on battery life.

However, if an alert is triggered, a fresh status message containing the alert(s) triggered is posted immediately.

To learn how the Asset Tracker expects to interact with your server, and the full structure of posted status messages, please see The Northbound API.

All messages are sent to a URL you specify at the application level, along with authentication credentials. These values are entered as impCentral environment variables. No default value is provided, and you should consider them mandatory:

  • CLOUD_REST_API_URL — The target URL excluding the endpoint, /data.
  • CLOUD_REST_API_USERNAME — The target server username.
  • CLOUD_REST_API_PASSWORD — The target server password.

Example

This is a sample status report. You can see that two alerts have been raised.

{
  "trackerId": "c0010c2a69f088a4",
  "timestamp": 1617900077,
  "status": {
     "inMotion": true,
     "repossession": false
  },
  "location": {
     "timestamp": 1617900070,
     "type": "gnss",
     "accuracy": 3,
     "lng": 30.571465,
     "lat": 59.749069
  },
  "sensors": {
     "batteryLevel": 100,
     "temperature": 42.191177
  },
  "alerts": [
     "temperatureHigh",
     "shockDetected"
  ]
}

* Sometimes it is necessary to shut down an agent for resource allocation reasons, but it will be offline for no more than five minutes and usually no more than a few seconds.

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