AirLink Devices

Preface: A note on Bluetooth® SIG requirements, Nov 2021

Our understanding is that the Bluetooth® Special Interest Group requires that any entity branding and selling devices enabled with Bluetooth® must register as a member with the SIG at bluetooth.com, as well as declare the product and the Bluetooth® component being used. This is true for resellers, distributors, and all commercial sales. The final selling brand and product name must be separately declared by the seller, even if the component containing Bluetooth® has been declared by the manufacturer.

Although membership has a free tier, each declaration as of this writing costs $8,000, set to rise to $9,600 in 2022. Multiple products using the same Bluetooth® component (one with an approved QDID) can be added to a new or existing declaration, however if the underlying Bluetooth® component is changed even within the same product, a new declaration must be filed with the full fee. Repercussions of not filing declarations may include shipments of the product being held by customs agents, from a global reference list maintained at bluetooth.com.

This requirement as we understand only applies for sold products, not prototypes.

Please note that this note is not official Bluetooth® SIG communication, but rather it is our understanding of the requirements set by the Bluetooth® SIG as of this writing.

Device Emulator App

To enable quick end to end testing of AirLink, we have designed a single-page Android-native app that imitates an AirLink device with temperature, battery and device configuration resources. The source code of this app as well as an Android-9 executable APK is saved in the AirLink Devices Github repository under the Device Simulator folder.

This app allows you to:

1. Pair with the main AirLink (gateway) app on another phone

2. Go through the provisioning flow and initialize the token generation flow

3. Send data to the server via the AirLink gateway app

4. Accept tokens from the server - although there is no nexus token decoder running in the app, so it will accept any token

The source code is meant as a reference when designing embedded firmware that can match AirLink’s provisioning and data exchange flows. With the emulator app, anyone can test AirLink without requiring hardware, simply by downloading it onto an Android phone, installing the AirLink gateway app on another phone, and logging on to the demo/custom tenant on the AirLink server.

The source code is not meant to actually process tokens, but could act as a starting point if Android Airlink devices are being developed.

Nordic Device Firmware

Nordic makes the most popular set of Bluetooth chips, and we have developed example firmware to support provisioning, data as well as full Nexus token capability. This firmware is meant to act as a reference for developing custom bluetooth hardware that supports AirLink and also to act as a testbed while developing a custom AirLink gateway app.

Nordic firmware reference source code is available on the AirLink Devices github repository.

BLE Range Testing

The Simusolar team tested how far we could find an AirLink device from in presence of walls and with clear line of sight.

From the OCF specification

https://openconnectivity.org/specs/OCF_Resource_to_BLE_Mapping_Specification_v2.2.2.pdf

AirLink Devices adopt the Open Connectivity Foundation's Resource Model bridging guidelines for Bluetooth LE devices. A key feature of this bridge is that several OCF Resources are wrapped into one Bluetooth Service to make GET/POST requests efficient. We leverage CBOR for this encapsulation.

Resource model design

The OCF bridging recommendation covers GATT properties well, however it does not cover Advertising nor does it cover a resource enumerator explicitly.

We used the following additional assumptions to design our resource models:

1. Bluetooth gateways from any vendor adopting AirLink should be able to detect other AirLink devices, to ensure interoperability as well as crowd-sourced stolen asset detection. Hence the advertising packet needs to be open format with sufficient information to identify the device and it's basic state

2. Extended advertising should not be required to transmit the required data, limiting the overall size to 26 bytes

3. The advertisement data packet as well as other GATT service characteristics must be CBOR encoded lists of Resource Model properties. This is designed for compatibility with the Nexus Channel effort. The GATT characteristics should be in 2-D array format, whereas the Advertisement packet will be a single dimensional byte array with positionally separated properties to conserve data packet length. The gateway device then converts this into a 2-D CBOR array and includes location information before transmitting to the server.

4. Location is to be appended by the gateway device before transmission to the server, as non-gateway devices are unlikely to have GSM/GPS to locate themselves. However, devices can store locations provided to them by gateway devices to enable a location history within the device if required

5. Pay-as-you-go credits are sent as Nexus Keycode Tokens, with planned future support for OpenPAYGO Tokens - this is to ensure interoperability with existing keypad/remote enabled devices as well as independence from time-stamp synchronization between server/gateway/end device.

6. We cover the following general use cases here:
   1. Required: Asset locatability by any gateway via advertisement
   2. Required: Resource enumerator service
   3. Required: Pay-as-you-go credits - we postulate that this does not require manufacturer specific authorization because OpenPAYG Tokens are already securely encrypted between a server and device
   4. Self-provisioning as supported by Thingsboard.io servers
   5. Optional: Power use and Productive Output data logging

Device Discovery Services

1. The advertisement packet is a compressed resource always readable from the device. We designate it as an 'Implicit GET'. A gateway device reads this resource while scanning for devices (before a connection is established), and decompresses it to create a standard-format resource model compatible with AirLink Server. It adds items such as resource type, interface type etc as required by OCF but also timezone, location lat-lon where the device was discovered and the manufacturer ID which is in the bluetooth advertisement header

2. The /res enumerator resource in AirLink is not included explicitly but each bluetooth property has the corresponding resource endpoint in its ‘Descriptor’ field, removing the need for an explicit descriptor resource while still allowing gateways to discover resources available in a device

3. To discover how a device gets added to the AirLink server, check the AirLink Server page!

Device Config Service

1. We presume and recommend self-provisioning, although this resource can also be written to if the device firmware permits.

2. Gateways can be updated with a list of these configurations for downstream devices

3. The command resource is a passthrough for building a custom encrypted application links e.g. Nexus Channel

4. On connection, the gateway must write the server access token property with the correct value for that device, upon which the rest of the properties are opened by the device for communication. This is expected to be the programmed behavior of AirLink devices

PUE Use Service

We envision 2 primary usages of a productive use asset:

1. PAYG control: This is a generic PAYG packet intended to cover all known PAYG use cases for BLE assets

2. Use data (time-series): This is a generic IoT Data packet designed to cover both battery-less and battery-based devices

3. Gateways can accumulate data for/from several devices