tinyusb

An open source cross-platform USB stack for embedded system

4,836

1,027

4,836

222

View on GitHub

Top Related Projects

libopencm3

3,073

Open source ARM Cortex-M microcontroller library

Quick Overview

TinyUSB is an open-source cross-platform USB Host/Device stack for embedded systems. It is designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred and handled in the non-ISR task function.

Pros

Highly portable and easy to use across different microcontrollers
Supports both USB device and host functionalities
Memory-safe implementation with no dynamic allocation
Thread-safe design with interrupt events handled in non-ISR tasks

Cons

Limited to embedded systems and not suitable for general-purpose computers
May require more setup and configuration compared to platform-specific USB stacks
Documentation could be more comprehensive for advanced use cases
Performance may be slightly lower compared to highly optimized vendor-specific stacks

Code Examples

Initializing TinyUSB:

#include "tusb.h"

int main(void)
{
    board_init();
    tusb_init();

    while (1)
    {
        tud_task(); // tinyusb device task
    }

    return 0;
}

Implementing a USB HID keyboard:

#include "tusb.h"

void hid_task(void)
{
    if (tud_hid_ready())
    {
        uint8_t keycode[6] = { 0 };
        keycode[0] = HID_KEY_A;
        tud_hid_keyboard_report(REPORT_ID_KEYBOARD, 0, keycode);
    }
}

Handling USB events:

void tud_mount_cb(void)
{
    // Device mounted
}

void tud_umount_cb(void)
{
    // Device unmounted
}

void tud_suspend_cb(bool remote_wakeup_en)
{
    // USB bus is suspended
}

void tud_resume_cb(void)
{
    // USB bus is resumed
}

Getting Started

Clone the TinyUSB repository:

git clone https://github.com/hathach/tinyusb.git

Add TinyUSB to your project's include path and source files.
Implement the required callbacks and USB descriptors for your device.
Initialize TinyUSB in your main function:
```
tusb_init();
```
Call tud_task() regularly in your main loop to handle USB events.

Competitor Comparisons

libopencm3

3,073

Open source ARM Cortex-M microcontroller library

Pros of libopencm3

Supports a wider range of microcontrollers, including STM32, EFM32, and LPC families
Provides a more comprehensive set of peripheral drivers and utilities
Offers a higher level of abstraction for hardware control

Cons of libopencm3

Steeper learning curve due to its broader scope and more complex architecture
Less focused on USB functionality compared to TinyUSB
May have a larger code footprint for simple projects

Code Comparison

libopencm3 GPIO configuration:

gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO5);
gpio_set(GPIOA, GPIO5);

TinyUSB GPIO configuration (using SDK-specific code):

gpio_init(LED_PIN);
gpio_set_dir(LED_PIN, GPIO_OUT);
gpio_put(LED_PIN, 1);

Both libraries offer straightforward GPIO control, but libopencm3 provides a more unified API across different microcontroller families, while TinyUSB relies on SDK-specific implementations for non-USB functionalities.

ArduinoCore-avr

1,214

The Official Arduino AVR core

Pros of ArduinoCore-avr

Extensive support for AVR microcontrollers, especially ATmega series
Well-established ecosystem with a large community and abundant resources
Simplified programming model suitable for beginners and rapid prototyping

Cons of ArduinoCore-avr

Limited USB functionality compared to TinyUSB's comprehensive USB stack
Less flexibility for advanced users who need fine-grained control over USB operations
Primarily focused on AVR architecture, while TinyUSB supports multiple platforms

Code Comparison

ArduinoCore-avr (basic USB serial communication):

void setup() {
  Serial.begin(9600);
}

void loop() {
  if (Serial.available()) {
    char c = Serial.read();
    Serial.write(c);
  }
}

TinyUSB (USB CDC example):

void cdc_task(void) {
  if (tud_cdc_available()) {
    uint8_t buf[64];
    uint32_t count = tud_cdc_read(buf, sizeof(buf));
    tud_cdc_write(buf, count);
  }
}

TinyUSB offers more granular control over USB operations, while ArduinoCore-avr provides a simpler interface for basic serial communication. TinyUSB's approach allows for more advanced USB implementations across various device classes.

pico-sdk

3,691

Pros of pico-sdk

Specifically designed for Raspberry Pi Pico, offering optimized performance and compatibility
Includes comprehensive documentation and examples tailored for Pico development
Provides a complete development ecosystem, including debugging tools and board support packages

Cons of pico-sdk

Limited to Raspberry Pi Pico and RP2040-based boards, lacking cross-platform support
Steeper learning curve for developers not familiar with the RP2040 architecture
Less extensive USB device class support compared to TinyUSB

Code Comparison

pico-sdk:

#include "pico/stdlib.h"
#include "hardware/gpio.h"

int main() {
    gpio_init(LED_PIN);
    gpio_set_dir(LED_PIN, GPIO_OUT);
    while (true) {
        gpio_put(LED_PIN, 1);
        sleep_ms(500);
        gpio_put(LED_PIN, 0);
        sleep_ms(500);
    }
}

