Z/IP Gateway Advanced Configurations#

This session covers advanced configurations that are required to deploy the Z/IP Gateway.

Where to Apply Configurations#

These settings are configured by the developer, or by the Z/IP client. If using Z-Ware, Z-Ware will do so, as they are an integral part of how Z-Ware works. In the previous session, part of setting up Z/IP Gateway was to apply some configurations. For example, the RF TX power to increase the range to the allowed range within Europe. This introduced the zipgateway.cfg file that can be used to apply different configurations.

Z/IP Gateway is not Certifiable Without a Client#

The main thing to remember about configurations that apply to Z-Wave is that Z/IP Gateway can't pass certification by itself. Z/IP Gateway is only part of the controller stack and it needs a Z/IP client to handle the application-level command classes. The problem is that, to build a certifiable Z-Wave controller, more application logic is needed. Most of the application logic required is related to command classes that Z/IP Gateway cannot support by itself because, in many ways, it is just a bridge.

These examples are not directly related to transport functionalities (SRN14435 section 6.1.2), of command classes that the Z/IP Gateway can support by itself. It can do so because the functionality is narrowly defined.

  • “Time command class”, where a Z-Wave device can request the current time from Z/IP Gateway. Z/IP Gateway knows how to get the current time on the host system and return it, no high-level application logic required.

  • “Z-Wave Plus info command class”; the gateway has sufficient information about itself to provide this information to any node in the network which requires it.

  • “Indicator command class”: This is used to identify a device physically in a network. It allows a user to send an indicator command, triggering the device to do something to draw attention, for example blink an LED. Z/IP Gateway has hardware interfaces to do this, no application logic required.

  • “Manufacturer specific command class”: Serial numbers and UUIDs.

  • “Version command class”: Z/IP Gateway supports this command class for all the command classes it provides support for. As a Z/IP client may have added more command classes as supported, any version get command for these specific command classes will be forwarded to the Z/IP client.

Command Class Support Required to Certify#

A Z/IP client is required to support a range of command classes. The most common examples are as follows:

  • “Association command class”: Association command class and lifeline association were introduced in the training for embedded devices. All Z-Wave devices are required to have a lifeline association group, which must have at least a single association group and, depending on the supported command classes, there are requirements for minimum lifeline reporting. The minimum requirement for controllers is that if it has been included into an existing Z-Wave network and it is reset, it must send a “device reset locally” command to tell the remaining controller in the network that it has been reset. With association, you can add much more application level functionality. This is seen with slave devices that offer direct control of other devices without any runtime involvement with controllers, and in the same way a controller could have multiple association groups. This is not something that Z/IP Gateway can handle.

  • “Association group info command class”: Provides information about association groups. As association command class is not supported by Z/IP Gateway, neither can it support association group info command class.

  • “Multi command command class”: an encapsulation layer that allows to send multiple Z-Wave commands within the same Z-Wave frame.

  • “Version command class”: While partially implemented by Z/IP Gateway, it must be supported by the Z/IP client as it will have to support it for the command classes it implements support for. For example, if requesting which version of “association command class” supported by this particular controller, Z/IP Gateway will not know it, and it will forward the request to the client.

Z/IP Gateway Deep Package Inspection#

When data is received from the Z-Wave network, Z/IP Gateway inspects that payload in deep packet inspection to see if the frames payload fulfill the requirements for the given command class. If the requirements are fulfilled, the frame is forwarded to the unsolicited destination, which is configured either in zipgateway.cfg, or through the “Z/IP Gateway command class”.

Deep packet inspection is different depending on whether the received payload is a command that requires support, such as “set” and “get” commands, or whether it is commands that require control, typically “report” commands. For the commands that requires “support”, Z/IP Gateway checks whether it is a command that it has listed as supported in its “node information frame”, or in “secure commands supported report”. If listed, it will check whether the command was received at the highest granted key class of the destination, meaning Z/IP Gateways highest granted key class.

If not true, the frame will be dropped. Z/IP Gateway will also, if the command is supervision encapsulated, reply with a supervisor report on behalf of the Z/IP client.

