modm API documentation
Modules
TinyUSB

Modules

 TinyUSB in Device Mode
 
 TinyUSB in Host Mode
 

Detailed Description

lbuild module: modm:tinyusb

TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function.

This module provides a autogenerated port for TinyUSB, which includes the correct interrupt mapping, a serial number based on the UID of the device, as well as remapping the assertions of TinyUSB.

Full vs High Speed Ports

Some microcontroller have USB peripherals capable of using external high speed transceivers via an ULPI interface. TinyUSB can be configured to run device and host classes on one port or both on separate ports at the same time. You can configure this via these module options:

<option name="modm:tinyusb:device:port">fs</option>
<option name="modm:tinyusb:host:port">hs</option>

However, the high speed capable port can also run in full speed mode, in which case you must configure TinyUSB to not use the ULPI interface:

<option name="modm:tinyusb:max-speed">full</option>

Initializing USB

The modm:platform:usb module provides the correct way of initializing the USB peripheral, however, you must connect the right signals too:

// USB is timing-sensitive, so prioritize the IRQs accordingly
Usb::initialize<SystemClock>(/*priority=*/3);
// For Device-Only USB implementations, this is enough
Usb::connect<GpioA11::Dm, GpioA12::Dp>();
// But for On-The-Go (OTG) USB implementations, you need more:
Usb::connect<GpioA11::Dm, GpioA12::Dp, GpioA10::Id>();
// For high speed USB ports, you need to connect all ULPI signals:
UsbHs::connect<
GpioA5::Ulpick, GpioC0::Ulpistp, GpioC2::Ulpidir, GpioH4::Ulpinxt,
GpioA3::Ulpid0, GpioB0::Ulpid1, GpioB1::Ulpid2, GpioB10::Ulpid3,
GpioB11::Ulpid4, GpioB12::Ulpid5, GpioB13::Ulpid6, GpioB5::Ulpid7>();

Note that depending on your specific hardware setup, you may need to fiddle around to find the right VBus sensing mechanism. Please look at the TinyUSB board definitions and examples for inspiration.

// Enable hardware Vbus sensing on GpioA9 (this can be tricky to get right!)
USB_OTG_FS->GCCFG |= USB_OTG_GCCFG_VBDEN;
Warning
USB shares resources with CAN Note that on STM32F1 and STM32F3 the USB interrupts and RAM are shared with CAN, thus there are conflicts in IRQ definitions as well as resource limitions in hardware. On some STM32F3, the USB IRQs can be remapped, this is done automatically by our port.

Autogeneration of USB Descriptors

You can select the device classes you want to use via the modm:tinyusb:config list option:

Note that you can add multiple devices at the same time, as long as there are enough endpoints and USB RAM available:

<!-- Using the CDC and MSC classes together -->
<option name="modm:tinyusb:config">device.cdc,device.msc</option>
<!-- Using two CDC ports! -->
<option name="modm:tinyusb:config">device.cdc,device.cdc</option>

modm will generate the USB descriptors automatically for the set of device classes you've chosen. You can then implement your app via TinyUSB callbacks.

Partial Customization

You can overwrite or add configurations via a <tusb_config_local.h> file, which will be included at the very beginning of the modm-generated tusb_config.h file:

// Overwrite the modm default
#define CFG_TUD_CDC_TX_BUFSIZE 1024
// Overwrite the TinyUSB default
#define CFG_TUD_CDC_EP_BUFSIZE 1024

You can also replace the following weakly linked descriptor functions and objects in case you want to update only a small part of the autogenerated descriptors:

Manual USB Descriptors

If you leave the modm:tinyusb:config option empty, no descriptors are generated, so you can implement them yourself. Note that you must also manually depend on the device classes you want to implement:

<module>modm:tinyusb:device:audio</module>
<module>modm:tinyusb:device:bth</module>
<module>modm:tinyusb:device:cdc</module>
<module>modm:tinyusb:device:dfu</module>
<module>modm:tinyusb:device:dfu_rt</module>
<module>modm:tinyusb:device:ecm_rndis</module>
<module>modm:tinyusb:device:hid</module>
<module>modm:tinyusb:device:midi</module>
<module>modm:tinyusb:device:msc</module>
<module>modm:tinyusb:device:ncm</module>
<module>modm:tinyusb:device:usbtmc</module>
<module>modm:tinyusb:device:vendor</module>
<module>modm:tinyusb:device:video</module>

Some of these classes require a lot of configuration that you must provide via the <tusb_config_local.h> file. Please consult the TinyUSB documentation and examples for their purpose.

Host classes

To use the host classes you must depend on them manually as modm does not provide a configuration option for them:

<module>modm:tinyusb:host:cdc</module>
<module>modm:tinyusb:host:cdc_rndis</module>
<module>modm:tinyusb:host:hid</module>
<module>modm:tinyusb:host:msc</module>
<module>modm:tinyusb:host:vendor</module>

Debugging TinyUSB

Since we've made it so easy to add multiple device classes, it's also easy to run out of endpoints or RAM. Therefore we reroute TinyUSBs assertions to modm_assert, so make sure you have implemented the modm_abandon handler! See the modm:architecture:assert module for details.

A TinyUSB assertion failure in release mode is fairly cryptic:

Assertion 'tu' failed!
Abandoning...

If you run this again in debug mode, you'll note a much more detailed assertion description. In this example you've exhaused the number of endpoints:

Assertion 'tu' failed!
modm/ext/tinyusb/portable/st/synopsys/dcd_synopsys.c:524 -> "epnum < 4U"
Abandoning...

To trace the TinyUSB core, you can add CFG_TUSB_DEBUG=3 to your CPP flags and the output will be forwarded to MODM_LOG_DEBUG.

<collect name="modm:build:cppdefines">CFG_TUSB_DEBUG=3</collect>

Module Options

modm:tinyusb:config: Endpoint Configuration

Generated with: [] in [device.cdc, device.dfu_rt, device.midi, device.msc, device.vendor]

modm:tinyusb:max-speed: Maximum HS port speed

Generated with: high in [full, high]