AirLink App

The AirLink Mobile app is a communication app skeleton enabling gateway functionality i.e. end to end communication between AirLink Bluetooth® devices and an AirLink server. The app is intended to act as a base that takes care of device interactions, on which different customer experiences can be built by the businesses adopting AirLink.

Once the App Instance is authenticated to the tenant or customer by the application server transferring the provisioning codes, it can provision the phone as an AirLink gateway using the phone’s IMEI. This allows flexibility in lost phones by tying functionality and device ownership to an authenticated user rather than a particular phone. The app provides a UI for entering these codes until the application server is enabled.

The app can be used for the following purposes:

  1. Scanning and connecting to AirLink devices automatically
  1. Registering AirLink devices to the server securely
  1. Updating Pay-as-you-go status of the device securely
  1. Posting data from the device to the server with authentication
  1. Finding AirLink devices even when the app is not running, and posting their locations to the server


Mobile App Framework built on Xamarin

Platform : Xamarin

App Development Framework

Xamarin multi-platform mobile app development framework

This is Microsoft's multi-platform mobile app development framework.

Access of Bluetooth hardware requires platform specific code in Xamarin, and the AirLink App is implemented only for Android at present but can be extended to iOS with minimal additional code.

We chose Xamarin as the development environment due to it’s relative maturity compared with Flutter and larger community in case of development challenges, however we believe that an AirLink spec app can also be implemented in Flutter using the Xamarin app as a reference for functionality.

Xamarin Forms adds another layer of UI abstraction, at some cost of speed. We use Xamarin Forms for UI pages and all pages are represented in XAML.

Xamarin uses a MVVM Architecture

Material Design:

Secure Storage:

Preparing for Release:


Microsoft introduced new development framework [ .NET MAUI ] for increased code sharing across platforms, by leveraging .NET layers. This Xamarin-forms app could be converted to .NET MAUI in 2022 using the migration scripts that Microsoft has promised to provide.