For command classes that requires control on the destination, Z/IP Gateway checks if the frame was sent at the source nodes highest granted key class. If receiving a frame from a door lock, Z/IP Gateway will check if the frame was sent using “access key class”.

Finally, there are general checks on the parameters of the command class, such as payload length.

  • Does the command require support (i.e.,) set and get commands

    • Is the command listed in Z/IP Gateway's NIF / secure commands supported

    • Is the command received at the destinations (i.e., Z/IP Gateways) highest key class granted to Z/IP - Gateway

  • Does the command require control (i.e., report commands)

    • Is the commands sent at the source’ highest granted key class

  • General checks on other parameters like payload length.

Z/IP Gateway Deep Package Inspection#

  • Commands that pass are forwarded to “unsolicited destination”.

  • Commands that fail check is discarded

    • If discarded commands are “supervision encapsulated”, Z/IP Gateway will respond with a supervision report on behalf of the unsolicited destination

Unsolicited Destination#

  • The gateway needs to know what to do with frames it did not ask for (or in other words did not solicit).

  • The payload is inspected and whether they pass deep packet inspection

  • They are forwarded to the “unsolicited destination”

  • The unsolicited destination is configured in zipgateway.cfg

TLS Tunnel Connection#

Z/IP Gateway can connect to a Z/IP client, through a TLS tunnel, sending TLS encapsulated IPv6 frames to a remote instance of a Z/IP client. This is used with Z-Ware in “portal mode”, where Z-Ware can be running on a remote location while Z/IP Gateway is connected behind a NAT router.

The TLS tunnel relies on mutual authentication through RSA certificates, meaning that both devices must have certificates, signed by the same certificate authority. The cloud instance of Z-Ware will verify that a Z/IP Gateway connecting is an authentic for the particular service, and Z/IP Gateway will verify that it is connecting to an authentic instance of Z-Ware. The mutual authentication allows both ends of the connection to be certain that they are connecting to a trusted party.

The Z-Ware portal instance can host many accounts; thousands potentially. Each of the individual Z/IP Gateway instances are identified by the serial number of the certificate.

  • TLS encapsulated IPv6 frames

  • Mutually authenticated through RSA certificates

    • Both Z/IP Gateway and portal must have certificates signed by same CA

    • Z/IP Gateway instances may be linked to individual accounts through certificate serial numbers.

Logfile#

Z/IP Gateways logfile contains a lot of information, both about the networks, Z-Wave and IP, but also about the communication passing through Z/IP Gateway. For debugging purposes, this information is essential as the network information, can be used to configure other debugging tools, such as the Zniffer and any IP tracing tools.

  • Z/IP Gateways log file contains all information about

    • The current network

    • The communication

A Look into zipgatway.log - header#

The logfile, starting with the header, contains very useful information about:

  • Hardware generation

  • Protocol versions

  • Network capabilities, meaning Z-Wave network capabilities

    • The controller’s role in the network

      • SUC/SIS

      • Inclusion

      • Secondary

    • Security keys

      • What they are

      • What the maximum security of the network is

    • Z-Wave home ID

    • Z-Wave node IDs

    • Z-Wave virtual nodes

In the following details are given on extracting this information from the log file.

