Improve video embed and fix missing figures (#8)

* Videos and Images fixed for embedding and lost URLs * lint fix * Update mkdocs.yml * Organized use case md files into a folder * Update mkdocs.yml * Update mkdocs.yml * Update AirLink Devices.md * Fixed Broken links and added video embeds to Use Cases --------- Co-authored-by: Daniel Mohns <[email protected]>
EnAccess · Nov 6, 2023 · 0a09f7b · 0a09f7b
1 parent a0598c5
commit 0a09f7b
Show file tree

Hide file tree

Showing 8 changed files with 233 additions and 73 deletions.
diff --git a/docs/AirLink App.md b/docs/AirLink App.md
@@ -95,14 +95,13 @@ Once authorized, you can now read data from the device. The App receives CBOR en
 
 If a device has just been manufactured, it may not yet be serialized, and be locked with a default access token. Enter this token, then press “Provision” to provision the device. The app will prompt for serial number entry.
 
-![2.4 PROVISION - Choice for serialization.jpg](AirLink%20App/home%20-%20device%20list%20page%20-%20device%20details%20page%20-%20provisioning%20input.jpg)
+![PROVISION - Choice for serialization.jpg](AirLink%20App/home%20-%20device%20list%20page%20-%20device%20details%20page%20-%20provisioning%20input.jpg)
 
 Scan or enter by hand this serial number. This is a one-time activity after which the device will forever remember it’s serial number. However if the serial number exists on the server, the provisioning will fail. As long as a unique serial number is supplied, the server accepts the device and returns a device-specific access token, which the app saves automatically to secure storage as well as displays in the access token field
 
-![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):
+!!! info "Provisioning Solaris or Angaza devices"
+    For Solaris devices, uploading a CSV to the AirLink server (and correspondingly adding them to the Solaris Distributor account) is the only option.
+    Angaza devices can be provisioned via the AirLink app. All you need are your Angaza API credentials for the manufacturer role. Enter these in the server (see rule-chains section):
     <style>
     .youtube-embed-container {
     position: relative;
@@ -124,9 +123,36 @@ Scan or enter by hand this serial number. This is a one-time activity after whic
     </iframe>
     </div>
 
-    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)
 
+### Synchronizing data with the server over the lifetime of the device
+
+All AirLink properties can be kept in sync between the server and the individual device simply by tapping the Sync button, or using the underlying function in an automated flow in your custom version of the app. The ability of the gateway to post device data to the server (”Client Scope”) as well as pull server data into the device (”Shared Scope”) generates a success message. All failure messages can be effectively debugged using the USB-connected debug mode of Visual Studio or IntelliJ.
+
+![Syncing data](AirLink%20App/home%20-%20device%20list%20page%20-%20device%20details%20page%20sync.jpg)
+
+The previous few steps about connecting to devices and synchronizing data are also described in this video:
+     <style>
+     .youtube-embed-container {
+     position: relative;
+     padding-bottom: 56.25%;
+     height: 0;
+     overflow:
+     hidden; max-width: 100%;
+     }
+     .youtube-embed-container iframe,
+     .youtube-embed-container object,
+     .youtube-embed-container embed { position: absolute; top: 0; left: 0; width: 100%; height: 100%; }
+     </style>
+     <div class="youtube-embed-container">
+     <iframe
+     src="https://youtube.com/embed/2zY5vETH4zk?enablejsapi=1"
+     frameborder="0"
+     allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+     allowfullscreen>
+     </iframe>
+     </div>
+
 ### 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.
@@ -141,11 +167,27 @@ The AirLink App also demonstrates the ability to generate PAYG Tokens for AirLin
 
 ![Token Generation](AirLink%20App/home%20-%20payg%20token%20page%20-%20token%20generated.jpg)
 
-### Synchronizing data with the server over the lifetime of the device
-
-All AirLink properties can be kept in sync between the server and the individual device simply by tapping the Sync button, or using the underlying function in an automated flow in your custom version of the app. The ability of the gateway to post device data to the server (”Client Scope”) as well as pull server data into the device (”Shared Scope”) generates a success message. All failure messages can be effectively debugged using the USB-connected debug mode of Visual Studio or IntelliJ.
-
-![Syncing data](AirLink%20App/home%20-%20device%20list%20page%20-%20device%20details%20page%20sync.jpg)
+Also see this video!
+     <style>
+     .youtube-embed-container {
+     position: relative;
+     padding-bottom: 56.25%;
+     height: 0;
+     overflow:
+     hidden; max-width: 100%;
+     }
+     .youtube-embed-container iframe,
+     .youtube-embed-container object,
+     .youtube-embed-container embed { position: absolute; top: 0; left: 0; width: 100%; height: 100%; }
+     </style>
+     <div class="youtube-embed-container">
+     <iframe
+     src="https://youtube.com/embed/OAEcQaUBIao?enablejsapi=1"
+     frameborder="0"
+     allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+     allowfullscreen>
+     </iframe>
+     </div>
 
 ## Architecture
 

diff --git a/docs/AirLink Devices.md b/docs/AirLink Devices.md
@@ -1,16 +1,15 @@
 # AirLink Devices
 
-![bluetooth-logo.png](AirLink%20Devices/bluetooth-logo.png)
+!!! info "Preface: A note on Bluetooth® SIG requirements, Oct 2023"
+      ![bluetooth-logo.png](AirLink%20Devices/bluetooth-logo.png)
 
-**Preface:** A note on Bluetooth® SIG requirements, Oct 2023
+      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.
 
-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* 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.
 
-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.
 
-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.*
 
 ---
 
@@ -145,9 +144,6 @@ A gateway device reads this resource while scanning for devices (before a connec
 | 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                                                                                                                                                                                                                                                                              | <http://thinsboard.io> has a 20-char device authentication token unique to each device                                                                                     |
 
 ### PUE Use Service
 

diff --git a/docs/AirLink Server.md b/docs/AirLink Server.md
@@ -10,6 +10,27 @@ We have created a fully functional demo tenant to enable quick testing of AirLin
 
 Follow the tenant configuration section in
 [Quick-start guide](Quick-start%20guide.md#tenant-config)
+Also shown in this video:
+    <style>
+    .youtube-embed-container {
+    position: relative;
+    padding-bottom: 56.25%;
+    height: 0;
+    overflow:
+    hidden; max-width: 100%;
+    }
+    .youtube-embed-container iframe,
+    .youtube-embed-container object,
+    .youtube-embed-container embed { position: absolute; top: 0; left: 0; width: 100%; height: 100%; }
+    </style>
+    <div class="youtube-embed-container">
+    <iframe
+    src="https://youtube.com/embed/6GAqmAPOLjI?enablejsapi=1"
+    frameborder="0"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowfullscreen>
+    </iframe>
+    </div>
 
 ## AirLink IoT Server Architecture
 

diff --git a/docs/AirLink_Unknown_Device_Flow.png b/docs/AirLink_Unknown_Device_Flow.png
diff --git a/docs/Quick-start guide.md b/docs/Quick-start guide.md
@@ -1,6 +1,6 @@
 # Quick-start guide
 
-Trying out AirLink is easy:
+## Trying out AirLink is easy
 
 1. Download two Android app APK files and install on two smartphones
 
@@ -52,7 +52,7 @@ AirLink is also for businesses who want their products secured against loss or t
     1. Develop your business integrations further by building on the open source app for clients or API integrations with the IoT server
     2. Don't forget to integrate with the EnAccess server for the inter-company, crowdsourced 'Neighborhood Watch' (lost assets database)
 
-### How to get started with your own AirLink deployment
+## How to get started with your own AirLink deployment
 
 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.
 
@@ -139,12 +139,32 @@ In short, you will first setup the server, then connect the AirLink App to the s
      </iframe>
      </div>
 
-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.**
+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.** or the built-in functionality in the Gateway App:
+     <style>
+     .youtube-embed-container {
+     position: relative;
+     padding-bottom: 56.25%;
+     height: 0;
+     overflow:
+     hidden; max-width: 100%;
+     }
+     .youtube-embed-container iframe,
+     .youtube-embed-container object,
+     .youtube-embed-container embed { position: absolute; top: 0; left: 0; width: 100%; height: 100%; }
+     </style>
+     <div class="youtube-embed-container">
+     <iframe
+     src="https://youtube.com/embed/OAEcQaUBIao?enablejsapi=1"
+     frameborder="0"
+     allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+     allowfullscreen>
+     </iframe>
+     </div>
 
-    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
-    4. Use the Generate Token flow with the correct device ID to generate a Nexus Keycode **PAYG token** for your device. This token will be automatically saved in the device properties as well
-    5. Connect the AirLink App and type the token in manually into the PC resource, or via keypad as shown in the video above
+     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
+     4. Use the Generate Token flow with the correct device ID to generate a Nexus Keycode **PAYG token** for your device. This token will be automatically saved in the device properties as well
+     5. Connect the AirLink App and type the token in manually into the PC resource, or via keypad as shown in the video above
 
 7. If you are connecting to one of the supported built-in integrations - Solaris Or Angaza, follow this guide to connect AirLink devices to those software stacks: [Connecting to other PAYGO software providers](Connecting%20to%20Solaris%20or%20Angaza.md)