NuGet packages

  • Acr.UserDialogs (
  • NetStandard.Library (2.0.3)
  • Newtonsoft.Json (13.0.1)
  • PeterO.Cbor(4.5.0)
  • Plugin.BLE (2.1.2)
  • Rg.plugins.Popup (
  • sqlite-net (1.6.292)
  • sqlite-net-pcl (1.8.116)
  • Xamarin.CommunityToolkit (1.3.2)
  • Xamarin.Essentials (1.7.0)
  • Xamarin.Forms (
  • Xamarin.Forms.PancakeView (
  • Xamarin.Forms.Visual.Material (
  • ZXing.Net.Mobile (3.1.0-beta2)
Xamarin Libraries leveraged to build the framework

Platform : Flutter

App Development Framework

Flutter multi-platform mobile app development framework

This is Google’s multi-platform mobile app development framework.

Flutter uses a layered Architecture

UI Design:

Flutter uses design widgets to make it easy to move between software that supports prototyping (e.g. Figma) and app development. This app uses the in-built Flutter widgets to display the app’s functionalities. However, they can be customized to fit the specific needs of the app, allowing you to create unique and engaging user experiences.

Flutter packages

To realize the Bluetooth requirements and other core functionality of AirLink, the AirLink app (gateway) uses the following packages:

  • line_icons: ^2.0.1
  • flutter_blue: ^0.8.0
  • cbor: ^5.0.1
  • convert: ^3.0.1
  • hex: ^0.2.0
  • flutter_secure_storage: ^5.0.2
  • flutter_dotenv: ^5.0.2
  • http: ^0.13.4
  • device_info_plus: ^3.2.2
  • flutter_barcode_scanner: ^2.0.0
  • location: ^4.3.0
  • sqflite: ^2.0.2
  • provider: ^6.0.3
  • app_settings: ^4.1.8
  • workmanager: ^0.5.0
  • permission_handler: ^10.2.0
  • timezone: ^0.9.0
Flutter Libraries leveraged to build the framework

Gateway Sync

The primary role of the AirLink gateway is to keep AirLink devices and the AirLink server in sync with respect to the state and operation of the device. There are three types of data sync:

  1. Server updates Device: Pay as you go credits after payment are the primary server update, along with client and configuration data
    AirLink Gateways or this App maps Server and Device properties
  1. Device posts time-series telemetry via primary gateway: Device posts various IoT data described in Nexus Resource Models relating to energy generation, consumption, battery use as well as productive output. In this case, the app actually masquerades as the device and posts data directly into the device's telemetry endpoint. This is enabled for the app via user input of device access token or in a production app, from the server pairing the gateway with devices via sharing of the access token automatically upon sale. Location is added by the gateway.

  1. Neighborhood watch gateway posts device advertisement: If the app finds an AirLink device that is not registered as managed by that app, it will post it to the server as a 'piggy-back' onto it's own telemetry, which the server then snips out and decides to post to the original device or forward on to the lost devices database
    AirLink Lost/Stolen Devices Flow

To convert between server-friendly JSON and Bluetooth-service friendly CBOR/.NET objects, the Json.NET and PeterO.CBOR libraries are used. Since the list of properties can vary, we use collections and read the property types = device resource models such as “/batt” and “/temp” from the Bluetooth Descriptors.

Serializing Collections
Product p1 = new Product { Name = "Product 1", Price = 99.95m, ExpiryDate = new DateTime(2000, 12, 29, 0, 0, 0, DateTimeKind.Utc), }; Product p2 = new Product { Name = "Product 2", Price = 12.50m, ExpiryDate = new DateTime(2009, 7, 31, 0, 0, 0, DateTimeKind.Utc), }; List products = new List (); products.Add(p1); products.Add(p2); string json = JsonConvert.SerializeObject(products, Formatting.Indented);

App UX Interactions

User - App - Device/Server Interactions

Code Entry Points

BleDevice.csAirLink Device ModelPlatform IndependentDescribes typical AirLink Device and properties
AirLinkDevice.csPlatform IndependentDescribes server-side interpretation of AirLink resource models
BleServer.csAndroidThe gateway device always acts as a server, and does not advertise an AirLink Advertisement packet. This server
MainActivity.csAndroidApp Business LogicStart background services
BackgroundService.csAndroidServiceBLE Advt monitoring registered, even if app exits or phone reboots
HttpsEndpoint.csPlatform IndependentSelects appropriate AirLink server endpoint based on type of transmission
IDataStore.csPlatform IndependentImplements the database to store devices found
PostData.csPlatform IndependentSends Data to AirLink server and processes errors
ProfilePageViewModel.csPlatform IndependentUI Business LogicHandles all the entries that configure the App to connect to the AirLink server
BLEDeviceDetailsViewModel.csPlatform IndependentUI Business LogicHandles a single selected BLE device, sync properties, provision etc
BLEDevicesViewModel.csPlatform IndependentUI Business LogicHandles BLE devices scan page

App Screenshots

Configuring to connect to server

First Step: Enter the information from AirLink Server and Provision the phone as a gateway on the server.

If you enter the data correctly including the tenant administrator, the gateway will provision.

Connecting to AirLink devices

Second Step: Your phone is ready to sync devices. Discover AirLink devices in the vicinity!

Once you find a device, tapping on it simply brings up a list of Nexus resources available on the device

Authorizing the gateway to the device with the Access Token

Always, when connecting to a device, we recommend that the device lock it’s properties until the (default or server) access token is supplied. Authorizing the device supplies it with the default access token.

To authorize the device, simply tap the “Authorize” button. The default access token is already saved on both the App and the device. The device will then compare its access token with this default one. Once they match, the device will be successfully authorized.

Once authorized, you can now read data from the device. The App receives CBOR encoded data from the device, and decodes it into a JSON that is more amenable to posting to the server, and displays this for each property when tapped.

Serializing and provisioning a new device and preparing it for accepting tokens

If a device has just been manufactured, it may not yet be serialized, and be locked with a default access token. Enter this token, then press “Provision” to provision the device. The app will prompt for serial number entry.

Scan or enter by hand this serial number. This is a one-time activity after which the device will forever remember it’s serial number. However if the serial number exists on the server, the provisioning will fail.

As long as a unique serial number is supplied, the server accepts the device and returns a device-specific access token, which the app saves automatically to secure storage as well as displays in the access token field

Entering Tokens

Some properties are writeable, especially true for the PAYG token property, found in the “PC” resource. Tapping this will open a prompt to enter a token. During the Provisioning stage, the token generator on the server is initialized and matched to each device’s secret. Hence, the token can be obtained from the server automatically by syncing the phone, or by manually copying the PC_tkn property value and inputting by hand while the phone is offline.

PAYG tokens are single-use and must match the individual device. If these criteria are met, the device accepts the token.

Synchronizing data with the server over the lifetime of the device

All AirLink properties can be kept in sync between the server and the individual device simply by tapping the Sync button, or using the underlying function in an automated flow in your custom version of the app

The ability of the gateway to post device data to the server (”Client Scope”) as well as pull server data into the device (”Shared Scope”) generates a success message. All failure messages can be effectively debugged using the USB-connected debug mode of Visual Studio.

Copyright 2021 Simusolar Inc

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.