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 most controllable 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:
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;import Homey, { ZwaveCommandClass } from "homey";
interface CommandClassBasic extends ZwaveCommandClass {
BASIC_SET: (args: { Value: unknown }) => Promise<void>;
}
export default class Device extends Homey.Device {
async onInit(): Promise<void> {
const node = await this.homey.zwave.getNode(this);
await (node.CommandClass["COMMAND_CLASS_BASIC"] as CommandClassBasic).BASIC_SET({ Value: true });
}
}
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
Homey Pro Z-Wave User Manual
The Homey Pro Z-Wave User Manual applies to Homey Pro (Early 2023) and newer, Homey Pro mini, Homey Self-Hosted Server and Homey Cloud.
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:
manufacturerIdproductTypeIdproductId
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.
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.
By default, the value is parsed as a signed integer. If your device requires the value to be interpreted as an unsigned integer, explicitly set the signed property to false in the setting's zwave configuration:
Security
There are two types of Security in Z-Wave: Security 0 (legacy) and Security 2.
Most newer devices support Security 2 (S2). In S2 there are different keys available: Access, Authenticated, Unauthenticated (and S0). The actual encryption algorithm is the same, it just determines which devices know which keys.
Homey will always grant all S2 keys that a device requests.
Homey Pro (2016-2019): Homey grants the highest requested key only.
Security 0 (S0)
Security 0 is not very secure and really inefficient, therefore it is not used by default. It is possible that devices only provide certain functionality when they are paired securely, for example a Z-Wave Doorlock can choose to only allow using COMMAND_CLASS_LOCK with secure communication. In this case your app should set the requireSecure property in your driver's zwave object to true. To find out what command classes require secure communication check your device's technical specifications.
By default Homey will use S2 if a device supports it. Due to the additional communication overhead of S0 your app needs to opt-into S0 by setting requireSecure to true.
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
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).
Check the device documentation from the manufacturer for an overview of the available association groups. Information can also be found here: https://products.z-wavealliance.org/
Homey is always added to association group 1, the Lifeline group. This way Homey can receive a notification when a device is factory reset for example. In that case the node is removed from Homey and the device is marked Unavailable.
To add Homey to other association groups automatically after pairing, add the corresponding group number to the associationGroups array property in the drivers zwave object.
Homey automatically determines whether to add a regular or multi-channel association to the group.
Note: the associationGroupsMultiChannel is handled the same way as associationGroups so Homey is added to those groups as well using the correct association command class. It is used for backwards compatibility but it is recommended to use associationGroups and set the app compatibility to >=13.2.0.
Associations between devices can be configured in the device settings. If a device supports COMMAND_CLASS_ASSOCIATION_GRP_INFO (most modern devices do), Homey uses this information to add a hint to the different groups explaining what they do. If this Command Class is not available or a more detailed hint is needed it can be provided in the associationGroupsOptions property.
Association Groups before Homey v13.2.0
In addition to "regular" (single-channel) associations devices with multiple endpoints can support "multi-channel association". In Homey versions before 13.2.0, Homey did not choose the regular or multi-channel association automatically. If multi-channel associations were necessary (to get updates from endpoints), they were configured using the associationGroupsMultiChannel property in the devices zwave options.
Note: in Homey before 13.2.0 it was possible to opt-out of the Lifeline association (group 1) by providing an empty array. As of version 13.2.0 the Lifeline association is always added.
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 has chosen an apropriate wake up interval. It may be nessecary to override 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 by Homey is: 30-16777215 (30 seconds to 194 days). Make sure to use a value that the device supports.
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 if they are specified in the multiChannelNodes property in the zwave options.
It is possible to override the settings of the Multi Channel Node by providing the settings option. This option takes the same values as the regular Device Settings:
homey-zwavedriver
A library named homey-zwavedriver has been developed for Node.js 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.
homey-zwavedriver is only compatible with SDK version 3. Its predecessor homey-meshdriver is available for SDK version 2.
When you are using homey-zwavedriver your device should extend ZwaveDevice instead of Homey.Device. This class implements some useful helpers that you can use to integrate your Z-Wave device with Homey. When a new Device is initialized ZwaveDevice#onNodeInit() will be called. In this method you should register all the devices capabilities. homey-zwavedriver supplies a ZwaveDevice#registerCapability() method that you only need to tell what capability your device has and which associated command class implements the capability.
If you are implementing a light device you can extend ZwaveLightDevice instead. This class already implements all the expected behaviour for a Z-Wave light.
Z-Wave API
If possible you should use homey-zwavedriver instead, only use the built-in Z-Wave API if you absolutely need to.
Command Class Reference
Last updated
Was this helpful?