Firmware update and file transfers¶
Mira comes with support for a method of distributing binary files to all nodes in a network. This method is intended for performing firmware updates over the air (FOTA), but can also be used for other purposes.
On the gateway¶
Move the firmware file to firmwares/X.bin, where X is the slot_id. The gateway
will automatically create a version number for it and start distributing it
to the rest of the network.
Transfer method¶
Figure 1: A file transfer throughout the network
A file is transferred hop by hop along the routing tree. It starts by the first node (root node) having the new file in its file swap storage. Its children download the file when they detect that there is a new version. This process continues throughout the network.
Update of Firmware¶
The transfer method allows for arbitrary binary files. The application is responsible for using this file in the correct way. The developer should take aspects of for example file integrity into consideration when designing the firmware file format.
Developers are responsible for building their bootloader to have support for updating firmware.
Using the supported transfer method is optional, alternate methods may be used if the developer finds that more suitable for the application.
Custom driver¶
It is possible to store the temporary image on an external flash, or any other device, by providing a custom driver.
The custom driver is set via mira_fota_set_driver()
A driver is defined as a set of callbacks that are called when the backend needs access to data.
The backend organizes multiple sessions, which can be in read, write or idle state. Multiple read sessions can run in parallel, but only one write, making it possible to have multiple parallel read requests at the same time.
An operation is terminated by calling the done_callback() with the argument
storage, provided to the driver callback. It is up to the driver to call the
done_callback() once, and only once, for each successful request. Requests
that can't be handled should have a non-zero return code, to indicate that the
done_callback() will not be called, and the operation fails. Failing to
properly call done_callback() will result in undefined behaviour.
An example of some parallel sessions:
| time | session 1 | session 2 | session 3 |
|---|---|---|---|
| 0 | -> read() | ||
| 1 | busy | -> read() | |
| 2 | busy | <- done() | |
| 3 | busy | -> read() | |
| 4 | busy | <- done() | |
| 5 | <- done() | ||
| 6 | -> erase() | ||
| 7 | <- done() | ||
| 8 | -> write() | ||
| 9 | <- done() | ||
| 10 | -> write() | ||
| 11 | <- done() | ||
| 12 | -> write() | ||
| 13 | <- done() | ||
| 14 | -> read() | ||
| 15 | -> read() | busy | |
| 16 | <- done() | busy | |
| 17 | <- done() |
As seen in the example, multiple read request can be called in parallel.
Defines¶
MIRA_FOTA_MAX_SLOT¶
#define MIRA_FOTA_MAX_SLOT
Number of available FOTA slots.
MIRA_FOTA_HEADER_SIZE¶
#define MIRA_FOTA_HEADER_SIZE
The size of the FOTA header in the swap storage.
FOTA places a header of this size first in the swap storage, before the actual binary.
Types¶
mira_fota_done_callback_t¶
typedef void(* mira_fota_done_callback_t) (void *storage);
Callback to indicate result is finished.
Parameters
| Name | Description |
|---|---|
| storage | Pointer to internal storage |
mira_fota_cb_init_t¶
typedef void(* mira_fota_cb_init_t) (void);
FOTA driver callback, to initialize driver.
Called to initialize FOTA driver
mira_fota_cb_get_size_t¶
typedef int(* mira_fota_cb_get_size_t) (uint16_t slot_id, uint32_t *size, mira_fota_done_callback_t done_callback, void *storage);
FOTA driver callback, to get the size of a slot.
Called to get the available size for a given slot. Note that this is the size of the slot, not the size of the data written.
On successful operation, call done_callback(storage). The callback does not have to be called within the method itself. However, it:* must be called once and only once if the method returns 0 / success * must not be called if the method returns an error.
If the slot id is not supported, return an error code.
Parameters
| Name | Description |
|---|---|
| slot_id | ID of the slot top operate on |
| size | output of the operation |
| done_callback | callback to be called when operation is finished |
| storage | pointer to pass to the done_callback to track the operation |
mira_fota_cb_read_t¶
typedef int(* mira_fota_cb_read_t) (uint16_t slot_id, void *data, uint32_t address, uint32_t length, mira_fota_done_callback_t done_callback, void *storage);
FOTA driver callback, to read data.
Multiple read sessions may occur in parallel, but only one write.
On successful operation, call done_callback(storage). The callback does not have to be called within the method itself. However, it:* must be called once and only once if the method returns 0 / success * must not be called if the method returns an error.
If the slot id is not supported, return an error code.
Parameters
| Name | Description |
|---|---|
| slot_id | ID of the slot top operate on |
| data | buffer to store result, valid until done_callback() is called |
| address | offset in slot to write to |
| length | number of bytes to be written |
| done_callback | callback to be called when operation is finished |
| storage | pointer to pass to the done_callback to track the operation |
mira_fota_cb_write_t¶
typedef int(* mira_fota_cb_write_t) (uint16_t slot_id, const void *data, uint32_t address, uint32_t length, mira_fota_done_callback_t done_callback, void *storage);
FOTA driver callback, to write data to driver.
Multiple read sessions may occur in parallel, but only one write. Erase counts as a write operation.
On successful operation, call done_callback(storage). The callback does not have to be called within the method itself. However, it:* must be called once and only once if the method returns 0 / success * must not be called if the method returns an error.
If the slot id is not supported, return an error code.
Parameters
| Name | Description |
|---|---|
| slot_id | ID of the slot top operate on |
| data | data to be written, valid until done_callback() is called |
| address | offset in slot to write to |
| length | number of bytes to be written |
| done_callback | callback to be called when operation is finished |
| storage | pointer to pass to the done_callback to track the operation |
mira_fota_cb_erase_t¶
typedef int(* mira_fota_cb_erase_t) (uint16_t slot_id, mira_fota_done_callback_t done_callback, void *storage);
FOTA driver callback, erase an entire slot.
Called to erase the slot.
Multiple read sessions may occur in parallel, but only one write. Erase counts as a write operation.
On successful operation, call done_callback(storage). The callback does not have to be called within the method itself. However, it:* must be called once and only once if the method returns 0 / success * must not be called if the method returns an error.
If the slot id is not supported, return an error code.
Parameters
| Name | Description |
|---|---|
| slot_id | ID of the slot top operate on |
| done_callback | callback to be called when operation is finished |
| storage | pointer to pass to the done_callback to track the operation |
Functions¶
mira_fota_set_driver¶
mira_status_t mira_fota_set_driver(mira_fota_cb_init_t init, mira_fota_cb_get_size_t get_size, mira_fota_cb_read_t read, mira_fota_cb_write_t write, mira_fota_cb_erase_t erase);
Set FOTA backend driver.
Exchange the default built-in driver with a custom driver. Useful for use with external storage.
The driver must implement all functions to work with FOTA.
The default built-in driver stores the FOTA image on internal flash on CPU, if available. In that case, only slot_id = 0 is available. slot_id other than 0 for the mira_fota_*() calls results in failure, returning -1.
FOTA starts every operation by calling the associated operation callback. These callbacks must execute the desired action. Finish the operation by calling done_callback(storage).
Note that done_callback(storage) does not need to be called directly from the operation callback: it may be called later. However, done_callback(storage) must be called once and only once per started operation. The driver itself is responsible for handling timeouts.
Return 0 from every operation callback to indicate that the operation started without error. Non-zero return value from the callback means that the operation failed to start, and the driver must not call done_callback(storage).
Multiple operations may be requested in parallel. If only one operation can be executed at any given time, the driver needs to hold a queue of the requested operations.
Note
Do not set a custom FOTA driver after the call to mira_fota_init().
Parameters
| Name | Description |
|---|---|
| init | Callback for when driver is initialized. |
| get_size | Callback to get size of swap space. |
| read | Callback to start reading from swap space. |
| write | Callback to start writing to swap space. |
| erase | Callback to erase entire swap space, cleaning before write. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | The operation was successful. |
| MIRA_ERROR_ALREADY_INITIALIZED | The FOTA is already initialized. |
mira_fota_init¶
mira_status_t mira_fota_init(void);
Initialize firmware transfer OTA.
Note
Call mira_net_init() before calling mira_fota_set_driver().
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | The operation was successful. |
| MIRA_ERROR_ALREADY_INITIALIZED | The FOTA is already initialized. |
| MIRA_ERROR_NOT_INITIALIZED | mira_net_init has not been called. |
mira_fota_is_valid¶
mira_bool_t mira_fota_is_valid(uint16_t slot_id);
Check if image in slot is valid.
Result is valid both during read operation and outside of read operation.
The result is guaranteed not to change during a read operation (between mira_fota_read_start has finished, and mira_fota_read_end).
Outside read operation, the result might change due to started OTA transfer, and may only be used for statistical purposes.
Parameters
| Name | Description |
|---|---|
| slot_id | Slot number. |
Return value
| Name | Description |
|---|---|
| MIRA_TRUE | The FOTA is valid. |
| MIRA_FALSE | The FOTA is not valid. |
mira_fota_get_image_size¶
mira_size_t mira_fota_get_image_size(uint16_t slot_id);
Get size of FOTA image in swap storage.
The result is guaranteed not to change during a read operation (between mira_fota_read_start has finished, and mira_fota_read_end).
Outside read operation, the result might change due to started OTA transfer, and may only be used for statistical purposes.
Parameters
| Name | Description |
|---|---|
| slot_id | Slot number. |
mira_fota_get_version¶
uint8_t mira_fota_get_version(uint16_t slot_id);
Get FOTA image version.
The result is guaranteed not to change during a read operation (between mira_fota_read_start has finished, and mira_fota_read_end).
The image version is a sequence number for the update session. It is useful for statistics for which nodes have got the image.
The version number is in the range 0-254. 255 means version number is not present.
Parameters
| Name | Description |
|---|---|
| slot_id | Slot number. |
mira_fota_read_start¶
mira_status_t mira_fota_read_start(uint16_t slot_id);
Start a read session.
A read session allows for the use of mira_fota_read().
Return value MIRA_SUCCESS means that a read session is requested. The read session only starts once mira_fota_is_working() returns MIRA_FALSE. See mira_fota_is_working() for more information.
Parameters
| Name | Description |
|---|---|
| slot_id | Slot number. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | The read session is successfully requested. |
| MIRA_ERROR_ALREADY_INITIALIZED | Another FOTA session is already active. |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA. |
mira_fota_read¶
mira_status_t mira_fota_read(uint8_t *dst, mira_size_t *dst_length, mira_size_t offset, mira_size_t length);
Read from swap storage.
Start a read request from the FOTA swap storage.
Return value MIRA_SUCCESS means that a read operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE.
Once the operation is finished, content is available at address of dst, and the size of the written data is available at dst_length.
Parameters
| Name | Description |
|---|---|
| dst | Pointer to where the read data should be stored. |
| dst_length | Pointer to the length of the read. |
| offset | Offset in the FOTA swap storage from where to start the reading. |
| length | Size of block to read. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | The read request is successfully requested. |
| MIRA_ERROR_NOT_INITIALIZED | A read session has not been started yet (mira_fota_read_start()). |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA. |
mira_fota_read_end¶
mira_status_t mira_fota_read_end(void);
Close the read session.
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | The read session was successfully closed. |
| MIRA_ERROR_NOT_INITIALIZED | A read session has not been started yet (mira_fota_read_start()). |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA. |
mira_fota_write_start¶
mira_status_t mira_fota_write_start(uint16_t slot_id);
Start a write session to the FOTA swap storage.
A write session allows for the use of mira_fota_write().
Return value of MIRA_SUCCESS means that a write session is requested. The write session only starts once mira_fota_is_working() returns MIRA_FALSE. See mira_fota_is_working() for more information.
Parameters
| Name | Description |
|---|---|
| slot_id | Slot number. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | A write session is successfully requested. |
| MIRA_ERROR_ALREADY_INITIALIZED | Another FOTA session is already active. |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA. |
mira_fota_write¶
mira_status_t mira_fota_write(mira_size_t offset, uint8_t *src, mira_size_t length);
Write to the FOTA swap storage.
Writing to the FOTA swap storage is only available during a write session.
If the return value is MIRA_SUCCESS, a write operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE.
During the entire operation, the content of the src memory must not change.
If the return value is not MIRA_SUCCESS, the write operation has not started.
Parameters
| Name | Description |
|---|---|
| offset | Offset of the location to write to. |
| src | Data to write. |
| length | Size of the write. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | A write request is successfully requested. |
| MIRA_ERROR_NOT_INITIALIZED | A write session has not been started yet (mira_fota_write_start()). |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA. |
mira_fota_erase¶
mira_status_t mira_fota_erase(void);
Erase the FOTA swap storage.
Erasing the FOTA swap storage is only available during a write session.
Return value MIRA_SUCCESS means that an erase operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE.
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | An erase request is successfully requested. |
| MIRA_ERROR_NOT_INITIALIZED | A write session has not been started yet (mira_fota_write_start()). |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA read. |
mira_fota_write_header¶
mira_status_t mira_fota_write_header(mira_size_t size, uint32_t checksum, uint16_t type, uint8_t flags, uint8_t version);
Write a header to the FOTA swap storage.
The header is necessary to validate the content of the swap storage, so that transfer can proceed.
The version number is a reference number which must change for every new image. Version numbers do not have to be incremented in order. The version number must not be 255.
The checksum is of type CRC-32 of the content written to the swap storage. It is used to validate the content integrity for transfer errors. The checksum uses polynom defined as 0x04C11DB7.
Return value MIRA_SUCCESS means that a write operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE.
Parameters
| Name | Description |
|---|---|
| size | The size of the image to transfer. |
| checksum | Checksum of the content in the swap storage, which must match the data for the content to be treated as valid. |
| type | An integer to identify the information in the swap storage. |
| flags | Flags for future use, set to 0. |
| version | A sequence number that should change for each new update. |
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | A write request is successfully requested. |
| MIRA_ERROR_NOT_INITIALIZED | A write session has not been started yet (mira_fota_write_start()). |
| MIRA_ERROR_INVALID_VALUE | The version parameter was 255. |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA read. |
mira_fota_write_end¶
mira_status_t mira_fota_write_end(void);
Close the write session.
The write operation will continue to work while mira_fota_is_working is returning MIRA_TRUE.
Return value
| Name | Description |
|---|---|
| MIRA_SUCCESS | The write session was successfully closed. |
| MIRA_ERROR_NOT_INITIALIZED | A write session has not been started yet (mira_fota_write_start()). |
| MIRA_FOTA_ERROR_LOCK | Unable to access a lock to the FOTA read. |
mira_fota_is_working¶
mira_bool_t mira_fota_is_working(void);
Check if the last operation is still running.
The process that called the previous operation will be polled when the operation is finished. Recommended usage:
mira_fota_operation(...);
PROCESS_WAIT_WHILE(mira_fota_is_working());
Note
Validation of the FOTA image is not included in this function. Therefore mira_fota_is_valid() might return MIRA_FALSE for a few seconds afer mira_fota_is_working() starts to return MIRA_FALSE following a write session.
Return value
| Name | Description |
|---|---|
| MIRA_FALSE | No FOTA operation is currently executing. |
| MIRA_TRUE | There is a FOTA operation which is currently executing. |