ESP MSC OTA

[中文]

esp_msc_ota` is an OTA (Over-The-Air) driver based on USB MSC (USB Mass Storage Class). It supports reading programs from a USB flash drive and burning them into a designated OTA partition, thereby enabling OTA upgrades via USB.

Features:

1. Supports OTA updates by retrieving programs from a USB flash drive via USB interface.

2. Supports hot-plugging of the USB flash drive.

User Guide

Hardware requirements:

• Any ESP32-S2/ESP32-S3 development board with a USB interface capable of providing external power.

• A USB flash drive using the BOT (Bulk-Only Transport) protocol and Transparent SCSI command set.

Partition Table:

• Includes an OTA partition.

Code examples

1. Call esp_msc_host_install to initialize the MSC host driver.

esp_msc_host_config_t msc_host_config = {
    .base_path = "/usb",
    .host_driver_config = DEFAULT_MSC_HOST_DRIVER_CONFIG(),
    .vfs_fat_mount_config = DEFAULT_ESP_VFS_FAT_MOUNT_CONFIG(),
    .host_config = DEFAULT_USB_HOST_CONFIG()
};
esp_msc_host_handle_t host_handle = NULL;
esp_msc_host_install(&msc_host_config, &host_handle);

2. Call esp_msc_ota to complete OTA updates. Use ota_bin_path to specify the OTA file path and wait_msc_connect to specify the waiting time for USB drive insertion in FreeRTOS ticks.

esp_msc_ota_config_t config = {
    .ota_bin_path = "/usb/ota_test.bin",
    .wait_msc_connect = pdMS_TO_TICKS(5000),
};
esp_msc_ota(&config);

3. Call esp_event_handler_register to register the event handler for obtaining OTA process details.

esp_event_loop_create_default();
esp_event_handler_register(ESP_MSC_OTA_EVENT, ESP_EVENT_ANY_ID, &event_handler, NULL);

API Reference

Header File

• components/usb/esp_msc_ota/include/esp_msc_ota.h

Functions

esp_err_t esp_msc_ota_begin(esp_msc_ota_config_t *config, esp_msc_ota_handle_t *handle)

Start MSC OTA Firmware upgrade.

If this function succeeds, then call esp_msc_ota_performto continue with the OTA process otherwise call esp_msc_ota_end.

Parameters

• config – [in] pointer to esp_msc_ota_config_t structure

• handle – [out] pointer to an allocated data of type esp_msc_ota_handle_t which will be initialised in this function

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG: Invalid argument (missing/incorrect config, handle, etc.)

• ESP_ERR_NO_MEM: Failed to allocate memory for msc_ota handle

• ESP_FAIL: For generic failure.

esp_err_t esp_msc_ota_perform(esp_msc_ota_handle_t handle)

Read data from the firmware on the USB flash drive and start the upgrade,.

It is necessary to call this function several times and ensure that the value returned each time is ESP_OK. and call esp_msc_ota_is_complete_data_received to monitor whether the firmware upgrade is complete or not. Make sure that the VFS file system is not unmounted during the fread process. If you manually unplug the USB flash drive or log out of the USB HOST, stop calling esp_msc_ota_perform before and call esp_msc_ota_abort afterwards.

Parameters

handle – [in] Handle for the MSC ota

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG: Invalid argument

• ESP_ERR_INVALID_STATE: Invalid state (handle not initialized, etc.)

• ESP_ERR_INVALID_SIZE: Fread failed

• ESP_FAIL: For generic failure.

• For other errors, please check the API for the specific error.

esp_err_t esp_msc_ota_end(esp_msc_ota_handle_t handle)

Clean-up MSC OTA Firmware upgrade.

Note

If this API returns successfully, esp_restart() must be called to boot from the new firmware image esp_https_ota_finish should not be called after calling esp_msc_ota_abort

Parameters

handle – [in] Handle for the MSC ota

Returns

• ESP_ERR_INVALID_ARG: Invalid argument

• ESP_ERR_INVALID_STATE: Incorrect status

• ESP_OK: Success

• For other errors, please check the API for the specific error.

esp_err_t esp_msc_ota_abort(esp_msc_ota_handle_t handle)

Clean-up MSC OTA Firmware upgrade and call esp_ota_abort

Note

esp_msc_ota_abort should not be called after calling esp_msc_ota_finish

Parameters

handle – [in] Handle for the MSC ota

Returns

• ESP_ERR_INVALID_ARG: Invalid argument

• ESP_ERR_INVALID_STATE: Incorrect status

• ESP_OK: Success

• For other errors, please check the API for the specific error.

esp_err_t esp_msc_ota(esp_msc_ota_config_t *config)

MSC OTA Firmware upgrade.

This function provides a complete set of MSC_OTA upgrade procedures. When the USB flash disk is inserted, it will be upgraded automatically. After the upgrade is completed, please call esp_restart()

Parameters

config – [in] pointer to esp_msc_ota_config_t structure

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG: Invalid argument

• ESP_OK: Success

• For other errors, please check the API for the specific error.

esp_err_t esp_msc_ota_get_img_desc(esp_msc_ota_handle_t handle, esp_app_desc_t *new_app_info)

Reads app description from image header. The app description provides information like the “Firmware version” of the image.

Parameters

• handle – [in] pointer to esp_msc_ota_config_t structure

• new_app_info – [out] pointer to an allocated esp_app_desc_t structure

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG: Invalid argument

• ESP_ERR_INVALID_STATE: Incorrect status

• ESP_FAIL: Fail to read image header

esp_err_t esp_msc_ota_set_msc_connect_state(esp_msc_ota_handle_t handle, bool if_connect)

When you manage the MSC HOST function, call this api to notify msc_ota that the u-disk has been inserted and the VFS filesystem has been mounted.

Parameters

• handle – [in] Handle for the MSC ota

• if_connect – [in]

Returns

alaways return ESP_OK

esp_msc_ota_status_t esp_msc_ota_get_status(esp_msc_ota_handle_t handle)

Get the status of the MSC ota.

Parameters

handle – [in] Handle for the MSC ota

Returns

esp_msc_ota_status_t

bool esp_msc_ota_is_complete_data_received(esp_msc_ota_handle_t handle)

Checks if complete data was received or not.

This API can be called just before esp_msc_ota_end() to validate if the complete image was indeed received.

Parameters

handle – [in] Handle for the MSC ota

Returns

true

Returns

false

Structures

struct esp_msc_ota_config_t

esp msc ota config

Public Members

const char *ota_bin_path

OTA binary name, must be an exact match. Note: By default file names cannot exceed 11 bytes e.g. “/usb/ota.bin”

bool bulk_flash_erase

Erase entire flash partition during initialization. By default flash partition is erased during write operation and in chunk of 4K sector size

TickType_t wait_msc_connect

Wait time for MSC device to connect

size_t buffer_size

Buffer size for OTA write operation, must larger than 1024

Type Definitions

typedef void *esp_msc_ota_handle_t

Handle for the MSC ota.

Enumerations

enum esp_msc_ota_event_t

Declare Event Base for ESP MSC OTA.

Values:

enumerator ESP_MSC_OTA_START

Start update

enumerator ESP_MSC_OTA_READY_UPDATE

Ready to update

enumerator ESP_MSC_OTA_WRITE_FLASH

Flash write operation

enumerator ESP_MSC_OTA_FAILED

Update failed

enumerator ESP_MSC_OTA_GET_IMG_DESC

Get image description

enumerator ESP_MSC_OTA_VERIFY_CHIP_ID

Verify chip id

enumerator ESP_MSC_OTA_UPDATE_BOOT_PARTITION

Boot partition update after successful ota update

enumerator ESP_MSC_OTA_FINISH

OTA finished

enumerator ESP_MSC_OTA_ABORT

OTA aborted

enum esp_msc_ota_status_t

Values:

enumerator ESP_MSC_OTA_INIT

enumerator ESP_MSC_OTA_BEGIN

enumerator ESP_MSC_OTA_IN_PROGRESS

enumerator ESP_MSC_OTA_SUCCESS

Provide feedback about this document