Z-Wave Session 0 Prerequisites#

This training course covers prerequisites to understand what the basic operation if the Z-Wave over IP (Z/IP) gateway.

Multichannel#

The first prerequisite is multichannel encapsulation, a command class that allows addressing multiple functions (called 'endpoints') on the same Z-Wave device. Typical examples of multichannel devices are power strips and floor heating controllers where the device can control multiple heating valves. As an example, consider a power strip with 3 outlets that need to be independently controlled. The Z-wave solution for this requirement is to give each outlet a different multichannel endpoint within the multichannel power strip.

Another example of using a multichannel is controlling composite devices where multiple device types are on one end node. For example, one node can have switch functionality, notification sensor functionality, and multilevel sensor functionality. Each of these functions then has its own endpoint.

Multichannel Examples

  • Power strip

  • Floor heating controller

  • Separate application level functionality on composite devices

The multichannel command class is not only used by multichannel devices. It is also implemented by other devices that can directly control multichannel destinations. As an example, consider a wall controller application in which associations can be configured to directly control relays or other devices and address multichannel endpoints directly. On slave devices that control multichannel endpoints but are not multichannel devices, the multichannel command class is typically exposed by supporting the multichannel association command class to indicate the capability of controlling multichannel endpoints. An example app that implements multichannel association is the sensorPIR example found in Simplicity Studio.

Finally, multichannel encapsulation supports bit addressing as a special feature, which makes it possible to control multiple endpoints at one time (up to 8). For example, to turn on multiple outlets on a power strip, a bitmask can be sent describing which outlets to control. An example of bitwise multichannel support is implemented in the lab.

Supervision#

Z-Wave Supervision Encapsulation, like a multichannel, is an encapsulation layer which wraps a command. Supervision Encapsulation triggers a response from a destination if the frame is delivered and decrypted correctly. It is used to ensure delivery of and monitor execution for command classes that don't trigger a response automatically. For example, for a set or a report request, a controller may not receive a response, preventing the user from knowing if an error occurred. Additionally, the supervision command class can implicitly include a get in the same command, using the ensured response mechanism to alleviate the need for polling. Supervision also allows for the use of the S2 TX option 'Verify Delivery,' which will be discussed in more detail later.

An application level status is returned when using supervision. For example, if a set is sent, the following potential status values are returned:

  • SUCCESS

  • FAILURE

  • NO_SUPPORT

  • WORKING (work in progress)

WORKING is used to communicate an action is in-progress. For example, consider a door lock where it takes some time to move the deadbolt. The controller first receives a WORKING response, and then a SUCCESS. If the WORKING response is received first, it includes a duration estimating how long it will take the requested action to complete.

We will implement an example of supervision encapsulation in the included lab.

Ensuring Message Decryption with S2#

When using S2 encryption, the S2 TX option ensures the destination can decrypt the command and execute it correctly, and confirms the SPAN is not out of sync. This option means the gateway:

  • Waits for an S2 nonce report before providing application level callback

  • Redelivers the payload after SPAN sync if a nonce report is received

Successful S2 Frame Flow#

S2 SuccessS2 Success

In a successful S2 transmission, an initial synchronization of 'Numbers Used Once' (nonces) occurs. Then, S2 encapsulation for each message can occur. For each S2 message, a pseudo random number is generated based on the SPAN. These pseudo random numbers need to be synchronized on the source and destination, or messages can no longer be decrypted.

unsuccessful S2 Frame Flow#

S2 FailS2 Fail

If decryption fails, the exchange in the figure above, occurs. An initial synchronization of the nonce is achieved using a 'Nonce Get' followed by a 'Nonce Report.' Then, S2 message encapsulation follows with a span header extension. If the SPAN gets out of sync, the destination node will not be able to decrypt frames. In this sate, the destination will respond with a nonce report with the SOS (span out of sync) bit set.

S2 ProtocolS2 Protocol

In the figure, above, notice that the application level callback happens right after the S2 message encapsulation has been delivered. The callback reports the message has been sent successfully, even though, shortly afterwards a nonce report is received denoting that the recipient was unable to decrypt the message. To prevent this, S2 TX option is used with the 'Verify Delivery' option, which causes the protocol to wait for an S2 nonce report before providing the application level callback, as shown below.

unsuccessful S2 Frame Flow when using S2 Tx option verify delivery#

S2 TX Option VerifyS2 TX Option Verify

If an S2 nonce report is received, the SPAN is resynchronized and the payload is retransmitted. As a result, with each transmission attempt the controller must wait until a nonce report arrives or a timeout occurs. In Z-Wave networks, it may take a long time to deliver frames depending on the network quality (up to 500 ms) as shown below.

S2 TX Option Verify TimeoutS2 TX Option Verify Timeout

If a decryption error occurs, the callback is usually received much faster because the nonce report is typically received much faster than 500 ms. A lot of time may be wasted waiting to see if something fails. As a workaround, the protocol executes the callback whenever it receives anything (not just a nonce report) from the destination. As a result, supervision encapsulation is used, ensuring that a response is received without needing to wait for the S2 timeout to expire.

Z/IP gateway will automatically use this option depending on the payload.

S2 TX option 'Verify' overloads the protocol value TRANSMIT_COMPLETE_OK. Normally, this means transmission was successful but does not indicate whether it was decrypted correctly or not. When TX option verify is used, it indicates transmission was successful and that the SPAN was resynchronized, if required.

Z/IP Gateway Implications#

S2 TX option verify is not controlled manually when using the Z/IP gateway. Instead, the Z/IP gateway will automatically invoke TX option verify depending on the payload so an ACK means different things, depending on the payload. For a get, TX option verify will be invoked, and ACK means the frame was delivered and the SPAN was resynchronized, if required. For a set, an ACK means the frame was delivered but does not indicate if it was decrypted correctly or not (unless supervision encapsulation is used to trigger a response). When using the Z/IP gateway, always send frames that automatically trigger a response (or use supervision encapsulation).