Developing Z-Wave IoT Devices: Choosing the Right Sample Application in the Z-Wave SDK
Introduction
How do you get started in developing a wireless IoT product using Z-Wave? Assuming you’ve chosen a silicon vendor from Part 1 of this blog, the next step is to become familiar with the tools, developer kits and software of the respective vendors, Silicon Labs and Trident IoT. Both vendors utilize the popular Microsoft Visual Studio (VS) Code Integrated Debug Environment (IDE). Each has developed an extension to customize VS Code for their respective SDK. If you’re not already a VS Code user, you should be. The Intellisense AI feature is a game changer for managing the large amount of code in the SDK you will be interfacing with for your project. I am relatively new to VS Code and I am still in the learning phase. Please comment on this blog If you know of any time saving tricks that I’ll be happy to pass on to the rest of the community.
I highly recommend taking the training and reading documentation from each vendor on using their tools and developers kits. In later postings I’ll be using these tools and assume you are already familiar with them.
Software Architecture, FreeRTOS and the SDK
Fundamentally the Z-Wave SDK relies on the open-source FreeRTOS real time operating system. FreeRTOS provides many resources such as multitasking, software timers, memory management and security. The Z-Wave SDK is in one task, your application code is in another task and then there are a few utility tasks. The use of an RTOS makes the code more modular but also more complex. Instead of simply calling a function to send a message over the radio, the application task sends the message through a queue to the Z-Wave task which then sends it over the radio and later returns the result to a callback function you passed through the queue. When the RTOS determines there’s nothing to do, it will put the chip to sleep. An always-on device will only put the CPU to sleep and leave the radio on, but battery powered devices will go into a low power mode.
Each vendor has some amount of the SDK pre-compiled into a library. Mostly this provides an abstraction layer that gives the vendor a level of intellectual property protection. Much of the code is in source code form and you will compile the SDK with your code as well. Trident has a method to compile all the source code into your project which can make debugging the SDK possible. The SDK includes lots of helper APIs and code for many common command classes. If the command class you need is not available (yet), you will want to copy the code of a similar command class. To be efficient, you need to reuse as much code as possible. Gotta love copy and paste.
Role Types & Device Types
The first step in defining a new Z-Wave product is to choose which broad Z-Wave category the product fits into. The Z-Wave Role Type defines how the device is powered, which in turn relates to how the messages are passed through the Z-Wave mesh network. There are five important Z-Wave Role Types:
| Name | Abbreviation | Comment | |
| 1 | Central Static Controller | CSC | Host controller running SerialAPI
Calculates all routing in the mesh |
| 2 | Always On End Node | AOEN | Wall switches, repeaters, wall powered
All nodes act as repeaters in the mesh |
| 3 | Reporting Sleeping End Node | RSEN | Battery powered sensors
Relies on AOEN to pass messages |
| 4 | Listening Sleeping End Node | LSEN | Door locks, thermostats
Wakes up every 1s – low power |
| 5 | Wake On Event End Node | WOEEN | New – energy harvesting devices |
There are several other rarely used Role Types in the Z-Wave Specification, but these are the five most products use. Some devices might operate as more than one Role Type. A wall powered thermostat is an AOEN type. But if the thermostat is joined to a Z-Wave network when it is battery powered, then it would be an LSEN. LSEN type devices sleep most of the time but wake up once every second very briefly and listen for a wakeup beam and if there is one then they fully wakeup and can receive messages. The important thing to note here is that it is possible for a device to be different Role Types when joined to a network. Once joined to a network, a device cannot change its Role Type. The thermostat must be removed from the network and added back in with the new Role Type.
The next step is to choose the Device Type. Refer to section 7 of the Z-Wave specification for the list of Device Types. The Device Type lists the mandatory Command Classes required for your product. You can then add more Command Classes to match your needs, but the mandatory list ensures interoperability which is a key aspect of Z-Wave. These are again broad categories which your product should be able to find a matching one. The Device Type can be a good starting point if there is a close match. The Device Type then points you to the Role Type.
Z-Wave, Z-Wave Plus, Z-Wave Plus V2
It is helpful to clarify what the “Plus” designation means in Z-Wave Plus and Z-Wave Plus V2. From a low-level radio perspective, Z-Wave, Z-Wave Plus, and Z-Wave Plus V2 all use the same fundamental communication framework and message transport. The differences between them are not in the underlying radio protocol, but in the certification requirements and mandatory command classes that devices must support.
Z-Wave Plus introduced a set of mandatory command classes for certified devices, including the Z-Wave Plus Info Command Class. This allowed controllers to automatically identify key device characteristics such as device type, role, and capabilities.
Z-Wave Plus V2 builds on this by requiring additional command classes and mandating newer minimum versions of several existing command classes. These requirements significantly improve interoperability across the ecosystem.
Because of these enhancements, a host controller can interrogate a device and automatically discover most of its capabilities without relying on manually written device profiles or engineers referencing product documentation.
Today, all newly certified Z-Wave devices must comply with Z-Wave Plus V2 requirements. In practice, this means new products are far more likely to work immediately with most host controller software, rather than requiring months or years before specific support is added.
Sample Applications
There are eight sample applications in the Z-Wave open-source github repository. Both vendors have the same set of sample applications and each has a few special ones as well.
| Name | Role Type | Comments | |
| 1 | Switch On/Off | AOEN | Recommended starting point for new developers
Easy to use and debug |
| 2 | Multilevel Sensor | RSEN | Deep Sleep battery powered sensor
Multilevel Sensor and Configuration CC |
| 3 | Door Lock Keypad | LSEN | Door Lock example that will wakeup every 1s |
| 4 | LED Bulb | AOEN | Color Switch and Multilevel Switch (dimmer) CC |
| 5 | Power Strip | AOEN | Multichannel CC individually controls each outlet |
| 6 | Sensor PIR | RSEN | Notification CC & Application Task |
| 7 | Wall Controller | AOEN | Central Scene CC |
| 8 | SerialAPI | CSC | Pre-compiled binaries are most often used |
Begin your project by selecting the sample application that most closely aligns with the power source for your project. The main trick is to copy code from the other sample apps to add features to your project. For example, the Sensor PIR project includes a FreeRTOS application task to sample a sensor, the Wall Controller shows how to manage button presses to send Central Scene commands (BTW: Central Scene should be called the Button Press command class!). Your product probably doesn’t exactly match the sample app but you can copy code from any sample app into your project.
When first starting out with Z-Wave development, experimenting with the Switch On/Off app is ideal to learn the tools and the SDK without having the complexity of the device sleeping when you least expect it and dropping off the debugger. I suggest experimenting with the classic blink an LED and send/receive Z-Wave messages using Switch On/Off app. Once you’ve got a basic feel for the tools, then start over from the beginning using a more advanced sample app. We’ll get more into debugging in a later blog post.
Once you’ve chosen a sample app to get started, my recommendation is to then write down EVERYTHING you’ve done to customize the sample app or make extensive use of git. Unfortunately, the Z-Wave SDK continues to be in a fair amount of flux and quite a lot of code and even APIs change from one release to the next. Generally, it has been required to start from scratch with the same sample app in a new release and re-implement your project. The vendors are making improvements in their “upgrade” tools which will hopefully handle SDK updates in the future, but reimplementing has been required up to now. Note that you must use a relatively recent SDK for certification. Always start out with the latest release and unless you can finish the project in less than 6 months, you’ll need to update to a newer release.
What to Customize Next
Below is a list of things I customize for any new project. I’m using the Silicon Labs SDK in this case but Trident is similar and starts by editing the app/CMakeLists.txt file. Open the .slcp file in Simplicity Studio V6, click on Software Components, then Installed, then open the Z-Wave list.
- Z-Wave Core Component – Select the Z-Wave Region to match your location
- Max Tx Power will need customization when preparing for regulatory approval
- Z-Wave Version Numbers – Turn on (True) Use Application Version and enter version numbers
- The Minor Version MUST be incremented for OTA firmware update
- Z-Wave ZAF Component – Several items must be customized for your product
- The Manufacturer Specific ID, Product Type and Product ID are a 48-bit unique identifier for the product – basically a fingerprint
- Command Classes – Association CC – Recommend a single Lifeline NodeID
- Uncheck Installed – then install Z-Wave Debug
- This will uninstall Z-Wave Release which uses higher compiler optimization and the debugger is unable to accurately single step C source code
- Note that OTA fails when DEBUG is enabled due to code size with the lower optimization
- Z-Wave Log – optionally turn on more logging which will print more messages out the UART
- Entering vcom into all 4 debug levels will print a lot of messages
- Be sure to turn this OFF when getting close to a release
- Note that the sending text out the UART is a blocking operation and will change how the code runs and may cause a watchdog reset
These customizations are just the start! From here you will install other command classes, SPI, I2C or UART drivers and of course your own custom code.
Next Steps
In part 3 of the journey, I’ll be discussing the key to Z-Wave’s interoperability, Command Classes. Command Classes define what one device sends to another device to pass information in a way that both the end device and the host understand at the application level. As we continue along the Z-Wave Developer’s Journey, I welcome your comments and questions. Please feel free to reach out to me directly via email.
About the Author
Eric Ryherd has been at the forefront of Z-Wave innovation since 2003, beginning as a consultant and later serving as a Field Application Engineer at Silicon Labs. Over the course of his career, he has contributed to the design and development of a wide range of Z-Wave products, including sensors, remote controls, motorized window shades, and in-wall dimmers, many of which are on the market today.
Although he “retired” in 2022, Eric remains deeply engaged in embedded systems and Z-Wave development through his blog, DrZWave.blog, and ongoing IoT consulting projects. He is also a familiar face at Z-Wave Alliance Unplug Fests, where he frequently serves as the lead coordinator, supporting interoperability and developer collaboration.
