Modbus RTU#

use pamoja_hal::port::{Parity, SerialPort, Settings};
use pamoja_modbus::{Client, Line, Server, BROADCAST};

fn word(on: bool) -> &'static str {
    if on {
        "on"
    } else {
        "off"
    }
}

// The line: 19200 baud, even parity, one stop bit, the default the Modbus specification
// sets. Eleven bits a character, and 3.5 of them of silence mark where a frame ends.
let settings = Settings::new(19_200).with_parity(Parity::Even);
let gap = Client::frame_gap(settings).as_micros() as u64;
println!(
    "line         {settings}, {} bits a character, t3.5 is {gap} us",
    settings.bits_per_character()
);

// Each device's manual gives its unit address and where its values live. The meter keeps
// its measurements in input registers from 0: volts in tenths, amps in hundredths, then a
// fault word. The relay module has four relays as coils 0 to 3, and the tank's low-level
// float switch as discrete input 0, on while the water is below it.
const METER: u8 = 17;
const PUMP: u8 = 18;
let mut line = Line::new();
line.attach(Server::new(METER)?.with_input_registers(0, &[2301, 418, 0]));
let relays = line.attach(
    Server::new(PUMP)?
        .with_coils(0, &[false; 4])
        .with_discrete_inputs(0, &[true]),
);

// The devices sit on a simulated line. On a gateway the port is
// SerialPort::open("/dev/ttyUSB0", settings), and nothing after this statement changes.
let port = SerialPort::simulated(settings, line);
let mut client = Client::new(port.clone());

// Poll the meter with function 0x04 for three input registers, and scale each one as its
// manual says.
let registers = client.read_input_registers(METER, 0, 3)?;
println!(
    "meter        {:.1} V, {:.2} A, faults {}",
    f32::from(registers[0]) / 10.0,
    f32::from(registers[1]) / 100.0,
    registers[2]
);

// What that poll cost the line: the request, the reply, and the silence before the request.
let (out, back) = (port.written(), port.received());
let line_time = settings.transfer_micros(out) + settings.transfer_micros(back) + gap;
println!(
    "poll         {out} bytes out, {back} back, {:.2} ms of line time",
    line_time as f64 / 1_000.0
);

// Read the float switch, and start the pump on relay 0 when the tank is low.
let low = client.read_discrete_inputs(PUMP, 0, 1)?[0];
println!("tank         low-level switch {}", word(low));
if low {
    client.write_single_coil(PUMP, 0, true)?;
}
let states = client.read_coils(PUMP, 0, 4)?;
let words: Vec<&str> = states.iter().map(|&on| word(on)).collect();
println!("relays       {}", words.join(" "));

// A broadcast, to unit 0, reaches every device on the line and none answers: here every
// relay off at once. The client waits out the turnaround so each device has carried it out
// before the next request.
client.write_multiple_coils(BROADCAST, 0, &[false; 4])?;
println!(
    "broadcast    every relay off, no reply, {} ms turnaround",
    client.turnaround().as_millis()
);
let after: Vec<&str> = client
    .read_coils(PUMP, 0, 4)?
    .iter()
    .map(|&on| word(on))
    .collect();
println!("relays       {}", after.join(" "));

// The meter keeps its measurements in input registers. Asking for them as holding
// registers, function 0x03, is the usual mistake with a new device, and the meter refuses
// it with an exception instead of answering.
let refused = client.read_holding_registers(METER, 0, 3);
if let Err(error) = &refused {
    println!("refused      {error}");
}

// A unit that is not on the line never answers. The client gives up after its response
// timeout, one second unless told otherwise, which a simulated line counts instead of
// sleeping through.
let before = port.waited_micros();
let silent = client.read_input_registers(19, 0, 1);
if let Err(error) = &silent {
    println!(
        "silent       {error}, {} ms counted and not slept",
        (port.waited_micros() - before) / 1_000
    );
}

