Skip to main content

hart_link/
lib.rs

1//! Tools for communicating with HART devices.
2//!
3//! The architecture separates wire-byte representation, operation semantics,
4//! and exchange execution. Core types and the streaming decoder are available
5//! without the standard library. The asynchronous queue and network channels
6//! are enabled by the `runtime` feature.
7//!
8//! # Hardware validation status
9//!
10//! Wired HART communication has been exercised with real devices through a
11//! transparent Moxa TCP gateway and directly through a USB HART modem. The
12//! `wireless-hart` feature is covered by software tests but has not yet been
13//! exercised against real WirelessHART radios and Network Managers. See the
14//! `mesh` module for the reporting format and safety requirements for dumps.
15//!
16//! # Minimal wire example
17//!
18//! ```
19//! use hart_link::{Address, Master, Request, inspect_bytes};
20//!
21//! let address = Address::polling(0, Master::Primary)?;
22//! let bytes = Request::new(address, 0u8, vec![]).to_frame()?.encode()?;
23//! let report = inspect_bytes(&bytes).map_err(|issue| issue.message)?;
24//! assert_eq!(report.command.get(), 0);
25//! # Ok::<(), Box<dyn std::error::Error>>(())
26//! ```
27//!
28//! # Application-defined queues
29//!
30//! Runtime users define one or more independently bounded queues. Weighted queues rotate
31//! without starvation; strict queues explicitly precede weighted traffic.
32//!
33//! ```
34//! # #[cfg(feature = "runtime")]
35//! # {
36//! use hart_link::{QueueConfig, QueueId, QueuePriority};
37//!
38//! const CONTROL: QueueId = QueueId::new(10);
39//! const POLLING: QueueId = QueueId::new(20);
40//! let queues = [
41//!     QueueConfig::strict(CONTROL, 32, 10)?,
42//!     QueueConfig::weighted(POLLING, 256, 1)?,
43//! ];
44//! assert_eq!(queues[0].priority(), QueuePriority::strict(10));
45//! # }
46//! # Ok::<(), Box<dyn std::error::Error>>(())
47//! ```
48
49#![cfg_attr(not(feature = "std"), no_std)]
50#![forbid(unsafe_code)]
51#![warn(missing_docs, rustdoc::broken_intra_doc_links)]
52
53extern crate alloc;
54
55/// Registry of known operations and their declared properties.
56pub mod catalog;
57/// Validation and explanation of complete frames.
58pub mod inspect;
59/// Typed operations grouped by purpose.
60pub mod operation;
61/// Versioned common tables that preserve unknown codes.
62pub mod tables;
63/// Link-layer byte representation and streaming decoding.
64pub mod wire;
65
66/// I/O channels for physical and network links.
67#[cfg(feature = "runtime")]
68pub mod channel;
69/// Dynamic descriptions of devices and application fields.
70#[cfg(feature = "device-info")]
71pub mod device;
72/// Test and link-emulation facilities.
73#[cfg(feature = "emulator")]
74pub mod emulator;
75/// HART-IP packet transport.
76#[cfg(feature = "hart-ip")]
77pub mod ip;
78/// Software-tested host-side WirelessHART mechanisms; real hardware validation is pending.
79#[cfg(feature = "wireless-hart")]
80pub mod mesh;
81/// Bounded DeviceInfo extraction from an FDI package.
82#[cfg(feature = "fdi-package")]
83pub mod package;
84/// Physical-link, gateway, and device-discovery profiles.
85#[cfg(feature = "runtime")]
86pub mod profile;
87/// Exchange queue, runner, and device session.
88#[cfg(feature = "runtime")]
89pub mod service;
90/// Metric snapshots independent of a specific observability system.
91#[cfg(feature = "runtime")]
92pub mod telemetry;
93/// Recording and replay of byte-exact exchanges.
94#[cfg(feature = "runtime")]
95pub mod trace;
96/// Local functional campaigns against an emulator or hardware.
97#[cfg(feature = "runtime")]
98pub mod verification;
99
100pub use catalog::{
101    CommandClass, CommandDescriptor, OperationSafety, PayloadConstraint, command_descriptor,
102    request_constraint,
103};
104pub use inspect::{
105    ExchangeReport, FrameReport, InspectionIssue, MAXIMUM_INSPECTION_TEXT_BYTES, inspect_base64,
106    inspect_bytes, inspect_exchange, inspect_hex,
107};
108pub use operation::{
109    CheckedOperation, CommandCode, CommandOutcome, DeviceReply, Operation, OperationError,
110    RawOperation, Request,
111};
112pub use wire::{
113    Address, ChecksumPolicy, DecodeEvent, DecodeLimits, DecodeLimitsError, Frame, FrameDecoder,
114    FrameKind, FrameRepair, MAX_ENCODED_FRAME_SIZE, MAXIMUM_DECODE_BUFFER_CAPACITY,
115    MAXIMUM_DECODE_EVENTS_PER_PUSH, Master, PhysicalLayer, WireError,
116};
117
118#[cfg(feature = "runtime")]
119pub use service::{
120    AdaptiveTiming, CommandContext, CommandPolicy, CommandRouting, DEFAULT_LATE_RESPONSE_GUARD,
121    DeviceHealthConfigError, DeviceHealthOptions, DeviceHealthSnapshot, DeviceSnapshot,
122    ExchangeError, LinkBuildError, LinkBuilder, LinkClient, LinkConfig, LinkConfigError, LinkEvent,
123    LinkRunner, LinkSnapshot, MAXIMUM_LATE_RESPONSE_GUARD, MAXIMUM_LINK_DECODER_BUFFER,
124    MAXIMUM_LINK_EVENT_CAPACITY, MAXIMUM_LINK_QUEUES, MAXIMUM_LINK_READ_BUFFER,
125    MAXIMUM_QUEUE_CAPACITY, MAXIMUM_RETRY_DURATION, MAXIMUM_TOTAL_QUEUE_CAPACITY,
126    MAXIMUM_TRANSMIT_PREFIX, ManagedDeviceSession, ManagedSessionError, PendingReply, QueueClient,
127    QueueConfig, QueueConfigError, QueueError, QueueId, QueuePriority, QueueSnapshot, RetryCause,
128    RetryPolicy, RetryPolicyError, SnapshotError, SnapshotField, SnapshotOptions, StartError,
129    create_link, try_create_link,
130};