🗄️

AirLink Server

AirLink Server Architecture

Entities Overview Snapshot from Thingsboard.io documentation
AirLink Server Tenant Setup

Concepts by Use Case

Business NeedBusiness ConceptsThingsboard Concepts
Devices provision themselvesProvisionDeviceTechnicianAPI TokenDevice AuthTokenGatewayIntegrationProvisioningRule-chain Script
AirLink uses nexus channel resource models ie standard device typesAirLinkAttributesDevice Profiles
Simusolar uses Aeris globalSIM in PAYG** gatewaysAeris VPNFirst PAYG ServerDevice AuthTokenGatewayIntegration
Phone or solar panel controls deviceAirLinkDevice AuthTokenDevice Group
Device belongs to customerPAYG Box IDPAYG CustomerSales OrderSystem IDAPI TokenCustomerDeviceIntegration
Orders make CustomersPAYG CustomerSales OrderAssetCustomer
CBOR transfer over HTTP/MQTTAirLinkData ConverterIntegration
Loan platform updates creditsFinancingPAYG CreditWebiAPI TokenIntegration
Device heeds PAYG creditsFinancingDevice AuthTokenIntegration
AirLink uses Nexus Keycode or Solaris OpenPAYGO TokenAirLinkToken AutomationAttributesRule-chain Script
Device data savedCallhome DataGraphs and MapsData ConverterDeviceDevice AuthTokenRule-chain Script
Partners can see referred customer dataGraphs and MapsPAYG CreditPAYG CustomerCustomer GroupData ChartEntity View Group
Technicians update devicesDFUDebug DataProvisionDeviceService SwapTechnicianAssetAsset GroupDFUData ConverterDeviceDevice AuthTokenGatewayIntegrationUser Group
Simusolar operates in several countries with inter-country asset movementCentralized ITAssetAsset GroupUser Group
Simusolar franchises payg functionalityDebug DataDistributorGraphs and MapsPAYG CreditToken AutomationCustomer GroupCustomer HierarchyMulti-tenancy

Testing Testing Testing

We encourage creating test entities to learn about Thingsboard, that way production entities can be easily kept separate. Every entity can be grouped, so creating a test group for each type of entity is an easy way to do testing. Entities can be added to a test group by selecting one or more entities from the 'All' catch-all group, and adding to a specific group:

Tenant Configuration

User Roles

Two main roles are defined, Tenant Admin (first assigned along with tenant) who has full privileges within the platform including controlling other users access, and Technician who has full device privileges including re-provisioning and assigning to customers. Customer administration is presumed to be done via API integration by the business applications server, hence there is no third role regarding customer administration.

<Screenshots on configuring the two roles>

Device Profiles

Device profiles can be considered as the equivalent of 'class definitions' in object oriented programming, with each device then being an instance of a particular profile. We have two main device profiles, an edge device and a gateway. These could potentially be merged, however Thingsboard does make a differentiation between a gateway and non-gateway with a checkbox as well as requirements on data format, hence we define two profiles.

<FIXME Screenshots on configuring AirLink device and AirLink gateway>

Rule Chains

Rule chains are the heart of custom data manipulation within the platform, and the 'data converter' is the first step at the edge of the rule chain that re-forms incoming data to a format that can be processed by the other blocks in the rule chain and then re-forms outgoing data to REST or other standards needed by the rest of the application and device network. The Root Rule chain is used for all customized telemetry functions including lost device reporting, and is available as a downloaded JSON file to be imported into each tenant.

<FIXME Exported Rule Chain File>

Attributes and Time Series Data

Data exchanged with the device or with the application server in the context of a device are termed attributes.

Working with IoT device attributes
On this page ThingsBoard provides the ability to assign custom attributes to your entities and manage these attributes. Those attributes are stored in the database and may be used for data visualization and data processing. Attributes are treated as key-value pairs.
https://thingsboard.io/docs/user-guide/attributes/

In the AirLink server (based on Thingsboard), Attributes are Device properties that are only stored as current values, while Timeseries data are properties tracked over time. Attributes and Timeseries keys can be created during provisioning or are automatically created in the Airlink server when first posted, allowing for flexibility in growing resource models over time without requiring reconfiguration of the server. The following are the major attribute types and their scopes in a basic AirLink setup.

Server Side: Attributes only seen by the server and application server integrations

Shared: Attributes written to by the server and application server integrations, and available to the Device to read only

Device Side: Attributes written to by the device, and by application server integrations. Time series data also behaves this way.

Screenshot from AirLink server showing Attributes and Telemetry. Telemetry is always client-scope or 'device side'

Scope of Data Categories

NameScope
Rule chain alarm ThresholdsServer Side
Device Administration ConfigurationServer Side
PAYG CommandShared
Device provisioning or claiming keysShared
Customer Provisioning InformationShared
Timeseries DataDevice (Client) Side:
PAYG StatusDevice (Client) Side:
Config status e.g. Firmware versionDevice (Client) Side:

