DOCSEARCHbyAlgolia
Submit Docs

CherryUSB Documentation

repository·master·Indexed 23 days ago

https://github.com/cherry-embedded/cherryusb

A high-performance, portable USB host and device stack for embedded systems. It features streamlined code, data transmission interfaces similar to UART DMA, and extensive support for various USB classes, hardware IPs, and integrations with RT-Thread, NuttX, Zephyr, and ThreadX. Supports a wide range of microcontrollers from NXP, STM32, WCH, Bouffalolab, and others, with specific ports for EHCI, OHCI, DWC2, MUSB, and PUSB2.

Tokens
35.5K
Snippets
59
Records
185
Agent score
83%

What's inside CherryUSB

  1. Overview of CherryUSB

    master

    CherryUSB is a lightweight, portable USB host and device protocol stack designed for embedded systems. It is structured to be easy to learn, easy to use, and capable of high performance.

    Key Features

    Easy to Learn

    • Streamlined Logic: Simple code with minimal complex C syntax.
    • Layered Architecture: Tree-structured programming with progressive layers.
    • Simplified Drivers: Templated Class and porting drivers.
    • Clear API Categorization:
      • Device Stack: Focuses on initialization, class registration, command callbacks, and data transmission.
      • Host Stack: Focuses on initialization, class discovery, and data transmission.

    Easy to Use

    • Familiar Interface: Data transmission is designed to feel similar to UART TX/RX DMA.
    • No Packetization Management: Users can transmit or receive data without length restrictions; the porting drivers handle USB packetization automatically.

    High Performance

    • Direct Register Access: Porting drivers interface directly with hardware registers without heavy abstraction layers.
    • Zero Copy: Supports memory zero-copy mechanisms.
    • DMA Integration: Utilizes DMA modes when the USB IP supports it to maximize hardware bandwidth and handle packetization in the interrupt context.

  2. Explore Open Source projects based on CherryUSB

    master
    CherryUSB is used as the underlying USB stack for various open-source projects, including RTOS ports, hardware debuggers, and specialized firmware. You can explore these projects to see real-world implementations of the CherryUSB stack in different environments (e.g., RT-Thread, NuttX, Zephyr) or hardware applications (e.g., DAPLINK, HSCANT, Blackmagic).

  4. Specialized Protocol and Debugger Support

    master

    CherryUSB supports several specialized hardware and protocol implementations:

    • Blackmagic: USB Device CDC ACM support.
    • DAPLINK: DAPLINK v2.1 support with USB Device CDC ACM + WinUSB (HID and MSC are optional).
    • UF2: USB Device MSC support.
    • QMK: USB Device HID support.

  6. RT-Thread Integration Support

    master

    CherryUSB offers extensive support for the RT-Thread ecosystem:

    • Device Drivers: rt_device support for USB Device MSC.
    • File Systems: DFS support for USB Host MSC.
    • Networking: lwip support for USB Host Net classes (cdc_ecm, cdc_ncm, cdc_rndis, asix, rtl8152, bl616_wifi).
    • Shell/CLI: msh support with lsusb command; shell support with adb.
    • Character Devices: Host support for cdc_acm, ftdi, ch34x, cp210x, and pl2303.

  7. Supported File Systems and Network Stacks

    master

    CherryUSB provides integration support for several common open-source file systems and network stacks:

    Fatfs

    • USB Host MSC: Support for Mass Storage Class as a host.
    • USB Device MTP: Support for Media Transfer Protocol as a device.

    lwip

    • USB Host Net Class: Support for various network classes including cdc_ecm, cdc_ncm, cdc_rndis, asix, rtl8152, and bl616_wifi.

  10. Overview of the CherryUSB Device Stack

    master

    The CherryUSB Device stack provides a unified framework for handling standard device requests, CLASS requests, VENDOR requests, and custom requests. It uses an object-oriented approach with linked lists to allow developers to quickly implement composite devices without managing low-level logic. It also provides a standard dcd (Device Controller Driver) porting interface to enable programming against the USB IP rather than specific hardware registers.

    Supported Features:

    • USB 2.0 Full Speed and High Speed (USB 3.0 Super Speed is TODO).
    • Endpoint interrupt registration.
    • Composite device support.
    • Extensive Class support including: CDC (ACM, ECM), HID, MSC, UVC (1.0, 1.5), UAC (1.0, 2.0), RNDIS, DFU, MIDI, MTP, TMC, WINUSB (1.0, 2.0), WEBUSB, BOS, and more.
    • Support for multiple device instances on the same USB IP.

  11. Overview of the CherryUSB Host Stack

    master

    The CherryUSB Host stack implements standard enumeration for devices connected to root hubs or external hubs. It provides standard interfaces for various USB Classes to handle connection and disconnection events. The stack is managed via an OS abstraction layer (osal) and uses a standard hcd (Host Controller Driver) porting interface to support different USB IPs.

    Supported Features:

    • Support for Low Speed, Full Speed, High Speed, and Super Speed devices.
    • Automatic loading of supported Class drivers.
    • Support for both blocking and asynchronous transfers.
    • Multi-level HUB support (up to 7 levels).
    • Extensive Class support including: CDC (ACM, ECM, NCM), HID, MSC, UVC, UAC (1.0), RNDIS, DFU, USB Bluetooth, and various Vendor Serial/Network classes.
    • lsusb functionality via shell plugins to view connected device information.

  12. What is a Short Packet and ZLP (Zero-Length Packet)

    master

    In USB communication, specific packet types are used to signal the end of a data stream:

    • Short Packet: The final packet in a sequence where the data length is less than the Endpoint Maximum Packet Size (EP MPS). For example, if EP MPS is 64 and you send 129 bytes, the sequence is 64 + 64 + 1. The 1-byte packet is the short packet.
    • ZLP (Zero-Length Packet): A short packet with a data length of 0. This is used when the total data length is an exact multiple of the EP MPS. The ZLP informs the receiver that the transmission has ended.

    Important Constraints:

    • ZLP functionality is limited to CONTROL and BULK transfers.
    • Some custom protocols (like MSC) may not require a ZLP even if the length is a multiple of EP MPS.