Expand description
USB HID transport framing and report chunking.
When communicating with a RØDECaster over USB, messages are split into
fixed REPORT_SIZE (64-byte) HID reports. Each report begins with a
report ID byte (REPORT_ID_OUT host-to-device, REPORT_ID_IN device-to-host)
followed by up to REPORT_PAYLOAD (63 bytes) of data.
This module provides packet encoding and scanning so you can assemble incoming HID reports into complete protocol payloads and split outgoing messages into valid HID reports.
§Sending Messages
To send a message, wrap your payload in Packet and call Packet::to_bytes:
use rodecaster_protocol::usb::{Packet, REPORT_SIZE};
let payload = vec![0x01, 0x02, 0x03];
let report_bytes = Packet::new(payload).to_bytes();
// report_bytes is padded to multiples of REPORT_SIZE (64 bytes).
// Write each 64-byte report to your HID device handle:
for report in report_bytes.chunks_exact(REPORT_SIZE) {
let _ = report;
}§Receiving Messages
As reports arrive from your HID device, append them to a buffer and call
scan_frame:
use rodecaster_protocol::usb::{scan_frame, FrameScan, Packet};
let mut buffer = Vec::new();
// buffer.extend_from_slice(&incoming_report);
if let FrameScan::Complete { len } = scan_frame(&buffer) {
if let Some((packet, consumed)) = Packet::from_bytes(&buffer[..len]) {
buffer.drain(..consumed);
// Pass packet.payload to ProtocolSession::ingest
let _ = packet.payload;
}
}Re-exports§
pub use crate::frame::FrameScan;
Structs§
- Packet
- A USB HID message: the inner
bodyplus its length, framed and chunked into HID reports on the wire. The USB counterpart tocrate::Packet(no magic header).
Constants§
- HANDSHAKE_
BODY - The 4-byte body the device expects as the first message after connect to
start a full-state sync. Send
handshake_bytes; on the wire it is the framed form[04 00 00 00][AD 10 A7 B0]in one report. - MAX_
MESSAGE_ LEN - Sanity cap on a decoded message body (1 MiB). A corrupt length prefix would
otherwise wedge a streaming reader on an impossible frame; past this,
scan_framereportsFrameScan::Desync. - REPORT_
ID_ IN - HID report id for device -> host (input) reports.
- REPORT_
ID_ OUT - HID report id for host -> device (output) reports.
- REPORT_
PAYLOAD - Usable payload bytes per HID report (
REPORT_SIZEminus the report-id byte). The length-prefixed message is chunked into pieces this large. - REPORT_
SIZE - Total HID report size on the wire: one report-id byte plus the payload.
Functions§
- frame_
payload - Decode the payload of one complete message at the front of a raw HID report
buffer. Returns an owned
Vec<u8>with report IDs and padding stripped. - handshake_
bytes - The HID wire bytes (one
REPORT_SIZEreport) carrying the startup handshake (HANDSHAKE_BODY). - scan_
frame - Scan a raw HID report buffer for a complete leading message without copying
the body. The USB counterpart to
crate::scan_frame;leninFrameScan::Completeis the raw byte count to drain (a whole number ofREPORT_SIZEreports).FrameScan::Desyncmeans the length prefix is impossible (zero or overMAX_MESSAGE_LEN); drop one report and rescan.