TinyUSB:

#include "tusb.h"

void main() {
    board_init();
    tusb_init();
    while (1) {
        tud_task();
    }
}

arduino-esp32

13,492

Arduino core for the ESP32

Pros of arduino-esp32

Specifically designed for ESP32 microcontrollers, offering optimized performance and features
Integrates seamlessly with the Arduino ecosystem, providing a familiar development environment
Includes extensive libraries and examples tailored for ESP32 functionality

Cons of arduino-esp32

Limited to ESP32 platforms, lacking the cross-platform support of TinyUSB
May have a steeper learning curve for developers not familiar with ESP32 architecture
Potentially larger codebase and memory footprint compared to TinyUSB's minimalist approach

Code Comparison

TinyUSB example (device initialization):

tusb_init();
while (1) {
  tud_task();
}

arduino-esp32 example (WiFi initialization):

#include <WiFi.h>
void setup() {
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
  }
}

Both repositories provide USB functionality, but TinyUSB focuses on a lightweight, portable USB stack for various microcontrollers, while arduino-esp32 offers a comprehensive framework specifically for ESP32 devices. TinyUSB's code tends to be more concise and low-level, while arduino-esp32 provides higher-level abstractions and additional features beyond USB, such as WiFi and Bluetooth support.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

TinyUSB Project

.. figure:: docs/assets/logo.svg :alt: TinyUSB

TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function. Check out the online documentation <https://docs.tinyusb.org/>__ for more details.

.. figure:: docs/assets/stack.svg :width: 500px :alt: stackup

.
âââ docs            # Documentation
âââ examples        # Examples with make and cmake build system
âââ hw
â   âââ bsp         # Supported boards source files
â   âââ mcu         # Low level mcu core & peripheral drivers
âââ lib             # Sources from 3rd party such as freeRTOS, fatfs ...
âââ src             # All sources files for TinyUSB stack itself.
âââ test            # Tests: unit test, fuzzing, hardware test
âââ tools           # Files used internally

Getting started

See the online documentation <https://docs.tinyusb.org>_ for information about using TinyUSB and how it is implemented.

We use GitHub Discussions <https://github.com/hathach/tinyusb/discussions>_ as our forum. It is a great place to ask questions and advice from the community or to discuss your TinyUSB-based projects.

For bugs and feature requests, please raise an issue <https://github.com/hathach/tinyusb/issues>_ and follow the templates there.

Check out Getting Started_ guide for adding TinyUSB to your project or building the examples. If you are new to TinyUSB, we recommend starting with the cdc_msc example.

See Porting_ guide for adding support for new MCUs and boards.

Device Stack

Supports multiple device configurations by dynamically changing USB descriptors, low power functions such like suspend, resume, and remote wakeup. The following device classes are supported:

Audio Class 2.0 (UAC2)
Bluetooth Host Controller Interface (BTH HCI)
Communication Device Class (CDC)
Device Firmware Update (DFU): DFU mode (WIP) and Runtime
Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...
Mass Storage Class (MSC): with multiple LUNs
Musical Instrument Digital Interface (MIDI)
Network with RNDIS, Ethernet Control Model (ECM), Network Control Model (NCM)
Test and Measurement Class (USBTMC)
Video class 1.5 (UVC): work in progress
Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.
WebUSB <https://github.com/WICG/webusb>__ with vendor-specific class

If you have a special requirement, usbd_app_driver_get_cb() can be used to write your own class driver without modifying the stack. Here is how the RPi team added their reset interface raspberrypi/pico-sdk#197 <https://github.com/raspberrypi/pico-sdk/pull/197>_

Host Stack

Human Interface Device (HID): Keyboard, Mouse, Generic
Mass Storage Class (MSC)
Communication Device Class: CDC-ACM
Vendor serial over USB: FTDI, CP210x
Hub with multiple-level support

Similar to the Device Stack, if you have a special requirement, usbh_app_driver_get_cb() can be used to write your own class driver without modifying the stack.

TypeC PD Stack

Power Delivery 3.0 (PD3.0) with USB Type-C support (WIP)
Super early stage, only for testing purpose
Only support STM32 G4

OS Abstraction layer

TinyUSB is completely thread-safe by pushing all Interrupt Service Request (ISR) events into a central queue, then processing them later in the non-ISR context task function. It also uses semaphore/mutex to access shared resources such as Communication Device Class (CDC) FIFO. Therefore the stack needs to use some of the OS's basic APIs. Following OSes are already supported out of the box.

No OS
FreeRTOS
RT-Thread <https://github.com/RT-Thread/rt-thread>: repo <https://github.com/RT-Thread-packages/tinyusb>
Mynewt Due to the newt package build system, Mynewt examples are better to be on its own repo <https://github.com/hathach/mynewt-tinyusb-example>_

Supported CPUs

Following CPUs are supported, check out Supported Devices_ for comprehensive list of driver, features for each CPU.

