# Reliable protocols
Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (opens new window).
# Overview
The Reliable protocols can be used to transfer data reliably. They are responsible for the end-to-end communication between the End Device and the Gateway or between End Devices. They provides the application with an easy-to-use protocol that makes standardized communication possible in a simple and maker-friendly way.
One MAY use the Application Layer protocol but it is not a requirement. Setting the Application protocol ID to 14 allows for implementing an user-defined application protocol.
# Protocol ID numbers
This table lists the Application protocol ID numbers used in the Transport Header (THdr):
| App protocol ID | Description |
|---|---|
| 0 | No data (used for ack packets) |
| 1 | Network Command protocol |
| 2 | Network Event protocol |
| 3 | Application Command protocol |
| 4 | Application Event protocol |
| 5 | Generic Attribute Protocol |
| 6-13 | Reserved |
| 14 | User defined protocol (proprietary) |
| 15 | Reserved |
# Firmware update Process
In order to make the most spectrum efficient firmware update process, the data is broadcast to multiple devices. Only end devices that support 2-way communication can be firmware upgraded. If the End Device needs to know when the Firmware update is broadcast, it must periodically ask for an acknowledgement packet when sending data. It is recommended that the ED asks for an ACK at least once per 24 hours. When the ED get the acknowledge packet it will have the FCtrl flag “Pending frame” set. The next message it will receive is a 0x21 “Wake up in X seconds for firmware update. This is done in order to synchronize multiple devices to receive the firmware update all at the same time. This message contains frequency, speed, modulation and “seconds from now” for when the device MUST wake up. When the EDs selected for firmware update wakes up, they change frequency channel and wait until it receives the firmware update begin message (0x24). Firmware update message is received and is followed by the firmware data messages (0x26) EDs reads the information message and therefore knows how many 0x26 firmware update messages that it must receive. ED receives the Firmware update end message (0x28).
The Gateway will send the FW update three times successively starting with the Firmware update information message (0x24) followed by the data (0x22) messages ending with the end message (0x28). This will allow the ED to receive possible lost packets.
# Encryption
AES128 CBC
IV is set to:
000102030405060708090a0b0c0d0e0f
Key is individually set for each End Device. In case the End Device has a SerialID, this can be used as the 128 bit encryption key.
# Network time format
The time format is designed to be easy to use by the End Devices. The RTC in a microcontroller is typically setup using hour, minute, day, month etc. and not Unix time.
The format is an array of 8 bytes:
| RFU 1 byte | Year 1 byte | Month 1 byte | Day 1 byte | Weekday 1 byte | Hours 1 byte | Minutes 1 byte | Seconds 1 byte |
|---|
All fields are uint8:
| Field | Range | Description |
|---|---|---|
| Year | 0-99 | The last two digits of the year |
| Month | 1-12 | Month |
| Day | 1-31 | Day of Month |
| Weekday | 0-6 | Sunday=0, Monday=1, Tuesday=2, Saturday=6... |
| Hours | 0-23 | 24H format. |
| Minutes | 0-59 | |
| Seconds | 0-59 |
# Application Command messages
Application commands are defined by the protocol and MAY be extended by the use of proprietary Application Commands. The Command ID is set in the Frame Options (FOpts) field of the frame and the payload is command specific.
# Application Event messages
Event messages are defined by the protocol and MAY be extended by the use of proprietary Network events. The event ID is set in the Frame Options field (FOpts) of the frame and the payload is specific to the event.
The corresponding Ack frame payload is application specific and does not need to adhere to this standard.