embassy-usb

Crates

git

Versions

default

Flavors

Skip to main content

Module io_box

Module io_box 

Source
Expand description

USB Audio Class 2.0 - audio I/O box

Line out (host to device) and line in (device to host) in one audio function, in the IO_BOX category. Both streams are asynchronous: line out reports the device’s sample rate through an explicit feedback endpoint, and line in sizes its packets after it.

It works at full and high speed, whichever Config::max_speed builds the descriptors for: one packet per frame (1 ms) at full speed, one per microframe (125 µs) at high speed.

CLOCK_SOURCE (internal programmable)
└── CLOCK_SELECTOR (one input)
    ├── IT (USB streaming) → [FU] → OT (line connector)   line out
    └── IT (line connector) → [FU] → OT (USB streaming)   line in

Both directions share one clock, so macOS groups them into one device. The clock selector is for Linux, which otherwise doesn’t start the feedback endpoint.

Each direction has any number of channels the bandwidth allows. At high speed that’s one packet of up to 1024 bytes per microframe, so for example 13 channels of 24-bit audio at 192 kHz, 26 at 96 kHz. At full speed it’s one packet of up to 1023 bytes per frame, and all periodic endpoints share 90 % of a frame (1350 bytes), so for example stereo 24-bit audio at 96 kHz both ways. The channels are either numbered (Channels::Numbered, the usual choice for an interface’s inputs and outputs) or speaker positions (Channels::Spatial).

N, a const generic on the class’s types, is the room for Feature Unit settings: the master plus the channels of the direction with more of them. Without Feature Units it can be 0.

Stereo in and out at 48 or 96 kHz, 24-bit, with a volume control on each output:

ⓘ
use embassy_usb::class::uac::device::SampleWidth;
use embassy_usb::class::uac::device::uac2::io_box::{self, Channels, Config, FeatureUnitControls, IoBox, State};
use embassy_usb::UsbDeviceSpeed;

const RATES: [u32; 2] = [48_000, 96_000];
const SPEED: UsbDeviceSpeed = UsbDeviceSpeed::High;
// the stream buffers: frames of one microframe at 96 kHz, plus one, 6 bytes each
const MAX_PACKET: usize = io_box::max_packet_size(SPEED, 96_000, SampleWidth::Width3Byte, 2);

// room for the Feature Unit: the master and two channels
let mut config = Config::<3>::new(&RATES, SampleWidth::Width3Byte, Channels::Numbered(2), Channels::Numbered(2));
let v = FeatureUnitControls::VOLUME;
config.line_out_feature_unit = [FeatureUnitControls::empty(), v, v].into_iter().collect();
let mut io = IoBox::new(&mut builder, state, config);

// each in its own task, after `wait_connection()`:
let n = io.line_out.read_packet(&mut buf).await?; // what the host plays
io.line_in.write_packet(&frames).await?; // what the device records, one packet's worth
// the device's sample rate, 16.16 samples per packet, every packet or so
io.feedback.write_packet((((rate_hz as u64) << 16) / io_box::packet_rate_hz(SPEED) as u64) as u32).await?;

// the rate the host selected, and the first output's volume
let hz = io.control_monitor.sample_rate_hz();
let volume = io.control_monitor.line_out_volume(0);

Re-exports§

pub use super::super::Volume;

Structs§

Config
I/O box stream settings and optional host controls.
ControlMonitor
Control status change monitor.
FeatureUnitControls
Supported control flags. Combine flags with |, for example Self::MUTE | Self::VOLUME.
Feedback
Line out’s explicit feedback endpoint: the device’s sample rate in samples per packet (packet_rate_hz).
Interrupt
The AudioControl interrupt endpoint: tells the host which controls the device changed itself, so it reads them again. Keep Self::run running.
IoBox
USB Audio Class 2.0 I/O box: line out + line in with explicit feedback.
LineInStream
Line in stream (device to host, isochronous IN endpoint).
LineOutStream
Line out stream (host to device, isochronous OUT endpoint).
State
Internal state for the I/O box.
VolumeRange
The volume range a Feature Unit advertises, in whole dB.

Enums§

Channels
The channels of one direction, as the host is told about them.

Functions§

max_packet_size
The isochronous packet size a direction needs: the audio frames of one packet at the highest rate, plus one for the rate to drift, times the frame size. Size the stream buffers with it.
packet_rate_hz
Packets per second on each streaming endpoint: one per frame at full speed, one per microframe at high speed, and one per 125 us bus interval at SuperSpeed.