ESP MSC OTA

[English]

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

特性：

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

用户指南

硬件需求：

任何带有 USB OTG 接口的开发板, 且 USB 接口需要能够向外供电

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

分区表：

具有 OTA 分区

代码示例

调用 esp_msc_host_install 初始化 MSC 主机驱动程序仅当应用已经安装 USB Host Library，并且已有任务调用 usb_host_lib_handle_events() 时，才将 skip_init_usb_host_driver 设置为 true。

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 升级。host_handle 为必填项，OTA 会通过它等待 MSC VFS 挂载，并在读取文件期间保持锁定。通过 ota_bin_path 指定 OTA 文件路径，通过 wait_msc_connect 指定等待 U 盘插入的时间，单位为 freertos tick。

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

OTA 成功后调用 esp_restart() 重启。如果应用需要关闭 MSC host，则仅当 U 盘已拔出且 MSC 设备不再挂载时，才调用 esp_msc_host_uninstall()。
调用 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);

如需感知 MSC host 端事件（U 盘连接/断开、设备安装/卸载、VFS 注册/注销等），请在 esp_msc_host_config_t 中设置 event_cb 与 event_cb_arg。从 v2.0.0 起，MSC host 不再通过默认 esp_event 循环派发事件，也不再提供 ESP_MSC_HOST_EVENT event base，只能通过该回调获取通知。

static void msc_host_event_cb(esp_msc_host_handle_t handle,
                              esp_msc_host_event_t event, void *user_ctx)
{
    switch (event) {
    case ESP_MSC_HOST_CONNECT:
    case ESP_MSC_HOST_DISCONNECT:
    case ESP_MSC_HOST_DEVICE_INSTALL:
    case ESP_MSC_HOST_DEVICE_UNINSTALL:
    case ESP_MSC_HOST_VFS_REGISTER:
    case ESP_MSC_HOST_VFS_UNREGISTER:
        // 处理对应事件
        break;
    }
}

esp_msc_host_config_t msc_host_config = {
    /* ... */
    .event_cb = msc_host_event_cb,
    .event_cb_arg = NULL,
};

API Reference

Header File

components/usb/esp_msc_ota/include/esp_msc_host.h

Functions

bool esp_msc_host_is_mounted(esp_msc_host_handle_t handle)

Check if the MSC VFS is mounted.

参数: handle – [in] Handle for the MSC host driver
返回: true if the VFS is mounted
返回: false if the VFS is not mounted or the handle is invalid

esp_err_t esp_msc_host_wait_mounted(esp_msc_host_handle_t handle, TickType_t timeout)

Block until the MSC VFS is mounted (or timeout elapses).

Returns immediately with ESP_OK when the VFS is already mounted. Otherwise the calling task is suspended and woken up as soon as the internal MSC host task finishes mounting the device.

参数

handle – [in] Handle for the MSC host driver
timeout – [in] Maximum time to wait, in FreeRTOS ticks. Use portMAX_DELAY to wait indefinitely, or 0 for a non-blocking poll.

返回

ESP_OK on success

返回

ESP_ERR_INVALID_ARG if handle is invalid

返回

ESP_ERR_TIMEOUT if the VFS was not mounted before the timeout expired

esp_err_t esp_msc_host_lock(esp_msc_host_handle_t handle, TickType_t timeout)

Lock MSC file access before reading from the mounted VFS.

This prevents the host task from unregistering VFS while a client is actively reading files from the MSC device.

参数

handle – [in] Handle for the MSC host driver
timeout – [in] Timeout in FreeRTOS ticks

返回

ESP_OK on success

返回

ESP_ERR_INVALID_ARG if handle is invalid

返回

ESP_ERR_INVALID_STATE if VFS is not mounted

返回

ESP_ERR_TIMEOUT if the lock cannot be taken in time

esp_err_t esp_msc_host_unlock(esp_msc_host_handle_t handle)

Unlock MSC file access.

参数: handle – [in] Handle for the MSC host driver
返回: ESP_OK on success
返回: ESP_ERR_INVALID_ARG if handle is invalid

esp_err_t esp_msc_host_install(esp_msc_host_config_t *config, esp_msc_host_handle_t *handle)

Install the MSC USB HOST.

备注

When the USB flash drive is inserted, do not call uninstall immediately afterward.

参数

config – [in] See esp_msc_host_config_t for details.
handle – [out] Handle for the MSC host driver

返回

esp_err_t ESP_ERR_INVALID_ARG if any of the parameters are invalid. ESP_ERR_NO_MEM if memory can not be allocated for the driver. ESP_FAIL if the driver fails to install. ESP_OK on success.

esp_err_t esp_msc_host_uninstall(esp_msc_host_handle_t handle)

Uninstall the MSC USB HOST.

备注

When the USB flash drive is inserted, you need to pull out the USB flash drive.

