Z-Wave Protocol Controller (ZPC)

Table of Contents

• Z-Wave Protocol Controller (ZPC)
  • Table of Contents
  • What is ZPC?
  • ZPC features
  • Supported Z-Wave Command Classes
  • How to run ZPC
    • Installing dependencies
      • macOS
      • Linux
  • How to use ZPC
    • Setting up the MQTT broker (e.g., Mosquitto)
    • Setting up the NCP
    • Setting up the Switch On/Off device
    • Building ZPC
    • Configuring ZPC
    • Running ZPC
  • Switch On/Off Demo
    • Step 1: Start the MQTT broker
    • Step 2: Start ZPC
    • Step 3: Add the Switch On/Off device to the network
    • Step 4: Control the Switch On/Off device via MQTT
  • Documentation
    • Getting started
    • MQTT APIs
    • Guides
    • Component docs
    • Command class reference
    • Sequences
  • Resources
  • Legal info

What is ZPC?

ZPC is a Linux/macOS based Z-Wave gateway application that functions as a central static controller in Z-Wave networks. It provides the host side functionality of the Z-Wave Controller, and interacts with the Z-Wave network through the Silicon Labs Network Co-Processor (NCP) controller. As a static controller, ZPC remains continuously powered and acts as the primary hub for managing and coordinating communication among all Z-Wave devices in a smart home network. ZPC provides network management, device control, and state synchronization capabilities through an MQTT-based communication interface.

ZPC features

• MQTT based communication: Subscribe to and publish to MQTT topics to control and monitor Z-Wave devices and the network
• Z-Wave network management: Add and remove nodes from the network, device control
• Persistent storage system: Store the state of the Z-Wave network and devices

ZPC uses a reported/desired value system where all state parameters have a reported value (current state) and a desired value (user-preferred state). When these values differ, ZPC automatically sends the appropriate commands to synchronize the state.

Supported Z-Wave Command Classes

Command Class	Version	Supported	Controlled	Security Level
Association	3	true	true	Network Scheme
Association Group Info	3	true	true	Network Scheme
Basic	2	false	true	Network Scheme
Battery	3	false	true	Network Scheme
Device Reset Locally	1	true	true	Network Scheme
Door Lock	4	false	true	Network Scheme
Firmware Update MD	5	false	true	Network Scheme
Indicator	4	true	true	Network Scheme
Manufacturer Specific	2	true	true	Network Scheme
Multi Channel	4	false	true	Network Scheme
Multi Channel Association	3	true	true	Network Scheme
Notification	8	true	true	Network Scheme
Power Level	1	true	false	Network Scheme
Protocol (Z-Wave)	1	true	false	Network Scheme
Protocol Long Range	1	true	false	Network Scheme
Security 0 (S0)	1	true	true	None
Security 2 (S2)	1	true	true	None
Supervision	2	true	true	None
Switch Binary	2	false	true	None
Switch Color	3	false	true	Network Scheme
Switch Multilevel	4	false	true	None
Thermostat Fan Mode	5	false	true	Network Scheme
Thermostat Mode	3	false	true	Network Scheme
Thermostat Setpoint	3	false	true	Network Scheme
Transport Service	2	true	true	None
Version	3	true	true	Network Scheme
Wake Up	3	false	true	Network Scheme
Z-Wave+ Info	2	true	true	None

Supported means the controller responds to this command class (support handler). Controlled means the controller can send commands for this command class (control handler). For full MQTT APIs per command class, see the Command Classes MQTT Interface.

Protocol (Z-Wave), Protocol Long Range, Security 0 (S0), Security 2 (S2), and Transport Service are not generated by the command class generator; they are implemented manually. S0, S2, and Transport Service are handled by the transport layer and are not exposed at the application layer.

How to run ZPC

Installing dependencies

macOS

brew install $(cat ci/dependencies/brew-packages.txt)
pip3 install -r ci/dependencies/requirements.txt

Linux

apt-get install -y $(cat ci/dependencies/apt-packages-base.txt)
pip3 install -r ci/dependencies/requirements.txt

How to use ZPC

Setting up the MQTT broker (e.g., Mosquitto)

mosquitto -p 1883

Setting up the NCP

Flash the NCP Serial API Controller firmware and note the serial port it is connected to. For example, /dev/ttyACM0.

Setting up the Switch On/Off device

Flash the Switch On/Off device firmware and consult the firmware documentation. Note the first 5 digits of the device DSK.

Building ZPC

# <preset_name>: macos or debian
cmake --workflow --preset <preset_name>

On Linux, you can produce a Debian package (.deb) after the build; see docs/packaging-debian.md.

Configuring ZPC

Use this configuration file as a template.

Point to your configuration file with:

--conf <path_to_config_file>

To get ZPC running, set these parameters in the template under the zpc: section:

• Serial port — NCP connection (e.g. the serial port of the flashed NCP):

zpc:
  serial: /dev/ttyACM0

Alternatively, use IP connection to the NCP:

zpc:
  ip_address: '192.168.1.2'
  ip_port: 4901

• Connection log file — where serial/IP communication of the Z-Wave module is logged:

zpc:
  connection_log_file: /path/to/the/log/file/file.log

• Datastore file — path to the persistent database:

zpc:
  datastore_file: /path/to/the/database/file/database.db

Running ZPC

./build/<preset_name>/applications/zpc/zpc --log.level d

