Changelog
2.4.1 (2026-10-20)
Fixes
restore publication of every reference in
--mqtt-singlemode when two--mqtt-keyslabels collide (e.g. a reference name containing|matching another reference’s name/unit); 2.4.0 could silently omit one topic
2.4.0 (2026-10-20)
Features
add
--mqtt-on-changeto publish data only when MQTT-formatted values change, with per-reference--mqtt-singleupdates and cache invalidation after reconnects, publish errors, and device recovery
2.3.1 (2026-10-11)
Fixes
make pyserial optional again now that pymodbus 3.16.1 imports without it (pymodbus#3042); pymodbus 3.16.0 is excluded. Serial/RTU users install
modpoll2mqtt[serial], as before 2.3.0
2.3.0 (2026-10-11)
Features
add
--check-configfor whole-configuration validation without opening Modbus/MQTT transportsadd
--read-onlyto reject all MQTT writes and--modbus-bit-write maskfor optional atomic FC22 register updatesadd
--poller-recover-afterfor optional re-probing after--autoremovedisables a polleradd
--mqtt-namespaceand--mqtt-command-topic-patternfor isolated gateway topics and versioned get/set commands with per-reference results and bounded process-local request deduplicationadd
--mqtt-max-payload-bytes,--mqtt-queue-bytes,--mqtt-tx-queue-size, and--mqtt-command-ttlto bound command resources and ageadd
--mqtt-shutdown-timeout,--mqtt-session-expiry, and--mqtt-pass-filefor publication flushing, explicit persistent sessions, and file-based credentialsexpose per-reference quality/acquisition times and MQTT rejection/publication/subscription counters in diagnostics
Fixes
bind references to their declared function code/endian instead of the first overlapping range; retain distinct aliases when identical pollers are reused
reject unsafe numeric writes before bus I/O; make register bit writes inverse to decoding; target only the declared coil group
clear failed/short/non-finite decodes without retaining a stale current value; isolate a malformed UTF-8 string from other references
saturate reconnect backoff, schedule with monotonic time, avoid counting unattempted polls, disable pymodbus write retries, and guarantee transport cleanup
ignore retained commands (MQTT 5 preserves retain on live delivery), reject malformed/duplicate-key JSON, bound incoming/outgoing queues, reconnect MQTT asynchronously, and republish retained presence after reconnect
aggregate all configurations into one atomic JSON export and report partial writes/uncertain acknowledgements without blind replay
repair shipped SDM120M permissions, SmartLogger dtype, and TriStar duplicate names (second occurrences use their address suffix)
require pyserial so the package still imports with pymodbus 3.16.0, which fails without it (pymodbus#3042); the
serialextra is kept for compatibility
BREAKING CHANGES
invalid CSV entries previously skipped now abort startup (exit 2); device names must be unique across files, scales finite/nonzero, IDs/ranges/dtypes/permissions valid
unsigned overflow no longer wraps; out-of-range, non-finite, fractional unscaled integer writes and oversized UTF-8 strings are rejected; scaled integer writes round the scaled raw value
TLS 1.0/1.1 are rejected; sessions are ephemeral by default at every QoS; explicit persistent sessions require
--mqtt-clientid--onceruns polling only and returns 1 on poll/runtime/MQTT publication failure; command responses are never retained, even with--mqtt-retainlegacy SET now returns per-reference results on
<request-topic>/response; all known writes are validated before any are attempted, and conflicting ranges in a single command are rejectedshipped
contrib/configurations changed: TriStar duplicate names are renamed (their MQTT topics and payload keys change), SDM120M permissions and the SmartLogger dtype are corrected
Tests and CI
add regression coverage for the audit defects, all supported numeric endians, strict commands, batch prevalidation, lost acknowledgements, queue budgets, recovery, atomic export, and exit codes
run real CLI/Modbus/MQTT 5 and 3.1.1 exchanges with local Mosquitto and independent slave/object spaces; required CI integration cannot silently skip missing infrastructure
test minimum/latest pymodbus, install built wheels outside the source tree with the serial extra, build docs with warnings as errors on PRs, and require these gates before publishing ## 2.2.1 (2026-06-16)
Internal
add strict static typing with basedpyright across
modpoll/; introducemodpoll/types.pyand enforcemake typecheckin local and CI quality gatesextract
Device,Poller, andReferenceintomodpoll/modbus_models.py(orchestration remains inmodbus_task.py)replace black with ruff for format and lint
Documentation
add typing audit baseline in
docs/typing-audit.mdextend contributor release checklist and harden the
on-release-mainworkflow
Tests
import device models from
modpoll.modbus_modelsin unit tests
2.2.0 (2026-06-16)
Features
MQTT on-demand read (get): subscribe on
modpoll/+/get(--mqtt-get-topic-pattern); publish{"ref": null}tomodpoll/{device}/get; response onmodpoll/{device}/get/responsewith partial success (unknown or failed refs omitted); targeted Modbus reads viareference_read.pywith adjacent register batchingPersistent Modbus connection:
ModbusConnectionManagerkeeps the client open between poll cycles and MQTT commands; non-blocking exponential reconnect backoff (--modbus-backoff-base,--modbus-backoff-max); optional connection recycle (--modbus-max-connection-age)enrich per-device MQTT diagnostics with
config_source, get/set counters (get_count,get_errors,get_success,get_unknown_refs,get_read_errors,set_count,set_errors,set_success,set_unknown_refs)publish process-wide health on
modpoll/diagnostics(mqtt_connected,modbus_ok,devices_failing,last_cycle_s, Modbus connection state and reconnect metrics)publish process presence on
modpoll/statuswith last-will (online: false) and birth message (online: true); status is always retainedapply
--mqtt-retainto diagnostics topics (same policy as data publishes)
BREAKING CHANGES
``–interval`` default is now transport-aware:
0.0s for TCP/UDP (was0.5s); serial/RTU derives the RTU 3.5-character frame gap from--serial-baudwith a0.005s floor. Set--intervalexplicitly for slow devices.Modbus connect/close per poll cycle removed: the client stays open until shutdown or a transport failure; on serial/RTU the port remains reserved while
modpollrunsMQTT multi-reference writes now use
--intervalbetween successive refs in onesetmessage (was a fixed0.1s delay)
Documentation
document MQTT get, persistent connection, transport-aware
--interval, and extended diagnostics indocs/usage.rst
Tests
add
tests/test_modbus_connection.py, extendtests/test_main_get.pyfor backoff, connection reuse, and diagnostic countersmigrate Modbus lifecycle tests to
ModbusConnectionManager
2.1.2 (2026-06-15)
Features
warn at config load when a reference is marked
w/rwon adiscrete_inputorinput_registerpoller (Modbus inputs are read-only)
Documentation
fix README MQTT write example for
bool8references (array of 8 booleans, not a scalar)document export, diagnostics, mqtt-single, config sources, write constraints, and publish behavior in
docs/usage.rstexpand
docs/configure.rstwith CSV schema, dtypes, poll limits, and validation rulescorrect
config_template.csvcomment: dtype column is required
Tests
add contract tests in
tests/test_handler_behavior.pyfor documented edge casesconsolidate handler regression/contract tests; share
FakeModbusMasterintests/helpers/modbus.py
2.1.1 (2026-06-11)
Features
add
--mqtt-retainto set the MQTT retain flag on data publishes (diagnostics topics are never retained)
Documentation
add release documentation checklist for agents and maintainers in CONTRIBUTING.md
align narrative docs with MQTT reference-map write format and
--mqtt-keysusage
Internal
centralize MQTT data publish policy (QoS and retain) in
MqttHandler.publish_data_message
2.1.0 (2026-06-10)
Features
add
--mqtt-keys name-onlyto publish MQTT JSON keys without the unit suffix (default key style remainsname-with-unit)MQTT writes on
modpoll/{device}/setaccept a map of references{"ref_a": val, "ref_b": val}in one message; unknown keys are skipped with a warning
BREAKING CHANGES
renamed
--daemon/-dto--no-output(suppresses poll result tables only; does not fork)MQTT write payload must be a reference map (
{"ref": val});ref/valueobject format removed
2.0.0 (2026-06-10)
Project
forked from modpoll; PyPI package renamed to
modpoll2mqtt, repositoryyoch/modpoll2mqttCLI command and Python module remain
modpoll
Features
semantic MQTT write by CSV reference on
modpoll/{device}/setwith payloadrefandvalue(device from topic; scale, dtype, and endianness handled automatically)subscribe pattern
modpoll/+/setby default
BREAKING CHANGES
removed low-level MQTT write format (
object_type,address,value); use topic +refandvalueinsteadduplicate reference names on the same device now abort config loading (previously warned and overwrote)