Zwave basics

From ago control wiki
Jump to: navigation, search


Z-Wave Basics

This document should explain you the basics about inclusion, association and parameters of a Z-Wave device. This should be a beginner page for everybody who want to use Z-Wave devices.

First steps and needs

We would stongly advice you to have a Z-Wave-Stick attached to your system and use a Z-Wave-Remote Controller(Inclusion controller). Your first step is to learn your Z-Wave Remote Controller to the Z-Wave-Stick. After that you can start to learn your devices to the Z-Wave-Remote Controller. Only use the Remote Controller to learn new devices or remove devices. NEVER use the Z-Wave-Stick for this. The Stick should be always at the system - else you can run into problems with devices and their configuration.

Before you start to learn your first device with the Remote Controller you shoud read the manual of the device you want to use and look at the possible configuration parameters and group configuration. A good starting point is

Devices like switches and dimmers should work out of the box. More interest you should give to devices which have for example a power meter or devices with multiple sensors like a multilevel sensor. If you just "learn" a device to your Remote Controller you just have "connected a cable" - nothing else. Some devices are simple some need a configuration.

A Z-Wave Network will have Nodes. Every Node can have Groups. Groups are pre-definded by the manufacture. If you Plug your Z-Wave Stick you will have "Node 1" and if you plug your Z-Wave-Remote Controller it will get "Node 2" and so on. if you plug the next device it will get "Node 3". Now lets say that the device (Node 3) is a 2-function rocker switch. The one rocker could be "Group 1" and the other "Group 2". Now you can have for example a light with a Z-Wave switch which is "Node 4". So now you want to switch on the light if you press on the first rocker. In this case you need to tell "Node 3" that "Node 4" is in "Group 1" - this is an association. After you told this to the switch you can press the first rocker and the device will tell to the light switch to turn on or off. For more complex devices there can be extra parameters to tell the Group what to report.

In the following example we are using this hardware from Aeon Labs:

Installation and Configuration

Install the agocontrol zwave package by doing:

apt-get install agocontrol-zwave

You need to specify the usb serial device that is provided by the Z-Wave dongle on your system in the /etc/opt/agocontrol/conf.d/zwave.conf like this:


If you you also are using other USB ports. You will end up after reboot, that your /dev/ttyUSB0 might be setup to another USB device and then your stuff won't work. To bypass this you declare an alternative usbdevice. via udev rules []

Other controllers need different devices, e.g. /dev/ttyAMA0 for Razberry

Include your first device

You simply can press the "Include" buttons on the Remote and the include button on the device you want to add. The details are in the docs of the Remote Controller and of the device. Now you you have connected your Controller with the Device. You now already should know if you need to configure your device. Please take care on battery powered devices - they just wake up in defined intervall, since they need to save battery. In the docs you should find some more details. Sometimes you just need to press the include button for 3 times to keep it awake for a few minutes. So mind that your device is not sleeping when you want to send a configuration!

Add association for device

In this example I am using a Aeon Labs Multilevel sensor which is included as "Node 5". You can find technical docs here:

This multilevel sensor will not send any report about temperature, humidity and luminance by default - you need to configure it. First you will to is to include the device with the Z-Wave Remote and tell the device that "Group 1" should tell everything to "Node1". This is an association. In ago control you can do it with this command:

/opt/agocontrol/bin/messagesend uuid=a00c2e7c-6cbf-4bb1-85a3-dd65a8d762b0 command=addassociation node=5 group=1 target=1

The uuid is the uuid of the zwavecontroller device, the command is "addassociation", the node is our multilevel Sensor with "Node 5", the group we want to set on the device is "Group 1" and the target is our "Node 1". This command tells the multilevelsensor to add our "Node 1" to the "Group 1" of the device. Now we'll get all reports from "Group 1" to our "Node 1". Next step is to configure the device parameters of the multilevelsensor.

Set parameters of device

Latest at this point you should have a deep look in the documentation or here for this example. Now we want to set the parameter 101 which reports need to send automatically in timing intervals for "Group 1". We need to send a bitset with a size of "4". The size is very important! So how to come to the value now what we want to send. Here are the "Values" the manual is tells:

0	   ->  	Battery report
5	   ->  	Temperature
6	   ->  	Luminosity
7	   ->  	Humidity

Lets say now we have to set this bits: 0, 5, 6 and 7 and think in Bits. The Bit "0" is on the right side:


Now we have this schema in front of us since Bit 1 to 4 are reserved:

xxxRRRRx (R = reserved)

If we want to enable for example just the battery report we will have this:


If you just want to get the humidity you will have this:


We want to enable Bit 0, 5, 6 and 7 (Battery report, Temperature, Luminosity, Humidity):


So now we need to convert our Bin value to a Bin number. This is simply done with a "Calculator". You can open the calculator on a Mac and switch to "Programmer View". Then press on "10". Make sure you have a no value for now - a 0 is fine. Now you see the Bin Values in the bottom and you click on Bit 0, 5, 6 and 7. Your result should be "225" then. This is what we need four our command. You can send a command then:

/opt/agocontrol/bin/messagesend uuid=a00c2e7c-6cbf-4bb1-85a3-dd65a8d762b0 command=setconfigparam node=5 param=101 size=4 value=225

The uuid is the uuid of the zwavecontroller device, the command is "setconfigparam", the node is our multilevel Sensor with "Node 5", parameter is "101" with a size of 4 (MIND THE SIZE) and our calculated value "225".

Now we are done and should get automatically the Battery report, Temperature, Luminosity, Humidity reported to our "Node 1".

Sometimes you can find a XML File for your device with some useful information inside and you do not need to "code the numbers". You can see many of them linked here:


You can run diagnostics from a terminal with:

sudo -u agocontrol /opt/agocontrol/bin/agozwave -d

Special device types

The dongle itself is announced as "zwavecontroller" device type to the resolver. You can send some special commands to it for z-wave device management:

allon - switch all z-wave nodes on
alloff - swich all z-wave nodes off
addnode - add a node to the z-wave network
removenode - remove a node
addcontroller - add a contrller
reset - WARNING, this deletes the network information from the stick. You need to rebuild your network afterwards
Personal tools