Files
eddys_snippets/modbus_params/Readme.md

323 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# modbus_params
**modbus_params** is a command-line tool and network server for interacting with Modbus RTU
devices. It uses a human‑readable **dictionary** that maps register addresses to mnemonic codes,
supports periodic dumping of selected parameters to a TSV file, and provides a TCP/UNIX socket
interface for remote access.
The project is hosted at:
[https://github.com/eddyem/eddys_snippets/tree/master/modbus_params](https://github.com/eddyem/eddys_snippets/tree/master/modbus_params)
## Features
- Read and write Modbus holding registers by **address** or **mnemonic code**.
- Define a dictionary (`code → register`) with optional comments and read‑only flags.
- Read discrete inputs and coils (all at once or one bit), write coils (all at once or one bit).
- Dump selected registers periodically to a TSV file.
- Start a **TCP or UNIX socket server** that accepts commands to:
- Read/write registers (by code or address).
- Read discrete inputs / coils; write coils.
- List dictionary entries or aliases.
- Start/stop and rename the dump file.
- Define **aliases** – macros that expand to other commands or expressions.
- Verbose logging with configurable level.
## Dependencies
- [libmodbus](https://libmodbus.org/) (Modbus RTU backend)
- [usefull_macros](https://github.com/eddyem/snippets_library) (argument parsing, socket helpers,
logging macros)
- POSIX threads (pthread)
- Standard C library
## Building
Clone the repository together with the required submodule:
```bash
git clone --depth=1 https://github.com/eddyem/eddys_snippets.git
cd eddys_snippets/modbus_params
```
Then compile with `make`:
```bash
make
```
The resulting executable is named `modbus_params`. You can copy this file wherever you want, e.g.
```bash
su -c "cp modbus_params /usr/local/bin
```
## Command‑line usage
```
modbus_params [options]
```
### General options
| Option | Argument | Description |
|--------|-------------------|-------------|
| `-h`, `--help` | – | Show help and exit |
| `-v`, `--verbose` | – | Increase verbosity (can be used multiple times) |
| `-D`, `--dictionary` | *file* | Dictionary file (format: `code register value readonly`). *Required for most operations.* |
| `-a`, `--alias` | *file* | Aliases file (format: `name : command`). Optional. |
| `-s`, `--slave` | *ID* | Modbus slave ID (default: 1) |
| `-d`, `--device` | *path* | Serial device (default: `/dev/ttyUSB0`) |
| `-b`, `--baudrate` | *rate* | Baud rate (default: 9600) |
### Read/write operations
| Option | Description |
|--------|-------------|
| `-r`, `--readr` *addr* | Read register by address (multiply: `-r 100 -r 200`) |
| `-R`, `--readc` *code* | Read register by dictionary code (multiply) |
| `-w`, `--writer` *addr=val* | Write value to register by address (multiply) |
| `-W`, `--writec` *code=val* | Write value to register by dictionary code (multiply) |
| `-O`, `--outdic` *file* | Read **all** registers listed in the dictionary and save them (with current values) into a new dictionary file |
### Discrete I/O sizes
| Option | Argument | Description |
|--------|-------------------|-------------|
| `-i`, `--inputs` | N | Number of bytes for discrete inputs (default: 1) |
| `-c`, `--coils` | N | Number of bytes for coils/outputs (default: 1) |
### Dumping (periodic TSV output)
| Option | Description |
|--------|-------------|
| `-k`, `--dumpkey` *code* | Add a dictionary key to the dump list (multiply) |
| `-o`, `--outfile` *file* | TSV file for the dump |
| `-t`, `--dumptime` *seconds* | Dump interval (default: 0.1 s) |
### Server mode
| Option | Description |
|--------|-------------|
| `-N`, `--node` *spec* | Start a server. For TCP: IP address or hostname with port after ':' (e.g. `:1212` or `localhost:1212`). For UNIX socket: a path (e.g. `/tmp/mb_sock`). |
| `-U`, `--unixsock` | Use UNIX domain socket instead of TCP (requires `-N` with a path) |
If `-N` is given, the program runs as a server **after** executing any immediate read/write/dump
operations. The server stays alive until interrupted (Ctrl+C).
## File formats
### Dictionary file
Each line defines one register. Empty lines and text after `#` are ignored.
Format:
```
<code> <register> <value> <readonly>
```
- `code` – mnemonic string (no spaces).
- `register` – 16‑bit Modbus address (decimal).
- `value` – initial/default value (16‑bit, not used by the tool except for documentation).
- `readonly` – `0` (writable) or `1` (read‑only).
Example (from `dictionary.dic`):
```
F00.00 61440 1 0 # Motor management (V/F)
F00.01 61441 0 0 # Selecting the START command task
...
A02.01 41473 0 1 # Output frequency (read-only)
```
### Aliases file
Aliases provide a way to define shortcuts or composite commands.
Format:
```
name : expression # optional comment
```
The `expression` is a string that will be interpreted as a command (register read/write, another
alias, or a built‑in server command). Aliases are resolved recursively.
Example:
```
stop : F00.00=0 # stop motor
start : F00.00=1 # start motor
freq : F00.11 # read current frequency
```
When the server receives `stop`, it writes `0` to register mapped to `F00.00`.
### Dump file (TSV)
When dumping is active, the tool writes a tab-separated file with a header line:
```
# time,s <code1> <code2> ...
```
Each subsequent line contains a timestamp (seconds since dump start) followed by the current value
of each registered key. Unreadable registers are shown as `----`.
Example:
```
# time,s F00.00 F00.11
0.000 1 5000
0.102 1 5000
```
## Server protocol
The server listens for plain text commands, terminated by newline (`\n`).
Each command is a key‑value pair: `key[=value]`.
- **Getter** – just the key → returns current value.
- **Setter** – `key=value` → writes the value (if the register is writable).
### Built‑in keys (handlers)
| Key | Description |
|-----|-------------|
| `list` | As a getter: prints the whole dictionary (one line per entry). As a setter (e.g. `list=F00.01`): prints details of the given code or register address. |
| `alias` | Getter: prints all aliases. Setter (e.g. `alias=myalias`): prints that specific alias. |
| `newdump` | Getter: returns current dump file name. Setter (e.g. `newdump=/path/file.dump`): closes current dump file (if any), opens a new one and starts dumping. |
| `clodump` | Stops the dump thread and closes the dump file. No value expected. |
| `readcoils` | Getter: read **all** coils as HEX (uses `--coils` bytes, e.g. `readcoils = 0x00FF`). With `[N]` (e.g. `readcoils[0]`): read a **single** coil (returns 0 or 1). |
| `readinputs` | Getter: read **all** discrete inputs as HEX (uses --inputs bytes). With [N]: read a **single** discrete input. |
| `writecoils` | Setter: write **all** coils from a number (e.g. `writecoils = 0` to clear all, `writecoils = 0x0F` to set several). With `[N]` (e.g. `writecoils[4] = 1`): write a **single** coil. |
### Default handler (register access)
If the key is **not** a built‑in handler, the program tries to interpret it as:
- A **register address** (decimal integer) → find the corresponding dictionary entry.
- A **dictionary code** → find the entry.
- An **alias** → recursively expand and execute.
Then:
- **Getter** (only key) → reads the register and replies `key = value`.
- **Setter** (`key = value`) → writes the value to the register (if not read‑only) and replies `OK`.
### Examples (using `netcat`, `telnet` or `socat`)
**TCP server** (assuming `-N :5020`):
```
$ nc localhost 5020
F00.00
F00.00=1
F00.00=0
OK
list=F00.01
F00.01 61441 0 0 # Selecting the START command task
newdump=/tmp/motor.dump
OK
clodump
OK
```
**UNIX socket**:
```
$ socat - UNIX-CONNECT:/tmp/mb_sock
F00.11
F00.11=5000
```
**Discrete I/O** (assuming `-c 2 -i 1`):
```
readcoils
readcoils = 0x0000
writecoils = 0x000F
OK
readcoils
readcoils = 0x000F
readcoils[0]
readcoils[0] = 1
readcoils[1]
readcoils[1] = 1
writecoils[4] = 1
OK
readcoils[4]
readcoils[4] = 1
writecoils = 0
OK
readcoils
readcoils = 0x0000
readinputs
readinputs = 0x05
readinputs[0]
readinputs[0] = 1
```
## Examples
### 1. Simple read by address
```bash
modbus_params -D dictionary.txt -s 1 -d /dev/ttyUSB0 -b 9600 -r 61440
```
### 2. Write a value using a code
```bash
modbus_params -D dictionary.txt -W "F00.00=1"
```
### 3. Dump two registers every 0.5 seconds to `data.tsv`
```bash
modbus_params -D dictionary.txt -k F00.00 -k F00.11 -o data.tsv -t 0.5
```
(No server started – the program will dump until interrupted.)
### 4. Start a local server with dumping already active
```bash
modbus_params -D dictionary.txt -k F00.00 -o /tmp/dump.csv -t 1 -N localhost:5020
```
Now you can connect to port 5020 and use `newdump` to change the output file, or `clodump` to stop.
### 5. Read all dictionary registers and save current values
```bash
modbus_params -D dictionary.dic -O current_state.dic
```
### 6. Server with discrete I/O
```bash
modbus_params -D dictionary.dic -c 2 -i 1 -N :5020
```
Now readcoils/writecoils operate on 16 coils, readinputs on 8 inputs.
## Signals
- `SIGINT` (Ctrl+C), `SIGTERM`, `SIGQUIT` – gracefully close Modbus, dump files, and exit.
- `SIGHUP`, `SIGTSTP` – ignored (no action).
## Notes
- The dictionary is **shared** between the main program and the server thread. Do not modify the
dictionary file while the program is running.
- The dump thread uses a separate timer; if a read operation hangs, the dump may stall.
- When using UNIX sockets, the path can be prefixed with `\0` or `@` (for abstract sockets).
The program accepts plain paths for filesystem sockets.
- The `usefull_macros` library provides the `sl_dtime()` high‑resolution timer and thread‑safe
logging macros.
## License
Copyright 2022 Edward V. Emelianov <edward.emelianoff@gmail.com>.
GNU General Public License v3 or later.
Full text of the GPLv3 is available at <https://www.gnu.org/licenses/gpl-3.0.html>.