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

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 firmware
  • size: Total length of firmware, If image size is not yet known, pass OTA_SIZE_UNKNOWN and call mupgrade_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 firmware
  • size: 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 mac
  • dest_addrs_num: Number of destination nodes
  • result: 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 address
  • data: Upgrade instructions or firmware
  • size: 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 address
  • data: State of non-root response
  • size: 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

mdf_err_t mupgrade_version_fallback()

Upgrade error back to previous version.

Return
  • MDF_OK
  • MDF_FAIL

mdf_err_t mupgrade_stop()

Stop upgrading.

Return
  • MDF_OK
  • MDF_FAIL_cplusplus MUPGRADE_H

Structures

struct mupgrade_packet_t

Firmware packet.

Public Members

uint8_t type

Type of packet, MUPGRADE_TYPE_DATA

uint16_t seq

Sequence

uint16_t size

Size

uint8_t data[MUPGRADE_PACKET_MAX_SIZE]

Firmware

struct mupgrade_status_t

Status packet.

Public Members

uint8_t type

Type of packet, MUPGRADE_TYPE_STATUS

char name[32]

Unique identifier of the firmware

mdf_err_t error_code

Upgrade status

size_t total_size

Total length of firmware

size_t written_size

The length of the flash has been written

uint8_t progress_array[0]

Identify if each packet of data has been written

struct mupgrade_config_t

Mupgrade config.

Public Members

QueueHandle_t queue

Queue handle

esp_ota_handle_t handle

OTA handle

const esp_partition_t *partition

Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get.

uint32_t start_time

Start time of the upgrade

mupgrade_status_t status

Upgrade status

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

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