📱

AirLink App

The AirLink Mobile app is a barebones communication app enabling gateway functionality i.e. end to end communication between AirLink Bluetooth® devices and an AirLink server. The app is built using the Xamarin framework and is intended to act as a base skeleton on which custom extensions can be built by 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 using the phone’s IMEI. This allows some flexibility in lost phones and such, although the App does report the phone's identifier in device telemetry. 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

Architecture

Mobile App Framework built on Xamarin

Platform

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.

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:

Next:

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.

https://docs.microsoft.com/en-us/dotnet/maui/what-is-maui

Libraries = NuGet packages (minimum version)

  • Acr.UserDialogs (7.1.0.514)
  • ble.net(1.2.1)
  • NetStandard.Library (2.0.3)
  • Newtonsoft.Json (13.0.1)
  • PeterO.Cbor(4.4.4)
  • Plugin.BLE (2.1.2)
  • Rg.plugins.Popup (2.0.0.12)
  • sqlite-net (1.6.292)
  • sqlite-net-pcl (1.8.116)
  • Xamarin.CommunityToolkit (1.2.0)
  • Xamarin.Essentials (1.7.0)
  • Xamarin.Forms (5.0.0.2012)
  • Xamarin.Forms.PancakeView (2.3.0.759)
  • Xamarin.Forms.Visual.Material (5.0.0.2125)
Xamarin 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.

    FIXME missing graphics for telemetry posts

  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

    FIXME missing graphics for unknown device posts

To convert between server-friendly JSON and Bluetooth-service friendly .NET objects, the Json.NET library is used. Since the list of properties can vary, we use collections.

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);
https://www.newtonsoft.com/json/help/html/SerializingCollections.htm

App Interactions

User - App - Device/Server Interactions

Code Organization

ComponentCategoryFunction
BackgroundService.csAndroidServiceBLE Advt monitoring registered, even if app exits or phone reboots
BleServer.csAndroidThe gateway device always acts as a server, and does not advertise an AirLink Advertisement packet. This server
BleServerCallback.csAndroid
MainActivity.csAndroidApp Business LogicStart background services
App.xamlPlatform IndependentUI Page
App.xaml.csPlatform IndependentUI Business Logic
AppShell.xamlPlatform IndependentUI Page
AppShell.xaml.csPlatform IndependentUI Business Logic
AirLinkDevice.csPlatform IndependentDescribes server-side interpretation of AirLink resource models
MainPage.xamlPlatform IndependentUI Page
MainPage.xaml.csPlatform IndependentUI Business Logic
PUEAdvertisedData.csAirLink Data StructurePlatform IndependentDescribes Advertisement properties, used to interpret and store advertisement data
PUEPayGData.csAirLink Data StructurePlatform Independent
PUETimeSeries.csAirLink Data StructurePlatform Independent
BleDevice.csAirLink Device ModelPlatform IndependentDescribes typical AirLink Device and properties
PaygUpdate.csPlatform Independent
Property.csPlatform Independent
PropertyDataBank.csPlatform Independent
Resources.csPlatform Independent
ResourceAndProperties.csPlatform Independent
ResourceDataBank.csPlatform Independent
CustomEntry.csPlatform IndependentInterface for Text input fields
DataConverter.csPlatform Independent
HttpsEndpoint.csPlatform IndependentSelects appropriate AirLink server endpoint based on type of transmission
IDataStore.csPlatform Independent
IEnvironment.csPlatform Independent
MockDataStore.csPlatform Independent
PostData.csPlatform IndependentSends Data to AirLink server and processes errors
TheTheme.csPlatform IndependentDescribes various components of the App's UI theme
PayGData.csPlatform Independent
BaseViewModel.csPlatform IndependentUI Business Logic
BluetoothServerModel.csPlatform IndependentUI Business Logic
ProfilePageViewModel.csPlatform IndependentUI Business Logic
BLEDeviceDetailsViewModel.csPlatform IndependentUI Business Logiccontroller interacting with a single selected BLE device, sync properties, provision etc
BLEDevicesViewModel.csPlatform IndependentUI Business Logiccontroller interacting with BLE devices scan page

Examples

Transmission to thingsboard.io server FIXME-needs updating

The following is an example of an advertisement resource posted to the thingsboard.io. The steps were:

  1. Mobile app scanned and saved an encoded advertisement from an AirLink development device over Bluetooth, using definitions covered in Airlink Devices.
  1. Mobile app decoded the CBOR encoded single-dimensional data structure and converted into a two-dimensional name-value pair array
  1. Mobile app appended latitude and longitude information to the array
  1. Mobile app posted to airlink.enaccess.org server using JSON, and also a cbor-encoded version in the "cd" property that is a mirror of the rest of the properties as a demonstration of reduced data size transmission. The cd array can be decoded at cbor.me.
{
"cd": "AC6263721818626473006265720062667663312E306270756148627274006361646663312E30636469641A0C908D81636C61746A2D362E37363439343235637074736A32303039313231343031646C6F6E676A33392E32343139353534676465764E616D651A0C908D81",
"cr": 24,
"ds": 0,
"er": 0,
"fv": "1.0",
"pu": "H",
"rt": 0,
"adf": "1.0",
"did": 210800001,
"lat": "-6.7649425",
"pts": "2009121401",
"long": "39.2419554",
"devName": 210800001
}

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.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.