docs/faq.rst

**************************
Frequently Asked Questions
**************************

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, 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