feat: Add magic baud rate to enter download mode

This feature allows updating the bridge firmware over the same USB cable without physical BOOT/RESET access.

Configure the magic baud in menuconfig under **Bridge Configuration** (`CONFIG_BRIDGE_DOWNLOAD_MAGIC_BAUD`, default `1200`).
Set to `0` to disable. Rebuild and flash after changing the value. The host `bit_rate` must match exactly.

To trigger download mode from the host (adjust `PORT` and baud if configured differently):

```bash
python3 -c "import serial; s=serial.Serial('PORT', 1200); s.close()"
```

Author: peterdragun

README.md

@@ -52,6 +52,32 @@ idf.py -p /dev/ttyACMx flash monitor
 
 Please note that [esptool](https://github.com/espressif/esptool) or any terminal program can connect to the virtual serial port as well.
 
+### Updating Bridge Firmware (Magic Baud Download Mode)
+
+The bridge chip (ESP32-S2 or ESP32-S3) can reset **itself** into ROM download mode when the host sets the USB CDC port to a configured magic baud rate and then closes the port. This allows updating EUB firmware over the same USB cable without physical BOOT/RESET access.
+
+The magic baud **arms** the reset; clearing DTR on port close **fires** it. The bridge then sets `RTC_CNTL_FORCE_DOWNLOAD_BOOT` and restarts. The ROM bootloader exposes a USB download interface on the same cable. This affects the **bridge MCU only**. While the bridge application is running, DTR/RTS on this port still drive the target's BOOT and RST lines; they are unrelated to this self-reset path except that clearing DTR is what fires it once armed.
+
+Do **not** use the magic baud for normal target serial traffic. Opening the CDC at that rate and then clearing DTR (port close, or a host reset sequence that deasserts DTR) puts the **bridge** into download mode instead of communicating with the target.
+
+Configure the magic baud in menuconfig under **Bridge Configuration** (`CONFIG_BRIDGE_DOWNLOAD_MAGIC_BAUD`, default `1200`). Set to `0` to disable. Prefer a baud that host tools will not use for the target. Rebuild and flash after changing the value. The host `bit_rate` must match exactly.
+
+To trigger download mode from the host, adjust `PORT` and baud if configured differently.
+DTR must be asserted while the magic baud is set, then cleared to fire the reset.
+`pyserial` asserts DTR on open by default, so closing the port is enough:
+
+```bash
+python3 -c "import serial; s=serial.Serial('PORT', 1200); s.close()"
+```
+
+After the bridge reboots, flash over USB:
+
+```bash
+idf.py -p PORT flash
+```
+
+The feature requires `EFUSE_DIS_FORCE_DOWNLOAD` and `EFUSE_DIS_DOWNLOAD_MODE` not to be burned (default on development chips).
+
 ## JTAG Bridge
 
 The ESP USB Bridge provides a JTAG device. The following command can be used to connect to an ESP32 target MCU.

main/CMakeLists.txt

@@ -11,6 +11,7 @@ idf_component_register(SRCS "main.c"
                             "msc.c"
                             "eub_vendord.c"
                             "serial_bridge.c"
+                            "usb_phy.c"
                        REQUIRES ${dependencies}
                        LDFRAGMENTS "noflash.lf"
                        INCLUDE_DIRS "." "public_include")

main/Kconfig.projbuild

@@ -69,4 +69,16 @@ menu "Bridge Configuration"
         help
             Volume label shown in the MSC disc. Max length is 11 ASCII characters.
 
+    config BRIDGE_DOWNLOAD_MAGIC_BAUD
+        int "Magic baud rate to enter download mode"
+        default 1200
+        help
+            When the host sets the CDC serial port to this baud rate, download
+            mode reset is armed. Closing the port (clearing DTR) then resets the
+            bridge chip (ESP32-S2 or ESP32-S3) into download mode so its firmware
+            can be updated over USB. Do not use this baud for normal target
+            serial traffic; any DTR clear while armed triggers bridge download
+            mode. Prefer a baud that host tools will not use for the target.
+            Set to 0 to disable.
+
 endmenu

main/main.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -17,10 +17,10 @@
 #include "driver/gpio.h"
 #include "sdkconfig.h"
 #include "esp_mac.h"
-#include "esp_private/usb_phy.h"
 #include "eub_vendord.h"
 #include "debug_probe.h"
 #include "usb_defs.h"
+#include "usb_phy.h"
 #include "led_io.h"
 
 static const char *TAG = "bridge_main";
@@ -229,27 +229,13 @@ static void init_led_gpios(void)
     ESP_LOGI(TAG, "LED GPIO init done");
 }
 
-static void int_usb_phy(void)
-{
-    usb_phy_config_t phy_config = {
-        .controller = USB_PHY_CTRL_OTG,
-        .target = USB_PHY_TARGET_INT,
-        .otg_mode = USB_OTG_MODE_DEVICE,
-        .otg_speed = USB_PHY_SPEED_FULL,
-        .ext_io_conf = NULL,
-        .otg_io_conf = NULL,
-    };
-    usb_phy_handle_t phy_handle;
-    usb_new_phy(&phy_config, &phy_handle);
-}
-
 void app_main(void)
 {
     init_led_gpios(); // Keep this at the beginning. LEDs are used for error reporting.
 
     init_serial_no();
 
-    int_usb_phy();
+    ESP_ERROR_CHECK(eub_usb_phy_init());
 
     ESP_ERROR_CHECK(serial_handler_init(TRANSPORT_TYPE_UART));
     serial_handler_register_tx_activity_callback(serial_tx_activity_callback);

main/serial_bridge.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,17 +18,24 @@
 #include "freertos/ringbuf.h"
 #include "freertos/semphr.h"
 #include "esp_timer.h"
+#include "esp_system.h"
+#include "sdkconfig.h"
 #include "util.h"
 #include "debug_probe.h"
+#include "usb_phy.h"
+#include "soc/rtc_cntl_reg.h"
 
 #define USB_SEND_RINGBUFFER_SIZE (2 * 1024)
+/* tud_cdc_n_get_line_state(): bit 0 = DTR, bit 1 = RTS */
+#define CDC_LINE_STATE_DTR (1u << 0)
 
 static const char *TAG = "serial_bridge";
 
 static RingbufHandle_t usb_sendbuf;
 static SemaphoreHandle_t usb_tx_requested = NULL;
 static SemaphoreHandle_t usb_tx_done = NULL;
 static esp_timer_handle_t state_change_timer;
+static bool download_mode_armed;
 
 // Transport data received callback - called by serial handler when data arrives
 static void transport_data_received_callback(const uint8_t *data, size_t len)
@@ -121,8 +128,22 @@ void tud_cdc_rx_cb(const uint8_t itf)
     }
 }
 
