uploaded 2 weeks ago

Support OTA update through USB host MSC


[![Component Registry](](

## Introduction to ESP MSC OTA Component

``esp_msc_ota`` is a USB disk OTA program based on ESP32 USB OTG peripheral.

* Supports hot-plugging of USB disk.
* Supports USB disk OTA functionality.

### User Guide

Please refer:

### Adding the Component to the Project

Please use the component manager command `add-dependency` to add `esp_msc_ota` as a dependency to your project. During the `CMake` execution, this component will be automatically downloaded to the project directory.

    ``` add-dependency "espressif/esp_msc_ota=*"

## Usage Example

    ESP_ERROR_CHECK(esp_event_handler_register(ESP_MSC_OTA_EVENT, ESP_EVENT_ANY_ID, &msc_ota_event_handler, NULL));
    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_config_t config = {
        .ota_bin_path = "/usb/ota_test.bin",
        .wait_msc_connect = pdMS_TO_TICKS(5000),

## Notes

* For the default file system, filenames should not exceed 11 characters. If support for long-named files is needed, please enable any of the macros below:



# changelog

## v0.1.1 - 2024-2-1

* Add example: MSC USB OTA

## v0.1.0 - 2023-8-15

### Enhancements:

* Support MSC hot-plug
* Support MSC OTA process management

readme of usb_msc_ota example

                                        # USB Host MSC OTA Example

This example demonstrates how to use [esp_msc_ota]( to OTA with USB disk or other MSC devices.

## How to use the example

### Hardware Required

The example can be run on ESP32-S2 or ESP32-S3 based development board with USB Disk (with Fat32 format).

### Setup the Hardware

Connect the external USB MSC device to ESP32-S USB interface directly.

| ESP32-Sx GPIO | USB Device  |
| ------------- | ----------- |
| 20            | D+ (green)  |
| 19            | D- (white)  |
| GND           | GND (black) |
| +5V           | +5V (red)   |

### Configure the project

1. Use the command below to set build target to esp32s2 or esp32s3.

    ``` set-target esp32s3

2. Build the project and flash it to the board, then run monitor tool to view serial output:

    ``` -p PORT build flash monitor

    (To exit the serial monitor, type ``Ctrl-]``.)

    See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

3. Move the file located in the directory /build/usb_msc_ota.bin to the USB MSC drive (USB disk). Insert the USB flash drive into the USB interface. The upgrade process will start immediately. Once the upgrade is successful, press the reset button to initiate OTA partition 2.

Note: Please keep in mind, to continuous support for USB MSC OTA, the USB MSC OTA function must also be enabled in the OTA firmware.



License: Apache-2.0

To add this component to your project, run: add-dependency "espressif/esp_msc_ota^0.1.1"

or download archive


  • espressif/cmake_utilities 0.*
  • espressif/usb_host_msc 1.1.1
  • ESP-IDF >=5.0
  • Examples:


    more details


    • Downloaded in total
      Downloaded in total 6 times
    • Downloaded this version
      This version: 2 times


    espressif/esp_msc_ota version: 0.1.1 |