import { Parity, SerialPort } from '@pamoja/hal'
import {
  BROADCAST,
  ModbusClient,
  ModbusClientError,
  ModbusLine,
  ModbusServer,
} from '@pamoja/modbus'

function word(on: boolean): string {
  return on ? 'on' : 'off'
}

async function main() {
  // The line: 19200 baud, even parity, one stop bit, the default the Modbus specification
  // sets. Eleven bits a character, and 3.5 of them of silence mark where a frame ends.
  const settings = { baud: 19200, parity: Parity.Even }
  const gap = Math.floor(ModbusClient.frameGapNanos(settings) / 1000)
  console.log(
    `line         ${SerialPort.describe(settings)}, ` +
      `${SerialPort.bitsPerCharacter(settings)} bits a character, t3.5 is ${gap} us`,
  )

  // Each device's manual gives its unit address and where its values live. The meter keeps
  // its measurements in input registers from 0: volts in tenths, amps in hundredths, then a
  // fault word. The relay module has four relays as coils 0 to 3, and the tank's low-level
  // float switch as discrete input 0, on while the water is below it.
  const METER = 17
  const PUMP = 18
  const meter = new ModbusServer(METER)
  meter.setInputRegisters(0, [2301, 418, 0])
  const relays = new ModbusServer(PUMP)
  relays.setCoils(0, [false, false, false, false])
  relays.setDiscreteInputs(0, [true])
  const line = new ModbusLine()
  line.attach(meter)
  line.attach(relays)

  // The devices sit on a simulated line. On a gateway the port is
  // SerialPort.open('/dev/ttyUSB0', settings), and nothing after this statement changes.
  const port = line.port(settings)
  const client = new ModbusClient(port)

  // Poll the meter with function 0x04 for three input registers, and scale each one as its
  // manual says.
  const registers = await client.readInputRegisters(METER, 0, 3)
  console.log(
    `meter        ${(registers[0] / 10).toFixed(1)} V, ${(registers[1] / 100).toFixed(2)} A, ` +
      `faults ${registers[2]}`,
  )

  // What that poll cost the line: the request, the reply, and the silence before the request.
  const out = port.written
  const back = port.received
  const lineTime =
    SerialPort.transferMicros(settings, out) + SerialPort.transferMicros(settings, back) + gap
  console.log(
    `poll         ${out} bytes out, ${back} back, ${(lineTime / 1000).toFixed(2)} ms of line time`,
  )

  // Read the float switch, and start the pump on relay 0 when the tank is low.
  const [low] = await client.readDiscreteInputs(PUMP, 0, 1)
  console.log(`tank         low-level switch ${word(low)}`)
  if (low) {
    await client.writeSingleCoil(PUMP, 0, true)
  }
  const states = await client.readCoils(PUMP, 0, 4)
  console.log(`relays       ${states.map(word).join(' ')}`)

  // A broadcast, to unit 0, reaches every device on the line and none answers: here every
  // relay off at once. The client waits out the turnaround so each device has carried it out
  // before the next request.
  await client.writeMultipleCoils(BROADCAST, 0, [false, false, false, false])
  console.log(`broadcast    every relay off, no reply, ${client.turnaroundMs} ms turnaround`)
  const after = await client.readCoils(PUMP, 0, 4)
  console.log(`relays       ${after.map(word).join(' ')}`)

  // The meter keeps its measurements in input registers. Asking for them as holding
  // registers, function 0x03, is the usual mistake with a new device, and the meter refuses it
  // with an exception instead of answering.
  let refused: ModbusClientError | undefined
  try {
    await client.readHoldingRegisters(METER, 0, 3)
  } catch (error) {
    refused = error as ModbusClientError
    console.log(`refused      ${refused.message}`)
  }

  // A unit that is not on the line never answers. The client gives up after its response
  // timeout, one second unless told otherwise, which a simulated line counts instead of
  // sleeping through.
  const before = port.waitedMicros
  let silent: ModbusClientError | undefined
  try {
    await client.readInputRegisters(19, 0, 1)
  } catch (error) {
    silent = error as ModbusClientError
    const waited = Math.floor((port.waitedMicros - before) / 1000)
    console.log(`silent       ${silent.message}, ${waited} ms counted and not slept`)
  }

  return { registers, out, back, low, states, relays, refused, silent }
}

