path: root/docs/reference/usb_classes.rst

***********
USB Classes
***********

TinyUSB supports multiple USB device and host classes. This reference describes the features, capabilities, and requirements for each class.

Device Classes
==============

CDC (Communication Device Class)
--------------------------------

Implements USB CDC specification for serial communication.

**Supported Features:**
- CDC-ACM (Abstract Control Model) for virtual serial ports
- Data terminal ready (DTR) and request to send (RTS) control lines
- Line coding configuration (baud rate, parity, stop bits)
- Break signal support

**Configuration:**
- ``CFG_TUD_CDC``: Number of CDC interfaces (1-4)
- ``CFG_TUD_CDC_EP_BUFSIZE``: Endpoint buffer size (typically 512)
- ``CFG_TUD_CDC_RX_BUFSIZE``: Receive FIFO size
- ``CFG_TUD_CDC_TX_BUFSIZE``: Transmit FIFO size

**Key Functions:**
- ``tud_cdc_available()``: Check bytes available to read
- ``tud_cdc_read()``: Read data from host
- ``tud_cdc_write()``: Write data to host
- ``tud_cdc_write_flush()``: Flush transmit buffer

**Callbacks:**
- ``tud_cdc_line_coding_cb()``: Line coding changed
- ``tud_cdc_line_state_cb()``: DTR/RTS state changed

HID (Human Interface Device)
----------------------------

Implements USB HID specification for input devices.

**Supported Features:**
- Boot protocol (keyboard/mouse)
- Report protocol with custom descriptors
- Input, output, and feature reports
- Multiple HID interfaces

**Configuration:**
- ``CFG_TUD_HID``: Number of HID interfaces
- ``CFG_TUD_HID_EP_BUFSIZE``: Endpoint buffer size

**Key Functions:**
- ``tud_hid_ready()``: Check if ready to send report
- ``tud_hid_report()``: Send HID report
- ``tud_hid_keyboard_report()``: Send keyboard report
- ``tud_hid_mouse_report()``: Send mouse report

**Callbacks:**
- ``tud_hid_descriptor_report_cb()``: Provide report descriptor
- ``tud_hid_get_report_cb()``: Handle get report request
- ``tud_hid_set_report_cb()``: Handle set report request

MSC (Mass Storage Class)
------------------------

Implements USB mass storage for file systems.

**Supported Features:**
- SCSI transparent command set
- Multiple logical units (LUNs)
- Read/write operations
- Inquiry and capacity commands

**Configuration:**
- ``CFG_TUD_MSC``: Number of MSC interfaces
- ``CFG_TUD_MSC_EP_BUFSIZE``: Endpoint buffer size

**Key Functions:**
- Storage operations handled via callbacks

**Required Callbacks:**
- ``tud_msc_inquiry_cb()``: Device inquiry information
- ``tud_msc_test_unit_ready_cb()``: Test if LUN is ready
- ``tud_msc_capacity_cb()``: Get LUN capacity
- ``tud_msc_start_stop_cb()``: Start/stop LUN
- ``tud_msc_read10_cb()``: Read data from LUN
- ``tud_msc_write10_cb()``: Write data to LUN

Audio Class
-----------

Implements USB Audio Class 2.0 specification.

**Supported Features:**
- Audio streaming (input/output)
- Multiple sampling rates
- Volume and mute controls
- Feedback endpoints for asynchronous mode

**Configuration:**
- ``CFG_TUD_AUDIO``: Number of audio functions
- Multiple configuration options for channels, sample rates, bit depth

**Key Functions:**
- ``tud_audio_read()``: Read audio data
- ``tud_audio_write()``: Write audio data
- ``tud_audio_clear_ep_out_ff()``: Clear output FIFO

MIDI
----

Implements USB MIDI specification.

**Supported Features:**
- MIDI 1.0 message format
- Multiple virtual MIDI cables
- Standard MIDI messages

**Configuration:**
- ``CFG_TUD_MIDI``: Number of MIDI interfaces
- ``CFG_TUD_MIDI_RX_BUFSIZE``: Receive buffer size
- ``CFG_TUD_MIDI_TX_BUFSIZE``: Transmit buffer size

**Key Functions:**
- ``tud_midi_available()``: Check available MIDI messages
- ``tud_midi_read()``: Read MIDI packet
- ``tud_midi_write()``: Send MIDI packet

DFU (Device Firmware Update)
----------------------------

Implements USB DFU specification for firmware updates.

**Supported Modes:**
- DFU Mode: Device enters DFU for firmware update
- DFU Runtime: Request transition to DFU mode

