Getting Started with Z-Wave Development (500 Series)

2020-01-18 (updated: 2020-01-20)

The Z-Wave protocol is relatively complex and gets more complex every year. It is difficult to get started due to the sheer number of documents.

This article aims to help you with developing your first (500 series) Z-Wave device by helping you get past the biggest entry barriers:

Which approach is best suited for our product?
Where do I find the information I need?
When should we work on what?
Which aspects require extra attention?

Warning: This introduction focuses on the old 500 series of Z-Wave chips and is based on how things worked back in 2019. The Z-Wave protocol is evolving quickly, so take these suggestions only as a rough orientation.

Websites

Non-Technical

Consumer focused marketing page
Business focused alliance page

Technical

Certified Products Database
Database with all certified Z-Wave products and their documentation.
Z-Wave Technical Service (ZTS)
Development resources, e.g. datasheets, specifications, code, tools.
- Specification
- Certification
- Software and Tools
  Embedded SDK, Controller SDK, Protocol Life Cycle.
- Dev Kits
- Search

Technical Documentation

In order to get started with Z-Wave development, it helps to get the big picture, i.e. get familiar with the Z-Wave specific concepts.

Know which information is available, where you can find it, and don’t try to understand everything at once. You can always find additional documents via SiLab’s Z-Wave search. An overview of the most important technical documents is available in the References article of the Z-Wave Cert Portal Wiki—only accessible by Z-Wave members.

To get started quickly, follow the product development steps outlined below. They’ll show you what to read at which point in the development process. Only read additional documentation if you are stuck.

Note: Always make sure to work with the latest documentation, tools, firmware binaries, and code samples.

Overview: quick

[SRN13926] Z-Wave 500 Series SDK v6.81.01
SRN13926-5 pages 2-4: overview of Z-Wave technology.
[APL13475] Z-Wave Development Basics
Overview of the dev process and what to consider: Creating Z-Wave Devices

Overview: detailed

Application Notes
[APL12955] Z-Wave Multi Channel Basics
[APL12956] Z-Wave Association Basics
[APL12957] Z-Wave Battery Support Basics
[APL13031] Z-Wave Networking Basics
[APL13084] Z-Wave Control Application Basics
[APL13128] Z-Wave Time and Date Basics
[APL13298] Z-Wave Device Configuration Basics

Specification documents: generic

Device & Role Type Specification
[SDS11847] Z-Wave Plus Device Type Specification
[SDS11846] Z-Wave Plus Role Type Specification
Command Class Specification
[SDS13781] Z-Wave Application Command Class Specification
[SDS13782] Z-Wave Management Command Class Specification
[SDS13783] Z-Wave Transport Encapsulation Command Class Specification
[SDS13784] Z-Wave Network-Protocol Command Class Specification

Specification documents: specific

Z/IP
[SDS11445] IP Architecture Framework for Z-Wave (Z/IP)
[INS12503] Z/IP Gateway Porting Process
[SRN14206] Z/IP GW SDK 2.81.00
[SDS12089] Z/IP Gateway Bootstrapping
[INS12903] Z-Ware Web User Guide
Hardware: Chip
[INS12213-14] 500 Series Integration Guide
[SDS12467] 500 Series Z-Wave Chip NVR Flash Page Contents
[INS12524] 500 Series Calibration User Guide
[DSH12625-9] ZM5101 Data Sheet
Hardware: RF
Radio frequencies for different world regions.
[APL10045] Application Note - Antennas for Short Range Devices
[INS12880] Micro RF LinkX for 500 Series

Guidelines: programming

On-chip via C API
[INS12366] Working in 500 Series Environment User Guide
[INS13954] Z-Wave 500 Series Appl. Programmers Guide v6.81.0x
[INS13953] Z-Wave Plus Application Framework v6.8x.0x
… SW architecture overview on page 4 ff.
[SRN13926] Z-Wave 500 Series SDK v6.81.02
[ERN13927] Known Test Observations SDK v6.81.02
[DrZWave] 8051 8-bit CPU Coding Tricks & Tips
Creating Z-Wave Devices
On-host via Serial API
[INS12350] Serial API Host Appl. Prg. Guide
[INS10245]] Z-Wave Bridge User Guide

Guidelines: certification

Process
[Cert Portal Wiki] Description of the certification program and process
[INS10638] Z-Wave Certification Overview
[INS10637] Z-Wave Certification Form V8.5
[STP14205] SW Test Plan - Supervision Command Class certification tests
[SDS13783] Z-Wave Transport-Encapsulation Command Class Specification
… e.g. “Key Management” for S2.
Testing/ Reliability
[Cert Portal Wiki] Table of Contents
[CTS10999] Z-Wave Certification Test Specification
[INS10336] Z-Wave Reliability Test Guideline

Product Development Steps

