Session 5: Z-Ware Portal and Installation of Web Portal#

This session is the least technical of the series as it concerns the Z-Ware web UI and installation of the Web portal. It also includes a top down overview of Z-Ware.

Z-Ware Overview#

Z-Ware includes separate components that build on top of each other. At this point, Z/IP Gateway, which bridges the Z-Wave serial API to IP is well known. Z-Ware builds on top of the Z/IP Gateway.

Z-Ware is a stack of separate components. At the bottom of the stack is Z-Ware C-API which as the name implies, is an API written in C and can be accessed from native C-applications.

The next level is the Z-Ware Web daemon, which is built using the Z-Ware C-API. The Z-Ware daemon provides an HTTPS interface that allows to control Z-Wave through a restful API using Web standards.

On top of the Web daemon, Z-Ware includes an actual UI that resembles what a consumer would expect to see in an actual Z-Wave controller. The UI has the functionality required to be installed in a home and used to control Z-Wave devices in an meaningful way.

  • This is the collection of high-level controller components:

    • C-API

    • HTTPS interface

    • HTTP UI

Z-Ware Z-Wave Connectivity#

As previously mentioned, Z/IP Gateway offers local and global connectivity. Local connectivity requires end-to-end IP connectivity often on the same network segment and relies on DTLS security with pre-shared key.

Z-Ware relies on the local option, where Z/IP Gateway and Z-Ware are running on the same local network, and often also on the same host. In the lab exercise, this will be the Raspberry Pi.

  • Local

    • Local Z-Ware requiring end-to-end IP connectivity

    • Relies on DTLS security with pre-shared key

Developer Interfaces#

A developer can choose either the C-API or the HTTPS interface for their project.

  • C-API

    • Implements callback functions

  • HTTP interface

    • Implements scene engine

Choosing the Interface#

The main difference between the C-API and the HTTPS interface in terms of functionality is that the C-API implements callback functions. Callbacks can be created separately for each command class on each device. If having something like a motion sensor in the network, the controller software can configure a callback function for the motion sensor. If motion is detected by the motion sensor, the controller application receives a callback, and can trigger an action on this event.

The HTTPS interface is different because HTTPS by default does not implement push mechanisms. This means that the Z-Ware Web daemon can't push any events to an HTTPS client and notify it if an event occurs. To work around this, the Web daemon implements the scene engine. The scene engine allows the HTTPS client to push more application logic to the Web daemon, rather than having it in the application. As a result, it reduces the amount of HTTPS traffic between Z-Ware and the client.

Choosing the interface usually means weighing flexibility against ease of implementation. The further up the stack an application interface resides, the less flexibility Z-Ware offers, but the faster a finished product can be built. If moving down the stack, the application will have to implement more and more functionality. This will take more developer resources to, but the benefit is that there is more flexibility to create special solutions that may cater better for the product being implemented.

Taking the controller stack from the top, the first interface is the HTTPS interface. It has the least flexibility because it relies on the scene engine with the limitations it imposes.

When moving down to the C-API, more flexibility is available as callbacks can be configured for each individual type of frame that might arrive.

Then further down, discarding Z-Ware entirely and working directly on Z/IP Gateway, even more flexibility is available. Choosing the interface is always a trade off of flexibility against the cost of implementation. The recommendation when choosing the interface is to start from the top and see if the HTTPS interface suits the requirements. If not, move a step down to see if the C-API can fulfill the requirements. If not, move further down and rely on the Z/IP interface.

Z-Ware Portal#

Features#

Z-Ware portal UI is a fully-certified demo controller, which means that it fulfills all requirements for Z-Wave Plus version 2 gateway device type. As part of each release process, Z-Ware and with Z/IP Gateway undergo a full Z-Wave certification. As a result, the controller stack with the Z-Ware Web UI is equivalent to a finalized product in terms of mandatory Z-Wave functionality.

  • Fully certified demo controller

    • Fulfills all requirements for a Z-Wave Plus v.2 Gateway device type

Connection#

Like other Z/IP clients, the local version requires an IP address for Z/IP Gateway. Z-Ware automatically does gateway discovery and populates a drop down showing all Z/IP Gateways in the network. It also allows the user to enter an IP address manually. Next, the UI has a field for the DTLS pre-shared key, as seen from other Z/IP clients. The next field is the unsolicited port. The concept of the unsolicited destination has been discussed earlier. If populating this field, Z-Ware will bind to a port on the host it is running on and configure Z/IP Gateway to forward all unsolicited frames to the IP of the host Z-Ware is running on and the port specified here. If this field is not populated, lifeline reporting will not work. Specifically, battery-powered sensors will be heavily affected, but there will be issues with other device type as well. Failing to configure this field will prevent Z-Wave certification of the product.

  • Address

  • DTLS PSK

  • Unsolicited destination port

Connecting to Z/IP GatewayConnecting to Z/IP Gateway