ESC[32;1m10352130 Opening config file /usr/local/etc/zipgateway.cfg
ESC[0mESC[34;1m10352130 RF Region EU = 0
ESC[0mStarting Contiki
Opening eeprom file /usr/local/var/lib/zipgateway/eeprom.dat
Lan device tap0
LAN HW addr 32:9C:B0:61:C0:9A
ESC[32;1m10352132 Starting zipgateway ver7_13.01 build ver7_13.01
ESC[0mESC[32;1m10352132 Resetting ZIP Gateway
ESC[0mESC[32;1m10352132 Serial Process init
ESC[0mESC[32;1m10352132 Using serial port /dev/ttyUSB0
ESC[0mESC[32;1m10352175 Version: Z-Wave 7.13, type 7
ESC[0mESC[34;1m10352229 ...... Firmware Update Meta Data command class version: 5 ......
ESC[0mESC[34;1m10352235 Magic check 191da1  == 191da1
ESC[0mESC[34;1m10352242 NVM version is 2
ESC[0mESC[32;1m10352249 L2 HW addr ESC[0m00:1e:32:1e:0e:ec
ESC[32;1m10352249
ESC[0mESC[32;1m10352266 700 series chip version 0 serial api version 8
ESC[0mESC[32;1m10352272 I'am SUC
ESC[0mESC[34;1m10352370 Key  class  80
ESC[0m4C8DEEF8631D1FDA5654667C28B7B58D
ESC[33;1m10352376 sec0_set_key
ESC[0mESC[34;1m10352397 Key  class  1
ESC[0mDCBBF75E55E8D1A553D7EBA42BB4635B
ESC[34;1m10352411 Key  class  2
ESC[0mE2F1966BCA7266F0AC7208E48735E267
ESC[34;1m10352425 Key  class  4
ESC[0mF9F9DE5BFC0DA4546CC79BE19965CF99
ESC[32;1m10352431 Network scheme is:ESC[0mESC[32;1m10352431 S2 ACCESS
ESC[0mESC[34;1m10352437 Resetting IMA
ESC[0mESC[34;1m10352437 Indicator blink script from config file (not sanitized): zipgateway_node_identify_generic.sh
ESC[0mESC[32;1m10352437 Using indicator blink script: /usr/local/etc/zipgateway_node_identify_generic.sh
ESC[0mESC[32;1m10352438 I'm a primary or inclusion controller.
ESC[0mESC[32;1m10352454 Command classes updated
ESC[0mESC[34;1m10352460  nodeid=1 0x00
ESC[0mESC[34;1m10352517 Waiting for bridge
ESC[0mESC[34;1m10352517 ZIP_Router_Reset: pan_lladdr: 88:9a:06:d5:00:01  Home ID = 0xd5069a88
ESC[0mESC[32;1m10352517 Tunnel prefix       ESC[0m::
ESC[32;1m10352517 Lan address         ESC[0mfd00:aaaa::03
ESC[32;1m10352517 Han address         ESC[0mfd00:bbbb::01
ESC[32;1m10352517 Gateway address     ESC[0mfd00:aaaa::1234
ESC[32;1m10352517 Unsolicited address ESC[0mfd00:aaaa::b156:ad51:8fb:2032
dynamic
ECDH Public key is
58225-04923-43331-28077-
06312-33855-41199-50032-
46474-14320-16623-54729-
25929-50757-25842-13413-
ESC[32;1m10352552 DTLS server started
ESC[0mESC[33;1m10352552 mDNS server started
ESC[0mESC[32;1m10352552 DHCP client started
ESC[0mESC[34;1m10352552 Starting zip tcp client
ESC[0mESC[32;1m10352552 ZIP TCP Client Started.
ESC[0mESC[32;1m10352552 No portal host defined. Running without portal.
ESC[0mESC[32;1m10352557 DHCP client started
ESC[0mESC[34;1m10352557 Found storage file /usr/local/var/lib/zipgateway/provisioning_list_store.dat
ESC[0mESC[34;1m10352557 Using file /usr/local/var/lib/zipgateway/provisioning_list_store.dat for provisioning list storage.
ESC[0mESC[34;1m10352557 Imported 0 provisions, stored 0
ESC[0mtap_dev: tapdev_send: write: Input/output error
tap_dev: tapdev_send: write: Input/output error
tap_dev: tapdev_send: write: Input/output error
fd00:bbbb::01

fd00:aaaa::03

fe80::21e:32ff:fe1e:eec

tap_dev: tapdev_send: write: Input/output error
ESC[32;1m10354117 Comming up
ESC[0mESC[32;1m10354166 temp_assoc_virtual_nodeids (count=4): 6 7 8 ... 9
ESC[0mESC[32;1m10354188 Bridge init done
ESC[0m1759
ESC[32;1m10354195 HomeID is d5069a88 node id 1

In the following sections the log file above is broken down.

Logfile – Version information#

ESC[0mESC[32;1m10352272 I'am SUC
1m16888 Starting zipgateway ver7_13.01 build ver7_13.01
32;1m16937 Version: Z-Wave 7.13, type 7
32;1m20309 700 series chip version 0 serial api version 8

Starting from the top, Z/IP Gateway's own version is seen, and the protocol version running on the Z-Wave module.

There are a lot of Z-Wave protocol versions, and Z/IP Gateway does not print the least significant digit. In other words, while this was captured on 7.13.06, It cannot be seen from the log.

Logfile – Z-Wave Network Information#

ESC[0mESC[34;1m20565 ZIP_Router_Reset: pan_lladdr: b5:b0:ea:f9:00:01  Home ID = 0xf9eab0b5
ESC[0mESC[34;1m1751818  nodeid=1 0x00
ESC[0mESC[32;1m1753617 temp_assoc_virtual_nodeids (count=4): 2 3 4 ... 5

The home ID is shown along with Z/IP Gateway's node ID. Typically referred to as Z/IP Gateways own node ID; 1. The virtual node IDs, which in this case are 2 through 5.

All information is added sequentially to the zipgateway.log, so when doing network management operations, such as resetting or joining other networks, the home ID and the node IDs will be changing, and both old and new home IDs will be shown sequentially.

The node IDs are useful for understanding where the traffic is coming from in a Z-Wave network. If the frames are sent from Z/IP Gateways own node ID, typically 1, then the traffic will be originating from Z/IP Gateway itself, while if the frames are coming from any of the virtual node IDs, the traffic was sent from a Z/IP client. This can be seen on the Zniffer.

Logfile - IP Network Information#

ESC[32;1m750873 Lan address         ESC[0mfdd1:3ca1:d800:01:21e:32ff:fe1e:eec
ESC[32;1m750873 Han address         ESC[0mfdcf:d2d9:1152:02::
ESC[32;1m750873 Gateway address     ESC[0mfd00:aaaa::1234
ESC[32;1m750873 Unsolicited address ESC[0mfd00:aaaa::b156:ad51:8fb:2032

  • LAN address.

  • PAN address: The home area network address, which is the prefix used for the Z-Wave nodes.

  • gateway address: This is the default IP gateway in the network; a router to reach the rest of the Internet. If in a network, was it possible to route the IPv6 address globally,

  • unsolicited destination.

This informations is very useful if debugging on the IPv6 layer. It allows for extracting the gateway address and the prefix for the Z-Wave nodes. It cal also be used to filter out traffic from individual Z-Wave nodes on an IP trace.

IPv4 Transactions#

ESC[0mESC[34;1m759092 got OFFER
ESC[0mESC[34;1m759092 send REQUEST
ESC[0mESC[34;1m759094 got ACK
ESC[0mESC[32;1m759094 Node 1 has ipv4 address 192.168.80.233
ESC[0mESC[34;1m759094 Checking for new sessions
ESC[0mESC[34;1m759094 We should send a discover
ESC[0mESC[32;1m759094 New IPv4 assigned for node 1

Information about IPv4. For each Z-Wave node there is a DHCP frame exchange with “offer”, “request” and “ack”. For each node this results in an IPv4 address. The IPv4 address may change over time depending on the configuration of the DHCP server, so these IPv4 lease acquisitions will be scattered throughout the log file. Again, this information is useful for debugging, while not as readable as the IPv6 addresses, it may be relevant depending on the chosen IP environment.

Logfile – runtime information#

2739937 ClassicZIPNode_dec_input: pkt: 23 2 len: 12
2739938 Sending long attempt
2739938 process_node_queues: uip_len:60
2739938 ClassicZIPNode_input: uip_len:60
2739938 ClassicZIPUDP_input len: 12 secure: 1
fdd1:3ca1:d800:01:7415:87ff:fe38:24c6
2739938 temp_assoc_lookup_by_zip_client
2739938 temp_assoc_lookup_by_zip_client() found: 0x7d716c
2739938 Sending 2->6, class: 0x20, cmd: 0x2, len: 2
2739938 Sending with scheme 2
2739938 S2_fsm_post_event event: SEND_MSG, state IDLE
2739938 S2_set_timeout interval =65000 ms
2739939  Sending S2_send_frame 14
2739963 S2_fsm_post_event event: SEND_DONE, state VERIFYING_DELIVERY
2739963 S2_set_timeout interval =274 ms
2739973 ApplicationCommandHandler 6->2 class 0x9f cmd 0x03 size 17
2739973 S2_fsm_post_event event: GOT_ENC_MSG, state VERIFYING_DELIVERY
2739973 s2incl process_event event: S2_INCLUSION_SEND_DONE state: S2_INC_IDLE
2739973 send_using_temp_assoc_callback_ex for node 6 status 0
2739974 queue_send_done to node 6 queue 2 status: 0
2739974 ApplicationCommandHandler 6->2 class 0x20 cmd 0x03 size 5
2739975 bridge_virtual_node_commandhandler Handled
2739978 Sending long attempt
2739978 process_node_queues: uip_len:65
2739978 ClassicZIPNode_input: uip_len:65
2739978 DeMangled HAN node 6 Virtual Node 2
2739978 Packet from Z-Wave side (nodeid: 6) to port: 51607 IP addr: fdd1:3ca1:d800:01:7415:87ff:fe38:24c6
2739979 queue_send_done to node 6 queue 2 status: 0

This is an example of sending a payload to a Z-Wave node. From the top, there is an entry saying that an incoming frame, hex 23 02, Z/IP encapsulation, was received. This is the Z-Wave over IP encapsulation used when transferring Z-Wave payloads over IP. As the destination is a Z-Wave node, a temporary association is assigned meaning that Z/IP Gateway is allocating a virtual node to use for the communication from a certain IP source to a certain Z-Wave destination. Finally, the payload is transmitted from virtual node 2, to the destination device, node ID 6, and the payload being sent can be seen, hex 20 02; a basic get.

A few lines related to S2 are seen because the destination supports S2. Timeouts are also there. It can also be seen that, because the payload is a “get” command soliciting an answer, Z/IP Gateway is automatically using the “verify delivery” mechanism discussed in the previous section. The timestamps are in milliseconds, so this process is running swiftly. A lot of it is within the same millisecond and, when Z/IP Gateway transmits to something relying on the Z-Wave RF interface, slower. It can be seen that node ID 6 is returning a frame to node ID 2. Z/IP Gateway processes this frame in steps. The first step is to inspect the command class, hex 9f 03, which is an encrypted s2 message encapsulation, then Z/IP Gateway decrypts the frame. A few lines later, the decrypted payload is shown, 20 03, a basic report that was inside the encryption encapsulation.

If there are frames with multiple encapsulation layers, Z/IP Gateway will iterate through these steps, showing at least the command class and command identifier for each of the steps, until the frame is fully deencapsulated an processed into a payload that can forwarded over IP.

The frame is forwarded to the IP destination, which happens to match the same destination as the get was originally sent from, due to Z/IP Gateways use of temporary associations.

This is what it looks like, Z/IP Gateway processes an incoming get command from a Z/IP client. The Z/IP client sends a get, Z/IP Gateway forwards it to the Z-Wave destination, using verify delivery because the command is triggering a response. When the reply is received, if encapsulation layers are used, Z/IP Gateway will break it down, layer by layer, until reaching the core payload, that is forwarded to the IP destination.

If using non-secure communications, the process looks significantly simpler, while the security is the current baseline.

Log File – Deep Packet Inspection#

5558013 ApplicationCommandHandler 1->2 class 0x32 cmd 0x02 size 7
5558013 nm_fsm_post_event event: NM_EV_FRAME_RECEIVED state: NM_IDLE
5558013 Cmd class 0x32 command 0x02 identified as version 5
5558013 Command class 0x32 : 0x02 not supported
5558013 Unhandled command  0x32:0x02 from fda3:9838:93fe:02::01
5558014
5558014 Check security for rnode:1 scheme ff class 32 command 02
5558014 Frame not forwarded to unsolicited because it was not sent on right scheme or not supported.

In this example, an incorrect meter report was received. Z/IP Gateway does not list the specific reason for discarding the frame, but it could be:

  • Payload length

  • Incorrect key class (lower than the highest granted for the device)

In this case, the frame is discarded and, if it had been supervision get encapsulated, Z/IP Gateway would transmit a supervision report on behalf of the Z/IP client.