main()

from pamoja.hal import Parity, SerialSettings
from pamoja.modbus import BROADCAST, ModbusClient, ModbusClientError, ModbusLine, ModbusServer


def word(on: bool) -> str:
    """A state as the output prints it."""
    return "on" if on else "off"


# The line: 19200 baud, even parity, one stop bit, the default the Modbus specification sets.
# Eleven bits a character, and 3.5 of them of silence mark where a frame ends.
settings = SerialSettings(19_200, Parity.EVEN)
gap = ModbusClient.frame_gap_nanos(settings) // 1_000
print(f"line         {settings}, {settings.bits_per_character} bits a character, t3.5 is {gap} us")

# Each device's manual gives its unit address and where its values live. The meter keeps its
# measurements in input registers from 0: volts in tenths, amps in hundredths, then a fault
# word. The relay module has four relays as coils 0 to 3, and the tank's low-level float switch
# as discrete input 0, on while the water is below it.
METER = 17
PUMP = 18
meter = ModbusServer(METER)
meter.set_input_registers(0, [2301, 418, 0])
relays = ModbusServer(PUMP)
relays.set_coils(0, [False] * 4)
relays.set_discrete_inputs(0, [True])
line = ModbusLine().attach(meter).attach(relays)

# The devices sit on a simulated line. On a gateway the port is
# SerialPort.open("/dev/ttyUSB0", settings), and nothing after this statement changes.
port = line.port(settings)
client = ModbusClient(port)

# Poll the meter with function 0x04 for three input registers, and scale each one as its manual
# says.
registers = client.read_input_registers(METER, 0, 3)
print(f"meter        {registers[0] / 10:.1f} V, {registers[1] / 100:.2f} A, faults {registers[2]}")

# What that poll cost the line: the request, the reply, and the silence before the request.
out, back = port.written, port.received
line_time = settings.transfer_micros(out) + settings.transfer_micros(back) + gap
print(f"poll         {out} bytes out, {back} back, {line_time / 1_000:.2f} ms of line time")

# Read the float switch, and start the pump on relay 0 when the tank is low.
[low] = client.read_discrete_inputs(PUMP, 0, 1)
print(f"tank         low-level switch {word(low)}")
if low:
    client.write_single_coil(PUMP, 0, True)
states = client.read_coils(PUMP, 0, 4)
print(f"relays       {' '.join(word(on) for on in states)}")

# A broadcast, to unit 0, reaches every device on the line and none answers: here every relay
# off at once. The client waits out the turnaround so each device has carried it out before the
# next request.
client.write_multiple_coils(BROADCAST, 0, [False] * 4)
print(f"broadcast    every relay off, no reply, {round(client.turnaround * 1_000)} ms turnaround")
after = client.read_coils(PUMP, 0, 4)
print(f"relays       {' '.join(word(on) for on in after)}")

# The meter keeps its measurements in input registers. Asking for them as holding registers,
# function 0x03, is the usual mistake with a new device, and the meter refuses it with an
# exception instead of answering.
refused = None
try:
    client.read_holding_registers(METER, 0, 3)
except ModbusClientError as error:
    refused = error
    print(f"refused      {error}")

# A unit that is not on the line never answers. The client gives up after its response timeout,
# one second unless told otherwise, which a simulated line counts instead of sleeping through.
before = port.waited_micros
silent = None
try:
    client.read_input_registers(19, 0, 1)
