feat: USB CDC ACM interface support

DNedic · DNedic · commit 4e26444fb056 · 2024-02-13T16:04:20.000+01:00
This adds support for the USB CDC ACM interface, and an ESP port using the interface. Closes #64
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@ empty_file.bin
 binaries.c
 *.lock
 python_venv
+managed_components
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -38,10 +38,29 @@ variables:
     - idf.py build
     - cd $CI_PROJECT_DIR/examples/esp32_spi_load_ram_example
     - idf.py build
+    - cd $CI_PROJECT_DIR/examples/esp32_usb_cdc_acm_example
+    - idf.py build
 
+# Special case as ESP-IDF v4.3 is not supported by the usb_host_cdc_acm component
+# required by the USB CDC ACM interface port and its example
 build_idf_v4.3:
-  extends: .build_idf_template
+  stage: build
   image: espressif/idf:release-v4.3
+  tags:
+    - build
+    - internet
+  variables:
+    PEDANTIC_FLAGS: "-Werror -Wall -Wextra"
+    EXTRA_CFLAGS: "${PEDANTIC_FLAGS}"
+    EXTRA_CXXFLAGS: "${PEDANTIC_FLAGS}"
+  script:
+    - cd $CI_PROJECT_DIR/examples/esp32_example
+    - idf.py build -DMD5_ENABLED=1
+    - idf.py build -DMD5_ENABLED=0
+    - cd $CI_PROJECT_DIR/examples/esp32_load_ram_example
+    - idf.py build
+    - cd $CI_PROJECT_DIR/examples/esp32_spi_load_ram_example
+    - idf.py build
 
 build_idf_v4.4:
   extends: .build_idf_template
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -19,6 +19,12 @@ if (DEFINED ESP_PLATFORM)
             src/protocol_spi.c
             port/esp32_spi_port.c
         )
+    elseif (${CONFIG_SERIAL_FLASHER_INTERFACE_USB})
+        list(APPEND srcs
+            src/protocol_uart.c
+            src/slip.c
+            port/esp32_usb_cdc_acm_port.c
+        )
     endif()
 
     # Register component to esp-idf build system
@@ -27,6 +33,10 @@ if (DEFINED ESP_PLATFORM)
                            PRIV_INCLUDE_DIRS private_include
                            PRIV_REQUIRES driver esp_timer)
 
+    if (${CONFIG_SERIAL_FLASHER_INTERFACE_USB})
+        idf_component_set_property(${COMPONENT_NAME} PRIV_REQUIRES usb APPEND)
+    endif()
+
     set(target ${COMPONENT_LIB})
     component_compile_options(-Wstrict-prototypes)
 
@@ -91,6 +101,11 @@ elseif (DEFINED SERIAL_FLASHER_INTERFACE_SPI OR CONFIG_SERIAL_FLASHER_INTERFACE_
     PUBLIC
         SERIAL_FLASHER_INTERFACE_SPI
     )
+elseif (DEFINED SERIAL_FLASHER_INTERFACE_USB OR CONFIG_SERIAL_FLASHER_INTERFACE_USB STREQUAL "y")
+    target_compile_definitions(${target}
+    PUBLIC
+        SERIAL_FLASHER_INTERFACE_USB
+    )
 endif()
 
 if(DEFINED SERIAL_FLASHER_DEBUG_TRACE OR CONFIG_SERIAL_FLASHER_DEBUG_TRACE)
diff --git a/Kconfig b/Kconfig
@@ -17,6 +17,9 @@ menu "ESP serial flasher"
         config SERIAL_FLASHER_INTERFACE_SPI
             bool "SPI (Only supports downloading to RAM)"
 
+        config SERIAL_FLASHER_INTERFACE_USB
+            bool "USB (Experimental)"
+
     endchoice
 
     config SERIAL_FLASHER_RESET_HOLD_TIME_MS
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 `esp-serial-flasher` is a portable C library for flashing or loading apps to RAM of Espressif SoCs from other host microcontrollers.
 
 ## Using the library
-Espressif SoCs are normally programmed via serial interface (UART).
+`esp-serial-flasher` supports a variety of host/target/interface combinations:
 
 Supported **host** microcontrollers:
 
