docs/faq.rst
Frequently Asked 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.
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.
Q: My USB device isn't recognized by the host
Common causes:
LOG=2 buildtud_task() not called regularly in main looptusb_config.h settingsQ: Windows shows "Device Descriptor Request Failed"
This typically indicates:
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:
Q: Why doesn't my host application detect any devices?
Check:
LOG=2 to see enumeration detailsQ: 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.
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?
tusb_config.hCFG_TUSB_DEBUG = 0 for release builds-Os optimizationQ: 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.
Q: How do I debug USB communication issues?
LOG=2LOGGER=rtt or LOGGER=swo for high-speed loggingQ: My application crashes or hard faults
Common causes:
DEBUG=1 and use a debuggerQ: Performance is poor or USB transfers are slow
tud_task()/tuh_task() called frequently (< 1ms intervals)Q: Some USB devices don't work with my host application
Q: ESP32-S3 USB host/device issues
ESP32-S3 has specific USB implementation challenges: