Skip to main content

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};