RP USB Serial Console

A lightweight no_std USB CDC serial console for RP2040 and RP2350.

It provides:

USB CDC virtual serial output
formatted logging via usb_print! / usb_println!
internal RX/TX buffering
optional interrupt-driven USB maintenance
poll-driven receive path suitable for future protocol handling such as Modbus

Overview

rp-usb-serial is a small embedded Rust library that wraps the RP USB peripheral as a USB CDC ACM serial device.

It is designed for:

debug logging
serial console interaction
host-to-device byte streaming
protocol bring-up and early frame parsing
RP2040 / RP2350 projects using no_std

Compared with a simple "write-only USB log" implementation, this library now includes:

a TX queue
an RX queue
a poll() function that drives:
- USB protocol progress
- RX pumping
- optional echo
- TX flushing

This makes it more suitable for interactive testing and frame-oriented protocols.

Features

no_std
USB CDC ACM virtual serial port
supports RP2040
supports RP2350 ARM
supports RP2350 riscv32
global singleton-style USB console
internal TX queue
internal RX queue
usb_print! / usb_println! macros
poll()-driven RX/TX processing
optional use with USBCTRL_IRQ

Supported Platforms

RP2040

HAL: rp2040-hal
Architecture: ARM
USB registers:
- pac::USBCTRL_REGS
- pac::USBCTRL_DPRAM

RP2350 ARM

HAL: rp235x-hal
Architecture: ARM
USB registers:
- pac::USB
- pac::USB_DPRAM

RP2350 riscv32

HAL: rp235x-hal
Architecture: riscv32-*-none-*
USB registers:
- pac::USB
- pac::USB_DPRAM

rp2040 supports ARM targets only.
rp2350 supports ARM and bare-metal riscv32.

Cargo Features

The crate uses feature flags to select the target family.

Default

By default, the crate targets RP2040.

RP2040

[dependencies]
rp-usb-serial = "0.3.0"

RP2350

[dependencies]
rp-usb-serial = { version = "0.3.0", default-features = false, features = ["rp2350"] }

Installation Typical dependencies in your application may look like this:


[dependencies]
panic-halt = "0.2"
embedded-hal = "1.0.0"

# RP2040:
rp2040-hal = { version = "0.10", features = ["rt"], optional = true }

# RP2350:
rp235x-hal = { version = "0.3", features = ["rt"], optional = true }

rp-usb-serial = "0.3.0"

Or for RP2350:


[dependencies]
panic-halt = "0.2"
embedded-hal = "1.0.0"
rp235x-hal = { version = "0.3", features = ["rt"] }
rp-usb-serial = { version = "0.3.4", default-features = false, features = ["rp2350"] }

Adjust versions to match your local toolchain and HAL version.

Core Behavior

The current library behavior is centered around RpUsbConsole::poll().

poll() does all of the following:
Polls the USB device stack
Reads incoming bytes from the USB CDC endpoint
Pushes received bytes into the internal RX queue
Optionally echoes received bytes back to host
Flushes queued TX data
Important
read() does not read directly from the USB hardware endpoint anymore.

Instead:

poll() moves data into the internal RX queue
read() consumes data from that RX queue
So if you do not call poll(), incoming data may never reach read().

Quick Start

Import the crate


use rp_usb_serial::{RpUsbConsole, usb_println};

Initialize USB

RP2040


RpUsbConsole::init(
    pac.USBCTRL_REGS,
    pac.USBCTRL_DPRAM,
    &mut pac.RESETS,
    clocks.usb_clock,
);

RP2350


RpUsbConsole::init(
    pac.USB,
    pac.USB_DPRAM,
    &mut pac.RESETS,
    clocks.usb_clock,
);

Regularly call poll()


loop {
    RpUsbConsole::poll();
}

Read received bytes


let mut buf = [0u8; 64];
let n = RpUsbConsole::read(&mut buf);
if n > 0 {
    // process bytes
}

