Developer Resources

Along with making the Z-Wave Specifications available to the general public, Sigma Designs is also providing additional resources to developers to jump start the development of Z-Wave Over IP products and applications. The suggested development environment here is a Raspberry Pi 3. Sigma Designs provides a Raspbian SD Card image that has been customized and includes everything that is needed to develop for Z-Wave Over IP - be it using the Z/IP Gateway directly, or via the Z-Ware middleware. Both come pre-installed and pre-configured in the SD card image.

It is recommended that you follow the guide below as an introduction to Z-Wave Over IP. The guide will walk you through the process of setting up the SD card and using the included Reference Z/IP Client to include a Z-Wave light switch to your network. Once you have a running network and feel like exploring further we recommend that you read through the Z/IP and Z-Ware Specifications to get a general understanding of how to interact with both of them.

The documentation for both Z/IP and Z-Ware clients can be found here:

Z/IP Client documentation

Z-Ware Client Documentation

Both clients are developed completely in the open and their code repositories are hosted on GitHub:

Z/IP Client Repository - libzwaveip

Z-Ware Client Repository - PyZWare

The SD card image for the Raspberry Pi 3 can be found here:

Z-Wave Over IP SD card image for Raspberry Pi 3

After completing the initial setup described below, you can continue to the next tutorial and connect your Z-Wave network to the IFTTT service.

"Instant Success" Guide

This guide will instruct you on how to toggle a light switch using Z-Wave Over IP. The guide assumes that you have the following hardware on hand:

Hardware Requirements

Raspberry Pi 3
Bridge Controller UZB
SD Card
(at least 2GB)
A light switch that speaks Z-Wave

Do note that Z-Wave devices operate on frequencies that are specific to the regions they're intended to work in. If you purchase any Z-Wave devices to follow this guide, ensure that they use the frequency that is used in your geographical region - and of course, that all the devices in your network use the same frequency.

This guide assumes that the light switch is not currently included in a Z-Wave network and is ready to be included into one.

Working with the Raspberry Pi

  1. Download the SD Card Image

Sigma Designs provides an SD Card image for the Raspberry Pi that comes preloaded with everything that is needed to start working with Z-Wave Over IP. The image can be downloaded from here.

  1. Load the SD Card Image

This guide uses "Etcher" from resin.io to prepare the SD Card. It can be downloaded from the Etcher website: https://www.etcher.io Etcher provides a simple interface that looks the same across multiple platforms to flash SD Card images in three easy steps:

  1. Select the image file
  2. Select the destination drive
  3. Flash!

Select the image you downloaded from the Public Z-Wave site, insert the SD card you'd like to use to your computer, and click "Flash!"

Etcher
Using "Etcher" to prepare the SD Card

  1. Connecting the Raspberry Pi

There are many ways to work with the Z-Wave over IP installation. Of course, it is intended to be accessed over the network and from different devices, but for the sake of simplicity, and to help illustrate key concepts, this guide will assume that you are working from within the Raspberry Pi itself. This can be done by either connecting the Pi to a display and a keyboard, or by connecting to it over a secure shell. Users following this guide on macOS or Linux can use the built-in ssh command to connect. Windows users will need an SSH client, like PuTTY (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) to connect. To simplify the setup, this guide suggests that you connect the computer you're working from and the Pi to the same Ethernet router - ideally with no other devices in that network.

The provided image defaults to booting the Raspberry Pi with the hostname raspberrypi so identifying and connecting to it is simple. The image also announces its SSH service over DNS-SD using the _ssh._tcp service type to aid you in locating it.


Listing SSH services on the local network

The image comes with a pre-made user account named pi that has the password raspberry. This guide assumes you are authenticating as this user for the remainder of the steps.


The Z-Wave Over IP Raspberry Pi MOTD

Once authenticated, the shell prompt will display a list of common tasks and the commands that run them. You can always refer back to this list should you need a refresher or what a command does, or to copy-paste them to save you some typing, at any time by running:

cat /etc/motd

Working with the Reference Z/IP Client

  1. Preparing the Hardware

The image comes with both a pre-installed Z/IP Gateway and a pre-built version of Sigma Design's reference implementation of a Z/IP Gateway client. You'll be leveraging both in this guide.

Connect a Z-Wave UZB Bridge Controller to the Raspberry Pi. The pre-installed Z/IP Gateway is already configured to look for a connected UZB at the path the Raspbian image connects it to by default.

  1. Starting the Z/IP Gateway

Start the Z/IP Gateway by running:

/etc/init.d/zipgateway start


The Z/IP Gateway starting up

With the Z/IP Gateway now running we can move on to connecting to it with the Reference Z/IP Client. The Reference Z/IP Client needs to be provided the IP address of a Z/IP Gateway to connect to, so the next step is to determine the IP address the Z/IP gateway started above is listening on. The Z/IP Gateway advertises all of the Z-Wave devices it provides connectivity to, as well as itself, over DNS-SD. The Z-Wave Over IP image that you're running has a tool to browse these services called avahi-browse. You can use the tool to locate, and determine the IP address of, all the Z-Wave devices that Z/IP Gateways in your local network are advertising by running:

