Data Structure

Every payload consists of a series of data blocks, each beginning with a 2-byte ID.

Each ID indicates: the type and length of data, how to parse the data, the parser can skip the data if it does not know how to parse the ID.

Parsing information is included in the parsing table of fields and future IDs will follow the same structure to allow forward and backwards compatibility.

ID Ranges and Data Length Rules

Timestamp Handling

Timestamps are represented as 4-byte unsigned UNIX time

A single timestamp applies to all following IDs until another timestamp ID appears. This means that the timestamp or end of packet defines the start/end of an event.

---
config:
  packet:
    bitsPerRow: 22
    bitWidth: 40
    rowHeight: 36
    showBits: False
    
title: Example Packet
---
packet
+1: "Start"
+2: "2 Bytes"
+2: "4 Bytes"
+2: "2 Bytes"
+2: "x Bytes"
+2: "2 Bytes"
+2: "x Bytes"
+2: "2 Bytes"
+2: "4 Bytes"
+2: "2 Bytes"
+2: "x Bytes"
+1: "End"

+1: ""
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+1: ""

+1: ""
+2: "Timestamp"
+2: "UNIX"
+2: "Temperature"
+2: "data"
+2: "Humidity"
+2: "data"
+2: "Timestamp"
+2: "UNIX"
+2: "Temperature"
+2: "data"
+1: ""

+1: ""
+12: "Event 1"
+8: "Event 2"
+1: ""

The timestamp before IDs for settings is when the settings were last updated from online or from the mobile application.

Header and Protocol Metadata

LoRa: No headers or FPort usage is required in the application layer. The DevEui (device id) is included inherently within the LoRa protocol.

Cellular: There is no fixed or hardcoded header, but the IMEI, application type are always specified through the respective IDs and are sent with every message.

SIGFOX: There is no fixed or hardcoded header, but the SIGFOX ID (device id) is included inherently within the SIGFOX protocol.

Compatibility

Payload structure must maintain backward compatibility, across firmware versions and even across different applications.

Parsers not updated with new IDs should be able to skip unknown IDs based on length and continue parsing.

Downlinks

1. Downlink messages are used to update the device settings, issue software commands (ex. FOTA Server Sync, Device Reset), and hardware control.

2. Downlink messages must follow the same format and parsing rules as uplinks for consistency and reuse of parsing logic. This means multiple IDs can be bundled within the same downlink using the format {id}{value}. Timestamps are not required as delimiters.

3. Downlink messages that include settings IDs are confirmed with an uplink containing the new settings, typically sent after 1 minute. This confirmation uplink may also include other IDs such as telemetry data.

4. Commands are downlink-only and will not be echoed back by the device as uplinks.

5. LoRa-specific: When queuing a downlink, flush the queue first to remove any previous downlinks that may no longer be relevant. Use Port 1 for queuing downlinks.

Acknowledgments

If Message Confirmation is enabled (default is enabled), the Downlink should include ID 0x07E1 to confirm every uplink received. This acknowledgment needs to be sent so that the connection between server and device is terminated.

Packet Size

• The maximum Cellular Uplink and Downlink payload sizes are of 1024 bytes.

• The maximum LoRa Uplink and Downlink payload sizes are dependent on the Data Rate.

Fields Naming Convention

• Field names are all snake case and lower case without special characters.

• Fields start with either one of the following: time, network_common, network_nbiot, network_lora, device, telemetry

• Fields can either be a parameter (param) or a setting (set), in which case the latter is generally both an uplink and a downlink.

• Events (all data following one timestamp and ending at the next timestamp) cannot have a mix of parameters and settings.

Alerts Convention

Alerts are grouped by channel and the same field name can be reused in different applications if it applies.

CRC Integration

If CRC is included, it must be the last ID/data pair in the message. CRC is computed over all previous bytes, including the 2-byte ID of the CRC itself.

Security and Data Protection

Security Concepts

