feature(tinyusb): Software VBUS monitoring feature

[roma-jam]

Description

ESP32S2/S3 - USB OTG 1.1

Handled via USB PHY.

USB OTG signals are connected to the GPIO matrix and we can connect GPIO signal from VBUS monitoring pin directly to Bvalid session signal.

ESP32P4 - USB OTG 1.1

Handled via USB PHY.

USB OTG signals are connected to the GPIO matrix and we can connect GPIO signal from VBUS monitoring pin directly to Bvalid session signal.

ESP32P4 - USB OTG 2.0

USB OTG signals for DWC OTG 2.0 are not connected, so we need another mechanism to control the Bvalid session signal.

The controller provides an option to override Bvalid value via GOTGCTL register.

To workaround absence of signal mapping, the combination of GPIO level detection via IRQ and changing the Bvalid value in the tinyusb driver are being proposed.

When TinyUSB is configured on HS port, the VBUS monitoring logic can be enabled by setting the self_powered flag.
The logic detects the VBUS monitor pin state change and override the Bvalid value via register, causing the USB DWC controller to change the state of B-peripheral session.

Limitation

Overriding the Bvalid value via GOTGCTL register from the application works differently for USB OTG 1.1 and USB OTG 2.0.

On 2.0, when we override the value via GOTGCTL register, the device is staying connected to the USB Host and we need disable the D+ pull-up register additionally (via DCTL register).

On 1.1 the last step isn't necessary (test cases "Emulated" and "Controlled").

Refer to TODO: Verify, why device staying connected after setting value to 0 and why signaling works differently

Related

• Closes IDF-10720

Follow-up

• Make debounce delay for VBUS state change detection runtime configurable via tinyusb_config_t (now default 500ms, not critical)
• Add dependency for ATTR_SELF_POWERED in device descriptor (right now, there are now verification if the config is set with self_powered = true but device descriptor doesn't have the attribute, not critical).

Testing

ESP32S2/S3

(1)	"Emulated VBUS, verify attach/detach events callback (via Bvalid signal)" [ci][dconn]
(2)	"Controlled VBUS, verify attach/detach events callback" [dconn]
(3)	"Real VBUS, verify attach/detach events callback (requires manual handling)" [dconn]

ESP32P4

(1)	"Emulated VBUS USB OTG 1.1, verify attach/detach events callback (via Bvalid signal)" [dconn]
(2)	"Emulated VBUS USB OTG 1.1, verify attach/detach events callback (via GOTGCTL register)" [dconn]
(3)	"Emulated VBUS USB OTG 2.0, verify attach/detach events callback (via GOTGCTL register)" [ci][dconn]
(4)	"Controlled VBUS USB OTG 1.1, verify attach/detach events callback" [dconn]
(5)	"Controlled VBUS USB OTG 2.0, verify attach/detach events callback" [dconn]
(6)	"Real VBUS USB OTG 1.1, verify attach/detach events callback (requires manual handling)" [dconn]
(7)	"Real VBUS USB OTG 2.0, verify attach/detach events callback (requires manual handling)" [dconn]

Approach selection

Approach	Advantages	Disadvantages	Comment
GPIO Glitch Filter	No additional task required	HW filter only isn't enough	The IRQ is still happeneing, even if 1uF capasitor is applied (as in ESP32P4 dev board, circuit USB2_5V). I was able to achieve this, just moving the USB connection in the host port.
Debounce timer: esp_timer	Lower jitter	Runs in a dedicated high-priority ESP timer task	Additional task, requires esp_timer dependency
Debounce timer: FreeRTOS	Runs in the FreeRTOS timer service task	more jitter under load	Less memory usage, appropriate jitter, simplicity

Desired solution: FreeRTOS timer without HW Glitch Filter. All parasitic glitches are handled in the software.

---

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 software VBUS monitoring functionality for TinyUSB across different ESP32 variants. The feature addresses hardware limitations in ESP32P4's USB OTG 2.0 controller where USB OTG signals are not connected to the GPIO matrix.

• Added VBUS monitoring logic with GPIO-based detection and debouncing
• Introduced BVALID signal override mechanism for ESP32P4 USB OTG 2.0
• Created comprehensive test suite covering different scenarios and target platforms

Reviewed Changes

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

Show a summary per file

File	Description
tinyusb_vbus_monitor.c	Core VBUS monitoring implementation with GPIO interrupt handling and debouncing
tinyusb.c	Integration of VBUS monitoring into driver install/uninstall flows
tinyusb_task.c	Task-level enablement of VBUS monitoring
test files	Comprehensive test coverage for VBUS monitoring functionality
CMakeLists.txt	Build configuration updates for new components

Comments suppressed due to low confidence (1)

device/esp_tinyusb/tinyusb_vbus_monitor.c:1

• Duplicate comment on lines 156 and 158. One should be removed or made more specific.

/*

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

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

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[roma-jam]

Hi @leeebo,

I would be happy, if you or someone from your team could check this changes as well.

Please, note the Limitation section in the PR description and my comment to the test_vbus_monitor.c file.

[tore-espressif]

we need disable the D+ pull-up register additionally (via DCTL register).

Is this already implemented in the code?

It would be great if we could avoid using the esp_timer for debouncing. Could you check if P4's glitch filter could help us here? Chapter 8.4.4 https://www.espressif.com/sites/default/files/documentation/esp32-p4_technical_reference_manual_en.pdf

I'll check with others whether there are other ways of doing this

[roma-jam]

@tore-espressif

Is this already implemented in the code?

Yes, I added these lines to the test application for behavior to be the same on S2/S3 and P4.
But I didn't do it in the driver, so there is no breaking change.

It would be great if we could avoid using the esp_timer for debouncing.
It might be replaced by the FreeRTOS basic timer. And we can omit the dependency from esp_timer with this.

Anyway, we will have one in the USB Host library (for suspend/wakeup), why not to have it in the device stack as well (for software VBUS detection).

UPD:

Could you check if P4's glitch filter could help us here?

Based on the info from ref manual, it might be the option. I'll check.

[leeebo]

Hi @roma-jam , this detection logic LGTM!

[roma-jam]

Thanks to everyone who is already reviewed the code - I considered all notes.

To simplify the reviewing process the feature the rollout plan for this feature has been split into two steps:
PR 1 - VBUS monitor API + test application (enable CI for esp32s2) + Docs
PR 2 - VBUS monitor logic + test application (enable CI for esp32p4)

This PR will be closed. Please, refer the following:

1. feature(tinyusb): Software VBUS monitoring feature on ESP32P4 (part1/2) #305