Southbound API Reference

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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