Sleeping Nodes Lab#

This lab explores the behavior of Reporting Sleeping Slave (RSS) and Frequently Listening Sleeping Slave (FLiRS) nodes.

This exercise is the fourth exercise in the Z-wave Controller Training Course series and requires a grasp of the topics covered in the Advanced Z/IP Gateway and Z/IP Gateway Traffic Analysis exercises.

Inclusion of RSS/FLiRS devices
Zniffer analysis of the FLiRS Beam transmission
Zniffer analysis of retransmission attempts
Zniffer analysis of the Wakeup Command Class
Getting and setting the Wake Up Interval
Deep packet inspection of the Expected Delivery Header Extension and More Information flag using Wireshark
Evaluation of Z/IP / DNS and zipgateway.log traffic related to sleeping nodes

Introduction#

In this exercise, you will include sleeping nodes onto a Z-Wave PAN and evaluate the normal traffic exchange for sleeping devices. Additionally, this exercise demonstrates Z/IP gateway behavior when a sleeping device is temporarily or permanently unreachable. Finally, this exercise demonstrates how to evaluate specific Z/IP packets used with sleeping devices.

Hardware Requirements#

1 UZB Controller
1 Raspberry 3B (+)
1 SD card pre-flashed with RaspberryOS 'Stretch'
1 IP Router with built in DHCP
2 WSTK Main Development Boards
1 Z-Wave Radio Development Board: ZGM130S SiP Module
1 USB Zniffer

Software Requirements#

An SSH terminal of your choice
Simplicity Studio
Z-Wave SDK
Z-Wave PC Controller
Z-wave Zniffer

For this exercise, use Simplicity Studio to flash the 'Door Lock Keypad' and 'Sensor PIR' references onto your WSKTs following the procedure outlined in Gateway Session 1 Lab.

Prerequisites#

To gain familiarity with the protocol, see the following:

The Z-Wave 700 Series Training.

Videos 1-3 and exercise 6,7 and 10 will be relevant.

Further the participant should have completed:

Gateway Session 1 - 'Basic Z/IP' Gateway

Gateway Session 1 Lab

Gateway Session 2 - 'Z/IP Gateway Advanced Configurations'

Gateway Session 2 Lab

Gateway Session 3 - 'Traffic Analysis'

Gateway Session 3 Lab

Gateway Session 4 - 'Sleeping Nodes'

Users should be familiar with operating the Zniffer and Wireshark programs and connecting to the Raspberry Pi.

Sleeping Device Inclusion#

Ensure that the Zniffer and Wireshark are both running before proceeding with this lab.

To decode packets in Wireshark, an initial DTLS handshake must be captured which means Wireshark must be started before connecting the libzwaveip reference_client to your gateway.

Following the steps presented in Gateway Session 3 - 'Traffic Analysis', enter your DTLS key to decode the Z/IP traffic.

PIR Sensor Inclusion (RSS Node)#

Next, following the inclusion steps from Gateway Session 1 Lab, include your 'PIR Sensor reference'

Note that the libzwaveip reference_client console output will appear as follows after inclusion completes successfully:

(ZIP)
cmd_class:  COMMAND_CLASS_NETWORK_MANAGEMENT_INCLUSION  v3
cmd:  NODE_ADD_STATUS
param:  Seq. No 0x18
param:  Status  >
      NODE_ADD_STATUS_DONE
param:  Reserved1 0x00
param:  New Node ID 0x13
param:  Node Info Length 0x1B
param:  Properties1  >
     Z-Wave Protocol Specific Part 1:: 53
      Listening : false
param:  Properties2  >
  Z-Wave Protocol Specific Part 2:: 1c
  Opt : true
param:  Basic Device Class 0x04
param:  Generic Device Class 0x07
param:  Specific Device Class 0x01

Note that the Properties1 field denotes the device is non-listening. Additionally, note the Basic Device Class 0x04 (Mailbox Type), Generic Device Class 0x07 (Sensor Notification), and Specific Device Class 0x01 (Notification Sensor)