avahi-browse _z-wave._udp -r


Listing Z-Wave services in the local network

This command continues running in the background, looking for more services, until you stop it with Ctrl+C. In our simple setup, the only advertised Z-Wave device will be the Z/IP Gateway. You may notice that the Z/IP Gateway might have more that one address assigned, and that it uses both IPv4 and IPv6 addresses. For the remainder of the steps, this guide will focus on IPv6. Also note that the advertisements say the devices are listening on port 4123. In reality, all of the services listen on both port 4123 and 41230. Communication with port 41230 needs to be encrypted, while communication with port 4123 happens in the clear but is only available on builds of Z/IP Gateway that explicitly allow non-encrypted communication. The Z/IP Gateway provided in the Z-Wave Over IP image does not allow non-encrypted communication.

  1. Starting the Reference Z/IP Client

Now that the IP address the Z/IP Gateway is listening on is known the Reference Z/IP Client can be started and instructed to connect to the Z/IP Gateway. Communication with the Z/IP Gateway is protected with TLS, specifically DTLS 1.0. In order to be able to connect to the Gateway, the Reference Client needs to provide a Pre-Shared Key, or PSK for short, in addition to the IP address of the Gateway. The Reference Client expects the Z/IP Gateway to be listening on the default port for Z/IP DTLS communication - 41230. This guide assumes that the Z/IP Gateway is configured to use the default PSK, which is 0x123456789012345678901234567890aa, and that the Gateway is listening on the IPv6 address fd00:aaaa::3

A pre-compiled version of the Reference Z/IP Client is included in the SD card image in the pi user's home directory under libzwaveip_ver_X - where the X stands for a version number. You might consider adding this directory to your working path to allow you to conveniently execute the client from elsewhere in the system. To start the Reference Client and connect to the Gateway, change into the libzwaveip_ver_X directory and run: (replacing fd00:aaaa::3 with your zipgateway's IP Address):

./reference_client -p 123456789012345678901234567890aa -s fd00:aaaa::3


Starting the Z/IP Reference Client

The Reference Z/IP Client provides its own command line and command line interpreter, including bash-like "Tab completion" for Z-Wave Command Classes and their Commands.

  1. Including the Light Switch

To instruct the Reference Z/IP Client to include a new Z-Wave device type the following command:

addnode


Initiating node inclusion

The client will begin negotiating with the Z/IP Gateway, who'll in turn get ready to include a new device. The command doesn't produce any output in the Reference Client's console, but the Z/IP Gateway is now waiting for a new device to request inclusion to the Z-Wave network. Different device manufacturers have different procedures for including their devices, so you'll need to refer to the product manual for the light switch you're using for the correct procedure. Typically, a single- or quick triple-press on their button is what is required to request inclusion.

Once the node has been successfully included, the Reference Client will print out a summary of the Command Classes the included device can work with, and some additional information to its console.


Caption

  1. Controlling the Light Switch

To see a list of all the Z-Wave devices that are reachable by the Reference Client type:

list


Listing reachable Z-Wave devices in the Reference Client

In the Reference Client, you refer to directly to a Z-Wave device's channel. If the light switch you're using has multiple channels you will see multiple entries with very similar Service Names. This guide controls a simple Z-Wave device which doesn't have multiple channels. To turn the light switch on you'll send a Z-Wave message to it using the "Switch Binary Command Class." This Command Class defines the "Binary Set" Command, which is used to change the state of on/off switches. For a complete description of this, and other Command Classes and their Commands, refer to the "Command Class Specification" document.

The Reference Client uses the send command to transmit messages to Z-Wave devices. The generic format of this command is send <SERVICE_NAME> <COMMAND_CLASS> <COMMAND> <VALUES ... >. The values for Command Class Commands need to be provided in "ASCII encoded hex" notation, which means leading zeros and two characters per byte. As a convenience, the send command provides bash-like "Tab completion" for Command Class names and their Commands.

To turn the light switch on type (replacing Switch Binary [efb1db2f0600] with your light switch's Service Name):

send "Switch Binary [efb1db2f0600]" COMMAND_CLASS_SWITCH_BINARY SWITCH_BINARY_SET ff


Using the Reference Client to turn on a Z-Wave device

To turn the light switch back off, type (replacing Switch Binary [efb1db2f0600] with your light switch's Service Name):

send "Switch Binary [efb1db2f0600]" COMMAND_CLASS_SWITCH_BINARY SWITCH_BINARY_SET 00


Using the Reference Client to turn off a Z-Wave device

Continue exploring the possibilities of Z-Wave by connecting your setup to the IFTTT service.