Metadata-Version: 2.1
Name: modpoll2mqtt
Version: 2.1.1
Summary: Modbus to MQTT gateway — fork of modpoll
Home-page: https://github.com/yoch/modpoll2mqtt
License: MIT
Keywords: modbus,modpoll,mqtt,gateway,bridge,iot,industrial-automation,building-automation,modbus-tcp,modbus-rtu,modbus-udp,cli
Author: yoch
Author-email: yoch.melka@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Provides-Extra: serial
Requires-Dist: paho-mqtt (>=2.1.0,<3.0.0)
Requires-Dist: prettytable (>=3.9.0,<4.0.0)
Requires-Dist: pymodbus (>=3.10,<4.0)
Requires-Dist: pyserial (>=3.5,<4.0) ; extra == "serial"
Requires-Dist: requests (>=2.32.5,<3.0.0)
Project-URL: Documentation, https://yoch.github.io/modpoll2mqtt
Project-URL: Repository, https://github.com/yoch/modpoll2mqtt
Description-Content-Type: text/markdown

# modpoll2mqtt — Modbus to MQTT Gateway

[![Release](https://img.shields.io/github/v/release/yoch/modpoll2mqtt?label=release)](https://github.com/yoch/modpoll2mqtt/releases/latest)
[![Build status](https://img.shields.io/github/actions/workflow/status/yoch/modpoll2mqtt/main.yml?branch=main)](https://github.com/yoch/modpoll2mqtt/actions/workflows/main.yml?query=branch%3Amain)
[![License](https://img.shields.io/pypi/l/modpoll2mqtt)](https://github.com/yoch/modpoll2mqtt/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pepy/dt/modpoll2mqtt)](https://pepy.tech/projects/modpoll2mqtt)

> Documentation: [yoch.github.io/modpoll2mqtt](https://yoch.github.io/modpoll2mqtt)

**modpoll2mqtt** is a command-line Modbus-to-MQTT gateway. It polls Modbus devices (RTU, TCP, UDP) using CSV configuration files, publishes values to an MQTT broker, and accepts write commands by CSV reference name.

Install the PyPI package as `modpoll2mqtt`; the executable command remains `modpoll`.

Fork of [modpoll](https://github.com/gavinying/modpoll), with semantic MQTT writes by CSV reference name and CTA (air handling unit) examples.

## Features

- Modbus RTU, TCP, and UDP (CSV configuration files)
- Local display of polled data (debug mode)
- MQTT publishing of references (configurable topics)
- Optional MQTT retain on data publishes (`--mqtt-retain`)
- MQTT writes by CSV reference name (`modpoll/<device>/set`)
- Local CSV export of polled data
- Bit-level access on registers and coils

## Installation

Python 3.10+ required.

```bash
pip install modpoll2mqtt
```

Optional serial support (pyserial):

```bash
pip install 'modpoll2mqtt[serial]'
```

Upgrade:

```bash
pip install -U modpoll2mqtt
```

On Windows, [pipx](https://pypa.github.io/pipx/installation/) is recommended:

```powershell
pipx install modpoll2mqtt
```

## Quickstart

Single poll of a Modbus TCP device (replace the IP address with yours):

```bash
modpoll --once \
  --tcp 192.168.1.10 \
  --config examples/modsim.csv
```

Publish to an MQTT broker:

```bash
modpoll \
  --tcp 192.168.1.10 \
  --mqtt-host broker.emqx.io \
  --config examples/modsim.csv
```

Data is published to `modpoll/<device_name>/data` by default.

Add `--mqtt-retain` so the broker keeps the last data message per topic for new subscribers. Diagnostics topics are never retained. If a device goes offline, retained values may still appear live until the next successful publish.

### MQTT write by reference

Once connected to the broker, `modpoll` subscribes to `modpoll/+/set`. Publish to `modpoll/<device>/set`:

```json
{
  "PID_V3V_EC_Consigne_reprise": 21.5,
  "BP_MA_CTA": true
}
```

Unknown reference names in the payload are skipped with a warning.

Example with [`examples/CTA/cta_conf_restaurant.csv`](examples/CTA/cta_conf_restaurant.csv): an `int16` reference with scale `0.1` accepts `21.5` as input; the raw register value `215` is written.

**Migration from modpoll 1.6.x:** the low-level format (`object_type`, `address`, `value`) is no longer supported.

### Configuration pitfalls

- On **coil** or **discrete_input** pollers, use `bool` with the **absolute Modbus coil address** for a single boolean.
- `bool8` / `bool16`: legacy grouped reads (group index, not a direct coil address).
- On **holding_register** or **input_register**, use `bool` with `address:bit` (0–15), e.g. `40019:15,bool`.
- `<endian>` must be `BE_BE`, `LE_BE`, `LE_LE`, or `BE_LE` only.
- `--autoremove` disables a poller after 3 consecutive Modbus failures.

## Examples

```bash
# Modbus TCP
modpoll --tcp 192.168.1.10 --config examples/modsim.csv

# Modbus serial
modpoll --serial /dev/ttyUSB0 --serial-baud 9600 --config contrib/eniwise/scpms6.csv

# MQTT + CSV export
modpoll --tcp 192.168.1.10 --mqtt-host localhost --export data.csv --config examples/modsim.csv

# Multiple config files
modpoll --tcp 192.168.1.10 --config examples/modsim.csv examples/modsim2.csv

# CTA (building automation example)
modpoll --tcp 192.168.1.20 --mqtt-host localhost --config examples/CTA/cta_conf_restaurant.csv
```

See [`examples/`](examples/) and [`contrib/`](contrib/) for more device configurations.

## Credits

This project builds on:

- [modpoll](https://github.com/gavinying/modpoll) — Ying Shaodong (MIT)
- [modbus2mqtt](https://github.com/owagner/modbus2mqtt) — Oliver Wagner (MIT)
- [spicierModbus2mqtt](https://github.com/mbs38/spicierModbus2mqtt) — Max Brueggemann (MIT)

## License

MIT — see [LICENSE](LICENSE).

