Skip to content

Latest commit

 

History

History
132 lines (81 loc) · 3.82 KB

README.rst

File metadata and controls

132 lines (81 loc) · 3.82 KB
Raw

USB

Sming library for TinyUSB.

Note that TinyUSB uses a large number of configuration variables and callback functions, so is compiled and linked directly with the application rather than as a separate library.

Device stack

The TinyUSB example applications generally consist of these three things:

tusb_config.h
Contains definitions such as which classes are supported, how many endpoints (each), buffer sizes, etc.
usb_descriptors.c
Provides descriptor/report structure definitions, interface and endpoint assignments and string definitions, with callback function implementations to provide these to the TinyUSB stack.
main.c and other translation units
Implements class-specific callbacks.

Applications may choose to use the raw TinyUSB API; this is demonstrated in the :sample:`HID_Composite_Device` sample. A drawback of this approach is that the configuration files have to be composed manually, which requires some knowledge of TinyUSB and can also be error-prone.

Instead, the configuration can be described in a JSON file and the configuration generated by the library. The format of this file is defined in :source:`schema.json`. For vscode, the .usbcfg file extension is association with this schema by make ide-vscode. This enables use of auto-completion in the editor. See :doc:`/tools/vscode`.

This approach is demonstrated in the :sample:`Basic_Device` sample. In the application component.mk file, set :envvar:`USB_CONFIG` to the name of the configuration file. The configuration will be validated and configuration files generated in, for example, out/Rp2040/debug/USB.

Device classes

C++ Device implementations are provided for some of the standard interfaces. Use is demonstrated in the :sample:`Basic_Device` sample.

CDC

Communications Device Class. :cpp:class:`USB::CDC::Device`.

TinyUSB implements only the ACM modes which apparently have issues with Windows. Appears in linux as /dev/ttyACM0, etc.

DFU
Device Firmware Update. :cpp:class:`USB::DFU::Device`. Use the linux dfu-util tool to test.
ECM_RNDIS and NCM

https://en.wikipedia.org/wiki/Ethernet_over_USB

Not yet implemented. :cpp:class:`USB::ECM_RNDIS::Device` and :cpp:class:`USB::NCM::Device`.

HID
Human Interface Device. :cpp:class:`USB::HID::Device`.
MIDI
Musical Instrument Digital Interface (over USB). :cpp:class:`USB::MIDI::Device`.
MSC
Mass Storage Class. :cpp:class:`USB::MSC::Device`.
VENDOR
Devices are identifed by VID:PID and require appropriate host driver. :cpp:class:`USB::VENDOR::Device`. TinyUSB implements a simple read/write interface for this class. This is implemented like a serial port to allow asynchronous streaming, etc.

Host stack

See :sample:`Basic_Host` for an example.

Note

At present, there is no host support for Esp32. Samples will build for Rp2040 only.

HUB
When connected to a hub (or multiple hubs) this must be defined in the configuration.
HID
:cpp:class:`USB::HID::HostDevice`
CDC
:cpp:class:`USB::CDC::HostDevice`
MSC
Allows attachment of USB storage. :cpp:class:`USB::MSC::HostDevice` See :sample:`Basic_IFS` for a real-world example.
VENDOR
Support access to custom devices. :cpp:class:`USB::MSC::HostDevice`. The sample contains a demonstration for connecting an original XBOX-360 joypad controller.

Configuration variables

.. envvar:: USB_DEBUG_LEVEL

    default: 0 (disable)

    Set to a value from 1-3 to enable debug output messages from the TinyUSB stack.



.. envvar:: USB_CONFIG

    default: undefined

    This identifies the name of the JSON USB configuration file for the application.
    This allows the TinyUSB configuration data to be generated rather than written manually.

API

.. doxygennamespace:: USB
   :members: