Z-Wave

Z-Wave is a two-way wireless communication standard on the 868 MHz - 915 MHz band. It is very similar to Zigbee.

Z-Wave is built around a principle called Command Classes. A Command Class is a group of Commands, that each can make a device perform an action, or request data.

Commands usually belong to one of 3 categories:

  • "set" commands update a value

  • "report" commands to let devices know the current value

  • "get" commands are a request the current value, the device will send a report in response

As an example lets take a look at COMMAND_CLASS_BASIC, this Command Class is supported by all devices. It has a BASIC_SET command, which sets a boolean (usually on/off), a BASIC_GETcommand, and a BASIC_REPORT command. Sending a BASIC_GET to the device will make the device send a BASIC_REPORT to Homey. The BASIC_REPORT contains the boolean (on/off) value.

Sending a command to a device from Homey is simple:

/drivers/<driver_id>/device.js
const Homey = require('homey');
โ€‹
class Device extends Homey.Device {
async onInit() {
const node = await this.homey.zwave.getNode(this);
โ€‹
await node.CommandClass.COMMAND_CLASS_BASIC.BASIC_SET({ Value: true });
}
}
โ€‹
module.exports = Device;

You can view working examples of Homey Apps that use Z-Wave at: https://github.com/athombv/com.fibaro-exampleย and https://github.com/athombv/com.danalock-exampleโ€‹

Pairing

Tell Homey your driver supports a Z-Wave device by adding a zwave object to your driver manifest. To create a driver for a Z-Wave device you need to know the following properties of the device:

  • manufacturerId

  • productTypeId

  • productId

To find out your device's IDs, pair it as a Basic Z-Wave Device. After successfully pairing you can find these values in the device settings. All Z-Wave devices are paired using the built-in Z-Wave pair wizard. Upon pairing a Z-Wave device, an App will be selected if all three IDs match.

You can customize the built-in Z-Wave pair wizard by supplying more specific instructions and a custom image in the learnmode property.

/drivers/<driver_id>/driver.compose.json
{
"name": { "en": "My Driver" },
"class": "light",
"capabilities": ["onoff"],
"zwave": {
"manufacturerId": 271,
"productTypeId": [256],
"productId": [260],
"learnmode": {
"image": "/drivers/<driver_id>/assets/learnmode.svg",
"instruction": { "en": "Press the button on your device three times" }
}
}
}

It is possible to add multiple productTypeId and productId values in order to support multiple devices with the same Driver.

Most Z-Wave devices are unpaired in the same way as they are paired but in case the unpair wizard benefits from custom instructions or a different image it is possible to provide unlearnmode options to your Z-Wave driver manifest. unlearnmode accepts the same properties as learnmode.

Manifest

In addition to the essential driver zwave properties manifacturerId, productTypeId and productId there are properties allow you to configure the behaviour of your Z-Wave device.

Some of these properties configure the behaviour of your device while pairing, so changes to them will require you to remove and re-add your devices.

Device settings

Z-Wave devices often have configuration parameters, in Homey these can be set in the device settings. The only thing you need to do is tell Homey which setting corresponds to which Z-Wave configuration parameter of the device. You can do this by adding a zwave property to the device setting that controls the configuration parameter. Read the device setting guide for more information.

/drivers/<driver_id>/driver.settings.compose.json
[
{
"id": "minimum_brightness",
"type": "number",
"label": { "en": "Minimum brightness level" },
"value": 1,
"attr": { "min": 1,"max": 98 },
"hint": { "en": "This parameter determines the minimal brightness." },
"zwave": {
"index": 13,
"size": 1
}
}
]

Default device configuration

After pairing a device, Homey can write configuration parameters to ensure they are set to the correct value using the defaultConfiguration parameter of the devices zwave options.

Configuration parameters can be 1, 2 or 4 bytes long, use the size property to tell Homey how many bytes to write. The value is a signed integer and its range is determined by the size of the parameter:

  • -128, 127 for size=1

  • -32768, -32767 for size=2

  • -2147483648, 2147483647 for size=4

/drivers/<driver_id>/driver.compose.json
{
"name": { "en": "My Driver" },
"class": "light",
"capabilities": ["onoff"],
"zwave": {
"manufacturerId": 271,
"productTypeId": [256],
"productId": [260],
"defaultConfiguration": [
{
"id": 3,
"size": 1,
"value": 123
}
]
}
}

Association Groups

Association groups allow Z-Wave devices to be linked together (associated) so that they can communicate directly without needing a central controller, like Homey. For some devices, Homey needs to be added to their association group to be able to receive status updates. For example devices may choose to only send "central scene activation" commands to their "lifeline" (the node in association group 1).