except ModbusClientError as error:
    silent = error
    waited = (port.waited_micros - before) // 1_000
    print(f"silent       {error}, {waited} ms counted and not slept")

static string Word(bool on) => on ? "on" : "off";

// The line: 19200 baud, even parity, one stop bit, the default the Modbus
// specification sets. Eleven bits a character, and 3.5 of them of silence mark where
// a frame ends.
var settings = new SerialSettings(19_200, Parity.Even);
ulong gap = ModbusClient.FrameGapNanos(settings) / 1_000;
Console.WriteLine($"line         {settings}, {settings.BitsPerCharacter} bits a character, t3.5 is {gap} us");

// Each device's manual gives its unit address and where its values live. The meter
// keeps its measurements in input registers from 0: volts in tenths, amps in
// hundredths, then a fault word. The relay module has four relays as coils 0 to 3, and
// the tank's low-level float switch as discrete input 0, on while the water is below it.
const byte Meter = 17;
const byte Pump = 18;
using var meter = new ModbusServer(Meter);
meter.SetInputRegisters(0, [2301, 418, 0]);
using var relays = new ModbusServer(Pump);
relays.SetCoils(0, new bool[4]);
relays.SetDiscreteInputs(0, [true]);
using var line = new ModbusLine().Attach(meter).Attach(relays);

// The devices sit on a simulated line. On a gateway the port is
// SerialPort.Open("/dev/ttyUSB0", settings), and nothing after this statement changes.
using SerialPort port = line.Port(settings);
using var client = new ModbusClient(port);

// Poll the meter with function 0x04 for three input registers, and scale each one as
// its manual says.
ushort[] registers = client.ReadInputRegisters(Meter, 0, 3);
Console.WriteLine(Invariant(
    $"meter        {registers[0] / 10.0:F1} V, {registers[1] / 100.0:F2} A, faults {registers[2]}"));

// What that poll cost the line: the request, the reply, and the silence before the
// request.
long bytesOut = port.Written;
long bytesBack = port.Received;
ulong lineTime = settings.TransferMicros((int)bytesOut) + settings.TransferMicros((int)bytesBack) + gap;
Console.WriteLine(Invariant(
    $"poll         {bytesOut} bytes out, {bytesBack} back, {lineTime / 1_000.0:F2} ms of line time"));

// Read the float switch, and start the pump on relay 0 when the tank is low.
bool low = client.ReadDiscreteInputs(Pump, 0, 1)[0];
Console.WriteLine($"tank         low-level switch {Word(low)}");
if (low)
{
    client.WriteSingleCoil(Pump, 0, true);
}

bool[] states = client.ReadCoils(Pump, 0, 4);
Console.WriteLine($"relays       {string.Join(' ', states.Select(Word))}");

// A broadcast, to unit 0, reaches every device on the line and none answers: here
// every relay off at once. The client waits out the turnaround so each device has
// carried it out before the next request.
client.WriteMultipleCoils(ModbusClient.Broadcast, 0, new bool[4]);
Console.WriteLine($"broadcast    every relay off, no reply, {client.Turnaround.TotalMilliseconds} ms turnaround");
bool[] after = client.ReadCoils(Pump, 0, 4);
Console.WriteLine($"relays       {string.Join(' ', after.Select(Word))}");

// The meter keeps its measurements in input registers. Asking for them as holding
// registers, function 0x03, is the usual mistake with a new device, and the meter
// refuses it with an exception instead of answering.
ModbusClientException? refused = null;
try
{
    client.ReadHoldingRegisters(Meter, 0, 3);
}
catch (ModbusClientException error)
{
    refused = error;
    Console.WriteLine($"refused      {error.Message}");
}

// A unit that is not on the line never answers. The client gives up after its response
// timeout, one second unless told otherwise, which a simulated line counts instead of
// sleeping through.
ulong before = port.WaitedMicros;
ModbusClientException? silent = null;
try
{
    client.ReadInputRegisters(19, 0, 1);
}
catch (ModbusClientException error)
{
    silent = error;
    Console.WriteLine($"silent       {error.Message}, {(port.WaitedMicros - before) / 1_000} ms counted and not slept");
}

