diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 3b27802..4065e88 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -20,7 +20,7 @@ pipx inject mkdocs mkdocs-material mkdocs serve ``` -Then open [docs](http://127.0.0.1:8000/OpenSmartMeter/) in a local web browser. +Then open [docs](http://127.0.0.1:8000/AirLink-Docs/) in a local web browser. ## Writing documentation diff --git a/docs/AirLink App.md b/docs/AirLink App.md index 1052a03..ac84f22 100644 --- a/docs/AirLink App.md +++ b/docs/AirLink App.md @@ -6,201 +6,65 @@ The AirLink Mobile app is a communication app skeleton enabling gateway function 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: +The app demonstrates three different roles that can be used to build different business processes: -1. Scanning and connecting to AirLink devices automatically -2. Registering AirLink devices to the server securely -3. Updating Pay-as-you-go status of the device securely -4. Posting data from the device to the server with authentication -5. Finding AirLink devices even when the app is not running, and posting their locations to the server +1. Manufacturer Role: Registering AirLink devices to the server securely - this needs to be the first step +2. End-User Role: + 1. Scanning and connecting to AirLink devices automatically + 2. Updating Pay-as-you-go status of the device securely + 3. Posting data from the device to the server with authentication + 4. Finding AirLink devices even when the app is not running, and posting their locations to the server +3. Device Admin Role: Generating PAYGO tokens for AirLink or Angaza devices - this needs to be done before a User Role could sync the token to the device via the App -## Architecture - -![Mobile App Framework built on Xamarin](AirLink%20App/App_Architecture.png) - -Mobile App Framework built on Xamarin - -## Platform : Xamarin - -### App Development Framework (Xamarin) - -**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. - -[https://www.youtube.com/watch?v=JH8ekYJrFHs&list=PLdo4fOcmZ0oU10SXt2W58pu2L0v2dOW-1](https://www.youtube.com/watch?v=JH8ekYJrFHs&list=PLdo4fOcmZ0oU10SXt2W58pu2L0v2dOW-1) - -**Xamarin uses a MVVM Architecture:** ![By Ugaya40 - Own work, CC BY-SA 3.0, [https://commons.wikimedia.org/w/index.php?curid=19056842](https://commons.wikimedia.org/w/index.php?curid=19056842)](AirLink%20App/MVVMPattern.png) - -By Ugaya40 - Own work, CC BY-SA 3.0, [https://commons.wikimedia.org/w/index.php?curid=19056842](https://commons.wikimedia.org/w/index.php?curid=19056842) - -**Material Design:** This app uses Material Design for it’s pages: - -[Xamarin.Forms 101: Using Material Design in Xamarin Forms](https://channel9.msdn.com/Shows/XamarinShow/XamarinForms-101-Using-Material-Design-in-Xamarin-Forms) - -**Secure Storage:** This app uses secure storage to save all authentication secrets - -[Xamarin.Essentials: Secure Storage - Xamarin](https://docs.microsoft.com/en-us/xamarin/essentials/secure-storage?tabs=android) - -**Preparing for Release:** [Preparing an Application for Release - Xamarin](https://docs.microsoft.com/en-us/xamarin/android/deploy-test/release-prep/?tabs=windows#AOT_Compilation) - -**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 using the migration scripts that Microsoft has promised to provide. - -[https://docs.microsoft.com/en-us/dotnet/maui/what-is-maui](https://docs.microsoft.com/en-us/dotnet/maui/what-is-maui) - -### NuGet packages - -- Acr.UserDialogs (7.2.0.562) -- ble.net(1.2.1) -- NetStandard.Library (2.0.3) -- Newtonsoft.Json (13.0.1) -- PeterO.Cbor(4.5.0) -- 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.3.2) -- Xamarin.Essentials (1.7.0) -- Xamarin.Forms (5.0.0.2291) -- Xamarin.Forms.PancakeView (2.3.0.763-beta) -- Xamarin.Forms.Visual.Material (5.0.0.2291) -- ZXing.Net.Mobile (3.1.0-beta2) - -### Software - -Visual Studio 2019, available for Mac/Windows +## App Chronology -[https://visualstudio.microsoft.com/vs/](https://visualstudio.microsoft.com/vs/) +While AirLink Devices are the end use-case for any AirLink business case, and the AirLink server the main infrastructure needed, The AirLink App (or an equivalent hardware gateway) is the *primary enabler*. As such, much of the user activity around the lifecycle of AirLink Devices happens with the Gateway. Here, we take a look at this device lifecycle, which starts with first linking the AirLink App instance to the server. -[Visual Studio setup and to Git library instructions (Mac)](AirLink%20App/Visual%20Studio%20setup%20and%20to%20Git%20library%20instruction%201c38135f4b6b4e3db7ed0d2b3a30ccae.md) +### Configuring to connect to server (Manufacturer role) -### Dev hardware +First Step: Enter the information from AirLink Server and Provision the phone as a gateway on the server. In a production app, this information might be hardcoded or saved as credentials within the app, invisible to the user. -Computer recommendation: 8GB RAM, 128GB SSD, 2.0+ GHz processor +!!! info "Security check" + The server credentials, especially the manufacturer role, is a very powerful role that can impact all devices and data, so it should be shared only as needed and securely encoded into the app! -Test AirLink Device: BLE Development Kit or any device with BLE. +![home - credentials page - airlink.jpg](AirLink%20App/home%20-%20credentials%20page%20-%20airlink.jpg) -Test Airlink Gateway Device: Android mobile phone. +If you enter the data correctly including the tenant administrator, the app instance will be provisioned as a Gateway device on the AirLink Server, allowing data transfer operations and linking to AirLink Devices. -[Set Up Device for Development - Xamarin](https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/set-up-device-for-development) +VIDEO Placeholder: Provisioning ![3.1 PROVISION GATEWAY - Gateway provisioned successfully.jpg](AirLink%20App/3.1_PROVISION_GATEWAY_-_Gateway_provisioned_successfully.jpg) -![Xamarin Libraries leveraged to build the framework](AirLink%20App/IoT_Communications_and_Components_spec_-_App_Architecture-2.png) +### Discovering AirLink devices -Xamarin Libraries leveraged to build the framework - -## Platform : Flutter - -### App Development Framework (Flutter) - -**Flutter multi-platform mobile app development framework:** This is Google’s multi-platform mobile app development framework. - -[https://www.youtube.com/watch?v=VPvVD8t02U8](https://www.youtube.com/watch?v=VPvVD8t02U8) - -**Flutter uses a layered Architecture:** [Flutter architectural overview](https://docs.flutter.dev/resources/architectural-overview) - -**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](AirLink%20App/IoT_Arch_Open-Source_App_Architecture.jpeg) - -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](AirLink%20App/IoT_Communications_and_Components_spec_-_App_Architecture-2%201.png) - - AirLink Gateways or this App maps Server and Device properties - -2. 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. +Second Step: Your phone is ready to sync devices. Discover AirLink devices in the vicinity! (The AirLink App looks for CBOR-encoded advertisements as an identifying signature to filter out AirLink devices from other BLE devices that might be present). -3. 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**](AirLink_Unknown_Device_Flow.png) - - **AirLink Lost/Stolen Devices Flow** - -To convert between server-friendly JSON and Bluetooth-service friendly CBOR/.NET objects, the [Json.NET](http://Json.NET) and [PeterO.CBOR](https://github.com/peteroupc/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](https://www.newtonsoft.com/json/help/html/SerializingCollections.htm) - -## App UX Interactions - -![User - App - Device/Server Interactions](AirLink%20App/IoT_Communications_and_Components_spec_-_App_Architecture.png) - -User - App - Device/Server Interactions - -## App Components - -[GitHub - EnAccess/Airlink-App](https://github.com/EnAccess/Airlink-App) - -| Component | Category | Function | -| --- | --- | --- | -| BleDevice.cs | Platform Independent,AirLink Device Model | Describes typical AirLink Device and properties | -| AirLinkDevice.cs | Platform Independent | Describes server-side interpretation of AirLink resource models | -| BleServer.cs | Android | The gateway device always acts as a server, and does not advertise an AirLink Advertisement packet. This server | -| MainActivity.cs | Android,App Business Logic | Start background services | -| BackgroundService.cs | Service,Android | BLE Advt monitoring registered, even if app exits or phone reboots | -| HttpsEndpoint.cs | Platform Independent | Selects appropriate AirLink server endpoint based on type of transmission | -| IDataStore.cs | Platform Independent | Implements the database to store devices found | -| PostData.cs | Platform Independent | Sends Data to AirLink server and processes errors | -| ProfilePageViewModel.cs | UI Business Logic,Platform Independent | Handles all the entries that configure the App to connect to the AirLink server | -| BLEDeviceDetailsViewModel.cs | UI Business Logic,Platform Independent | Handles a single selected BLE device, sync properties, provision etc | -| BLEDevicesViewModel.cs | UI Business Logic,Platform Independent | Handles BLE devices scan page | +![1. Devices view.jpg](AirLink%20App/1._Devices_view.jpg) -## App Screenshots +Once you find a device, tapping on it simply brings up a list of Nexus resources available on the device -### Configuring to connect to server +![2. Resources view.jpg](AirLink%20App/2._Resources_view.jpg) -First Step: Enter the information from AirLink Server and Provision the phone as a gateway on the server. +!!! info "Device Emulator App" -![3. Profile view.jpg](AirLink%20App/3._Profile_view.jpg) + 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](https://github.com/EnAccess/AirLink-Devices) under the Device Simulator folder. -If you enter the data correctly including the tenant administrator, the gateway will provision. + ![Device Simulator app running on an Android-9 phone](AirLink%20App/AirLink_BLE_Simulator.jpg) -![3.1 PROVISION GATEWAY - Gateway provisioned successfully.jpg](AirLink%20App/3.1_PROVISION_GATEWAY_-_Gateway_provisioned_successfully.jpg) + Device Simulator app running on an Android-9 phone -### Connecting to AirLink devices + This app allows you to: -Second Step: Your phone is ready to sync devices. Discover AirLink devices in the vicinity! + 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 -![1. Devices view.jpg](AirLink%20App/1._Devices_view.jpg) + 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. -Once you find a device, tapping on it simply brings up a list of Nexus resources available on the device - -![2. Resources view.jpg](AirLink%20App/2._Resources_view.jpg) + The [source code](https://github.com/EnAccess/AirLink-Devices) is not meant to actually process tokens, but could act as a starting point if Android Airlink devices are being developed. ### 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. +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. ![2.1 READ RESOURCE - Data is empty.jpg](AirLink%20App/2.1_READ_RESOURCE_-_Data_is_empty.jpg) @@ -226,6 +90,13 @@ As long as a unique serial number is supplied, the server accepts the device and ![2.6 Device provisioned successfully.jpg](AirLink%20App/2.6_Device_provisioned_successfully.jpg) +!!! info "Solaris or Angaza devices" + Angaza devices can be provisioned via the AirLink app as well! All you need are your Angaza API credentials for the manufacturer role. Enter these in the server (see rule-chains section): + [AirLink Server Setup](https://youtu.be/6GAqmAPOLjI) + + For Solaris devices, uploading a CSV is the only option: + ![Solaris device provisioning in AirLink](AirLink%20App/home%20-%20device%20list%20page%20-%20device%20details%20page%20-%20provisioning%20input%20with%20type%20expanded.jpg) + ### 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. @@ -236,6 +107,10 @@ PAYG tokens are single-use and must match the individual device. If these criter ![2.8 SUCCESS - Success on Token entry.jpg](AirLink%20App/2.8_SUCCESS_-_Success_on_Token_entry.jpg) +### Generating Tokens + +The AirLink App also demonstrates the ability to generate PAYG Tokens for AirLink and Angaza devices. + ### 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 @@ -246,11 +121,66 @@ The ability of the gateway to post device data to the server (”Client Scope” ![2.10 SUCCESS - Success on syncing data.jpg](AirLink%20App/2.10_SUCCESS_-_Success_on_syncing_data.jpg) +## Architecture + +### App Development Framework: Flutter + +**Flutter is Google’s multi-platform mobile app development framework.** + +[https://www.youtube.com/watch?v=VPvVD8t02U8](https://www.youtube.com/watch?v=VPvVD8t02U8) + +**Flutter uses a layered Architecture:** [Flutter architectural overview](https://docs.flutter.dev/resources/architectural-overview) + +**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. + +!!! info "Flutter packages" + To realize the BLE requirements and other core functionality of AirLink, the AirLink app (gateway) uses the following packages: + + - cbor: ^6.1.1 + - convert: ^3.0.1 + - hex: ^0.2.0 + - flutter_secure_storage: ^6.0.0 + - http: ^1.1.0 + - device_info_plus: ^3.2.2 + - flutter_barcode_scanner: ^2.0.0 + - location: ^5.0.3 + - provider: ^6.0.2 + - app_settings: ^5.1.1 + - workmanager: ^0.5.1 + - permission_handler: ^11.0.0 + - path_provider: ^2.0.14 + - equatable: ^2.0.5 + - dartz: ^0.10.1 + - get_it: ^7.6.0 + - internet_connection_checker: ^1.0.0+1 + - hive: ^2.2.3 + - hive_flutter: ^1.1.0 + - flutter_dotenv: ^5.1.0 + - flutter_blue_plus: ^1.16.2 + +## Gateway as a Sync relay - mapping property names + +The primary role of an AirLink gateway is to keep AirLink devices (BLE, or GSM devices that can also work without the gateway) and the AirLink server (availabke on GSM/Wifi) 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](AirLink%20App/IoT_Communications_and_Components_spec_-_App_Architecture-2%201.png) + + AirLink Gateways or this App maps Server and Device properties +2. 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. +3. Neighborhood watch gateway posts device advertisement: If the app finds an AirLink device that is not registered as managed by that app instance (e.g. that customer doesn't have permissions for that device but another customer might), it will post the device's advertisement data 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**](AirLink_Unknown_Device_Flow.png) + +To convert between server-friendly JSON and Bluetooth-service friendly CBOR/.NET objects, the [Json.NET](http://Json.NET) and [PeterO.CBOR](https://github.com/peteroupc/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](https://www.newtonsoft.com/json/help/html/SerializingCollections.htm) + --- -![syo9FlQN.jpg](AirLink%20App/syo9FlQN.jpg) +![Simusolar Inc](Simusolar_logo.png) -Copyright 2021 Simusolar Inc +Copyright 2023 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: diff --git a/docs/AirLink App/1._Devices_view.jpg b/docs/AirLink App/1._Devices_view.jpg deleted file mode 100644 index 3030767..0000000 Binary files a/docs/AirLink App/1._Devices_view.jpg and /dev/null differ diff --git a/docs/AirLink App/2.10_SUCCESS_-_Success_on_syncing_data.jpg b/docs/AirLink App/2.10_SUCCESS_-_Success_on_syncing_data.jpg deleted file mode 100644 index c004860..0000000 Binary files a/docs/AirLink App/2.10_SUCCESS_-_Success_on_syncing_data.jpg and /dev/null differ diff --git a/docs/AirLink App/2.1_READ_RESOURCE_-_Data_is_empty.jpg b/docs/AirLink App/2.1_READ_RESOURCE_-_Data_is_empty.jpg deleted file mode 100644 index 438aa9f..0000000 Binary files a/docs/AirLink App/2.1_READ_RESOURCE_-_Data_is_empty.jpg and /dev/null differ diff --git a/docs/AirLink App/2.2_AUTHORIZE_-_Device_authorized.jpg b/docs/AirLink App/2.2_AUTHORIZE_-_Device_authorized.jpg deleted file mode 100644 index 4d34867..0000000 Binary files a/docs/AirLink App/2.2_AUTHORIZE_-_Device_authorized.jpg and /dev/null differ diff --git a/docs/AirLink App/2.3_READ_RESOURCE_-_Data_is_displayed.jpg b/docs/AirLink App/2.3_READ_RESOURCE_-_Data_is_displayed.jpg deleted file mode 100644 index 967750d..0000000 Binary files a/docs/AirLink App/2.3_READ_RESOURCE_-_Data_is_displayed.jpg and /dev/null differ diff --git a/docs/AirLink App/2.4_PROVISION_-_Choice_for_serialization.jpg b/docs/AirLink App/2.4_PROVISION_-_Choice_for_serialization.jpg deleted file mode 100644 index 301c7fc..0000000 Binary files a/docs/AirLink App/2.4_PROVISION_-_Choice_for_serialization.jpg and /dev/null differ diff --git a/docs/AirLink App/2.5_TYPE_SERIAL_NUMBER.jpg b/docs/AirLink App/2.5_TYPE_SERIAL_NUMBER.jpg deleted file mode 100644 index 8bce11f..0000000 Binary files a/docs/AirLink App/2.5_TYPE_SERIAL_NUMBER.jpg and /dev/null differ diff --git a/docs/AirLink App/2.6_Device_provisioned_successfully.jpg b/docs/AirLink App/2.6_Device_provisioned_successfully.jpg deleted file mode 100644 index 4e8fbbe..0000000 Binary files a/docs/AirLink App/2.6_Device_provisioned_successfully.jpg and /dev/null differ diff --git a/docs/AirLink App/2.7_ENTER_PAYG_TOKEN.jpg b/docs/AirLink App/2.7_ENTER_PAYG_TOKEN.jpg deleted file mode 100644 index 353b248..0000000 Binary files a/docs/AirLink App/2.7_ENTER_PAYG_TOKEN.jpg and /dev/null differ diff --git a/docs/AirLink App/2.8_SUCCESS_-_Success_on_Token_entry.jpg b/docs/AirLink App/2.8_SUCCESS_-_Success_on_Token_entry.jpg deleted file mode 100644 index 30a3bb5..0000000 Binary files a/docs/AirLink App/2.8_SUCCESS_-_Success_on_Token_entry.jpg and /dev/null differ diff --git a/docs/AirLink App/2.9_SYNC_-_Syncing_data.jpg b/docs/AirLink App/2.9_SYNC_-_Syncing_data.jpg deleted file mode 100644 index 947eb7d..0000000 Binary files a/docs/AirLink App/2.9_SYNC_-_Syncing_data.jpg and /dev/null differ diff --git a/docs/AirLink App/2._Resources_view.jpg b/docs/AirLink App/2._Resources_view.jpg deleted file mode 100644 index 83ff299..0000000 Binary files a/docs/AirLink App/2._Resources_view.jpg and /dev/null differ diff --git a/docs/AirLink App/3.1_PROVISION_GATEWAY_-_Gateway_provisioned_successfully.jpg b/docs/AirLink App/3.1_PROVISION_GATEWAY_-_Gateway_provisioned_successfully.jpg deleted file mode 100644 index f4cf53f..0000000 Binary files a/docs/AirLink App/3.1_PROVISION_GATEWAY_-_Gateway_provisioned_successfully.jpg and /dev/null differ diff --git a/docs/AirLink App/3._Profile_view.jpg b/docs/AirLink App/3._Profile_view.jpg deleted file mode 100644 index 002dfe4..0000000 Binary files a/docs/AirLink App/3._Profile_view.jpg and /dev/null differ diff --git a/docs/AirLink App/AirLink_BLE_Simulator.jpg b/docs/AirLink App/AirLink_BLE_Simulator.jpg new file mode 100644 index 0000000..1f4c2c4 Binary files /dev/null and b/docs/AirLink App/AirLink_BLE_Simulator.jpg differ diff --git a/docs/AirLink App/AirLink_Data_Flow.png b/docs/AirLink App/AirLink_Data_Flow.png index 772a969..ba53610 100644 Binary files a/docs/AirLink App/AirLink_Data_Flow.png and b/docs/AirLink App/AirLink_Data_Flow.png differ diff --git a/docs/AirLink App/MVVMPattern.png b/docs/AirLink App/MVVMPattern.png deleted file mode 100644 index 87e4ab8..0000000 Binary files a/docs/AirLink App/MVVMPattern.png and /dev/null differ diff --git a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae.md b/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae.md deleted file mode 100644 index e2843e6..0000000 --- a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae.md +++ /dev/null @@ -1,35 +0,0 @@ -# Visual Studio setup and to Git library instructions (Mac) - -Download [Xamarin - Visual Studio for Mac (~2+GB)](https://visualstudio.microsoft.com/vs/mac/xamarin/). If you want to build your application for iOS, you will also need Xcode (12+GB), which Visual studio will prompt you to install once it is done installing itself. - -## Setting up the GitHub repository - -In Github Airlink repository: Copy the HTTPS clone link: - -![Screen Shot 2021-10-04 at 10.53.38 AM.png](Visual%20Studio%20setup%20and%20to%20Git%20library%20instruction%201c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.38_AM.png) - -In the visual studio menu, instead of creating a new project from the startup popup screen, go to Menu and select Clone Repository... - -![Screen Shot 2021-10-04 at 10.52.50 AM.png](Visual%20Studio%20setup%20and%20to%20Git%20library%20instruction%201c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.50_AM.png) - -Paste the link copied from Github - -![Screen Shot 2021-10-04 at 10.53.55 AM.png](Visual%20Studio%20setup%20and%20to%20Git%20library%20instruction%201c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.55_AM.png) - -That's it! Visual studio will create the project. You might need to allow it to download additional components as required. - -![Screen Shot 2021-10-04 at 10.52.11 AM.png](Visual%20Studio%20setup%20and%20to%20Git%20library%20instruction%201c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.11_AM.png) - -To post updates to the project, you will need to request developer access from EnAccess as well as setup a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -[A more secure GitHub Experience](https://devblogs.microsoft.com/visualstudio/a-more-secure-github-experience/?WT.mc_id=modinfra-0000-abartolo) - -We recommend that you use GitHub Desktop to push changes rather than VisualStudio for Mac due to ease of use: - -[GitHub Desktop](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwjPipmGwbbzAhVIUxoKHRIfAcUQFnoECBgQAQ&url=https%3A%2F%2Fdesktop.github.com%2F&usg=AOvVaw3Q4aArCExy0qKbKQYeMfD4) - -### For Apple chip (M1 and above) users, setting up the debugger - -Note: to access Bluetooth and run the AirLink App, you will still need an actual phone to debug - -[Setting Up an M1 Mac for Xamarin Development](https://montemagno.com/setting-up-an-m1-mac-for-xamarin-development/) diff --git a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.11_AM.png b/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.11_AM.png deleted file mode 100644 index 15e1a81..0000000 Binary files a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.11_AM.png and /dev/null differ diff --git a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.50_AM.png b/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.50_AM.png deleted file mode 100644 index f0c6eb6..0000000 Binary files a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.52.50_AM.png and /dev/null differ diff --git a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.38_AM.png b/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.38_AM.png deleted file mode 100644 index 86888ec..0000000 Binary files a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.38_AM.png and /dev/null differ diff --git a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.55_AM.png b/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.55_AM.png deleted file mode 100644 index 2e060d6..0000000 Binary files a/docs/AirLink App/Visual Studio setup and to Git library instruction 1c38135f4b6b4e3db7ed0d2b3a30ccae/Screen_Shot_2021-10-04_at_10.53.55_AM.png and /dev/null differ diff --git a/docs/AirLink App/home - credentials page - airlink.jpg b/docs/AirLink App/home - credentials page - airlink.jpg new file mode 100644 index 0000000..59fd528 Binary files /dev/null and b/docs/AirLink App/home - credentials page - airlink.jpg differ diff --git a/docs/AirLink App/home - credentials page - angaza.jpg b/docs/AirLink App/home - credentials page - angaza.jpg new file mode 100644 index 0000000..47a24f0 Binary files /dev/null and b/docs/AirLink App/home - credentials page - angaza.jpg differ diff --git a/docs/AirLink App/home - device list page - device details page - provisioning choices.jpg b/docs/AirLink App/home - device list page - device details page - provisioning choices.jpg new file mode 100644 index 0000000..3aea1d9 Binary files /dev/null and b/docs/AirLink App/home - device list page - device details page - provisioning choices.jpg differ diff --git a/docs/AirLink App/home - device list page - device details page - provisioning input with type expanded.jpg b/docs/AirLink App/home - device list page - device details page - provisioning input with type expanded.jpg new file mode 100644 index 0000000..688f6c4 Binary files /dev/null and b/docs/AirLink App/home - device list page - device details page - provisioning input with type expanded.jpg differ diff --git a/docs/AirLink App/home - device list page - device details page - provisioning input.jpg b/docs/AirLink App/home - device list page - device details page - provisioning input.jpg new file mode 100644 index 0000000..300134b Binary files /dev/null and b/docs/AirLink App/home - device list page - device details page - provisioning input.jpg differ diff --git a/docs/AirLink App/home - device list page - device details page - transfer payg token.jpg b/docs/AirLink App/home - device list page - device details page - transfer payg token.jpg new file mode 100644 index 0000000..9f25b58 Binary files /dev/null and b/docs/AirLink App/home - device list page - device details page - transfer payg token.jpg differ diff --git a/docs/AirLink App/home - device list page - device details page.jpg b/docs/AirLink App/home - device list page - device details page.jpg new file mode 100644 index 0000000..cf23374 Binary files /dev/null and b/docs/AirLink App/home - device list page - device details page.jpg differ diff --git a/docs/AirLink App/home - device list page - no permissions.jpg b/docs/AirLink App/home - device list page - no permissions.jpg new file mode 100644 index 0000000..b002239 Binary files /dev/null and b/docs/AirLink App/home - device list page - no permissions.jpg differ diff --git a/docs/AirLink App/home - device list page.jpg b/docs/AirLink App/home - device list page.jpg new file mode 100644 index 0000000..eb981c4 Binary files /dev/null and b/docs/AirLink App/home - device list page.jpg differ diff --git a/docs/AirLink App/home - payg token page - enter credit.jpg b/docs/AirLink App/home - payg token page - enter credit.jpg new file mode 100644 index 0000000..d5e9735 Binary files /dev/null and b/docs/AirLink App/home - payg token page - enter credit.jpg differ diff --git a/docs/AirLink App/home - payg token page - search for device.jpg b/docs/AirLink App/home - payg token page - search for device.jpg new file mode 100644 index 0000000..c0fe706 Binary files /dev/null and b/docs/AirLink App/home - payg token page - search for device.jpg differ diff --git a/docs/AirLink App/home - payg token page - token generated.jpg b/docs/AirLink App/home - payg token page - token generated.jpg new file mode 100644 index 0000000..81e8922 Binary files /dev/null and b/docs/AirLink App/home - payg token page - token generated.jpg differ diff --git a/docs/AirLink App/home - payg token page.jpg b/docs/AirLink App/home - payg token page.jpg new file mode 100644 index 0000000..83b7263 Binary files /dev/null and b/docs/AirLink App/home - payg token page.jpg differ diff --git a/docs/AirLink Devices.md b/docs/AirLink Devices.md index 89fd799..dd873e9 100644 --- a/docs/AirLink Devices.md +++ b/docs/AirLink Devices.md @@ -1,39 +1,24 @@ # AirLink Devices -![bluetooth-logo-color-black.svg](AirLink%20Devices/bluetooth-logo-color-black.svg) +![bluetooth-logo.png](AirLink%20Devices/bluetooth-logo.png) -**Preface:** A note on Bluetooth® SIG requirements, Nov 2021 +**Preface:** A note on Bluetooth® SIG requirements, Oct 2023 -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](https://www.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. +Our understanding is that the Bluetooth® Special Interest Group requires that any entity (manufacturer or distributor) branding/re-branding/incorporating and selling devices with Bluetooth® must register as a member with the SIG at [bluetooth.com](https://www.bluetooth.com), as well as declare the product and the Bluetooth® component being used. This is true for resellers, distributors, and all commercial sales. We understand that the final sold 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. +Although *membership* is free to start, each *declaration* of products within the membership portal costs $9,600 as of this writing. Multiple products using the same Bluetooth® component (technically this is defined as 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, using a global reference list maintained at bluetooth.com. The SIG conducts regular reviews of compliance of a company, based on products listed with the Bluetooth® brand on the company's website. 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.* +*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.* --- -## Development Reference +## Development Resources -### Device Emulator App +### Range Testing -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](https://github.com/EnAccess/AirLink-Devices) under the Device Simulator folder. - -![Device Simulator app running on an Android-9 phone](AirLink%20Devices/Screenshot_20230208-141454_AirLink_BLE_Simulator.jpg) - -Device Simulator app running on an Android-9 phone - -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](https://github.com/EnAccess/AirLink-Devices) is not meant to actually process tokens, but could act as a starting point if Android Airlink devices are being developed. +How far will an AirLink Bluetooth® link go? [We tested the range from a basic smartphone to a device.](AirLink%20Devices/Range%20Testing%20Results.md) ### Nordic Device Firmware @@ -49,15 +34,20 @@ A Nordic DVK-BLE kit running AirLink demo firmware Programming the Nordic kit with AirLink demo firmware -### BLE Range Testing +The open-source example firmware is fully featured for the device lifecycle as well as has AirLink PAYG out of the box - and is sufficiently flexible to quickly create new use cases for new types of devices. See the rest of this page for concepts on which the firmware is built, or jump directly into the firmware source code itself - +[More information on AirLink example Firmware](https://github.com/EnAccess/AirLink-Devices/blob/8d761f0fafe73d0706947c977d440aed2da71f2f/Nordic%20Firmware%20-%20PAYG%20output%20and%20Thermometer/README.md) + +--- -[Range Testing Results](AirLink%20Devices/Range%20Testing%20Results%20ef4c4ece8fba4542830d415dc0fa1a42.md) +## AirLink Communication Protocol -The Simusolar team tested how far we could find an AirLink device from in presence of walls and with clear line of sight. +The AirLink communication protocol relies on the Open Connectivity Foundation (OCF)'s "Resource Model", where related properties are grouped into a named resource. OCF resource models map well to REST/JSON implementations with endpoints as resources and key-value pairs as properties and values. Similarly, they can also map to Bluetooth Services and properties. -### From the OCF specification +[More on OCF models](https://openconnectivity.org/specs/OCF_Resource_to_BLE_Mapping_Specification_v2.2.2.pdf) -[](https://openconnectivity.org/specs/OCF_Resource_to_BLE_Mapping_Specification_v2.2.2.pdf) +### Resource models + +The OCF bridging recommendation covers GATT properties well, however it does not cover Advertising nor does it cover a resource *enumerator* explicitly. Resource discovery using named models (e.g. /batt for battery) is a key idea of OCF models however, and AirLink implements this by using BLE Descriptors. AirLink Devices adopt the [Open Connectivity Foundation's Resource Model bridging guidelines](https://openconnectivity.org/specs/OCF_Resource_to_BLE_Mapping_Specification_v2.2.3.pdf) 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. @@ -69,29 +59,21 @@ AirLink Devices adopt the [Open Connectivity Foundation's Resource Model bridgin ![AirLink%20Devices/Screen_Shot_2021-07-13_at_11.34.54_AM.png](AirLink%20Devices/Screen_Shot_2021-07-13_at_11.34.54_AM.png) ---- - -## AirLink Protocol Design - -### 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 AirLink resource models:** -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 +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 follow an 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](https://angaza.github.io/nexus-channel-models/resource_type_spec.html) 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](https://nexus.angaza.com/keycode.html), with planned future support for [OpenPAYGO Tokens](https://github.com/EnAccess/OpenPAYGO-Token) - 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](http://thingsboard.io) servers - 5. Optional: Power use and Productive Output data logging + 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](http://thingsboard.io) servers + 5. Optional: Power use and Productive Output data logging -### Device Discovery Services +### Device Resource Discovery 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 @@ -100,56 +82,38 @@ A gateway device reads this resource while scanning for devices (before a connec ### AirLink Advertisement /advt -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| | | | | | -| “mac” | 6 | Default | AirLink Advt Resource 1.0 | Bluetooth MAC ID Automatically available in BLE Advertisement. Sent to AirLink server as advt_mac converted to all-caps text e.g. BD:DD:EE:FF:AA:BB | -| Array Cbor header | 1 | CBOR Header | | Array declaration header of 8 elements | -| BLE Advt resource version "rv" | 3 | Float (uint16_t),Read-Only | AirLink Advt Resource 1.0 | 10 (major/minor digits), 2 Bytes = 2^(8*2) = 65536 i.e from 0-65535 (0xFFFF) The format of the data version according to the protocol used. First integer is major number, second minor | -| Device Fault Status "ft", cbor encoded | 1 | Read-Only,Integer (uint8_t),Scope: Time-series | AirLink Advt Resource 1.0 | From 0-23. Any Universal error that should be executed with priority. -Error 0 = Unprovisioned, -Error 1 = Lost track of PAYG credit (battery off), -Error 2 = Battery Fault -Error 3 = Output Overcurrent/Overtemp - details in ftd field in timeseries data -Error 23 = Lost device (e.g. when device doesn't find other Bluetooth devices from it's 'pack'. -Errors 4-22 are manufacturer specific | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| -------------------------------------- | ------ | ---------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| “mac” | 6 | Default | AirLink Advt Resource 1.0 | Bluetooth MAC ID Automatically available in BLE Advertisement. Sent to AirLink server as advt_mac converted to all-caps text e.g. BD:DD:EE:FF:AA:BB | +| Array Cbor header | 1 | CBOR Header | | Array declaration header of 8 elements | +| BLE Advt resource version "rv" | 3 | Float (uint16_t),Read-Only | AirLink Advt Resource 1.0 | 10 (major/minor digits), 2 Bytes = 2^(8*2) = 65536 i.e from 0-65535 (0xFFFF) The format of the data version according to the protocol used. First integer is major number, second minor | +| Device Fault Status "ft", cbor encoded | 1 | Read-Only,Integer (uint8_t),Scope: Time-series | AirLink Advt Resource 1.0 | From 0-23. Any Universal error that should be executed with priority. Error 0 = Unprovisioned, Error 1 = Lost track of PAYG credit (battery off), Error 2 = Battery Fault, Error 3 = Output Overcurrent/Overtemp - details in ftd field in timeseries data, Error 23 = Lost device (e.g. when device doesn't find other Bluetooth devices from it's 'pack'. Errors 4-22 are manufacturer specific | | Device Airlink ID "aid" + Cbor header 4 bytes | 5 | Read-Only,Optional | AirLink Advt Resource 1.0 | 2^(8*4) = 4,294,967,296 numeric device ids. The ID of the device that resides in manufacturer registry. AirLink uses the BLE mac ID to uniquely identify an unknown device so this is only a human readable option | -| Timestamp last pulled from gateway or network "gts" | 5 | Read-Only,Byte Array | AirLink Advt Resource 1.0 | Linux epoch format, expires in Y2035 | -| Device provisioning status "pst" | 1 | Integer (uint8_t),Read-Only,Scope: Time-series | AirLink Advt Resource 1.0 | 2^8 = 256 i.e from 0-255 (0xFF) The status of the device according to manufacturer definition. It can be -1-unserialized, -2-unprovisioned, -3-disabled, -4-recall, -5-stolen, -6-9-Manufacturer custom -The range is from 1-9. If not supported then 0 | +| Timestamp last pulled from gateway or network "gts" | 5 | Read-Only,Byte Array | AirLink Advt Resource 1.0 | Linux epoch format, expires in Y2035 | +| Device provisioning status "pst" | 1 | Integer (uint8_t),Read-Only,Scope: Time-series | AirLink Advt Resource 1.0 | 2^8 = 256 i.e from 0-255 (0xFF) The status of the device according to manufacturer definition. It can be 1-unserialized, 2-unprovisioned, 3-disabled, 4-recall, 5-stolen, 6-9-Manufacturer custom. The range is from 1-9. If not supported then 0 | | Device FW Ver "fv" | 2 | Read-Only,Integer (uint8_t) | AirLink Advt Resource 1.0 | 2^8 = 256 i.e from 0-255 (0xFF). Shows the version of the hardware firmware. It ranges from 01-99. If not supported then 0 | -| Device PayG Credit Remaining "cr" | 5 | Read-Only,Scope: Time-series | AirLink Advt Resource 1.0 | 2^(8*2) = 65536 i.e from 0-65535 (0xFFFF). The value remaining for the device to OFF. Range is from 01-9999 +| Device PayG Credit Remaining "cr" | 5 | Read-Only, Scope: Time-series | AirLink Advt Resource 1.0 | 2^(8*2) = 65536 i.e from 0-65535 (0xFFFF). The value remaining for the device to OFF. Range is from 01-9999 If non payg device then 0 | -| Expected RSSI at 1 meter “s1” | 2 | Read-Only,Scope: Client,Integer (uint8_t) | AirLink Advt Resource 1.0 | Expected signal strength of this Bluetooth device for a receiver (phone / other Bluetooth device) placed at 1 meter, used for distance estimation. -Value is in negative dB (e.g. a value of s1=70 is considered to be -70dB) -Calibrated during device prototyping, and adjusted by each device for any changes in it’s transmit power with respect to the transmit power at calibration time (e.g. +2dB transmit power during advertising ⇒ s1=68, if 0dB transmit power at calibration time had yielded an RSSI of -70dB). | -| Spare | 1 | | AirLink Advt Resource 1.0 | Can be used for Manufacturer specific information, for example type of asset, data about status etc | -| Dummy “dmy” | | Optional | AirLink Advt Resource 1.0 | Some Bluetooth chips require fixed-length advts, this dummy can make up for variation in other properties lengths | -| Device Manufacturer ID "mid" added by gateway device | | Integer (uint16_t),Read-Only,Mandatory,Scope: Time-series | AirLink Advt Resource 1.0 | From Device advertisement - all manufacturers and end brands of BLE products need to be registered with Bluetooth SIG, as well as EnAccess as tenants to use this service | +| Expected RSSI at 1 meter “s1” | 2 | Read-Only,Scope: Client,Integer (uint8_t) | AirLink Advt Resource 1.0 | Expected signal strength of this Bluetooth device for a receiver (phone / other Bluetooth device) placed at 1 meter, used for distance estimation. Value is in negative dB (e.g. a value of s1=70 is considered to be -70dB). Calibrated during device prototyping, and adjusted by each device for any changes in it’s transmit power with respect to the transmit power at calibration time (e.g. +2dB transmit power during advertising ⇒ s1=68, if 0dB transmit power at calibration time had yielded an RSSI of -70dB). | +| Spare | 1 | | AirLink Advt Resource 1.0 | Can be used for Manufacturer specific information, for example type of asset, data about status etc | +| Dummy “dmy” | | Optional | AirLink Advt Resource 1.0 | Some Bluetooth chips require fixed-length advts, this dummy can make up for variation in other properties lengths | +| Device Manufacturer ID "mid" added by gateway device | | Integer (uint16_t),Read-Only,Mandatory,Scope: Time-series | AirLink Advt Resource 1.0 | From Device advertisement - all manufacturers and end brands of BLE products need to be registered with Bluetooth SIG, as well as EnAccess as tenants to use this service | ### Location Resource /loc -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| Array Cbor header | 1 | CBOR Header | | Array declaration header of 8 elements | -| Timestamp last pulled from gateway or network "gts" | 5 | Read-Only,Byte Array | Location Resource 1.0 | Linux epoch format, expires in Y2035 | -| Gateway Manufacturer ID "gmid" added by gateway device | 2 | Integer (uint16_t),Read-Only,Mandatory | Location Resource 1.0 | How can we prevent one manufacturer from messing up the other's IDs? | -| Gateway AirLink ID "gid" added by gateway device | 5 | Integer (uint32_t) | Location Resource 1.0 | | -| Longitude "ln" added by gateway device | | String | Location Resource 1.0 | Added by gateway device reporting location of non-gateway device, 10 octets | -| Latitude "lt" added by gatway device | | String | Location Resource 1.0 | Added by gateway device reporting location of non-gateway device, 10 octets | -| Location accuracy "la" added by gateway device | | String | Location Resource 1.0 | Added by gateway device reporting location of non-gateway device, 6 octets | -| Device Signal strength "dss" added by gateway device | | String | Location Resource 1.0 | Added by gateway device reporting the exactly location of the device from a gateway expressed in dBm | -| Timeseries Timestamp “ts” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | TImestamp of when the data is recorded | -| Timeseries History Index “thi” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | Whenever this property is available that means it is a timeseries resource. -thi = 0, means there is no more timeseries data. -Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | -| Dummy “dmy” | | Optional | AirLink PUE Timeseries 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ------------------------------------------------------ | ------ | -------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------- | +| Array Cbor header | 1 | CBOR Header | | Array declaration header of 8 elements | +| Timestamp last pulled from gateway or network "gts" | 5 | Read-Only,Byte Array | Location Resource 1.0 | Linux epoch format, expires in Y2035 | +| Gateway Manufacturer ID "gmid" added by gateway device | 2 | Integer (uint16_t),Read-Only,Mandatory | Location Resource 1.0 | How can we prevent one manufacturer from messing up the other's IDs? | +| Gateway AirLink ID "gid" added by gateway device | 5 | Integer (uint32_t) | Location Resource 1.0 | | +| Longitude "ln" added by gateway device | | String | Location Resource 1.0 | Added by gateway device reporting location of non-gateway device, 10 octets | +| Latitude "lt" added by gatway device | | String | Location Resource 1.0 | Added by gateway device reporting location of non-gateway device, 10 octets | +| Location accuracy "la" added by gateway device | | String | Location Resource 1.0 | Added by gateway device reporting location of non-gateway device, 6 octets | +| Device Signal strength "dss" added by gateway device | | String | Location Resource 1.0 | Added by gateway device reporting the exactly location of the device from a gateway expressed in dBm | +| Timeseries Timestamp “ts” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | TImestamp of when the data is recorded | +| Timeseries History Index “thi” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | Whenever this property is available that means it is a timeseries resource. |thi = 0, means there is no more timeseries data.Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | +| Dummy “dmy” | | Optional | AirLink PUE Timeseries 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | ### Device Config Service @@ -160,38 +124,32 @@ Any number greater than zero can be used for indicating which data proceeds espe ### AirLink Device Provisioning Resource /dcfg -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | -| Device Provisioning resource version "rv" | 3 | Float (uint16_t),Read-Only | AirLink Device Provisioning 1.0 | 10 (major/minor digits) | -| Device ID "did" + Cbor header 20 bytes | 21 | Mandatory,Read-Write | AirLink Device Provisioning 1.0 | UTF-8 coded device serial numbers | -| AirLink ID "aid" + Cbor header 4 bytes | 5 | Mandatory,Read-Write | AirLink Device Provisioning 1.0 | 2^(8*4) = 4,294,967,296 numeric device ids. The ID of the device that maps 1:1 in manufacturer registry to serial number | -| PayG Units accepted "pul" | 10 | Unencrypted,Read-Only,Mandatory,String,Scope: Client | AirLink Device Provisioning 1.0 | CSV list of acceptable Units e.g. "l" for liters, "h,d" for hours and days | -| Payg Token starting code "psc" | 5 | Write-Only,Scope: Shared | AirLink Device Provisioning 1.0 | 1-day token, | -| PayG Unit "pu" | 1 | Encrypted,Read-Write,Mandatory,String,Scope: Shared,Scope: Client | AirLink Device Provisioning 1.0 | 36^1 The unit of the PayG update, it can be minutes, hours, days, months and years. [s-seconds, m-minutes, h-hours, d- days, M-months, Y-years] | -| Provisioning Status "pst" | 1 | Unencrypted,Integer,Mandatory,Read-Write,Scope: Client | AirLink Device Provisioning 1.0 | Reflected in Advt packet also. It can be unprovisioned, disabled, recall, stolen, Cash, Loan. The range is from 1-9. If not supported then 0 | -| Server access Token "sat" | 21 | Encrypted,String,Mandatory,Write-Only,Scope: Shared | AirLink Device Provisioning 1.0 | 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. | -| Current Unix Time “cut” | 4 | Write-Only | AirLink Device Provisioning 1.0 | This property can be used to sync or correct system time. | -| Productive Output Set Limit "opmax" | 4 | Read-Write,Integer,Scope: Shared,Scope: Client | AirLink Device Provisioning 1.0 | Max brightness, max water flow etc set for safety / environmental reasons / other reasons | -| Dummy “dmy” | | Optional | AirLink Device Provisioning 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ----------------------------------------- | ------ | ----------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | +| Device Provisioning resource version "rv" | 3 | Float (uint16_t),Read-Only | AirLink Device Provisioning 1.0 | 10 (major/minor digits) | +| Device ID "did" + Cbor header 20 bytes | 21 | Mandatory,Read-Write | AirLink Device Provisioning 1.0 | UTF-8 coded device serial numbers | +| AirLink ID "aid" + Cbor header 4 bytes | 5 | Mandatory,Read-Write | AirLink Device Provisioning 1.0 | 2^(8*4) = 4,294,967,296 numeric device ids. The ID of the device that maps 1:1 in manufacturer registry to serial number | +| PayG Units accepted "pul" | 10 | Unencrypted,Read-Only,Mandatory,String,Scope: Client | AirLink Device Provisioning 1.0 | CSV list of acceptable Units e.g. "l" for liters, "h,d" for hours and days | +| Payg Token starting code "psc" | 5 | Write-Only,Scope: Shared | AirLink Device Provisioning 1.0 | 1-day token, | +| PayG Unit "pu" | 1 | Encrypted,Read-Write,Mandatory,String,Scope: Shared,Scope: Client | AirLink Device Provisioning 1.0 | 36^1 The unit of the PayG update, it can be minutes, hours, days, months and years. [s-seconds, m-minutes, h-hours, d- days, M-months, Y-years] | +| Provisioning Status "pst" | 1 | Unencrypted,Integer,Mandatory,Read-Write,Scope: Client | AirLink Device Provisioning 1.0 | Reflected in Advt packet also. It can be unprovisioned, disabled, recall, stolen, Cash, Loan. The range is from 1-9. If not supported then 0 | +| Server access Token "sat" | 21 | Encrypted,String,Mandatory,Write-Only,Scope: Shared | AirLink Device Provisioning 1.0 | 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. | +| Current Unix Time “cut” | 4 | Write-Only | AirLink Device Provisioning 1.0 | This property can be used to sync or correct system time. | +| Productive Output Set Limit "opmax" | 4 | Read-Write,Integer,Scope: Shared,Scope: Client | AirLink Device Provisioning 1.0 | Max brightness, max water flow etc set for safety / environmental reasons / other reasons | +| Dummy “dmy” | | Optional | AirLink Device Provisioning 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | ### AirLink Client Provisioning Resource /ccfg -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | -| Client Provisioning resource version "rv" | 3 | Float (uint16_t),Read-Only | | 10 (major/minor digits) | -| Customer Name -"cn" | 16 | Unencrypted,String,Optional,Read-Write,Scope: Shared,Scope: Client | AirLink Client Provisioning 1.0 | Requested 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. | -| Customer's Phone "cp" - | 16 | Unencrypted,String,Optional,Read-Write,Scope: Shared,Scope: Client | AirLink Client Provisioning 1.0 | Requested 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 | -| Readable ID "rid" + Cbor header 2 bytes | 6 | Mandatory,Read-Write,Scope: Shared,Scope: Client | AirLink Client Provisioning 1.0 | 2^(8*4) = 4,294,967,296 numeric device ids or payment reference or any number that device should display | -| Provisioning Status "pst" | 1 | Unencrypted,Integer,Mandatory,Read-Write,Scope: Client | AirLink Client Provisioning 1.0 | Reflected in Advt packet also. It can be unprovisioned, disabled, recall, stolen, Cash, Loan. The range is from 1-9. If not supported then 0 | -| Server Auth Token "sat" encryption overhead | 20 | Encrypted,String,Mandatory,Write-Only,Scope: Shared | AirLink Client Provisioning 1.0 | has a 20-char device authentication token unique to each device | - -### Nexus Command Resource /nxc - -[Nexus Command Resource /nxc](AirLink%20Devices/Nexus%20Command%20Resource%20nxc%20ed4247090ba4475583e05f72cc537ff0.csv) +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | +| Client Provisioning resource version "rv" | 3 | Float (uint16_t),Read-Only | | 10 (major/minor digits) | +| Customer Name "cn" | 16 | Unencrypted,String,Optional,Read-Write,Scope: Shared,Scope: Client | AirLink Client Provisioning 1.0 | Requested 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. | +| Customer's Phone "cp"| 16 | Unencrypted,String,Optional,Read-Write,Scope: Shared,Scope: Client | AirLink Client Provisioning 1.0 | Requested 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 | +| Readable ID "rid" + Cbor header 2 bytes | 6 | Mandatory,Read-Write,Scope: Shared,Scope: Client | AirLink Client Provisioning 1.0 | 2^(8*4) = 4,294,967,296 numeric device ids or payment reference or any number that device should display | +| Provisioning Status "pst" | 1 | Unencrypted,Integer,Mandatory,Read-Write,Scope: Client | AirLink Client Provisioning 1.0 | Reflected in Advt packet also. It can be unprovisioned, disabled, recall, stolen, Cash, Loan. The range is from 1-9. If not supported then 0 | +| Server Auth Token "sat" encryption overhead | 20 | Encrypted,String,Mandatory,Write-Only,Scope: Shared | AirLink Client Provisioning 1.0 | has a 20-char device authentication token unique to each device | ### PUE Use Service @@ -203,141 +161,109 @@ We envision 2 primary usages of a productive use asset: ### PAYG Credit Resource /pc -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor map header | 1 | Read-Write | | encapsulating the rest of the properties | -| AirLink PAYG resource version "rv" | 3 | Float (uint16_t),Read-Only | | 10 (major/minor digits) | -| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | PAYG Credit 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | -| Device PayG Credit Remaining "re" | 5 | Mandatory,Integer,Read-Write,Scope: Time-series | PAYG Credit 1.0 | should be The value remaining for the device to OFF. - -For Write, a Nexus Channel Link must be established otherwise read-only, updated via token | -| PayG Unit "pu" | 1 | Mandatory,String,Read-Only | AirLink Device Provisioning 1.0 | 36^1 The unit of the PayG update, it can be minutes, hours, days, months and years. [s-seconds, m-minutes, h-hours, d- days, M-months, Y-years] | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ---------------------------------- | ------ | ----------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cbor map header | 1 | Read-Write | | encapsulating the rest of the properties | +| AirLink PAYG resource version "rv" | 3 | Float (uint16_t),Read-Only | | 10 (major/minor digits) | +| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | PAYG Credit 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | +| Device PayG Credit Remaining "re" | 5 | Mandatory,Integer,Read-Write,Scope: Time-series | PAYG Credit 1.0 | should be The value remaining for the device to OFF. For Write, a Nexus Channel Link must be established otherwise read-only, updated via token | +| PayG Unit "pu" | 1 | Mandatory,String,Read-Only | AirLink Device Provisioning 1.0 | 36^1 The unit of the PayG update, it can be minutes, hours, days, months and years. [s-seconds, m-minutes, h-hours, d- days, M-months, Y-years] | | PayG SwitchOffTime “sot” | 6 | DateTime,Optional,Scope: Time-series,Read-Write | PAYG Credit 1.0 | Linux epoch format, expires in Y2035. The datetime at which payg credit currently expires | -| Mode "mo" | 1 | Read-Write,Scope: Shared Attr | PAYG Credit 1.0 | mode of device i.e. leading/following etc - -For Write, a Nexus Channel Link must be established otherwise read-only, updated via token | -| PayG Token "tkn" | 5 | Write-Only,Encrypted,Integer,Scope: Shared Attr | PAYG Credit 1.0 | . Accepted by device only if valid. No read token to ensure unsecured gateways cannot act maliciously. | +| Mode "mo" | 1 | Read-Write,Scope: Shared Attr | PAYG Credit 1.0 | mode of device i.e. leading/following etc. For Write, a Nexus Channel Link must be established otherwise read-only, updated via token | +| PayG Token "tkn" | 5 | Write-Only,Encrypted,Integer,Scope: Shared Attr | PAYG Credit 1.0 | . Accepted by device only if valid. No read token to ensure unsecured gateways cannot act maliciously. | | Last Added PayG Credit "lcr" | 2 | Read-Only,Integer,Optional,Scope: Time-series | PAYG Credit 1.0 | Historical last PayG credit update duration. Range is from 01-9999 | | Timestamp at which PayG remaining was calculated "pts" | 6 | DateTime,Optional,Read-Only,Scope: Time-series | PAYG Credit 1.0 | Linux 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] | | Timestamp of last PAYG Update to device "lts" | 6 | Read-Only,DateTime,Optional,Scope: Time-series | PAYG Credit 1.0 | Linux epoch format, expires in Y2035, readonly - Historical last PayG update Timestamp | | Current Local Time "lt" | 6 | Read-Write,DateTime,Optional,Scope: Time-series | PAYG Credit 1.0 | Linux 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 | | Timeseries Timestamp “ts” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | TImestamp of when the data is recorded | -| Timeseries History Index “thi” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | Whenever this property is available that means it is a timeseries resource. -thi = 0, means there is no more timeseries data. -Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | -| Dummy “dmy” | | Optional | AirLink PUE Timeseries 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | +| Timeseries History Index “thi” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | Whenever this property is available that means it is a timeseries resource. thi = 0, means there is no more timeseries data. Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | +| Dummy “dmy” | | Optional | AirLink PUE Timeseries 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | ### AirLink Temperature Resource /temp -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor map header | 1 | Read-Write | TEMP 1.0 | encapsulating the rest of the properties | -| TEMP resource version "rv" | 3 | Float (uint16_t),Read-Only | TEMP 1.0 | 10 (major/minor digits) | -| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | PAYG Credit 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | -| Current Temperature "temp" | 5 | Read-Only,Mandatory,Scope: Time-series | TEMP 1.0 | 0-128C in 1/2 degree increments | -| Max Temperature "tmax" | 5 | Read-Only,Optional,Scope: Time-series | TEMP 1.0 | 0-128C in 1/2 degree increments | -| Max Temperature "tmin" | 5 | Read-Only,Optional,Scope: Time-series | TEMP 1.0 | 0-128C in 1/2 degree increments | -| Temperature upper limit threshold "hlim" | 5 | Read-Write,Optional,Scope: Client Attr | TEMP 1.0 | 0-128C in 1/2 degree increments | -| Temperature lower limit threshold "llim" | 5 | Read-Write,Optional,Scope: Client Attr | TEMP 1.0 | 0-128C in 1/2 degree increments | -| Timeseries Timestamp “ts” | 4 | Read-Only | TEMP 1.0 | TImestamp of when the data is recorded | -| Timeseries History Index “thi” | 4 | Read-Only | TEMP 1.0 | Whenever this property is available that means it is a timeseries resource. -thi = 0, means there is no more timeseries data. -Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | -| Dummy “dmy” | | Optional | TEMP 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ---------------------------------------- | ------ | -------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cbor map header | 1 | Read-Write | TEMP 1.0 | encapsulating the rest of the properties | +| TEMP resource version "rv" | 3 | Float (uint16_t),Read-Only | TEMP 1.0 | 10 (major/minor digits) | +| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | PAYG Credit 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | +| Current Temperature "temp" | 5 | Read-Only,Mandatory,Scope: Time-series | TEMP 1.0 | 0-128C in 1/2 degree increments | +| Max Temperature "tmax" | 5 | Read-Only,Optional,Scope: Time-series | TEMP 1.0 | 0-128C in 1/2 degree increments | +| Max Temperature "tmin" | 5 | Read-Only,Optional,Scope: Time-series | TEMP 1.0 | 0-128C in 1/2 degree increments | +| Temperature upper limit threshold "hlim" | 5 | Read-Write,Optional,Scope: Client Attr | TEMP 1.0 | 0-128C in 1/2 degree increments | +| Temperature lower limit threshold "llim" | 5 | Read-Write,Optional,Scope: Client Attr | TEMP 1.0 | 0-128C in 1/2 degree increments | +| Timeseries Timestamp “ts” | 4 | Read-Only | TEMP 1.0 | TImestamp of when the data is recorded | +| Timeseries History Index “thi” | 4 | Read-Only | TEMP 1.0 | Whenever this property is available that means it is a timeseries resource. |thi = 0, means there is no more timeseries data.Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | +| Dummy “dmy” | | Optional | TEMP 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | ### AirLink Productive Use Resource /pu -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | -| AirLink TimeSeries resource version "rv" | 4 | Float (uint16_t),Read-Only | AirLink PUE Timeseries 1.0 | 1.0 | -| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | AirLink PUE Timeseries 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | -| Time Series Data Format "df" | 1 | Mandatory,Read-Only,Integer | AirLink PUE Timeseries 1.0 | following DF in OpenPAYGO Metrics (in case device has GSM). 0 if not used | -| Productive Equipment Type "pue" | 2 | Read-Only,Integer,Mandatory | AirLink PUE Timeseries 1.0 | e.g. "Surface Pump", "Borehole Pump", "Fishing Light" etc preregistered types | -| BatteryDevice "bat" | 1 | Read-Only,Integer,Mandatory | AirLink PUE Timeseries 1.0 | Yes/No Yes = it has an internal or system level battery | -| Device Fault "ft" | 1 | Mandatory,Read-Only,Integer,Enum | AirLink PUE Timeseries 1.0 | Same as Advertisement packet | -| Device Fault Data "ftd" | 2 | Integer,ByteArray,Optional | AirLink PUE Timeseries 1.0 | Can contain details of error e.g. over-pressure error could contain max pressure measured | -| seconds since data measured "ss" | 6 | Read-Only,Mandatory,DateTime | AirLink PUE Timeseries 1.0 | seconds passed since last /pu data pull by any gateway device - presumption is that gateway transmits the data to server. Useful for devices that store a rolling history of data | -| Productive Output Primary Metric "op" | 4 | Optional Grp 1,Read-Only,Integer | AirLink PUE Timeseries 1.0 | e.g. Water output for pumps in Litres/hour | -| Productive Output Primary Set Limit ”opl” | 4 | Optional Grp 1,Read-Write,Integer | AirLink PUE Timeseries 1.0 | The limit of primary product Output -Eg. 100L/H for the pump that can go to 500 L/H | -| Productive Output Secondary Metric "os" | 4 | Optional Grp 1,Read-Only,Integer | AirLink PUE Timeseries 1.0 | e.g. Pressure for pumps in kPa (1kPa = 10cm water or 0.1 bar) | -| Productive Output Secondary Set Limit “osl” | 4 | Optional Grp 1,Read-Write,Integer | AirLink PUE Timeseries 1.0 | The limit of secondary product Output -Eg. Could be a pressure of 5kPa for the pump that can preduce the pressure of 10kPa | -| Timeseries Timestamp “ts” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | TImestamp of when the data is recorded | -| Timeseries History Index “thi” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | Whenever this property is available that means it is a timeseries resource. -thi = 0, means there is no more timeseries data. -Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | -| Dummy “dmy” | | Optional | AirLink PUE Timeseries 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ----------------------------------------------------------------------------------- | ------ | ------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | +| AirLink TimeSeries resource version "rv" | 4 | Float (uint16_t),Read-Only | AirLink PUE Timeseries 1.0 | 1.0 | +| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | AirLink PUE Timeseries 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | +| Time Series Data Format "df" | 1 | Mandatory,Read-Only,Integer | AirLink PUE Timeseries 1.0 | following DF in OpenPAYGO Metrics (in case device has GSM). 0 if not used | +| Productive Equipment Type "pue" | 2 | Read-Only,Integer,Mandatory | AirLink PUE Timeseries 1.0 | e.g. "Surface Pump", "Borehole Pump", "Fishing Light" etc preregistered types | +| BatteryDevice "bat" | 1 | Read-Only,Integer,Mandatory | AirLink PUE Timeseries 1.0 | Yes/No Yes = it has an internal or system level battery | +| Device Fault "ft" | 1 | Mandatory,Read-Only,Integer,Enum | AirLink PUE Timeseries 1.0 | Same as Advertisement packet | +| Device Fault Data "ftd" | 2 | Integer,ByteArray,Optional | AirLink PUE Timeseries 1.0 | Can contain details of error e.g. over-pressure error could contain max pressure measured | +| seconds since data measured "ss" | 6 | Read-Only,Mandatory,DateTime | AirLink PUE Timeseries 1.0 | seconds passed since last /pu data pull by any gateway device - presumption is that gateway transmits the data to server. Useful for devices that store a rolling history of data | +| Productive Output Primary Metric "op" | 4 | Optional Grp 1,Read-Only,Integer | AirLink PUE Timeseries 1.0 | e.g. Water output for pumps in Litres/hour | +| Productive Output Primary Set Limit ”opl” | 4 | Optional Grp 1,Read-Write,Integer | AirLink PUE Timeseries 1.0 | The limit of primary product Output Eg. 100L/H for the pump that can go to 500 L/H | +| Productive Output Secondary Metric "os" | 4 | Optional Grp 1,Read-Only,Integer | AirLink PUE Timeseries 1.0 | e.g. Pressure for pumps in kPa (1kPa = 10cm water or 0.1 bar) | +| Productive Output Secondary Set Limit “osl” | 4 | Optional Grp 1,Read-Write,Integer | AirLink PUE Timeseries 1.0 | The limit of secondary product Output Eg. Could be a pressure of 5kPa for the pump that can preduce the pressure of 10kPa | +| Timeseries Timestamp “ts” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | TImestamp of when the data is recorded | +| Timeseries History Index “thi” | 4 | Read-Only | AirLink PUE Timeseries 1.0 | Whenever this property is available that means it is a timeseries resource. |thi = 0, means there is no more timeseries data. Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | +| Dummy “dmy” | | Optional | AirLink PUE Timeseries 1.0 | Some Bluetooth chips require fixed-length characteristics, this dummy can make up for variation in other properties lengths | ### Energy Consumption Resource /eout -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | -| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | energy consumption 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | -| Voltage (milliVolts) "vo" | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | Output voltage depending on data format registered by manufacturer | -| Current (centiAmps) "ao" | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | Output current depending on data format registered by manufacturer | -| Current Limit (centiAmps) "aol" | 4 | Optional,Integer,Read-Write | energy consumption 1.0 | Current limit setting | -| Power (deciWatts) "po" | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | Output power depending on data format registered by manufacturer | -| eo | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | 'Energy consumed' in deciwatt-hours(Wh / 10). Computed over a time window defined by egs and egp | -| eos | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | 'Energy consumed start'. Minutes in the past (minutes ago) when the reported eg value began accumulation | -| eop | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | 'Energy consumed period'. Minutes since egs over which the value of eg was accumulated. For example, if egs is 60, and egp is 60, the value of eg represents the watt-hours generated during the past hour | -| Timeseries Timestamp “ts” | 4 | Read-Only | energy consumption 1.0 | TImestamp of when the data is recorded | -| Timeseries History Index “thi” | 4 | Read-Only | energy consumption 1.0 | Whenever this property is available that means it is a timeseries resource. -thi = 0, means there is no more timeseries data. -Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | -| Dummy “dmy” | | Optional | energy consumption 1.0 | Some Bluetooth chips require fixed-length Characteristics, this dummy can make up for variation in other properties lengths | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ---------------------------------- | ------ | ---------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | +| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | energy consumption 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | +| Voltage (milliVolts) "vo" | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | Output voltage depending on data format registered by manufacturer | +| Current (centiAmps) "ao" | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | Output current depending on data format registered by manufacturer | +| Current Limit (centiAmps) "aol" | 4 | Optional,Integer,Read-Write | energy consumption 1.0 | Current limit setting | +| Power (deciWatts) "po" | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | Output power depending on data format registered by manufacturer | +| eo | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | 'Energy consumed' in deciwatt-hours(Wh / 10). Computed over a time window defined by egs and egp | +| eos | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | 'Energy consumed start'. Minutes in the past (minutes ago) when the reported eg value began accumulation | +| eop | 4 | Optional,Read-Only,Integer,Source: Time-series | energy consumption 1.0 | 'Energy consumed period'. Minutes since egs over which the value of eg was accumulated. For example, if egs is 60, and egp is 60, the value of eg represents the watt-hours generated during the past hour | +| Timeseries Timestamp “ts” | 4 | Read-Only | energy consumption 1.0 | TImestamp of when the data is recorded | +| Timeseries History Index “thi” | 4 | Read-Only | energy consumption 1.0 | Whenever this property is available that means it is a timeseries resource. | thi = 0, means there is no more timeseries data. Any number greater than zero can be used for indicating which data proceeds especially when the timestamp is the same. | +| Dummy “dmy” | | Optional | energy consumption 1.0 | Some Bluetooth chips require fixed-length Characteristics, this dummy can make up for variation in other properties lengths | ### Energy Generation Resource /ein -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | -| Voltage (milliVolts) "vi" | 4 | Read-Only,Integer,Optional | energy generation 1.0 | Input voltage depending on data format registered by manufacturer. We will start with PV in controllers and Output in FL | -| Current (centiAmps) "ai" | 4 | Read-Write,Integer,Optional | energy generation 1.0 | Input current depending on data format registered by manufacturer. We will start with PV in controllers and Output in FL | -| Power (deciWatts) "pi" | 4 | Integer,Optional,Read-Only | energy generation 1.0 | Input power depending on data format registered by manufacturer. We will start with PV in controllers and Output in FL | -| Type of source "st" | 1 | Mandatory,Read-Write,Enum,Integer | energy generation 1.0 | Type of power generator. Known types - -0 = Disconnected/None - autodetected -1 = DC Solar - autodetected -2 = AC Grid/microgrid (as a source) - autodetected -3 = DC Grid/microgrid (as a source) - from gateway -4 = AC Wind power - from gateway -5 = DC Wind power - from gateway -6 = AC Hydro power - from gateway -7 = DC Hydro power - from gateway -8 = AC Petrol/Diesel Generator - from gateway -100 = Unknown - from gateway | +| Resource Property | Octets | Qualifiers | Nx Resource | Description | +| ------------------------- | ------ | --------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | +| Voltage (milliVolts) "vi" | 4 | Read-Only,Integer,Optional | energy generation 1.0 | Input voltage depending on data format registered by manufacturer. We will start with PV in controllers and Output in FL | +| Current (centiAmps) "ai" | 4 | Read-Write,Integer,Optional | energy generation 1.0 | Input current depending on data format registered by manufacturer. We will start with PV in controllers and Output in FL | +| Power (deciWatts) "pi" | 4 | Integer,Optional,Read-Only | energy generation 1.0 | Input power depending on data format registered by manufacturer. We will start with PV in controllers and Output in FL | +| Type of source "st" | 1 | Mandatory,Read-Write,Enum,Integer | energy generation 1.0 | Type of power generator. Known types - 0 = Disconnected/None - autodetected, 1 = DC Solar - autodetected, 2 = AC Grid/microgrid (as a source) - autodetected, 3 = DC Grid/microgrid (as a source) - from gateway, 4 = AC Wind power - from gateway, 5 = DC Wind power - from gateway, 6 = AC Hydro power - from gateway, 7 = DC Hydro power - from gateway, 8 = AC Petrol/Diesel Generator - from gateway, 100 = Unknown - from gateway | | eg | 4 | Optional,Read-Only,Integer | energy generation 1.0 | 'Energy generated' in deciwatt-hours(Wh / 10). Computed over a time window defined by egs and egp. | | egs | 4 | Optional,Read-Only,Integer | energy generation 1.0 | 'Energy generation start'. Minutes in the past (minutes ago) when the reported eg value began accumulation. | | egp | 4 | Optional,Read-Only,Integer | energy generation 1.0 | 'Energy generation period'. Minutes since egs over which the value of eg was accumulated. For example, if egs is 60, and egp is 60, the value of eg represents the watt-hours generated during the past hour. | ### Battery Resource /batt -| Resource Property | Octets | Qualifiers | Nx Resource | Description | -| --- | --- | --- | --- | --- | -| cbor header | 1 | Read-Write | | encapsulating the rest of the properties | -| Timeseries History remaining “tsh” | 2 | Read-Only,Optional,Scope: Time-series | PAYG Credit 1.0 | Any resource with one or more timeseries properties is enabled with this optional property which can indicate that the device has stored historical data while offline that it can sequentially upload to the gateway via multiple reads | -| Bat Voltage mV "vb" | 4 | Read-Only,Integer,Optional Grp 3,Scope: Time-series | Battery 1.0 | Only for Battery Device | -| Bat charging or discharge current mA "ib" | 4 | Read-Only,Integer,Optional Grp 3,Scope: Time-series | Battery 1.0 | Only for Battery Device | -| Bat Pct "cp" | 3 | Optional Grp 3,Read-Only,Integer,Scope: Time-series | Battery 1.0 | Only for Battery Device, charge percentage | -| Charging Status "cs" | 1 | Enum,Optional Grp 3,Scope: Time-series | Battery 1.0 | 0 = No Data -1 = Charging - fast -2 = Charging - slow / trickle -3 = Discharging | -| Alert Threshold (%) "th" | 3 | Read-Write,Optional Grp 3,Integer,Scope: Time-series | Battery 1.0 | | -| Low battery "lb" | 1 | Bool,Optional Grp 3,Scope: Time-series | Battery 1.0 | 0: cp>th -1: cpth 1: cp - - - bluetooth-logo-color-black - Created with Sketch. - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/AirLink Devices/bluetooth-logo.png b/docs/AirLink Devices/bluetooth-logo.png new file mode 100644 index 0000000..7743d89 Binary files /dev/null and b/docs/AirLink Devices/bluetooth-logo.png differ diff --git a/docs/AirLink Server.md b/docs/AirLink Server.md index 7fb0301..f540980 100644 --- a/docs/AirLink Server.md +++ b/docs/AirLink Server.md @@ -15,8 +15,6 @@ Follow the tenant configuration section in AirLink builds a structure on top of a standard [Thingsboard.io](http://Thingsboard.io) professional edition server. The only, minimal customization is the addition of a rule node to generate PAYG tokens, which is not a default part of Thingsboard. A Thingsboard PE server is a ‘multi-tenant’ server, which means several separated businesses can run their IoT devices from a single server without visibility into the other tenants data. This setup makes it a perfect candidate for a centrally hosted server that can onboard new participants in the AirLink community. ***Please familiarize yourself with [http://thingsboard.io/](http://thingsboard.io/) documentation before reading the rest of this page!*** -[How we chose Thingsboard for AirLink Server](AirLink%20Server/How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933.md) - In the figure, the “AirLink Tenant” is the main location of the IoT setup of a particular tenant, which can be very different from the next tenant. In fact, we setup a second “Lost & Found Tenant”, also referred in this documentation as “Neighborhood Watch”, which is intended to be a common repository for tenant gateways who find AirLink devices that don’t belong to them but want to help locate them. This documentation serves as the reference to setup your own tenant in a way that is AirLink compliant. The bulk of the setup is very simple, and the only relatively complex configuration which is the “Rule Chain”, can be imported from a JSON file available in the [AirLink Server repository](https://github.com/EnAccess/AirLink-Server). @@ -25,23 +23,23 @@ This documentation serves as the reference to setup your own tenant in a way tha AirLink Server Tenant Setup -| Business Need | Business Concepts | Thingsboard Concepts | -| --- | --- | --- | -| Devices provision themselves | Technician,ProvisionDevice | API Token,Gateway,Integration,Provisioning,Device AuthToken,Rule-chain Script | -| AirLink uses nexus channel resource models ie standard device types | AirLink | Attributes,Device Profiles | -| Simusolar uses Aeris globalSIM in PAYG** gateways | Aeris VPN,First PAYG Server | Integration,Device AuthToken,Gateway | -| Phone or solar panel controls device | AirLink | Device AuthToken,Device Group | -| Device belongs to customer | PAYG Customer,PAYG Box ID,System ID,Sales Order | Customer,Device,Integration,API Token | -| Orders make Customers | Sales Order,PAYG Customer | Customer,Asset | -| CBOR transfer over HTTP/MQTT | AirLink | Integration,Data Converter | -| Loan platform updates credits | PAYG Credit,Financing,Webi | Integration,API Token | -| Device heeds PAYG credits | Financing | Integration,Device AuthToken | -| AirLink uses Nexus Keycode or Solaris OpenPAYGO Token | AirLink,Token Automation | Rule-chain Script,Attributes | -| Device data saved | Callhome Data,Graphs and Maps | Device,Data Converter,Rule-chain Script,Device AuthToken | -| Partners can see referred customer data | Graphs and Maps,PAYG Credit,PAYG Customer | Data Chart,Customer Group,Entity View Group | -| Technicians update devices | Technician,ProvisionDevice,DFU,Service Swap,Debug Data | DFU,Gateway,Device,Device AuthToken,User Group,Data Converter,Integration,Asset,Asset Group | -| Simusolar operates in several countries with inter-country asset movement | Centralized IT | Asset Group,Asset,User Group | -| Simusolar franchises payg functionality | Distributor,PAYG Credit,Graphs and Maps,Token Automation,Debug Data | Customer Hierarchy,Customer Group,Multi-tenancy | +| Business Need | Business Concepts | Thingsboard Concepts | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Devices provision themselves | Technician,ProvisionDevice | API Token,Gateway,Integration,Provisioning,Device AuthToken,Rule-chain Script | +| AirLink uses nexus channel resource models ie standard device types | AirLink | Attributes,Device Profiles | +| Simusolar uses Aeris globalSIM in PAYG** gateways | Aeris VPN,First PAYG Server | Integration,Device AuthToken,Gateway | +| Phone or solar panel controls device | AirLink | Device AuthToken,Device Group | +| Device belongs to customer | PAYG Customer,PAYG Box ID,System ID,Sales Order | Customer,Device,Integration,API Token | +| Orders make Customers | Sales Order,PAYG Customer | Customer,Asset | +| CBOR transfer over HTTP/MQTT | AirLink | Integration,Data Converter | +| Loan platform updates credits | PAYG Credit,Financing,Webi | Integration,API Token | +| Device heeds PAYG credits | Financing | Integration,Device AuthToken | +| AirLink uses Nexus Keycode or Solaris OpenPAYGO Token | AirLink,Token Automation | Rule-chain Script,Attributes | +| Device data saved | Callhome Data,Graphs and Maps | Device,Data Converter,Rule-chain Script,Device AuthToken | +| Partners can see referred customer data | Graphs and Maps,PAYG Credit,PAYG Customer | Data Chart,Customer Group,Entity View Group | +| Technicians update devices | Technician,ProvisionDevice,DFU,Service Swap,Debug Data | DFU,Gateway,Device,Device AuthToken,User Group,Data Converter,Integration,Asset,Asset Group | +| Simusolar operates in several countries with inter-country asset movement | Centralized IT | Asset Group,Asset,User Group | +| Simusolar franchises payg functionality | Distributor,PAYG Credit,Graphs and Maps,Token Automation,Debug Data | Customer Hierarchy,Customer Group,Multi-tenancy | ### Test entities @@ -70,10 +68,10 @@ Two main roles are defined, Tenant Admin (first assigned along with tenant) who ### Device Provisioning Flow in AirLink Server -| Device State | Gateway Action | -| --- | --- | -| No Serial # | Program Serial # via BLE to Device | -| Has Serial #, but not Provisioned | Act as Application Server: using Tenant Admin or Customer User credentials (login + password) +| Device State | Gateway Action | +| --------------------------------- | --------------------------------------------------------------------------------------------- | +| No Serial # | Program Serial # via BLE to Device | +| Has Serial #, but not Provisioned | Act as Application Server: using Tenant Admin or Customer User credentials (login + password) | 1. Generate Server Auth Token (SAT) and Airlink ID (aid) 2. Provision Device to Devices Profile* in Server and get DeviceUUID @@ -115,37 +113,34 @@ The following are the major attribute types and their scopes in a basic AirLink Screenshot from AirLink server showing Attributes and Telemetry. Telemetry is always client-scope or 'device side' -[Attribute Scopes for AirLink resource properties](AirLink%20Server/Attribute%20Scopes%20for%20AirLink%20resource%20properties%2081cd9ab605c54348a6c03bbef738dbd2.csv) - CBOR data types are defined here: [https://datatracker.ietf.org/doc/html/rfc7049#section-2.1](https://datatracker.ietf.org/doc/html/rfc7049#section-2.1) -| NX resource | rtr | Resource Property | key | rtr_key | Qualifiers | CBOR Type | Description | -| --- | --- | --- | --- | --- | --- | --- | --- | -| AirLink Device Provisioning 1.0 | prd | Server Auth Token | sat | prd_sat | String,Mandatory,Scope: Shared | 3 | 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.0 | prd | Provisioning Status | pst | prd_pst | Mandatory,Scope: Shared,Integer (uint8_t) | 0 | Reflected 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.0 | prd | PayG Unit | pu | prd_pu | Mandatory,String,Scope: Shared | 3 | 36^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.0 | prd | PayG Token starting code | psc | prd_psc | Scope: Shared,String | 3 | 1-day token, | -| AirLink Device Provisioning 1.0 | prd | PayG Units accepted | pul | prd_pul | Mandatory,String,Scope: Device | 3 | CSV list of acceptable Units e.g. "l" for liters, "h,d" for hours and days | -| AirLink Client Provisioning 1.0 | prc | Provisioning Status | pst | prc_pst | Mandatory,Integer (uint8_t),Scope: Shared | 0 | Reflected 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.0 | prc | Readable ID + Cbor header 2 bytes | rid | prc_rid | Mandatory,Integer (uint32_t),Scope: Shared | 26 | 2^(8*4) = 4,294,967,296 numeric device ids or payment reference or any number that device should display | -| AirLink Client Provisioning 1.0 | prc | Customer's Phone | cp | prc_cp | String,Optional,Scope: Shared | 3 | Requested 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.0 | prc | Customer Name | cn | prc_cn | String,Optional,Scope: Shared | 3 | Requested 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.0 | nxc | Nexus COSE command | cmd | nxc_cmd | Scope: Shared | 3 | Upto 120 bytes for Nexus Channel Passthrough commands | -| AirLink PAYG 1.0 | pyg | Current Server Time | lt | pyg_lt | Optional,Scope: Device | | Linux 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.0 | pyg | Timestamp of last PAYG Update to device | lts | pyg_lts | Optional,Scope: Device | | Linux epoch format, expires in Y2035, readonly - Historical last PayG update Timestamp | -| AirLink PAYG 1.0 | pyg | Timestamp at which PayG remaining was calculated | ts | pyg_ts | Optional,Scope: Device | | Linux 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.0 | pyg | Last Added PayG Credit | lcr | pyg_lcr | Optional,Scope: Device | | Historical last PayG credit update duration. Range is from 01-9999 | -| AirLink PAYG 1.0 | pyg | PayG Token | tkn | pyg_tkn | Scope: Shared | | SipHash token. Accepted by device only if valid. No read token to ensure unsecured gateways cannot act maliciously. | -| PAYG Credit 1.0 | pyg | Mode | mo | pyg_mo | Not Implemented,Scope: Shared | | mode of device i.e. leading/following etc +| NX resource | rtr | Resource Property | key | rtr_key | Qualifiers | CBOR Type | Description | +| ------------------------------- | --- | ------------------------------------------------ | --- | ------- | ------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| AirLink Device Provisioning 1.0 | prd | Server Auth Token | sat | prd_sat | String,Mandatory,Scope: Shared | 3 | 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.0 | prd | Provisioning Status | pst | prd_pst | Mandatory,Scope: Shared,Integer (uint8_t) | 0 | Reflected 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.0 | prd | PayG Unit | pu | prd_pu | Mandatory,String,Scope: Shared | 3 | 36^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.0 | prd | PayG Token starting code | psc | prd_psc | Scope: Shared,String | 3 | 1-day token, | +| AirLink Device Provisioning 1.0 | prd | PayG Units accepted | pul | prd_pul | Mandatory,String,Scope: Device | 3 | CSV list of acceptable Units e.g. "l" for liters, "h,d" for hours and days | +| AirLink Client Provisioning 1.0 | prc | Provisioning Status | pst | prc_pst | Mandatory,Integer (uint8_t),Scope: Shared | 0 | Reflected 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.0 | prc | Readable ID + Cbor header 2 bytes | rid | prc_rid | Mandatory,Integer (uint32_t),Scope: Shared | 26 | 2^(8*4) = 4,294,967,296 numeric device ids or payment reference or any number that device should display | +| AirLink Client Provisioning 1.0 | prc | Customer's Phone | cp | prc_cp | String,Optional,Scope: Shared | 3 | Requested 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.0 | prc | Customer Name | cn | prc_cn | String,Optional,Scope: Shared | 3 | Requested 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 PAYG 1.0 | pyg | Current Server Time | lt | pyg_lt | Optional,Scope: Device | | Linux 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.0 | pyg | Timestamp of last PAYG Update to device | lts | pyg_lts | Optional,Scope: Device | | Linux epoch format, expires in Y2035, readonly - Historical last PayG update Timestamp | +| AirLink PAYG 1.0 | pyg | Timestamp at which PayG remaining was calculated | ts | pyg_ts | Optional,Scope: Device | | Linux 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.0 | pyg | Last Added PayG Credit | lcr | pyg_lcr | Optional,Scope: Device | | Historical last PayG credit update duration. Range is from 01-9999 | +| AirLink PAYG 1.0 | pyg | PayG Token | tkn | pyg_tkn | Scope: Shared | | SipHash token. Accepted by device only if valid. No read token to ensure unsecured gateways cannot act maliciously. | +| PAYG Credit 1.0 | pyg | Mode | mo | pyg_mo | Not Implemented,Scope: Shared | | mode 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.0 | pyg | Device PayG Credit Remaining | re | pyg_re | Mandatory,Scope: Time Series | | should be The value remaining for the device to OFF. +| PAYG Credit 1.0 | pyg | Device PayG Credit Remaining | re | pyg_re | Mandatory,Scope: Time Series | | should 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 | -| PAYG Credit 1.0 | pyg | Payg Token Secret | pts | pyg_pts | Mandatory,Scope: Server | | On first release, this is the Nexus Keycode secret | -| PAYG Credit 1.0 | pyg | Payg Token Message ID | msg | pyg_msg | Mandatory,Scope: Server | | On first release, this is the Nexus Keycode message ID | +| PAYG Credit 1.0 | pyg | Payg Token Secret | pts | pyg_pts | Mandatory,Scope: Server | | On first release, this is the Nexus Keycode secret | +| PAYG Credit 1.0 | pyg | Payg Token Message ID | msg | pyg_msg | Mandatory,Scope: Server | | On first release, this is the Nexus Keycode message ID | 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. @@ -168,19 +163,15 @@ Device-initiated or gateway-initiated communications posting time-series data an 1. Individual devices equipped with GSM send data directly ***using their device token*** e.g. water pump control boxes 2. 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 3. 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. -4. 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. +4. 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. -| Concept | MQTT | HTTP/CoAP ✅ | -| --- | --- | --- | -| Application Server + IoT Server model for value-added services | ⚠️ Can only be used for IoT comms, not business app comms | Needed by phone app for comms to application server, but not by non-phone gateways | -| Bandwidth | Better than HTTP for persistent connections - not expected in AirLink | ✅ CoAP is better than MQTT, more so when connections are sporadic - as is expected in AirLink | -| IoT Gateway functionality | ✅ Thingsboard supports MQTT as gateway paired with customer devices, majority use case -✅ Single connection can report multiple devices' data -❌ If multiple gateways need to own devices, they would need to be transferred between devices e.g. Field service agent's phone, customer's phone, farm boys' phone etc by online transactions with server - may not be feasible in the field | ⚠️ Credential of each device would need to be known to gateway (additional thingsboard workflow), and list of gateways that can control device wouldn't be registered with Airlink server (more potential for spoofing), requiring credentials to be refreshed or other security measures -⚠️ Each device would need to be reported separately, increasing number of HTTP required connections -✅ Could support arbitrary number of gateways | +| Concept | MQTT | HTTP/CoAP ✅ | +| -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| Application Server + IoT Server model for value-added services | ⚠️ Can only be used for IoT comms, not business app comms | Needed by phone app for comms to application server, but not by non-phone gateways | +| Bandwidth | Better than HTTP for persistent connections - not expected in AirLink | ✅ CoAP is better than MQTT, more so when connections are sporadic - as is expected in AirLink | +| IoT Gateway functionality | ✅ Thingsboard supports MQTT as gateway paired with customer devices, majority use case ✅ Single connection can report multiple devices' data ❌ If multiple gateways need to own devices, they would need to be transferred between devices e.g. Field service agent's phone, customer's phone, farm boys' phone etc by online transactions with server - may not be feasible in the field |⚠️ Credential of each device would need to be known to gateway (additional thingsboard workflow), and list of gateways that can control device wouldn't be registered with Airlink server (more potential for spoofing), requiring credentials to be refreshed or other security measures ⚠️ Each device would need to be reported separately, increasing number of HTTP required connections ✅ Could support arbitrary number of gateways | ### KeyCode generation @@ -203,9 +194,9 @@ The provided KeyCode node Here is a test sequence that can verify that the PAYG Token chain is working end to end from credit request to device function. | KeyCode Node Function | msg_id, saved in server side attributes | Credit Request Packet from Postman POST mimicking loan management server - note the knowledge of ‘Device ID’, which is the UUID of the IoT device on the AirLink Server | Input Key to KeyCode node, visible in node “Events” metadata with Debug enabled on AirLink Server | Output Message from KeyCode node sent to Device via Shared Attributes sync’d through the AirLink gateway App, visible in node “Events” metadata with Debug enabled on AirLink Server | Decoded Output within AirLink Device implementing Nexus Keycode | -| --- | --- | --- | --- | --- | --- | -| Added 6 Days | 1 | { - “pay_g_tkn”:”6” +| --------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | +| Added 6 Days | 1 | { | + “pay_g_tkn”:”6” } | “pay_g_tkn”:”6”, | *010 050 135 981 34# | - Received tkn*01005013598134# - PayG update received @@ -213,15 +204,15 @@ Here is a test sequence that can verify that the PAYG Token chain is working end - Credit remaining: 86400 seconds - PayG update received | | Set Device to exactly 10 Days | 2 | { - “set_tkn”:”11” + “set_tkn”:”11” } | “set_tkn”:”11” | *123 026 694 078 81# | - Received tkn*12302669407881# - PayG update received - Keycode is valid. - Credit remaining: 950100 seconds - PayG update received | | Unlock the Device | 3 | { - “unlock_tkn”:”1” -} | “unlock_tkn”:”1” | *336 153 083 439 44# | - Received tkn*33615308343944# + “unlock_tkn”:”1” +} | “unlock_tkn”:”1” | *336 153 083 439 44# | - Received tkn*33615308343944# - PayG update received - Keycode is valid. - The device is unlocked diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2.csv b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2.csv deleted file mode 100644 index 0ac4452..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2.csv +++ /dev/null @@ -1,11 +0,0 @@ -Name,Scope -Rule chain alarm Thresholds,Server Side -Device Administration Configuration,Server Side -"PAYG Token Secret, Message ID",Server Side -PAYG Command or Token,Shared by Server -Device provisioning or claiming keys,Shared by Server -Customer Provisioning Information,Shared by Server -AirLink ID,Shared by Server -Timeseries Data,Device (Client) Side: -PAYG Status,Device (Client) Side: -Config status e.g. Firmware version,Device (Client) Side: \ No newline at end of file diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/AirLink ID 34a6a602814745ab9a28940d1d3af142.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/AirLink ID 34a6a602814745ab9a28940d1d3af142.md deleted file mode 100644 index 7a91da4..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/AirLink ID 34a6a602814745ab9a28940d1d3af142.md +++ /dev/null @@ -1,3 +0,0 @@ -# AirLink ID - -Scope: Shared by Server diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Config status e g Firmware version 988f3023800e4866a1e1261b6fa36f35.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Config status e g Firmware version 988f3023800e4866a1e1261b6fa36f35.md deleted file mode 100644 index 18e13b6..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Config status e g Firmware version 988f3023800e4866a1e1261b6fa36f35.md +++ /dev/null @@ -1,3 +0,0 @@ -# Config status e.g. Firmware version - -Scope: Device (Client) Side: diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Customer Provisioning Information c6f47efb3ff542858cf76d07d5186883.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Customer Provisioning Information c6f47efb3ff542858cf76d07d5186883.md deleted file mode 100644 index 4ac85b2..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Customer Provisioning Information c6f47efb3ff542858cf76d07d5186883.md +++ /dev/null @@ -1,3 +0,0 @@ -# Customer Provisioning Information - -Scope: Shared by Server diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Device Administration Configuration 30d49450eb1a44ccbd1ac620dcc63072.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Device Administration Configuration 30d49450eb1a44ccbd1ac620dcc63072.md deleted file mode 100644 index 5413b8a..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Device Administration Configuration 30d49450eb1a44ccbd1ac620dcc63072.md +++ /dev/null @@ -1,3 +0,0 @@ -# Device Administration Configuration - -Scope: Server Side diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Device provisioning or claiming keys c74f19fa1fe54dddb737c804e3d103da.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Device provisioning or claiming keys c74f19fa1fe54dddb737c804e3d103da.md deleted file mode 100644 index 7c26d91..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Device provisioning or claiming keys c74f19fa1fe54dddb737c804e3d103da.md +++ /dev/null @@ -1,3 +0,0 @@ -# Device provisioning or claiming keys - -Scope: Shared by Server diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Command or Token ef142acab5b44b3a9fcb61522d5acaf5.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Command or Token ef142acab5b44b3a9fcb61522d5acaf5.md deleted file mode 100644 index e8d8289..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Command or Token ef142acab5b44b3a9fcb61522d5acaf5.md +++ /dev/null @@ -1,3 +0,0 @@ -# PAYG Command or Token - -Scope: Shared by Server diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Status 11596ed3dbde4bf4a6f9621ddc6dcede.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Status 11596ed3dbde4bf4a6f9621ddc6dcede.md deleted file mode 100644 index 774d44a..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Status 11596ed3dbde4bf4a6f9621ddc6dcede.md +++ /dev/null @@ -1,3 +0,0 @@ -# PAYG Status - -Scope: Device (Client) Side: diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Token Secret, Message ID b093831971814a90b318c81b731c49f2.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Token Secret, Message ID b093831971814a90b318c81b731c49f2.md deleted file mode 100644 index 307093d..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/PAYG Token Secret, Message ID b093831971814a90b318c81b731c49f2.md +++ /dev/null @@ -1,3 +0,0 @@ -# PAYG Token Secret, Message ID - -Scope: Server Side diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Rule chain alarm Thresholds c22121ef28224db891e765cb24ba59d5.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Rule chain alarm Thresholds c22121ef28224db891e765cb24ba59d5.md deleted file mode 100644 index 45c86c1..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Rule chain alarm Thresholds c22121ef28224db891e765cb24ba59d5.md +++ /dev/null @@ -1,3 +0,0 @@ -# Rule chain alarm Thresholds - -Scope: Server Side diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Timeseries Data 5c5d4a527a5e4fa18fc32c31fe1fba8c.md b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Timeseries Data 5c5d4a527a5e4fa18fc32c31fe1fba8c.md deleted file mode 100644 index c87dfd5..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2/Timeseries Data 5c5d4a527a5e4fa18fc32c31fe1fba8c.md +++ /dev/null @@ -1,3 +0,0 @@ -# Timeseries Data - -Scope: Device (Client) Side: diff --git a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2_all.csv b/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2_all.csv deleted file mode 100644 index 0ac4452..0000000 --- a/docs/AirLink Server/Attribute Scopes for AirLink resource properties 81cd9ab605c54348a6c03bbef738dbd2_all.csv +++ /dev/null @@ -1,11 +0,0 @@ -Name,Scope -Rule chain alarm Thresholds,Server Side -Device Administration Configuration,Server Side -"PAYG Token Secret, Message ID",Server Side -PAYG Command or Token,Shared by Server -Device provisioning or claiming keys,Shared by Server -Customer Provisioning Information,Shared by Server -AirLink ID,Shared by Server -Timeseries Data,Device (Client) Side: -PAYG Status,Device (Client) Side: -Config status e.g. Firmware version,Device (Client) Side: \ No newline at end of file diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933.md deleted file mode 100644 index fb4a456..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933.md +++ /dev/null @@ -1,180 +0,0 @@ -# How we chose Thingsboard.io for AirLink Server - -## Decision Context - -PAYG devices fall under the IoT 'edge device' umbrella. A small set of SaaS companies are currently offering integrated loan management and device management services to PAYG-IoT distributors, primarily focused on token-based GSM home-system devices with some extensions for data feedback. Companies like Angaza have proprietary hardware+software IoT stacks that offer API-integration at some levels while companies like Solaris offer more open source codebases for device firmware and token software. Neither offer an open-source provisioning or analytics platform, although both have SaaS offerings for analytics and PAYG control, integrated with their custom loan platform. Both have a per-end-user-per-month revenue model which is consistent with contemporary SaaS - their revenues scale directly with their customer's customer bases. - -Simusolar would like to build or buy a PAYG + IoT Data system that has API integration, configurable analytics, cost-effective implementation, ability to serve partners as well as ability to aggregate data over BLE / GSM / Keypad / Wired systems. EnAccess has provided a $50,000 grant to Simusolar to build an open-source multi-medium IoT communication protocol and data format to support these goals in 2021, with a focus on a deliverable that can enable upstart companies in this area to easily overcome the PAYG-IoT technology barrier. Simusolar currently has pumps and fishing lights that will be modified to meet this standard. - ---- - -We need to decide on the best alternative approach to building this IoT database and related tools. Simusolar has recently adopted several managed and no-code tools to enable speed of secure and scalable business process automation with low overhead costs. We believe this approach has long term value and hence we give priority to options which have managed or no-code cores. We consider two high-level options -a. custom database with open source dashboarding tools (no-code device/partner management can follow alternate no-code/code analysis) -b. open source IoT platforms - -### a. Custom db + Dashboard Options - -(IaaS, e.g. managed Redis on DigitalOcean + custom droplet with code) - -[The Best 9 Free and Open Source Dashboard Software](https://www.goodfirms.co/blog/best-free-open-source-dashboard-software) - -[freeboard](https://freeboard.io/#pricing) - -[Redash Reviews - GoodFirms](https://www.goodfirms.co/software/redash) - -[Dashbuilder - Home](https://www.dashbuilder.org) - -Pros of a custom db+dashboard approach - -Freedom to adopt managed or self-managed databases without lock-in - -Completely custom server code i.e. process triggers and PAYG responses - -The communication layer ends at the database, cleanly separating the application layer which can be full-custom - -A central database managed by one entity e.g. EnAccess would only require to handle communication layer while application layer would be handed off, making the central db more easily viable compared to a solution with an application layer - -Cons of a custom db+dashboard approach - -Requires coding competence to pre-process incoming IoT data stream - -Requires domain-expert skill for building of device provisioning and basic analytics flows - -Requires a full-time administrator to manage IoT connection to rest of business apps platform - -New workflow features require coding and hence take weeks to develop - -Initial adoption by business takes longer due to coding requirements - -### b. IoT Platform Options - -(PaaS if managed or IaaS+PaaS in case of self-managed, includes closed-source options for reference) - -[Guide to IOT Dashboards and Platforms](http://www.steves-internet-guide.com/iot-mqtt-dashboards/) - -[IoT Analytics - ThingSpeak Internet of Things](https://thingspeak.com) - -[ThingsBoard - Open-source IoT Platform](https://thingsboard.io) - -[Homepage - Thingstream by u-blox IoT Communication-as-a-Service](https://thingstream.io) - -[➤ Kaa Demo | Kaa IoT Platform](https://www.kaaproject.org/demo) - -[OpenRemote | The 100% Open Source IoT Platform](https://openremote.io) - -[Google Cloud IoT - Fully Managed IoT Services](https://cloud.google.com/solutions/iot) - -[dweet™ - Bug Labs Enteprise IoT Platform](https://dweetpro.io/pricing.html) - -[SQL Database for IoT & Sensor Data | CrateDB](https://crate.io/use-cases/iot-sensor-data/) - -[Particle Company News and Updates | Particle](https://particle.io) - -[Learn More - ThingSpeak IoT](https://thingspeak.com/pages/commercial_learn_more) - -[itead/IoTgo](https://github.com/itead/IoTgo) - -[Introduction to the Azure Internet of Things (IoT)](https://docs.microsoft.com/en-us/azure/iot-fundamentals/iot-introduction) - -[AWS IoT - Amazon Web Services](https://aws.amazon.com/iot/) - -Pros of an open-source IoT Platform approach - -Leverages a pre-built best-practices approach to managing incoming IoT data-stream - -Leverages a device provisioning and basic analytics platform that is ready to go, reducing the startup-building burden - -New workflows can be built quickly as many of these platforms offer drag and drop UIs for process triggers based on incoming IoT connections - -Companies can choose a managed or SaaS model for the same service if their business model supports that choice better than a self-managed PaaS - -Cons of an open-source IoT Platform approach - -Adopters would be initially oblivious to implementation details before they can study the large amount of platform source code in the specific programming language - -The Application layer comes with presumptions about IoT management that may not apply across all businesses - -Any central entity such as EnAccess who manages a common db might need to provide application-level client-management/API as well as database management and communication layer level API - ---- - -### Perspectives on Approach - -Simusolar has experienced the often hidden time-cost and domain-knowledge complexity of building device-provisioning/onboarding flows for IoT systems, and considers provisioning an important complement to the IoT data/PAYG flow when considering approaches facilitating new ventures in this field. Standardizing this while considering privacy best-practices could reduce a big barrier, further abstracting away the technical details for integrating PAYG IoT with other business applications. - -Data Retention management and Analytics is another natural feature desired of GSM IoT collections. We conjecture that most IoT analysis usually pivots on a single plotted variable for a particular device class e.g. power used by time of day for energy products, along with some standard status variables e.g. location, error state. PAYG control also has common requirements e.g. on/off control or use-metered control. - -Hence there are opportunities to design a platform that has pre-built, privacy-enabled standard features for device provisioning, single-variable control and single-variable graphing with map and status indicators and a built in retention policy. Such a platform could enable adopters of the project to incorporate standard IoT outcomes easily into their business operations. - -Lock-in risks as well as the central role of EnAccess in enabling upstarts points to the importance of open source, modular approaches that allow the scaling of individual components as managed or self-managed entities, such as front end databases and servers that run data processing code. - -### Culling the options - -AWS/Azure/IBM IoT offerings were not considered the right cost-value tradeoff due to the complexity of adoption and the fact that the dataset of most adopters of this project will be limited in size and will manage with smaller IT teams i.e. not tens of millions of devices/interactions per day managed by a specialist IT team, but hundreds of thousands at most managed by a multi-tasking IT team. The caveat is potentially losing out on AI integration which could be useful for predictive tasks. In the PAYG-IoT business case, learning and prediction requirements are as yet not well defined as business differentiators and hence AI was not considered a prime factor. - -The alternatives list was further limited by the following parameter choices: Open source, Free/freemium versions and no per-device fees. Per-devices services are roughly $2/month/device (in addition to any network/SIM card fees), which adds up quickly when selling a large number of smart devices and can be margin-limiting in low-cost markets. This consideration discounted dweetpro.io, [thingstream.io](http://thingstream.io), particle.io and thingspeak.com - -*Baseline:* SaaS + PaaS + IaaS + Support-vendor costs for Simusolar are $86,658/yr projected to reduce to $52,100/yr by December 2021 by using no-code platforms and internal support - -[Last Round Alternatives](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Last%20Round%20Alternatives%200ab7b7c54fa646a9ae62f45fe89de548.csv) - -## Proposed Solution: [thingsboard.io](http://thingsboard.io) docker monolithic - -Scale Architecture - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-11_at_11.20.51_PM.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-11_at_11.20.51_PM.png) - -Deployment proposal: Lock-in mitigation is by using a managed database for Cassandra/PostgreSQL - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.10.41_PM.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.10.41_PM.png) - -Multi-vendor management from a single central db - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.07.11_PM.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.07.11_PM.png) - -Private devices and dashboards via tenancy - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Untitled.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Untitled.png) - -PAYG control - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.15.02_PM.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.15.02_PM.png) - -Self-Provisioning - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.14.02_PM.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.14.02_PM.png) - -Plotting the primary variable by device type - -![How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.16.29_PM.png](How%20we%20chose%20Thingsboard%20io%20for%20AirLink%20Server%20fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.16.29_PM.png) - -### Feasible Implementation Plan - -- Setup DigitalOcean Ubuntu droplet -- Setup [Thingsboard.io](http://thingsboard.io) docker image -- Test custom protocol integration, write connector if required - - Test VPN integration with Aeris -- Buy managed PostGreSQL db on DigitalOcean - - Reconfigure Thingsboard configuration-database connection -- Buy managed Cassandra droplet on DigitalOcean from Aiven - - Reconfigure Thingsboard timeseries-database connection -- Setup administration for EnAccess and tenancy for Simusolar and Tulima Solar - - Setup tenant profile including dashboard template - - Setup provisioning flow on Simusolar servers to attach to Simusolar tenant -- Configure phone app to act as MQTT gateway for protocol-compliant devices, including claiming flow - -### Stakeholder validation (R.A.C.I.) - -Were the responsible (implementers) persons consulted for feasibility? - -Are the accountable (project manager) persons committed to the outcome? - -Have the consulted (change recipients) people indicated their support? - -Will the Informed (all other impacted) people receive the information in time? - -## Final Choice - -Date: - -Decider (Proof): diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548.csv b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548.csv deleted file mode 100644 index edce7ce..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548.csv +++ /dev/null @@ -1,26 +0,0 @@ -Feature,custom development,ThingsBoard.io ✓,Kaaproject.org,OpenRemote.io ❌,Crate.io ❌ -"Total Cost of Ownership for paid premium option - 1 year, 10,000 devices","$120/yr code server, $180/yr Redis managed, $180/yr postgresql managed = $480/yr","$3600/yr for Docker+managed db or $6,000/yr for SaaS cloud, provides flexibility","$3600/yr for self-managed or $24,000/yr for managed on-premise ","$3600/yr for self-managed, no cloud offering",db-only $2616/month ❌ -Model,"IaaS: DigitalOcean droplet with custom stream-processing code, managed Redis db buffer for incoming data providing high-rel front end, then managed PostGreSQL db for IoT metrics. Custom device/partner management workflows on another platform e.g. Airtable-like no-code platform","Open Source or Managed PaaS: Monolithic/microservice interchangeable, IoT stream processing, device/partner management and and IoT Analytics platform in Docker on a DigitalOcean droplet with Aiven-Cassandra + PostGreSQL managed dbs on DigitalOcean. One downloadable package architecture, can be clustered ","Open Source or Managed PaaS: microservices type IoT stream processing, device/partner management and and IoT Analytics platform in Docker connecting to a Redis + PostGreSQL. No monolithic download so steeper initial learning curve","Assissted deployment only, no managed cloud options","Open Source or Managed PaaS: CrateDB is a distributed SQL database built on top of a NoSQL foundation. Customers often use CrateDB to store and query machine data. This is because CrateDB makes it easy and economical to handle the velocity, volume, and diversity of machine and log data." -"Open source ",—,"Yes, updated in 2021","Yes, updated in 2021","Yes, updated in 2021","Yes, updated in 2021" -Performance / scale,Full-custom,Single-container / managed cluster / cloud SaaS optionality,Kubernetes baked,,Highly scalable -Lock-in risk,Nil,Company could decide to fork free/paid codebases. Timestream data could be migrated but tenant management structure would probably need to fork codebase,Timestream data could be migrated but tenant management structure would probably need to fork codebase,Timestream data could be migrated but tenant management structure would probably need to fork codebase,Developing for specific db type could lead to harder migration options -"Basic Data External forwarding and Workflow triggers ",—,"Yes, Kafka stream and Rulechain configured from drag and drop UI",Yes Redis based queue,"'Rule-chain' for PAYG response seems very basic without custom scripts, only math/text functions ❌",Needs external SQL queries but performance is fast enough to support datastream analysis -Vendor info / any risk to business,SLA is fully dependent on internal developers,"thingsboard pro used by Engie, no SLA for community edition, dependent on internal developers",FDA and HIPAA as customers,Germany focus with some cities adopting it also Schipol security,— -Feature dev speed,~1wk-1mo,~1day-1wk (most common features are UI based),~1day-1wk (most common features are UI based),~1day-1wk (most common features are UI based),~1wk-1mo -Feature cost,Internal Development @$1000/month,Internal Development @$1000/month,Internal Development @$1000/month,Internal Development @$1000/month,Internal Development @$1000/month -"IoT Comms ",Customizable,"POST/MQTT/CoAP upload, GET request or Gateway subscribing via MQTT","POST/MQTT/CoAP upload, GET request or Gateway subscribing via MQTT",,— -API,Will need to be built,REST with JWT auth per device/entity,REST API,,— -Analytics for metrics,No,Yes,Yes,,Not inbuilt ❌ -Device management,Will need to be built,Yes with profiles and gateway MQTT-only devices,"Yes with profiles, versions and gateway MQTT-only devices",,No ❌ -Data management possiblity,Managed Redis + Managed PostgreSQL,"Part of docker image as starting point, Managed Cassandra (Aiven on DigitalOcean) + PostgreSQL (native DigitalOcean) database",Managed Redis + Managed PostgreSQL,, -Customer management,Will need to be built,Yes with groups and embeddable client dashboards,Yes with groups,,No ❌ -Customer support,Internal,Only for cloud otherwise internal,Only for cloud otherwise internal,, -Interoperable format compatibility,Yes,"JSON key-value pairs, additional Customizable 'connectors' for custom binary",JSON,, -Chart options,Will need external service e.g. No code big-data service,Moving line/bar/speed-gauge/map,Moving line/bar/speed-gauge/map,,No ❌ -Filters on displayed charts,—,Only time filters?,Only time filters?,,No ❌ -Dashboard UX,—,"Basic, sufficient","Basic, sufficient",,— -Login based filtering,Custom development,Yes,Yes,, -SSO types for users/customers,Custom development,Oauth2,Oauth2,, -Programming language,PHP,Java,Go,Go,Java -Device/Sandbox codebase,—,not seen any,"Arduino samples, web sandbox, etc",,Python client example -Git / source Link,—,https://thingsboard.io/docs/user-guide/install/digital-ocean/ also https://github.com/thingsboard/thingsboard,https://github.com/kaaproject/kaa,https://github.com/openremote,https://github.com/crate \ No newline at end of file diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/API 2b45090acf5a4dd3bb6c93cf09bbd247.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/API 2b45090acf5a4dd3bb6c93cf09bbd247.md deleted file mode 100644 index a9d46d3..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/API 2b45090acf5a4dd3bb6c93cf09bbd247.md +++ /dev/null @@ -1,6 +0,0 @@ -# API - -ThingsBoard.io ✓: REST with JWT auth per device/entity -Crate.io ❌: — -Kaaproject.org: REST API -custom development: Will need to be built diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Analytics for metrics 5d54acc723e1438499645a7d8fd8e7b5.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Analytics for metrics 5d54acc723e1438499645a7d8fd8e7b5.md deleted file mode 100644 index 30befec..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Analytics for metrics 5d54acc723e1438499645a7d8fd8e7b5.md +++ /dev/null @@ -1,6 +0,0 @@ -# Analytics for metrics - -ThingsBoard.io ✓: Yes -Crate.io ❌: Not inbuilt ❌ -Kaaproject.org: Yes -custom development: No diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Basic Data External forwarding and Workflow trigge 04a000ddf27045a58324c05c69129708.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Basic Data External forwarding and Workflow trigge 04a000ddf27045a58324c05c69129708.md deleted file mode 100644 index d3a9f85..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Basic Data External forwarding and Workflow trigge 04a000ddf27045a58324c05c69129708.md +++ /dev/null @@ -1,7 +0,0 @@ -# Basic Data External forwarding and Workflow triggers - -ThingsBoard.io ✓: Yes, Kafka stream and Rulechain configured from drag and drop UI -Crate.io ❌: Needs external SQL queries but performance is fast enough to support datastream analysis -Kaaproject.org: Yes Redis based queue -OpenRemote.io ❌: 'Rule-chain' for PAYG response seems very basic without custom scripts, only math/text functions ❌ -custom development: — diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Chart options e17ee203b9f24c1aada36ec4907d4e53.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Chart options e17ee203b9f24c1aada36ec4907d4e53.md deleted file mode 100644 index a553a77..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Chart options e17ee203b9f24c1aada36ec4907d4e53.md +++ /dev/null @@ -1,6 +0,0 @@ -# Chart options - -ThingsBoard.io ✓: Moving line/bar/speed-gauge/map -Crate.io ❌: No ❌ -Kaaproject.org: Moving line/bar/speed-gauge/map -custom development: Will need external service e.g. No code big-data service diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Customer management 8db790b517ed40b0ad46a54d5e22d3e6.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Customer management 8db790b517ed40b0ad46a54d5e22d3e6.md deleted file mode 100644 index 089ab05..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Customer management 8db790b517ed40b0ad46a54d5e22d3e6.md +++ /dev/null @@ -1,6 +0,0 @@ -# Customer management - -ThingsBoard.io ✓: Yes with groups and embeddable client dashboards -Crate.io ❌: No ❌ -Kaaproject.org: Yes with groups -custom development: Will need to be built diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Customer support c389bb7fd1314df5b11b9229e3913f07.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Customer support c389bb7fd1314df5b11b9229e3913f07.md deleted file mode 100644 index 2dd492b..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Customer support c389bb7fd1314df5b11b9229e3913f07.md +++ /dev/null @@ -1,5 +0,0 @@ -# Customer support - -ThingsBoard.io ✓: Only for cloud otherwise internal -Kaaproject.org: Only for cloud otherwise internal -custom development: Internal diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Dashboard UX 5dad589f771c4a029339bbaf7a3c88eb.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Dashboard UX 5dad589f771c4a029339bbaf7a3c88eb.md deleted file mode 100644 index 3892f98..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Dashboard UX 5dad589f771c4a029339bbaf7a3c88eb.md +++ /dev/null @@ -1,6 +0,0 @@ -# Dashboard UX - -ThingsBoard.io ✓: Basic, sufficient -Crate.io ❌: — -Kaaproject.org: Basic, sufficient -custom development: — diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Data management possiblity 452df22571f145aeb569939c9146bc21.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Data management possiblity 452df22571f145aeb569939c9146bc21.md deleted file mode 100644 index 8a09be8..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Data management possiblity 452df22571f145aeb569939c9146bc21.md +++ /dev/null @@ -1,5 +0,0 @@ -# Data management possiblity - -ThingsBoard.io ✓: Part of docker image as starting point, Managed Cassandra (Aiven on DigitalOcean) + PostgreSQL (native DigitalOcean) database -Kaaproject.org: Managed Redis + Managed PostgreSQL -custom development: Managed Redis + Managed PostgreSQL diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Device Sandbox codebase 4ad4a1269d814bc498180c06887a9355.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Device Sandbox codebase 4ad4a1269d814bc498180c06887a9355.md deleted file mode 100644 index 9631a03..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Device Sandbox codebase 4ad4a1269d814bc498180c06887a9355.md +++ /dev/null @@ -1,6 +0,0 @@ -# Device/Sandbox codebase - -ThingsBoard.io ✓: not seen any -Crate.io ❌: Python client example -Kaaproject.org: Arduino samples, web sandbox, etc -custom development: — diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Device management 89dd4a0b8d174648b6b88b68ba915f89.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Device management 89dd4a0b8d174648b6b88b68ba915f89.md deleted file mode 100644 index 9e5c380..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Device management 89dd4a0b8d174648b6b88b68ba915f89.md +++ /dev/null @@ -1,6 +0,0 @@ -# Device management - -ThingsBoard.io ✓: Yes with profiles and gateway MQTT-only devices -Crate.io ❌: No ❌ -Kaaproject.org: Yes with profiles, versions and gateway MQTT-only devices -custom development: Will need to be built diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Feature cost a078e1055d1c4dc3be68b1c194a6d0bc.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Feature cost a078e1055d1c4dc3be68b1c194a6d0bc.md deleted file mode 100644 index 3e11b5f..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Feature cost a078e1055d1c4dc3be68b1c194a6d0bc.md +++ /dev/null @@ -1,7 +0,0 @@ -# Feature cost - -ThingsBoard.io ✓: Internal Development @$1000/month -Crate.io ❌: Internal Development @$1000/month -Kaaproject.org: Internal Development @$1000/month -OpenRemote.io ❌: Internal Development @$1000/month -custom development: Internal Development @$1000/month diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Feature dev speed 7468c1c2b41f4e07a5c21f60089fcc1d.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Feature dev speed 7468c1c2b41f4e07a5c21f60089fcc1d.md deleted file mode 100644 index 6296265..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Feature dev speed 7468c1c2b41f4e07a5c21f60089fcc1d.md +++ /dev/null @@ -1,7 +0,0 @@ -# Feature dev speed - -ThingsBoard.io ✓: ~1day-1wk (most common features are UI based) -Crate.io ❌: ~1wk-1mo -Kaaproject.org: ~1day-1wk (most common features are UI based) -OpenRemote.io ❌: ~1day-1wk (most common features are UI based) -custom development: ~1wk-1mo diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Filters on displayed charts 085f49ada5944cadb42c9865898b0232.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Filters on displayed charts 085f49ada5944cadb42c9865898b0232.md deleted file mode 100644 index fa2799c..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Filters on displayed charts 085f49ada5944cadb42c9865898b0232.md +++ /dev/null @@ -1,6 +0,0 @@ -# Filters on displayed charts - -ThingsBoard.io ✓: Only time filters? -Crate.io ❌: No ❌ -Kaaproject.org: Only time filters? -custom development: — diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Git source Link 3d7d92e5cc5f458db244260d3b9424ac.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Git source Link 3d7d92e5cc5f458db244260d3b9424ac.md deleted file mode 100644 index 22d48ed..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Git source Link 3d7d92e5cc5f458db244260d3b9424ac.md +++ /dev/null @@ -1,7 +0,0 @@ -# Git / source Link - -ThingsBoard.io ✓: also -Crate.io ❌: -Kaaproject.org: -OpenRemote.io ❌: -custom development: — diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Interoperable format compatibility 2566d647a3e4402890f3e48472e3b59f.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Interoperable format compatibility 2566d647a3e4402890f3e48472e3b59f.md deleted file mode 100644 index 8859522..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Interoperable format compatibility 2566d647a3e4402890f3e48472e3b59f.md +++ /dev/null @@ -1,5 +0,0 @@ -# Interoperable format compatibility - -ThingsBoard.io ✓: JSON key-value pairs, additional Customizable 'connectors' for custom binary -Kaaproject.org: JSON -custom development: Yes diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/IoT Comms 7fccfe926a3b4b9fafa201822f7a164f.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/IoT Comms 7fccfe926a3b4b9fafa201822f7a164f.md deleted file mode 100644 index ed79770..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/IoT Comms 7fccfe926a3b4b9fafa201822f7a164f.md +++ /dev/null @@ -1,6 +0,0 @@ -# IoT Comms - -ThingsBoard.io ✓: POST/MQTT/CoAP upload, GET request or Gateway subscribing via MQTT -Crate.io ❌: — -Kaaproject.org: POST/MQTT/CoAP upload, GET request or Gateway subscribing via MQTT -custom development: Customizable diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Lock-in risk c4cee9ccea7b4add8234d7af062f0a1a.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Lock-in risk c4cee9ccea7b4add8234d7af062f0a1a.md deleted file mode 100644 index 5bdf934..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Lock-in risk c4cee9ccea7b4add8234d7af062f0a1a.md +++ /dev/null @@ -1,7 +0,0 @@ -# Lock-in risk - -ThingsBoard.io ✓: Company could decide to fork free/paid codebases. Timestream data could be migrated but tenant management structure would probably need to fork codebase -Crate.io ❌: Developing for specific db type could lead to harder migration options -Kaaproject.org: Timestream data could be migrated but tenant management structure would probably need to fork codebase -OpenRemote.io ❌: Timestream data could be migrated but tenant management structure would probably need to fork codebase -custom development: Nil diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Login based filtering ae8d17cc1af74ff99a1ec4324e53e3ba.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Login based filtering ae8d17cc1af74ff99a1ec4324e53e3ba.md deleted file mode 100644 index c2b1b55..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Login based filtering ae8d17cc1af74ff99a1ec4324e53e3ba.md +++ /dev/null @@ -1,5 +0,0 @@ -# Login based filtering - -ThingsBoard.io ✓: Yes -Kaaproject.org: Yes -custom development: Custom development diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Model f4340e4dcc1c424684d2345ff7352be7.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Model f4340e4dcc1c424684d2345ff7352be7.md deleted file mode 100644 index 481c6bd..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Model f4340e4dcc1c424684d2345ff7352be7.md +++ /dev/null @@ -1,7 +0,0 @@ -# Model - -ThingsBoard.io ✓: Open Source or Managed PaaS: Monolithic/microservice interchangeable, IoT stream processing, device/partner management and and IoT Analytics platform in Docker on a DigitalOcean droplet with Aiven-Cassandra + PostGreSQL managed dbs on DigitalOcean. One downloadable package architecture, can be clustered -Crate.io ❌: Open Source or Managed PaaS: CrateDB is a distributed SQL database built on top of a NoSQL foundation. Customers often use CrateDB to store and query machine data. This is because CrateDB makes it easy and economical to handle the velocity, volume, and diversity of machine and log data. -Kaaproject.org: Open Source or Managed PaaS: microservices type IoT stream processing, device/partner management and and IoT Analytics platform in Docker connecting to a Redis + PostGreSQL. No monolithic download so steeper initial learning curve -OpenRemote.io ❌: Assissted deployment only, no managed cloud options -custom development: IaaS: DigitalOcean droplet with custom stream-processing code, managed Redis db buffer for incoming data providing high-rel front end, then managed PostGreSQL db for IoT metrics. Custom device/partner management workflows on another platform e.g. Airtable-like no-code platform diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Open source 387cd4e6cba54538af21c020f6b19cf1.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Open source 387cd4e6cba54538af21c020f6b19cf1.md deleted file mode 100644 index f723756..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Open source 387cd4e6cba54538af21c020f6b19cf1.md +++ /dev/null @@ -1,7 +0,0 @@ -# Open source - -ThingsBoard.io ✓: Yes, updated in 2021 -Crate.io ❌: Yes, updated in 2021 -Kaaproject.org: Yes, updated in 2021 -OpenRemote.io ❌: Yes, updated in 2021 -custom development: — diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Performance scale e6052517c5fa41a29509227c87dcf768.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Performance scale e6052517c5fa41a29509227c87dcf768.md deleted file mode 100644 index dd0efec..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Performance scale e6052517c5fa41a29509227c87dcf768.md +++ /dev/null @@ -1,6 +0,0 @@ -# Performance / scale - -ThingsBoard.io ✓: Single-container / managed cluster / cloud SaaS optionality -Crate.io ❌: Highly scalable -Kaaproject.org: Kubernetes baked -custom development: Full-custom diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Programming language dafec3aef11545a789df7e5c5326f130.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Programming language dafec3aef11545a789df7e5c5326f130.md deleted file mode 100644 index b5487aa..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Programming language dafec3aef11545a789df7e5c5326f130.md +++ /dev/null @@ -1,7 +0,0 @@ -# Programming language - -ThingsBoard.io ✓: Java -Crate.io ❌: Java -Kaaproject.org: Go -OpenRemote.io ❌: Go -custom development: PHP diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/SSO types for users customers 565c4ec86bef46c78ece2158d6f80cd6.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/SSO types for users customers 565c4ec86bef46c78ece2158d6f80cd6.md deleted file mode 100644 index 27ae002..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/SSO types for users customers 565c4ec86bef46c78ece2158d6f80cd6.md +++ /dev/null @@ -1,5 +0,0 @@ -# SSO types for users/customers - -ThingsBoard.io ✓: Oauth2 -Kaaproject.org: Oauth2 -custom development: Custom development diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Total Cost of Ownership for paid premium option - 6077e5705a174cdc86fe64348bf16fdb.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Total Cost of Ownership for paid premium option - 6077e5705a174cdc86fe64348bf16fdb.md deleted file mode 100644 index ecf39b4..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Total Cost of Ownership for paid premium option - 6077e5705a174cdc86fe64348bf16fdb.md +++ /dev/null @@ -1,7 +0,0 @@ -# Total Cost of Ownership for paid premium option - 1 year, 10,000 devices - -ThingsBoard.io ✓: $3600/yr for Docker+managed db or $6,000/yr for SaaS cloud, provides flexibility -Crate.io ❌: db-only $2616/month ❌ -Kaaproject.org: $3600/yr for self-managed or $24,000/yr for managed on-premise -OpenRemote.io ❌: $3600/yr for self-managed, no cloud offering -custom development: $120/yr code server, $180/yr Redis managed, $180/yr postgresql managed = $480/yr diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Vendor info any risk to business 6ecbb09542ef478caeb5b327d783d74e.md b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Vendor info any risk to business 6ecbb09542ef478caeb5b327d783d74e.md deleted file mode 100644 index a8c8aa0..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548/Vendor info any risk to business 6ecbb09542ef478caeb5b327d783d74e.md +++ /dev/null @@ -1,7 +0,0 @@ -# Vendor info / any risk to business - -ThingsBoard.io ✓: thingsboard pro used by Engie, no SLA for community edition, dependent on internal developers -Crate.io ❌: — -Kaaproject.org: FDA and HIPAA as customers -OpenRemote.io ❌: Germany focus with some cities adopting it also Schipol security -custom development: SLA is fully dependent on internal developers diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548_all.csv b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548_all.csv deleted file mode 100644 index edce7ce..0000000 --- a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Last Round Alternatives 0ab7b7c54fa646a9ae62f45fe89de548_all.csv +++ /dev/null @@ -1,26 +0,0 @@ -Feature,custom development,ThingsBoard.io ✓,Kaaproject.org,OpenRemote.io ❌,Crate.io ❌ -"Total Cost of Ownership for paid premium option - 1 year, 10,000 devices","$120/yr code server, $180/yr Redis managed, $180/yr postgresql managed = $480/yr","$3600/yr for Docker+managed db or $6,000/yr for SaaS cloud, provides flexibility","$3600/yr for self-managed or $24,000/yr for managed on-premise ","$3600/yr for self-managed, no cloud offering",db-only $2616/month ❌ -Model,"IaaS: DigitalOcean droplet with custom stream-processing code, managed Redis db buffer for incoming data providing high-rel front end, then managed PostGreSQL db for IoT metrics. Custom device/partner management workflows on another platform e.g. Airtable-like no-code platform","Open Source or Managed PaaS: Monolithic/microservice interchangeable, IoT stream processing, device/partner management and and IoT Analytics platform in Docker on a DigitalOcean droplet with Aiven-Cassandra + PostGreSQL managed dbs on DigitalOcean. One downloadable package architecture, can be clustered ","Open Source or Managed PaaS: microservices type IoT stream processing, device/partner management and and IoT Analytics platform in Docker connecting to a Redis + PostGreSQL. No monolithic download so steeper initial learning curve","Assissted deployment only, no managed cloud options","Open Source or Managed PaaS: CrateDB is a distributed SQL database built on top of a NoSQL foundation. Customers often use CrateDB to store and query machine data. This is because CrateDB makes it easy and economical to handle the velocity, volume, and diversity of machine and log data." -"Open source ",—,"Yes, updated in 2021","Yes, updated in 2021","Yes, updated in 2021","Yes, updated in 2021" -Performance / scale,Full-custom,Single-container / managed cluster / cloud SaaS optionality,Kubernetes baked,,Highly scalable -Lock-in risk,Nil,Company could decide to fork free/paid codebases. Timestream data could be migrated but tenant management structure would probably need to fork codebase,Timestream data could be migrated but tenant management structure would probably need to fork codebase,Timestream data could be migrated but tenant management structure would probably need to fork codebase,Developing for specific db type could lead to harder migration options -"Basic Data External forwarding and Workflow triggers ",—,"Yes, Kafka stream and Rulechain configured from drag and drop UI",Yes Redis based queue,"'Rule-chain' for PAYG response seems very basic without custom scripts, only math/text functions ❌",Needs external SQL queries but performance is fast enough to support datastream analysis -Vendor info / any risk to business,SLA is fully dependent on internal developers,"thingsboard pro used by Engie, no SLA for community edition, dependent on internal developers",FDA and HIPAA as customers,Germany focus with some cities adopting it also Schipol security,— -Feature dev speed,~1wk-1mo,~1day-1wk (most common features are UI based),~1day-1wk (most common features are UI based),~1day-1wk (most common features are UI based),~1wk-1mo -Feature cost,Internal Development @$1000/month,Internal Development @$1000/month,Internal Development @$1000/month,Internal Development @$1000/month,Internal Development @$1000/month -"IoT Comms ",Customizable,"POST/MQTT/CoAP upload, GET request or Gateway subscribing via MQTT","POST/MQTT/CoAP upload, GET request or Gateway subscribing via MQTT",,— -API,Will need to be built,REST with JWT auth per device/entity,REST API,,— -Analytics for metrics,No,Yes,Yes,,Not inbuilt ❌ -Device management,Will need to be built,Yes with profiles and gateway MQTT-only devices,"Yes with profiles, versions and gateway MQTT-only devices",,No ❌ -Data management possiblity,Managed Redis + Managed PostgreSQL,"Part of docker image as starting point, Managed Cassandra (Aiven on DigitalOcean) + PostgreSQL (native DigitalOcean) database",Managed Redis + Managed PostgreSQL,, -Customer management,Will need to be built,Yes with groups and embeddable client dashboards,Yes with groups,,No ❌ -Customer support,Internal,Only for cloud otherwise internal,Only for cloud otherwise internal,, -Interoperable format compatibility,Yes,"JSON key-value pairs, additional Customizable 'connectors' for custom binary",JSON,, -Chart options,Will need external service e.g. No code big-data service,Moving line/bar/speed-gauge/map,Moving line/bar/speed-gauge/map,,No ❌ -Filters on displayed charts,—,Only time filters?,Only time filters?,,No ❌ -Dashboard UX,—,"Basic, sufficient","Basic, sufficient",,— -Login based filtering,Custom development,Yes,Yes,, -SSO types for users/customers,Custom development,Oauth2,Oauth2,, -Programming language,PHP,Java,Go,Go,Java -Device/Sandbox codebase,—,not seen any,"Arduino samples, web sandbox, etc",,Python client example -Git / source Link,—,https://thingsboard.io/docs/user-guide/install/digital-ocean/ also https://github.com/thingsboard/thingsboard,https://github.com/kaaproject/kaa,https://github.com/openremote,https://github.com/crate \ No newline at end of file diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-11_at_11.20.51_PM.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-11_at_11.20.51_PM.png deleted file mode 100644 index b641863..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-11_at_11.20.51_PM.png and /dev/null differ diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.07.11_PM.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.07.11_PM.png deleted file mode 100644 index 61a9fbe..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.07.11_PM.png and /dev/null differ diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.10.41_PM.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.10.41_PM.png deleted file mode 100644 index 17daf6f..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.10.41_PM.png and /dev/null differ diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.14.02_PM.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.14.02_PM.png deleted file mode 100644 index 331f980..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.14.02_PM.png and /dev/null differ diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.15.02_PM.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.15.02_PM.png deleted file mode 100644 index f04cdf4..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.15.02_PM.png and /dev/null differ diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.16.29_PM.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.16.29_PM.png deleted file mode 100644 index 6f4d438..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Screen_Shot_2021-04-12_at_12.16.29_PM.png and /dev/null differ diff --git a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Untitled.png b/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Untitled.png deleted file mode 100644 index 5680e46..0000000 Binary files a/docs/AirLink Server/How we chose Thingsboard io for AirLink Server fdf5dfccc506431c838c41eb1c407933/Untitled.png and /dev/null differ diff --git a/docs/AirLink Server/RelatingDevicesToEntities.gif b/docs/AirLink Server/RelatingDevicesToEntities.gif new file mode 100644 index 0000000..d308f08 Binary files /dev/null and b/docs/AirLink Server/RelatingDevicesToEntities.gif differ diff --git a/docs/AirLink Components.png b/docs/AirLink_Components.png similarity index 100% rename from docs/AirLink Components.png rename to docs/AirLink_Components.png diff --git a/docs/Connecting to Solaris or Angaza.md b/docs/Connecting to Solaris or Angaza.md index 67bf5d9..f463d07 100644 --- a/docs/Connecting to Solaris or Angaza.md +++ b/docs/Connecting to Solaris or Angaza.md @@ -32,9 +32,7 @@ To use AirLink with Solaris, you will need an account with Solaris that allows A *Note that requests for new PAYG credit/tokens are done to the Solaris platform in this case and AirLink only supports synchronizing with the devices.* - - -The end to end process for Solaris devices is shown in the following video: [Solaris AirLink device demo]() +The process for setting up PAYG devices is shown in the following video: [AirLink PAYG options](https://youtu.be/SR9axySPXTs) 1. **Credentials:** For simplicity, the authentication token required for a particular Solaris account's API access have been added to the json of the Solaris rule chain (the GitHub file has the development account token that need to be replaced with your own Solaris account's token). Before uploading the Solaris rule chain json file, open it in a text editor and look for OPGMServerToken, then replace the value in quotes (starting with eyJ... and ending with ...WEY in the example) with the value provided by Solaris - @@ -47,21 +45,16 @@ The end to end process for Solaris devices is shown in the following video: [Sol ![SolarisAuthInfo](Connecting%20to%20Solaris%20or%20Angaza/SolarisAuthInfo.png) *Note: Only one Solaris credential set is supported out of the box, which means that the functionality is most suited to distributors rather than manufacturers. Further development of the AirLink server is possible to support multiple Solaris credentials based on device group.* - 2. **Provisioning Solaris Devices:** To add Solaris devices, you will need to provision them both in the Solaris PAYGOPS platform as well as in AirLink separately. 1. To provision a single device to AirLink after adding it's details to the Solaris platform, use the AirLink App to provision the device and select payg_type as Solaris and Label as the serial number entered into the Solaris platform for that device. - - - ![Solaris device provisioning in AirLink]() - + ![Solaris device provisioning in AirLink](AirLink%20App/home%20-%20device%20list%20page%20-%20device%20details%20page%20-%20provisioning%20input%20with%20type%20expanded.jpg) 2. To provision devices in AirLink in bulk to connect to Solaris servers for PAYGO Tokens, use the format while uploading new devices in the following CSV File: - [TestSolarisDevices.csv](Connecting%20to%20Solaris%20or%20Angaza/TestSolarisDevices.csv) + [TestSolarisDevices.csv](Connecting%20to%20Solaris%20or%20Angaza/TestSolarisDevices.csv) 3. **PAYGO Tokens:** Solaris makes tokens available each time telemetry data is posted to the server. For this reason, the AirLink server expects any property to be updated for a Solaris device, upon which it will automatically download the latest token provided by the Solaris server. This token can then be pulled to the device using a 'GET' equivalent command for the pc_tkn property. Note that the demo app can do this automatically. - 4. **Telemetry Data:** Solaris servers provide a single POST-response method for posting data as well as getting tokens. When the AirLink server receives telemetry or attribute updates from a devices with the payg_type set to Solaris, it automatically forwards the telemetry data in the proper format to the Solaris servers, saving the latest token from the response. ## Angaza [Nexus Channel](https://github.com/EnAccess/OpenPAYGO-Token) and automatic device provisioning @@ -70,9 +63,7 @@ To use AirLink with Angaza, you will need an account with Angaza that allows API *Note that requests for new PAYG credit/tokens are done to the Angaza platform in this case and AirLink only supports synchronizing with the devices.* - - -The end to end process for Angaza devices is shown in the following video: [Angaza AirLink device demo]() +The process for Angaza PAYG is shown in the following video: [AirLink PAYG](https://youtu.be/SR9axySPXTs) 1. **Credentials:** For simplicity, the credentials required for a particular Angaza account's API access have been added to the json of the Angaza rule chain (the GitHub file has the development account credentials that need to be replaced with your own Angaza account's credentials). Look for the following in the Angaza rule chain .json file and edit it with your username (in place of airlink_nexus_demo) and password (in place of !2?6r*Cugq9Y) within the quotes, before uploading to the AirLink tenant: @@ -85,19 +76,13 @@ The end to end process for Angaza devices is shown in the following video: [Anga ![AngazaAuthInfo](Connecting%20to%20Solaris%20or%20Angaza/AngazaAuthInfo.png) *Note that only one Angaza credential is supported out of the box, which means that the functionality is best suited to a manufacturer. Further development of the airlink server is possible to support different device groups with different Angaza credentials if needed.* - 2. **Provisioning:** 1. To provision a single device to AirLink for use with the Angaza platform, use the AirLink App to provision the device and select payg_type as Angaza and Label as the serial number. The app and server will then *automatically add this to your Angaza platform* - - - - ![Angaza device provisioning in AirLink]() - + ![Provisioning via AirLink App](https://youtu.be/L4Tj_V7B4CE) 2. For bulk provisioning devices, Please use a format like the following CSV file to add Angaza devices, so that they get properly created in the Angaza server. Don't worry if something goes wrong, you can always delete devices and start again: - [TestAngazaDevices.csv](Connecting%20to%20Solaris%20or%20Angaza/TestAngazaDevices.csv) + [TestAngazaDevices.csv](Connecting%20to%20Solaris%20or%20Angaza/TestAngazaDevices.csv) 3. **PAYGO Tokens:** Angaza devices use tokens for two reasons - for PAYGO credit, and for device-device commands on authorized paired devices. Both types of tokens can be exchanged using the AirLink flow, and hence AirLink effectively enables both Nexus Token and Nexus Channel functionalities. Whenever any activity happens on an Angaza device in the AirLink server e.g. saving a property value, it will download the latest PAYGO token from the Angaza server so that it is available to sync. Angaza does not push tokens to the AirLink server, so it is necessary to have device activity to pull the latest token. The easiest way to achieve this is to update a timestamp property via a 'POST' type command from the device or app, and then 'GET' the pc_tkn for the latest token pulled from the Angaza server. Note that the demo app can do this automatically. - 4. **Telemetry Data:** Telemetry forwarding to Angaza is not supported out of the box i.e. Device properties such as location sent from the device will be saved to the AirLink server, but will not be automatically forwarded to Angaza. This is because Angaza requires first a registration of a ‘data format’ to save device data, which needs to be done per manufacturer spec. There is a stub of the rule chain required for this interchange setup in the Angaza rule-chain, and can be edited per each manufacturer’s preference! diff --git a/docs/Quick-start guide.md b/docs/Quick-start guide.md index b25d74e..e525a6b 100644 --- a/docs/Quick-start guide.md +++ b/docs/Quick-start guide.md @@ -3,6 +3,7 @@ Trying out AirLink is easy: 1. Download two Android app APK files and install on two smartphones + 1. one acting [as device](https://github.com/EnAccess/Airlink-Devices/releases/) - on a phone with Android 9 or lower - and 2. one acting as the actual [AirLink smartphone gateway](https://github.com/EnAccess/Airlink-App/releases/) - tested upto Android 11 2. [Request the Demo tenant server login](https://enaccess.org/airlink/) from EnAccess, @@ -35,55 +36,51 @@ AirLink is also for businesses who want their products secured against loss or t Once you decide to try your own AirLink deployment and obtain a login from EnAccess on the managed demo server which can handle startup-scale IoT traffic (the fastest way to get your own AirLink deployment going), or setup your own [Thingsboard.io](http://Thingsboard.io) server, here is a step by step setup for your tenant login in the AirLink server. -In short, you will first setup the server, then connect the AirLink App to the server, provision a device using the App, and finally generate a Pay as you go token for the airlink device. Here are the steps in detail: - -1. Assumption: You have a **“Tenant Administrator”** email login provided by EnAccess, or one that you made for your own server. Login with this administrator account. -Steps 2-5 are also covered in this video: +[A video playlist for setting up AirLink start to end](https://www.youtube.com/playlist?list=PLzs9gB3KSMw_u0zuKGCKE0x2EER0s6ONP) - [Tenant setup: Users, Profiles and Rule Chains](https://youtu.be/Sw0xrE0ZpbI) +In short, you will first setup the server, then connect the AirLink App to the server, provision a device using the App, setup data sychronization, and finally generate a Pay as you go token for the airlink device. Here are the steps in detail: +1. Assumption: You have a **“Tenant Administrator”** email login provided by EnAccess, or one that you made for your own server. Login with this administrator account. + Steps 2-5 are also covered in this video: [Tenant setup: Users, Profiles and Rule Chains](https://youtu.be/Sw0xrE0ZpbI) 2. Go to Users → Tenant Users, click on the + sign at the the top right of the page to create a new **Tenant User**. If activating by displaying activation link, note down the email and password. Note that the AirLink app uses this login information for administrative actions like registering devices via *Oauth*, whereas device data exchange is done using *access tokens*. -![AddingUsers.gif](AirLink%20Server/AddingUsers.gif) + ![AddingUsers.gif](AirLink%20Server/AddingUsers.gif) 3. Setup Device Profiles - - ![Screen Shot 2022-01-26 at 9.20.24 PM.png](AirLink%20Server/Screen_Shot_2022-01-26_at_9.20.24_PM.png) + ![Screen Shot 2022-01-26 at 9.20.24 PM.png](AirLink%20Server/Screen_Shot_2022-01-26_at_9.20.24_PM.png) 1. Setup a **“Gateways”** profile and enable the “Allow provisioning...” option. To do this, you need to tap the pencil button and then remember to save by pressing the tick-mark button. - - ![Screen Shot 2022-01-26 at 9.20.13 PM.png](AirLink%20Server/Screen_Shot_2022-01-26_at_9.20.13_PM.png) - + ![Screen Shot 2022-01-26 at 9.20.13 PM.png](AirLink%20Server/Screen_Shot_2022-01-26_at_9.20.13_PM.png) 2. Setup a **“Devices”** Profile, and enable the “Default” checkbox as in the figure above. Also enable the “Allow provisioning...” option as in the previous step 3. Copy the Provisioning Keys and Secrets, you will need to input these in the AirLink app! + 4. Import the **rule chains**: All data that flows to the thingsboard server goes to the root rule chain, and any other rule chain that the root chain hands off to. To process AirLink data, we created two rule chains saved as .json files in the [AirLink Server repository](https://github.com/EnAccess/AirLink-Server). This is where to find the Rule chains, just below the Home icon. - ![Screen Shot 2022-01-26 at 9.27.48 PM.png](AirLink%20Server/Screen_Shot_2022-01-26_at_9.27.48_PM.png) + ![Screen Shot 2022-01-26 at 9.27.48 PM.png](AirLink%20Server/Screen_Shot_2022-01-26_at_9.27.48_PM.png) 1. Make sure to import the lowest level rule chains first by following this order in Rule Chain → + → Import Rule Chain: - 1. **“Interact with other PAYG Software Providers”** - click save - - ![FirstRuleChain1.png](AirLink%20Server/FirstRuleChain1.png) + 1. **“Interact with other PAYG Software Providers”** - click save - ![FirstRuleChain2.png](AirLink%20Server/FirstRuleChain2.png) - 2. **“Root Advertisements and Telemetry”** - edit the link to the Interact with other PAYG Software Providers rule chain, then click save + ![FirstRuleChain1.png](AirLink%20Server/FirstRuleChain1.png) - ![SecondRuleChain1.png](AirLink%20Server/SecondRuleChain1.png) + ![FirstRuleChain2.png](AirLink%20Server/FirstRuleChain2.png) + 2. **“Root Advertisements and Telemetry”** - edit the link to the Interact with other PAYG Software Providers rule chain, then click save - ![SecondRuleChain2.png](AirLink%20Server/SecondRuleChain2.png) + ![SecondRuleChain1.png](AirLink%20Server/SecondRuleChain1.png) - ![SecondRuleChain3.png](AirLink%20Server/SecondRuleChain3.png) + ![SecondRuleChain2.png](AirLink%20Server/SecondRuleChain2.png) - ![SecondRuleChain4.png](AirLink%20Server/SecondRuleChain4.png) + ![SecondRuleChain3.png](AirLink%20Server/SecondRuleChain3.png) - ![SecondRuleChain5.png](AirLink%20Server/SecondRuleChain5.png) + ![SecondRuleChain4.png](AirLink%20Server/SecondRuleChain4.png) - 2. Mark the **“Root Advertisements and Telemetry”** rule chain as “Root” using the Flag icon next to it + ![SecondRuleChain5.png](AirLink%20Server/SecondRuleChain5.png) + 3. Mark the **“Root Advertisements and Telemetry”** rule chain as “Root” using the Flag icon next to it - ![Root rule chain.png](AirLink%20Server/Root%20rule%20chain.png) + ![Root rule chain.png](AirLink%20Server/Root%20rule%20chain.png) 5. That’s it for the minimum required configuration on the Server! Next, **configure your AirLink App** to talk to your server per the following video, and you are set to provision and test real devices! - - [AirLink App and End to End flow](https://youtu.be/OAEcQaUBIao) +[AirLink App and End to End flow](https://youtu.be/OAEcQaUBIao) 6. After registering a device using the above flow, you can **generate a Nexus Keycode PAYG token** for it by using the **Postman collection in the AirLink-Server repository.** + 1. Download both the **API calls** collection and the **environment**, and upload to your Postman (getpostman.com) 2. First use the login flow with the **Tenant User username/password** of the demo user to authenticate and get a JWT token, then 3. enter the **JWT token** into the Airlink environment current value diff --git a/docs/Simusolar_logo.png b/docs/Simusolar_logo.png index f3901b0..ab227ef 100644 Binary files a/docs/Simusolar_logo.png and b/docs/Simusolar_logo.png differ diff --git a/docs/Use Case - Device Manufacturer.md b/docs/Use Case - Device Manufacturer.md new file mode 100644 index 0000000..b58edcd --- /dev/null +++ b/docs/Use Case - Device Manufacturer.md @@ -0,0 +1,27 @@ +# A Device Manufacturer developing devices to be used in remote-region IoT data collection or PAYGO-financed use + +## Why + +AirLink saves manufacturers from the hassle of building out a custom IoT software backend for their hardware devices, and the open source format makes it likely that several adopters with different software stacks for business management can adopt AirLink devices. *This clear separation of the hardware and software stacks using the most commonly adopted ad-hoc wireless communication standard, Bluetooth®, is a key benefit of AirLink.* If your idea requires PAYGO devices *without* data connectivity, do also check out the [OpenPAYGO Token](https://enaccess.org/materials/openpaygotoken/). + +## Making your Devices compatible with AirLink + +Compatibility takes four simple steps focused on Advertisement and Data format, and optionally on authentication. + +1. Customize the Advertisement packet to match AirLink spec, as mentioned in the [AirLink Devices](AirLink%20Devices.md) page. The easiest way to do this is to fork the open source [Nordic nRF firmware codebase](https://www.nordicsemi.com/Products/Bluetooth-Low-Energy). +2. Group similar properties e.g. tempC, maxTemp. Create a [CBOR array](https://cbor.me) with these properties. These will be transferred once the app connects to the device. Collapsing several individual properties into one CBOR Array has the added benefit of making the data transfer memory efficient and fast. +3. Name the Bluetooth® *descriptor* with the property name e.g. 'temp'. Then, AirLink will understand your properties as temp_tempC, temp_maxTemp etc and on successful sync you will find these properties in the timeseries data for that device on the server. Device configurations are also saved similarly in dcfg_* properties. +4. Optional: Build an [access control flow](https://youtu.be/2zY5vETH4zk) in your devices which relies on a Server Access Token "password" unique to the device, starting with a pre-programmed value which is entered into to the firmware. Then, your device will only allow data transfer from/to a particular app which knows the default access token - and once provisioned on the server, will receive an access token *unique* to it. All device data access control will then be locked to phones that can access this unique device token from the server, based on the Role-Based Access Control functions available on the server. + +## Supplying AirLink Devices + +There are three main options to having distributors or end users adopt your AirLink devices. + +1. Get tenancy on the [AirLink Server](AirLink%20Server.md) and manage devices yourself, using API capabilities to interface with the software stack of the adopter. Upload devices using [CSV upload](Quick-start%20guide.md) to get them ready for the adopter's AirLink App. +2. Get tenancy on the [AirLink Server](AirLink%20Server.md) and use the built-in Angaza or Solaris integration to make your devices connect with one of those software stack, using credentials supplied by Angaza or Solaris. This means any adopter using those software stacks can use your devices, only requirement being obtaining manufacturer and/or distributor API credentials from Angaza or Solaris. +3. Send your devices to the distributor or end user with only the default access token programmed, and the distributor can then associate them with their own version of the AirLink App and their own server tenancy + +For each of the cases, the only input required to the devices after [Compatibility](#making-your-devices-compatible-with-airlink) is programming the default access token. Similarly, the only step required to move devices between distributors e.g. reselling stock is to change the default access token to the one supported by the other adopter. The devices themselves are separate from any custom functionality developed in the AirLink app for each distributor/user/adopter so the AirLink Bluetooth® protocol effectively acts to insulate the devices from software stack changes. + +!!! info "Bluetooth® SIG registration" + If your customer will be selling the devices without changing the product name or incorporating into another product, you might need to register with the Bluetooth® SIG at your cost (or negotiate with a distributor). You only have to do this once for all your products that depend on a single Bluetooth® IC e.g. nRF81822, or the Laird BL653 etc. More details are on the [AirLink Devices](AirLink%20Devices.md) page. diff --git a/docs/Use Case - NGO.md b/docs/Use Case - NGO.md new file mode 100644 index 0000000..f2ee8b5 --- /dev/null +++ b/docs/Use Case - NGO.md @@ -0,0 +1,44 @@ +# An NGO wanting to define a adaptable hardware/software standard for data collection in your projects or grantees + +## Why adopt AirLink as an NGO + +Several common needs for IoT data transfer at low cost and poor-network areas using a semi-skilled workforce of agents are covered natively by AirLink, and customization to a particular device type or project can be done with software modifications. Further, hardware devices get a clear spec to design to from this AirLink documentation, making it easier to engage contractors. + +## Out of the box + +AirLink, after you complete the *first three steps* in [the video playlist](https://www.youtube.com/playlist?list=PLzs9gB3KSMw_u0zuKGCKE0x2EER0s6ONP), also detailed in the [Quick-Start](Quick-start%20guide.md), can synchronize data from AirLink-compatible devices to the server without any other setup. Server data and device configuration updates can be pulled from the server when in network range, and device updates and data collection from the device can be done fully offline over Bluetooth®. This can be tested using the AirLink Gateway App and AirLink Devices app as shown in the guide. + +To customize this behavior for your own data collection project, you will need to customize your Bluetooth® device firmware as well as the open-source AirLink App as below: + +## Making Devices compatible with AirLink + +If the devices that will serve the data you need to collect have Bluetooth® enabled, then compatibility takes four simple steps focused on Advertisement and Data format, and optionally on authentication. Please discuss these with the device manufacturer, and ensure that they get the devices declared with the Bluetooth® SIG: + +1. Customize the Advertisement packet to match AirLink spec, as mentioned in the [AirLink Devices](AirLink%20Devices.md) page. The easiest way to do this is to fork the open source [Nordic nRF firmware codebase](https://www.nordicsemi.com/Products/Bluetooth-Low-Energy). +2. Group similar properties e.g. tempC, maxTemp. Create a [CBOR array](https://cbor.me) with these properties. These will be transferred once the app connects to the device +3. Name the Bluetooth® *descriptor* with the property name e.g. 'temp'. Then, AirLink will understand your properties as temp_tempC, temp_maxTemp etc and on successful sync you will find these properties in the timeseries data for that device on the server. Device configurations are also saved similarly in dcfg_* properties. +4. Optional: Build an [access control flow](https://youtu.be/2zY5vETH4zk) in your devices which relies on a Server Access Token "password" unique to the device, starting with a pre-programmed value which is entered into to the firmware. Then, your device will only allow data transfer from/to a particular app which knows the default access token - and once provisioned on the server, will receive an access token *unique* to it. All device data access control will then be locked to phones that can access this unique device token from the server, based on the Role-Based Access Control functions available on the server. + +## Building information ownership + +Want to assign devices to certain agents? Want to ensure that they automatically pull data when in range / on a button press? Need to store access tokens for certain devices on certain agent phones? No problem! All of these can be achieved using the API access between the AirLink App and the server, and the Role Based Access Control available in thingsboard. The full documentation for the server API is live at the server's [Swagger URL](https://airlink.enaccess.org/swagger-ui.html). + +Here are some starting ideas to get your work setup. These can be either done in the Flutter app itself, or on a server running your own application stack "Your Stack". + +1. Relating Agents and Devices - AirLink Server UI OR Flutter App OR Your Stack - The first step is to create a relation from the Agent or Customer, registered as a user or customer in the AirLink server, to your device. You can do this via the AirLink server UI, or API access using the "Tenant Administrator" role available in the Flutter app for demonstration, as shown below: + UI: ![Relating Devices to Other Entities via UI](AirLink%20Server/RelatingDevicesToEntities.gif) + + API: [Adding Relations via API](https://airlink.enaccess.org/swagger-ui/#/entity-relation-controller/saveRelationUsingPOST) + +2. Pulling relevant Server Access Tokens from the server for devices related to a particular app - Flutter App - The first step here is to relate each app instance to the user/customer created in Step #1. At Simusolar for example, we built a SMS based authentication flow for customers and an email based flow for our Staff, all using Thingsboard.io Rule Chains on the AirLink server connecting to our software stack via API. Once you have users/customers related to the app instance, the relations built in Step #1 will indirectly relate the devices to the app instance. You can then download a list of all the devices that have the relevant relationship, using a query based lookup supported by the AirLink server. For this, you will need to use the "Tenant Administrator" role in the Flutter App and access this API: + [Entity Query Controller](https://airlink.enaccess.org/swagger-ui/#/entity-query-controller) + and then then get the Access Tokens for each of the related devices: + [Device credentials by ID](https://airlink.enaccess.org/swagger-ui/#/device-controller/getDeviceCredentialsByDeviceIdUsingGET) + +## Using the devices and app to collect data at scale + +1. Device initialization and Use - Flutter App - [Provisioning AirLink apps and devices](https://youtu.be/L4Tj_V7B4CE) +2. Synchronizing data via app - Flutter App - [Synchronizing data](https://youtu.be/2zY5vETH4zk) +3. Optional: Create an Automation in your Flutter app that scans for devices, connects to them one by one and pulls data from them to make the process seamless for an Agent or user. The open-source app has the mechanism for the individual steps but leaves the process automation to you depending on your use case. + +--- diff --git a/docs/Use Case - Paygo Entrepreneur.md b/docs/Use Case - Paygo Entrepreneur.md new file mode 100644 index 0000000..f380db9 --- /dev/null +++ b/docs/Use Case - Paygo Entrepreneur.md @@ -0,0 +1,26 @@ +# A Fintech/PAYGO entrepreneur focused on innovative software, needing a standard hardware spec to share with a device manufacturer + +## Why AirLink as a Fintech/PAYGO entrepreneur + +Does your idea require network-connected or PAYGO devices at low cost? Are you planning on a smartphone app as the primary UI for the customer / end user? Do you want to get started with your idea quickly? + +## Trying AirLink out + +You can decide if AirLink is for you by simply downloading two apps and getting access to the demo server from EnAccess. The [Quick-start](Quick-start%20guide.md) outlines this process. + +## Saving MVP costs + +The EnAccess team are committed to open source innovation, and run the AirLink server for the same reason. By requesting your own tenancy on the server, you can start prototyping your custom app immediately! With in-build PAYGO functionality, AirLink takes the most complex but non-differentiating piece out of the equation and lets you focus on your differentiating development. If your idea requires PAYGO devices without data connectivity, do also check out the [OpenPAYGO Token](https://enaccess.org/materials/openpaygotoken/). + +## Idea -> differentiating development, quickly + +AirLink allows you to focus on what is unique to your business idea by abstracting away the complexity of setting up an IoT device-gateway-server connection. If the smartphone-centric use case is what you need, you can dive into your differentiating development while awaiting prototype devices from a manufacturer of your choice. After trying out the initial demo, follow this playlist to get your AirLink tenancy setup: + +[4 steps to full AirLink functionality](https://www.youtube.com/playlist?list=PLzs9gB3KSMw_u0zuKGCKE0x2EER0s6ONP) + +Then, focus on your *differentiating* development: + +1. Fork the Flutter code from the [AirLink Gateway app](https://github.com/EnAccess/Airlink-App/tree/main/airlink_flutter) and start developing. +2. Download the [AirLink Device demo app](https://github.com/EnAccess/AirLink-Devices) APK, so that you can use a phone as a representative device. If it helps, modify the simple Android-native Java source-code to add more 'device' functionality to the device demo app. +3. Provide the [AirLink Devices](AirLink%20Devices.md) spec and the [Nordic nRF firmware codebase](https://www.nordicsemi.com/Products/Bluetooth-Low-Energy) as a reference to any hardware manufacturer capable of making a Bluetooth® device to your specifications. +4. Use the [Swagger documentation](https://airlink.enaccess.org/swagger-ui.html) for API access to the AirLink server and read the [Thingsboard PE documentation](https://thingsboard.io/docs/pe/) as you develop complex customer-device functionality using Thingsboard.io's full Pro version! diff --git a/docs/assets/EnAccess_Logo_Digital_Inverse.svg b/docs/assets/EnAccess_Logo_Digital_Inverse.svg index 3fb11d9..452303d 100644 --- a/docs/assets/EnAccess_Logo_Digital_Inverse.svg +++ b/docs/assets/EnAccess_Logo_Digital_Inverse.svg @@ -1,5 +1,5 @@ - +