@@ -26,14 +26,15 @@ Supported **target** microcontrollers:
 Supported hardware interfaces:
 - UART
 - SPI (only for RAM download)
+- USB CDC ACM (experimental)
 
 For example usage check the `examples` directory.
 
 ## Configuration
 
 These are the configuration toggles available to the user:
 
-* `SERIAL_FLASHER_INTERFACE_UART/SERIAL_FLASHER_INTERFACE_SPI`
+* `SERIAL_FLASHER_INTERFACE_UART`/`SERIAL_FLASHER_INTERFACE_SPI`/`SERIAL_FLASHER_INTERFACE_USB`
 
 This defines the hardware interface to use.
 
diff --git a/examples/common/example_common.c b/examples/common/example_common.c
@@ -253,7 +253,7 @@ esp_loader_error_t connect_to_target(uint32_t higher_transmission_rate)
     }
     printf("Connected to target\n");
 
-#ifdef SERIAL_FLASHER_INTERFACE_UART
+#if (defined SERIAL_FLASHER_INTERFACE_UART) || (defined SERIAL_FLASHER_INTERFACE_USB)
     if (higher_transmission_rate && esp_loader_get_target() != ESP8266_CHIP) {
         err = esp_loader_change_transmission_rate(higher_transmission_rate);
         if (err == ESP_LOADER_ERROR_UNSUPPORTED_FUNC) {
@@ -271,12 +271,12 @@ esp_loader_error_t connect_to_target(uint32_t higher_transmission_rate)
             printf("Transmission rate changed changed\n");
         }
     }
-#endif /* SERIAL_FLASHER_INTERFACE_UART */
+#endif /* SERIAL_FLASHER_INTERFACE_UART || SERIAL_FLASHER_INTERFACE_USB */
 
     return ESP_LOADER_SUCCESS;
 }
 
-#ifdef SERIAL_FLASHER_INTERFACE_UART
+#if (defined SERIAL_FLASHER_INTERFACE_UART) || (defined SERIAL_FLASHER_INTERFACE_USB)
 esp_loader_error_t flash_binary(const uint8_t *bin, size_t size, size_t address)
 {
     esp_loader_error_t err;
@@ -329,7 +329,7 @@ esp_loader_error_t flash_binary(const uint8_t *bin, size_t size, size_t address)
 
     return ESP_LOADER_SUCCESS;
 }
