Homey has 8 wireless radio's onboard, namely Wi-Fi, Bluetooth, ZigBee, Z-Wave, 433 MHz, 868 MHz, NFC and Infrared. This blogpost will be a in-depth view of Z-Wave, and how we've integrated it into Homey. While intended for techies, I hope it's understandable for enthusiasts as well!
What is Z-Wave?
Z-Wave is a wireless protocol designed by Sigma Designs. The protocol is proprietary, which means that it is not open, and manufacturers have to pay a license fee when including the technology in their product. In fact, the chip required for Z-Wave can only be bought from Sigma Designs. In exchange, they develop, maintain and support the protocol and the compatible devices.
The Z-Wave protocol operates on the 868 MHz band in Europe, 916 MHz in the USA and 922 MHz in Asia and Australia. This is due to different governmental regulations. Therefore, when ordering Homey, we ship the right version for your country. Every device that uses Z-Wave must pass certification to ensure that Z-Wave devices always work together. In theory this is a great idea, but in reality we found it to be much more complex. More about that later though.
Homey is a certified Z-Wave Plus controller and can be found in the Z-Wave Product Catalog. (Note our little joke, Homey's Product ID is 0xBA5E, which reads 'Base' in hexadecimal), meaning it supports the latest and most secure Z-Wave version.
Homey embeds the ZM5304 module, the most recent and advanced Z-Wave module available. What exactly happens inside of the chip is Sigma Design's work, but we have programmed Homey to talk to the chip to do our magic.
Mesh Network
One of the advantages of Z-Wave is its so-called 'mesh network'. What this basically means is that devices in your network, e.g. Homey, a plug and a sensor, can wirelessly reach each other by using one another. Imagine you have Homey in your living room downstairs, a plug in the bedroom upstairs and a motion sensor in the attic.
When the motion sensor goes off, and wants to reach Homey, it sends a signal to the plug, and the plug forwards this message to Homey. A signal can make up to 4 hops, increasing the effective range a lot. To save your sensors batteries, only devices connected to a permanent power source repeat signals of other devices.
This mesh network is a big advantage over protocols such as Wi-Fi or Bluetooth, because the range can be increased with every device added to the network. It also keeps the devices' energy usage very low. In the future, we will update Homey's software to provide a visual map of the Z-Wave network at home.
A simple mesh network. The sensor (right) contacts Homey (left) through the plug (middle)
The protocol
Communication with Z-Wave devices is very simple. There are three types of messages: GET, SET and REPORT. A 'SET' message can change something on the device, e.g. turning it on or off. A 'GET' message asks for a value, e.g. if the device is turned on. After every 'GET' message, a 'REPORT' message is then sent by the device, containing the requested value. 
Messages are grouped by Command Classes. This is a collection of commands that belong together, e.g. all thermostat-like commands are grouped in the Thermostat Command Class. A Command Class can be supported by a device, and always has a version, by default v1. Command Classes are backwards compatible, so even the device updates, communication should be still possible.
The Z-Wave documentation defines how messages look. In the simplest case, a BASIC_SET message, can send one byte (a byte is a number between 0 and 255). For example, when Homey sends BASIC_SET with byte '255' to a socket, the socket will likely turn on. Sending '0' will turn off the socket. More advanced commands can specify many parameters, which are essentially many bytes glued together. It depends on the Z-Wave controller (Homey) if a device can be supported, because it must know these commands.
Homey Apps and Z-Wave
When we first started with our Z-Wave implementation, we followed the guidelines very closely. Because Z-Wave is a defined protocol, we figured that once you implement the most used Command Classses and their Commands all devices will be automatically supported. At least, that was the theory.
We soon found out that many devices chose their own implementation of commands. For example, one sensor would send their temperature values using the Command Class 'Multilevel Sensor', whereas the other would send it using the Command Class 'Notification'.
Some devices even created a Multichannel Node, a 'virtual' device, for each reading. Sigma Designs have really done a great job at creating a wireless protocol, but the interoperability between devices is a problem not yet solved (even with other wireless technologies, this is a recurring problem and the reason why we've built Homey in the first place).
With our experience, we've chosen to take a unique approach, because we always design for the best user experience. One of Homey's unique assets is our App Store and our community who helps building them. The best user experience, we thought, was a dedicated app for every device. By this method, Apps don't only pack the right Command Classes, but also include specific icons, pairing instructions and options, making pairing, recognising and using devices way easier.
To speed up development, we have created a module named ZwaveDriver, which can be included by any developer in their app. It takes most of the hard work, and leaves the app developer with grabbing the right values and converting them to Homey's standard.
Parsing Z-Wave messages
Z-Wave is a very low-level protocol, because every byte sent counts. Values are usually stored in bytes, a bitmask (e.g. 1011 could mean yes, no, yes, yes) and other types of 'harder' programming concepts. The BASIC_SET message we talked about earlier sends 255 as a 'yes', for example.
This creates a problem, however. Homey developers are used to JavaScript, because all Homey Apps are written in JavaScript. Ideally, the developer could send 'BASIC_SET' with a value 'true', instead of '255'. For example:
node.CommandClass.COMMAND_CLASS_BASIC.BASIC_SET({
"Value": true
}, function( err ) {
if( err ) return console.error( err );
});
So that's exactly what we did! Sigma Designs provides a .xml file with all the Command Class definitions, which is used for their debugging software. At Athom however, we're the good kind of lazy, so we wrote a script that takes this file as input, and generates a .json file for every Command Class with all its Commands and parameters.
Homey then loads these .json definitions, and automatically generates the Command Classes and their Commands for each Z-Wave device. All possible types of data, e.g. Byte, Bitmask, etc. can be converted from a JavaScript object to a raw Buffer (to send), and vice versa when Homey receives a 'REPORT'. A few weeks ago, Sigma Designs released a new version of their specification. It took us literally 2 minutes to update Homey to this new version, because of our unique approach!
Generic features
Some generic features can be better managed from Homey itself, than to reinvent the wheel for every app. For example, most battery-powered devices have a 'Wake Up Interval', which is the amount of seconds it'll take for them to be reachable to receive commands, e.g. new settings or a GET command.
Upon pairing, Homey reads this value, and optionally set a new value if the app developer provided a new value. The same happens for associations, which are the 'channels' Z-Wave devices can send messages on when something happens. For example, if an app needs a 'BATTERY_REPORT' command, but the device only sends that report on Association Group 3, the app developer can instruct Homey to make Homey join group 3 upon pairing. Default configuration parameters behave the same. As you can see below, app-specific settings and Homey-core settings work very nice together.
Pairing behavior
Upon pairing, a so called 'interview' takes place. This is simply Homey asking the device for information useful afterwards. For example what the device's Manufacturer ID and Product ID are, the supported Command Classes and their versions, etc. When that's done, Homey looks if there's a compatible app installed, and then figures out if any app-specific commands have to be sent.
As discussed above, these can be default configuration parameters, association groups, etc. It is not possible to search our App Store during pairing, because some battery devices go to 'sleep' if Homey has to find, download and install an App in the meantime.
So make sure, when adding a Z-Wave device to Homey, to download the App first. A device that's asleep makes them unavailable. We have some very neat ideas to work around this in a future software version.
Network range
Because Z-Wave is a mesh network, the range can depend enormously on how many non-battery devices you also have paired - the more, the better. Homey is tested at certification to reach at least 40 meters point-to-point range, but of course walls and other obstacles might influence this.
At the moment, Homey does an auto-discovery of new network routes that signals can take every 30 minutes, or after a reboot (some controllers call this 'healing'). In a future update, a map of all devices and how they talk to each other will be visible. From there, broken nodes can be easily found and repaired.
Conclusion
In this blog post, we've discussed the inner workings of Z-Wave, and how we've designed Homey to allow for a great user experience without sacrificing tools for power users. Our bet on Apps has been proven to be a successful one, with all major and even some minor and upcoming brands supported.
We really loved how the Athom Community has helped us to support most brands in no-time! It was heart-warming to see that some really good coders took it upon themselves to support some brands from scratch, and others have helped a lot by supplying configuration parameters found in the manuals.
Because of this combined effort, even the normal user can use Z-Wave without it becoming too technical, which is one of the things we strive for. Thank you all for that!
