modbus-read 0.1.0

Read-only Modbus TCP client. Only the two read function codes exist, so it cannot write to a device.
Documentation
  • Coverage
  • 100%
    79 out of 79 items documented0 out of 2 items with examples
  • Size
  • Source code size: 84.7 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 830.5 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 5s Average build duration of successful builds.
  • all releases: 5s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Volt-Labs-Technology/modbus-read
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • scull7

modbus-read

What this is

A read-only Modbus TCP client. Modbus TCP is a request/response protocol used by electricity meters and power-distribution units: a header (transaction id, protocol id, length, unit id) sits in front of a short body. This crate encodes a read, decodes the reply, and turns the 16-bit register words into numbers. Only function codes 3 (read holding registers) and 4 (read input registers) exist in the types, so a write cannot be expressed.

Who it is for

An engineer with a meter or similar device on a TCP network who needs to read registers from Rust without taking a dependency that can write.

How to use it

Add the crate to a Rust project:

cargo add modbus-read

That writes this line into Cargo.toml:

modbus-read = "0.1.0"

Minimal example. The register values below are synthetic; they are not readings from a real device.

use std::net::TcpStream;

use modbus_read::{
    read_registers, FunctionCode, ReadRequest, RegisterAddress, RegisterCount,
    TransactionId, UnitId,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut stream = TcpStream::connect("127.0.0.1:502")?;
    let request = ReadRequest::new(
        TransactionId::new(1),
        UnitId::new(1)?,
        FunctionCode::ReadHoldingRegisters,
        RegisterAddress::new(0),
        RegisterCount::new(2)?,
    )?;
    let words = read_registers(&mut stream, &request)?;
    println!("{words:?}");
    Ok(())
}

A loopback device that serves fixed synthetic registers is available behind the test-server feature. See examples/read_two_registers.rs.

What it deliberately does not do

It does not write to a device. It does not speak Modbus RTU over a serial line. It does not retry or poll; the caller owns the connection, the schedule, and the next transaction id.

Version 0.x: the API may change before 1.0.