# Software update
Being able to push out Software or firmware updates, is essential for Device security. Usually, the network operator wants to control when the software update is applied and whether it was applied successfully. This specification describes how the scheduling, retrieval and status event are exchanged.
There are two ways of Firmware Over The Air (FOTA) update a device. Provided that at a Content Store on the network contains the software update: A device can either 1) retrieve and apply the update at its own request, or 2) the network operator can send a "Schedule Update" Device Command, which will cause the network to broadcast/send the software update to the device at the specified time. The last option is particular useful when updating multiple devices on duty-cycle restricted frequency bands like 915/868MHz or 433MHz bands.
# Scheduling
When a device receives a "Schedule update" Device command, there are two options for the retrieval of the software, depending on the device is contrained or not:
- The Network will broadcast the update on the specified time (constrained device)
- Requesting the network to send the update (non-constrained device)
The internal flash-memory on constrained devices typically has a limited write-speed and buffer memory, so network MUST therefore send the update packets with a suitable delay between the packets.
Many wireless devices is operating in a frequency band with a duty-cycle restriction (eg. Sub-GHz). The Network SHOULD therefore support the option of broadcasting the software update to many devices at once.
# Content Name
The content name is comprised of the Z-Mesh Network Management Name prefix, the manufacturer, model, version and the sequence number of the packet.
| Content name | Description |
|---|---|
| zdm/sw/<MANUFACTURER>-<MODEL>-<VERSION> | Software upgrade |
When the software update is made available to the network, it MUST be split in chunks that will fit in the MTU (maximum transfer unit) of the physical medium of the receiving device. This number is typically between 48 and 104 bytes and SHOULD be in multiples of the AES encryption algorithm blocksize, which is probably 16 bytes.
# FOTA Scheduling message format
To update a device, the Device Management system will send out a FOTA scheduling message, detailing when, where and how to be ready for the upgrade. The format is as follows:
| Update Time | Content Name | MTU | Enc. Type | Enc. IV | Enc. Key |
|---|---|---|---|---|---|
| 6 bytes | 6 bytes | 2 bytes | 1 byte | 9 bytes | 16 bytes |
Update time and Content Name will tell the device when and on what Content name to receive the update. The MTU (Maximum Transfer Unit) MAY be used by the device in preparing for the update. Encryption SHOULD be used and is specified using the Enc. Type, IV and Key fields.
# Encryption
The software update SHOULD be encrypted.
# Protocol messages
The Software upgrade process is a sequence of messages starting with a Software Begin Message with SEQ=0. Then a sequence of data messages starting with SEQ=1, ending with Software Update End Message. Thus it is the SEQ in the Content Name that determines the order or the chunks.
# Update Begin message
The Software update Begin message is the first message. This will let the devices know what is to follow.
The format is as follows:
| FW Length | FW CRC32 | FW Num packets |
|---|---|---|
| 4 bytes | 4 bytes | 4 bytes |
# Update Data message
This Update Data message contains the update data. The data MUST be 8-byte aligned as many MCUs can write internal flash faster with double words instead of a single word. Also, as some transceivers has as little as a 64 byte RX fifo, the Software Update message can be as little as 48 bytes. Because some encryption algorithms are block-based, it is preferable to encrypt the software update in chunks of 16 bytes.