node-openzwave-shared

Linux Linux Build Status Windows Windows Build status

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.

Manually compiling OpenZwave involves the usual dance of 1) downloading its source tarball (latest code from GitHub or a stable release) or from the OpenZWave snapshots repository and then 2) compiling it and installing on your system (make && sudo make install && sudo ldconfig)
You could also install OpenZWave via a precompiled package that's suitable for your Linux distribution and architecture. Notice: Be sure to install BOTH the binary (libopenzwave-x.y) AND the development package (libopenzwave-dev).

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. nodejs/nan#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.

hovissimo/node-openzwave-shared