TinyUSB

The tinyusb component implements a foundation for USB device functionality. It is currently supported on the following ESP32 microcontroller variants:

ESP32-H4
ESP32-P4
ESP32-S2
ESP32-S3
ESP32-S31

The component simply initializes the TinyUSB driver, allowing the microcontroller to act as a USB device when connected to a USB host.

NOTE

This component:

does not implement any specific device functionality; it is simply a foundation for other components to do so.
cannot be used with the Usb Host; operation as both a host and a device simultaneously is not possible.

# Example minimal configuration entry
tinyusb:

Configuration variables

id (Optional, ID): Manually specify the ID for this component.
usb_product_id (Optional, int): USB product identifier. Defaults to 0x4001.
usb_vendor_id (Optional, int): USB vendor identifier. Defaults to 0x303A (Espressif Systems).
usb_lang_id (Optional, int): USB language identifier. Defaults to 0x0409 (English - United States).
usb_manufacturer_str (Optional, string): Manufacturer string descriptor. Defaults to "ESPHome".
usb_product_str (Optional, string): Product name string descriptor. Defaults to "ESPHome".
usb_serial_str (Optional, string): Serial number string descriptor. If not specified, the device’s MAC address will be used.
vbus_monitor_pin (Optional, Pin): For a device that has its own power supply, the GPIO that senses the USB VBUS (5 V) line. Required for on_unmount to fire when the cable is unplugged; see Reacting to a USB host. Not available on the ESP32-S31.
on_mount (Optional, Automation): An automation to perform when a USB host has connected to the device and finished setting it up. See Reacting to a USB host.
on_unmount (Optional, Automation): An automation to perform when the USB host disconnects. See Reacting to a USB host.

Notes

Vendor and Product IDs

When specifying custom usb_vendor_id and usb_product_id values, be aware that:

USB Vendor IDs are officially assigned by the USB Implementers Forum (USB-IF).
Using unassigned or third-party vendor/product ID combinations may result in unexpected (host) behavior.
The default vendor ID 0x303A is assigned to Espressif Systems.
For hobbyist and development purposes, you may use test IDs, but these should not be used in production devices.

Language Identifiers

The usb_lang_id field uses USB Language IDs as defined by the USB specification. Common values include:

0x0409 - English (United States) - Default
0x0809 - English (United Kingdom)
0x0407 - German (Germany)
0x040C - French (France)

A more complete list can be found here.

Reacting to a USB Host

The on_mount and on_unmount automations run when a computer (or any other USB host) connects to the device and finishes setting it up, and when it disconnects again. A connection to a charger or a power-only cable does not count as a host, so these automations tell you whether something is actually able to talk to the device over USB. Both run on the main loop, so any action can be used.

tinyusb:
  on_mount:
    - logger.log: USB host connected
  on_unmount:
    - logger.log: USB host disconnected

When the Automations Run

on_mount runs when a host has finished setting the device up, which is the moment it can start talking to it:

A few hundred milliseconds after power-on when a computer is already attached. Use on_mount for this rather than checking tinyusb.is_mounted in on_boot, which runs too early.
When the cable is plugged into a running computer.

on_unmount runs when the USB controller learns that the host has gone. That happens in only two cases:

The host deliberately shuts the device down over USB. Computers rarely do this.
The controller sees the USB VBUS (5 V) line drop. This requires vbus_monitor_pin.

Nothing runs when:

The computer goes to sleep. As far as USB is concerned the host is still there, so this is correct.
The cable is unplugged from a device that has its own power supply and no vbus_monitor_pin. The controller only sees the bus go quiet, which looks the same as a sleeping computer, so it keeps reporting a connected host. Plugging the cable back in does not run on_mount either, because the controller never noticed the host leaving. tinyusb.is_mounted keeps returning true in this state as well.

IMPORTANT

If the device has its own power supply and needs to notice the cable being unplugged, connect VBUS to a GPIO through a suitable voltage divider and set vbus_monitor_pin.

A device powered only from its USB port does not have this problem. Unplugging the cable powers it off, and every power-on starts from a clean state: a computer runs on_mount shortly after boot, a charger never does. Such a device can tell the two apart with on_mount alone, without on_unmount or extra wiring.

`tinyusb.is_mounted` Condition

This condition passes while a USB host has the device connected and set up. It reflects what the USB controller knows, so on a device with its own power supply and no vbus_monitor_pin it stays true after the cable is unplugged.

id (Optional, ID): The ID of the tinyusb component. Only needed if you have given it an ID yourself.

on_...:
  - if:
      condition:
        tinyusb.is_mounted:
      then:
        - logger.log: A USB host is connected