-#endif /* SERIAL_FLASHER_INTERFACE_UART */
+#endif /* SERIAL_FLASHER_INTERFACE_UART || SERIAL_FLASHER_INTERFACE_USB */
 
 esp_loader_error_t load_ram_binary(const uint8_t *bin)
 {
diff --git a/examples/esp32_usb_cdc_acm_example/CMakeLists.txt b/examples/esp32_usb_cdc_acm_example/CMakeLists.txt
@@ -0,0 +1,9 @@
+# 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)
+
+set(EXTRA_COMPONENT_DIRS ../../)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(esp32_usb_cdc_acm_example)
diff --git a/examples/esp32_usb_cdc_acm_example/README.md b/examples/esp32_usb_cdc_acm_example/README.md
@@ -0,0 +1,86 @@
+# Flashing multiple partitions over USB CDC ACM interface
+
+## Overview
+
+This example demonstrates how to flash an ESP32-S3 from another ESP32-S3 or an ESP32-S2 MCU using the `esp_serial_flash` component API. Binaries to be flashed from host MCU to another Espressif SoC can be found in `binaries` folder and are converted into C-array during build process.
+
+> **Note:** The `esp32_usb_cdc_acm` port requires ESP-IDF v4.4 or newer to build
+
+Following steps are performed in order to re-program target's memory:
+
+1. The system is started
+2. The USB CDC ACM driver is initialized and a task to handle USB events is created
+3. As soon as an ESP32-S3 is connected to the bus, a connection is opened with it using `loader_port_esp32_usb_cdc_acm_init()`. If the target USB Serial/JTAG peripheral is not active (e.g the device firmware is using the USB OTG peripheral), it is necessary to manually put it in download mode.
+4. The flasher connection is started with the connected ESP32-S3 by calling `esp_loader_connect()`.
+5. Binary file is opened and its size is acquired, as it has to be known before flashing.
+6. Then `esp_loader_flash_start()` is called to enter flashing mode and erase amount of memory to be flashed.
+7. `esp_loader_flash_write()` function is called repeatedly until the whole binary image is transferred.
+8. After completion, the device can be manually reset and another ESP32-S3 can be connected to perform the flashing on.
+
+> **Note:** The USB CDC ACM device of the ESP32-S3 does not support changing the baudrate, so the argument to `esp_loader_connect()` is irrelevant
+
+## USB host driver usage
+
+This example makes use of the Espressif [USB Host Driver](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/usb_host.html).
+In addition to initializing the host driver, a FreeRTOS task needs to be created to handle host usb events.
+
+A binary semaphore is used as a lock for the connected device, and a callback is registered with the loader port which releases the lock so that a new device can be connected only after disconnection.
+
+## Hardware Required
+
+* One ESP32-S3 target board and one ESP32-S3 or ESP32-S2 board, with each board having USB connections
+* An USB OTG adapter for the host board
+* One or two USB cables for power supply and programming.
+
+> **Note:** The USB connector on most ESP32-S3 and ESP32-S2 boards cannot supply power to the target, so a separate power connection is required
+
+## Building and flashing
+
+To run the example, type the following command:
+
+```CMake
+idf.py -p PORT 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.
+
+## Configuration
+
+For details about available configuration option, please refer to top level [README.md](../../README.md). 
+Compile definitions can be specified on command line when running `idf.py`, for example:
+
+```
+idf.py build -DMD5_ENABLED=1
+```
+Binaries to be flashed are placed in separate folder (binaries.c) for each possible target and converted to C-array. Without explicitly enabling MD5 check, flash integrity verification is disabled by default.
+
+## Example output
+
+Here is the example's console output:
+
+```
+...
+I (541) main_task: Calling app_main()
+I (541) usb_flasher: Installing USB Host
+I (571) usb_flasher: Installing the USB CDC-ACM driver
+I (571) usb_flasher: Opening CDC ACM device 0x303A:0x1001...
+Connected to target
+I (1121) usb_flasher: Loading bootloader...
+Erasing flash (this may take a while)...
+Start programming
+Progress: 100 %
+Finished programming
+I (1681) usb_flasher: Loading partition table...
+Erasing flash (this may take a while)...
+Start programming
+Progress: 100 %
+Finished programming
+I (1771) usb_flasher: Loading app...
+Erasing flash (this may take a while)...
+Start programming
+Progress: 100 %
+Finished programming
+I (5011) usb_flasher: Done!
+```
diff --git a/examples/esp32_usb_cdc_acm_example/main/CMakeLists.txt b/examples/esp32_usb_cdc_acm_example/main/CMakeLists.txt
@@ -0,0 +1,16 @@
+set(srcs main.c ../../common/example_common.c)
+set(include_dirs . ../../common)
+
+idf_component_register(SRCS ${srcs}
+                    INCLUDE_DIRS ${include_dirs}
+                    PRIV_REQUIRES esp-serial-flasher usb
+                    )
+set(target ${COMPONENT_LIB})
+
+# Embed binaries into the app.
+# In ESP-IDF this can also be done using EMBED_FILES option of idf_component_register.
+# Here an external tool is used to make file embedding similar with other ports.
+include(${CMAKE_CURRENT_LIST_DIR}/../../common/bin2array.cmake)
+create_resources(${CMAKE_CURRENT_LIST_DIR}/../../binaries/Hello-world ${CMAKE_BINARY_DIR}/binaries.c)
+set_property(SOURCE ${CMAKE_BINARY_DIR}/binaries.c PROPERTY GENERATED 1)
+target_sources(${target} PRIVATE ${CMAKE_BINARY_DIR}/binaries.c)
diff --git a/examples/esp32_usb_cdc_acm_example/main/idf_component.yml b/examples/esp32_usb_cdc_acm_example/main/idf_component.yml
@@ -0,0 +1,4 @@
+## IDF Component Manager Manifest File
+dependencies:
+  usb_host_cdc_acm: "^2"
+  idf: ">=4.4"
diff --git a/examples/esp32_usb_cdc_acm_example/main/main.c b/examples/esp32_usb_cdc_acm_example/main/main.c
@@ -0,0 +1,117 @@
+/* Flashing multiple partitions over USB CDC ACM interface
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+
+#include "esp_log.h"
+#include "esp_err.h"
+#include "esp_loader.h"
+#include "esp32_usb_cdc_acm_port.h"
+#include "example_common.h"
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+
+#include "usb/usb_host.h"
+#include "usb/cdc_acm_host.h"
+
+#define ESPRESSIF_VID 0x303a
+#define ESP_SERIAL_JTAG_PID 0x1001
+
+static const char *TAG = "usb_flasher";
+static SemaphoreHandle_t device_disconnected_sem;
+
+/**
+ * @brief USB Host library handling task
+ *
+ * @param arg Unused
+ */
+static void usb_lib_task(void *arg)
+{
+    while (1) {
+        /* Start handling system events */
+        uint32_t event_flags;
+        usb_host_lib_handle_events(portMAX_DELAY, &event_flags);
+        if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) {
+            ESP_ERROR_CHECK(usb_host_device_free_all());
+        }
+        if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) {
+            ESP_LOGI(TAG, "USB: All devices freed");
+            /* Continue handling USB events to allow device reconnection */
+        }
+    }
+}
+
+static void device_disconnected_callback(void)
+{
+    xSemaphoreGive(device_disconnected_sem);
+}
+
+/**
+ * @brief Main application
+ *
+ * Here we open a connection with any ESP32-S3 device connected and try flashing it
+ */
+void app_main(void)
+{
+    /* Install USB Host driver. Should only be called once in entire application */
+    ESP_LOGI(TAG, "Installing USB Host");
+    const usb_host_config_t host_config = {
+        .skip_phy_setup = false,
+        .intr_flags = ESP_INTR_FLAG_LEVEL1,
+    };
+    ESP_ERROR_CHECK(usb_host_install(&host_config));
+
+    /* Create a task that will handle USB library events */
+    BaseType_t task_created = xTaskCreate(usb_lib_task,
+                                          "usb_lib",
+                                          4096,
+                                          xTaskGetCurrentTaskHandle(),
+                                          20,
+                                          NULL);
+    assert(task_created == pdTRUE);
+
+    ESP_LOGI(TAG, "Installing the USB CDC-ACM driver");
+    ESP_ERROR_CHECK(cdc_acm_host_install(NULL));
+
+    while (true) {
+        const loader_esp32_usb_cdc_acm_config_t config = {
+            .device_vid = ESPRESSIF_VID,
+            .device_pid = ESP_SERIAL_JTAG_PID,
+            .connection_timeout_ms = 1000,
+            .out_buffer_size = 4096,
+            .device_disconnected_callback = device_disconnected_callback,
+        };
+
+        ESP_LOGI(TAG, "Opening CDC ACM device 0x%04X:0x%04X...", config.device_vid, config.device_pid);
+        if (loader_port_esp32_usb_cdc_acm_init(&config) != ESP_LOADER_SUCCESS) {
+            continue;
+        }
+
+        device_disconnected_sem = xSemaphoreCreateBinary();
+        assert(device_disconnected_sem);
+
+        /* The ESP32-S3 ignores the line coding set commands,
+           so we don't set the higher baudrate argument */
+        if (connect_to_target(0) == ESP_LOADER_SUCCESS) {
+            example_binaries_t bin;
+            get_example_binaries(esp_loader_get_target(), &bin);
+
+            ESP_LOGI(TAG, "Loading bootloader...");
+            flash_binary(bin.boot.data, bin.boot.size, bin.boot.addr);
+            ESP_LOGI(TAG, "Loading partition table...");
+            flash_binary(bin.part.data, bin.part.size, bin.part.addr);
+            ESP_LOGI(TAG, "Loading app...");
+            flash_binary(bin.app.data, bin.app.size, bin.app.addr);
+            ESP_LOGI(TAG, "Done!");
+        }
+
+        /* Wait for device disconnection and start over */
+        xSemaphoreTake(device_disconnected_sem, portMAX_DELAY);
+    }
+}
diff --git a/examples/esp32_usb_cdc_acm_example/partitions.csv b/examples/esp32_usb_cdc_acm_example/partitions.csv
@@ -0,0 +1,4 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     ,        0x6000,
+phy_init, data, phy,     ,        0x1000,
+factory,  app,  factory, ,        1920K,
diff --git a/examples/esp32_usb_cdc_acm_example/sdkconfig.defaults b/examples/esp32_usb_cdc_acm_example/sdkconfig.defaults
@@ -0,0 +1,3 @@
+CONFIG_IDF_TARGET="esp32s3"
+CONFIG_SERIAL_FLASHER_INTERFACE_USB=y
+CONFIG_PARTITION_TABLE_CUSTOM=y
diff --git a/idf_component.yml b/idf_component.yml
@@ -3,3 +3,8 @@ description: Serial flasher component provides portable library for flashing or
 url: https://github.com/espressif/esp-serial-flasher
 dependencies:
   idf: ">=4.3"
+  usb_host_cdc_acm:
+    version: "^2"
+    rules:
+      - if: "idf_version >=4.4"
+      - if: "target in [esp32s2, esp32s3]"
diff --git a/include/esp_loader.h b/include/esp_loader.h
diff --git a/port/esp32_usb_cdc_acm_port.c b/port/esp32_usb_cdc_acm_port.c
diff --git a/port/esp32_usb_cdc_acm_port.h b/port/esp32_usb_cdc_acm_port.h
diff --git a/private_include/protocol.h b/private_include/protocol.h
diff --git a/src/esp_loader.c b/src/esp_loader.c

Original file line number	Diff line number	Diff line change
`@@ -253,7 +253,7 @@ esp_loader_error_t connect_to_target(uint32_t higher_transmission_rate)`
`253`	`253`	`}`
`254`	`254`	`printf("Connected to target\n");`
`255`	`255`
`256`		`-#ifdef SERIAL_FLASHER_INTERFACE_UART`
	`256`	`+#if (defined SERIAL_FLASHER_INTERFACE_UART) \|\| (defined SERIAL_FLASHER_INTERFACE_USB)`
