Fully configurable Zwave to MQTT Gateway and Control Panel.
- Backend: NodeJS, Express, socket.io, Mqttjs, openzwave-shared, Webpack
- Frontend: Vue, socket.io, Vuetify
Check docker repo for more info
# Using volumes as persistence
docker run --rm -it -p 8091:8091 --device=/dev/ttyACM0 --mount source=zwave2mqtt,target=/usr/src/app/store robertslando/zwave2mqtt:latest
# Using local folder as persistence
mkdir store
docker run --rm -it -p 8091:8091 --device=/dev/ttyACM0 -v $(pwd)/store:/usr/src/app/store robertslando/zwave2mqtt:latest
# As a service
wget https://raw.githubusercontent.com/robertsLando/Zwave2Mqtt-docker/master/compose/docker-compose.yml
docker-compose up
Replace
/dev/ttyACM0
with your serial device
Enjoy 😄
-
Firstly you need to install Open-Zwave library on your system.
If you are using Ubuntu:
sudo apt-get install libudev-dev cd ~ wget http://old.openzwave.com/downloads/openzwave-1.4.1.tar.gz tar zxvf openzwave-*.gz cd openzwave-* && make && sudo make install sudo ln -s /usr/local/lib64/libopenzwave.so /usr/local/lib/libopenzwave.so sudo ln -s /usr/local/lib64/libopenzwave.so.1.4 /usr/local/lib/libopenzwave.so.1.4 sudo ldconfig export LD_LIBRARY_PATH=/usr/local/lib64 sudo sed -i '$a LD_LIBRARY_PATH=/usr/local/lib64' /etc/environment
For Raspberry check here
-
Test the library: go to openzwave directory
cd openzwave-*
and run the commandMinOZW /dev/ttyACM0
replace
/dev/ttyACM0
with the USB port where your controller is connected -
Now you can use the packaged version (you don't need NodeJS/npm installed) or clone this repo and build the project:
-
For the packaged version:
cd ~ mkdir Zwave2Mqtt cd Zwave2Mqtt wget https://github.com/OpenZWave/Zwave2Mqtt/releases/download/1.0.0/zwave2mqtt-v1.0.0.zip unzip zwave2mqtt-v1.0.0_PKG.zip ./zwave2mqtt
-
If you want to compile last code from github:
git clone https://github.com/OpenZWave/Zwave2Mqtt cd Zwave2Mqtt npm install npm run build npm start
-
-
Open the browser http://localhost:8091
Developers who wants to debug the application have to open 2 terminals.
In first terminal run npm run dev
to start webpack-dev for front-end developing and hot reloading at http://localhost:8092
(THE PORT FOR DEVELOPING IS 8092)
In the second terminal run npm run dev:server
to start the backend server with inspect and auto restart features (if you don't have nodemon installed: npm install -g nodemon
)
To package the application run npm run pkg
command and follow the steps
Firstly you need to open the browser at the link http://localhost:8091 and edit the settings for Zwave, MQTT and the Gateway.
Zwave settings:
- Serial port: The serial port where your controller is connected
- Network key (Optional): Zwave network key if security is enabled. The correct format is
"0xCA,0xFE,0xBA,0xBE,.... "
whithout spaces (16 bytes total) - Logging: Enable/Disable Openzwave Library logging
- Save configuration: Store zwave configuration in
zwcfg_<homeHex>.xml
andzwscene.xml
files this is needed for peristent node information like node name and location - Poll interval: Interval in milliseconds between polls (should not be less than 1s per device)
- Configuration Path: The path to Openzwave devices config db
- Assume Awake: Assume Devices that support the Wakeup Class are awake when starting up OZW
Mqtt settings:
- Name: A unique name that identify the Gateway.
- Host: The url of the broker. Insert here the protocol if present, example:
tls://localhost
. Mqtt supports this protocols:mqtt
,mqtts
,tcp
,tls
,ws
,wss
,wss
andmqtts
- Port: Broker port
- Reconnect period: Milliseconds between two reconnection tries
- Prefix: The prefix where all values are published
- QoS: Quality Of Service (check MQTT specs) of outgoing packets
- Retain: The retain flag of outgoing packets
- Clean: Sets the clean flag when connecting to the broker
- Store: Enable/Disable persistent storage of packets (QoS > 0). If disabled in memory storage will be used but all packets stored in memory are lost in case of shutdowns or unexpected errors.
- Allow self signed certs: When using encrypted protocols, set this to true to allow self signed certificates (WARNING this could expose you to man in the middle attacks)
- Ca Cert and Key: Certificate Authority, Client Key and Client Certificate files required for secured connections (if broker requires valid certificates, this fields can be leave empty otherwise)
- Auth: Enable this if broker requires auth. If so you need to enter also a valid username and password.
Gateway settings:
-
Gateway type: This setting specify the logic used to publish Zwave Nodes Values in MQTT topics. At the moment there are 3 possible configuration, two are automatic (all values are published in a specific topic) and one needs to manually configure which values you want to publish to MQTT and what topic to use. For every gateway type you can set custom topic values, if gateway is not in 'configure manually' mode you can omit the topic of the values (the topic will depends on the gateway type) and use the table to set values you want to
poll
or if you want to scale them usingpost operation
-
ValueId Topics: Automatically configured. The topic where zwave values are published will be:
<mqtt_prefix>/<?node_location>/<node_id>/<class_id>/<instance>/<index>
mqtt_prefix
: the prefix set in Mqtt Settingsnode_location
: location of the Zwave Node (optional, if not present will not be added to the topic)node_id
: the unique numerical id of the node in Zwave networkclass_id
: the numerical class id of the valueinstance
: the numerical value of value instanceindex
: the numerical index of the value
-
Named Topics: Automatically configured. DEPRECATED After a discussion with Openzwave author lib we discurage users to use this configuration as we cannot ensure that value labels will be the same, they could change in future versions (and also they depends on localization added in OZW 1.6). You can find more info HERE
The topic where zwave values are published will be:
<mqtt_prefix>/<?node_location>/<node_name>/<class_name>/<?instance>/<value_label>
mqtt_prefix
: the prefix set in Mqtt Settingsnode_location
: location of the Zwave Node (optional, if not present will not be added to the topic)node_name
: name of the node, if not set will benodeID_<node_id>
class_name
: the node class name corrisponding to given class id orunknownClass_<class_id>
if the class name is not found?instance
: Used just with multi-instance devices. The main instance (1) will not have this part in the topic but other instances will have:instance_<instance_index>
value_label
: the zwave value label (lower case and spaces are replaced with_
)
-
Configured Manually: Needs configuration. The topic where zwave values are published will be:
<mqtt_prefix>/<?node_location>/<node_name>/<value_topic>
mqtt_prefix
: the prefix set in Mqtt Settingsnode_location
: location of the Zwave Node (optional, if not present will not be added to the topic)node_name
: name of the node, if not set will benodeID_<node_id>
value_topic
: the topic of the value. This is manually configured in Gateway settings by popolating a table with the values that I want to read from each device of a specific type in my network. Once scan is complete, the gateway creates an array with all devices types found in the network. A device has adevice_id
that is unique, it is composed by this node properties:<manufacturerid>-<productid>-<producttype>
.
-
-
Payload type: The content of the payload when an update is published:
-
JSON Time-Value: The payload will be a JSON object like:
{ "time": 1548683523859, "value": 10 }
-
Entire Zwave value Object The payload will contain all info of a value from Zwave network:
{ "value_id": "3-64-1-0", "node_id": 3, "class_id": 64, "type": "list", "genre": "user", "instance": 1, "index": 0, "label": "Mode", "units": "", "help": "", "read_only": false, "write_only": false, "min": 0, "max": 0, "is_polled": false, "values": ["Off", "Heat (Default)", "Cool", "Energy Heat"], "value": "Off", }
-
Just value: The payload will contain only the row Numeric/String value
-
-
Send 'list' as integer: Zwave 'list' values are sent as list index instead of string values
Once finished press SAVE
and gateway will start Zwave Network Scan, than go to 'Control Panel' section and wait until the scan is completed to check discovered devices and manage them.
Settings, scenes and Zwave configuration are stored in JSON/xml
files under project store
folder that you can easily import/export for backup purposes.
By default Node status (true
if node is ready false
if node is dead) will be published in:
<mqtt_prefix>/<?node_location>/<node_name>/status
To add a node using the UI select the controller Action Add Node (inclusion)
, click send (:airplane:) button to enable the inclusion mode in your controller and enable the inclusion mode in your device to. Controller status
will be waiting
when inclusion has been successfully enabled on the controller and completed
when the node has been successfully added. Wait few seconds and your node will be visible in the table once ready.
To add a node using the UI select the controller Action Remove Node (exlusion)
, click send (:airplane:) button to enable the exclusion mode in your controller and enable the exclusion mode in your device to. Controller status
will be waiting
when exclusion has been successfully enabled on the controller and completed
when the node has been successfully removed. Wait few seconds and your node will be removed from the table.
To replace a failed node using the UI you have to check if the Node is failed using Has node failed
command. If Controller status says NodeFailed
the node can be replaced, if not controller will say NodeOk
. Sometimes to update node state and make it failed you firstly need to send Update return route
command than send Has node failed
and check if the status now is NodeFailed
. If so you can replace the node using the command Replace Failed Node
, now the controller will start inclusion mode and status will be Waiting
, now enable inclusion on your device to add it to the network by replacing the failed one.
- Configurable Zwave to Mqtt Gateway
- Zwave Control Panel:
- Nodes management: check nodes status in the network, change nodes
name
andlocation
, get nodes values and configure them, send actions to controller and import/export zwave configuration files - Groups associations: create associations between nodes (also supports multi-instance associations, need to use last version of openzwave-shared)
- Custom scenes management: (OpenZwave-Shared scenes management has actually some bugs and it's limited so I have made a custom scenes implementation that uses the same APIs but stores values in a JSON file that can be imported/exported and also allows to set a timeout to a value in a scene)
- Nodes management: check nodes status in the network, change nodes
- Log debug in UI
You have full access to all Openzwave-Shared APIs (and more) by simple usign MQTT.
To call a Zwave API you just need to publish a JSON object like:
{
"args": [2,1]
}
Where args
is an array with the args used to call the api, the topic is:
<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/<api_name>/set
The result will be publised on the same topic without /set
Example: If I publish the previous json object to the topic
zwave/_CLIENTS/ZWAVE_GATEWAY-office/api/getAssociations/set
I will get this response (in the same topic without the suffix /set
):
{
"success":true,
"message":"Success zwave api call",
"result":[1]
}
result
will contain the value returned from the API. In this example I will get an array with all node IDs that are associated to the group 1 (lifeline) of node 2.
To write a value using MQTT you just need to send the value to set in the same topic where the value updates are published by adding the suffix /set
to the topic (READONLY VALUES CANNOT BE WRITE).
Example with gateway configured with named topics
:
If I publish the value 25.5
(also a payload with a JSON object with the value in value
property is accepted) to the topic
zwave/office/nodeID_4/thermostat_setpoint/heating/set
I will set the Heating setpoint of the node with id 4
located in the office
to 25.5
. To check if the value has been successfully write just check when the value changes on the topic:
zwave/office/nodeID_4/thermostat_setpoint/heating
You can send broadcast values to all values with a specific suffix in the network.
Broadcast API is accessible from:
<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/broadcast/<value_topic_suffix>/set
value_topic_suffix
: the suffix of the topic of the value I want to control using broadcast.
It works like the set value API without the node name and location properties.
If the API is correctly called the same payload of the request will be published
to the topic without /set
suffix.
Example of broadcast command (gateway configured as named topics
):
zwave/_CLIENTS/ZWAVE_GATEWAY-test/broadcast/thermostat_setpoint/heating/set
Payload: 25.5
All nodes with command class thermostat_setpoint
and value heating
will be set to 25.5
and I will get the same value on the topic:
zwave/_CLIENTS/ZWAVE_GATEWAY-test/broadcast/thermostat_setpoint/heating
- Better logging
- Dockerize application
- Package application with PKG
- HASS integration, check zegbee2mqtt
- Add unit test
- JSON validator for settings and scenes
- Better nodes status management using 'testNode'
- Network graph to show neightborns using vue-d3-network
Support me on Patreon ❤️