CBOR data types are defined here:

https://datatracker.ietf.org/doc/html/rfc7049#section-2.1

Server and Shared Data to support AirLink Devices

Nx ResourcertrResource Propertykeyrtr_propQualifiersCBOR TypeDescription
AirLink Device Provisioning 1.0PRDServer Auth TokensatPRD_satMandatoryScope: SharedString3Thinsboard.io has a 20-char device authentication token unique to each device. During device provisioning, this token is written to the device, permanently attaching the device to the server. The token is never transmitted again.
AirLink Device Provisioning 1.0PRDProvisioning StatuspstPRD_pstInteger (uint8_t)MandatoryScope: Shared0Reflected in Advt packet also. It can be unprovisioned, disabled, recall, stolen, Cash, Loan. The range is from 1-9. If not supported then 0
AirLink Device Provisioning 1.0PRDPayG UnitpuPRD_puMandatoryScope: SharedString336^1 The unit of the PayG update, it can be minutes, hours, days, months and years. [m-minutes, h-hours, d- days, M-months, Y-years]
AirLink Device Provisioning 1.0PRDPayG Token starting codepscPRD_pscScope: SharedString31-day token, https://github.com/EnAccess/OpenPAYGO-HW
AirLink Device Provisioning 1.0PRDPayG Units acceptedpulPRD_pulMandatoryScope: DeviceString3CSV list of acceptable Units e.g. "l" for liters, "h,d" for hours and days
AirLink Client Provisioning 1.0PRCProvisioning StatuspstPRC_pstInteger (uint8_t)MandatoryScope: Shared0Reflected in Advt packet also. It can be unprovisioned, disabled, recall, stolen, Cash, Loan. The range is from 1-9. If not supported then 0
AirLink Client Provisioning 1.0PRCReadable ID + Cbor header 2 bytesridPRC_ridInteger (uint32_t)MandatoryScope: Shared262^(8*4) = 4,294,967,296 numeric device ids or payment reference or any number that device should display
AirLink Client Provisioning 1.0PRCCustomer's PhonecpPRC_cpOptionalScope: SharedString3Requested by customers for stolen device reporting (needs a workflow to collect this number explicitly from client in addition to regular lead number). Assign the mobile number of the customer to a device. With maximum of 16 character including + and country code number. This is for security purpose
AirLink Client Provisioning 1.0PRCCustomer NamecnPRC_cnOptionalScope: SharedString3Requested by customers for lost device reporting. This writes the customer name to a device with the maximum of 16 characters with space and special characters inclusive.
AirLink Nexus Command 1.0NXCNexus COSE commandcmdNXC_cmdScope: Shared3Upto 120 bytes for Nexus Channel Passthrough commands
AirLink PAYG 1.0PYGCurrent Server TimeltPYG_ltOptionalScope: DeviceLinux epoch format, expires in Y2035. The current time when updating the device with PayG update. We do not recommend using this to calculate PAYG use, because it could be used to trick the device into more tokens. This is for non-PAYG purposes eg client experience
AirLink PAYG 1.0PYGTimestamp of last PAYG Update to deviceltsPYG_ltsOptionalScope: DeviceLinux epoch format, expires in Y2035, readonly - Historical last PayG update Timestamp
AirLink PAYG 1.0PYGTimestamp at which PayG remaining was calculatedtsPYG_tsOptionalScope: DeviceLinux epoch format, expires in Y2035. The Last date and time when the PayG update was fetched from the Server to client [Mobile phone or other communication device]
AirLink PAYG 1.0PYGLast Added PayG CreditlcrPYG_lcrOptionalScope: DeviceHistorical last PayG credit update duration. Range is from 01-9999
AirLink PAYG 1.0PYGPayG TokentknPYG_tknScope: SharedSipHash token. Accepted by device only if valid. No read token to ensure unsecured gateways cannot act maliciously.
PAYG Credit 1.0PYGModemoPYG_moNot ImplementedScope: Sharedmode of device i.e. leading/following etc For Write, a Nexus Channel Link must be established otherwise read-only, updated via token. AirLink 1.0 does not implement Nexus Channel, which was in development at the time of release of AirLink 1.0
PAYG Credit 1.0PYGDevice PayG Credit RemainingrePYG_reMandatoryScope: Time Seriesshould be The value remaining for the device to OFF. For Write, a Nexus Channel Link must be established otherwise read-only, updated via token. AirLink 1.0 does not implement Nexus Channel, which was in development at the time of release of AirLink 1.0

Posting of device data to the server for off-edge devices is done via gateway by sharing their device access tokens with the gateway using the application server. For Smartphone gateways, this can be done via a separate channel to the application server. For 'thing' gateways, this must be done via a 'disappearing' shared server attribute for that gateway, so that tokens are not saved in the insecure data space for too long. The application server then would update the attribute to transfer tokens to the gateway, and then blank it out once the gateway receives the tokens or after a certain timeout.

