How to develop Z-Wave Devices
1. What is Z-Wave ?
Z-Wave has become the new star on the horizon of smart home technology with now more than 700 interoperable devices in the market. It opens a great opportunity for newcomers to add smart and new ideas to this large ecosystem of interoperable products and leverages the existing installed base.
This article describes the development process and the tools available to design and test Z-Wave compatible devices. Technically, Z-Wave is a specification for a low bitrate communication protocol that allows different devices in buildings to communicate with each other wirelessly. These devices include fix-installed gear such as light switches and heating control, mobile devices such as remote controls and also gateways to internet based services on mobile phones or in the Internet. The specification covers all aspects of the communication from the radio layer up to the way devices generate events and execute actions. Only devices with complete implementations of all aspects of the communication protocol are called Z-Wave compatible or short a Z-Wave certified device.
2. Hardware
To support the Z-Wave radio layer a special Z-Wave transceiver hardware is needed. The main supplier for this transceiver is the US company Sigma Designs (NASDAQ: SIGM). A second supplier, Mitsumi Corporation, offers a function and pin compatible silicon [Mitsumi2012]. The current chip generation of Sigma Designs is called Series 400 with the ZM4101 as standard component. Sigma or Mitsumi do not sell separate radio transceivers but the radio as one part of a whole SOC. The radio transceiver is available as a chip to very high volume applications where it can be embedded in the base designs but most customers purchase a SOC that integrates all functions of a computing system with radio interface:
• CPU Core, compatible to 8051
Figure 1: Z-Wave radio transceiver from Sigma Designs
Figure 2: Z-Wave Module ZM3102 based on Series 300 Transceiver ZW0301
• Radio transceiver with receiver and transmitter
• 2 KByte … 16 KByte Internal SRAM
• 32 KByte …64 KByte ROM
• Several Peripherals
Figure 1 shows the Z-Wave transceiver Series 400 chip from Sigma Designs as an example.
The series 400 comes equipped with one-time programmable memory making it ideal for cost sensitive designs where reprogramming isn’t required. The vast majority of applications use the Series 300 chip and its Flash based memory. The re-programmable Flash memory is better suited to development programs and applications that require updates from time to time.
Sigma Designs has announced the next generation chip called Series 500 to be available in 2013. This chip series will be pin and function interchangeable with the Series 400 but will replace the Series 400 OTP with Flash memory.
Figure 2 and 3 show the most commonly used module ZW3102 from Sigma Designs that com- bines the Series 300 chip with some capacities, a crystal and most important – an antenna filter.
The antenna filter is needed to comply with the regulations of the license free frequency bands used for Z-Wave. These antenna filters are frequency-specific for e.g. 868.4 MHz (Europe, Africa
Figure 3: Series 300 Z-Wave module size comparison
and parts of Asia) or 908.4 MHz (North America) and turn the modules into a region specific device. As a result different hardware exists for different frequency bands and manufacturers have to manufacture separate hardware e.g. for the European or the US market. The modules can be ordered either directly from the manufacturers or from Digikey (https://www.digikey.com), the worldwide distributor of Sigma Designs. The price point depends on volumes but a budgetary estimate of 5 … 6 US-$ can be assumed for small production volumes of few thousand modules.
The module fans out all I/Os of the SOC. These I/Os are multi-purpose I/Os and can be freely programmed as output, input with or without internal pull up. Certain I/Os have special functions to support commonly used circuits such as dimmers or motor control.
I/Os for the Series 300 are
• 10 * General Purpose
• Two Interrupt Inputs
• Serial UART
• SPI Interface
• Triac Control, allows directly attaching the Zero Crossing signal of a phase edge dimmer circuit and deliver the Triac control signal to design a dimmer with minimum external components.
• PWM Output
• Four multiplexed 12/8 bit ADC inputs
Generally the flexible I/O concept and the module approach allow designing products with minimal additional cost. Assuming a project for a simple binary sensor powered by a battery the whole product can be designed with as few as 10 additional components including the external antenna.
The modules provide a SPI interface that is used to program the memory and can be used to attach an external serial SPI EEPROM. The external EEPROM can be used to store additional application data. It is not possible to use the external EEPROM for operation code.
More information about the electrical characteristics of the Z-Wave Module Series 300 can be found in the product specification [Sigma300]. The 8051 compatible microcontroller with internal ROM typically contains and executes the application code of the device. Devices with more complex functions such as remote controls – may
Figure 4: Z-Wave Communication Stack
use the Z-Wave chip as a companion chip for communication only but the amount of memory and computing power typically allows implementing all needed functions right into the transceiver chip itself to save cost and PCBA foot print.
2.1 Firmware
For the software development a System Development Kit (SDK) is needed. Different versions of SDKs are offered by Sigma Designs, Mitsumi or Digikey with price points between 1500 and 3500 US-$. They differ in the selection of hardware provided. The more expensive SDK-versions not only contain EEPROM programmer hardware but also different test hardware for sensors, actors and for different frequencies. All SDKs contain the software and documentation package. In order to access the set of documentations, software codes and tools a NDA with Sigma Designs needs to be signed. By signing the NDA the manufacturer agrees to keep all information provided in the SDK as confidential.
As shown in Figure 4 the communication stack of Z-Wave consists of three parts. The PHY and MAC layer is specified as ITU-T recommendation G.9959 [ITU2012]. The network layer is Sigma Designs proprietary code and protected by several patents. The application layer is defined by the product manufacturer but needs to comply to the protocol to ensure interpretability and product certification.
The SDK contains all needed documentation and code to build a firmware that covers all three parts of the communication stack. The NET, PHY and MAC layer are well defined and shall not be altered by the developers. They are therefore not available as source code but as precompiled libraries only. The libraries are complemented by plenty of sample codes to show the usage of the libraries and to document the implementation of a Z-Wave compatible code.
The closed source of the libraries has its pros and cons:
• Con:
In case there are bugs in this library the turnaround cycle is much longer and for developers debugging is harder.
• Pro:
Nobody can change the lower part of the protocols. This makes sure that at least for this part all Z-Wave products interoperate without problems, since they all rely on the same well managed code base.
In order to compile a firmware for the Z-Wave modules using the Sigma Designs SDK a KEIL C compiler is needed [KEIL]. Although KEIL is a good and professional tool developers would certainly prefer to use the GNU tool chain as well. The precompiled libraries for the PHY and NET layer however force the usage of certain versions of the KEIL compiler and its environment. The SDK contains the following parts: precompiled libraries for different applications, sample code, source code for certain tools and the complete documentation of the Z-Wave protocol.
Z-Wave distinguishes different functions in the network, referred to as controllers or slaves. These different roles in the network use different functions in the protocol in Z-Wave. As a result the SDK offers different library versions for different device roles in the network. The main reason for this is memory footprint since the implementation of all functions in one library would exceed the available EEPROM space to store operation code. Most of the functions of the library, particularly the versions dealing with the network organization but also the initialization of the chip and the handling of the input and output queue of the transceiver are hidden from the developer. The main functions the developer uses are:
• sending and receiving application commands
• including / excluding devices
• some network management functions
• access to the peripherals such as watchdogs, TRIAC control etc.
The SDK also contains a skeleton to simplify the design of new applications. Various sample codes for different functions of Z-Wave simplify the use of the skeleton and help in developing applications. Unfortunately developers have almost no debugging mechanism for writing Z-Wave firmware. There is neither a JTAG in circuit debugger interface available or any emulator or simulator for the chip. The memory constrains for the 300 series add another layer of complexity and can make the development of firmware a frustrating experience. However the Z-Wave ecosystem contains several service providers that provide help and professional development services. [Z-Wave.Me] [Seluxit].
3. Design interoperable products
The communication part of the device control code needs to comply with the Z-Wave specification. The Z-Wave specification defines different roles of a device and the developer must choose one of these role types.
• Role in the network: controller can built own networks, additionally differentiating between mobile controllers (e.g. remote controls) or static controllers (e.g. gateways)
• Power supply model: battery powered with regular wakeup, mains powered, battery powered that can be waken u using a wakeup beam.
• Function of the device: switch, dimmer, motor control device, thermostats etc.
The role models of Z-Wave are described in so called Device Classes. The manufacturer needs to choose one device class the products shall fit in. This already defines certain functions and services this device must support. The wireless functions and services of a device are described in so called Command Classes. Command classes are groups of wireless commands that are used to control certain aspects of a device or to deliver data in relation to this aspect.
Command classes are e.g. called Binary switch, Battery, or Motor Control and combine all functions to deal with a binary on/off switch, the batteries status reporting or the control of a motor device. The command classes that are required by choosing a device class are called mandatory command classes. More than 20 Device classes and 100 Command Classes are described in the Z-Wave Standard.
The manufacturer can – and typically does – add additional voluntary command classes. There are no restrictions on what other voluntary command classes are implemented but in case a certain command shall be supported by the device this command class needs to be:
• announced in a so called Node Information Frame during the inclusion process
• implemented completely and according to the Z-Wave Command Class specification.
The API description of the libraries, the definition of the device classes and the definition of the command classes are therefore the core documents Z-Wave developers need to work with.
4. Serial Interface to Hosts
The very same module that is used to build products such as dimmers or switches is also used to interface with other host computers, e.g. PCs. The main interface used for this is the serial interface of the chip.
Series 400 and the soon to be released Series 500 modules have direct USB support. The Series 300 use can convert the provided Serial port to USB by using any number of common Serial-2-USB chips (ftdi, prolific, etc.). They are well supported in all major operating systems and do not cause extra effort for installing device drivers. Adding the USB device will create a new virtual serial device the operating systems Z-Wave application is using (e.g. COM x in Windows or /dev/tty.usbserial for USB sticks utilizing the prolific USB-2-Serial chip.)
Manufacturers of USB or serial interface devices are free to define their own communication protocol used on this interface. However since the interfacing to a host computer is a common task the SDK already provides a specification that maps certain functions of the Z-Wave library to a serial interface protocol and defines how to exchange data via the serial interface as well.
The SDK also contains some precompiled firmware’s that implement this serial interface protocol also referred to as Sigma Designs Serial API. The result is that most of the Z-Wave interface devices such as USB stick etc. just use these pretested and predefined firmware’s implementing the Sigma Designs Serial API. Certain vendors however have enhanced and optimized the firmware for the host interface over the serial interface [ZSTICK].
On the host side of the serial communication link a software needs to manage the serial interface provided by the virtual serial device. Because the serial interface as recommended by Sigma Designs
Figure 5: The Z-Wave Logo guarantees interoperability
is simply mapping library functions to the serial interface this interface protocol is quite complex and not straightforward to deal with. Controller code on the host needs to handle various part of the network control and maintain timings and the message queue from and to the Z-Wave transceiver SOC.
Sigma again offers sample code how to do this but developers have more options to choose from. In the Internet there are several open source projects implementing the Sigma Designs Serial API, e.g. [OpenZWave]. They have partly reverse engineered the Serial API that is provided as part of the SDK under NDA. However there is no official support of these projects from Sigma Designs. These open source implementations may therefore not completely implement the specification and/or use the latest features of Z-Wave the correct way.
There are certain commercial implementations of Host side Z-Wave stacks available in the market as well that offer professional support for projects that do not want to implement the Z-Wave Serial API support from scratch again [Z-Wave.Me].
5. Certification
The final step in the development process of a Z-Wave device is the Z-Wave certification. All devices implementing the Z-Wave Standard need to be certified in order to carry the Z-Wave logo as shown in Figure 5. The certification makes sure that the tested device complies with the requirements of the device classes selected and that all command classes that are implemented fully comply to the Z-Wave specification. Additionally the wireless behavior is tested to make sure the device offers some minimal wireless range of 25 m without any errors. The manual and all documentation are reviewed as well to ensure that the key characteristics of Z-Wave:
• two way communication,
• meshing,
• Inclusion, Exclusion, Association,
• interoperability of devices form various manufacturers
are correctly mentioned and described in the manual.
The certification process is very transparent. All test cases are well defined and the test tool used by the certification house is available to manufacturers to perform a pretest. Certification tests are done by two independent test houses Pepper One [PepperOne] in Germany and Bulogics [Bulogics] in the US. The test results of the test houses are submitted to the certification manager that will finally decide on the certification case and issue a certification number. The certification fee is 2000 USD regardless of the complexity of the device including the review of the manual.
6. The Z-Wave Alliance
The Z-Wave Alliance is the alliance of all companies using and supporting the Z-Wave protocol standard. Beside certain marketing and promotion activities the alliance also helps developers in various ways.
• The Alliance is organizing so called Un-Plug Fests. Here developers can test their products – finished or unfinished – against products of other vendors of the ecosystem and receive arm-length help from Field application engineers of Sigma Designs.
• One- and Two Day trainings evens help to get started with Z-Wave as technology and the development process.
• The Alliance runs an Interoperability lab in New Jersey (US) area that can be booked to perform advanced tests of products.
• Alliance maintains and offers the Z-Wave Compliance Test Tool to validate own products against the Z-Wave protocol specification.
• Developers can even join working groups within the Alliance that define new command and device classes. This particularly useful if the new projects to be developed offers brand new features not defined in Z-Wave yet. Collaboration in the further development of Z-Wave is not only allowed but appreciated.
More information about these activities can be found on the Z-Wave Alliance Website www.z- wavealliance.org.
7. Conclusion
The integration of Z-Wave hardware in own projects is quite straightforward and only minimal additional components are needed to design a product. In most cases the MCU of the Z-Wave SoC can be used for the application functions as well. The development of Z-Wave firmware on the chip requires documents, code skeletons and libraries available as SDK under NDA. The lack of debugging tools is a challenge but mitigated by plenty of example code and good documentation of all aspects of the design. The certification of Z-Wave devices ensures compatibility by testing the implementation of the application layer command classes and some other aspects. Sigma Designs offers an integrated end-to-end design flow that allows effective development of Z-Wave compatible devices. The Z-Wave Alliance provides a Compliance Test Tool (gold standard used by the test labs) and support in its Interoperability Test Lab.
References
[Mitsumi2012] Mitsumi Electric Co, Ltd Press Release: Mitsumi concluded Z-Wave Module Supply Agreement with Sigma Designs, Inc. in USA, May23rd, 2011, https://www.mitsumi.co.jp/pdf/20110523_e.pdf
[Sigma300] Sigma Designs, Ltd ZM3102 Z-Wave Module, Data Sheet, October, 2007, https://media.digikey.com/pdf/Data%20Sheets/Zensys%20PDFs/ZM3102N.pdf
[ITU2012] ITU-T G.9959: Short range narrowband digital radio communication transceivers – PHY & MAC layer specification, International Telecommunication Union, 02/2012
[Z-Wave.Me] Homepage: www.zwave.me
[Seluxit] Homepage: www.seluxit.com
[ZSTICK] https://www.zwaveeurope.com/PC-Adapters.23.0.html
[OpenZWave] Open Source Z-Wave Implementation in C, code.google.com/p/open-zwave/
[PepperOne] Homepage: www.pepper-one.de
[Bulogics] Homepage: www.bulogics.com/
[KEIL] Homepage: www.keil.com/
About the author:
Christian Pätz is honorary professor for systems reliability at the Chemnitz Technical University and spokesperson of the Z-Wave Alliance in Europe.
If you enjoyed this article, you will like the following ones: don't miss them by subscribing to :