+--------------+------------------------------------------------------------+ | Manufacturer | Family | +==============+============================================================+ | Allwinner | F1C100s/F1C200s | +--------------+------------------------------------------------------------+ | Analog | max32: 650, 666, 690. max78002 | | | | | | max3421e (host) | +--------------+------------------------------------------------------------+ | Brigetek | FT90x | +--------------+------------------------------------------------------------+ | Broadcom | BCM2711, BCM2837 | +--------------+------------------------------------------------------------+ | Dialog | DA1469x | +--------------+------------------------------------------------------------+ | Espressif | ESP32 S2, S3 | +--------------+------------------------------------------------------------+ | GigaDevice | GD32VF103 | +--------------+------------------------------------------------------------+ | Infineon | XMC4500 | +--------------+------------------------------------------------------------+ | | SAM: D11, D21, D51, E5x, G55, L2x, E7x, S7x, V7x | | MicroChip | | | | PIC: 24, 32mm, 32mk, 32mx, 32mz, dsPIC33 | +--------------+------------------------------------------------------------+ | Mind Montion | mm32 | +--------------+------------------------------------------------------------+ | NordicSemi | nRF52833, nRF52840, nRF5340 | +--------------+------------------------------------------------------------+ | Nuvoton | NUC 120, 121, 125, 126, 505 | +--------------+------------------------------------------------------------+ | NXP | iMXRT: RT10xx, RT11xx | | | | | | Kinetis: KL, K32L2 | | | | | | LPC: 11u, 13, 15, 17, 18, 40, 43, 51u, 54, 55 | | | | | | MCX: A15, N9 | +--------------+------------------------------------------------------------+ | Raspberry Pi | RP2040 | +--------------+-----+------------------------------------------------------+ | Renesas | RA: 4M1, 4M3, 6M1, 6M5 | | | | | | RX: 63N, 65N, 72N | +--------------+-----+------------------------------------------------------+ | Silabs | EFM32GG12 | +--------------+------------------------------------------------------------+ | Sony | CXD56 | +--------------+------------------------------------------------------------+ | ST STM32 | F0, F1, F2, F3, F4, F7, G0, G4, H5, H7, | | | | | | L0, L1, L4, L4+, L5, U5, WB | +--------------+------------------------------------------------------------+ | TI | MSP430, MSP432E4, TM4C123 | +--------------+------------------------------------------------------------+ | ValentyUSB | eptri | +--------------+------------------------------------------------------------+ | WCH | CH32F: F20x | | | | | | CH32V: V20x, V307 | +--------------+------------------------------------------------------------+

License

All TinyUSB sources in the src folder are licensed under MIT license, the Full license is here <LICENSE>__. However, each file can be individually licensed especially those in lib and hw/mcu folder. Please make sure you understand all the license term for files you use in your project.

Docs

Info
- Uses_
- Changelog_
- Contributors_
Reference_
- Supported Devices_
- Getting Started_
- Dependencies_
- Concurrency_
Contributing_
- Code of Conduct_
- Structure_
- Porting_

.. |Build Status| image:: https://github.com/hathach/tinyusb/actions/workflows/build.yml/badge.svg :target: https://github.com/hathach/tinyusb/actions .. |CircleCI Status| image:: https://dl.circleci.com/status-badge/img/circleci/4AYHvUhFxdnY4rA7LEsdqW/QmrpoL2AjGqetvFQNqtWyq/tree/master.svg?style=svg :target: https://dl.circleci.com/status-badge/redirect/circleci/4AYHvUhFxdnY4rA7LEsdqW/QmrpoL2AjGqetvFQNqtWyq/tree/master .. |Documentation Status| image:: https://readthedocs.org/projects/tinyusb/badge/?version=latest :target: https://docs.tinyusb.org/en/latest/?badge=latest .. |Fuzzing Status| image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/tinyusb.svg :target: https://oss-fuzz-build-logs.storage.googleapis.com/index.html#tinyusb .. |License| image:: https://img.shields.io/badge/license-MIT-brightgreen.svg :target: https://opensource.org/licenses/MIT

.. _Uses: docs/info/uses.rst .. _Changelog: docs/info/changelog.rst .. _Contributors: CONTRIBUTORS.rst .. _Reference: docs/reference/index.rst .. _Supported Devices: docs/reference/supported.rst .. _Getting Started: docs/reference/getting_started.rst .. _Dependencies: docs/reference/dependencies.rst .. _Concurrency: docs/reference/concurrency.rst .. _Contributing: docs/contributing/index.rst .. _Code of Conduct: CODE_OF_CONDUCT.rst .. _Structure: docs/contributing/structure.rst .. _Porting: docs/contributing/porting.rst

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of libopencm3

Cons of libopencm3

Code Comparison

Pros of ArduinoCore-avr

Cons of ArduinoCore-avr

Code Comparison

Pros of pico-sdk

Cons of pico-sdk

Code Comparison

Pros of arduino-esp32

Cons of arduino-esp32

Code Comparison

Convert designs to code with AI

README

Sponsors

TinyUSB Project

Getting started

Device Stack

Host Stack

TypeC PD Stack

OS Abstraction layer

Supported CPUs

License

Docs

Top Related Projects

Convert designs to code with AI