Authentication: Verifies that data comes from an authorised source and has not been tampered with. Authentication does not hide or scramble the data itself.

Encryption: Scrambles data into an unreadable form so that unauthorised parties cannot understand it without the correct key. Encryption alone does not verify who sent the data or whether it was modified.

Integrity: Ensures that data has not been altered or corrupted during transmission. If a protected message is modified, the receiving system can detect the modification and reject the message.

Best practice: Authentication and encryption are commonly used together to provide both data confidentiality and integrity.

Communication Path

The diagram below shows the typical communication path between a device and the Platform Backend.

For LoRaWAN and Sigfox, security is provided by the network technology between the device and its respective Network Backend. This includes authentication, integrity protection and encryption of the transmitted data. The Network Backend then forwards the data to the IoT Pro Platform Backend using secure communication methods such as HTTPS or AMQP/RabbitMQ.

For cellular technologies such as NB-IoT and LTE, the 3GPP security mechanisms provide authentication, confidentiality and integrity protection between the device and the cellular network. These mechanisms protect the cellular connection, but do not provide end-to-end security between the device and the Platform Backend.

The connection from the cellular Network Backend to the Platform Backend can therefore be protected using additional network-level security mechanisms or, where appropriate, application-level encryption and authentication. IoT Pro provides application-level security through its IoT Pro Protocol Security mechanism, described below.

Cellular Security

In addition to application-level encryption and authentication, cellular networks offer the following additional security options:

• Private APN/IP whitelisting - by opting for a Private APN, the range of IP addresses originating from the devices can be restricted and thus the Platform Backend can opt to allow incoming connections only from a restricted range of IPs

• VPN tunnel - establishes a private, encrypted connection between the network backend and the platform backend

IoT Pro Protocol Security (Application Layer)

IoT Pro Protocol Security is optionally available for Cellular networks where additional end-to-end protection is required. The protocol uses AES-128-CCM, which provides both encryption and authentication and integrity protection between the device and the IoT Pro Platform Backend.

Each device is provisioned with a unique, randomly generated pre-shared key (PSK) during manufacturing. For direct software integrators, the corresponding device-specific key is securely provided to the authorised customer for configuration within the Platform Backend.

Why application-level security?

Transport-layer security protocols such as DTLS can provide encryption and authentication for UDP-based communication. However, they introduce additional protocol and processing overhead.

Encrypted Packet Structure

When protocol security is enabled, the packet structure is extended to include the cryptographic information required to encrypt and authenticate the data. The encrypted packet follows the structure below:

---
config:
  packet:
    bitsPerRow: 18
    bitWidth: 40
    rowHeight: 36
    showBits: False
    
title: Encrypted Packet Structure
---
packet
+1: "Start"
+2: "2 Bytes"
+2: "7 Bytes"
+2: "2 Bytes"
+2: "12 Bytes"
+2: "2 Bytes"
+2: "x Bytes"
+2: "2 Bytes"
+2: "8 Bytes"
+1: "End"

+1: ""
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+2: "ID"
+2: "Data"
+1: ""

+1: ""
+2: "IMEI"
+2: "data"
+2: "Nonce"
+2: "data"
+2: "Ciphertext"
+2: "data"
+2: "Auth Tag"
+2: "data"
+1: ""

The presence of the Nonce indicates that protocol security is enabled for the packet.

• Nonce: A unique value used for the encryption operation. A different nonce is used for each encrypted packet.

• Ciphertext: The encrypted IoT Pro data. The original data cannot be read without the corresponding pre-shared key.

• Authentication Tag: Used to verify the authenticity and integrity of the encrypted data. If the data has been modified or the authentication verification fails, the packet is rejected.

The combination of the pre-shared key, unique nonce, encryption, and authentication tag provides end-to-end protection of the IoT Pro data between the device and the Platform Backend.

Firmware Security

Firmware updates are protected using a secure bootloader and cryptographic verification. Firmware images, whether delivered via BLE OTA or FOTA, must be authenticated before they are accepted for installation.