Introduction
This document is an introduction to UNO, explaining its basic concepts and functions.
What is UNO
Undagrid UNO is a service to leverage smart and IoT devices as gateways to access location and sensor data from a vast amount of available BLE devices. It does this by delivering a suite of tools that make it easy to integrate and use. The suite consists of:
- An iOS and Android SDK. The SDK is installed in an app and runs in the background. The UNO SDK will scan for specific BLE devices and send location data encrypted to the UNO cloud
- The UNO Cloud will store the encrypted data until it is fetched by the user via the UNO client API
- UNO client API is able to retrieve the encrypted data and pass it on to the client environment for decryption, decoding, and further processing
- A UNO-embedded SDK. Similar to the smartphone SDK, this SDK can be embedded into IoT devices with BLE scanning functionality.
Positioning
The smart device SDK uses the phone’s positioning systems together with the RSSI of the tag to provide position information. The phone can use GPS, WiFi, Cellular, Bluetooth, or a combination of these technologies to determine its position. The embedded SDK relies on the positioning mechanism of the IoT device, which can be anything from GPS to a static location.
Activity
Every location message of a tag is also tagged with the activity of the scanning phone. This information may be used to derive further context information.
Payload
Next to location, payload information of a tag can be transferred as well, giving the possibility to gain insights into things like temperature, motion, light, etc.
What payload to send can be configured via the UNO Cloud and does not need any changes to the UNO SDK.
Privacy and Security
Next to location, payload information of a tag can be transferred as well, giving the possibility to gain insights into things like temperature, motion, light, etc.
What payload to send can be configured via the UNO Cloud and does not need any changes to the UNO SDK.
Location awareness
The UNO services are location-aware, meaning that a client can configure what tags to scan where. For instance, fixed tags only need to be scanned at the relevant locations. While roaming tags may cover a much larger area, or come from specific locations. These locations can be configured at leisure and may be as complex as needed for the use case.
Low power
The UNO smart device SDK strives to use as little power as possible, by using location awareness, user activity, and using the phone’s location systems in smart ways, so that impact of the device’s battery life is minimized.
Technical details
In this section, we will go a bit deeper into the technical details of the Undagrid UNO services
Encryption
As mentioned before, location and payload data are end-to-end encrypted. Meaning that a message is encrypted on the phone, and only decrypted in the client environment. Moreover, every message uses its own individual encryption key, lowering the chances and impact of a key breach.
In more detail, this is how it works:
- Every BLE device gets an identifier. This identifier must be derivable from the payload data and can be set up via the Scan Profiles which we will cover later on
- A client must provide the UNO Cloud with a hash of this identifier and a public key for the BLE device. This means that the UNO Cloud does not know the real identifier of the BLE device. The private key remains at the client
- When the UNO SDK identifies a BLE device, it asks the UNO cloud for its public key based on the identifier hash.
- When the UNO SDK desires to send a new message for the BLE device, it will generate a new keypair key, and generate a new shared key with this private key and the devices’ public key. The shared key is used to encrypt the message. The encrypted message, device identifier hash, and the generated public key are sent to the UNO Cloud
- The UNO Cloud keeps the encrypted message until the client environment retrieves it
- The client environment can then decrypt the message again. For this, it used the private key of the BLE device, and the public key attached to the message. These two will result in the same shared key used in the encryption process and can therefore be used to decrypt the message
For the key exchanges X25519 is used, and for encryption aes-128-gcm is used.
Scan profiles
Scan profiles are used to instruct the SDKs to scan for specific beacons. These profiles have two main functions:
- identify a tag
- extract payload information
Identification of tags is important so that the device can be uniquely identified and the proper encryption methods can be used to transfer the payload data. Extraction of payload information lets you pinpoint whatever specific data you want to extract from the BLE tags without the need to send all the redundant payload data.
Both of these functions are implemented in a similar way. Let’s explore the structure of a scan profile:
Field | Description |
---|---|
id | an id generated by the UNO cloud |
name | optional name for the scan profile |
scanFor | instructs the SDK what to scan for. Currently only BLE 16-bit service ID’s are supported, in the format: uuid://<16-bit hex uuid> ttk a time to live for the profile. After this time the SDK needs to reload the profile from the server |
matches | an array of match objects, described below |
The matches are the powerhouse of the Scan Profile and describe what to filter:
Field | Description |
---|---|
match | A regular expression. This regular expression tries to match the payload data of the BLE packet. In case of service data, it only matches the service data payload |
id | an optional regular expression replacement to form the identifier of the ble tag. When this field is missing, normal payload data is assumed |
group | an array of match indexes that form the type of packet. This is used by the SDK to duplicate payload data |
payload | an array of match indexes that form the payload to transfer. if this field is missing, the full payload is transferred |
GeoJSON
{
"properties": {
"scanProfiles": [
"w4X9nqqMZVFhWeNsFY6Bwd",
"ocEUbE4t8wvdwVYz23gKJL"
]
}
}
To determine what get’s scanned and where one or more GeoJSON files can be uploaded to the UNO Cloud. These are standard GeoJSON files. Every feature can be tagged with multiple Scan Profiles ids’ by adding them to the features properties object as an array.
Buckets
A bucket is a logical endpoint for a client to fetch data. Every BLE tag that the clients add to the UNO Cloud can be assigned to a bucket. So the bucket aggregates data from all the tags assigned to it. The client can then access all this aggregated data all at once via a single API call.
The API call can be used in polling mode, so, called every few seconds to fetch new data. Or in long-polling mode, where the client keeps the connection open, and new data is pushed in real-time to the client until the connection is closed again.
Buckets also offer some statistics on the number of messages delivered to it and the number of currently buffered messages.