You can also retrieve the NIF with the list -n command:

"pir.left [f9985e4d-019-000]" IP:fd00:bbbb::6
  Mode: 0x04 (MODE_MAILBOX)
  Mode flags: 0x00 (none)
  NIF:
    0x07 (GENERIC_TYPE_SENSOR_NOTIFICATION)
    0x01 (SPECIFIC_TYPE_NOTIFICATION_SENSOR)
  Supported CCs (*:secure):
    0x5E (COMMAND_CLASS_ZWAVEPLUS_INFO)
    0x9F (COMMAND_CLASS_SECURITY_2)
    0x6C (COMMAND_CLASS_SUPERVISION)
    0x68 (COMMAND_CLASS_ZIP_NAMING)
    0x23 (COMMAND_CLASS_ZIP)
    0x86 (*COMMAND_CLASS_VERSION)
    0x5C (*COMMAND_CLASS_IP_ASSOCIATION)
    0x85 (*COMMAND_CLASS_ASSOCIATION)
    0x8E (*COMMAND_CLASS_MULTI_CHANNEL_ASSOCIATION)
    0x59 (*COMMAND_CLASS_ASSOCIATION_GRP_INFO)
    0x72 (*COMMAND_CLASS_MANUFACTURER_SPECIFIC)
    0x5A (*COMMAND_CLASS_DEVICE_RESET_LOCALLY)
    0x87 (*COMMAND_CLASS_INDICATOR)
    0x73 (*COMMAND_CLASS_POWERLEVEL)
    0x80 (*COMMAND_CLASS_BATTERY)
    0x71 (*COMMAND_CLASS_NOTIFICATION)
    0x00 (*unknown)
    0x84 (*COMMAND_CLASS_WAKE_UP)
    0x7A (*COMMAND_CLASS_FIRMWARE_UPDATE_MD)

Additionally, you can confirm the device type in the Zniffer:

Note the Z-Wave+ Role type is 0x06 Slave Sleeping Reporting. Additionally, after inclusion, the sleeping device will be interviewed. Evaluate the following frame exchange:

First, the gateway will get the Wake Up Command Class version information

Next, the gateway obtains the Wake Up Interval Capabilities from the RSS. Note in this frame that the device reports a Minimum Wake Up Interval of 20s, a Maximum Wake Up Interval of 86,400s, a Default Wake Up Interval of 300s, and a Wake Up Interval Step of 20[s]. Recall that a Wake Up Interval of 0[s] would denote that a device wakes only on local events (such as a sensor being tripped).

Finally, note that the gateway sets the Wake Up Interval of the device to 1[h] 10[m], selecting a value between the Minimum and Maximum that is divisible by the Wake Up Interval Step.

After this point, the RSS will periodically send Wake Up Notifications every 1[h] and 10[m].

RSS and the Mailbox#

While the RSS is sleeping, any commands sent to the node will be stored by the gateway until they can be delivered later.

Note that, because all sleeping devices MUST support the Battery Command Class, the RSS will respond to a Battery Get transmitted using the reference_client.

Evaluating the Zniffer trace, you can see that the gateway first attempts to optimistically transmit the packet:

The gateway does this in case the device is currently awake. Because the device is using S2, the gateway first attempts to synchronize a nonce with the RSS before sending the Battery Get. However, if the RSS is currently asleep, it does not respond to this initial attempt to resynchronize using S2. After exhausting its retries on the optimistic transmission, the gateway stores the command in the mailbox for transmission upon receiving a Wake Up Notification.

In the reference_client output, note the command is placed into the mailbox and an expected delay is reported periodically as the command waits to be dispatched.

(ZIP) hexsend fd00:bbbb::6 8002
(ZIP) Transmit put in gateways mailbox. Expected delay = 4002 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3942 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3882 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3822 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3762 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3702 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3642 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 3582 seconds

Additionally, check the /tmp/zipgateway.log:

Note the zipgateway.log shows the command enqueued into the mailbox as well as the current mailbox count.

Rather than waiting for a further 3582[s] for the next Wake Up Notification from the RSS, press the RESET button on the WSTK, which will cause the RSS device to reboot. After rebooting, the RSS sends a Wake Up Notification to the zipgateway, causing the gateway to immediately deliver the mailbox messages destined to the RSS.

(ZIP) Transmit OK
(ZIP)
cmd_class:  COMMAND_CLASS_BATTERY  v1
cmd:  BATTERY_REPORT
param:  Battery Level  >

bytestream: 80 03 64

Note that the reference_client immediately receives the requested Battery Report. Evaluate the Zniffer to confirm the following frame exchange on the air:

First, the RSS sends a Wake Up Notification. Next, because the RSS has awakened unexpectedly (outside of its Wake Up Interval), Z/IP Gateway sends a Wake Up Interval Get to determine if the Wake Up Interval has somehow changed, unexpectedly. After receiving a Wake Up Interval Report, the Z/IP Gateway resynchronizes its S2 Nonce and sends the "Battery Get" command enqueued earlier. Finally, note that the Z/IP Gateway sends a "Wake Up No More Information" frame when the mailbox is completely empty. Retry this exercise after enqueuing multiple commands destined for the RSS and confirm that all commands are sent before the Wake No More Information frame is transmitted.

Evaluating the "Expected Delay" Header Extension Option#

Recall from Gateway Session 4 - 'Sleeping Nodes' that when an "ACK Response" is requested, the client (reference_client, in our case) will be notified with a "NACK, Waiting" frame that includes an "Expected Delay" header extension. Wireshark will be used to evaluate this frame.

Referring to the Network Protocol Command Class Specification, recall that if Bit7 (Header ext. included) within Byte3 is set within the Z/IP header, the frame includes a Header Extension.

Refer to the 'Header Extension (Variable)' section within the Network Protocol Command Class Specification to determine the Header Extension Format:

Note that a Header Extension (Like the 'Expected Delay' extension) may also include one or many Packet Options. Packet Options are described in the 'Z/IP Packet Option (variable)' table:

Note that the lower seven bits within the first byte refer to an "Option Type," which can be decoded using the 'Packet Option Types' table appearing in section 4.12.3 List of defined Z/IP Packet Options of the Network Protocol Command Class Specification. Finally, see section 4.12.3.1 to decode the Expected Delay Option:

Using this information construct a Wireshark Filter for:

All DTLS packets
Containing the Command Class Z/IP (0x23) and Command ‘Packet’ (0x02)
With a header extension included (data.data.[3]&0x80)
Whose Option Type is ‘Expected Delay.’ (data.data[8]==0x01)

this filter appears as-follows in the Wireshark capture, below:

Decoding the payload appearing in the capture, above, yields the following:


Byte	0	1	2	3	4	5	6	7	8	9	10	11	12
Value	0x23	0x02	0x30	0x90	0x39	0x00	0x00	0x16	0x01	0x03	0x00	0x0d	0x8e
Type	Z/IP_CC	Packet	NACK +Waiting	Header inc.	Seq. no	Src	Dst	Header ext. Len	Opt. Type 0x01	Opt. Len	optMSB	..	optLSB

which allows you to determine the Expected Delay of 0xd8e = 3470[s]. Therefore, the gateway is communicating to the Z/IP client (reference_client) on behalf of the Reporting Sleeping Slave, Node6 (fd00:134f::6) notifying the client of the remaining time until the device wakes up. The gateway reports that Node6 is not available for about 57[m] in the packet above. If the ACK Request bit was set in the initial command, the gateway continues periodically transmitting a NACK+Waiting as-above with decreasing expected delay values on behalf of the RSS until the destination node wakes up.

Door Lock Inclusion (FLiRS Node)#

In comparison to the RSS, the Door Lock sample is a FLiRS device, meaning that commands can be sent to it by using a Beam signal. Following the same steps for normal inclusion, add the Door Lock sample to your controller. When completed, you should see output similar to the output below:

(ZIP)
cmd_class:  COMMAND_CLASS_NETWORK_MANAGEMENT_INCLUSION  v3
cmd:  NODE_ADD_STATUS
param:  Seq. No 0x02
param:  Status  >
         NODE_ADD_STATUS_DONE
param:  Reserved1 0x00
param:  New Node ID 0x07
param:  Node Info Length 0x1C
param:  Properties1  >
        Z-Wave Protocol Specific Part 1:: 53
         Listening : false
param:  Properties2  >
        Z-Wave Protocol Specific Part 2:: 5c
         Opt : true
param:  Basic Device Class 0x04
param:  Generic Device Class 0x40
param:  Specific Device Class 0x01
param:  Command Class  >
         COMMAND_CLASS_ZWAVEPLUS_INFO :
         COMMAND_CLASS_TRANSPORT_SERVICE :
         COMMAND_CLASS_SECURITY :
         COMMAND_CLASS_SECURITY_2 :
         COMMAND_CLASS_SUPERVISION :
         COMMAND_CLASS_ZIP_NAMING :
         COMMAND_CLASS_ZIP :
         (null) :
         COMMAND_CLASS_NO_OPERATION :
         COMMAND_CLASS_VERSION :
         COMMAND_CLASS_MANUFACTURER_SPECIFIC :
         COMMAND_CLASS_DEVICE_RESET_LOCALLY :
         COMMAND_CLASS_INDICATOR :
         COMMAND_CLASS_POWERLEVEL :
         COMMAND_CLASS_BATTERY :
         COMMAND_CLASS_DOOR_LOCK :
         COMMAND_CLASS_USER_CODE :
         COMMAND_CLASS_ASSOCIATION :
         COMMAND_CLASS_IP_ASSOCIATION :
         COMMAND_CLASS_MULTI_INSTANCE_ASSOCIATION :
         COMMAND_CLASS_ASSOCIATION_GRP_INFO :
         COMMAND_CLASS_FIRMWARE_UPDATE_MD :
param:  Granted Keys 0x84
param:  KEX Fail Type 0x00
param:  Properties3  >
        DSK Length:: 10
        Reserved2:: 00
param:  DSK  >
 0xbe 0x72 0xcf 0x87 0xc7 0x55 0xb0 0x6f 0x64 0x26 0xef 0x65 0x77 0x28 0xb8 0x8a
bytestream: 34 02 02 06 00 07 1c 53 dc 04 40 01 5e 55 98 9f 6c 68 23 f1 00 86 72 5a 87 73 80 62 63 85 5c 8e 59 7a 84 00 10 be 72 cf 87 c7 55 b0 6f 64 26 ef 65 77 28 b8 8a

Note that, similarly to the PIR sensor, the Door lock's Properties1 field denotes Listening: false. Additionally, note the Basic Device Class 0x04 (Mailbox Type), Generic Device Class 0x04 (Entry Control), and Specific Device Class 0x01 (Door Lock).

You can also retrieve the NIF with the list -n command:

"lock.left [f37d00fe-007-000]" IP:fd00:bbbb::7
  Mode: 0x03 (MODE_FREQUENTLYLISTENING)
  Mode flags: 0x00 (none)
  NIF:
    0x40 (GENERIC_TYPE_ENTRY_CONTROL)
    0x01 (SPECIFIC_TYPE_DOOR_LOCK)
  Supported CCs (*:secure):
    0x5E (COMMAND_CLASS_ZWAVEPLUS_INFO)
    0x9F (COMMAND_CLASS_SECURITY_2)
    0x6C (COMMAND_CLASS_SUPERVISION)
    0x68 (COMMAND_CLASS_ZIP_NAMING)
    0x23 (COMMAND_CLASS_ZIP)
    0x86 (*COMMAND_CLASS_VERSION)
    0x72 (*COMMAND_CLASS_MANUFACTURER_SPECIFIC)
    0x5A (*COMMAND_CLASS_DEVICE_RESET_LOCALLY)
    0x87 (*COMMAND_CLASS_INDICATOR)
    0x73 (*COMMAND_CLASS_POWERLEVEL)
    0x80 (*COMMAND_CLASS_BATTERY)
    0x62 (*COMMAND_CLASS_DOOR_LOCK)
    0x63 (*COMMAND_CLASS_USER_CODE)
    0x5C (*COMMAND_CLASS_IP_ASSOCIATION)
    0x85 (*COMMAND_CLASS_ASSOCIATION)
    0x8E (*COMMAND_CLASS_MULTI_CHANNEL_ASSOCIATION)
    0x59 (*COMMAND_CLASS_ASSOCIATION_GRP_INFO)
    0x7A (*COMMAND_CLASS_FIRMWARE_UPDATE_MD)

Note that Mode: 0x03 is Frequently Listening, as expected. Finally, you can confirm these values in the Zniffer, below.

After including your Door Lock, you can evaluate the Beam Signal on the Zniffer by issuing any command supported by the device. Recall that a FLiRS device MUST support the Battery Command Class -- so it will respond to a Battery Get issued from the reference_client:

(ZIP) hexsend fd00:bbbb::7 8002
(ZIP) Transmit put in gateways mailbox. Expected delay = 1 seconds
(ZIP) Transmit OK
(ZIP)
cmd_class:  COMMAND_CLASS_BATTERY  v1
cmd:  BATTERY_REPORT
param:  Battery Level  >
bytestream: 80 03 64

Note that an immediate response comes back from the FLiRS device. Similar to the RSS device, in the Zniffer trace the gateway first attempts three optimistic transmissions before sending a 'Wake Up Beam Start' which lasts approximately one second (+/- 10%) until a 'Wake Up Beam Stop' is transmitted. The Beam Signal is the key distinguishing feature of a FLiRS device.

After the FLiRS device is awake, gateway's virtual node 2 attempts to sync s2 with node 7 (the door lock), by sending a S2 Nonce Get, an ACK is returned, and then the Battery Get and Battery Report are delivered and acknowledged respectively.

Node Failure#

Recall from Gateway Session 4 'Sleeping Nodes', an RSS will be marked as failed by the Z/IP gateway after 2*WAKE_UP_INTERVAL + %10 [s].

Using reference_client, set the Wake Up interval to its minimum amount (in our PIR Sensor this value is 0x14 = 20[s]).

(ZIP) hexsend fd00:bbbb::6 840400001401
(ZIP) Transmit put in gateways mailbox. Expected delay = 3964 seconds
(ZIP) Transmit put in gateways mailbox. Expected delay = 4200 seconds
(ZIP) Transmit OK

Note that the RSS is initially sleeping, but that by depressing the RESET button on the WSTK the PIR sensor, it wakes up and transmission completes. Note in the Zniffer a 'Wake Up Notification' is now transmitted once every 20 [s].

Next, unplug the device and monitor /tmp/zipgateway.log.

Note that after the expected threshold of 2 * 20 [s] + 10% = 44 [s], the following entry appears in the log: 'mailbox node 6 is now failing, because it has not reported in'. Plugging the device back in will cause node 6 to return and the log will read 'Node 6 is now ok.'

By comparison, the Beam Signal of the FLiRS device allows the gateway to immediately determine that a device has failed. Unplug the Door Lock and send another Battery Get Command.

Note that in the Zniffer, the gateway will attempt to Beam the FLiRS device approximately ten times.

After failing to receive an expected response from the FLiRS device, note in /tmp/zipgateway.log that Node 7 (our FLiRS device) is marked as failed.

Conclusion#

At this point, you should be familiarized with RSS and FLiRS nodes and both nominal and failure mode behavior of these devices.