1 files changed, 93 insertions, 0 deletions
diff --git a/docs/integration.rst b/docs/integration.rst
new file mode 100644
index 000000000..32f90f793
--- /dev/null
+++ b/docs/integration.rst
@@ -0,0 +1,93 @@
+*******************
+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.