Firmware update

Firmware update¶

The Mira stack contains functionality to help you perform firmware updates OTA. You are still free to use other methods of course, but we think this is quite awesome, since it allows you to update the firmware of all nodes in networks of several thousands of nodes, without disturbing the application while running.

This method can be used bot for the firmware running on the MiraOne module, but also for softwares running on external processor when running the MiraOne module in hosted mode.

In the Mira SDK you will find an example of how to build a bootloader that can be used to allow for firmware updates over-the-air (OTA). There is also an example on how to build an updatable firmware image.

Starting an update session¶

The host CPU of the network root (aka. the update master) can start a firmware update session by issuing the FWUP_OPEN_SESSION command.

Message class	Message type	Data length	Data
0x4	0x3	6	Session parameters

Parameter	Data type	Data size	Description
session	uint16_t	1	Session ID
			`0x0002-0x01FE` - host CPU sessions
			`0x0020-0xFF7E` - Reserved
			`0xFF80-0xFFFE` - Mira sessions
data_size	uint32_t	1	Size of binary data

Only the 15 most significant bits are considered as the session ID. The least significant bit indicates that it is a local update (not being transmitted over the network). For instance 0xFFFF is a local Mira update, this will only update the MiraOne module connected directly to the host CPU.

Closing an update session¶

To close an ongoing session, the FWUP_CLOSE_SESSION message can be sent by the update master.

This message will also be issued by the MiraOne module to indicate that the update session is finished.

Message class	Message type	Data length	Data
0x4	0x4	2	Session ID

Parameter	Data type	Data size	Description
session	uint16_t	1	Session ID

Requesting status¶

If the update master wishes to get the status of an ongoing session, it can issue the FWUP_STATUS_REQUEST command.

Message class	Message type	Data length	Data
0x4	0x6	0	n/a

Status¶

The FWUP_STATUS command contains the status of an ongoing update session.

Message class	Message type	Data length	Data
0x4	0x7	6	Status parameters

Parameter	Data type	Data size	Description
eta	uint32_t	1	Estimated time to finish
session_id	uint16_t	1	Session ID of the current session

Data request¶

The MiraOne module will request data from the update master whenever it wants more data to transfer by sending the FWUP_DATA_REQUEST command.

Message class	Message type	Data length	Data
0x4	0x8	8	Request parameters

Parameter	Data type	Data size	Description
offset	uint32_t	1	Firmware data file offset
size	uint32_t	1	Requested data size (up to 32 bytes)

Firmware data block¶

To deliver data to the MiraOne module (when it asks for data), the update master will send a FWUP_DATA message.

This message will also be sent to a host CPU from a MiraOne module, during an update to which the host CPU has subscribed to.

Message class	Message type	Data length	Data
0x4	0x9	40	Data parameters

Parameter	Data type	Data size	Description
offset	uint32_t	1	Firmware data file offset
size	uint32_t	1	Data size
data	uint8_t	32	Binary data

Set update speed¶

The default speed of an update process is selected to work well in a wide variety of network setups and to avoid affecting normal operation of the application. Hence, in some cases it may be desired to speed up this process. This can be done by setting the delay between to update data blocks using the FWUP_SET_DELAY message. When utilizing this message, the user shall observe when the process backs off (FWUP_DATA_REQUEST requesting already sent data blocks) more often than usual. This means that the current limit for the network has been reached, and delay time should be increased for stability. The default delay is 2 seconds (specified as 256/128 seconds).

Message class	Message type	Data length	Data
0x4	0xD	2	Delay time

Parameter	Data type	Data size	Description
delay	uint16_t	1	Delay (x / 128 seconds)

Set checking period¶

When the network performs a firmware update, it periodically stops and collects the first data blocks that was not received by all devices. This helps in creating reliable transfers, and the collection period can be set with the FWUP_SET_FINDMIN_PERIOD message. The period is set in number of data blocks sent between the checks, it's set as a power of two. Default value is 64 blocks (2^6 blocks).

Message class	Message type	Data length	Data
0x4	0xE	1	Check period

Parameter	Data type	Data size	Description
period	uint8_t	1	The power of 2 of number of datablocks between checks.

Hosted mode¶

Subscribing to an update in hosted mode

The host CPU of nodes running in hosted mode can issue the FWUP_SUBSCRIBE command. This will let the node receive data for the subscribed session.

Message class	Message type	Data length	Data
0x4	0x5	2	Session ID

Parameter	Data type	Data size	Description
session	uint16_t	1	Session ID
			`0x0000` - unsubscribe
			`0x0002-0x01FE` - available for use

Rolling back the progress

If the host CPU for some reason would loose a block of data, it can request to roll the progress back to the offset where it lost the data by sending the FWUP_ROLLBACK_REQUEST command to the MiraOne module. The MiraOne module will then handle the rest.

Message class	Message type	Data length	Data
0x4	0xD	4	Offset

Parameter	Data type	Data size	Description
session	uint32_t	1	Binary file offset to roll back to

Response codes¶

When sending a message to the Mira module, the application should expect to receive response codes from the Mira module. These response codes will be sent from the Mira module to the application as a response to every request. The application shall not send responses to the Mira module.

Response type	Message class	Message type	Data type	Data length	Data
FWUP_ACK	0x4	0x1	n/a	0	n/a
FWUP_ERROR	0x4	0x2	uint8_t	1	`0x02` – unknown message type
					`0x03` – incorrect message size
					`0x05` – invalid addressing mode
					`0x06` – session in progress
					`0x05` – invalid block size