Merge branch 'feat/usb_msc_ota_example' into 'master'

feat: add usb msc ota example

Closes AEG-1278

See merge request ae_group/esp-iot-solution!949

.gitlab/ci/build.yml

@@ -670,6 +670,17 @@ build_example_usb_host_usb_cdc_basic:
   variables:
     EXAMPLE_DIR: examples/usb/host/usb_cdc_basic
 
+build_example_usb_host_usb_msc_ota:
+  extends:
+    - .build_examples_template
+    - .rules:build:example_usb_host_usb_msc_ota
+  parallel:
+    matrix:
+      - IMAGE: espressif/idf:release-v5.0
+      - IMAGE: espressif/idf:release-v5.1
+  variables:
+    EXAMPLE_DIR: examples/usb/host/usb_msc_ota
+
 build_example_utilities_xz_decompress_file:
   extends:
     - .build_examples_template

.gitlab/ci/rules.yml

@@ -412,6 +412,9 @@
 .patterns-example_usb_host_usb_cdc_basic: &patterns-example_usb_host_usb_cdc_basic
   - "examples/usb/host/usb_cdc_basic/**/*"
 
+.patterns-example_usb_host_usb_msc_ota: &patterns-example_usb_host_usb_msc_ota
+  - "examples/usb/host/usb_msc_ota/**/*"
+
 .patterns-example_utilities_xz_decompress_file: &patterns-example_utilities_xz_decompress_file
   - "examples/utilities/xz_decompress_file/**/*"
 
@@ -1070,6 +1073,18 @@
     - <<: *if-dev-push
       changes: *patterns-example_usb_host_usb_cdc_basic
 
+.rules:build:example_usb_host_usb_msc_ota:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_esp_msc_ota
+    - <<: *if-dev-push
+      changes: *patterns-example_usb_host_usb_msc_ota
+
 .rules:build:example_utilities_xz_decompress_file:
   rules:
     - <<: *if-protected

components/usb/esp_msc_ota/CHANGELOG.md

@@ -1,5 +1,9 @@
 # changelog
 
+## v0.1.1 - 2024-2-1
+
+* Add example: MSC USB OTA
+
 ## v0.1.0 - 2023-8-15
 
 ### Enhancements:

components/usb/esp_msc_ota/idf_component.yml

@@ -1,14 +1,16 @@
-version: "0.1.0"
+version: "0.1.1"
 targets:
   - esp32s2
   - esp32s3
 
 description: Support OTA update through USB host MSC
-url: https://github.com/espressif/esp-iot-solution
+url: https://github.com/espressif/esp-iot-solution/tree/master/components/usb/esp_msc_ota
 repository: https://github.com/espressif/esp-iot-solution.git
 issues: https://github.com/espressif/esp-iot-solution/issues
 
 dependencies:
   idf: ">=5.0"
   cmake_utilities: "0.*"
   espressif/usb_host_msc: "1.1.1"
+examples:
+  - path: ../../../examples/usb/host/usb_msc_ota

examples/.build-rules.yml

@@ -251,6 +251,10 @@ examples/usb/host/usb_cdc_basic:
   enable:
     - if: IDF_TARGET in ["esp32s2","esp32s3"]
 
+examples/usb/host/usb_msc_ota:
+  enable:
+    - if: SOC_USB_OTG_SUPPORTED == 1
+
 examples/utilities/xz_decompress_file:
   enable:
     - if: INCLUDE_DEFAULT == 1

examples/usb/host/usb_msc_ota/CMakeLists.txt

@@ -0,0 +1,8 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(usb_msc_ota)

examples/usb/host/usb_msc_ota/README.md

