r413d08_lib/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! A library for controlling the R413D08 8-channel relay module via Modbus.
3//!
4//! This crate provides two main ways to interact with the R413D08 relay module:
5//!
6//! 1.  **High-Level, Safe Clients**: Stateful, thread-safe clients that are easy
7//!     to share and use in concurrent applications. This is the recommended
8//!     approach for most users. See [`tokio_sync_safe_client::SafeClient`] (blocking)
9//!     and [`tokio_async_safe_client::SafeClient`] (`async`).
10//!
11//! 2.  **Low-Level, Stateless Functions**: A set of stateless functions that
12//!     directly map to the device's Modbus commands. This API offers maximum
13//!     flexibility but requires manual management of the Modbus context. See
14//!     the [`tokio_sync`] and [`tokio_async`] modules.
15//!
16//! ## Key Features
17//!
18//! - **Protocol Implementation**: Complete implementation of the R413D08 Modbus protocol.
19//! - **Stateful, Thread-Safe Clients**: For easy and safe concurrent use.
20//! - **Stateless, Low-Level Functions**: For maximum flexibility and control.
21//! - **Synchronous and Asynchronous APIs**: Both blocking and `async/await` APIs are available.
22//! - **Strongly-Typed API**: Utilizes Rust's type system for protocol correctness
23//!   (e.g., `Port`, `Address`, `PortState`).
24//!
25//! ## Cargo Features
26//!
27//! This crate uses feature flags to enable different functionalities and to
28//! select the desired `tokio-modbus` backend.
29//!
30//! For library users, it is recommended to disable the default features and
31//! enable only the ones you need. For example, in your `Cargo.toml`:
32//!
33//! ```toml
34//! [dependencies.R413D08]
35//! version = "0.3"
36//! default-features = false
37//! features = ["tokio-tcp-sync", "safe-client-sync"]
38//! ```
39//!
40//! ### Available Features
41//!
42//! - `tokio-rtu-sync`: Enables the synchronous (`blocking`) RTU backend.
43//! - `tokio-tcp-sync`: Enables the synchronous (`blocking`) TCP backend.
44//! - `tokio-rtu`: Enables the asynchronous (`async`) RTU backend.
45//! - `tokio-tcp`: Enables the asynchronous (`async`) TCP backend.
46//! - `safe-client-sync`: Enables the high-level, thread-safe, synchronous [`tokio_sync_safe_client::SafeClient`].
47//!   Requires either `tokio-rtu-sync` or `tokio-tcp-sync`.
48//! - `safe-client-async`: Enables the high-level, thread-safe, asynchronous [`tokio_async_safe_client::SafeClient`].
49//!   Requires either `tokio-rtu` or `tokio-tcp`.
50//! - `serde`: Enables `serde` support for the `protocol` types.
51//! - `bin-dependencies`: Enables all dependencies required for the `R413D08`
52//!   binary. This is not intended for library users.
53//!
54//! The `default` feature enables `bin-dependencies`.
55//!
56//! ## Quick Start
57//!
58//! This example shows how to use the recommended high-level, synchronous `SafeClient`.
59//!
60//! ```no_run
61//! use r413d08_lib::{
62//!     protocol::{Address, Port},
63//!     tokio_sync_safe_client::SafeClient,
64//! };
65//! use tokio_modbus::client::sync::tcp;
66//! use tokio_modbus::Slave;
67//!
68//! fn main() -> Result<(), Box<dyn std::error::Error>> {
69//!     // Connect to the device and create a stateful, safe client
70//!     let socket_addr = "192.168.1.100:502".parse()?;
71//!     let ctx = tcp::connect_slave(socket_addr, Slave(*Address::default()))?;
72//!     let client = SafeClient::new(ctx);
73//!
74//!     // Use the client to interact with the device
75//!     client.set_port_open(Port::try_from(0)?)?;
76//!     let status = client.read_ports()?;
77//!
78//!     println!("Successfully turned on relay 0. Current status: {}", status);
79//!
80//!     Ok(())
81//! }
82//! ```
83//!
84//! For more details, see the documentation for the specific client you wish to use.
85
86pub mod protocol;
87
88#[cfg_attr(
89    docsrs,
90    doc(cfg(any(
91        feature = "tokio-rtu-sync",
92        feature = "tokio-tcp-sync",
93        feature = "tokio-rtu",
94        feature = "tokio-tcp"
95    )))
96)]
97#[cfg(any(
98    feature = "tokio-rtu-sync",
99    feature = "tokio-tcp-sync",
100    feature = "tokio-rtu",
101    feature = "tokio-tcp"
102))]
103pub mod tokio_common;
104
105#[cfg_attr(
106    docsrs,
107    doc(cfg(any(feature = "tokio-rtu-sync", feature = "tokio-tcp-sync")))
108)]
109#[cfg(any(feature = "tokio-rtu-sync", feature = "tokio-tcp-sync"))]
110pub mod tokio_sync;
111
112#[cfg_attr(docsrs, doc(cfg(any(feature = "tokio-rtu", feature = "tokio-tcp"))))]
113#[cfg(any(feature = "tokio-rtu", feature = "tokio-tcp"))]
114pub mod tokio_async;
115
116#[cfg_attr(
117    docsrs,
118    doc(cfg(all(
119        feature = "safe-client-sync",
120        any(feature = "tokio-rtu-sync", feature = "tokio-tcp-sync")
121    )))
122)]
123#[cfg(all(
124    feature = "safe-client-sync",
125    any(feature = "tokio-rtu-sync", feature = "tokio-tcp-sync")
126))]
127pub mod tokio_sync_safe_client;
128
129#[cfg_attr(
130    docsrs,
131    doc(cfg(all(
132        feature = "safe-client-async",
133        any(feature = "tokio-rtu", feature = "tokio-tcp")
134    )))
135)]
136#[cfg(all(
137    feature = "safe-client-async",
138    any(feature = "tokio-rtu", feature = "tokio-tcp")
139))]
140pub mod tokio_async_safe_client;
r413d08_lib/lib.rs

r413d08_lib/
lib.rs
