motorcortex_rust/lib.rs
1//! Rust client for the [Motorcortex] real-time control system.
2//!
3//! Implements the wire protocol defined by `motorcortex.proto` over
4//! NNG + WebSocket Secure: request/reply for parameter access,
5//! publish/subscribe for real-time streaming, and the session-token
6//! dance that keeps long-lived connections alive through reverse
7//! proxies and transient server restarts.
8//!
9//! Two frontends share one actor-style core:
10//!
11//! - [`core`] — async (tokio-driven). The recommended surface.
12//! Handles are `Clone + Send + Sync`; multiple tasks share one
13//! connection safely.
14//! - [`blocking`] — thin sync wrapper for scripts, tests, and code
15//! that doesn't want a tokio runtime in `main()`. Same method
16//! names and semantics, just without `.await`.
17//!
18//! # Example — async round-trip
19//!
20//! ```no_run
21//! use motorcortex_rust::core::Request;
22//! use motorcortex_rust::{ConnectionOptions, Result};
23//!
24//! # async fn demo() -> Result<()> {
25//! let opts = ConnectionOptions::new("tests/mcx.cert.crt".into(), 5000, 5000);
26//! let req = Request::connect_to("wss://127.0.0.1:5568", opts).await?;
27//! req.login("root", "secret").await?;
28//! req.request_parameter_tree().await?;
29//!
30//! let value: f64 = req.get_parameter("root/Control/dummyDouble").await?;
31//! println!("{value}");
32//!
33//! req.disconnect().await?;
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! See the [`examples/`] directory for blocking, subscribe-latest,
39//! and subscribe-stream flavours, and [ARCHITECTURE.md] for the
40//! design rationale — actor driver, three-sink subscription model,
41//! reconnect + session-token machinery.
42//!
43//! [Motorcortex]: https://www.vectioneer.com/motorcortex
44//! [`examples/`]: https://git.vectioneer.com/pub/motorcortex-rust/-/tree/master/examples
45//! [ARCHITECTURE.md]: https://git.vectioneer.com/pub/motorcortex-rust/-/blob/master/ARCHITECTURE.md
46
47pub mod blocking;
48mod client;
49mod connection;
50pub mod core;
51mod error;
52mod msg;
53mod nng_init_threads;
54mod nng_logger;
55mod parameter_value;
56mod time_spec;
57mod url;
58
59pub use client::{ParameterTree, Parameters};
60pub use connection::ConnectionOptions;
61pub use core::ConnectionState;
62pub use error::{MotorcortexError, Result};
63pub use msg::*;
64pub use nng_init_threads::*;
65pub use nng_logger::*;
66pub use parameter_value::{GetParameterValue, SetParameterValue};
67pub use time_spec::TimeSpec;
68pub use url::parse_url;