Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/embedded/chip/rp_usb"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
executor |
std/embedded/executor |
rp_usb.dodo |
hal |
std/embedded/hal |
rp_usb.dodo |
io |
std/io |
rp_usb.dodo |
mem |
core/mem |
rp_usb.dodo |
ptr |
core/ptr |
rp_usb.dodo |
rp_pins |
std/embedded/chip/rp_pins |
rp_usb.dodo |
serial |
std/embedded/hal/serial |
rp_usb.dodo |
PACKET_SIZE
Constant · Source
pub const PACKET_SIZE: usize = 64
Identity
Struct · Source
The device’s identity on the bus: the vendor and product IDs a host matches drivers and tools against, and the manufacturer and product strings it shows. The IDs name the device and its firmware, not the library it was built with.
pub struct Identity {
pub vendor_id: u16
pub product_id: u16
// ASCII, cut at MAX_STRING_LENGTH bytes.
pub manufacturer: &str
pub product: &str
}
DEFAULT_VENDOR_ID
Constant · Source
The default identity’s IDs, for development: Raspberry Pi’s vendor ID with the product ID of the Pico SDK’s USB serial port (CDC UART). Hosts and tools take a board using them for a Pico running Pico SDK firmware, which the device behaves like, and
dodo runfinds it by them to restart it into the bootloader. A product distributed with its own USB identity uses a vendor ID its maker owns, or a product ID assigned to it under someone else’s, never another product ID under Raspberry Pi’s.
pub const DEFAULT_VENDOR_ID: u16 = 0x2E8A
DEFAULT_PRODUCT_ID
Constant · Source
pub const DEFAULT_PRODUCT_ID: u16 = 0x000A
DEFAULT_MANUFACTURER
Constant · Source
pub const DEFAULT_MANUFACTURER: &str = "Dodo"
MAX_STRING_LENGTH
Constant · Source
The longest manufacturer and product strings, in bytes of ASCII.
pub const MAX_STRING_LENGTH: usize = 32
default_identity
Function · Source
The default identity, with the default IDs and manufacturer, and
productas the product string.
pub fn default_identity(product: &str) -> Identity
TX_CAPACITY
Constant · Source
Queue sizes. Output is kept while no terminal has the port open, up to TX_CAPACITY bytes, and input until the program reads it: the host waits while RX_CAPACITY - PACKET_SIZE bytes are unread.
pub const TX_CAPACITY: usize = 1024
RX_CAPACITY
Constant · Source
pub const RX_CAPACITY: usize = 256
BOOTLOADER_BAUD
Constant · Source
The baud rate that, set by the host, restarts the board into its USB bootloader: the “1200 baud touch” of the Pico SDK and Arduino.
pub const BOOTLOADER_BAUD: u32 = 1200
DTR
Constant · Source
The control lines a terminal sets (SET_CONTROL_LINE_STATE).
pub const DTR: u32 = 1 << 0
RTS
Constant · Source
pub const RTS: u32 = 1 << 1
RECEIVED
Constant · Source
What
servedid, one bit each: bytes arrived, bytes left, the host configured or deconfigured the device, changed DTR or RTS, suspended or resumed it, and a 1200-baud line coding asks for the bootloader.
pub const RECEIVED: u32 = 1 << 0
SENT
Constant · Source
pub const SENT: u32 = 1 << 1
LINE_CHANGED
Constant · Source
pub const LINE_CHANGED: u32 = 1 << 2
BOOTLOADER_REQUESTED
Constant · Source
pub const BOOTLOADER_REQUESTED: u32 = 1 << 3
Device
Struct · Source
The device over controller registers R. See the package comment.
pub struct Device<R: hal.Registers> {
// Private implementation fields omitted.
}
Device.new
Function · Source
A stopped device on controller registers
registersand DPRAMram. Newline translation is on: see set_crlf.
pub fn new(registers: R, ram: R) -> Device<R>
Device.start
Function · Source
Power the controller up as a device with
identityand connect to the host, which then enumerates it. The controller must be out of reset with clk_usb at 48 MHz.
pub fn start(&mut self, identity: Identity)
Device.stop
Function · Source
Disconnect from the host and power the controller down. Queued output is dropped.
pub fn stop(&mut self)
Device.serve
Function · Source
Answer the host: handle finished buffers, a SETUP packet, a bus reset, and suspension, and keep both bulk endpoints busy. Returns what happened, as RECEIVED, SENT, LINE_CHANGED, and BOOTLOADER_REQUESTED bits. Run it from the controller’s interrupt, or poll it.
pub fn serve(&mut self) -> u32
Device.queue
Function · Source
Queue the start of
bytesfor the host, as far as there is room, and return how many were queued. With newline translation, a “\n” goes out as “\r\n” and needs room for both.
pub fn queue(&mut self, bytes: &[u8]) -> usize
Device.take
Function · Source
Move received bytes into
bufferand return how many. With newline translation, the CR that Enter sends, alone or followed by LF, reads as one “\n”.
pub fn take(&mut self, buffer: &mut[u8]) -> usize
Device.make_room
Function · Source
Drop the oldest queued output until
countbytes fit, for a message that must go out, such as a panic report.
pub fn make_room(&mut self, count: usize)
Device.set_crlf
Function · Source
Write “\n” as “\r\n” and read Enter as “\n”, for terminals. On at first; turn it off for binary data.
pub fn set_crlf(&mut self, on: bool)
Device.set_bootloader_reset
Function · Source
Whether a 1200-baud line coding restarts the board into its bootloader; on at first.
pub fn set_bootloader_reset(&mut self, on: bool)
Device.is_configured
Function · Source
The host has configured the device: it is enumerated, and the port exists on the host.
pub fn is_configured(&self) -> bool
Device.is_connected
Function · Source
A program on the host has the port open: configured, with DTR set, as terminals do while open.
pub fn is_connected(&self) -> bool
Device.line_state
Function · Source
DTR and RTS as the host last set them.
pub fn line_state(&self) -> u32
Device.baud
Function · Source
The baud rate the host last set. It changes nothing on USB, but tells a bridge to another serial port what to use.
pub fn baud(&self) -> u32
Device.unsent
Function · Source
Bytes queued for the host and not yet taken by it.
pub fn unsent(&self) -> usize
Device.room
Function · Source
Room for output, in bytes.
pub fn room(&self) -> usize
Device.available
Function · Source
Received bytes not yet taken.
pub fn available(&self) -> usize
Device.frame
Function · Source
The frame number of the host’s last start-of-frame, 0 to 2047, counting milliseconds while the bus runs.
pub fn frame(&mut self) -> u32
Device.release
Function · Source
Give back the register blocks, after
stop.
pub fn release(self) -> (R, R)
WRITE_TIMEOUT_FRAMES
Constant · Source
Frames (milliseconds) a write waits for the host to take output from a full queue before it drops the rest, and status polls as a bound when frames stop.
pub const WRITE_TIMEOUT_FRAMES: u32 = 100
open
Function · Source
Start the device on the controller at
registerswith its DPRAM atram, announcing itself withidentity, and return its port. Writes queue at once; the host enumerates the device within a second of connection, after which a terminal can open it.bootloaderrestarts the chip into its USB bootloader. The caller enables USBCTRL_IRQ in the NVIC. SAFETY: the controller must be out of reset with clk_usb at 48 MHz, no port may be open, and nothing else may use the controller.
pub unsafe fn open(registers: usize, ram: usize, identity: Identity, bootloader: fn()) -> Serial
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
close
Function · Source
Disconnect and stop the device of
serial. The caller disables USBCTRL_IRQ and holds the controller in reset afterwards.
pub fn close(serial: Serial)
report_panic
Function · Source
Queue a panic report, as rp_pins.report_panic writes it, and wait until the host has taken it, the port is closed, or PANIC_TIMEOUT_FRAMES pass. Older output makes room if needed. Does nothing without an open port. SAFETY:
checkandfilemust be NUL-terminated, and interrupts must be masked for good: the caller halts or resets afterwards.
pub unsafe fn report_panic(check: *const u8, file: *const u8, line: u32, column: u32)
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
idle_after_panic
Function · Source
Keep serving an open port forever with interrupts masked, after a panic: a terminal opened later still receives the report, and a host can still restart the board into its bootloader. Returns at once without a port. SAFETY: interrupts must be masked for good, as in a panic hook.
pub unsafe fn idle_after_panic()
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
Serial
Struct · Source
The USB serial port, as chip packages hand it out. Implements the std/io Reader and Writer protocols, so std/fmt prints to it. Every method is safe to call at any time; the interrupt handler serves the host in between.
pub struct Serial: serial.Port + serial.PollPort {
// Private implementation fields omitted.
}
Serial.write
Function · Source
Queue
bytesfor the host and return once they are queued. While no terminal has the port open, output is kept up to TX_CAPACITY bytes, for the terminal to receive when it opens it, and the rest is dropped. While one has it open, a full queue waits for the host, and output the host does not take within WRITE_TIMEOUT_FRAMES ms is dropped, so printing never stops the program. Never fails.
pub fn write(&mut self, bytes: &[u8]) -> usize!io.Error
Serial.poll_write
Function · Source
Queue what fits without waiting; Pending, with what was queued, once the queue is full.
pub fn poll_write(&mut self, bytes: &[u8]) -> io.Poll!io.Error
Serial.poll_flush
Function · Source
flushwithout waiting: true once the host has taken everything written, or no terminal has the port open. Never fails.
pub fn poll_flush(&mut self) -> bool!io.Error
Serial.flush
Function · Source
Wait until the host has taken everything written, while a terminal has the port open and the host keeps taking output; as write, it gives up after WRITE_TIMEOUT_FRAMES ms without progress. Never fails.
pub fn flush(&mut self) -> void!io.Error
Serial.read
Function · Source
Wait for the first byte, then return what has arrived, up to
buffer.len. A USB serial port never reaches end of input.
pub fn read(&mut self, buffer: &mut[u8]) -> usize!io.Error
Serial.poll_read
Function · Source
Return what has arrived without waiting; Pending while nothing has.
pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error
Serial.is_connected
Function · Source
Whether a program on the host has the port open (DTR set), so that what is written now is read now.
pub fn is_connected(&self) -> bool
Serial.is_configured
Function · Source
Whether the host has enumerated and configured the device.
pub fn is_configured(&self) -> bool
Serial.line_state
Function · Source
DTR and RTS, as the host last set them.
pub fn line_state(&self) -> u32
Serial.baud
Function · Source
The baud rate the host last set; 115200 until it sets one.
pub fn baud(&self) -> u32
Serial.available
Function · Source
Received bytes waiting to be read.
pub fn available(&self) -> usize
Serial.set_crlf
Function · Source
Write “\n” as “\r\n” and read Enter as “\n”, for terminals. On at first; turn it off for binary data.
pub fn set_crlf(&mut self, on: bool)
Serial.set_bootloader_reset
Function · Source
Whether the host setting 1200 baud restarts the board into its bootloader, as
dodo rundoes; on at first.
pub fn set_bootloader_reset(&mut self, on: bool)
Serial.set_signal
Function · Source
Raise
signalfrom the interrupt whenever something happens on the port: bytes arrive, output leaves, or the host connects, opens, closes, or suspends it. A task that takes the signal and then reads withpoll_readis woken by input; see std/embedded/executor.
pub fn set_signal(&mut self, signal: &executor.Signal)
Serial.clear_signal
Function · Source
Stop raising the signal.
pub fn clear_signal(&mut self)