Print logs


usb_println!("USB console ready");
usb_println!("rx len = {}", 10);

API Overview

  RpUsbConsole::init(...)

  //Initializes the USB bus, CDC serial class, USB device, and global console state.

  RpUsbConsole::poll()

  //Performs USB polling, RX pumping, optional echo, and TX flushing.

  RpUsbConsole::write(data: &[u8])
  //Queues data for transmission and attempts to send it.

  RpUsbConsole::print(s: &str)
  //Prints a string without line ending.

  RpUsbConsole::println(s: &str)
  //Prints a string followed by \r\n.

  RpUsbConsole::fmt_write(args)
  //Internal helper for formatted output.

  RpUsbConsole::read(buf: &mut [u8]) -> usize
  //Reads data from the internal RX queue.

Macros

usb_print!

usb_print!("value = {}", 42);

usb_println!


usb_println!("System boot");
//These macros ultimately route data into the library TX path.

Example: Poll-Driven Echo Test

This is the simplest recommended test mode.


loop {
    RpUsbConsole::poll();

    let mut buf = [0u8; 64];
    let n = RpUsbConsole::read(&mut buf);

    if n > 0 {
        usb_println!("received {} bytes", n);
    }
}

What happens
host sends data
poll() reads the USB endpoint
data is pushed into RX queue
current library version may also echo received bytes back
read() lets your application consume the same received bytes

Example: USBCTRL_IRQ + Main Loop Logging + Echo

Recommended structure:

USBCTRL_IRQ handles low-level USB maintenance
main loop handles logging, parsing, and application logic
main loop may still call poll() as a fallback
Interrupt side
The library already provides the USB interrupt entry for supported targets.

Main loop side


loop {
    // optional fallback poll
    RpUsbConsole::poll();

    let mut buf = [0u8; 64];
    let n = RpUsbConsole::read(&mut buf);

    if n > 0 {
        usb_println!("rx {} bytes", n);
    }
}

Do not heavily log inside USBCTRL_IRQ.

Prefer doing logs in the main loop.

Example: RP2350 riscv32 main.rs



#![no_std]
#![no_main]

use panic_halt as _;

use hal::{entry, pac, Clock};
use rp235x_hal as hal;

use rp_usb_serial::{RpUsbConsole, usb_println};
use hal::xh3irq;
use riscv::interrupt;

const XTAL_FREQ_HZ: u32 = 12_000_000u32;

#[link_section = ".start_block"]
#[used]
pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();

#[entry]
fn main() -> ! {
    let mut pac = pac::Peripherals::take().unwrap();
    let mut watchdog = hal::Watchdog::new(pac.WATCHDOG);

    let clocks = hal::clocks::init_clocks_and_plls(
        XTAL_FREQ_HZ,
        pac.XOSC,
        pac.CLOCKS,
        pac.PLL_SYS,
        pac.PLL_USB,
        &mut pac.RESETS,
        &mut watchdog,
    )
    .ok()
    .unwrap();

    let mut timer = hal::Timer::new_timer0(pac.TIMER0, &mut pac.RESETS, &clocks);

    RpUsbConsole::init(pac.USB, pac.USB_DPRAM, &mut pac.RESETS, clocks.usb_clock);

    unsafe {
        xh3irq::unmask(pac::Interrupt::USBCTRL_IRQ);
        interrupt::enable();
    }

    usb_println!("RP2350 USB CDC boot");
    usb_println!("system clock = {} Hz", clocks.system_clock.freq().to_Hz());

    let mut rx_buf = [0u8; 64];

    loop {
        // keep this as a fallback even when USB interrupt is enabled
        RpUsbConsole::poll();

        let n = RpUsbConsole::read(&mut rx_buf);
        if n > 0 {
            usb_println!("received {} bytes", n);
        }

        timer.delay_ms(1000);
    }
}