**Configuration:**
- ``CFG_TUD_DFU``: Enable DFU mode
- ``CFG_TUD_DFU_RUNTIME``: Enable DFU runtime

**Key Functions:**
- Firmware update operations handled via callbacks

**Required Callbacks:**
- ``tud_dfu_download_cb()``: Receive firmware data
- ``tud_dfu_manifest_cb()``: Complete firmware update

Vendor Class
------------

Custom vendor-specific USB class implementation.

**Features:**
- Configurable endpoints
- Custom protocol implementation
- WebUSB support
- Microsoft OS descriptors

**Configuration:**
- ``CFG_TUD_VENDOR``: Number of vendor interfaces
- ``CFG_TUD_VENDOR_EPSIZE``: Endpoint size

**Key Functions:**
- ``tud_vendor_available()``: Check available data
- ``tud_vendor_read()``: Read vendor data
- ``tud_vendor_write()``: Write vendor data

Host Classes
============

CDC Host
--------

Connect to CDC devices (virtual serial ports).

**Supported Devices:**
- CDC-ACM devices
- FTDI USB-to-serial converters
- CP210x USB-to-serial converters
- CH34x USB-to-serial converters

**Configuration:**
- ``CFG_TUH_CDC``: Number of CDC host instances
- ``CFG_TUH_CDC_FTDI``: Enable FTDI support
- ``CFG_TUH_CDC_CP210X``: Enable CP210x support

**Key Functions:**
- ``tuh_cdc_available()``: Check available data
- ``tuh_cdc_read()``: Read from CDC device
- ``tuh_cdc_write()``: Write to CDC device
- ``tuh_cdc_set_baudrate()``: Configure serial settings

HID Host
--------

Connect to HID devices (keyboards, mice, etc.).

**Supported Devices:**
- Boot keyboards and mice
- Generic HID devices with report descriptors
- Composite HID devices

**Configuration:**
- ``CFG_TUH_HID``: Number of HID host instances
- ``CFG_TUH_HID_EPIN_BUFSIZE``: Input endpoint buffer size

**Key Functions:**
- ``tuh_hid_receive_report()``: Start receiving reports
- ``tuh_hid_send_report()``: Send report to device
- ``tuh_hid_parse_report_descriptor()``: Parse HID descriptors

MSC Host
--------

Connect to mass storage devices (USB drives).

**Supported Features:**
- SCSI transparent command set
- FAT file system support (with FatFS integration)
- Multiple LUNs per device

**Configuration:**
- ``CFG_TUH_MSC``: Number of MSC host instances
- ``CFG_TUH_MSC_MAXLUN``: Maximum LUNs per device

**Key Functions:**
- ``tuh_msc_ready()``: Check if device is ready
- ``tuh_msc_read10()``: Read sectors from device
- ``tuh_msc_write10()``: Write sectors to device

Hub
---

Support for USB hubs to connect multiple devices.

**Features:**
- Multi-level hub support
- Port power management
- Device connect/disconnect detection

**Configuration:**
- ``CFG_TUH_HUB``: Number of hub instances
- ``CFG_TUH_DEVICE_MAX``: Total connected devices

Class Implementation Guidelines
===============================

Descriptor Requirements
-----------------------

Each USB class requires specific descriptors:

1. **Interface Descriptor**: Defines the class type
2. **Endpoint Descriptors**: Define communication endpoints
3. **Class-Specific Descriptors**: Additional class requirements
4. **String Descriptors**: Human-readable device information

Callback Implementation
-----------------------

Most classes require callback functions:

- **Mandatory callbacks**: Must be implemented for class to function
- **Optional callbacks**: Provide additional functionality
- **Event callbacks**: Called when specific events occur

Performance Considerations
--------------------------

When implementing USB classes, match **buffer sizes** to expected data rates to avoid bottlenecks. Choose appropriate **transfer types** based on your application's requirements. Keep **callback processing** lightweight for optimal performance. Avoid **memory allocations in critical paths** where possible to maintain consistent performance.

Testing and Validation
----------------------

- **USB-IF Compliance**: Ensure descriptors meet USB standards
- **Host Compatibility**: Test with multiple operating systems
- **Performance Testing**: Verify transfer rates and latency
- **Error Handling**: Test disconnect/reconnect scenarios

Class-Specific Resources
========================

- **USB-IF Specifications**: Official USB class specifications
- **Example Code**: Reference implementations in ``examples/`` directory
- **Test Applications**: Host-side test applications for validation
- **Debugging Tools**: USB protocol analyzers and debugging utilities