+static void enter_download_mode(void);
+
 void tud_cdc_line_coding_cb(const uint8_t itf, cdc_line_coding_t const *p_line_coding)
 {
+    if (CONFIG_BRIDGE_DOWNLOAD_MAGIC_BAUD > 0 && p_line_coding->bit_rate == CONFIG_BRIDGE_DOWNLOAD_MAGIC_BAUD) {
+        ESP_LOGI(TAG, "Magic baud %" PRIu32 " detected, arming download mode reset",
+                 p_line_coding->bit_rate);
+        download_mode_armed = true;
+        // Fire immediately if the host already cleared DTR (e.g. baud change on a closed port).
+        if (!(tud_cdc_n_get_line_state(itf) & CDC_LINE_STATE_DTR)) {
+            enter_download_mode();
+        }
+        return;
+    }
+
+    download_mode_armed = false;
     if (serial_handler_set_baudrate(p_line_coding->bit_rate) != ESP_OK) {
         ESP_LOGE(TAG, "Could not set the baudrate to %" PRIu32, p_line_coding->bit_rate);
         eub_abort();
@@ -131,6 +152,12 @@ void tud_cdc_line_coding_cb(const uint8_t itf, cdc_line_coding_t const *p_line_c
 
 void tud_cdc_line_state_cb(const uint8_t itf, const bool dtr, const bool rts)
 {
+    // Magic baud arms download mode; clearing DTR (typically on port close) fires it.
+    if (download_mode_armed && !dtr) {
+        enter_download_mode();
+        return;
+    }
+
     // The following transformation of DTR & RTS signals to BOOT & RST is done based on auto reset circutry shown in
     // schematics of ESP boards.
 
@@ -182,6 +209,20 @@ static void state_change_timer_cb(void *arg)
     serial_handler_set_boot_reset_pins(true, true); // BOOT=1, RST=1 (not in reset)
 }
 
+static void enter_download_mode(void)
+{
+    if (CONFIG_BRIDGE_DOWNLOAD_MAGIC_BAUD <= 0) {
+        return;
+    }
+
+    ESP_LOGI(TAG, "Forcing download mode and resetting bridge chip");
+    // Tear down USB before restart; avoid logging after this point (PHY/console go away).
+    // Called from tusb_device_task (CDC callbacks); esp_restart() never returns to tud_task.
+    eub_usb_phy_deinit();
+    REG_SET_BIT(RTC_CNTL_OPTION1_REG, RTC_CNTL_FORCE_DOWNLOAD_BOOT);
+    esp_restart();
+}
+
 static void init_state_change_timer(void)
 {
     const esp_timer_create_args_t timer_args = {

main/usb_phy.c

@@ -0,0 +1,71 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "usb_phy.h"
+#include "esp_private/usb_phy.h"
+#include "esp_rom_sys.h"
+#include "sdkconfig.h"
+#include "tusb.h"
+#if CONFIG_IDF_TARGET_ESP32S3
+#include "soc/rtc_cntl_reg.h"
+#include "soc/usb_serial_jtag_reg.h"
+#include "soc/usb_pins.h"
+#include "driver/gpio.h"
+#endif  // CONFIG_IDF_TARGET_ESP32S3
+
+static usb_phy_handle_t s_usb_phy;
+
+esp_err_t eub_usb_phy_init(void)
+{
+    const usb_phy_config_t phy_config = {
+        .controller = USB_PHY_CTRL_OTG,
+        .target = USB_PHY_TARGET_INT,
+        .otg_mode = USB_OTG_MODE_DEVICE,
+        .otg_speed = USB_PHY_SPEED_FULL,
+        .ext_io_conf = NULL,
+        .otg_io_conf = NULL,
+    };
+    return usb_new_phy(&phy_config, &s_usb_phy);
+}
+
+void eub_usb_phy_deinit(void)
+{
+    /*
+     * Detach from the bus before tearing down the PHY. With MSC mounted, the host
+     * keeps bulk transfers in flight; deleting the PHY / reconfiguring the pads
+     * while those are active can hang the teardown path so download-mode entry
+     * never completes until the volume is ejected.
+     */
+    tud_disconnect();
+    esp_rom_delay_us(10 * 1000);
+
+    if (s_usb_phy) {
+        usb_del_phy(s_usb_phy);
+        s_usb_phy = NULL;
+    }
+
+#if CONFIG_IDF_TARGET_ESP32S3
+    // Switch to hardware CDC+JTAG:
+    // Clear SW override and SW PHY sel bits so hardware (eFuse default) takes over,
+    // which maps internal PHY to USB Serial/JTAG
+    CLEAR_PERI_REG_MASK(RTC_CNTL_USB_CONF_REG,
+                        (RTC_CNTL_SW_HW_USB_PHY_SEL | RTC_CNTL_SW_USB_PHY_SEL | RTC_CNTL_USB_PAD_ENABLE));
+
+    // Do not use external PHY for Serial/JTAG
+    CLEAR_PERI_REG_MASK(USB_SERIAL_JTAG_CONF0_REG, USB_SERIAL_JTAG_PHY_SEL);
+
+    // Release GPIO pins from USB Serial/JTAG pad
+    CLEAR_PERI_REG_MASK(USB_SERIAL_JTAG_CONF0_REG, USB_SERIAL_JTAG_USB_PAD_ENABLE);
+
+    // Force host to see a USB disconnect (BUS_RESET) by pulling D+/D- LOW
+    gpio_set_direction(USBPHY_DM_NUM, GPIO_MODE_OUTPUT_OD);
+    gpio_set_direction(USBPHY_DP_NUM, GPIO_MODE_OUTPUT_OD);
+    gpio_set_level(USBPHY_DM_NUM, 0);
+    gpio_set_level(USBPHY_DP_NUM, 0);
+
+    SET_PERI_REG_MASK(USB_SERIAL_JTAG_CONF0_REG, USB_SERIAL_JTAG_USB_PAD_ENABLE);
+#endif  // CONFIG_IDF_TARGET_ESP32S3
+}

main/usb_phy.h

@@ -0,0 +1,35 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize the internal USB OTG PHY used by the USB device stack
+ *
+ * @return esp_err_t ESP_OK on success
+ */
+esp_err_t eub_usb_phy_init(void);
+
+/**
+ * @brief Tear down the USB OTG PHY before forcing download mode
+ *
+ * Disconnects from the bus and deletes the OTG PHY created by
+ * eub_usb_phy_init(). On ESP32-S3, also reconfigures the USB pads so the
+ * built-in USB Serial/JTAG controller can take over and the host sees a bus
+ * disconnect. On ESP32-S2 there is no USB Serial/JTAG block; only disconnect
+ * and PHY delete are performed.
+ */
+void eub_usb_phy_deinit(void);
+
+#ifdef __cplusplus
+}
+#endif