@@ -0,0 +1,44 @@
+# USB Host MSC OTA Example
+
+This example demonstrates how to use [esp_msc_ota](https://components.espressif.com/components/espressif/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.
+
+    ```
+    idf.py set-target esp32s3
+    ```
+
+2. Build the project and flash it to the board, then run monitor tool to view serial output:
+
+    ```
+    idf.py -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.
+
+![usb_msc_ota](https://dl.espressif.com/ae/esp-iot-solution/usb_msc_ota.gif)

examples/usb/host/usb_msc_ota/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "usb_msc_ota.c"
+                    INCLUDE_DIRS ".")

examples/usb/host/usb_msc_ota/main/Kconfig.projbuild

@@ -0,0 +1,13 @@
+menu "Example Configeration"
+
+    config MSC_OTA_BIN_NAME
+        string "msc ota bin name"
+        default "usb_msc_ota.bin"
+
+    config SIMPLE_MSC_OTA
+        bool "simple msc ota"
+        default y
+        help
+            simple msc ota
+
+endmenu

examples/usb/host/usb_msc_ota/main/idf_component.yml

@@ -0,0 +1,8 @@
+version: 0.0.1
+targets:
+  - esp32s2
+  - esp32s3
+dependencies:
+  esp_msc_ota:
+    version: "*"
+    override_path: "../../../../../components/usb/esp_msc_ota"

examples/usb/host/usb_msc_ota/main/usb_msc_ota.c

@@ -0,0 +1,118 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_check.h"
+#include "esp_msc_host.h"
+#include "esp_msc_ota.h"
+#include "usb/usb_host.h"
+
+static const char *TAG = "usb_msc_ota";
+
+#define OTA_FILE_NAME "/usb/" CONFIG_MSC_OTA_BIN_NAME
+
+void print_progressbar(float progress, float total)
+{
+    const int bar_width = 50;
+    int filled_width = progress * bar_width / total;
+
+    printf("%s[", LOG_COLOR_I);
+    for (int i = 0; i < bar_width; ++i) {
+        if (i < filled_width) {
+            printf(">");
+        } else {
+            printf(" ");
+        }
+    }
+    printf(" ]%s%d%%\r", LOG_RESET_COLOR, filled_width * 100 / bar_width);
+}
+
+static void msc_ota_event_handler(void *arg, esp_event_base_t event_base,
+                                  int32_t event_id, void *event_data)
+{
+    switch (event_id) {
+    case ESP_MSC_OTA_START:
+        ESP_LOGI(TAG, "ESP_MSC_OTA_START");
+        break;
+    case ESP_MSC_OTA_READY_UPDATE:
+        ESP_LOGI(TAG, "ESP_MSC_OTA_READY_UPDATE");
+        break;
+    case ESP_MSC_OTA_WRITE_FLASH:
+        float progress = *(float *)event_data;
+        print_progressbar(progress, 1.0);
+        break;
+    case ESP_MSC_OTA_FAILED:
+        ESP_LOGI(TAG, "ESP_MSC_OTA_FAILED");
+        break;
+    case ESP_MSC_OTA_GET_IMG_DESC:
+        ESP_LOGI(TAG, "ESP_MSC_OTA_GET_IMG_DESC");
+        break;
+    case ESP_MSC_OTA_VERIFY_CHIP_ID:
+        esp_chip_id_t chip_id = *(esp_chip_id_t *)event_data;
+        ESP_LOGI(TAG, "ESP_MSC_OTA_VERIFY_CHIP_ID, chip_id: %08x", chip_id);
+        break;
+    case ESP_MSC_OTA_UPDATE_BOOT_PARTITION:
+        esp_partition_subtype_t subtype = *(esp_partition_subtype_t *)event_data;
+        ESP_LOGI(TAG, "ESP_MSC_OTA_UPDATE_BOOT_PARTITION, subtype: %d", subtype);
+        break;
+    case ESP_MSC_OTA_FINISH:
+        ESP_LOGI(TAG, "ESP_MSC_OTA_FINISH");
+        break;
+    case ESP_MSC_OTA_ABORT:
+        ESP_LOGI(TAG, "ESP_MSC_OTA_ABORT");
+        break;
+    }
+}
+
+void app_main(void)
+{
+    esp_event_loop_create_default();
+    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 = OTA_FILE_NAME,
+        .wait_msc_connect = portMAX_DELAY,
+    };
+#if CONFIG_SIMPLE_MSC_OTA
+    esp_err_t ret = esp_msc_ota(&config);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "esp_msc_ota failed, ret: %d", ret);
+    }
+#else
+    esp_msc_ota_handle_t msc_ota_handle = NULL;
+
+    esp_err_t ret = esp_msc_ota_begin(&config, &msc_ota_handle);
+    ESP_GOTO_ON_ERROR(ret, fail, TAG, "esp_msc_ota_begin failed, err: %d", ret);
+
+    do {
+        ret = esp_msc_ota_perform(msc_ota_handle);
+        if (ret != ESP_OK) {
+            break;
+            ESP_LOGE(TAG, "esp_msc_ota_perform: (%s)\n", esp_err_to_name(ret));
+        }
+    } while (!esp_msc_ota_is_complete_data_received(msc_ota_handle));
+
+    if (esp_msc_ota_is_complete_data_received(msc_ota_handle)) {
+        esp_msc_ota_end(msc_ota_handle);
+        ESP_LOGI(TAG, "esp msc ota complete");
+    } else {
+        esp_msc_ota_abort(msc_ota_handle);
+        ESP_LOGE(TAG, "esp msc ota failed");
+    }
+fail:
+#endif
+    esp_msc_host_uninstall(host_handle);
+}

examples/usb/host/usb_msc_ota/partitions.csv

@@ -0,0 +1,8 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+# Note: if you have increased the bootloader size, make sure to update the offsets to avoid overlap
+
+nvs,      data, nvs,     ,        0x4000,
+otadata,  data, ota,     ,        0x2000,
+phy_init, data, phy,     ,        0x1000,
+ota_0,    app,  ota_0,   ,        1500K,
+ota_1,    app,  ota_1,   ,        1500K,

examples/usb/host/usb_msc_ota/sdkconfig.ci.no_simple_ota

@@ -0,0 +1 @@
+CONFIG_SIMPLE_MSC_OTA=n

examples/usb/host/usb_msc_ota/sdkconfig.ci.simple_ota

@@ -0,0 +1 @@
+CONFIG_SIMPLE_MSC_OTA=y

examples/usb/host/usb_msc_ota/sdkconfig.defaults

@@ -0,0 +1,8 @@
+# This file was generated using idf.py save-defconfig. It can be edited manually.
+# Espressif IoT Development Framework (ESP-IDF)  Project Minimal Configuration
+#
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_FATFS_LFN_HEAP=y
+CONFIG_FREERTOS_HZ=1000
+CONFIG_USB_HOST_RESET_RECOVERY_MS=200