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

r4dcb08_lib/
lib.rs
