mirror of
https://github.com/hathach/tinyusb.git
synced 2026-02-11 04:25:24 +00:00
more consolidation
This commit is contained in:
c1570
@ -1,11 +0,0 @@
|
||||
***********
|
||||
Explanation
|
||||
***********
|
||||
|
||||
Deep understanding of TinyUSB's design, architecture, and concepts.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
architecture
|
||||
usb_concepts
|
||||
@ -38,7 +38,7 @@ Run ``python tools/get_deps.py FAMILY`` where FAMILY is your MCU family (e.g., s
|
||||
|
||||
**Q: Can I use my own build system instead of Make/CMake?**
|
||||
|
||||
Yes, just add all ``.c`` files from ``src/`` to your project and configure include paths. See :doc:`tutorials/getting_started` for details.
|
||||
Yes, just add all ``.c`` files from ``src/`` to your project and configure include paths. See :doc:`getting_started` for details.
|
||||
|
||||
**Q: Error: "tusb_config.h: No such file or directory"**
|
||||
|
||||
|
||||
@ -13,11 +13,11 @@ To incorporate TinyUSB into your project:
|
||||
* Add all the ``.c`` files in the ``tinyusb/src`` folder to your project
|
||||
* Add ``your_project/tinyusb/src`` to your include path. Also ensure that your include path contains the configuration file ``tusb_config.h``.
|
||||
* Ensure all required macros are properly defined in ``tusb_config.h``. The configuration file from the demo applications provides a good starting point, but you'll need to add additional macros such as ``CFG_TUSB_MCU`` and ``CFG_TUSB_OS``. These are typically passed by make/cmake to maintain unique configurations for different boards.
|
||||
* If you're using the device stack, ensure you have created or modified USB descriptors to meet your specific requirements. Ultimately you need to implement all **tud descriptor** callbacks for the stack to work.
|
||||
* If you're using the **device stack**, you need to implement all **tud descriptor** callbacks for the stack to work.
|
||||
* Add a ``tusb_init(rhport, role)`` call to your reset initialization code.
|
||||
* Call ``tusb_int_handler(rhport, in_isr)`` from your USB IRQ handler
|
||||
* Implement all enabled classes' callbacks.
|
||||
* If you're not using an RTOS, you must call the ``tud_task()``/``tuh_task()`` functions continuously or periodically. These task functions handle all callbacks and core functionality.
|
||||
* If you're not using an RTOS, you must call the ``tud_task()``/``tuh_task()`` functions periodically. These task functions handle all callbacks and core functionality.
|
||||
|
||||
.. note::
|
||||
TinyUSB uses consistent naming prefixes: ``tud_`` for device stack functions and ``tuh_`` for host stack functions. See the :doc:`../reference/glossary` for more details.
|
||||
@ -29,6 +29,7 @@ To incorporate TinyUSB into your project:
|
||||
.role = TUSB_ROLE_DEVICE,
|
||||
.speed = TUSB_SPEED_AUTO
|
||||
};
|
||||
// tud descriptor omitted here
|
||||
tusb_init(0, &dev_init); // initialize device stack on roothub port 0
|
||||
|
||||
tusb_rhport_init_t host_init = {
|
||||
@ -67,7 +68,7 @@ Some ports require additional port-specific SDKs (e.g., for RP2040) or binaries
|
||||
Dependencies
|
||||
^^^^^^^^^^^^
|
||||
|
||||
TinyUSB separates example applications from board-specific hardware configurations. Example applications live in ``examples/device``, ``examples/host``, and ``examples/dual`` directories, while Board Support Package (BSP) configurations are stored in ``hw/bsp/FAMILY/boards/BOARD_NAME``. The BSP provides hardware abstraction including pin mappings, clock settings, linker scripts, and hardware initialization routines. For example, raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where ``FAMILY=rp2040`` and ``BOARD=raspberry_pi_pico``. When you build an example with ``BOARD=raspberry_pi_pico``, the build system automatically finds and uses the corresponding BSP.
|
||||
TinyUSB separates example applications from board-specific hardware configurations (Board Support Packages, BSP). Example applications live in ``examples/device``, ``examples/host``, and ``examples/dual`` directories, while BSP configurations are stored in ``hw/bsp/FAMILY/boards/BOARD_NAME``. The BSP provides hardware abstraction including pin mappings, clock settings, linker scripts, and hardware initialization routines. For example, raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where ``FAMILY=rp2040`` and ``BOARD=raspberry_pi_pico``. When you build an example with ``BOARD=raspberry_pi_pico``, the build system automatically finds and uses the corresponding BSP.
|
||||
|
||||
Before building, you must first download dependencies including MCU low-level peripheral drivers and external libraries such as FreeRTOS (required by some examples). You can do this in either of two ways:
|
||||
|
||||
@ -352,5 +353,5 @@ The ``cdc_msc_hid`` example creates a USB host that can connect to USB devices w
|
||||
Next Steps
|
||||
^^^^^^^^^^
|
||||
|
||||
* Check :doc:`../reference/boards` for board-specific information
|
||||
* Explore more :doc:`../examples` for advanced use cases
|
||||
* Check :doc:`reference/boards` for board-specific information
|
||||
* Explore more examples in ``examples/device/`` and ``examples/host/`` directories
|
||||
@ -18,10 +18,8 @@ TinyUSB provides a complete USB stack implementation supporting both device and
|
||||
|
||||
**Quick Navigation:**
|
||||
|
||||
* New to TinyUSB? Start with :doc:`tutorials/getting_started`
|
||||
* Need to solve a specific problem? Check :doc:`guides/index`
|
||||
* Looking for API details? See :doc:`reference/index`
|
||||
* Want to understand the design? Read :doc:`explanation/architecture`
|
||||
* New to TinyUSB? Start with :doc:`getting_started` and :doc:`reference/glossary`
|
||||
* Want to understand the design? Read :doc:`reference/architecture` and :doc:`reference/usb_concepts`
|
||||
* Having issues? Check :doc:`faq` and :doc:`troubleshooting`
|
||||
|
||||
Documentation Structure
|
||||
@ -31,12 +29,10 @@ Documentation Structure
|
||||
:maxdepth: 2
|
||||
:caption: Information
|
||||
|
||||
explanation/index
|
||||
tutorials/index
|
||||
guides/index
|
||||
reference/index
|
||||
getting_started
|
||||
faq
|
||||
troubleshooting
|
||||
reference/index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@ -239,11 +239,6 @@ Buffer Management
|
||||
- Size defined by ``CFG_TUD_*_RX/TX_BUFSIZE`` macros
|
||||
- Separate read/write pointers
|
||||
|
||||
**DMA Considerations**:
|
||||
- Buffers must be DMA-accessible on some MCUs
|
||||
- Alignment requirements vary by hardware
|
||||
- Cache coherency handled in portable drivers
|
||||
|
||||
Threading Model
|
||||
===============
|
||||
|
||||
@ -1,307 +0,0 @@
|
||||
*************
|
||||
Configuration
|
||||
*************
|
||||
|
||||
TinyUSB behavior is controlled through compile-time configuration in ``tusb_config.h``. This reference covers all available configuration options.
|
||||
|
||||
Basic Configuration
|
||||
===================
|
||||
|
||||
Required Settings
|
||||
-----------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Target MCU family - REQUIRED
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F4
|
||||
|
||||
// OS abstraction layer - REQUIRED
|
||||
#define CFG_TUSB_OS OPT_OS_NONE
|
||||
|
||||
// Enable device or host stack
|
||||
#define CFG_TUD_ENABLED 1 // Device stack
|
||||
#define CFG_TUH_ENABLED 1 // Host stack
|
||||
|
||||
Debug and Logging
|
||||
-----------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Debug level (0=off, 1=error, 2=warning, 3=info)
|
||||
#define CFG_TUSB_DEBUG 2
|
||||
|
||||
// Memory alignment for buffers (usually 4)
|
||||
#define CFG_TUSB_MEM_ALIGN __attribute__ ((aligned(4)))
|
||||
|
||||
Device Stack Configuration
|
||||
==========================
|
||||
|
||||
Endpoint Configuration
|
||||
----------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Control endpoint buffer size
|
||||
#define CFG_TUD_ENDPOINT0_SIZE 64
|
||||
|
||||
// Number of endpoints (excluding EP0)
|
||||
#define CFG_TUD_ENDPOINT_MAX 16
|
||||
|
||||
Device Classes
|
||||
--------------
|
||||
|
||||
**CDC (Communication Device Class)**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_CDC 1 // Number of CDC interfaces
|
||||
#define CFG_TUD_CDC_EP_BUFSIZE 512 // CDC endpoint buffer size
|
||||
#define CFG_TUD_CDC_RX_BUFSIZE 256 // CDC RX FIFO size
|
||||
#define CFG_TUD_CDC_TX_BUFSIZE 256 // CDC TX FIFO size
|
||||
|
||||
**HID (Human Interface Device)**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_HID 1 // Number of HID interfaces
|
||||
#define CFG_TUD_HID_EP_BUFSIZE 16 // HID endpoint buffer size
|
||||
|
||||
**MSC (Mass Storage Class)**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_MSC 1 // Number of MSC interfaces
|
||||
#define CFG_TUD_MSC_EP_BUFSIZE 512 // MSC endpoint buffer size
|
||||
|
||||
**Audio Class**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_AUDIO 1 // Number of audio interfaces
|
||||
#define CFG_TUD_AUDIO_FUNC_1_DESC_LEN 220
|
||||
#define CFG_TUD_AUDIO_FUNC_1_N_AS_INT 1
|
||||
#define CFG_TUD_AUDIO_FUNC_1_CTRL_BUF_SZ 64
|
||||
#define CFG_TUD_AUDIO_ENABLE_EP_IN 1
|
||||
#define CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX 2
|
||||
#define CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX 2
|
||||
|
||||
**MIDI**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_MIDI 1 // Number of MIDI interfaces
|
||||
#define CFG_TUD_MIDI_RX_BUFSIZE 128 // MIDI RX buffer size
|
||||
#define CFG_TUD_MIDI_TX_BUFSIZE 128 // MIDI TX buffer size
|
||||
|
||||
**DFU (Device Firmware Update)**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_DFU 1 // Enable DFU mode
|
||||
#define CFG_TUD_DFU_XFER_BUFSIZE 512 // DFU transfer buffer size
|
||||
|
||||
**Vendor Class**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUD_VENDOR 1 // Number of vendor interfaces
|
||||
#define CFG_TUD_VENDOR_EPSIZE 64 // Vendor endpoint size
|
||||
#define CFG_TUD_VENDOR_RX_BUFSIZE 64 // RX buffer size (0 = no buffering)
|
||||
#define CFG_TUD_VENDOR_TX_BUFSIZE 64 // TX buffer size (0 = no buffering)
|
||||
|
||||
.. note::
|
||||
Unlike other classes, vendor class supports setting buffer sizes to 0 to disable internal buffering. When disabled, data goes directly to ``tud_vendor_rx_cb()`` and the ``tud_vendor_read()``/``tud_vendor_write()`` functions are not available - applications must handle data directly in callbacks.
|
||||
|
||||
Host Stack Configuration
|
||||
========================
|
||||
|
||||
Port and Hub Configuration
|
||||
--------------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Number of host root hub ports
|
||||
#define CFG_TUH_HUB 1
|
||||
|
||||
// Number of connected devices (including hub)
|
||||
#define CFG_TUH_DEVICE_MAX 5
|
||||
|
||||
// Control transfer buffer size
|
||||
#define CFG_TUH_ENUMERATION_BUFSIZE 512
|
||||
|
||||
Host Classes
|
||||
------------
|
||||
|
||||
**CDC Host**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUH_CDC 2 // Number of CDC host instances
|
||||
#define CFG_TUH_CDC_FTDI 1 // FTDI serial support
|
||||
#define CFG_TUH_CDC_CP210X 1 // CP210x serial support
|
||||
#define CFG_TUH_CDC_CH34X 1 // CH34x serial support
|
||||
|
||||
**HID Host**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUH_HID 4 // Number of HID instances
|
||||
#define CFG_TUH_HID_EPIN_BUFSIZE 64 // HID endpoint buffer size
|
||||
#define CFG_TUH_HID_EPOUT_BUFSIZE 64
|
||||
|
||||
**MSC Host**:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUH_MSC 1 // Number of MSC instances
|
||||
#define CFG_TUH_MSC_MAXLUN 4 // Max LUNs per device
|
||||
|
||||
Advanced Configuration
|
||||
======================
|
||||
|
||||
Memory Management
|
||||
-----------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Enable stack protection
|
||||
#define CFG_TUSB_DEBUG_PRINTF printf
|
||||
|
||||
// Custom memory allocation (if needed)
|
||||
#define CFG_TUSB_MEM_SECTION __attribute__((section(".usb_ram")))
|
||||
|
||||
RTOS Configuration
|
||||
------------------
|
||||
|
||||
TinyUSB supports multiple operating systems through its OSAL (Operating System Abstraction Layer). Choose the appropriate configuration based on your target environment.
|
||||
|
||||
**FreeRTOS Integration**:
|
||||
|
||||
When using FreeRTOS, configure the task queue sizes to handle USB events efficiently:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUSB_OS OPT_OS_FREERTOS
|
||||
#define CFG_TUD_TASK_QUEUE_SZ 16 // Device task queue size
|
||||
#define CFG_TUH_TASK_QUEUE_SZ 16 // Host task queue size
|
||||
|
||||
**RT-Thread Integration**:
|
||||
|
||||
RT-Thread requires only the OS selection, as it uses the RTOS's built-in primitives:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUSB_OS OPT_OS_RTTHREAD
|
||||
|
||||
Low Power Configuration
|
||||
-----------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// Enable remote wakeup
|
||||
#define CFG_TUD_USBD_ENABLE_REMOTE_WAKEUP 1
|
||||
|
||||
// Suspend/resume callbacks
|
||||
// Implement tud_suspend_cb() and tud_resume_cb()
|
||||
|
||||
MCU-Specific Options
|
||||
====================
|
||||
|
||||
The ``CFG_TUSB_MCU`` option selects the target microcontroller family:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// STM32 families
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F0
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F1
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F4
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F7
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32H7
|
||||
|
||||
// NXP families
|
||||
#define CFG_TUSB_MCU OPT_MCU_LPC18XX
|
||||
#define CFG_TUSB_MCU OPT_MCU_LPC40XX
|
||||
#define CFG_TUSB_MCU OPT_MCU_LPC43XX
|
||||
#define CFG_TUSB_MCU OPT_MCU_KINETIS_KL
|
||||
#define CFG_TUSB_MCU OPT_MCU_IMXRT
|
||||
|
||||
// Other vendors
|
||||
#define CFG_TUSB_MCU OPT_MCU_RP2040
|
||||
#define CFG_TUSB_MCU OPT_MCU_ESP32S2
|
||||
#define CFG_TUSB_MCU OPT_MCU_ESP32S3
|
||||
#define CFG_TUSB_MCU OPT_MCU_SAMD21
|
||||
#define CFG_TUSB_MCU OPT_MCU_SAMD51
|
||||
#define CFG_TUSB_MCU OPT_MCU_NRF5X
|
||||
|
||||
Configuration Examples
|
||||
======================
|
||||
|
||||
Minimal Device (CDC only)
|
||||
--------------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F4
|
||||
#define CFG_TUSB_OS OPT_OS_NONE
|
||||
#define CFG_TUSB_DEBUG 0
|
||||
|
||||
#define CFG_TUD_ENABLED 1
|
||||
#define CFG_TUD_ENDPOINT0_SIZE 64
|
||||
|
||||
#define CFG_TUD_CDC 1
|
||||
#define CFG_TUD_CDC_EP_BUFSIZE 512
|
||||
#define CFG_TUD_CDC_RX_BUFSIZE 512
|
||||
#define CFG_TUD_CDC_TX_BUFSIZE 512
|
||||
|
||||
// Disable other classes
|
||||
#define CFG_TUD_HID 0
|
||||
#define CFG_TUD_MSC 0
|
||||
#define CFG_TUD_MIDI 0
|
||||
#define CFG_TUD_AUDIO 0
|
||||
#define CFG_TUD_VENDOR 0
|
||||
|
||||
Full-Featured Host
|
||||
------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define CFG_TUSB_MCU OPT_MCU_STM32F4
|
||||
#define CFG_TUSB_OS OPT_OS_FREERTOS
|
||||
#define CFG_TUSB_DEBUG 2
|
||||
|
||||
#define CFG_TUH_ENABLED 1
|
||||
#define CFG_TUH_HUB 1
|
||||
#define CFG_TUH_DEVICE_MAX 8
|
||||
#define CFG_TUH_ENUMERATION_BUFSIZE 512
|
||||
|
||||
#define CFG_TUH_CDC 2
|
||||
#define CFG_TUH_HID 4
|
||||
#define CFG_TUH_MSC 2
|
||||
#define CFG_TUH_VENDOR 2
|
||||
|
||||
Validation
|
||||
==========
|
||||
|
||||
Use these checks to validate your configuration:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// In your main.c, add compile-time checks
|
||||
#if !defined(CFG_TUSB_MCU) || (CFG_TUSB_MCU == OPT_MCU_NONE)
|
||||
#error "CFG_TUSB_MCU must be defined"
|
||||
#endif
|
||||
|
||||
#if CFG_TUD_ENABLED && !defined(CFG_TUD_ENDPOINT0_SIZE)
|
||||
#error "CFG_TUD_ENDPOINT0_SIZE must be defined for device stack"
|
||||
#endif
|
||||
|
||||
Common Configuration Issues
|
||||
===========================
|
||||
|
||||
1. **Endpoint buffer size too small**: Causes transfer failures
|
||||
2. **Missing CFG_TUSB_MCU**: Build will fail
|
||||
3. **Incorrect OS setting**: RTOS functions won't work properly
|
||||
4. **Insufficient endpoint count**: Device enumeration will fail
|
||||
5. **Buffer size mismatches**: Data corruption or transfer failures
|
||||
|
||||
For configuration examples specific to your board, check ``examples/device/*/tusb_config.h``.
|
||||
@ -7,9 +7,8 @@ Complete reference documentation for TinyUSB APIs, configuration, and supported
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api/index
|
||||
configuration
|
||||
usb_classes
|
||||
architecture
|
||||
usb_concepts
|
||||
boards
|
||||
dependencies
|
||||
concurrency
|
||||
|
||||
@ -1,287 +0,0 @@
|
||||
***********
|
||||
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
|
||||
@ -30,7 +30,7 @@ Host and Device Roles
|
||||
- Manages the USB bus
|
||||
- Enumerates and configures devices
|
||||
|
||||
**TinyUSB Host Stack**: Enable with ``CFG_TUH_ENABLED=1`` in ``tusb_config.h``. Call ``tuh_task()`` regularly in your main loop. See the :doc:`../tutorials/getting_started` Quick Start Examples for implementation details.
|
||||
**TinyUSB Host Stack**: Enable with ``CFG_TUH_ENABLED=1`` in ``tusb_config.h``. Call ``tuh_task()`` regularly in your main loop. See the :doc:`../getting_started` Quick Start Examples for implementation details.
|
||||
|
||||
**USB Device**: The peripheral side (keyboard, mouse, storage device, etc.). Devices:
|
||||
- Respond to host requests
|
||||
@ -38,7 +38,7 @@ Host and Device Roles
|
||||
- Receive power from the host
|
||||
- Must be enumerated by the host before use
|
||||
|
||||
**TinyUSB Device Stack**: Enable with ``CFG_TUD_ENABLED=1`` in ``tusb_config.h``. Call ``tud_task()`` regularly in your main loop. See the :doc:`../tutorials/getting_started` Quick Start Examples for implementation details.
|
||||
**TinyUSB Device Stack**: Enable with ``CFG_TUD_ENABLED=1`` in ``tusb_config.h``. Call ``tud_task()`` regularly in your main loop. See the :doc:`../getting_started` Quick Start Examples for implementation details.
|
||||
|
||||
**OTG (On-The-Go)**: Some devices can switch between host and device roles dynamically. **TinyUSB Support**: Both stacks can be enabled simultaneously on OTG-capable hardware. See ``examples/dual/`` for dual-role implementations.
|
||||
|
||||
@ -226,7 +226,10 @@ USB classes define standardized protocols for device types:
|
||||
- **DFU**: Device Firmware Update - Enable with ``CFG_TUD_DFU``
|
||||
- **Vendor**: Custom vendor classes - Enable with ``CFG_TUD_VENDOR``
|
||||
|
||||
See :doc:`../reference/usb_classes` for detailed class information and :doc:`../reference/configuration` for configuration options.
|
||||
.. note::
|
||||
**Vendor Class Buffer Configuration**: Unlike other USB classes, the vendor class supports setting buffer sizes to 0 in ``tusb_config.h`` (``CFG_TUD_VENDOR_RX_BUFSIZE = 0``) to disable internal buffering. When disabled, data goes directly to ``tud_vendor_rx_cb()`` and the ``tud_vendor_read()``/``tud_vendor_write()`` functions are not available - applications must handle data directly in callbacks.
|
||||
|
||||
See ``examples/device/*/tusb_config.h`` for configuration examples.
|
||||
|
||||
USB Speeds
|
||||
==========
|
||||
@ -420,6 +423,6 @@ USB provides power to devices:
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
- Start with :doc:`../tutorials/getting_started` for basic setup
|
||||
- Review :doc:`../reference/configuration` for configuration options
|
||||
- Explore :doc:`../examples` for advanced use cases
|
||||
- Start with :doc:`../getting_started` for basic setup
|
||||
- Review ``examples/device/*/tusb_config.h`` for configuration examples
|
||||
- Explore examples in ``examples/device/`` and ``examples/host/`` directories
|
||||
@ -1,10 +0,0 @@
|
||||
*********
|
||||
Tutorials
|
||||
*********
|
||||
|
||||
Step-by-step learning guides for TinyUSB development.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
getting_started
|
||||
Reference in New Issue
Block a user