Firmware update and file transfers¶

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

Transfer method¶

FOTA transfer steps
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. It's the responsibility of the application to use this file in the correct way. The developer should take aspects of for example file integrity into consideration when designing the firmware file format.

It is the developer's responsibility to build 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.

Functions¶

mira_fota_init¶

mira_status_t mira_fota_init(
    void);

Return

status of operation

mira_fota_is_valid¶

mira_bool_t mira_fota_is_valid(
    void);

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.

Return

If image in FOTA cache is valid

mira_fota_get_image_size¶

mira_size_t mira_fota_get_image_size(
    void);

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.

Return

0 if image isn't valid, size if image is valid

mira_fota_get_version¶

uint8_t mira_fota_get_version(
    void);

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.

Return

version number, or 255

mira_fota_read_start¶

mira_status_t mira_fota_read_start(
    void);

During the read session it is possible to use the mira_fota_read() method. If the return value is MIRA_SUCCESS, a read session is requested. The read session is first started once mira_fota_is_working() returns MIRA_FALSE next time. The calling process will be polled If the returned value is not MIRA_SUCCESS, triggering the request is not successful.

Return

status of the operation

mira_fota_read¶

mira_status_t mira_fota_read(
    uint8_t*      dst,
    mira_size_t*  dst_length,
    mira_size_t   src,
    mira_size_t   length);

Start a read request from the FOTA cache storage If the return value is MIRA_SUCCESS, a read operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE. Once the operaiton is finished, content is available at address of dst, and the size of the written data is available at dst_length. If the returned value is not MIRA_SUCCESS, triggering the request is not successful.

Parameters

Parameter	Description
`dst`	Target of the read operation
`dst_length`	Target of the length of the read
`src`	Offset in the FOTA cache from where to start reading
`length`	Size of block to read

Return

status of the operation

mira_fota_read_end¶

mira_status_t mira_fota_read_end(
    void);

Return

status of the operation

mira_fota_write_start¶

mira_status_t mira_fota_write_start(
    void);

During the write session it is possible to use the mira_fota_write() method. If the return value is MIRA_SUCCESS, a write session is requested. The write session is first started once mira_fota_is_working() returns MIRA_FALSE next time. The calling process will be polled If the returned value is not MIRA_SUCCESS, triggering the request is not successful.

Return

status of the operation

mira_fota_erase¶

mira_status_t mira_fota_erase(
    void);

Erasing the FOTA cache is only available during the write cycle If the return value is MIRA_SUCCESS, an erase operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE. If the return value is not MIRA_SUCCESS, the write operation has not started.

Return

status of the operation

mira_fota_write¶

mira_status_t mira_fota_write(
    mira_size_t   dst,
    uint8_t*      src,
    mira_size_t   length);

Writing to the FOTA cache 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 memory must not change. If the return value is not MIRA_SUCCESS, the write operation has not started.

Return

status of the operation

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);

The header is necessary to validate the content of the cache, so transfer can proceed. The version number is a sequence number which must be changed for every new image. Nodes uses the version number to identify updates of the image. The version number does 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 cache. It's used to validate the content integrity for transfer errors. The checksum uses polynom defined as 0x04C11DB7. If the return value is MIRA_SUCCESS, a write operation is requested. The operation is finished when mira_fota_is_working() returns MIRA_FALSE. If the return value is not MIRA_SUCCESS, the write operation has not started.

Parameters

Parameter	Description
`size`	The size of the image to transfer
`checksum`	Checksum of the content in the cache, which must match the data for the content to be treated as valid
`type`	an integer to identify the information in the cache
`flags`	Flags, for future use, set to 0
`version`	A sequence number that should change for each new update.

Return

status of the operation

mira_fota_write_end¶

mira_status_t mira_fota_write_end(
    void);

The write operation will continue to work while mira_fota_is_working is returning MIRA_TRUE. If the returned value is not MIRA_SUCCESS, the write session is aborted, and the image will not be valid.

Return

status of the operation

mira_fota_is_working¶

mira_bool_t mira_fota_is_working(
    void);

The process called the previous operation will be polled when the opration is finished. Recommended usage:

mira_fota_operation(...);
PROCESS_WAIT_WHILE(mira_fota_is_working());