roflmao/zwavejs2mqtt

By roflmao

•Updated over 5 years ago

roflmao/zwavejs2mqtt:dev builds master zwavejs2mqtt/node-zwave-js upon trigger

Image

3.0K

Overview Tags

roflmao/zwavejs2mqtt repository overview

⁠Zwave To MQTT

GitHub package.json version

Fully configurable Zwave to MQTT Gateway and Control Panel.

Backend: NodeJS⁠, Express⁠, socket.io⁠, Mqttjs⁠, zwavejs⁠, Webpack⁠
Frontend: Vue⁠, socket.io⁠, Vuetify⁠

⁠📖 Table of contents

Zwave To MQTT⁠

⁠:electric_plug: Installation

⁠DOCKER :tada: way

# Using volumes as persistence
docker run --rm -it -p 8091:8091 --device=/dev/ttyACM0 --mount source=zwavejs2mqtt,target=/usr/src/app/store zwavejs/zwavejs2mqtt: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 zwavejs/zwavejs2mqtt:latest

# As a service
wget https://raw.githubusercontent.com/zwave-js/zwavejs2mqtt/master/docker/docker-compose.yml
docker-compose up

Replace /dev/ttyACM0 with your serial device

For more info about docker check here⁠

⁠Kubernetes way

kubectl apply -k https://raw.githubusercontent.com/zwave-js/zwavejs2mqtt/master/kustomization.yaml

You will almost certainly need to instead use this as a base, and then layer on top patches or resource customizations to your needs or just copy all the resources from the kubernetes resources⁠ directory of this repo

⁠NodeJS or PKG version

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 zwavejs2mqtt
cd zwavejs2mqtt
# download latest version
curl -s https://api.github.com/repos/zwave-js/zwavejs2mqtt/releases/latest  \
| grep "browser_download_url.*zip" \
| cut -d : -f 2,3 \
| tr -d \" \
| wget -i -
unzip zwavejs2mqtt-v*.zip
./zwavejs2mqtt

If you want to compile last code from github:

git clone https://github.com/zwave-js/zwavejs2mqtt
cd zwavejs2mqtt
npm install
npm run build
npm start

Open the browser http://localhost:8091⁠

⁠Reverse Proxy Setup

If you need to setup ZWave To MQTT behind a reverse proxy that needs a subpath to work, take a look at the reverse proxy configuration docs⁠.

⁠Why Zwavejs

Entirely written in JS (Typescript). This is good for many reasons:
- We can drop the node-openzwave-shared that is maintained by me but would need a complete refactor and it's hard to maintain both projects.
- It will not require to compile OZW and we can have more control of updates/versions with zwavejs releases.
- JS it's straightforward to debug all through the stack rather than a black box that is abstracted by another library
Better support/collaboration: OZW is widely used and the author had many other related projects to maintain/support causing many delays or even no responses at all to some issues. Zwave is a good protocol but there are many devices compatibility issues and most of the issues on z2m were related to them. It's become really clear from the time building and maintaining z2m that the community is really important and have found working with @AlCalzone and the growing dev community around zwavejs to be really beneficial for fast paced change and this project is fully embraced by that community too.
Its device database keeps growing and uses configurations imported both from OpenHAB and OZW (ozw db import is waiting to be approved check updates here⁠).
Better code testing and overall features: it supports OTA Updates, Secure Node Replace and there is a work in progress for security S2 that are not supported by OZW

⁠Migrating From Zwave2Mqtt

For everyone that is coming from Zwave2Mqtt there will be some breaking changes:

settings.json are almost the same, you can easily export them from Z2M and import them in ZJS2M by using the Export and Import buttons in Settings tab. After importing them you only will have to edit some Zwave settings and all Gateway Values entries as now the value ids have changed
scenes.json need to be rewrited for the same reason as valueIds have changed. I suggest to manually recreate them using the UI and trash the old one
You cannot use the old OZW cache file but don't worry it will be automatially generated and the nodes names/locations will be restored from nodes.json file
nodes.json can be imported but you will have to manually edit it and delete all nodes hassDevices as them will not work in the new implementation (alternatively instead of deleting you can manually convert them, see next steps)
Values ids unique strings have changed, in Z2M valueIds were identified by <nodeId>/<commandClass>/<endpoint>/<index> now them are <nodeId>/<commandClass>/<endpoint>/<property>/<propertyKey?> where property and propertyKey (can be undefined) can be both numbers or strings based on the value. So essentially if you are using Hass or Mqtt functions all topics will change, here⁠ you can see how I have translated some valueids of devices.js from the old format to the new one.
List values are no longer handled as strings but as numbers by default. For example to change a Thermostat Mode in Z2M you used to send Heat or Off now you will need to send 1 (Heat) or 0 (Off). This will make it lot easier to handle list values
All bitmask values are now splitted in separeted values and are booleans. The same for rgb colors, now all colors will be handled separately, there will be a valueId to control Red (0-255), another for Green (0-255) and so on... There is an open issue on zwavejs to also create a valueId with the hex color string. Also now some values are splitted in targetValue and currentValue, the first one is used to send commands the second one to see the actual state. This could seems tricky at first sight but there are some reasons behind this.

