docs/integration.rst

*******************
Integrating TinyUSB
*******************

Once you've seen TinyUSB working in the examples, use this guide to wire the stack into your own firmware.

Integration Steps
=================

1. **Get TinyUSB**: Copy this repository or add it as a git submodule to your project at ``your_project/tinyusb``.
2. **Add source files**: Add every ``.c`` file from ``tinyusb/src/`` to your project build system.

.. note::
   Only supported dcd/hcd drivers for your CPU sources under ``tinyusb/src/portable/vendor/usbip/`` are needed. Add

3. **Configure TinyUSB**: Create ``tusb_config.h`` with macros such as ``CFG_TUSB_MCU``, ``CFG_TUSB_OS``, and class enable flags. Start from any example's ``tusb_config.h`` and tweak.
4. **Configure include paths**: Add ``your_project/tinyusb/src`` (and the folder holding ``tusb_config.h``) to your include paths.
5. **Implement USB descriptors**: For device stack, implement the ``tud_descriptor_*_cb()`` callbacks (device) or host descriptor helpers that match your product.
6. **Initialize TinyUSB**: Call ``tusb_init()`` once the clocks/peripherals are ready. Pass ``tusb_rhport_init_t`` if you need per-port settings.
7. **Handle interrupts**: From the USB ISR call ``tusb_int_handler(rhport, true)`` so the stack can process events.
8. **Run USB tasks**: Call ``tud_task()`` (device) or ``tuh_task()`` (host) regularly from the main loop, RTOS task.
9. **Implement class callbacks**: Provide the callbacks for the classes you enabled (e.g., ``tud_cdc_rx_cb()``, ``tuh_msc_mount_cb()``).

Minimal Example
===============

.. code-block:: c

   #include "tusb.h"

   int main(void) {
     board_init();  // Your board initialization

     // Init device stack on roothub port 0 for highspeed device
     tusb_rhport_init_t dev_init = {
       .role  = TUSB_ROLE_DEVICE,
       .speed = TUSB_SPEED_HIGH
     };
     tusb_init(0, &dev_init);

     // init host stack on roothub port 1 for fullspeed host
     tusb_rhport_init_t host_init = {
       .role  = TUSB_ROLE_HOST,
       .speed = TUSB_SPEED_FULL
     };
     tusb_init(1, &host_init);

     while (1) {
       tud_task();  // device task
       tuh_task();  // host task

       app_task();  // Your application logic
     }
   }

   void USB0_IRQHandler(void) {
     // forward interrupt port 0 to TinyUSB stack
     tusb_int_handler(0, true);
   }

   void USB1_IRQHandler(void) {
     // forward interrupt port 1 to TinyUSB stack
     tusb_int_handler(1, true);
   }

.. note::
   Unlike many libraries, TinyUSB callbacks don't need to be registered. Implement functions with the prescribed names (for example ``tud_cdc_rx_cb()``) and the stack will invoke them automatically.

.. note::
   Naming follows ``tud_*`` for device APIs and ``tuh_*`` for host APIs. Refer to :doc:`reference/glossary` for a summary of the prefixes and callback naming rules.


STM32CubeIDE Integration
========================

To integrate TinyUSB device stack with STM32CubeIDE

1. In STM32CubeMX, enable USB_OTG_FS/HS under Connectivity, set to "Device_Only" mode
2. Enable the USB global interrupt in NVIC Settings
3. Add ``tusb.h`` include and call ``tusb_init()`` in main.c
4. Call ``tud_task()`` in your main loop
5. In the generated ``stm32xxx_it.c``, modify the USB IRQ handler to call ``tud_int_handler(0)``

.. code-block:: c

   void OTG_FS_IRQHandler(void) {
     tud_int_handler(0);
   }

6. Create ``tusb_config.h`` and ``usb_descriptors.c`` files

.. tip::
   STM32CubeIDE generated code conflicts with TinyUSB. Don't use STM32's built-in USB middleware (USB Device Library) when using TinyUSB. Disable USB code generation in STM32CubeMX and let TinyUSB handle all USB functionality.