Programmable Asset Tracker Configuration Guide

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.

Expand image

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.

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.

  Expand image

• 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.

  Expand image

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

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:

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:

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.

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.

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.

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.

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.

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:

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

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.

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 devicesThis 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 fixThe 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. A GNSS fix is accepted as the determined location if a location with an accuracy of not more than 50 meters is returned by the GNSS module within a period of 55 seconds.
3. Use nearby WiFi networks and the Google Maps Geolocation APIThis 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 APIThis 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.

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 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.

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.

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.

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?

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.

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.

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.

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.

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

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.

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".

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.

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.

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

The Programmable Asset Tracker doesn't check whether an over-the-air SIM update is pending or has been downloaded and installed. You can force an update check using the configuration's simUpdate settings.

To start the SIM update procedure, set enabled to true. Now the cellular modem will check for SIM updates on every connection. Use the duration setting to specify how long the cellular connection should be maintain while the update chack (and installation, if required) completes.

* 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.