[opensourcedex]

CherryUSB is a free, open source data engineering & integration project written in C and released under Apache-2.0. It has 2,042 GitHub stars, 450 forks and 12 open issues, and was last pushed 8 hours ago. On this registry it ranks #25 of 39 tracked projects in Data Engineering & Integration, with 5 head-to-head comparisons available. It gained 3 stars over the last 3 tracked days.

What is CherryUSB?

What it is

CherryUSB is C USB host and device stack for embedded system with USB IP. It targets USB2.0 full and high speed, while USB3.0 super speed is TODO. It solves problem of adding USB protocol handling, class behavior, and controller porting to constrained embedded firmware. It gives device core, class drivers, demos, docs, and porting layer for dcd and hcd drivers. It lives in embedded C firmware ecosystem, not data pipeline ecosystem.

It addresses learning and integration burden. Code is streamlined, logic simple, no complex C syntax. It uses tree-structured progressive layers. Class drivers and porting drivers are templated and simplified. API is split into device initialization, class registration, command callbacks, data transmission, and host initialization, class discovery, data transmission. For data paths, interface feels like UART TX DMA or UART RX DMA. Users do not manage USB packetization, because porting drivers handle it.

Key capabilities

  • Device stack supports USB2.0 full and high speed, standard device requests, CLASS requests, VENDOR requests, custom special requests, and composite devices.
  • Class support includes CDC_ACM, CDC_ECM, HID, MSC, UVC1.0, UVC1.5, UAC1.0, UAC2.0, RNDIS, DFU, MIDI, MTP, TMC, WINUSB1.0, WINUSB2.0, WEBUSB, BOS, vendor display, vendor class, UF2, and Android Debug Bridge shell.
  • Porting covers USB IP drivers and topics such as CDNS2, CDNS3, DWC2, EHCI, OHCI, MUSB, and hub, with dcd and hcd porting directories.
  • Data transmission API has no fixed length restriction, moves packetization into porting drivers, and presents UART DMA-like send and receive paths.
  • Performance path uses direct register access, memory zero copy, DMA when IP supports it, packetization in interrupt context, and documented per-file FLASH, RAM, no-cache RAM, and heap usage.

Who uses it and how

  • Embedded firmware developers integrate CherryUSB into C projects to expose device classes such as CDC_ACM serial, HID, MSC storage, DFU upgrade, RNDIS networking, MIDI, MTP, or TMC from microcontroller.
  • Porting engineers adapt standard dcd and hcd interfaces to target USB IP blocks like CDNS2, CDNS3, DWC2, EHCI, OHCI, or MUSB, then connect drivers to board-specific interrupt and memory layout.
  • Teams and learners use demos, progressive code layers, and clear API split to build composite devices or study enumeration, driver loading, endpoint callbacks, and IP driver behavior.

Getting started

README points to docs, demo, port directories, and homepage https://cherryusb.readthedocs.io. Users integrate C sources into embedded project, select dcd or hcd port for target USB IP, and build demo or custom class.

When to use it — and when not to

Use CherryUSB when project needs C USB2.0 device stack, many classes, and IP-oriented porting for embedded firmware. Avoid it when USB3.0 super speed is required, since README lists it as TODO, or when support beyond documented device classes and host porting API is needed. Teams must provide target board porting, endpoint callbacks, memory layout, and interrupt or DMA handling.

project readme (upstream, from github) — read inline

English | 简体中文

CherryUSB

CherryUSB is a tiny and beautiful, high performance and portable USB host and device stack for embedded system with USB IP.

CherryUSB

Why choose CherryUSB

Easy to Learn USB

To facilitate user learning of USB fundamentals, enumeration, driver loading, and IP drivers, the written code has the following advantages:

  • Streamlined code with simple logic and no complex C language syntax
  • Tree-structured programming with progressive code layers
  • Templated and simplified Class drivers and porting drivers
  • Clear API categorization (Device: initialization, class registration, command callbacks, data transmission; Host: initialization, class discovery, data transmission)

Easy to Use USB

To facilitate user interaction with USB interfaces, considering users’ familiarity with UART and DMA, the designed data transmission interface has the following advantages:

  • Equivalent to using UART TX DMA/UART RX DMA
  • No length restrictions on transmission/reception; users don’t need to worry about USB packetization (porting drivers handle packetization)

Easy to Achieve USB Performance

Considering USB performance requirements to reach theoretical USB hardware bandwidth, the designed data transmission interface has the following advantages:

  • Porting drivers directly interface with registers without abstraction layer encapsulation
  • Memory zero copy
  • DMA mode used when IP supports DMA (DMA provides hardware packetization functionality)
  • No length restrictions, facilitating hardware DMA interfacing and maximizing DMA advantages
  • Packetization handled in interrupt context

Performance show：https://cherryusb.cherry-embedded.org/show/

Directory Structure

Directory Description
class usb class driver
common usb spec macros and utils
core usb core implementation
demo usb device and host demo
osal os wrapper
platform class support for other os
docs doc for guiding
port usb dcd and hcd porting
tools tool url

Device Stack Overview

CherryUSB Device Stack provides a unified framework of functions for standard device requests, CLASS requests, VENDOR requests and custom special requests. The object-oriented and chained approach allows the user to quickly get started with composite devices without having to worry about the underlying logic. At the same time, a standard dcd porting interface has been standardised for adapting different USB IPs to achieve ip-oriented programming.