Depending on your rp235x-hal version, the IRQ enable API may differ slightly.

Internal Design
The global singleton stores:

UsbDevice
SerialPort
TX queue
RX queue
TX path
write() pushes bytes into TX queue
poll() / interrupt processing flushes TX queue to host
RX path
poll() reads from USB CDC endpoint
bytes are stored into RX queue
read() retrieves those bytes from RX queue
This makes the design easier to adapt to:

line-based command parsers
binary packet handling
Modbus-like frame parsing
Echo and Logging
The current library implementation includes an internal auto-echo path in poll().

Meaning
When the host sends data:

bytes are stored into RX queue
bytes may also be queued for TX echo
This is useful for:

terminal echo testing
quick bring-up
host-device interaction debugging
Warning
If you also use usb_println! at the same time, your host terminal may show:

echoed raw input
formatted log lines
protocol payloads
all on the same CDC stream.

That is acceptable during bring-up, but not ideal for strict binary protocols.

Preparing for Modbus
This library layout is a good stepping stone toward Modbus or other frame-based protocols.

Recommended future workflow
keep poll() running regularly
collect bytes using read()
implement frame assembly / timeout logic in main loop
parse protocol payload
send response using write()
Important note
For Modbus or other binary protocols, you should avoid mixing:

auto echo
text logs
binary responses
on the same CDC stream during real protocol validation.

Recommended strategy
use echo during early testing only
reduce text logs when validating protocol frames
eventually let the CDC stream carry only request/response protocol data
USB Descriptor
The library uses different USB identity strings depending on the target.

RP2040
Manufacturer: Raspberry Pi
Product: RP2040
Serial: B8ED93AE
VID:PID = 0x2E8A:0x0003
RP2350
Manufacturer: Raspberry Pi
Product: RP2350
Serial: A74D15D8
VID:PID = 0x2E8A:0x10B0
Notes
This crate is intended for no_std embedded environments.
USB clock initialization must be completed before calling init().
If USB interrupt handling is not fully configured, call poll() regularly in the main loop.
read() consumes bytes from the internal RX queue, not directly from serial.read().
TX/RX queues are bounded; if they overflow, bytes may be dropped.
Avoid heavy formatted logging inside interrupt handlers.
For binary protocol work, avoid mixing logs and protocol traffic on the same CDC channel.
Limitations
Current implementation trade-offs include:

byte-by-byte TX flushing instead of bulk writes
bounded TX/RX queues
global singleton design
log traffic and protocol traffic may share the same CDC stream
These are acceptable for bring-up and light embedded console use, but may require refinement for high-throughput protocol applications.

Roadmap

configurable echo enable/disable API
batch writes for better throughput
queue overflow diagnostics
protocol-oriented examples
Modbus-style frame handling example
separate debug/protocol channel strategy examples

Contributing

Issues and pull requests are welcome.

If you report a platform-specific issue, please include:

target chip
architecture
target triple
HAL version
Rust version
minimal reproducible example
expected behavior vs actual behavior

License

MIT Apache-2.0 MIT OR Apache-2.0

Acknowledgements

Built on top of the embedded Rust ecosystem:

usb-device
usbd-serial
heapless
static_cell
rp2040-hal
rp235x-hal

Summary

rp-usb-serial is a compact USB CDC console layer for RP2040 and RP2350 embedded projects.

It supports:

logging
buffered RX/TX
poll-based USB maintenance
interrupt-assisted USB handling
early-stage protocol bring-up

and is especially useful when evolving from simple text-console debugging toward structured protocol processing such as Modbus.

rp-usb-serial 0.4.0

RP USB Serial Console

Overview

Features

Supported Platforms

RP2040

RP2350 ARM

RP2350 riscv32

Cargo Features

Default

RP2040

RP2350

Core Behavior

Quick Start

API Overview

Macros

Contributing

License

Acknowledgements

Summary

It supports: