Z-Ware C API Lab Exercise#

This lab exercise will explain the following:

  • Building library and apps

  • Connecting the sample app to Z/IP gateway

  • Doing basic control of Z-Wave devices

  • Modifying the sample app to receive the notification command class

Hardware Requirements#

  • 2 UZB Controllers

  • 1 Raspberry Pi 3B (+)

  • 1 SD card

  • 1 IP Router with built in DHCP

  • 1 WSTK Main Development Board

  • 1 Z-Wave Radio Development Board: ZGM130S SiP Module

  • 1 USB Zniffer

Software Requirements#

  • VNC and optionally SSH client

  • Simplicity Studio

    • Z-Wave SDK

    • Z-Wave PC Controller

    • Z-Wave Zniffer

Prerequisites#

Familiarize yourself with the protocol by referring to the following materials: https://www.silabs.com/support/training/z-wave-700-series Videos 1-3 and exercise 6,7 and 10 are relevant.

Furthermore, the participants should have completed gateway sessions 0-7 (and lab exercises) so that a Z/IP gateway is already running on the Raspberry Pi and VNC is already set up.

Building Library and Sample Apps#

The steps to build the library are also documented in the Gateway Getting Started Guide. Below are the steps to build on a Raspberry Pi.

The demo apps are built on top of the Z-Ware C library, which is based on the open SSL library, so both must be built before building the sample apps.

First, extract Z-Ware:

$ tar -xvf zware.tar.gz

Enter the Z-Ware library directory.

$ cd zware/v7.xx.x/src/

Extract the source code.

$ tar -zxvf zware.tar.gz

Enter the Z-Ware library source directory.

$ cd zwportal/src/zwave/hcapi

Build the openSSL library.

$ source install_openssl_lib.sh
$ source build_openssl.sh linux release

Build the Z-Ware library.

$ make TARGET_PLATFORM=LINUX_ZIP1

Build the sample apps.

$ cd demos/
$ make TARGET_PLATFORM=LINUX_ZIP2

Running Sample Applications#

Run the gateway discovery first. To run make sure that the Z/IP gateway is running, perform the following steps.

$ cd gw_discovery
$ ./gw_discovery

Every reachable gateway in the same IP subnet will be listed. Note the IP address of the discovered gateway.

Scanning for Z/IP gateway ...
Press 'x' to exit ...
	IPv6 Address: fd00:aaaa::10e1:98b9:230b:45a4
Found 1 network interfaces
Join ok. Multicast interface index: 4
Gw discovery received 1 responses

Received report:1/1 with gw count:1

---Gateways found---
(0) fd00:aaaa::3 [Static Controller [e9fff2d90100]._z-wave._udp.local]
Press 'x' to exit ...

If no gateway is found, return to the Z/IP gateway lab exercise and ensure it is running.

Each of the remaining Z-Ware demo apps relies on a configuration file located in the same directory as the app, called app.cfg. For each of the apps, app.cfg must be configured with the correct IP address and DTLS key in order to connect to Z/IP gateway.

Wait for initialization status 0x00. If the status is 0xFF, the initialization has failed. This is typically caused by a wrong IP address or a wrong DTLS key. The key used throughout this exercise is the default, so any errors during this exercise are likely to be the IP address.

add_node#

Load the switch on/off example from the Z-Wave SDK to the WSTK. If the switch on/off app is already included as a node, remove it first before attempting to run add_node. Set the Z/IP gateway IP address in the app.cfg file. Then run the sample app as follows.

$ cd add_node
$ ./add_node

In the menu, choose option 1. Enter the requested data. To add a node unsecured you may enter 0 for the granted keys bit-mask, otherwise enter the same as the requested keys.

Initialize network in progress, please wait for status ...
Press 'x' to exit ...
Initialization status:0
(1) Add node
(x) Exit
Select your choice:
1
Controller supports security 2.
Pre-enter Device Specific Key (DSK) (y/n)?:
n
Waiting for Requested keys and/or DSK callback ...
Device requested keys bit-mask: 83h
Key (bit-mask in hex) :
                      Security 2 key 0 (01)
                      Security 2 key 1 (02)
                      Security 2 key 2 (04)
                      Security 0       (80)
Grant keys bit-mask (hex):
83

Received DSK: XXXXX-62843-56878-07310-10775-03938-17638-08326
Do you accept this device to be added securely (y/n)?:
y
You accepted the device.
Enter 5-digit PIN that matches the received DSK:

You will find the 5 digits of the DSK in the device configuration menu for the WSTK in Simplicity Studio underneath the QR code.

bin_switch#

If the Switch on/off app is not included, use the add_node demo app first to include switch on/off sample application. Then, continue to control it using bin_switch. Configure app.cfg for the bin_switch sample app, continue to start the sample app, and toggle the included node on and off using the demo app.

$ cd bin_switch
$ ./bin_switch

You will see the following output to the terminal.

Initialize network in progress, please wait for status ...
Press 'x' to exit ...
Get node info 1/1 completed
Initialization status:0
network id:E9FFF2D9, Z/IP controller id:1

(1) Turn switch on
(2) Turn switch off
(x) Exit
Select your choice:
2
zwif_switch_set with error:3

Note. "error: 3" actually indicates success.

Modify bin_sensor#

Load the SensorPIR sample app to the WSTK. Then, add the node using the add_node sample app (enter learn mode on the WSTK using BTN1). Optionally, start the Zniffer to help debug if things don’t work (and add the node without security to simplify things even further). You will now modify bin_sensor to receive sensor notification reports. bin_sensor searches for the network for COMMAND_CLASS_BINARY_SENSOR, which is old. Modify the search function to search for COMMAND_CLASS_ALARM instead. This will find the SensorPIR node interface (see line 644 in bin_sensor.c). Next, you will modify the callback setup. On or around line 782, you see the callback set function. Change this to call zwif_alrm_rpt_set instead and create a callback function that prints to the screen.

For example, a callback can be as follows:

void hl_alrm_rep_cb (zwifd_p ifd, zwalrm_p alarm_info, time_t ts)
{
    printf ("alrm_rep cb\n");
}

Next, recompile the sample apps by typing the following in the demos directory.

$ make TARGET_PLATFORM=LINUX_ZIP2

Run bin_sensor again and choose 1 in the menu first to set up the callback. Then, verify when you hold BTN2 on the WSTK while running SensorPIR that you see the printf from the callback function on your screen.