use pamoja_hal::port::{Parity, SerialPort, Settings};
use pamoja_modbus::{Client, ClientError};

/// A USB RS485 adapter. The kernel names the first one it finds `ttyUSB0`, or `ttyACM0` for an
/// adapter that presents itself as a modem.
const PORT: &str = "/dev/ttyUSB0";

fn main() -> Result<(), Box<dyn Error>> {
    // The format every device on the line uses, from their manuals: 19200 8E1 is the default
    // the specification sets, and many meters ship at 9600 8N1 instead.
    let settings = Settings::new(19_200).with_parity(Parity::Even);
    let port = SerialPort::open(PORT, settings)?;

    // A device that is there answers within a few milliseconds, so a short response timeout
    // keeps the scan of all 247 addresses under half a minute.
    let mut client = Client::new(port).with_response_timeout(Duration::from_millis(100));

    let mut found = 0;
    for unit in 1..=247 {
        // Holding register 0 is a question any device can answer, with its value or with an
        // exception, and either proves the device is there.
        match client.read_holding_registers(unit, 0, 1) {
            Ok(values) => {
                println!("unit {unit:3}  holding register 0 is {}", values[0]);
                found += 1;
            }
            Err(ClientError::Exception { exception, .. }) => {
                let code = exception.code();
                println!("unit {unit:3}  there, and refused register 0 with exception {code:#04x}");
                found += 1;
            }
            Err(ClientError::Timeout { received: 0, .. }) => {}
            Err(error) => println!("unit {unit:3}  {error}: check the format and the wiring"),
        }
    }
    println!("{found} units answered on {PORT} at {settings}");
    Ok(())
}

cd examples/boards/raspberry-pi
cargo run --release --bin modbus

import { Parity, SerialPort } from '@pamoja/hal'
import { ModbusClient, ModbusClientError } from '@pamoja/modbus'

// A USB RS485 adapter. The kernel names the first one it finds ttyUSB0, or ttyACM0 for an
// adapter that presents itself as a modem.
const PORT = '/dev/ttyUSB0'

async function main(): Promise<void> {
  // The format every device on the line uses, from their manuals: 19200 8E1 is the default the
  // specification sets, and many meters ship at 9600 8N1 instead.
  const settings = { baud: 19200, parity: Parity.Even }
  const port = SerialPort.open(PORT, settings)

  // A device that is there answers within a few milliseconds, so a short response timeout
  // keeps the scan of all 247 addresses under half a minute.
  const client = new ModbusClient(port, { responseTimeoutMs: 100 })

  let found = 0
  for (let unit = 1; unit <= 247; unit += 1) {
    const label = `unit ${String(unit).padStart(3)}`
    // Holding register 0 is a question any device can answer, with its value or with an
    // exception, and either proves the device is there.
    try {
      const [value] = await client.readHoldingRegisters(unit, 0, 1)
      console.log(`${label}  holding register 0 is ${value}`)
      found += 1
    } catch (error) {
      if (!(error instanceof ModbusClientError)) {
        throw error
      }
      if (error.kind === 'Exception') {
        const code = (error.exception ?? 0).toString(16).padStart(2, '0')
        console.log(`${label}  there, and refused register 0 with exception 0x${code}`)
        found += 1
      } else if (!(error.kind === 'Timeout' && error.received === 0)) {
        console.log(`${label}  ${error.message}: check the format and the wiring`)
      }
    }
  }
  console.log(`${found} units answered on ${PORT} at ${SerialPort.describe(settings)}`)
}

main().catch((error: Error) => {
  console.error(error.message)
  process.exitCode = 1
})

npm --prefix bindings/node run boards
node bindings/node/build/boards/raspberry-pi/modbus.js

