IoT Pro Protocol Overview

1.1 Data Structure

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


1.1.2 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.

This means that the general structure of any parser should always start with a basic algorithm to read the the ID and skip its associated data length if the ID is not implemented by the user.

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


1.2 ID Ranges and Data Length Rules

ID Addresses (DEC)

ID Addresses (HEX)

Data length (Bytes)

No. of Allocated IDs

1-2000

0x0001-0x07D0

0

2000

2001-4000

0x07D1-0x0FA0

1

2000

4001-6000

0x0FA1-0x1770

2

2000

6001-8000

0x1771-0x1F40

3

2000

8001-10000

0x1F41–0x2710

4

2000

10001-12000

0x2711–0x2EE0

5

2000

12001-14000

0x2EE1–0x36B0

6

2000

14001-16000

0x36B1–0x3E80

7

2000

16001-18000

0x3E81–0x4650

8

2000

18001-20000

0x4651–0x4E20

9

2000

20001-22000

0x4E21–0x55F0

10

2000

22001-24000

0x55F1–0x5DC0

11

2000

24001-26000

0x5DC1–0x6590

12

2000

26001-29000

0x6591–0x7148

Variable with 1 byte length

3000

29001-32000

0x7149–0x7D00

Variable with 2 byte length

3000

32001-65535

0x7D01–0xFFFF

Reserved

33535

1.3 Timestamp Handling

1.3.1 Timestamps are represented as 4-byte unsigned UNIX time

You can use this website to convert the UNIX timestamp from its ASCII format to normal date and time.

1.3.2 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: ""

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

1.4 CRC Integration

1.4.1 If CRC is included, it must be the last ID/data pair in the message.

1.4.2 CRC is computed over all previous bytes, including the 2-byte ID of the CRC itself.

1.5 Header and Protocol Metadata

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

1.5.2 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.

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

1.6 Compatibility

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

Once built, a parser can be used for multiple applications with minimal modifications.

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

1.7 Downlinks

Application and Network Settings configuration are provided for free through the IoT Pro Software Platform - There is no subscription, and we still allow to control and manage directly

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

1.7.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.

1.7.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.

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

1.7.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.

1.8 Acknowledgments

This applies to Cellular networks only. LoRa networks use their own confirmed or non-confirmed message mechanism instead.

1.8.1 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.



1.9 Packet Size

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

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

2.0 Fields Naming Convention

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

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

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

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

2.1 Alerts Convention

2.1.1 Alerts are grouped by channel.

2.1.2 The same alert can be reused in different applications if it applies.