OpenZWave addon for Node.js (all versions) including management and security functions
C++ JavaScript Python
Clone or download
ekarak Merge pull request #234 from OpenZWave/bugfix/issue#233-toNumber-depr…
…ecation

Bugfix/issue#233 fix various deprecated API calls
Latest commit ce99f8a Jun 25, 2018
Permalink
Failed to load latest commit information.
config fix for Node.JS 4 nan scope issue (nan#440), completely refactor OZW … Sep 26, 2015
lib Merge pull request #184 from meastman/fix-path-detection Aug 12, 2017
src Update all emitted callbacks to use AsyncResource Jun 25, 2018
types Added type definitions, so that IDEs like WebStorm would provide code… Nov 8, 2017
.editorconfig adjust copyright dates Feb 5, 2017
.gitignore ignore .idea May 12, 2017
.npmignore fix npmignore Feb 5, 2017
.travis.yml add appveyor ci May 1, 2018
CHANGELOG.md Update all emitted callbacks to use AsyncResource Jun 25, 2018
LICENSE.md adjust copyright dates Feb 5, 2017
README-api.md Update README-api.md Jan 30, 2018
README-events.md issue #205: clarify on eventIds Feb 2, 2018
README-example.md amend docs Aug 12, 2017
README-mgmt.md updated readme to reflect that cancelControllerCommand is not depricated Apr 24, 2016
README-raspbian.md update raspbian docs Dec 10, 2016
README-security.md update docs Oct 15, 2015
README-ubuntu.md Copy options.xml to project directory Aug 7, 2015
README.md amend CI buttons May 1, 2018
appveyor.yml add appveyor ci May 1, 2018
binding.gyp Fixing a common coexistence issue. Look for the newest referece first. Jul 29, 2017
notes.txt first working implementation with NaN Jun 14, 2015
package.json version 1.4.5 Jun 25, 2018
test.js make test script exit after settimeout Feb 18, 2017
test2.js potential fix for #146 Jan 30, 2017
test3.js make populateValueId raise meaningful errors May 28, 2017

README.md

node-openzwave-shared

LinuxLinux Build Status WindowsWindows Build status Join the chat at https://gitter.im/OpenZWave/node-openzwave-shared

This is the homepage for node-openzwave-shared, the official binary add-on for Node.js, which wraps Open ZWave, a high quality C++ library for controlling Z-Wave networks.

You can now easily control and manage your ZWave devices (lights, dimmers, blinds, you name it) from within Node.js applications. This library also supports secure devices (eg door locks) that require encryption.

All widely used Node.js versions are supported with the help of NaN. This add-on is currently tested against 0.12.x on ARM and 4.2.x on x86_64, but it should also work on all supported Node.js versions (as early as 0.11.12) and architectures.

Check out the Node-Red integration project for an interesting use case, in which I've wired up ZWave and KNX devices working together as one big happy automated home.

This addon is currently able to:

  • scan a Z-Wave network and report on connected devices,
  • write values to zwave nodes
  • monitor the network for changes,
  • heal nodes and/or the network
  • perform management tasks (add/remove nodes, replace failed nodes, manage their group associations etc)

API change notice (v1.4.0) enablePoll() and disablePoll() used to affect only the first ValueID of any given command class. This is wrong, as for multi-instance devices you probably need to poll multiple ValueID's. These calls now accept a valueId, in very much the same way as setValue() does. This means that you now have to pass a valueID object (or its 4 constituents) for each value you want to enable/disable polling for.

Important notice

This library differs from its ancestor library in that it links dynamically to an OpenZWave shared library by means of your system dynamic linker. This is in contrast to statically linking OpenZWave as part of the node.js addon.

Thus you need to have OpenZWave fully installed on your system (both the compiled library AND the development headers) before trying to install this little baby. I know this diverges from the dominant npm paradigm, but with the shared lib approach:

  • compilation / installation is a lot faster and
  • OZW minor upgrades / bugfixes are way lot easier.

This also means that you need to be careful if you upgrade your OZW library: you might need to rebuild this addon, otherwise you'd might get api mismatch exceptions.

Prerequisites

Linux

You will need to ensure the OpenZWave library and headers are installed first. You can do this one of two ways.

MacOS/X

The only dependency that you need before compiling is pkg-config. Then, you could either pull down the OZW repo from Github and do a make && sudo make install , or you could try installing OpenZWave using brew install open-zwave.

Windows

Since there is no standard installation location for Open Z-Wave on Windows, it will be automatically downloaded, compiled, and installed when you install this module.

Installation and test script

Whenever you have OpenZWave installed in your machine, then all you need to do is:

$ npm install openzwave-shared

To try it out, boot up NodeJS, and use the .load shell helper function to boot up a basic OpenZWave CLI. This will initialise and expose 1) a zwave object that you can use to send commands and 2) the nodes object to get a list of all nodes:

$ node
> .load test2.js
...
...

// the 1st node is the USB controller stick
> console.log(nodes[1])
{ manufacturer: 'Aeotec',
  manufacturerid: '0x0086',
  product: 'Z-Stick S2',
  producttype: '0x0002',
  productid: '0x0001',
  type: 'Static PC Controller',
  name: '',
  loc: '',
  classes: { '32': { '0': [Object] } },
  ready: true }

// set dimmer (node 5) to 50%
> zwave.setValue(5,38,1,0,50);
undefined
> node5: changed: 38:Level:54->54

Notice 1: If you receive the error cannot find -lopenzwave on a 64-bit Linux system, libopenzwave.so was likely compiled into /usr/local/lib64. Run the terminal command ld -lopenzwave --verbose for a list of search locations used. You can workaround this by providing a symlink to one of the listed locations such as /usr/local/lib. Run sudo ln -s /usr/local/lib64/libopenzwave.so /usr/local/lib/libopenzwave.so creates symlink so that the file appears to be in the location that ld looks in. Now npm install should work.

Notice 2: nodejs Debian/Raspbian package (v0.10.29) causes an issue REPLACE_INVALID_UTF8 (cf. https://github.com/nodejs/nan/issues/414). You can use node from herokuapp or upgrade some node packages: sudo npm -g install npm node-gyp.

In case you want to develop your application in TypeScript, there is also a TypeScript declaration file available. Besides adding typechecking to your codebase this will also help you to navigate the API and see the type of parameters available for each function. You can download the latest version of the declaration file from GitHub.

Development documentation

Environment-specific documentation

License

The Open Z-Wave library that this module heavily relies upon is licensed under the Lesser GPLv3.

Everything else (all the bits that I and Jonathan have written) is under the vastly more sensible ISC license.