参数: handle – [in] Handle for the MSC host driver
返回: esp_err_t ESP_ERR_INVALID_ARG Invalid argument. ESP_ERR_INVALID_STATE if an MSC device is still connected or mounted. ESP_OK on success.

Structures

struct esp_msc_host_config_t

MSC host driver configuration passed to esp_msc_host_install().

Public Members

const char *base_path: Base path for mounting FATFS.

usb_host_config_t host_config: Configuration structure of the USB Host Library. Provided in the usb_host_install() function

msc_host_driver_config_t host_driver_config: MSC configuration structure. Do not register the callback variable

esp_vfs_fat_mount_config_t vfs_fat_mount_config: Configuration arguments for msc_host_vfs_register function

bool skip_init_usb_host_driver: Skip USB Host Library install/uninstall and event handling task. The application must install USB Host and call usb_host_lib_handle_events()

esp_msc_host_event_cb_t event_cb: Optional direct callback for MSC host events

void *event_cb_arg: User context for event_cb

Macros

DEFAULT_USB_HOST_CONFIG()

DEFAULT_MSC_HOST_DRIVER_CONFIG()

DEFAULT_ESP_VFS_FAT_MOUNT_CONFIG()

Type Definitions

typedef struct esp_msc_host_ctx *esp_msc_host_handle_t

Opaque MSC host handle.

The concrete type is private to the component; users must only pass the value returned by esp_msc_host_install() to the host APIs.

typedef void (*esp_msc_host_event_cb_t)(esp_msc_host_handle_t handle, esp_msc_host_event_t event, void *user_ctx)

MSC host event callback.

This callback is optional and is the only notification path for MSC host events. The handle identifies the host instance that generated the event.

Enumerations

enum esp_msc_host_event_t

MSC host events reported through esp_msc_host_event_cb_t.

Values:

enumerator ESP_MSC_HOST_CONNECT: MSC device connected

enumerator ESP_MSC_HOST_DISCONNECT: MSC device disconnected

enumerator ESP_MSC_HOST_DEVICE_INSTALL: MSC device installed

enumerator ESP_MSC_HOST_DEVICE_UNINSTALL: MSC device uninstalled

enumerator ESP_MSC_HOST_VFS_REGISTER: VFS driver registered

enumerator ESP_MSC_HOST_VFS_UNREGISTER: VFS driver unregistered

Header File

components/usb/esp_msc_ota/include/esp_msc_ota.h

Functions

esp_err_t esp_msc_ota_begin(const 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(const 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_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

esp_msc_host_handle_t host_handle: MSC host handle. OTA waits for this host’s VFS mounted state and locks file access through the host API

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”

TickType_t wait_msc_connect: Wait time for MSC VFS mount in FreeRTOS ticks

size_t buffer_size: Buffer size for OTA write operation, must larger than 1024

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

Type Definitions

typedef struct esp_msc_ota_ctx *esp_msc_ota_handle_t

Opaque MSC OTA handle.

The concrete type is private to the component; users must only pass the value returned by esp_msc_ota_begin() to the OTA APIs. Note that this is a different type from esp_msc_host_handle_t and the two handles must not be used interchangeably.

Enumerations

enum esp_msc_ota_event_t

Declare Event Base for ESP MSC OTA.

MSC OTA events posted on ESP_MSC_OTA_EVENT event base.

Values:

enumerator ESP_MSC_OTA_START: Start update, event data: NULL

enumerator ESP_MSC_OTA_READY_UPDATE: Ready to update, event data: NULL

enumerator ESP_MSC_OTA_WRITE_FLASH: Flash write operation, event data: float *progress

enumerator ESP_MSC_OTA_FAILED: Update failed, event data: esp_err_t *err

enumerator ESP_MSC_OTA_GET_IMG_DESC: Get image description, event data: NULL

enumerator ESP_MSC_OTA_VERIFY_CHIP_ID: Verify chip id, event data: esp_chip_id_t *chip_id

enumerator ESP_MSC_OTA_UPDATE_BOOT_PARTITION: Boot partition update after successful ota update, event data: esp_partition_subtype_t *subtype

enumerator ESP_MSC_OTA_FINISH: OTA finished, event data: NULL

enumerator ESP_MSC_OTA_ABORT: OTA aborted, event data: NULL

enum esp_msc_ota_status_t

Internal state of an esp_msc_ota handle.

Values:

enumerator ESP_MSC_OTA_INIT: Handle allocated but esp_msc_ota_begin() not called yet

enumerator ESP_MSC_OTA_BEGIN: esp_msc_ota_begin() succeeded, ready for esp_msc_ota_perform()

enumerator ESP_MSC_OTA_IN_PROGRESS: Firmware image is being written to flash

enumerator ESP_MSC_OTA_SUCCESS: Full firmware image has been written

提供有关此文档的反馈