Authentication flows for device and business applications server Access

AirLink server controls IoT interactions and can connect with the business applications server via REST API. The Business Applications server must authenticate itself as a User or Customer using JWT authentication, or have access keys to a custom integration as specified in the authentication flow. Note that only Custom Integration configurations are visible in the UI, the built-in telemetry, admin etc endpoints are only visible in the Swagger documentation but all events from each endpoint are posted to the root rule chain, enabling customized business logic for all types of data.

AirLink Server Device Auth Flows

Full API reference is available as live Swagger documentation here:

Swagger UI
https://airlink.enaccess.org/swagger-ui.html

Data Transport

Device-initiated or gateway-initiated communications posting time-series data and accepting a PAYG update response are expected to form the bulk of IoT traffic in PAYG use cases. Considering the Auth flows available for posting data, AirLink recommends four types of transport:

  1. Individual devices equipped with GSM send data directly using their device token e.g. water pump control boxes
  1. Gateways bundled with a sale register as MQTT gateways in the AirLink server to be able to post data from multiple downstream devices while minimizing bandwidth use. This is relevant because such IoT gateways often use data-thrifty 'Global-SIM' cards which can rack up high data costs e.g. solar panel with GSM chip bundled with 3 batteries that it charges
  1. Phone apps acting as gateways post data as the device and get PAYG updates from the server, using the individual device tokens downloaded during the sales and service flows. This needs to be enabled by the business applications server and is useful because several phone gateways may be used to operate the same device and a one-device multi-gateway scenario with offline access is not well served by MQTT. PAYG security is still ensured by the fact that the token is still only decode-able to the server and the device and not the intervening gateways. e.g. equipment owner could operate the device, several equipment technicians could operate the device etc.
  1. Phone apps and gateways post advertisement data for unknown AirLink devices to facilitate lost-and-found using a special property within the gateway's telemetry which is then processed by the root rule chain with the necessary validations to ensure that data gets send to the correct recipient and so that it is not used for posting non-advertising telemetry or attributes for the device.

AirLink currently only supports HTTP transport, CoAP will be enabled in the future. CBOR formatting of data is not currently supported.

KeyCode generation

Nexus Keycode as well as OpenPAYGO Token use 'SipHash' to generate the key, and have Python/Java libraries available. However Thingsboard only runs single-file JavaScript in it's rule chains and custom JAVA in it's rule nodes, hence we decided to create a JAVA rule node based on Nexus Keycode available for general KeyCode generation, but also external keycodes can be generated by swapping that rule node for an External REST request to a client's server running code generation. This can also be done in a device specific manner. Since Keycode generation is not a telemetry-time operation but rather account-payment time operation, the number of requests will scale with the number of devices and payment frequency rather than the number or frequency of telemetry data. The KeyCode node

  1. Re-forms incoming business data relating to standard keycode interactions such as adding credit, sending a command etc
  1. Uses SipHash to generate the actual keycode
  1. Returns this keycode to the rule chain for saving in the database to serve future GET requests from devices, and potentially sends it to a business server if required for SMS communications or saving in the business application server database

Lost asset location tracking

A significant benefit of interoperability is the ability across vendors to track lost and stolen items. Given the distributed and rural nature of PAYG distribution, this becomes particularly relevant if all wireless-enabled devices can report their current location to any AirLink gateway whether paired with the device or not. The gateway then needs to be able to post this data to Thingsboard without knowing the device's security token. To facilitate this process, the gateway posts device data one at a time as it's own timeseries property which is processed by the Rule chain modification shown below. We then host a 'Lost and Found Tenant' in the server as shown in the architecture diagram, where un-secured device locations can be stored by gateways registered to other tenants. The process then is that if a gateway chances upon a device it doesn't have access to, it reports the advertising packet along with it's own location to the 'neighborhood watch' tenant, which then passes on the information to the tenant that owns the device using the device's manufacturer code, and automated rule-chain code passes this unregistered device onto the lost and found tenant where it can be available for access by the tenant who may have lost the device. If the tenant owning the device is the same as that of the gateway, then MQTT can also be leveraged for posting advertisement data without any change required to the server. However for devices belonging to other tenants, since a gateway cannot claim them, this flow of posting via the /timeseries/ endpoint for the gateway itself as a piggyback device is valid. Unfortunately thingsboard.io does not provide an easy method to post several devices from the gateway within the same transmission, hence the gateway will see one transmission per reported device. This should be considered in the data limits of each device, and alternate flows employed if the data flow is a bottleneck. Data-rich gateways such as Smartphones should afford virtually unlimited device reporting per day.

Gateway Telemetry with a Piggyback Device