Skip to main content

A YAML-defined bidirectional Modbus to MQTT interface

Project description

Modbus4MQTT

https://github.com/tjhowse/modbus4mqtt

https://pypi.org/project/modbus4mqtt/

codecov

This is a gateway that translates between modbus TCP/IP and MQTT.

There are already a few things that do this, but didn't quite have the features I wanted.

The mapping of modbus registers to MQTT topics is in a simple YAML file.

The most up-to-date docs will always be on Github.

Installation

$ pip3 install --user modbus4mqtt
$ modbus4mqtt --help

Alternatively you can run Modbus4MQTT in a Docker container. A Dockerfile example is provided.

You will need to provide the credentials to connect to your MQTT broker, as well as a path to a YAML file that defines the memory map of your Modbus device.

YAML definition

Look at the Sungrow SH5k-20 configuration YAML for a working example.

Modbus device settings

ip: 192.168.1.89
port: 502
update_rate: 1

This is the address of the Modbus device to be polled. Presently only Modbus TCP/IP is supported. The update rate is in seconds. This defines how frequently the registers are polled for changes.

registers:
  - pub_topic: "forced_charge/mode"
    set_topic: "forced_charge/mode/set"
    retain: true
    pub_only_on_change: false
    table: 'holding'
    address: 13140
    value_map:
      enabled: 170
      disabled: 85
  - pub_topic: "forced_charge/period_1/start_hours"
    set_topic: "forced_charge/period_1/start_hours/set"
    pub_only_on_change: true
    table: 'holding'
    address: 13142
  - pub_topic: "voltage_in_mv"
    address: 13000
    scale: 1000
  - pub_topic: "first_bit_of_second_byte"
    address: 13001
    mask: 0x0010

This section of the YAML lists all the modbus registers that you consider interesting.

pub_topic (Optional) This is the topic to which the value of this register will be published.

set_topic (Optional) Values published to this topic will be written to the Modbus device.

retain (Optional) Controls whether the value of this register will be published with the retain bit set.

pub_only_on_change (Optional) Controls whether this register will only be published if its value changed from the previous poll.

table (Optional) The Modbus table to read from the device. Must be 'holding' or 'input'. If absent it will default to 'holding'.

address (Required) The address to read from the device.

value_map (Optional) A series of human-readable and raw values for the setting. This will be used to translate between human-readable values via MQTT to raw values via Modbus. If a value_map is set for a register the interface will reject raw values sent via MQTT. If value_map is not set the interface will try to set the Modbus register to that value. Note that the scale is applied after the value is read from Modbus and before it is written to Modbus.

scale (Optional) After reading a value from the Modbus register it will be multiplied by this scalar before being published to MQTT. Values published on this register's set_topic will be divided by this scalar before being written to Modbus.

mask (Optional) This is a 16-bit number that can be used to select a part of a Modbus register to be referenced by this register. For example a mask of 0xFF00 will map to the most significant byte of the 16-bit Modbus register at address. A mask of 0x0001 will reference only the least significant bit of this register.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

modbus4mqtt-0.2.1.tar.gz (11.1 kB view hashes)

Uploaded Source

Built Distribution

modbus4mqtt-0.2.1-py3-none-any.whl (12.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page