⁠:nerd_face: Development

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

⁠Developing against a different backend

By default running npm run dev:server will proxy the requests to a backend listening on localhost on port 8091.

If you want to run the development frontend against a different backend you have the following environment variables that you can use to redirect to a different backend:

SERVER_HOST: [Default: 'localhost'] the hostname or IP of the backend server you want to use;
SERVER_PORT: [Default: '8091'] the port of the backend server you want to use;
SERVER_SSL: [Default: undefined] if set to a value it will use https/wss to connect to the backend;
SERVER_URL: [Default: use the other variables] the full URL for the backend API, IE: https://zwavetomqtt.home.net:8443/
SERVER_WS_URL: [Default: use the other variables] the full URL for the backend Socket, IE: wss://zwavetomqtt.home.net:8443/

⁠:wrench: Usage

Firstly you need to open the browser at the link http://localhost:8091⁠ and edit the settings for Zwave, MQTT and the Gateway.

⁠Zwave

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 like the OZW key but without 0x , and spaces: OZW: 0x5C, 0x14, 0x89, 0x74, 0x67, 0xC4, 0x25, 0x98, 0x51, 0x8A, 0xF1, 0x55, 0xDE, 0x6C, 0xCE, 0xA8 Zwavejs: 5C14897467C42598518AF155DE6CCEA8
Log level: Set the zwave-js Library log level
Log to file: Enable this to store zwave-js logs to a file
Commands timeout: Seconds to wait before automatically stop inclusion/exclusion
Hidden settings: advanced settings not visible to the user interface, you can edit these by setting in the settings.json
- zwave.plugin defines a js script that will be included with the this context of the zwave client, for example you could set this to hack and include a hack.js in the root of the app with module.exports = zw => {zw.client.on("scan complete", () => console.log("scan complete")}
- zwave.options overrides options passed to the zwave js Driver constructor ZWaveOptions⁠

⁠MQTT

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 these protocols: mqtt, mqtts, tcp, tls, ws and wss
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

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 using post operation
1. ValueId Topics: Automatically configured. The topic where zwave values are published will be:
  
  <mqtt_prefix>/<?node_location>/<nodeId>/<commandClass>/<endpoint>/<property>/<propertyKey>
  - mqtt_prefix: the prefix set in Mqtt Settings
  - node_location: location of the Zwave Node (optional, if not present will not be added to the topic)
  - nodeId: the unique numerical id of the node in Zwave network
  - commandClass: the command class number of the value
  - endpoint: the endpoint number (if the node has more then one endpoint)
  - property: the value property⁠
  - propertyKey: the value propertyKey⁠
2. Named Topics: Automatically configured. The topic where zwave values are published will be:
  
  <mqtt_prefix>/<?node_location>/<node_name>/<class_name>/<?endpoint>/<propertyName>/<propertyKey>
  - mqtt_prefix: the prefix set in Mqtt Settings
  - node_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 be nodeID_<node_id>
  - class_name: the valueId command class name corresponding to given command class number or unknownClass_<class_id> if the class name is not known
  - ?endpoint: Used just with multi-instance devices. The main enpoint (0) will not have this part in the topic but other instances will have: endpoint_<endpoint>
  - propertyName: the value propertyName⁠
  - propertyKey: the value propertyKey⁠
3. 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 Settings
  - node_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 be nodeID_<node_id>
  - value_topic: the topic you want to use for that value (taken from gateway values table).

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 ValueId Object The payload will contain all info of a value from Zwave network:

{
  id: "38-0-targetValue",
  nodeId: 8,
  commandClass: 38,
  commandClassName: "Multilevel Switch",
  endpoint: 0,
  property: "targetValue",
  propertyName: "targetValue",
  propertyKey: undefined,
  type: "number",
  readable: true,
  writeable: true,
  description: undefined,
  label: "Target value",
  default: undefined,
  genre: "user",
  min: 0,
  max: 99,
  step: undefined,
  unit: undefined,
  list: false,
  value: undefined,
  lastUpdate: 1604044669393,
}

Example of a valueId with states:

{
  id: "112-0-200",
  nodeId: 8,
  commandClass: 112,
  commandClassName: "Configuration",
  endpoint: 0,
  property: 200,
  propertyName: "Partner ID",
  propertyKey: undefined,
  type: "number",
  readable: true,
  writeable: true,
  description: undefined,
  label: "Partner ID",
  default: 0,
  genre: "config",
  min: 0,
  max: 1,
  step: undefined,
  unit: undefined,
  list: true,
  states: [
    {
      text: "Aeon Labs Standard Product",
      value: 0,
    },
    {
      text: "others",
      value: 1,
    },
  ],
  value: 0,
  lastUpdate: 1604044675644,
}

Just value: The payload will contain only the row Numeric/String/Bool value

Ignore status updates: Enable this to prevent gateway to send an MQTT message when a node changes its status (dead/sleep == false, alive == true)
Ignore location: Enable this to remove nodes location from topics
Send Zwave Events: Enable this to send all Zwave client events to MQTT. More info here⁠
Include Node Info: Adds in ValueId json payload two extra values with the Name: nodeName and Location nodeLocation for better graphing capabilities (usefull in tools like InfluxDb,Grafana)
Use nodes name instead of numeric nodeIDs: When gateway type is ValueId use this flag to force to use node names instead of node ids in topic.
:star:Hass discovery:star:: Enable this to automatically create entities on Hass using MQTT autodiscovery (more about this here⁠)
Discovery Prefix: The prefix to use to send MQTT discovery messages to HASS

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 files under project store folder that you can easily import/export for backup purposes.

⁠Special topics

App version:

<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/version

The payload will be in the time-value json format and the value will contain the app string version.

Mqtt status:

<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/status

The payload will be in the time-value json format and the value will be true when mqtt is connected, false otherwise.

Node status:

<mqtt_prefix>/<?node_location>/<node_name>/status

The payload will be true if node is ready false otherwise. If the payload is in JSON format it will also contain the node status string in status property (Alive, Awake, Dead)

Node notifications:

<mqtt_prefix>/<?node_location>/<node_name>/notification/<notificationLabel>

The payload will be the notification parameters (can be null or not based on the notification type)

⁠Gateway values table

The Gateway values table can be used with all gateway types to customize specific values topic for each device type found in the network and do some operations with them. Each value has this properties:

Device: The device type. Once scan is complete, the gateway creates an array with all devices types found in the network. A device has a device_id that is unique, it is composed by this node properties: <manufacturerid>-<productid>-<producttype>.
Value: The value you want to customize
Device Class: If the value is a multilevel sensor, a binary sensor or a meter you can set a custom device_class to use with home assistant discovery. Check sensor⁠ and binary sensor⁠
Topic: The topic to use for this value. It is the topic added after topic prefix, node name and location. If gateway type is different than Manual this can be leave blank and the value topic will be the one based on the gateway configuration chosen
Post operation: If you want to convert your value (eg. '/10' '/100' '*10' '*100')
Parse Send: Enable this to allow users to specify a custom function(value) to parse the value sent to MQTT. The function must be sync
Parse receive: Enable this to allow users to specify a custom function(value) to parse the value received via MQTT. The function must be sync

⁠:file_folder: Nodes Management

⁠Add a node

To add a node using the UI, go to Control Panel and from the actions dropdown menu select Start inclusion, click send (:airplane:) button to enable the inclusion mode in your controller, a popup will ask you if you want to start it in Secure mode. In the Controller status text field you should see Non-secure/Secure inclusion started when inclusion has been successfully enabled on the controller. Wait few seconds and once the interview finish your node will be visible in the table.

⁠Remove a node

To remove a node using the UI, go to Control Panel and from the actions dropdown menu select Start exclusion, click send (:airplane:) button to enable the exclusion mode in your controller and enable the exclusion mode in your device to. Controller status should show Exclusion started when exclusion has been successfully enabled on the controller. Wait few seconds and your node will be removed from the table.

⁠Replace failed node

To replace a failed node from the UI you have to use the command Replace Failed Node, the controller will start inclusion mode and status will be Waiting, a popup will ask you if you want to start it in Secure mode. Now enable inclusion on your device to add it to the network by replacing the failed one.

⁠Remove a failed node

If a node is missing or marked as dead. There is a way to cleanup the controller by executing Remove Failed Node. This

Tag summary

Recent tags

Content type

Image

Digest

Size

48.4 MB

Last updated

almost 6 years ago

docker pull roflmao/zwavejs2mqtt