Skip to content

feat(usb): Add ESP32-S31 support in tinyusb#81

Merged
igi540 merged 1 commit intorelease/v0.20from
feat/tinyusb_esp32s31_support
Apr 15, 2026
Merged

feat(usb): Add ESP32-S31 support in tinyusb#81
igi540 merged 1 commit intorelease/v0.20from
feat/tinyusb_esp32s31_support

Conversation

@igi540
Copy link
Copy Markdown
Collaborator

@igi540 igi540 commented Apr 10, 2026

Description

Add ESP32-S31 as a supported MCU in TinyUSB. The S31 uses a DWC2 high-speed OTG controller with a UTMI PHY on Port 0 — unlike ESP32-P4 which has both FS (Port 0) and HS (Port 1) controllers, the S31 has a single HS-only port.

Changes

Core stack (src/)

  • Define OPT_MCU_ESP32S31 (911) in tusb_option.h
  • Add S31 MCU configuration in tusb_mcu.h: DWC2 HS, 16 endpoints, multi-core, slave/DMA toggle
  • Add DWC2 controller entry in dwc2_esp32.h (reg base 0x20300000, 4096 FIFO, ETS_USB_OTGHS_INTR_SOURCE)
  • Exclude usb_wrap_struct.h include and USB_WRAP usage — S31 has no USB_WRAP peripheral
  • Select USB_PHY_TARGET_UTMI instead of USB_PHY_TARGET_INT for S31 PHY init

Build system

  • Add esp32s31 target to idf_component.yml
  • Map esp32s31 to OPT_MCU_ESP32S31 in top-level CMakeLists.txt
  • Force OPT_MODE_HIGH_SPEED for S31 device/host port speed in family.cmake
  • Remove unused tusb_family variable from CMakeLists.txt

BSP

  • Add OPT_MCU_ESP32S31 to all TU_CHECK_MCU guard lists in family.c
  • Remove empty preprocessor guard block

CI

  • Remove --disable-targets esp32s31 from build_and_run_idf_examples.yml and build_and_run_esp_usb_test_apps.yml

Docs

  • Add S31 row to supported CPUs table in README.rst
  • Add changelog entry in docs/info/changelog.rst

Other

  • Fix missing TUP_MCU_MULTIPLE_CORE definition for ESP32-H4

@igi540 igi540 self-assigned this Apr 10, 2026
@peter-marcisovsky
Copy link
Copy Markdown
Collaborator

@igi540 Apart from the current build errors related to S31 changes, there will be some run errors, same as in my older PR #77

I have finished another CI fix in #79 which corrects the current CI, just waiting for the CI to finish.
We can merge my #79 first, then you rebase onto my changes and will enable S31.

Comment thread .github/workflows/build_and_run_esp_usb_test_apps.yml Outdated
Comment thread .github/workflows/build_and_run_idf_examples.yml Outdated
Comment thread idf_component.yml
Comment thread CMakeLists.txt Outdated
Comment thread hw/bsp/espressif/boards/CMakeLists.txt Outdated
Comment thread src/common/tusb_mcu.h
Comment thread src/common/tusb_mcu.h Outdated
Comment thread src/common/tusb_mcu.h
Comment thread src/common/tusb_mcu.h Outdated
Comment thread docs/reference/boards.rst Outdated
Comment thread hw/bsp/espressif/components/led_strip/CMakeLists.txt
@igi540 igi540 force-pushed the feat/tinyusb_esp32s31_support branch from 3941223 to ad9da55 Compare April 14, 2026 22:00
Add ESP32-S31 as a supported MCU in TinyUSB and wire it into build/runtime,
BSP, docs, examples, and CI.

- Define OPT_MCU_ESP32S31 (911) with DWC2 HS-only, UTMI PHY, 16 endpoints
- Add DWC2 controller entry (reg base 0x20300000, 4096 FIFO)
- Exclude USB_WRAP peripheral (not present on S31)
- Force high-speed mode for Port 0 in family.cmake
- Enable CI builds for esp32s31 target
- Update idf_component.yml, README, and changelog

Also:
- Fix missing TUP_MCU_MULTIPLE_CORE for ESP32-H4
- Remove unused tusb_family variable from CMakeLists.txt
- Remove empty preprocessor guard block in family.c
@igi540 igi540 force-pushed the feat/tinyusb_esp32s31_support branch from ad9da55 to 04437f8 Compare April 14, 2026 22:06
@igi540 igi540 marked this pull request as ready for review April 14, 2026 22:08
@tore-espressif
Copy link
Copy Markdown
Collaborator

@igi540 LGTM, but please check the failing MSC example build in CI.

It might be related to missing defaults for MSC buffer sizes https://github.com/espressif/esp-usb/blob/master/device/esp_tinyusb/Kconfig#L139

If the required fix is only in esp_tinyusb, we can merge this PR and continue working on esp_tinyusb

@igi540
Copy link
Copy Markdown
Collaborator Author

igi540 commented Apr 15, 2026

@igi540 LGTM, but please check the failing MSC example build in CI.

It might be related to missing defaults for MSC buffer sizes https://github.com/espressif/esp-usb/blob/master/device/esp_tinyusb/Kconfig#L139

If the required fix is only in esp_tinyusb, we can merge this PR and continue working on esp_tinyusb

Thanks for the review! All the CI build errors are caused by a single issue — the missing default value for TINYUSB_MSC_BUFSIZE on esp32s31 in esp_tinyusb/Kconfig. When the value is not set, CFG_TUD_MSC_EP_BUFSIZE expands to nothing, which causes the static assert, buffer declaration, and all subsequent references to _mscd_epbuf to fail.

I verified this locally by adding the appropriate default in esp_tinyusb/Kconfig, and the MSC example builds successfully for esp32s31 after that change.

Since the fix is only needed in esp_tinyusb, I agree we can merge this PR and address the Kconfig default separately.

@igi540 igi540 merged commit ab4a181 into release/v0.20 Apr 15, 2026
80 of 82 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants