modbusmqtt/modbus-mqtt

ModbusMQTT

A bridge between Modbus devices and MQTT.

It is early days, but the plan is:

• Support custom Modbus transports (Sungrow WiNet-S has been implemented)
  • Modbus RTU has not been tested because I don't have a serial Modbus device, but in principle it should work. Please let me know
• Support reading input registers
• Support reading holding registers
• Support setting holding registers
• Support optional auto-configuration of Home Assistant entities, including using MQTT Number et al for holding registers, to allow setting the value.
• TLS MQTT connections
• WebSocket MQTT connections

NOTE: For the time being, this does not support MQTTv5.

Installing

For now, cargo install is the easiest way to install. Either run it in a checkout for the latest development version, or run cargo install modbus-mqtt to install the latest release version.

If you don't want to set up the Rust toolchain, you can likely found built binaries as build artifacts in the GitHub Actions tab above.

In the future, there will also be Docker images made available for convenience.

Running

Start the binary, passing in the URL to your MQTT server, including any credentials:

$ modbus-mqtt mqtt://$MQTT_HOST[:$MQTT_PORT]/[$CUSTOM_MODBUS_TOPIC]

The supported protocols are currently just tcp:///mqtt://, but with intent to support: mqtts://, ssl:///tls://, ws://, and wss://.

The default topic which ModbusMQTT monitors and to which it publishes is modbus-mqtt. You can vary that by changing the path portion of the MQTT URL.

Further, you can change other MQTT options by using query params, such as setting a custom client_id:

"mqtt://1.2.3.4/?client_id=$CUSTOM_CLIENT_ID"

For a full list of supported options, check the MQTT client library's source code.

Connecting to Modbus devices

To connect to a Modbus device, you need to post the connection details to MQTT under a topic of $prefix/$connection_id/connect. It is intended that such messages are marked as retained so that ModbusMQTT reconnects to your devices when it restarts.

For instance, a simple config might be:

// PUBLISH modbus-mqtt/solar-inverter/connect
{
  "host": "10.10.10.219",
  "proto": "tcp",
}

If the connection is successful, you will see the following message like the following sent to the MQTT server:

// modbus-mqtt/solar-inverter/state
"connected"

Full connection examples

All fields accepted (optional fields show defaults)

{
  // Common fields
  "address_offset": 0, // optional
  "unit": 1,           // optional, aliased to "slave"

  // TCP:
  "proto": "tcp",
  "host": "1.2.3.4",
  "port": 502, // optional

  // RTU / Serial:
  "proto": "rtu",
  "tty": "/dev/ttyACM0",
  "data_bits": "Eight",   // optional (TODO: accept numeric and lowercase)
                          //   valid: Five, Six, Seven, Eight
  "stop_bits": "One",     // optional (TODO: accept numeric and lowercase)
                          //   valid: One, Two
  "flow_control": "None", // optional (TODO: accept lowercase)
                          //   valid: None, Software, Hardware
  "parity": "None",       // optional (TODO: accept lowercase)
                          //   valid: None, Odd, Even

  // Sungrow WiNet-S dongle
  "proto": "winet-s",
  "host": "1.2.3.4",
}

Monitoring registers

Post to $MODBUS_MQTT_TOPIC/$CONNECTION_ID/$TYPE/$ADDRESS where $TYPE is one of input or holding with the following payload (optional fields show defaults):

{
  "address": 5123,          // REQUIRED

  "register_type": "input", // OPTIONAL

  "name": null,             // OPTIONAL - gives the register a name which is used in the register MQTT topics (must be a valid topic component)

  "interval": "1m",         // OPTIONAL - how often to update the registers value to MQTT
                            //   e.g.: 3s (every 3 seconds)
                            //         2m (every 2 minutes)
                            //         1h (every 1 hour)

  "swap_bytes": false,      // OPTIONAL
  "swap_words": false,      // OPTIONAL

  "type": "s16",            // OPTIONAL
                            //   valid: s8, s16, s32, s64 (signed)
                            //          u8, u16, u32, u64 (unsigned)
                            //          f32, f64          (floating point)

  "scale": 0,               // OPTIONAL - number in register will be multiplied by 10^(scale)
                            //   e.g.: to turn kW into W, you would provide scale=3
                            //         to turn W into kW, you would provide scale=-3

  "offset": 0,              // OPTIONAL - will be added to the final result (AFTER scaling)
}

Register shorthand

When issuing the connect payload, you can optionally include a top-level registers array, containing the above register schema. When present, these payloads will be replayed to the MQTT server as if the user had specified each register separately, as above.

This is a recommended way to specify connections, but the registers are broken out separately so that they can be dynamically added to too.

Development

TODO: set up something like https://hub.docker.com/r/oitc/modbus-server to test with

Similar projects

• https://github.com/Instathings/modbus2mqtt
• https://github.com/TenySmart/ModbusTCP2MQTT - Sungrow inverter specific
• https://github.com/bohdan-s/SunGather - Sungrow inverter specific