By default Homey will always associate with group 1, this behaviour can be customized by adding a associationGroups property to the devices zwave options. Entering an empty array or leaving out the number 1 will cause Homey to remove the association with group 1.

Users can configure the associations from the device settings, use the associationGroupsOptions property to add hints explaining what the various association groups do and how to configure them correctly.

/drivers/<driver_id>/driver.compose.json
{
"name": { "en": "My Driver" },
"class": "light",
"capabilities": ["onoff"],
"zwave": {
"manufacturerId": 271,
"productTypeId": [256],
"productId": [260],
"associationGroups": [1, 3],
"associationGroupsOptions": {
"3": {
"hint": { "en": "On/off signals from input 3" }
}
}
}
}

Battery Device Wake Up Interval

Z-Wave battery devices can have special behaviour to conserve power. These devices will send messages at any time but they are not always listening for messages. The interval with which it is possible to send messages to such a device is called the "wake up interval". By default the manufacturer will have set the wake up interval to a duration they think is appropriate but it may be necessary to overwrite this default. In those cases you can set the wakeUpInterval property in the device's zwave options. This property controls the desired wake up interval in seconds. The range of allowed values is: 30-16777215 (30 seconds to 194 days)

/drivers/<driver_id>/driver.compose.json
{
"name": { "en": "My Driver" },
"class": "light",
"capabilities": ["onoff"],
"zwave": {
"manufacturerId": 271,
"productTypeId": [256],
"productId": [260],
"wakeUpInterval": 900
}
}

Multi channel nodes

In Z-Wave a device can only implement a command class once. This means that technically a single Z-Wave device can only have a single switch, because it can only implement, for example, COMMAND_CLASS_SWITCH_BINARY once. In order to give devices the ability to implement a command class multiple times, Z-Wave has Multi Channel Nodes. A Multi Channel Node is a type of Z-Wave node that contains several "endpoints" which are each their own Z-Wave node. Each of these endpoints can individually implement, for example, COMMAND_CLASS_SWITCH_BINARY.

In Homey after pairing a Multi Channel node, several devices will be added to the devices overview.

/drivers/<driver_id>/driver.compose.json
{
"name": { "en": "My Driver" },
"class": "light",
"capabilities": ["onoff"],
"zwave": {
"manufacturerId": 271,
"productTypeId": [256],
"productId": [260],
"wakeUpInterval": 900
},
"multiChannelNodes": {
"1": {
"name": { "en": "MultiChannel device 1" },
"class": "socket",
"capabilities": ["onoff", "measure_power", "meter_power"],
"icon": "/drivers/<driver_id>/assets/icon-multichannelnode1.svg"
}
}
}

ZwaveDriver

A library named ZwaveDriver has been developed to ease development of Z-Wave devices in Homey. It mainly maps Command Classes to Homey's capabilities. It is recommended for most app developers to use this library.

ZwaveDriver is only compatible with SDK version 3. Its predecessor MeshDriver is available for SDK version 2.

npm install homey-zwavedriver

Your device should extend ZwaveDevice. Start by looking at the docs for ZwaveDevice. This is the class you most likely want to extend from. If you are implementing a light device take a look at ZwaveLightDevice.

See examples/fibaroplug.js and examples/fibaroplug.jsonโ€‹

Z-Wave API

Note: this API should rarely be used, use ZwaveDriver instead.

/drivers/<driver_id>/device.js
const Homey = require('homey');
โ€‹
class Device extends Homey.Device {
async onInit() {
// get the node by our Device's instance
const node = await this.homey.zwave.getNode(this);
โ€‹
// get the BASIC status
node.CommandClass.COMMAND_CLASS_BASIC.BASIC_GET()
.then((result) => {
if (result["Value"]) {
this.log("Device is turned on");
} else {
this.log("Device is turned off");
}
})
.catch(this.error);
โ€‹
// battery nodes can emit an 'online' event when they're available
// you can send commands within 10s of this event, before the node goes to sleep again
node.on("online", (online) => {
if (online) {
this.log("Device is online");
} else {
this.log("Device is offline");
}
});
โ€‹
// register for 'report' events
node.CommandClass.COMMAND_CLASS_BASIC.on("report", (command, report) => {
this.log(command.name); // e.g. BASIC_REPORT
this.log(report); // e.g. { Value: true }
});
}
}
โ€‹
module.exports = Device;

Command Class Reference

The Command Classes are documented extensively by Sigma Designs, and are freely available.