NYMEA-MODBUS-CLI(1)

NAME
nymea-modbus-cli - inspect, read, and write Modbus TCP, TLS, and RTU devices

SYNOPSIS
nymea-modbus-cli --address address [TCP-options] [request-options]
nymea-modbus-cli --serial device [RTU-options] [request-options]
nymea-modbus-cli --address address --tls-info [TLS-options]
nymea-modbus-cli --list-serials

DESCRIPTION
nymea-modbus-cli is a diagnostic command-line client for Modbus TCP, Modbus TCP over TLS, and Modbus RTU. It can read input or holding registers and discrete inputs or coils, write a value, inspect a TLS endpoint without sending Modbus traffic, and list local serial ports.

Select exactly one transport using --address for TCP or --serial for RTU. A normal read or write also requires a register address. The --tls-info and --list-serials modes do not require one.

GENERAL OPTIONS

-h, --help
    Display command-line help and exit.

--help-all
    Display command-line help including generic Qt options and exit.

-v, --version
    Display version information and exit.

-d, --debug
    Print additional connection and protocol information.

--list-serials
    List serial ports detected on the host and exit.

TCP OPTIONS

-a, --address address
    Connect to the specified Modbus TCP server IP address.

-p, --port port
    Set the TCP port. The default is 502 for plain Modbus TCP and 802 when TLS is enabled.

--tls
    Use Modbus TCP over TLS.

TLS OPTIONS

--tls-version version
    Select the TLS protocol. Supported values are auto and 1.2. The default is auto.

--tls-fingerprint sha256
    Accept only a server certificate whose DER-encoded SubjectPublicKeyInfo has the specified SHA-256 fingerprint. Hexadecimal fingerprints may contain colons or whitespace.

--tls-accept-any-fingerprint
    Accept the SPKI fingerprint presented by the server during each handshake. This disables server identity verification and cannot be combined with --tls-fingerprint. The connection remains encrypted but is vulnerable to a man-in-the-middle attack. Use this option only for controlled diagnostics.

--tls-server-name name
    Set the TLS server name used for Server Name Indication (SNI) and certificate hostname verification.

--tls-client-certificate file
    Present the PEM client certificate in file. The file may contain the leaf certificate followed by intermediate certificates. This option requires --tls-client-key.

--tls-client-key file
    Read the PEM EC or RSA client private key from file. This option requires --tls-client-certificate.

--tls-client-key-passphrase-file file
    Read the client private-key passphrase from file. One trailing newline is ignored. This option requires --tls-client-key.

--tls-info
    Perform a TLS handshake, print connection timing, negotiated protocol and cipher, session information, and the server certificate chain, then exit without sending Modbus traffic. This option enables TLS and uses port 802 unless --port is supplied.

RTU OPTIONS

--serial device
    Use Modbus RTU through the serial device, for example /dev/ttyUSB0.

--baudrate baud
    Set the serial baud rate. The default is 19200. Common values include 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200.

--parity parity
    Set serial parity to none, even, odd, space, or mark. The default is none.

--databits bits
    Set the number of data bits to 5, 6, 7, or 8. The default is 8.

--stopbits bits
    Set the number of stop bits to 1, 1.5, or 2. The default is 1.

MODBUS REQUEST OPTIONS

-m, --modbus-address id
    Set the Modbus server address (unit or slave ID). The default is 1. Address 0 must be selected using --broadcast.

--broadcast
    Send the request to Modbus server address 0. This option cannot be combined with an explicit --modbus-address.

-t, --type type
    Select the register type: input, holding, discrete, or coils. The default is holding.

-r, --register register
    Set the first Modbus register address.

-l, --length count
    Set the number of registers or bits to read. The default read count is 1. For a write, the count is inferred from the data; an explicitly supplied length must match it.

-w, --write data
    Write holding registers or coils instead of reading. Holding-register data may be a decimal or hexadecimal word, a comma-separated word list, or compact hex. Compact value 0x00010002 writes words 0x0001 and 0x0002 to consecutive addresses. Coil lists accept 0, 1, false, and true.

--output format
    Select table, json, or legacy output. The default is table.

--decode type
    Decode register data as uint16, int16, uint32, int32, uint64, int64, float32, or float64. This option may be repeated. The read length must be divisible by the selected type's register width.

--byte-order order
    Set byte order inside each 16-bit register used by --decode to big or little. The default is big.

--word-order order
    Set word order inside each decoded value to forward or reverse. The default is forward.

REGISTER REPRESENTATION
The table output for holding and input registers shows raw hex, signed and unsigned 16-bit interpretations in both byte orders, and escaped ASCII. It also shows the complete response in bulk raw and ASCII forms. Coils and discrete inputs are shown as Boolean values.

Byte order affects the two bytes within each register. Word order affects the sequence of 16-bit registers within each decoded 32- or 64-bit value. Raw compact write data always uses wire order: the leftmost word is written to the lowest address.

TLS AUTHENTICATION
Without --tls-fingerprint, normal CA and hostname validation is used. When validation fails, the CLI prints the server SPKI-SHA256 fingerprint so it can be verified out of band and supplied to a subsequent invocation.

The CLI does not save fingerprints, certificates, private keys, or TLS sessions. A fingerprint passed with --tls-fingerprint is valid only for that invocation.

EXAMPLES
Read two holding registers over plain Modbus TCP:

    nymea-modbus-cli -a 192.168.0.10 -p 502 -r 1000 -l 2

Read register 1000 over TLS 1.2 with an SPKI pin:

    nymea-modbus-cli -a 192.168.0.10 --tls --tls-version 1.2 \
        --tls-fingerprint 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
        -r 1000

Inspect a TLS endpoint without sending Modbus traffic:

    nymea-modbus-cli -a 192.168.0.10 --tls-info --tls-version 1.2 \
        --tls-accept-any-fingerprint

Read two holding registers over Modbus RTU:

    nymea-modbus-cli --serial /dev/ttyUSB0 --baudrate 9600 -r 1000 -l 2

Write decimal value 16 to holding register 200:

    nymea-modbus-cli -a 192.168.0.10 -r 200 -w 16

Write two holding registers using compact hexadecimal data:

    nymea-modbus-cli -a 192.168.0.10 -r 200 -w 0x00010002

Decode two registers as both an unsigned integer and IEEE-754 float:

    nymea-modbus-cli -a 192.168.0.10 -r 200 -l 2 \
        --decode uint32 --decode float32

Write four coils:

    nymea-modbus-cli -a 192.168.0.10 -t coils -r 20 \
        --write true,false,1,0

EXIT STATUS
Returns zero after a successful request, TLS inspection, or serial-port list. Returns non-zero for invalid arguments, connection or TLS failures, Modbus errors, and unsuccessful reads or writes.

FILES

/usr/share/bash-completion/completions/nymea-modbus-cli
    Bash command completion definitions.

SECURITY
Prefer a verified CA chain or an independently verified SPKI fingerprint. Private-key passphrases should be supplied using --tls-client-key-passphrase-file rather than placed directly on the command line. Protect all client private keys and passphrase files from other users.

SEE ALSO
openssl(1), bash(1)

AUTHORS
nymea GmbH and chargebyte austria GmbH.