CherryUSB Device Stack has the following functions:

  • Support USB2.0 full and high speed(USB3.0 super speed TODO)
  • Support endpoint irq callback register by users, let users do whatever they wants in endpoint irq callback.
  • Support Composite Device
  • Support Communication Device Class (CDC_ACM, CDC_ECM)
  • Support Human Interface Device (HID)
  • Support Mass Storage Class (MSC)
  • Support USB VIDEO CLASS (UVC1.0, UVC1.5)
  • Support USB AUDIO CLASS (UAC1.0, UAC2.0)
  • Support Remote NDIS (RNDIS)
  • Support Device Firmware Upgrade CLASS (DFU)
  • Support USB MIDI CLASS (MIDI)
  • Support Media Transfer Protocol (MTP)
  • Support Test and Measurement Class (TMC)
  • Support WINUSB1.0, WINUSB2.0, WEBUSB, BOS
  • Support Vendor display (xfz1986_usb_graphic_driver)
  • Support Vendor class
  • Support UF2
  • Support Android Debug Bridge (Only support shell)
  • Support multi device with the same USB IP

CherryUSB Device Stack resource usage (GCC 10.2 with -O2, disable log):

file FLASH (Byte) No Cache RAM (Byte) RAM (Byte) Heap (Byte)
usbd_core.c ~4000 (512(default) + 320) * bus 8 0
usbd_cdc_acm.c ~400 0 0 0
usbd_msc.c ~3200 (128 + 512(default)) * bus 16 * bus 0
usbd_hid.c ~200 0 0 0
usbd_audio.c ~1300 0 8 * bus 0
usbd_video.c ~2500 0 124 * bus 0
usbd_rndis.c ~2000 2 * 1580(default)+156+8 76 0
usbd_cdc_ecm.c ~1500 2 * 1514(default)+16 42 0
usbd_mtp.c ~9000 2048(default)+128 sizeof(struct mtp_object) * n 0
usbd_dfu.c ~800 0 1 0

usbdevice_usage

Host Stack Overview

The CherryUSB Host Stack has a standard enumeration implementation for devices mounted on root hubs and external hubs, and a standard interface for different Classes to indicate what the Class driver needs to do after enumeration and after disconnection. A standard hcd porting interface has also been standardised for adapting different USB IPs for IP-oriented programming. Finally, the host stack is managed using os, and provides osal to make a adaptation for different os.

CherryUSB Host Stack has the following functions:

  • Support low speed, full speed, high speed and super speed devices
  • Automatic loading of supported Class drivers
  • Support blocking transfers and asynchronous transfers
  • Support Composite Device
  • Multi-level HUB support, expandable up to 7 levels(Testing hub with 10 ports works well,only support dwc2/ehci/xhci/rp2040)
  • Support Communication Device Class (CDC_ACM, CDC_ECM, CDC_NCM)
  • Support Human Interface Device (HID)
  • Support Mass Storage Class (MSC)
  • Support USB Video CLASS (UVC1.0, UVC1.5)
  • Support USB Audio CLASS (UAC1.0)
  • Support Remote NDIS (RNDIS)
  • Support Device Firmware Upgrade CLASS (DFU)
  • Support USB Bluetooth class (support nimble and zephyr bluetooth stack, support CLASS:0xE0 or vendor class like cdc acm)
  • Support Vendor Serial Class(CH34X、CP210X、PL2303、FTDI、GSM)
  • Support Vendor network Class(RTL8152、AX88772)
  • Support USB modeswitch
  • Support Android Open Accessory
  • Support multi host with the same USB IP

The CherryUSB Host stack also provides the lsusb function, which allows you to view information about all mounted devices, including those on external hubs, with the help of a shell plugin.

CherryUSB Host Stack resource usage (GCC 10.2 with -O2, disable log):

file FLASH (Byte) No Cache RAM (Byte) RAM (Byte) Heap (Byte)
usbh_core.c ~4000 (512(default) + 8 * (1+x) *n) * bus sizeof(struct usbh_hub) * bus raw_config_desc
usbh_hub.c ~3000 (32 + 4 * (1+x)) * bus 12 + sizeof(struct usbh_hub) * x 0
usbh_msc.c ~1500 128 * x 4 + sizeof(struct usbh_msc) * x 0
usbh_hid.c ~2000 64 * x 4 + sizeof(struct usbh_hid) * x 0
usbh_video.c ~2500 128 * x 4 + sizeof(struct usbh_video) * x 0
usbh_audio.c ~4000 128 * x 4 + sizeof(struct usbh_audio) * x 0
usbh_rndis.c ~3000 512 + 2 * 2048(default) sizeof(struct usbh_rndis) * 1 0
usbh_cdc_ecm.c ~1500 2 * 1514 + 16 sizeof(struct usbh_cdc_ecm) * 1 0
usbh_cdc_ncm.c ~2000 2 * 2048(default) + 16 + 32 sizeof(struct usbh_cdc_ncm) * 1 0
usbh_bluetooth.c ~1000 2 * 2048(default) sizeof(struct usbh_bluetooth) * 1 0
usbh_asix.c ~3500 2 * 2048(default) + 16

readme truncated — read the full docs on github

Frequently asked questions

Is CherryUSB free to use?

CherryUSB is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does CherryUSB do?

CherryUSB is a tiny and beautiful, high performance and portable USB host and device stack for embedded system with USB IP

What is CherryUSB written in?

CherryUSB is primarily written in C. Its source is publicly available at https://github.com/cherry-embedded/CherryUSB, and it has 2,042 GitHub stars.