fix(esp_tinyusb): VBUS monitoring feature on ESP32-P4, USB OTG 2.0 v4.30a [WIP] (IEC-435)

[roma-jam]

Description

Added the vbus monitor state change callback to vbus_monitor module.
This callback is used to workaround the absence of UNPLUG event in tinyusb, because:

• On the USB OTG 2.0 v4.30a, VBUSVALID, SRP_BVALID, SESSEND: these signals are not available
• USB_SRP_BVALID_IN_IDX cannot be connected to GPIO via matrix

Thus, based on the VBUS IO state (in our case only relevant for DETACHED event), we notify the upper layer.

Limitation

• As the storage mount/umount logic is handled in the FreeRTOS timer task context (Tmr SVC), the stack size should be not less then 2304 (2048 + 256) Bytes (Measured manually, as it is not working with 2048 default size. Starts to work at 2100, but I added 256 bytes in advance).

Related

• Prerequisites in feature(tinyusb): Software VBUS monitoring feature on ESP32P4 (part2/2) [WIP] (IEC-436) #307

Testing

Verified local test vbus_monitor (all scenarios) on:

• ESP32-S3, USB OTG 1.1 (Limitation: No stable suspend event on test 3 before device detachment)
• ESP32-P4 ECO4, USB OTG 1.1
• ESP32-P4 ECO4, USB OTG 2.0 (Limitation: Several parasite SUSPEND events on test 7)
• ESP32-P4 ECO5, USB OTG 1.1
• ESP32-P4 ECO5, USB OTG 2.0 (Limitation: One parasite SUSPEND event on any test before device attach IEC-412)

Additional testing

• [ECO5] Local run for esp-idf example esp-idf/examples/peripherals/usb/device/tusb_msc with self_powered flag (device attached/detached by the power button on the external hub, connected to the Laptop)

• [ECO4] Local run for esp-idf example esp-idf/examples/peripherals/usb/device/tusb_msc with self_powered flag (device attached/detached by the power button on the external hub, connected to the Laptop)

---

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

[Copilot]

Pull Request Overview

This PR implements a workaround for VBUS monitoring on ESP32-P4 ECO5 (USB OTG 2.0 v4.30a), where hardware-based BValid override is not available. The solution introduces conditional compilation to handle different chip revisions and uses direct application layer notification as a fallback mechanism.

Key Changes:

• Added conditional support for BValid override based on ESP32-P4 chip revision
• Implemented workaround using tinyusb_device_detached() for newer revisions lacking hardware support
• Refactored TinyUSB callbacks to use new attach/detach notification functions

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
device/esp_tinyusb/tinyusb_vbus_monitor.c	Added conditional compilation for BValid override support and workaround for ECO5
device/esp_tinyusb/tinyusb.c	Refactored mount/unmount callbacks to use new attach/detach notification functions
device/esp_tinyusb/test_apps/vbus_monitor/main/test_vbus_monitor.c	Updated test to handle suspend events during attach/detach sequences
device/esp_tinyusb/include_private/tinyusb_vbus_monitor.h	Updated documentation for init function error codes
device/esp_tinyusb/include_private/tinyusb_device.h	New header declaring device detach notification function

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[roma-jam]

Hi
@tore-espressif
@peter-marcisovsky
@igi540

this one is ready, PTAL.

[tore-espressif]

As the storage mount/umount logic is handled in the FreeRTOS timer task context (Tmr SVC), the stack size should be not less then 2304 (2048 + 256) Bytes (Measured manually, as it is not working with 2048 default size. Starts to work at 2100, but I added 256 bytes in advance).

This is currently blocking limitation. If our implementation creates stack overflow in any system task, we should defer the handling to our tinyusb task.

Is it possible to signal the unplug event with dcd_event_bus_signal(port, DCD_EVENT_UNPLUGGED, false);? If yes, the DCD layer would propagate all callback to our tinyusb task

[roma-jam]

Hi @tore-espressif,

this can be a blocking limitation for the release, but it is not blocking limitation for this PR.
This PR enables the mechanism of VBUS monitoring feature on the ECO5.

Resolve the limitation we can easily by moving the vbus monitor callback, added in this PR, to the dedicated task context.

This will take couple of lines and break the limitation easily. But for this, we need to move from the blocking tud_task() to non-blocking tud_task_ext().

Alternatives already were considered, such as:

• Dedicated task for VBUS monitor feature only (rejected). As we don't need a separate task for such simple feature.
• Using esp_timer instead of FreeRTOS timer as it has it's own dedicated task for the timer callback. (already discussed, rejected). This adds the additional task and also a dependency from esp_timer component.

As the feature with non-blocking tusb_task_ext() is still not reviewed, there is no other way right now to enable the VBUS monitoring for ECO5 in any other way.

So we can enable the feature with limitation to have it working on ECO5 and then (after moving to non-blocking tusb_task_ext()) remove this limitation with the simple follow-up PR.