This is a Node.js tool to connect a Siemens S7 PLC over Mqtt with Home Assistant
This project is intended to use along with Home Assistant, but is also possible to use it as a simple bridge between s7 and mqtt.
This tool can receive data over mqtt and can write it to a designated address on a plc and vice versa, enabling smart home data to be displayed in the home assistant.
docker run -d -v /path/on/host/config.json:/usr/src/app/config.json timroemisch/mqtt-s7-connector
Note: You only have to mount the configuration file, not the entire folder.
Config volume mountpoint: /usr/src/app/config.json
The configuration file has to be located in the same directory as the installation and has to be named config.json
An example of a correct configuration file is found in config.example.json
.
The config file has to be valid JSON (You can check here if it´s correct)
and is separated in 3 sections:
plc:
general setup of the connection to the plc
In the most use cases you only have to change the host value to the correct ip
"plc": { "port": 102, "host": "192.168.0.1", "rack": 0, "slot": 2, "debug": false }
mqtt:
general setup of the connection to the mqtt broker
The URL/host value can be one of the following protocols: 'mqtt', 'mqtts', 'tcp', 'tls', 'ws', 'wss'.
If you are using a self-signed certificate, use the
rejectUnauthorized: false
option. Beware that you are exposing yourself to man in the middle attacks, so it is a configuration that is not recommended for production environments."mqtt": { "host": "mqtts://host.com:1234", "user": "u", "password": "p", "rejectUnauthorized": true }
devices:
list of all registered devices
the list of devices is implemented as an array in json.
each device has it's own entry in this list and will be configured there.Each device has to have a 'name' entry and a 'type' entry, the remaining attributes are optional
"devices": [ { "name": "Dimmable Light", "type": "light",
"state": "DB56,X150.0",
"brightness": "DB56,BYTE151"
}, { "name": "Dimmable Light 2", "type": "light",
"state": "DB56,X150.1",
} ]
This tool uses the NodeS7 Library and it uses the same address formatting.
An example of correct formatted addresses is found at the NodeS7 Repository
Address examples:
DB56,X150.0 (read from DB56 one bit at 150.0)
DB51,REAL216 (read from DB51 four bytes starting from byte 216)
DB56,BYTE40 (read from DB56 one byte at 40)
Supported data types
X = 1 Bit -> converted to true / false
BYTE = 1 Byte (8 Bit) -> converted to Int
REAL = 4 Bytes (32 Bit) -> converted to Float
For more information see the NodeS7 Repository
The device type categories are based on the categories from Home Assistant
It is strongly recommended to look into the example configuration file !!
Current list of supported device types with supported attributes:
light
state
(X)
on/off state of the device
brightness
(BYTE)
value between 0-255
sensor
state
(X/BYTE/REAL)switch
state
(X)climate
target_temperature
(REAL)
current_temperature
(REAL)
readonly by default
_updateinterval is 15 min by default
cover
targetPosition
(BYTE)
tiltAngle
(BYTE)
currentPosition
(BYTE)
readonly by default
currentTiltAngle
(BYTE)
readonly by default
trigger
(X)
internal value: it won't be exposed over mqtt
this bit will be turned on and off automatically after one of the other attributes of the cover will be changed
binaryCover
targetPosition
(X)
currentPosition
(X)
readonly by default
A "simple" device has just the plc address as the value of the attributes,
however it's possible to configure each attribute individually by assigning an object instead of a string to it.
Simple Attribute:
...
"state": "DB56,X150.0",
...
Rewritten Attribute:
...
"state": {
"plc": "DB56,X150.0"
},
...
Now after rewriting it's possible to add more options inside the brackets of the attribute.
Available options:
Changes the read / write permissions
Read PLC | Write PLC | Subscribe MQTT | Publish MQTT | |
---|---|---|---|---|
r | ✅ | ❌ | ❌ | ✅ |
w | ❌ | ✅ | ✅ | ❌ |
rw | ✅ | ✅ | ✅ | ✅ |
"state": {
"plc": "DB56,X150.0",
"rw": "r"
},
update_interval
By default (without this option) each attribute will sent an update over mqtt after it changes, but this option will disable it and set an interval for updates.
The time is set in ms"state": { "plc": "DB56,BYTE234", "update_interval": 1000 },
unit_of_measurement
This is only for Home Assistant. It will add an additional unit of measurement to the data.
"state": { "plc": "DB56,REAL10", "unit_of_measurement": "km/h" },
set_plc
By default attributes have only one address, but if you define "set_plc"
the attribute will read from "plc" and write to "set_plc""state": { "plc": "DB56,X150.0", "set_plc": "DB56,X150.1" },
write_back
When using both
plc_address
andplc_set_address
, settingwrite_back
totrue
will automatically write any changes read fromplc_address
toplc_set_address
."state": { "plc": "DB56,X150.0", "set_plc": "DB56,X150.1", "write_back": true },
This tool will send for each device an auto-discovery message over mqtt in the correct format defined by Home Assistant.
The default mqtt topic is homeassistant
, it can be changed in the config file. (See the example)
Pull requests welcome! 😄
Licensed under ISC
Copyright (c) 2021 Tim Römisch