rodecaster_protocol/lib.rs
1//! A pure-Rust protocol library for controlling RØDECaster Pro II and RØDECaster Duo audio consoles.
2//!
3//! This crate implements the binary protocol used by RØDECaster hardware and
4//! desktop applications. It provides high-level typed commands and events while
5//! leaving transport I/O (sockets, USB handles) under your control.
6//!
7//! # Architecture
8//!
9//! The library is organized into three distinct layers:
10//!
11//! 1. **Domain Layer (High-Level)**:
12//! - [`ProtocolSession`]: The main entry point for managing connection state and device lifecycle.
13//! - [`Command`]: Strongly-typed commands to mute faders, change volumes, trigger sound pads, and route audio.
14//! - [`DeviceEvent`]: Strongly-typed inbound events representing fader moves, button presses, and state updates.
15//! - [`DeviceCapabilities`]: Query physical and virtual fader counts, available input sources, and hardware model.
16//!
17//! 2. **Transport Framing**:
18//! - [`usb`]: Chunking and reassembly for 64-byte USB HID reports.
19//! - [`frame`]: Framing for TCP network streams using magic header and length prefix.
20//!
21//! 3. **Protocol Primitives (Low-Level)**:
22//! - [`valuetree`]: Parses JUCE `ValueTree` snapshots into structured [`Node`] and [`Property`] trees.
23//! - [`juce_var`]: Encodes and decodes typed [`Value`] items according to JUCE `var` binary formatting.
24//! - [`change_frame`]: Encodes and decodes granular `ValueTreeSynchroniser` change opcodes.
25//!
26//! # Quickstart
27//!
28//! Most applications interact directly with [`ProtocolSession`]:
29//!
30//! ```rust
31//! use rodecaster_protocol::{Command, Fader, ProtocolSession, SessionUpdate};
32//!
33//! # fn run() -> Result<(), Box<dyn std::error::Error>> {
34//! let mut session = ProtocolSession::new();
35//!
36//! // Pass raw payloads received from your transport (USB HID or TCP)
37//! let raw_payload: &[u8] = &[];
38//! if let Ok(update) = session.ingest(raw_payload) {
39//! match update {
40//! SessionUpdate::Ready { initial_events } => {
41//! let caps = session.capabilities().unwrap();
42//! println!("Connected to {} with {} faders", caps.model(), caps.faders().len());
43//! println!("Initial state contains {} events", initial_events.len());
44//! }
45//! SessionUpdate::Event(event) => {
46//! println!("Device event: {event:?}");
47//! }
48//! SessionUpdate::NeedsFullSync => {
49//! println!("Device topology changed; request full sync");
50//! }
51//! }
52//! }
53//!
54//! // Send commands once the session is ready
55//! if session.is_ready() {
56//! let command = Command::SetFaderMute {
57//! fader: Fader::Physical1,
58//! mute: true,
59//! };
60//! let packets = session.encode(&command)?;
61//! for packet in packets {
62//! // Send packet bytes to device via USB or TCP
63//! let _ = packet;
64//! }
65//! }
66//! # Ok(())
67//! # }
68//! ```
69
70pub mod capabilities;
71pub mod change_frame;
72pub mod commands;
73pub mod events;
74pub mod frame;
75pub mod juce_var;
76pub mod layout;
77pub mod names;
78pub mod session;
79pub mod trigger;
80pub mod usb;
81pub mod valuetree;
82
83#[doc(hidden)]
84pub mod test_fixtures;
85
86pub use capabilities::DeviceCapabilities;
87pub use change_frame::ChangeFrame;
88pub use commands::Command;
89pub use events::{
90 decode_event, decode_event_from_frame, DeviceEvent, MixLinkDirection, MixLinkRequestOrigin,
91};
92pub use frame::{frame_payload, scan_frame, FrameScan, Packet, MAGIC_HEADER};
93pub use juce_var::{read_value, Reader, Value};
94pub use layout::Layout;
95pub use names::{
96 AppParam, AudioParam, BuildParam, ChannelParam, CurrentShowParam, DeviceModel, DuckerParam,
97 EffectsParam, Fader, FxPresetParam, GuiParam, HeadphoneParam, InputSourceParam, MasterParam,
98 MeterParam, MixMinusesParam, MixOutput, NetworkParam, OutputParam, PadParam, PadRecorderParam,
99 ParseFaderError, ParseMixOutputError, ParseSourceError, PlayerParam, RadioParam, RadioRxParam,
100 RadioTxParam, RcSyncMixParam, RecorderParam, RecordingParam, RecordingsParam, ShowControlParam,
101 ShowParam, SipAdvancedParam, SipCallSlotsParam, SipCallingParam, SipRegistrationParam, Source,
102 StorageVolumeParam, StreamerXMixPresetParam, StreamerXStreamMixParam, SystemParam, TestParam,
103 ThemeParam, WifiScanResultParam,
104};
105pub use session::{ProtocolSession, SessionError, SessionUpdate};
106pub use trigger::{TriggerOrigin, TriggerPhase};
107pub use valuetree::{parse_valuetree, Node, Property};
108
109/// Compile-time guarantee that the public types stay `Send + Sync` so
110/// consumers can wrap them in `Arc<T>` and share across threads without
111/// needing the crate to opt into locking. A future field with interior
112/// mutability would fail this assertion at compile time.
113const _: () = {
114 const fn assert_send_sync<T: Send + Sync>() {}
115 assert_send_sync::<Layout>();
116 assert_send_sync::<DeviceCapabilities>();
117 assert_send_sync::<ProtocolSession>();
118 assert_send_sync::<SessionError>();
119 assert_send_sync::<SessionUpdate>();
120 assert_send_sync::<Command>();
121 assert_send_sync::<DeviceEvent>();
122 assert_send_sync::<ChangeFrame>();
123 assert_send_sync::<Value>();
124 assert_send_sync::<Node>();
125 assert_send_sync::<Packet>();
126};