docs/troubleshooting.rst
Troubleshooting
This guide helps you diagnose and fix common issues when developing with TinyUSB.
"arm-none-eabi-gcc: command not found"
The ARM GCC toolchain is not installed or not in PATH.
Solution:
.. code-block:: bash
$ sudo apt-get update && sudo apt-get install gcc-arm-none-eabi
$ brew install --cask gcc-arm-embedded
"make: command not found" or CMake errors
Build tools are missing.
Solution:
.. code-block:: bash
$ sudo apt-get install build-essential cmake
$ xcode-select --install $ brew install cmake
"No rule to make target" or missing header files
Dependencies for your MCU family are not downloaded.
Solution:
.. code-block:: bash
$ python tools/get_deps.py -b stm32h743eval # Replace with your board $ python tools/get_deps.py stm32f4 # Replace with your family
cd examples/device/cdc_msc make BOARD=your_board get-deps
Board Not Found
Invalid board name in build command.
Diagnosis:
.. code-block:: bash
ls hw/bsp/stm32f4/boards/
Solution: Use exact board name from the listing.
Device not recognized by host
The most common issue - host doesn't see your USB device.
Diagnosis steps:
LOG=2dmesg (Linux)Common causes and solutions:
usb_descriptors.c carefullytud_task() not called: Ensure regular calls in main loop (< 1ms interval)tusb_config.h settingsEnumeration starts but fails
Device is detected but configuration fails.
Diagnosis:
.. code-block:: bash
make BOARD=your_board LOG=2 all
Look for:
Solutions:
Data transfer issues
Device enumerates but data doesn't transfer correctly.
Common causes:
Solutions:
No devices detected
Host application doesn't see connected devices.
Hardware checks:
Software checks:
tuh_task() called regularlytusb_config.hDevice enumeration fails
Devices connect but enumeration fails.
Diagnosis:
.. code-block:: bash
make BOARD=your_board LOG=2 RHPORT_HOST=1 all
Common issues:
Class driver issues
Device enumerates but class-specific communication fails.
Troubleshooting:
Symptoms: Lower than expected USB transfer rates
Causes and solutions: Improve task scheduling by calling tud_task()/tuh_task() more frequently to ensure timely USB event processing. Consider increasing endpoint buffer sizes for bulk transfers to reduce the frequency of small transfers. Enable DMA usage for USB transfers if your hardware supports it to offload CPU processing. Finally, use High Speed (480 Mbps) instead of Full Speed (12 Mbps) when possible to achieve better throughput.
Symptoms: MCU spending too much time in USB handling
Solutions:
Clock configuration problems:
Pin configuration:
PIO-USB for host mode:
USB peripheral differences:
For complex issues, hardware USB analyzers provide detailed protocol traces:
Debugging with traditional debuggers is limited due to the real time nature of USB. However, especially for diagnosis of crashes, it can still be useful.
.. code-block:: bash
make BOARD=your_board DEBUG=1 all
arm-none-eabi-gdb build/your_app.elf
Useful breakpoints:
dcd_int_handler() - USB interrupt entrytud_task() - Main device taskFor production debugging, implement custom logging:
.. code-block:: c
// In tusb_config.h #define CFG_TUSB_DEBUG_PRINTF my_printf
// Your implementation void my_printf(const char* format, ...) { // Send to RTT, SWO, or custom interface }
When reporting issues:
LOG=2 enabledResources: