HartLink
HartLink is a pure-Rust toolkit for building HART masters, gateways, diagnostic tools, and device-management applications. It covers the path from raw wire bytes to typed operations and provides an asynchronous runner that safely serializes many callers over one physical HART line.
The protocol core is no_std. Transport, queue, discovery, session, emulator,
HART-IP, DeviceInfo-style schemas, and host-side WirelessHART components are
opt-in Cargo features.
Hardware status: wired HART communication has been exercised through a transparent Moxa TCP gateway and directly through a USB HART modem. The
wireless-hartfeature is covered by software tests, but has not yet been exercised against real WirelessHART radios and Network Managers.
Understand HartLink in one minute
| If you need to... | Start with... |
|---|---|
| inspect or construct a HART frame without I/O | Address, Request, Frame, FrameDecoder, inspect_bytes |
| read a known device over TCP or serial | LinkBuilder, LinkClient, and a typed operation |
| share one line between many tasks | clone LinkClient; keep exactly one LinkRunner for the channel |
| discover devices behind a gateway or module | LineProfile and discover_line |
| send a vendor-specific command | RawOperation or a custom Operation implementation |
| isolate traffic classes on one line | define QueueConfig values and keep one QueueClient per class |
| test without hardware | the emulator, trace, and verification modules |
| use only parsing in firmware | disable default features; the wire and operation core stays no_std |
The central rule is simple: application code owns cloneable clients; the runner owns the physical stream. This prevents concurrent requests from interleaving bytes on a shared HART medium.
What is included
| Layer | Supported behavior |
|---|---|
| Wire protocol | short and long addresses, FSK and PSK, STX/ACK/BACK, up to three header-extension bytes, checksum validation, and standard or expanded commands in 0..=65535 through Command 31 |
| Streaming input | arbitrary fragmentation, bounded buffering, recovery after noise or damaged frames, local-echo removal, and stale/late-response filtering |
| Operations | typed identification, process-value, text, configuration, diagnostics, and control operations; checked raw and custom vendor operations |
| Execution | bounded queues, cancellation, coalescing of compatible reads, end-to-end deadlines, retry-safety rules, Busy retry, and delayed-response polling |
| Discovery and sessions | module address shifts, adaptive preambles, bounded hints, per-address timing, device sessions, partial snapshots, health cooldown, and adaptive read timing |
| Transports and labs | serial, transparent serial-over-TCP, byte-exact record/replay, PCAP-NG capture, in-memory emulation, and bounded fault injection |
| Optional models | DeviceInfo-style schemas, bounded FDI/ZIP extraction, HART-IP Version 1 Token-Passing sessions, and software-tested host-side WirelessHART state management |
HartLink preserves unknown values and raw payloads instead of inventing their meaning. Typed support requires a known public, licensed, or vendor-provided payload definition.
Hardware validation status
| Path | Current evidence |
|---|---|
| transparent serial-over-TCP | exercised with real HART 5, 6, and 7 devices through a Moxa gateway |
| direct wired HART | exercised with real devices through a USB HART modem |
| emulator and fault injection | covered by automated fragmentation, noise, timeout, retry, queue, and resource-limit tests |
| WirelessHART | software-tested host-side state only; real radio, gateway, and Network Manager validation is still pending |
Hardware observations are interoperability evidence for the tested setup, not FieldComm certification or a guarantee for every modem and device revision.
Installation
The default build provides the asynchronous runtime and transparent TCP transport:
[]
= "0.3"
Choose only the hardware and subsystems the application actually uses:
# Parser, encoder, inspector, operations, and common tables; no std or Tokio.
= { = "0.3", = false }
# Runtime with both transparent TCP and serial transports.
= { = "0.3", = ["serial"] }
# Every optional subsystem, useful for a desktop laboratory tool.
= { = "0.3", = ["full"] }
Architecture
src/
├── wire/ addresses, delimiters, frames, checksum, streaming decoder
├── operation/ domain-oriented request and response semantics
├── catalog.rs explicit command class and retry-safety registry
├── inspect.rs frame and complete-exchange validation
├── service/ queue, runner, session, discovery, Burst, and transfer
├── channel/ independent TCP and serial byte channels
├── device/ dynamic schemas for specific devices
├── ip.rs HART-IP packet session
├── mesh/ software-tested host-side WirelessHART mechanisms
├── emulator.rs in-memory link, device, noise, and failures
├── trace.rs recording, PCAP-NG, and deterministic replay
└── profile.rs link, module, address-offset, and timing settings
The wire layer does not depend on typed operations. Operations do not depend on
Tokio, TCP, or serial ports. Only LinkRunner owns the physical channel, while
LinkClient can be cloned for independent application components.
Feature selection
| Feature | Purpose |
|---|---|
| no features | no_std wire types, operations, inspector, and tables |
runtime |
queue, runner, session, and Tokio integration |
tcp |
transparent serial-over-TCP channel |
serial |
serial modem channel |
device-info |
dynamic schemas and JSON catalog |
fdi-package |
bounded loading of matching JSON profiles from ZIP/FDI containers |
hart-ip |
HART-IP Version 1 packet session and Token-Passing adapter |
wireless-hart |
experimental host-side admission, key custody, replay protection, graph, routes, and schedules; real hardware validation pending |
emulator |
in-memory link, device, and fault injection |
cli |
local frame inspector and request builder |
full |
every library subsystem |
Features are additive. The default set is runtime + tcp; enabling serial
does not disable TCP. The full feature is convenient for tools and labs, but
libraries should normally enable only the required pieces.
Check the minimal core with:
cargo check --no-default-features
Quick start: inspect a frame without hardware
This path needs no runtime, socket, or serial port. It is suitable for packet inspectors, capture analysis, and embedded applications:
use ;
let address = polling?;
let bytes = new
.to_frame?
.encode?;
let report = inspect_bytes.map_err?;
assert_eq!;
# Ok::
Quick start: read a device through transparent TCP
Create the channel once, start one runner, and clone the client wherever the application needs access to the line:
use Duration;
use ;
use ;
use ReadDeviceIdentity;
# async
To scan a known polling range instead of addressing one known device, reuse the same client and describe the physical line explicitly:
use Master;
use ;
use discover_line;
# use LinkClient;
# async
An execute call covers the complete lifecycle below. Its total deadline starts
before enqueueing, so time spent waiting behind other commands is never hidden.
Queues and scheduling
Every link contains an application-defined layout of one to 256 independently bounded queues. There is no separate one-queue mode and no built-in traffic class: one queue, two queues, and a larger layout all use the same scheduler. Queue identifiers are small values chosen by the application; they do not change the HART frame or consume bytes on the physical line.
Weighted queues rotate without starvation. Their weights describe relative shares only while several queues are ready. Empty queues never create an artificial pause. Strict queues are selected before every weighted queue; larger strict ranks win and equal ranks rotate fairly. Continuous strict work can intentionally starve weighted work, so strict priority is explicit.
| Configuration | Scheduling behavior |
|---|---|
| one weighted queue | bounded global FIFO |
several queues with weight 1 |
fair round-robin |
weights 6, 2, and 1 |
starvation-free relative shares 6:2:1 |
strict rank 20 and strict rank 10 |
rank 20 is drained first; equal ranks rotate |
| strict plus weighted queues | every ready strict queue precedes weighted work |
The following is complete Rust configuration, not YAML or pseudocode:
use ;
# use MemoryChannel;
#
Each queue enforces its own capacity before accepting a request. The builder
also validates duplicate IDs, the selected default queue, queue count,
individual capacity, and total capacity. A QueueClient is permanently bound
to its queue, so application components do not repeat a queue selector for
every command.
One queue
The default builder already creates one bounded FIFO. An explicit one-queue layout is useful when the application wants a different identifier or capacity:
use ;
# use MemoryChannel;
#
Routing and command admission
Routing runs before admission. The policy therefore sees the effective queue.
A rejected request consumes neither queue capacity nor a request identifier and
increments LinkSnapshot::denied:
use ;
# use MemoryChannel;
#
Built-in policies include allow-all, read-only, retry-safe, command allow-list,
command deny-list, and an allow-list for one effective queue. The read-only
and retry-safe policies trust only the built-in command registry: a caller
cannot bypass them by changing Request::retry_safety. An unknown vendor
command must be admitted explicitly, for example by composing a reviewed
command allow-list with or. Policies can be combined with and or or;
CommandPolicy::custom receives the full immutable request, both effective and
catalog safety, and the effective queue. Admission is a local safety
boundary, not authentication or authorization of a remote user.
Managed device health and adaptive timing
ManagedDeviceSession adds an optional health layer around an identified
DeviceSession. Repeated transport outages open a bounded cooldown, so callers
fail locally instead of filling the shared queue with requests to an offline
device. A deliberate probe can bypass cooldown only for a command that the
built-in catalog classifies as read-only. Request metadata and vendor safety
claims cannot widen that exception.
Successful read-only exchanges teach a smoothed response duration. A later read may use one shorter first attempt and then fall back to the caller's conservative timeout. This optimization consumes, rather than adds, one transport retry and never extends the original end-to-end deadline. Writes, actions, unknown commands, Busy handling, and delayed-response polling retain their caller-selected behavior.
use ;
use ;
# use DeviceSession;
#
Partial device snapshots
DeviceSession::snapshot collects identity, process values, tags, and
additional status without turning one unsupported or failed command into the
loss of every successful field. Each requested field is represented as a
value, a retained command error, or an explicit unsupported state. Optional
groups can be disabled with SnapshotOptions, including an identity-only
snapshot that performs no I/O.
use ;
# async
Damaged-frame policy
Checksum validation is strict by default. Known hardware defects must be
enabled explicitly with ChecksumPolicy::KnownGateway. Every frame accepted by
that policy carries a FrameRepair value; unrelated checksum mismatches are
never repaired automatically.
Device warnings
Typed operations reject every nonzero response code by default. If the exact
command specification or exact-revision DeviceInfo marks a code as a warning,
pass only that code to execute_accepting. The returned CommandOutcome<T>
contains both the decoded value and the original response code/device status.
Communication-error summaries are never accepted as application warnings.
Arbitrary and vendor commands
RawOperation and Request support every logical command number in
0..=65535; commands above 255 are carried through Command 31. The crate does
not invent unknown payload layouts. A vendor codec can implement Operation,
and a known read-only or idempotent vendor operation can explicitly declare its
retry safety. Unknown operations remain Action, so uncertain transport
failures are not retried automatically.
Commands that derive calibration from a live physical input, including 36 and 37, are also classified as actions. A missing response therefore never causes HartLink to repeat the physical calibration automatically.
The shorter constructors make that intent visible at the call site:
RawOperation::read, RawOperation::idempotent_write, and
RawOperation::action.
Resource and timeout guarantees
- the streaming decoder retains only its configured tail and never copies an oversized fragment before applying that limit;
- validated link construction rejects zero, undersized, or implausibly large queues and buffers before calling Tokio allocation primitives;
- a trace is bounded independently by record count and total payload bytes;
- deterministic replay validates both step count and aggregate payload size and stops immediately when an iterator exceeds either budget;
- transparent TCP connection establishment has a ten-second default deadline
and an explicit
connect_with_timeoutvariant; zero or implausibly large connect, keepalive, and HART-IP durations are rejected; - direct HART-IP use has socket and whole-exchange deadlines, so a peer cannot keep one request alive indefinitely by publishing unrelated packets;
- HART-IP Publish retention, stale correlation, Burst fingerprints, subscriber backlogs, package extraction, and block receive buffers are bounded;
- frame inspectors reject input larger than any canonical HART frame before decoding Base64 or hexadecimal payloads;
- emulator queues, injected noise, direct transmissions, fragmentation, and artificial latency have hard safety bounds with strict constructors;
- cooldown, adaptive timing, and all retry durations have explicit hard limits, and cooldown rejection occurs before queue capacity or request identifiers are consumed.
LinkBuilder, RetryPolicy, LinkConfig, TcpOptions, TimingProfile,
LineProfile, DiscoveryOptions, BurstConfig, TraceLimits, ReplayLimits,
PackageLimits, CatalogLimits, TableRepositoryLimits, DeviceHealthOptions,
AdaptiveTiming, and SnapshotOptions provide fluent setters for common
configuration. Request::try_new, ReplayChannel::new,
MemoryChannel::try_pair, and MemoryChannel::try_set_faults reject invalid
input at the call site. Public fields remain available when direct construction
is clearer.
Safe adaptive discovery
Selected physical polling addresses can receive an additional pre-probe delay and their own response timeout without slowing every other address. Overrides use the address after applying a confirmed module shift:
use Duration;
use ;
let timings = new.with?;
# Ok::
Pass this set to discover_line_with_address_timings; ordinary
discover_line and discover_line_with_options retain the line-wide timing.
discover_line_with_options scans each configured address sequentially and
skips addresses already identified on an earlier pass. A complete pass exits
immediately when every configured address answered, so extra passes do not add
an unconditional delay.
DiscoveryHints may contain a previously confirmed request-preamble count for
an exact short address. Hints are bounded and validated, affect only the first
probe, and never supply identity or prove that a device is present. If a hinted
probe times out, discovery immediately retries that address with the
conservative LineProfile::discovery_preambles value and the configured retry
budget. DiscoveryReport::hinted_attempts and hint_fallbacks expose both
paths for monitoring and regression tests.
Discovery remains serialized because a HART physical link is a shared medium. Running address probes in parallel would make frames collide and is not a safe performance optimization.
WirelessHART hardware feedback
The wireless-hart feature has automated coverage for admission decisions,
key erasure, replay protection, topology, routes, schedules, and resource
limits. It has not yet been validated against a broad matrix of real radios,
gateways, Network Managers, and device firmware. HartLink therefore does not
claim complete over-the-air interoperability or FieldComm conformance.
This limitation applies specifically to WirelessHART. The ordinary wired HART path has already been exercised through a transparent Moxa TCP gateway and a direct USB HART modem.
If real hardware behaves differently, open a WirelessHART hardware report. A useful report contains:
- the HartLink version or commit and enabled Cargo features;
- host OS, gateway or Network Manager model, device model, and firmware revisions;
- the exact operation, expected result, actual result, and whether the failure is repeatable;
- monotonic timestamps and the event order leading to the failure;
- a minimal sanitized configuration plus logs;
- the smallest raw hexadecimal dump, PCAP-NG capture, or byte-exact trace that reproduces the behavior.
Do not publish join keys, network or session keys, passwords, private certificates, licensed specification text, proprietary DeviceInfo packages, or unrelated production traffic. Replace secrets with fixed placeholders while preserving byte lengths and message ordering. Hardware reports are used to add a regression case first and then adjust the implementation without guessing.
Boundaries
The built-in catalog does not replace licensed Common Tables, Command Summary, Common Practice Commands, Block Transfer, or vendor DeviceInfo content. The current internal JSON model is DeviceInfo-style; it is not a complete importer for every official DeviceInfo XML/JSON revision. Unknown values and raw payload bytes are preserved, but their semantics must come from a lawfully available source.
The HART-IP feature implements the publicly documented Version 1 stream session and Token-Passing PDU path, including TCP. It does not claim UDP session-port handling, Direct PDU, later protocol-version security, or official HART-IP conformance. The WirelessHART feature is software-tested host-side state machinery, not a hardware-validated radio stack, cryptographic join implementation, or complete Network Manager. The host-side manager exposes no unauthenticated join shortcut: applications must provide a verifier, keys are redacted and zeroized, and replacing a key invalidates active state. The block helper enforces bounded ordering but does not claim the complete licensed Block Transfer 2.0 command state machine.
HART 7.10 introduced specification revisions and Command 554. HartLink can carry Command 554 through the raw expanded-command API, but a typed codec must not be added without the normative request/response format. Local tests prove the implemented software contracts; they are not FieldComm Group product certification or evidence of electrical interoperability.
Official entry points: