| **** | |
| FAQs | |
| **** | |
| General Questions | |
| ================= | |
| **Q: What microcontrollers does TinyUSB support?** | |
| TinyUSB supports 50+ MCU families including STM32, RP2040, NXP (iMXRT, Kinetis, LPC), Microchip SAM, Nordic nRF5x, ESP32, and many others. See :doc:`reference/boards` for the complete list. | |
| **Q: Can I use TinyUSB in commercial projects?** | |
| Yes, TinyUSB is released under the MIT license, allowing commercial use with minimal restrictions. | |
| **Q: Does TinyUSB require an RTOS?** | |
| No, TinyUSB works in bare metal environments. It also supports FreeRTOS, RT-Thread, ThreadX, and Mynewt. | |
| **Q: How much memory does TinyUSB use?** | |
| Typical usage: 8-20KB flash, 1-4KB RAM depending on enabled classes and configuration. The stack uses static allocation only. | |
| Build and Setup | |
| ================ | |
| **Q: Why do I get "arm-none-eabi-gcc: command not found"?** | |
| Install the ARM GCC toolchain: ``sudo apt-get install gcc-arm-none-eabi`` on Ubuntu/Debian, or download from ARM's website for other platforms. | |
| **Q: Build fails with "Board 'X' not found"** | |
| Check available boards: ``ls hw/bsp/FAMILY/boards/`` or run ``python tools/build.py -l`` to list all supported boards. | |
| **Q: What are the dependencies and how do I get them?** | |
| Run ``python tools/get_deps.py FAMILY`` where FAMILY is your MCU family (e.g., stm32f4, rp2040). This downloads MCU-specific drivers and libraries. | |
| **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:`getting_started` for details. | |
| **Q: Error: "tusb_config.h: No such file or directory"** | |
| This is a very common issue. You need to create ``tusb_config.h`` in your project and ensure it's in your include path. The file must define ``CFG_TUSB_MCU`` and ``CFG_TUSB_OS`` at minimum. Copy from ``examples/device/*/tusb_config.h`` as a starting point. | |
| **Q: RP2040 + pico-sdk ignores my tusb_config.h settings** | |
| The pico-sdk build system can override ``tusb_config.h`` settings. The ``CFG_TUSB_OS`` setting is often ignored because pico-sdk sets it to ``OPT_OS_PICO`` internally. Use pico-sdk specific configuration methods or modify the CMake configuration. | |
| **Q: "multiple definition of dcd_..." errors with STM32** | |
| This happens when multiple USB drivers are included. Ensure you're only including the correct portable driver for your STM32 family. Check that ``CFG_TUSB_MCU`` is set correctly and you don't have conflicting source files. | |
| Device Development | |
| ================== | |
| **Q: My USB device isn't recognized by the host** | |
| Common causes: | |
| - Invalid USB descriptors - validate with ``LOG=2`` build | |
| - ``tud_task()`` not called regularly in main loop | |
| - Incorrect ``tusb_config.h`` settings | |
| - USB cable doesn't support data (charging-only cable) | |
| **Q: Windows shows "Device Descriptor Request Failed"** | |
| This typically indicates: | |
| - Malformed device descriptor | |
| - USB timing issues (check crystal/clock configuration) | |
| - Power supply problems during enumeration | |
| - Conflicting devices on the same USB hub | |
| **Q: How do I implement a custom USB class?** | |
| Use the vendor class interface (``CFG_TUD_VENDOR``) or implement a custom class driver. See ``src/class/vendor/`` for examples. | |
| **Q: Can I have multiple configurations or interfaces?** | |
| Yes, TinyUSB supports multiple configurations and composite devices. Modify the descriptors in ``usb_descriptors.c`` accordingly. | |
| **Q: How do I change Vendor ID/Product ID?** | |
| Edit the device descriptor in ``usb_descriptors.c``. For production, obtain your own VID from USB-IF or use one from your silicon vendor. | |
| **Q: Device works alone but fails when connected through USB hub** | |
| This is a known issue where some devices interfere with each other when connected to the same hub. Try: | |
| - Using different USB hubs | |
| - Connecting devices to separate USB ports | |
| - Checking for power supply issues with the hub | |
| Host Development | |
| ================ | |
| **Q: Why doesn't my host application detect any devices?** | |
| Check: | |
| - Power supply - host mode requires more power than device mode | |
| - USB connector type - use USB-A for host applications | |
| - Board supports host mode on the selected port | |
| - Enable logging with ``LOG=2`` to see enumeration details | |
| **Q: Can I connect multiple devices simultaneously?** | |
| Yes, through a USB hub. TinyUSB supports multi-level hubs and multiple device connections. | |
| **Q: Does TinyUSB support USB 3.0?** | |
| No, TinyUSB currently supports USB 2.0 and earlier. USB 3.0 devices typically work in USB 2.0 compatibility mode. | |
| Configuration and Features | |
| ========================== | |
| **Q: How do I enable/disable specific USB classes?** | |
| Edit ``tusb_config.h`` and set the corresponding ``CFG_TUD_*`` or ``CFG_TUH_*`` macros to 1 (enable) or 0 (disable). | |
| **Q: Can I use both device and host modes simultaneously?** | |
| Yes, with dual-role/OTG capable hardware. See ``examples/dual/`` for implementation examples. | |
| **Q: How do I optimize for code size?** | |
| - Disable unused classes in ``tusb_config.h`` | |
| - Use ``CFG_TUSB_DEBUG = 0`` for release builds | |
| - Compile with ``-Os`` optimization | |
| - Consider using only required endpoints/interfaces | |
| **Q: Does TinyUSB support low power/suspend modes?** | |
| Yes, TinyUSB handles USB suspend/resume. Implement ``tud_suspend_cb()`` and ``tud_resume_cb()`` for custom power management. | |
| **Q: What CFG_TUSB_MCU should I use for x86/PC platforms?** | |
| For PC/motherboard applications, there's no standard MCU option. You may need to use a generic option or modify TinyUSB for your specific use case. Consider using libusb or other PC-specific USB libraries instead. | |
| **Q: RP2040 FreeRTOS configuration issues** | |
| The RP2040 pico-sdk has specific requirements for FreeRTOS integration. The ``CFG_TUSB_OS`` setting may be overridden by the SDK. Use pico-sdk specific configuration methods and ensure proper task stack sizes for the USB task. | |
| Debugging and Troubleshooting | |
| ============================= | |
| **Q: How do I debug USB communication issues?** | |
| 1. Enable logging: build with ``LOG=2`` | |
| 2. Use ``LOGGER=rtt`` or ``LOGGER=swo`` for high-speed logging | |
| 3. Use USB protocol analyzers for detailed traffic analysis | |
| 4. Check with different host systems (Windows/Linux/macOS) | |
| **Q: My application crashes or hard faults** | |
| Common causes: | |
| - Stack overflow - increase stack size in linker script | |
| - Incorrect interrupt configuration | |
| - Buffer overruns in USB callbacks | |
| - Build with ``DEBUG=1`` and use a debugger | |
| **Q: Performance is poor or USB transfers are slow** | |
| - Ensure ``tud_task()``/``tuh_task()`` called frequently (< 1ms intervals) | |
| - Use DMA for USB transfers if supported by your MCU | |
| - Optimize endpoint buffer sizes | |
| - Consider using high-speed USB if available | |
| **Q: Some USB devices don't work with my host application** | |
| - Not all devices follow USB standards perfectly | |
| - Some may need device-specific handling | |
| - Composite devices may have partial support | |
| - Check device descriptors and implement custom drivers if needed | |
| **Q: ESP32-S3 USB host/device issues** | |
| ESP32-S3 has specific USB implementation challenges: | |
| - Ensure proper USB pin configuration | |
| - Check power supply requirements for host mode | |
| - Some features may be limited compared to other MCUs | |
| - Use ESP32-S3 specific examples and documentation |