from pamoja.hal import Parity, SerialPort, SerialSettings
from pamoja.modbus import ModbusClient, ModbusClientError

# A USB RS485 adapter. The kernel names the first one it finds ttyUSB0, or ttyACM0 for an
# adapter that presents itself as a modem.
PORT = "/dev/ttyUSB0"


def main() -> None:
    # The format every device on the line uses, from their manuals: 19200 8E1 is the default
    # the specification sets, and many meters ship at 9600 8N1 instead.
    settings = SerialSettings(19_200, Parity.EVEN)
    port = SerialPort.open(PORT, settings)

    # A device that is there answers within a few milliseconds, so a short response timeout
    # keeps the scan of all 247 addresses under half a minute.
    client = ModbusClient(port, response_timeout=0.1)

    found = 0
    for unit in range(1, 248):
        # Holding register 0 is a question any device can answer, with its value or with an
        # exception, and either proves the device is there.
        try:
            [value] = client.read_holding_registers(unit, 0, 1)
            print(f"unit {unit:3}  holding register 0 is {value}")
            found += 1
        except ModbusClientError as error:
            if error.kind == "exception":
                print(f"unit {unit:3}  there, and refused register 0 with exception {error.exception:#04x}")
                found += 1
            elif not (error.kind == "timeout" and error.received == 0):
                print(f"unit {unit:3}  {error}: check the format and the wiring")
    print(f"{found} units answered on {PORT} at {settings}")


if __name__ == "__main__":
    main()

python bindings/python/boards/raspberry_pi/modbus.py

using Pamoja.Hal;
using Pamoja.Modbus;

namespace Boards.RaspberryPi;

/// <summary>
/// A Modbus line scan: asks every unit address on an RS485 line, through a USB adapter, which
/// devices are there. Wire the adapter's A and B to every device's A and B, join the grounds,
/// and set the line's format below to the one the devices use.
/// </summary>
public static class ModbusScan
{
    // A USB RS485 adapter. The kernel names the first one it finds ttyUSB0, or ttyACM0 for an
    // adapter that presents itself as a modem.
    private const string Port = "/dev/ttyUSB0";

    /// <summary>Asks units 1 to 247 in turn and reports every one that answers.</summary>
    public static void Run()
    {
        // The format every device on the line uses, from their manuals: 19200 8E1 is the
        // default the specification sets, and many meters ship at 9600 8N1 instead.
        var settings = new SerialSettings(19_200, Parity.Even);
        using SerialPort port = SerialPort.Open(Port, settings);

        // A device that is there answers within a few milliseconds, so a short response timeout
        // keeps the scan of all 247 addresses under half a minute.
        using var client = new ModbusClient(port) { ResponseTimeout = TimeSpan.FromMilliseconds(100) };

        int found = 0;
        for (int unit = 1; unit <= 247; unit++)
        {
            // Holding register 0 is a question any device can answer, with its value or with
            // an exception, and either proves the device is there.
            try
            {
                ushort value = client.ReadHoldingRegisters((byte)unit, 0, 1)[0];
                Console.WriteLine($"unit {unit,3}  holding register 0 is {value}");
                found++;
            }
            catch (ModbusClientException error)
            {
                if (error.Kind == ModbusClientErrorKind.Exception)
                {
                    Console.WriteLine($"unit {unit,3}  there, and refused register 0 with exception 0x{(byte)error.ExceptionCode!:x2}");
                    found++;
                }
                else if (!(error.Kind == ModbusClientErrorKind.Timeout && error.Received == 0))
                {
                    Console.WriteLine($"unit {unit,3}  {error.Message}: check the format and the wiring");
                }
            }
        }

        Console.WriteLine($"{found} units answered on {Port} at {settings}");
    }
}

dotnet run --project bindings/dotnet/samples/Pamoja.Boards -- raspberry-pi/modbus