Mupgrade API¶
Mupgrade
(Mesh Upgrade) is a solution for simultaneous over-the-air (OTA) upgrading of multiple ESP-WIFI-MESH devices on the same wireless network by efficient routing of data flows. It features automatic retransmission of failed fragments, data compression, reverting to an earlier version, firmware check, etc.
Application Examples¶
For ESP-MDF examples, please refer to the directory function_demo/mupgrade, which includes:
- Send a request for data to server via AP, in order to complete the upgrading of the overall Mesh network.
API Reference¶
Header File¶
Functions¶
-
mdf_err_t
mupgrade_firmware_init
(const char *name, size_t size)¶ Initialize the upgrade status and erase the upgrade partition.
- Attention
- Only called at the root
- Return
- MDF_OK
- MDF_ERR_INVALID_ARG
- MDF_ERR_MUPGRADE_FIRMWARE_PARTITION
- Parameters
name
: Unique identifier of the firmwaresize
: Total length of firmware, If image size is not yet known, pass OTA_SIZE_UNKNOWN and callmupgrade_firmware_download_finished()
after the firmware download is complete.
-
mdf_err_t
mupgrade_firmware_download
(const void *data, size_t size)¶ Write firmware to flash.
- Attention
- Only called at the root
- Return
- MDF_OK
- MDF_ERR_MUPGRADE_FIRMWARE_NOT_INIT
- MDF_ERR_MUPGRADE_FIRMWARE_FINISH
- Parameters
data
: Pointer to the firmwaresize
: The length of the data
-
mdf_err_t
mupgrade_firmware_download_finished
(size_t image_size)¶ Finish OTA update and validate newly written app image.
- Attention
- Only called
mupgrade_firmware_init()
firmware size unknown at root node - Return
- MDF_OK
- MDF_ERR_MUPGRADE_FIRMWARE_NOT_INIT
- Parameters
image_size
: of new OTA app image
-
mdf_err_t
mupgrade_firmware_check
(const esp_partition_t *partition)¶ Check if the firmware is generated by this project.
- Return
- MDF_OK
- MDF_ERR_MUPGRADE_FIRMWARE_INVALID
- Parameters
partition
: The partition where the firmware to be checked is located
-
mdf_err_t
mupgrade_firmware_send
(const uint8_t *dest_addrs, size_t dest_addrs_num, mupgrade_result_t *result)¶ Root sends firmware to other nodes.
- Attention
- Only called at the root
- Return
- MDF_OK
- MDF_ERR_MUPGRADE_FIRMWARE_NOT_INIT
- MDF_ERR_MUPGRADE_DEVICE_NO_EXIST
- Parameters
dest_addrs
: Destination nodes of macdest_addrs_num
: Number of destination nodesresult
: Must call mupgrade_result_free to free memory
-
mdf_err_t
mupgrade_firmware_stop
()¶ Stop Root to send firmware to other nodes.
- MDF_ERR_NOT_SUPPORTED
- Return
- MDF_OK
-
mdf_err_t
mupgrade_result_free
(mupgrade_result_t *result)¶ Free memory in the results list.
- Return
- MDF_OK
- MDF_ERR_INVALID_ARG
- Parameters
result
: Pointer to device upgrade status
-
mdf_err_t
mupgrade_handle
(const uint8_t *addr, const void *data, size_t size)¶ Handling upgrade data sent by ROOT.
- Attention
- Only called at the non-root
- Return
- MDF_OK
- MDF_ERR_MUPGRADE_FIRMWARE_DOWNLOAD
- MDF_ERR_MUPGRADE_NOT_INIT
- Parameters
addr
: root addressdata
: Upgrade instructions or firmwaresize
: The length of the data
-
mdf_err_t
mupgrade_root_handle
(const uint8_t *addr, const void *data, size_t size)¶ Handling the status of non-root responses.
- Attention
- Only called at the root
- Return
- MDF_OK
- MDF_ERR_TIMEOUT
- Parameters
addr
: Non-root addressdata
: State of non-root responsesize
: The length of the data
-
mdf_err_t
mupgrade_get_status
(mupgrade_status_t *status)¶ Get the status of the upgrade.
- Return
- MDF_OK
- MDF_ERR_INVALID_ARG
- MDF_ERR_NOT_SUPPORTED
- Parameters
status
: The status of the upgrade
Structures¶
-
struct
mupgrade_packet_t
¶ Firmware packet.
-
struct
mupgrade_status_t
¶ Status packet.
-
struct
mupgrade_config_t
¶ Mupgrade config.
-
struct
mupgrade_result_t
¶ List of devices’ status during the upgrade process.
Public Members
-
size_t
unfinished_num
¶ The number of devices to be upgraded
-
uint8_t *
unfinished_addr
¶ MAC address of devices to be upgraded
-
size_t
successed_num
¶ The number of devices that succeeded to upgrade
-
uint8_t *
successed_addr
¶ MAC address of devices that succeeded to upgrade
-
size_t
requested_num
¶ The number of devices to be upgraded
-
uint8_t *
requested_addr
¶ This address is used to buffer the result of the request during the upgrade process
-
size_t
Macros¶
-
MDF_ERR_MUPGRADE_FIRMWARE_NOT_INIT
¶ mupgrade error code definition
< _cplusplus Uninitialized firmware configuration
-
MDF_ERR_MUPGRADE_FIRMWARE_PARTITION
¶ Partition table error
-
MDF_ERR_MUPGRADE_FIRMWARE_INVALID
¶ Non-project generated firmware
-
MDF_ERR_MUPGRADE_FIRMWARE_INCOMPLETE
¶ The firmware received by the device is incomplete
-
MDF_ERR_MUPGRADE_FIRMWARE_DOWNLOAD
¶ Firmware write flash error
-
MDF_ERR_MUPGRADE_FIRMWARE_FINISH
¶ The firmware has been written to completion
-
MDF_ERR_MUPGRADE_DEVICE_NO_EXIST
¶ The device that needs to be upgraded does not exist
-
MDF_ERR_MUPGRADE_SEND_PACKET_LOSS
¶ Request device upgrade status failed
-
MDF_ERR_MUPGRADE_NOT_INIT
¶ Upgrade configuration is not initialized
-
MDF_ERR_MUPGRADE_STOP
¶ Upgrade configuration is not initialized
-
MDF_EVENT_MUPGRADE_STARTED
¶ enumerated list OF MDF event id
The device starts to upgrade
-
MDF_EVENT_MUPGRADE_STATUS
¶ Proactively report progress
-
MDF_EVENT_MUPGRADE_FINISH
¶ The upgrade is complete and the new firmware will run after the reboot
-
MDF_EVENT_MUPGRADE_STOPED
¶ Stop upgrading
-
MDF_EVENT_MUPGRADE_FIRMWARE_DOWNLOAD
¶ Start firmware write flash
-
MDF_EVENT_MUPGRADE_SEND_FINISH
¶ Send the firmware to other devices to complete
-
MUPGRADE_PACKET_MAX_SIZE
¶ Firmware subcontract upgrade.
Maximum length of a single packet transmitted
-
MUPGRADE_PACKET_MAX_NUM
¶ The maximum number of packets
-
MUPGRADE_GET_BITS
(data, bits)¶ Bit operations to get and modify a bit in an array.
-
MUPGRADE_SET_BITS
(data, bits)¶
-
MUPGRADE_TYPE_DATA
¶ Type of packet.
-
MUPGRADE_TYPE_STATUS
¶