`257`	`257`	`if (higher_transmission_rate && esp_loader_get_target() != ESP8266_CHIP) {`
`258`	`258`	`err = esp_loader_change_transmission_rate(higher_transmission_rate);`
`259`	`259`	`if (err == ESP_LOADER_ERROR_UNSUPPORTED_FUNC) {`
`@@ -271,12 +271,12 @@ esp_loader_error_t connect_to_target(uint32_t higher_transmission_rate)`
`271`	`271`	`printf("Transmission rate changed changed\n");`
`272`	`272`	`}`
`273`	`273`	`}`
`274`		`-#endif /* SERIAL_FLASHER_INTERFACE_UART */`
	`274`	`+#endif /* SERIAL_FLASHER_INTERFACE_UART \|\| SERIAL_FLASHER_INTERFACE_USB */`
`275`	`275`
`276`	`276`	`return ESP_LOADER_SUCCESS;`
`277`	`277`	`}`
`278`	`278`
`279`		`-#ifdef SERIAL_FLASHER_INTERFACE_UART`
	`279`	`+#if (defined SERIAL_FLASHER_INTERFACE_UART) \|\| (defined SERIAL_FLASHER_INTERFACE_USB)`
`280`	`280`	`esp_loader_error_t flash_binary(const uint8_t *bin, size_t size, size_t address)`
`281`	`281`	`{`
`282`	`282`	`esp_loader_error_t err;`
`@@ -329,7 +329,7 @@ esp_loader_error_t flash_binary(const uint8_t *bin, size_t size, size_t address)`
`329`	`329`
`330`	`330`	`return ESP_LOADER_SUCCESS;`
`331`	`331`	`}`
`332`		`-#endif /* SERIAL_FLASHER_INTERFACE_UART */`
	`332`	`+#endif /* SERIAL_FLASHER_INTERFACE_UART \|\| SERIAL_FLASHER_INTERFACE_USB */`
`333`	`333`
`334`	`334`	`esp_loader_error_t load_ram_binary(const uint8_t *bin)`
`335`	`335`	`{`