ZPC is controlled entirely over MQTT — it does not read from the terminal. For full MQTT API documentation, see the MQTT API index, which links to Discovery, Network Management, SmartStart, Device Interview, and all Command Class MQTT interfaces.

Switch On/Off Demo

Step 1: Start the MQTT broker

See above section "Setting up the MQTT broker".

Step 2: Start ZPC

See above section "Running ZPC".

Step 3: Add the Switch On/Off device to the network

• Get the Home ID from ZPC by issuing the following command on MQTT

mosquitto_pub -t "zpc/Discovery" -m '{}'

• Home ID will be sent back on the following topic

zpc/Discovery/Report

• Start add process by issuing the following command on MQTT

mosquitto_pub -t 'zpc/<home_id>/Network/Node/Add' -m '{}'

• Enable learn mode on the end device by pushing BTN1
• For S2 inclusion, ZPC publishes to zpc/<home_id>/Network/RequestedKeys/Report when the node requests keys and to zpc/<home_id>/Network/RequestedDSK/Report when DSK verification is needed. Respond by publishing to zpc/<home_id>/Network/GrantKeys (payload: {"Accept":true,"Keys":<keys>,"CSA":<csa>}) and/or zpc/<home_id>/Network/DSK/Accept (payload: {"dsk":"<value>"}).
• Accept DSK on ZPC side by issuing the following command on MQTT

mosquitto_pub -t 'zpc/<home_id>/Network/DSK/Accept' -m '{"dsk":"12345"}'

• When the device interview finishes (per endpoint), ZPC publishes to zpc/<home_id>/Interview/Report with payload {"node_id":<id>,"endpoint_id":<ep>,"status":<code>}. Subscribe to that topic to know when the device is fully interviewed.

Step 4: Control the Switch On/Off device via MQTT

At this point the end device is successfully included to the network. To get the Node ID of that device in the network call the following MQTT API:

mosquitto_pub -t 'zpc/<home_id>/Network/Node/List' -m '{}'

It will reply on the following topic

zpc/<home_id>/Network/Node/List/Report

Node ID of the freshly added end device is in the node_information section

  ...
  {
      "node_information":{
         "basic_device_class":"4",
         "generic_device_class":"16",
         "listening_protocol":"211",
         "node_id":"2",
         "optional_protocol":"156",
         "specific_device_class":"0"
      },
  ...

To switch off the device, publish the following message to the MQTT topic:

 mosquitto_pub -t 'zpc/<home_id>/<node_id>/ep0/SwitchBinary/Command/SwitchBinarySet' -m '{ "target_value": "0", "duration": "0" }'

To switch on the device, publish the following message to the MQTT topic:

 mosquitto_pub -t 'zpc/<home_id>/<node_id>/ep0/SwitchBinary/Command/SwitchBinarySet' -m '{ "target_value": "255", "duration": "0" }'

Subscribe to the following topic to get notified about SwitchBinary state changes

 mosquitto_sub -v -h localhost -t 'zpc/<home_id>/<node_id>/ep0/SwitchBinary/Report/SwitchBinaryReport'

Example transmission

 zpc/<home_id>/<node_id>/ep0/SwitchBinary/Report/SwitchBinaryReport {"current_value":255,"duration":0,"target_value":255}

Documentation

Full documentation is built with MkDocs and the Material theme, and can be published to GitHub Pages. When enabled, the doc site is available at the repository's GitHub Pages URL (e.g. https://<owner>.github.io/z-wave-protocol-controller/) and provides a single navigation, search, and consistent base URL for all docs.

In-repo index — A dedicated docs index is at docs/README.md. To build the doc site locally: install dependencies with pip install -r scripts/mkdocs/requirements.txt, run python scripts/mkdocs/prepare_docs_for_mkdocs.py (merges Command Class docs), then mkdocs serve. MQTT API, Network Manager, and Device Interviewer docs are included automatically via the mkdocs-monorepo-plugin.

Getting started

• How to run ZPC — Dependencies and setup
• How to use ZPC — MQTT broker, NCP, build, config, run
• Switch On/Off Demo — End-to-end demo

MQTT APIs

• MQTT API index — Central index of all MQTT topics (Discovery, Network Management, SmartStart, Device Interview, Network Status, OTA, Command Classes) and links to sequence docs

Guides

• Command Class Implementation Guide — Implementing Z-Wave command classes in ZPC
• Known Failing CTT Test Cases — Automated CTT test failures tracked against ZPC

Component docs

• MQTT API Overview — MQTT API architecture and implementation
• MQTT API Interface — Topic conventions and MqttApiBase reference
• Network Management MQTT API — Add/Remove nodes (including Remove Failed), DSK, Grant Keys, Node List, Factory Reset, NLS
• Device Interviewer — Interview state machine and MQTT (Interview/Report)
• Network Status — Unsolicited Network/Status/Report for online/offline/unknown transitions
• OTA Firmware Manager — OTA state machine, MQTT commands/reports, and end-to-end example

Command class reference

• Command Classes MQTT Interface — Endpoint addressing and links to each command class MQTT doc

Sequences

• Inclusion flow — From Add/SmartStart to node added and interviewed
• Exclusion flow — From Node Remove to node removed

Resources

Additional links:

• CONTRIBUTING — How to contribute to the project
• License — Legal information

Legal info

Copyright 2026 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.