ZPC Architecture#

ZPC separates application integration, controller services, persistent state, and Z-Wave network transport into distinct layers. Components communicate through the Component Connector, while the Z-Wave Serial API provides the boundary between the host application and the Z-Wave NCP.

ZPC High-Level ArchitectureZPC High-Level Architecture

For a high-level architecture overview on GitHub, see ZPC High-Level Architecture.

Application Communication Layer#

The Application Communication Layer connects ZPC to a product application through an external MQTT broker.

  • MQTT Handler (Paho) manages the connection to the MQTT broker and publishes and subscribes to MQTT topics.

  • MQTT APIs expose network management, device management, monitoring, OTA, and Command Class operations to the product application.

ZPC is controlled through MQTT and does not provide an interactive command-line interface. MQTT payloads use JSON, and topics identify the Z-Wave network, node, endpoint, service, or Command Class involved in an operation.

Services Layer#

The Services Layer implements application-layer features:

  • SmartStart manages the SmartStart provisioning list and automatic inclusion of provisioned devices.

  • Discovery allows an application to discover the ZPC instance and obtain its Z-Wave Home ID.

  • Device Interviewer discovers the capabilities, endpoints, supported Command Classes, and security properties of included devices.

  • Network Monitor tracks device availability and reports node status changes.

  • OTA manages firmware images and firmware updates for Z-Wave devices.

  • Command Class Manager registers Command Class implementations, checks security requirements, and dispatches incoming Z-Wave commands.

  • Command Classes implement the Z-Wave application functionality supported or controlled by ZPC.

These services publish information to the client application through the MQTT interface and use the lower layers to exchange data with the Z-Wave network.

Persistent Storage#

ZPC maintains a persistent representation of the Z-Wave network and its devices:

  • Attribute Store maintains device and network information in a hierarchical data model.

  • Attribute Resolver monitors reported and desired values and initiates the actions required to synchronize them.

  • Datastore serializes persistent Attribute Store data to a versioned SQLite3 database.

This design allows ZPC to retain network and device information across application restarts and to coordinate asynchronous communication with sleeping or temporarily unavailable devices.

Reported and Desired State#

ZPC represents relevant device properties with reported and desired values:

  • A reported value is the latest state reported by the Z-Wave device.

  • A desired value is the state requested by the client application.

When the values differ, the Attribute Resolver determines the Z-Wave command required to move the device toward the desired state. When ZPC receives the corresponding report from the device, it updates the reported value. This model separates the state requested by the application from the state last confirmed by the device.

Network and Transport Layer#

The Network and Transport Layer manages Z-Wave network operations and frame exchange:

  • Network Manager performs operations such as inclusion, exclusion, security bootstrapping, and factory reset.

  • TX/RX sends and receives Z-Wave frames.

  • Transport handles encapsulation and security for S0, S2, and Multi-Channel.

  • Z-Wave Serial API (SAPI) communicates with the Silicon Labs Z-Wave NCP over a serial or IP connection.

This layer supports communication with both Z-Wave Classic and Z-Wave Long Range networks.

Component Connector#

The Component Connector provides communication between ZPC components while keeping their implementations separate. Components use it to exchange events and data across the application communication, services, persistent storage, and the network and transport layers.

ZPC and NCP Responsibilities#

ZPC runs on the gateway host and provides controller services, application-facing APIs, security and transport processing, network and device state, and persistent storage.

The NCP running Serial API Controller firmware provides the Z-Wave radio and lower-level protocol functionality. ZPC communicates with the NCP through the Z-Wave Serial API protocol.