Define the customer’s requirements.
Determine the technical approach.
1. Find out in which general direction the development will go.
  1. Select the world region.
  2. Determine Device Type [SDS11847] and Role Type [SDS11846] by also looking at the Device Classes [SDS10242].
  3. Select SW tech stack (ZW SDK vs. Z/IP GW).
2. Start HW development (on-chip vs. on-host, ext. NVM, production programming, …).
  1. Select the Z-Wave Radio Module/ SoC and buy the appropriate Dev Kit.
    Things to consider: Feature set, production volume, antenna options.
    Before you decide to use a SoC ALWAYS contact your assigned FAE or Z-Wave Sales Manager to discuss your choice.
  2. Perform HW tests as soon as possible, especially to verify the RF performance.
    Remember to tune the antenna beforehand, if it is a new (board) design.
    Choose and place your antenna wisely. Use the available application notes and guides.
    Make sure the PCB is layouted according to RF best practices.
3. Determine missing details so the SW implementation can start.
  1. Start updating your Preferred Devices.
  2. Start updating your Device Data.
  3. Determine CCs to use for the application (version, support/control) + explain the choice.
  4. Create Cert Case and make sure it reflects your current approach.
    (network role, CCs to implement, hardware configuration, …)
  5. Update list of CCs to implement based on feedback from Cert Case.
Start the SW implementation and non-technical documentation (based on what the Cert Case requires).
(a) Setup SW development environment + start implementation of CCs.
(b) Start designing/ implementing a SW architecture connecting the ZW implementation to the app layer—in case you implement the app on a host MCU.
(c) Ensure a spec compliant GUI.
(d) Start Market Cert (Product Information form hinders completion of the technical Certification).
(e) Create non-technical part of the End User Documentation.
Test as early and as often as possible. Focus on implementing usable/ testable features in small increments.
(Optional) Ask Test House for guidance on performing the tests.
(Optional) Ask Test House to give you advice on which implementation choices make the most sense in practice.
(Optional) Let the Test House’s SW dev do any low-level Z-Wave implementation for you.
Once MVP is ready: Start of in-house test phase.
Make sure, it was implemented correctly and document it.
(a) Start Self-Cert with Cert Case.
(b) Create technical part of the End User Documentation.
Self-Cert can start in parallel to the CC implementation.
Self-Cert tests the Device and Role Type requirements as well as the correct implementation of the supported Command Classes.
(Optional) Ask Test House for guidance on performing the tests.
Once SW is feature complete: Start of test phase with select customers.
Start the technical certification once everything seems to be implemented correctly.
1. (Optional) Pre-Cert
  Let the Test House perform a Pre-Cert so you know how well you are doing.
  Can be converted into a full Cert, if it looks good. This saves time and reduces risk due to flexibility.
  One does not have to wait long for a Pre-Cert and a Pre-Cert can be stopped any time, while a full Cert has a high up-front cost.
2. Technical Certification at Test House
  The certification will fail, if more than three technical issues (CC/ protocol) are discovered. Five document issues count as one technical issue. See details.
  You will likely fail at your first attempt—especially if you are building a controller.
Set up S2 (and SmartStart) label printer
Set up Production Testing
See [INS10343] for a description of the test procedure.
Test software is provided as part of the Z-Wave Embedded SDK: Production Test DUT/ Generator and PVT files.
Typical tests:
(a) RF performance
(b) Open/ shorts
(c) Power consumption
(Optional) Add device to FOSS registries.
Example: Horstmann SRT323 in OpenZWave.
Product release

Product Development Checklist

A simple way to track overall progress and report to management.

Example states:
TODO: no work has been done yet
WIP: task is currently worked on
blocked: task was interrupted b/c something is missing
DONE: no more work needs to be done

Each state can be color-coded to represent it’s context:
red: high risk of failure/ problematic.
yellow: medium risk of failure/ may be a lot of work or complicated.
green: low risk of failure/ no issues.

State	Item	Comment
	1. Functional and technical specification
	2. Device Type
	3. Role Type
	4. Security Class
	5. ZW SW versions we build on
	6. SW tech stack we decided to use
	7. HW development, EMC performance
	8. ZW Preferred Devices
	9. ZW Device Data
	10. Cert Case: “Development and Manufacturing” section
	11. CCs we want to use for the app
	12. CCs the Cert Case requires us to implement
	13. Implement CCs
	14. SW architecture (ZW impl <-> app)
	15. Spec compliant GUI
	16. End User Documentation: non-technical
	17. End User Documentation: technical
	18. Cert: Market Cert
	19. Cert: Self-Cert
	20. Cert: Pre-Cert at test house
	21. Cert: Certification at test house
	22. Production: setup S2 (and SmartStart) label printer
	23. Production: testing
	24. Release

After the Certification

Track all future changes of your software’s Z-Wave part with an internal version number. This will make it easier to recertify subsequent stable releases.

Matthias Miehl