ESP MSC OTA

[English]

esp_msc_ota 是基于 USB MSC 的 OTA 驱动程序，它支持通过 USB 从 U 盘中读取程序，烧录到指定 OTA 分区，从而实现 OTA 升级的功能。

特性：

支持通过 USB 接口读取 U 盘，并实现 OTA 升级
支持 U 盘热插拔

用户指南

硬件需求：

任何带有 USB 接口的 ESP32-S2/ESP32-S3 开发板, 且 USB 接口需要能够向外供电

使用 BOT（仅限大容量传输）协议和 Transparent SCSI 命令集的 U 盘。

分区表：

具有 OTA 分区

代码示例

调用 esp_msc_host_install 初始化 MSC 主机驱动程序

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

调用 esp_msc_ota 完成 OTA 升级。通过 ota_bin_path 指定 OTA 文件路径，通过 wait_msc_connect 指定等待 U 盘插入的时间，单位为 freertos tick。

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

调用 esp_event_handler_register 注册事件处理程序，获取 ota 过程细节。

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.

参数

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

返回

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.

参数

handle – [in] Handle for the MSC ota

返回

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.

备注

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

参数

handle – [in] Handle for the MSC ota

返回

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

备注

esp_msc_ota_abort should not be called after calling esp_msc_ota_finish

参数

handle – [in] Handle for the MSC ota

返回

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

参数

config – [in] pointer to esp_msc_ota_config_t structure

返回

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.

参数

handle – [in] pointer to esp_msc_ota_config_t structure
new_app_info – [out] pointer to an allocated esp_app_desc_t structure

返回

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.

参数

handle – [in] Handle for the MSC ota
if_connect – [in]

返回

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.

参数: handle – [in] Handle for the MSC ota
返回: 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.

参数: handle – [in] Handle for the MSC ota
返回: true
返回: 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

提供有关此文档的反馈