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