Multiple possibilities exist, we will install the barebones zwave-js server project (https://www.npmjs.com/package/@zwave-js/server). zwave-js server is a node project implementing the zwavejs library and which is ready to use. it requires a certain version of the library to function, so always install the package and it will install the correct dependencies.
There is no need to use the cli commands after installation, just provide a config file and start up the server. Then, you can use the migration wizard in HA to move the legacy zwave to the new zwave-js version OR of course set up a new installation.
For the installation we will use a version of node and npm installed as the homeassistant user through NVM (so not from packages). the installation was tested on a raspberry pi 3 which was migrated from legacy zwave to zwave-js.
below is meant for home assistant core (the ‘advanced use case’ describe on the zwave-js documentation at the home assistant site).
In short, it means:
- install the zwave-js server and start the daemon
- enable the zwave-js home assistant integration
- migrate your zwave devices to zwave-js
- correct any missing devices.
steps
prereqs:
make sure you have these installed: git-cli, curl.
Of course, make a backup of the database and config folder.
then, as user homeassistant, do:
- install nvm (node version manager)
curl -O https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh
. install.sh- restart your shell to have the nvm environment variables added to your path.
- install node.js and npm (node package manager):
nvm install node npm
You are no ready to install node package zwave-js/server.
installing :
npm i @zwave-js/serverFor already initialized zwave sticks: create a config file with at least your existing security key in it, if you have one:
module.exports = {
securityKeys: {
S0_Legacy: Buffer.from("4xxxxxxxxxxxxxxxxyyyyyyyyyyyyyyD", "hex")
}
};Start up the binary (provide the correct serial device for your z-wave stick, in the below example ttyAMA0) and check the logs for errors.
Set up a systemd unit file if needed for auto-startup:
[Unit]
Description=ZWaveJS-server
After=network.service
[Service]
Type=simple
Environment=PATH=/home/homeassistant/.nvm/versions/node/v17.2.0/bin:/usr/local/pyenv/shims:/usr/local/pyenv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
User=homeassistant
Group=zwavejs
WorkingDirectory=/home/zwavejs/zwave-js-server
ExecStart=/home/zwavejs/zwave-js-server/node_modules/.bin/zwave-server /dev/ttyAMA0 --config /home/zwavejs/zwavejs-config.js
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.targetYou can now enable and start the zwavejs-server service and continue with https://www.home-assistant.io/integrations/zwave_js/#advanced-installation-instructions
Upgrading
Occasionally an upgrade may be needed, home assistant will show you during startup and you will see in the dashboard that the zwave-js integration is incompatible with the installed zwave-js server version. You should upgrade. Switch to the user running zwave-js, then:
[email protected]:/home/zwavejs/zwave-js-server# npm outdated
Package Current Wanted Latest Location Depended by
@types/node 16.11.10 16.11.26 17.0.21 node_modules/@types/node zwave-js-server
@types/ws 8.2.0 8.5.1 8.5.1 node_modules/@types/ws zwave-js-server
@types/yargs 17.0.7 17.0.8 17.0.8 node_modules/@types/yargs zwave-js-server
@typescript-eslint/eslint-plugin 4.33.0 4.33.0 5.12.1 node_modules/@typescript-eslint/eslint-plugin zwave-js-server
@typescript-eslint/parser 4.33.0 4.33.0 5.12.1 node_modules/@typescript-eslint/parser zwave-js-server
@zwave-js/server 1.13.0 1.15.0 1.15.0 node_modules/@zwave-js/server zwave-js-server
eslint 7.32.0 7.32.0 8.10.0 node_modules/eslint zwave-js-server
eslint-config-prettier 8.3.0 8.4.0 8.4.0 node_modules/eslint-config-prettier zwave-js-server
husky 4.3.8 4.3.8 7.0.4 node_modules/husky zwave-js-server
lint-staged 12.1.2 12.3.4 12.3.4 node_modules/lint-staged zwave-js-server
prettier 2.5.0 2.5.1 2.5.1 node_modules/prettier zwave-js-server
ts-node 10.4.0 10.5.0 10.5.0 node_modules/ts-node zwave-js-server
typescript 4.5.2 4.5.5 4.5.5 node_modules/typescript zwave-js-server
ws 8.3.0 8.5.0 8.5.0 node_modules/ws zwave-js-server
npm notice
npm notice New minor version of npm available! 8.2.0 -> 8.5.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v8.5.2
npm notice Run npm install -g [email protected] to update!
npm notice
[email protected]:/home/zwavejs/zwave-js-server# npm update @zwave-js/server
added 10 packages, removed 1 package, changed 37 packages, and audited 399 packages in 2m
83 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilitiesNotes & caveats
- copy your zwave key ! (it will also be shown through the migration wizard)
- in my case, all my devices were migrated but not all entities. I just recreated the missing entities later through the GUI. (mostly this meant recreating some graphs or other widgets).
- if you keep a backup of your homeassistant config folder/database, you can always revert.
Links
| zwave-js server npm implementation | https://www.npmjs.com/package/@zwave-js/server |
| zwave-js library documentation | https://github.com/zwave-js |
| nvm documentation | https://github.com/nvm-sh/nvm |
| installing node tools through nvm | https://heynode.com/tutorial/install-nodejs-locally-nvm/ |
| home assistant zwave-js docs | https://www.home-assistant.io/integrations/zwave_js/#advanced-installation-instructions |