Rate this page:

How to Use the Programmable Asset Tracker with BLE Beacons

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.

One of the various ways the Twilio Programmable Asset Tracker can determine its location is by reference to one or more known points. These reference points are provided by Bluetooth LE (BLE) beacons whose geographical or user-specified co-ordinates are known. The Programmable Asset Tracker supports iBeacons — a popular form of beacon devised by Apple — and generic BLE devices.

This method for working out an Asset Tracker’s location is useful because it requires a much lower power expenditure than either making use of the Tracker’s GNSS system or connecting to the cellular network in order to access online APIs to assist with location accuracy. Beacons are usually inexpensive, easy to install, and operate a battery or USB AC adapter. When installed and their exact locations gathered, they can be used for a variety of site-management applications, but particularly to aid Asset Trackers moving around the site, or from one site to another.

How BLE beacon technology works

BLE devices signal their presence to devices with which they might want to communicate by periodically transmitting presence advertisement packets. These packets are defined by the Bluetooth standard’s Generic Access Profile (GAP), which mandates a structure for the presence information a device will transmit. The organization of this data is beyond the scope of this guide — for more information, you should consult the Bluetooth 5.0 specification and the Bluetooth Core Specification Supplement — but it includes up to 31 bytes of advertising packet payload comprising two or more data fields.

The first of these data fields specifies that the payload is a Bluetooth LE advertising packet. In the case of iBeacons, the second data field incorporates Apple-specified data (it is marked as a manufacturer-defined field) which includes three key data points:

  • A 16-byte universally unique ID called the ‘Proximity UUID’.
  • A two-byte iBeacon ‘Major’ value.
  • A two-byte iBeacon ‘Minor’ value.

These values identify an iBeacon and its relationship to other iBeacons, not necessarily nearby ones.

The Proximity UUID is typically common to all iBeacons at the application level. For example, a shipping company might use a single UUID across all its iBeacons. The Major value would then be used to distinguish iBeacons located at one site from those placed at another site. Minor values, which are only unique for a specific major value, would distinguish buildings or floors at a particular site.

There are other beacon types, such as AltBeacon, but at this time the Programmable Asset Tracker supports only iBeacons specifically. However, all BLE devices signal their presence and identify themselves by their MAC address. This can be used as a proxy for Proximity UUID, Major, and Minor.

How the Programmable Asset Tracker uses beacons

The Programmable Asset Tracker’s setting can include a series of beacons — both generic and iBeacons — which it will use to approximate its location, if this feature is enabled and it has been provided one or more beacons’ identifiers and their locations. For each beacon, of whatever supported type, the Asset Tracker needs a mapping of the beacon’s Proximity UUID, Major and Minor, or its MAC, to latitude and longitude co-ordinates.

BLE signal strength data is used with the beacons’ known latitude and longitude values to locate the Programmable Asset Tracker itself. More accurate, triangulation-based location determination can be performed using a multilateration algorithm in the cloud, but this is not part of the Asset Tracker’s software.

How to provide the Programmable Asset Tracker with beacon data

The Programmable Asset Tracker’s settings are stored in dictionary form and JSON is used as the medium by which this data is received or transmitted to the Programmable Asset Tracker.

The configuration.locationTracking.bleDevices path yields an object containing the following keys:

  • enabled — whether location determination by beacon should be used — true or false.
  • generic — A list of known generic BLE beacons.
  • iBeacon — A list of known iBeacons.

Within the list of generic BLE beacons, each beacon is represented by its unique MAC address, which is a key to an object containing two keys, lat and lng, which give that beacon’s co-ordinates.

The list of iBeacons is more complex: lists of iBeacons are organized by UUID — under each UUID are major objects which contain multiple unique minor keys each of which has lat and lng to give the specific uuid.major.minor beacon’s geographical co-ordinates. For example:

    { "bleDevices": {
        "enabled": true,
        "iBeacon": {
            "51A0A09CD00D456A95513A392182590F": {
                { "0": {
                    "0": {
                        "lat": 51.56185591289561,
                        "lon": -0.14012451953529212
                    "1": {
                        "lat": 51.560773505587306,
                        "lon": -0.13938163401338588
                    "2": {
                        "lat": 51.562966471000806,
                        "lon": -0.13990847502124734
                  "1": {
                    "0": {
                        "lat": 51.56898319519194,
                        "lon": -0.14329618513008963
        "generic": {
            "0007800269EE": {
               "lat": 51.5628361439754,
               "lon": -0.12761030183210698

The latitude and longitude co-ordinates do not need to be geographical co-ordinates like those in the example above. They can be any co-ordinate pair as determined by the user’s coordinate system: for example, x/y distances from an origin point in a warehouse. The co-ordinates are simply passed on by the Asset Tracker to the cloud for further processing and determination of the location of the Asset Tracker relative to the BLE beacons it has detected.

Enter UUID without any dashes that may appear in the way they are presented elsewhere, i.e., 2F234454CF6D4A0FADF2F4911BA9FFA6 not 2F234454-CF6D-4A0F-ADF2-F4911BA9FFA6.

The JSON data can be uploaded to a specific Asset Tracker via the Southbound API, or entered into the Tracker’s Web UI on the Configuration tab.

To apply the settings to a fleet of Asset Trackers, include the list within the escaped JSON string that you set as the value of the DEFAULT_CFG environment variable in impCentral for your fleet’s Device Group.

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!