-
Notifications
You must be signed in to change notification settings - Fork 24
Using the Example Applications
The SD Card image that was downloaded and prepared in "Preparing a Raspberry Pi 3" may already contain a copy of the libzwaveip sources. If it does, it is recommended that you remove them and replace them with a copy that is cloned from this repository.
libzwaveip includes two sample applications that demonstrate how a Z/IP Client can handle outgoing and incoming messages to/from a Z/IP Gateway. The reference_client application provides a command line interface that can list discovered Z-Wave IP devices and send Command Class messages to them. The reference_listener application provides visualization of Command Class messages that a zipgateway forwards to its Unsolicited Destination. Each of these applications are explained in a little more detail further below.
Command Classes and their structure are briefly explained in Command Class Basics.
In order to build libzwaveip and the sample applications, some dependencies need to be installed first:
$ sudo apt-get update
$ sudo apt-get install cmake libssl-dev libavahi-client-dev libxml2-dev libbsd-dev libncurses5-dev git
First, clone the libzwaveip repository from GitHub:
$ git clone https://github.com/Z-WavePublic/libzwaveip.git
The build process used is a standard "out of source" build using CMake:
$ mkdir libzwaveip/build
$ cd libzwaveip/build
$ cmake ..
$ make
Typically, reference_client is executed with two additional parameters:
- The IP address of a zipgateway (either an IPv4 or an IPv6 address) with the
-sswitch - The PSK used by the zipgateway that's being connected to with the
-pswitch. The SD Card image uses123456789012345678901234567890aaas its default PSK, which matches the default PSK used byreference_client, so this argument can be omitted for brevity if the PSK isn't modified.
To connect to the zipgateway running locally in the Raspberry Pi, we'll obtain its address from /usr/local/etc/zipgateway.cfg by looking at the value of the ZipLanIp6 key. As an example, if the configuration file shows:
[...]
ZipLanIp6 = fd00:a622:3f5d:4590::3
[...]
We can connect reference_client to it by running:
$ ./reference_client -s fd00:a622:3f5d:4590::3 -p 123456789012345678901234567890aa
If the connection to the zipgateway is successful, you'll see the (ZIP) prompt in your shell. reference_client's shell supports a few commands. Type help for a list.
To instruct the Z/IP Gateway to add a new node to the Z-Wave network you use the addnode command. This will put zipgateway into inclusion mode, where it'll wait for a joining node wanting to be added to the Z-Wave network. The command doesn't produce any output in the 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 device 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, reference_client will print out a summary of the Command Classes the included device can work with, and some additional information to its console - for example:
(ZIP) addnode
(ZIP)
AppCmdHdlr: 34020206000716D39C041001728670855C259C717332317AEF2568230000
cmd_class: COMMAND_CLASS_NETWORK_MANAGEMENT_INCLUSION v2
cmd: NODE_ADD_STATUS
Seq. No >
02
Status >
NODE_ADD_STATUS_DONE
Reserved >
00
New Node ID >
07
Node Info Length >
16
Properties1 >
Capability:: 53
Listening : true
Properties2 >
Security:: 1C
Opt : true
Basic Device Class >
04
Generic Device Class >
10
Specific Device Class >
01
Non-Secure Command Class >
COMMAND_CLASS_MANUFACTURER_SPECIFIC :
COMMAND_CLASS_VERSION :
COMMAND_CLASS_CONFIGURATION :
COMMAND_CLASS_ASSOCIATION :
COMMAND_CLASS_IP_ASSOCIATION :
COMMAND_CLASS_SWITCH_BINARY :
COMMAND_CLASS_SENSOR_ALARM :
COMMAND_CLASS_NOTIFICATION :
COMMAND_CLASS_POWERLEVEL :
COMMAND_CLASS_METER :
COMMAND_CLASS_SENSOR_MULTILEVEL :
COMMAND_CLASS_FIRMWARE_UPDATE_MD :
COMMAND_CLASS_MARK :
COMMAND_CLASS_SWITCH_BINARY :
COMMAND_CLASS_ZIP_NAMING :
COMMAND_CLASS_ZIP :
Granted Keys >
00
KEX Fail Type >
00
bytestream: 34 02 02 06 00 07 16 d3 9c 04 10 01 72 86 70 85 5c 25 9c 71 73 32 31 7a ef 25 68 23 00 00
Inclusion done
You can instruct the Z/IP Gateway to prepare to remove a device using the removenode command. Different device manufacturers have different procedures for having their devices excluded, so you'll need to refer to the product manual for the device you're using for the correct procedure. Typically, a single- or quick triple-press on their button is what is required to request exclusion.
Once the operation completes, reference_client will print out a summary - for example:
(ZIP) removenode
(ZIP)
AppCmdHdlr: 3404010600
cmd_class: COMMAND_CLASS_NETWORK_MANAGEMENT_INCLUSION v2
cmd: NODE_REMOVE_STATUS
Seq. No >
01
Status >
NODE_REMOVE_STATUS_DONE
NodeID >
00
bytestream: 34 04 01 06 00
zipgateway announces the Z-Wave devices it manages as mDNS services. The SD Card image has a pre-installed copy of Avahi, an mDNS implementation, including avahi-browse so you can browse for Z-Wave IP devices from outside reference_client by running:
$ avahi-browse _z-wave._udp
which will show any discovered Z-Wave IP devices:
+ br-lan IPv6 Static Controller [e3a6e2620100] _z-wave._udp local
+ br-lan IPv6 Switch Binary [e3a6e2620700] _z-wave._udp local
This command continues running in the background, looking for more services, until you stop it with Ctrl+C. For more details on using avahi-browse, refer to its man page:
$ man avahi-browse
From within reference_client you use the list command to show Z-Wave IP devices that the Z/IP Gateway is managing:
(ZIP) list
List of discovered Z/IP services:
--- zwE3A6E26201.local: "Static Controller [e3a6e2620100]"
--- zwE3A6E26207.local: "Switch Binary [e3a6e2620700]"
You use the send command to send Z-Wave messages to these service names. The messages must be Z-Wave Command Classes - their construction was briefly discussed in Command Class Basics. As a convenience, the send command allows you to use names for the Command Class and Command identifiers - the first two bytes of a Z-Wave Command Class message - and provides Tab completion for them.
For example, to turn on the Switch Binary that was listed above, you send it a "Switch Binary Set" command with a value of "0xff":
(ZIP) send "Switch Binary [e3a6e2620700]" COMMAND_CLASS_SWITCH_BINARY SWITCH_BINARY_SET ff
and to turn it off:
(ZIP) send "Switch Binary [e3a6e2620700]" COMMAND_CLASS_SWITCH_BINARY SWITCH_BINARY_SET 00
If you know the IP address of the device you want to communicate with and are comfortable typing the "raw" Z-Wave Command Class message as a hexadecimal string, the hexsend command can accomplish the same thing:
(ZIP) hexsend fd00:ab45:754f:c15d::7 2501ff