A Z-Wave Developer’s Journey | Part 3

DrZWaveLeave a comment

This is an abbreviated version of Part 3, the full article is on the Z-Wave Alliance Web site.

Which Z-Wave Command Classes to Use for Your Z-Wave IoT Device and Why

Command Classes are the key to Z-Wave’s application-level interoperability. All protocols have a standardized physical layer which ensures devices manufactured by different companies can communicate. Z-Wave’s physical layer is defined in the ITU-T G.9959 standard. The physical layer standard is necessary, but insufficient for IoT devices to communicate in a meaningful way. Command Classes are the key to enabling a controller to “know” how to turn on a light when motion is detected and adjust the thermostat to the liking of the user. Command Classes are defined in the Application Work Group Z-Wave Specification available on the Z-Wave Alliance web site.

The “spec” is over 1300 pages long. If you need help sleeping one night, crack this open and you’ll be off to lala land in no time! Fortunately, it is not a document you read from cover to cover. It is more like a dictionary, where you look up specific items to understand exactly how an IoT device communicates in an interoperable way, so all parties properly communicate the information. I make extensive use of the bookmarks bar in the PDF reader to quickly jump to the section I need. Search is also valuable to find the answer to a specific question.

Z-Wave Application Work Group Specification Z-Wave Alliance

When you first open the specification, you’ll see many versions of a command class and numerous ones that are obsolete or deprecated. If a command class is obsolete, you cannot use it ever and as a controller you don’t have to support it. Deprecated command classes are mostly old versions, and you must use the newer ones. Note that it is NOT required to support the latest version of a command class. For example, Battery Command Class version 1 is perfectly fine for most devices. Versions 2 and 3 add extra information for special types of batteries, but version 1 is fine for most IoT devices with simple batteries.

Another key Z-Wave file is the ZW_classcmd.h file which is in the SDK. This file explicitly defines every field of every command in every command class. The spec gets you to the right command, but the ZW_classcmd.h file defines the exact syntax and spelling of the fields you need to put in your code. Fortunately, VS Code does a pretty good job of filling most of this in for you when using Simplicity Studio V6. I’ll go into more coding details in the next blog post.

Where Do I Start?

What’s the first step in coding a new Z-Wave Product? You’ve already chosen the sample app in the 2nd blog and that choice goes a long way toward your first step here. Start with the Device Type V2 Specification section 7. There is a long list of common devices like switches, locks, bulbs, thermostats, sensors, and gateways. Your device should fit into one of these broad categories. Each Device Type specifies a list of mandatory command classes.

Mandatory Command Classes

The sample app typically provides all the mandatory command classes so there is no work required here. But you should double check as requirements change and sometimes the code lags the specification. The Z-Wave Certification Test Tool will do a comprehensive check for all the mandatory command classes so it’s worth a few minutes to check early in the project development.

Mandatory command classes are mandatory for a reason! They significantly improve interoperability! They help make most devices operate in a predictable way and provide similar information. They also ensure your device can be probed for all salient features enabling the hub to offer all your features to the user. This allows your product to be supported the day it starts shipping without waiting for the hub vendor to “support” your product thru manual coding. Note that section 7.2 of the specification has a list of mandatory command classes that are required for all products. These include Z-Wave Plus Info which helps the hub know exactly the general type of device, Association which tells the device where to send unsolicited reports, Firmware Update which enables updates in the field which is now required for the new global security initiatives.

What to do for Command Classes That Haven’t Been Implemented Yet

Not all command classes have been implemented yet. Can AI write them? Probably – let me know if you can create a working command class with AI. None of the thermostat related command classes are in the open-source repository as mentioned above. What do you do? You must implement them yourself. Ideally you should submit your implementation to the open-source repository to help the entire community. This is a pretty high-bar as you must implement every command in the command class and follow the coding rules as well as provide test code to ensure the code is bug-free (maybe bug-lite?). I’m currently implementing Geographic Location and Time command classes which I hope to Pull Request into the repository in the coming months.

The key is to copy a similar command class to use as a starting point. The first step is to implement the REGISTER_CC_V6 macro. Each existing command class has this macro, or an earlier version of it, at the bottom of the main command class file. The macro installs the command class into the Node Information Frame (NIF) and provides links to the command class handlers and other functions. The NIF is the list of command classes the device supports which the hub uses to interrogate the device to learn what it can do when first joined to a network. Next, implement the handlers that decode all the commands of a command class and return a report when a Get command is received. The command to send a frame is zaf_transport_tx() which puts the message into the FreeRTOS queue and sends it to the SDK. A callback function is called when the message is sent with a status of success or not.

Next Steps

Part 4 of the Developer’s Journey will discuss details about coding and debugging Z-Wave firmware. This is a longer blog as there is a lot to cover. I will include several screen shots and recommend tools that I find invaluable. 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.

A Z-Wave Developer’s Journey | Part 2

DrZWaveLeave a comment

This is an abbreviated version of Part 2, the full article is on the Z-Wave Alliance Web site.

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.

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.

  1. Z-Wave Core Component – Select the Z-Wave Region to match your location
    1. Max Tx Power will need customization when preparing for regulatory approval
  2. Z-Wave Version Numbers – Turn on (True) Use Application Version and enter version numbers
    1. The Minor Version MUST be incremented for OTA firmware update
  3. Z-Wave ZAF Component – Several items must be customized for your product
    1. The Manufacturer Specific ID, Product Type and Product ID are a 48-bit unique identifier for the product – basically a fingerprint
  4. Command Classes – Association CC – Recommend a single Lifeline NodeID
  5. Uncheck Installed – then install Z-Wave Debug
    1. This will uninstall Z-Wave Release which uses higher compiler optimization and the debugger is unable to accurately single step C source code
    1. Note that OTA fails when DEBUG is enabled due to code size with the lower optimization
  6. Z-Wave Log – optionally turn on more logging which will print more messages out the UART
    1. Entering vcom into all 4 debug levels will print a lot of messages
    1. Be sure to turn this OFF when getting close to a release
    1. 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.

See more details at the full blog posting on the Alliance Web Site via this link: https://z-wavealliance.org/a-z-wave-developers-journey-part-2-2/

Please comment below on this or any of the topics in the Developers Journey.

Join me at the Z-Wave Summit May 27-29 in Vienna Austria. Unplug Fest is the afternoon of the 27th which I will be coordinating. We’re not doing range testing this time around but will be demonstrating some of the main features of Z-Wave including SmartStart, Multicast, Mesh routing and more. Bring your new devices and test them with several ecosystem players to see Z-Wave interoperability in the real world.

A Z-Wave Developers Journey | Part 1

DrZWave1 Comment

The Z-Wave Alliance is funding my writing of a blog that describes how to develop a Z-Wave product. The “Journey” is a series of ten blog postings with step-by-step descriptions of how to develop a Z-Wave product from idea to volume production. The full blog posting is on the Alliance web site but here is an abbreviated version.

Introduction

A Z-Wave Developer’s Journey is a series of ten blogs on the nuts and bolts of creating and bringing to market a wireless IoT product utilizing Z-Wave. The series provides a step-by-step roadmap for an engineering team to bring their idea from the concept to a product ready for volume manufacturing. Naturally, this series can’t delve into every aspect of the process but leverages vendor training, documentation and Github to flesh out the details. The journey focuses on Z-Wave end devices but a similar process would be followed by Z-Wave controllers. One thing to note is that everything is constantly changing. The Z-Wave specification continues to evolve with new Command Classes and updates to existing ones, the vendor Software Development Kits (SDKs) have new releases every few months and new silicon chips are always being released. While the guidance shared here is relevant today, details will inevitably evolve over time, so stay engaged and enjoy the ride.

Topics

The journey begins with this blog which describes the topics to be discussed in this ten-part series. You have the opportunity to comment on these topics as each is published. Feel free to comment or reach out to me directly at DrZWave@DrZWave.blog. I continue to learn by doing and enjoy exchanging best-in-class techniques for IoT product development of both hardware and software even in “retirement”. Below is a list of planned topics though the list may morph somewhat along the way based on your feedback. Don’t be shy, comment below or send me an email.

  1. Introduction & Z-Wave Silicon Choices
  2. First Steps in Customizing Z-Wave Firmware
  3. Which Z-Wave Command Classes to Include and Why
  4. Coding and Debugging Z-Wave Firmware
  5. Firmware Hardening
  6. Z-Wave Hardware Design Best Practices
  7. Optimizing Battery Life
  8. Antennas for Z-Wave
  9. Z-Wave Regulatory Process
  10. Z-Wave Volume Manufacturing

See the Alliance blog posting for details on the available Z-Wave silicon.

How to Choose

Which Z-Wave chip should you use for your project? Of course, the answer is… depends. The main challenge with the ZG23 is the limited amount of flash and RAM. The SDK uses virtually all the available resources. If your product is fairly simple, like a door/window sensor, the ZG23 should be fine. If you are designing a thermostat or door lock, I would recommend either the ZG28 or the CZ20. If you use the Silicon Labs QFN48 you can develop using the ZG28 and then potentially reduce cost by switching to the pin compatible ZG23 if the code fits. The ZG23 could also work out if you connect an external serial flash chip for the OTA image. That frees up half of the 512KB of flash for your application but it’s still tight on RAM. The ZGM230 module is easier to manufacture since the crystal is calibrated at the factory but is limited to +14dBm transmit power thus effectively cutting the RF range in half. The choice of Silicon Labs or Trident IoT is a more nuanced choice based on the support and relationship you have with the vendor.

Feel free to comment below or contact me with your thoughts or topics you need answers!

Save the DATE! EMEA Z-Wave Unplug Fest and Summit Vienna, Austria, May 27-29.

Unplugfest 2025 Know Before You GO!

DrZWaveLeave a comment

Z-Wave UnplugFest 2025 will be held at the Lake Elsinore Skydive center in California October 28, 2025. Here are a few things you need to know before heading out to test your Z-Wave device and your BRAVERY!

Travel Plan for Z-Wave Unplugfest 2025 in Lake Elsinore California

Before You Head to Unplugfest

  1. IF YOU HAVE A Battery Powered End Device (FLiRS or Sleeping EM4):
    1. Your End Device MUST have the Listening Bit Set and thus be an Always-On device
      1. Temporarily alter your firmware to be Always-On. In SSv5 open the <project>.SLCP file, Click on Software Components, Scroll down to Z-Wave, Click on Role Types, Install Z-Wave Role Type Always On, You can switch it back later or make a copy of your project specifically for Unplugfest
      We will be using ZRADmini boards with a GPS receiver to track the exact location during Z-Wave Long Range testing. Your device does NOT have to support Geographic Location V2. Your device will be one of up to 2 other devices that will be tracked using a GPS enabled ZRADmini during RF Range Testing. However, for the maximum accuracy of RF Range testing you can add GeoLocV2 with a GPS module to your end device
    1. If your End Device can be powered via USB-C, we will have that covered, otherwise bring sufficient batteries for several hours of continuous operation
  2. Your End Device must have a visible QR code and PIN on it – all devices will be joined with S2 Authenticated or Access keys
  3. Bring your own source of POWER – Especially for Controllers
    1. We hope to have limited amount of 120VAC power from the Skydive center BUT maybe not!
    1. Better to bring your own battery inverter like a Jackery
  4. Are you brave enough to go skydiving?
    1. Signup here – Recommend you book online ahead of time!
  5. Arrive by Monday – the bus LEAVES at 9:00am SHARP Tuesday morning on a 75 minute drive
  6. Bring extra units, WSTK to reprogram units, firmware project, extra cables, batteries, tape, etc.
    1. Plan on things failing so bring extras! Unplugfest always seems to follow Murphys Law

Timeline for the 2025 Z-Wave UnplugFest

  • 8:00am – Gather at hotel Cassara lobby and board the bus at 8:45
  • 9am SHARP – bus leaves for Elsinore airport – 1+hr
  • 10:30 – setup at end of Cereal St or at Skydive Elsinore
  • 11am-3pm – RF Range Testing
    • If weather permits, JonLuke West will skydive while tracking altitude via GPS
      • If you’re brave enough, join him on a tandem jump via Skydive Elsinore!
        • Must be booked in advance which YOU must call and arrange yourself!
      • Or soar in a 17m sailplane however the plane is metal which may block RF
    • Eric will have one ZRAD as a Controller and another as an End Device with Geographic Location V2 and a GPS receiver to track the exact locations of up to 3 additional devices at a time
      • DUTs can run standard firmware (without needing GeoLocV2) and will confirm their range using fully secure Get/Report while obtaining the GPS coordinates from ZRAD
      • All devices must be joined with S2 Authenticated Security enabled and US Long Range
  • Noon Box Lunch for all who registered for Unplugfest
  • 3:00pm Testing Ends – Board Bus
  • 3:15pm SHARP – Bus departs
  • Wrap Up discussion – 3:30pm-4:30pm on the bus
    • Discussion with all attendees on findings and general discussion of Unplugfest, Z-Wave, development tools, the market, the latest football scores, and the best beer in Carlsbad
  • The Z-Wave Summit kicks off in the hotel at 5:30pm

Check out the video from the 2024 Unplugfest in Austin TX: ZWA2024AustinUnPlugFest.mp4 and DrZWave’s blog post: https://drzwave.blog/2024/05/08/z-wave-summit-2024-austin-tx/ and JonLukes 2.7mi Z-Wave Skydive: https://youtu.be/lcuyDC128cQ?si=09wVd3cDV89326wW

DEBUGPRINT Is Now ZPAL_LOG

DrZWaveLeave a comment

The 2025.6 Silicon Labs SSDK Z-Wave release changes the familiar DEBUGPRINT utility to ZPAL_LOG. A brief mention of the change is in the Important Changes for the Z-Wave 7.24.0 release however I’ll give a more detailed description of what has changed and how to use this new utility. If you’re trying to upgrade a project from an earlier SDK, this “breaking change” will make that effort more difficult as you have to switch any DPRINT statements to the new ZPAL_LOG format.

DEBUGPRINT

First a little history. The DEBUGPRINT utility came from the original early 2000s Zensys code running on the 8051 8-bit CPU. From the initial 100 series thru the 500 series, DEBUGPRINT was the ONLY debug utility we had! Even though this was the 2000s thru most of the 2010s, debugging using PRINTF was obsolete by the late 1980s – but not for Z-Wave. PRINTF would print out a short message and maybe a hex value or two and we would try to divine what was going on from these tiny details. There were no breakpoints, no ability to single step the CPU or watch RAM or registers change as the code was executing. Because sending characters out the UART would block the CPU until the UART was empty, you could only send a few characters and maybe a hex value. Sending more characters out the UART would alter the flow of the program and either mask the bug or break something else or often cause a watchdog reset! UGH. While primitive, it was all we had and we made do. DEBUGPRINT was easy to enable or disable – just #define DEBUGPRINT in the file you needed the print statements and recompile. Typically, only a few print statements were enabled at a time or the UART would spew out too much detail or messages would get mixed together making gibberish of the output.

Debugging Today

Debug is much easier with the modern ARM CM33 processor on todays Z-Wave chips. We have Single-Wire-Debug (SWD) and can set breakpoints, watchpoints, single step, view memory and peripherals. There’s even Trace where every instruction executed is logged enabling the precise flow of a program to be viewed after the trigger condition of a bug. We still have DEBUGPRINT which is handy for printing out high level messages like “eReset Reason=3′ each time the chip reboots. These messages are handy during debug and were easy to remove prior to building the final production code simply by commenting out the #define.

ZPAL_LOG

The Z-Wave Log component in a Simplicity Studio project .slcp file is installed by default in all the sample applications starting with the 7.24 release. This is good thing and a bad thing. It’s good since it’s already installed and printing messages before you’ve started modifying the code for your project. It’s bad because when you should remove this code for the final production build, we’ll get into that shortly.

General

When you Configure the Z-Wave Log component you get a lot of radio buttons to switch various features on or off. The first block “General” includes:

  • Size of the buffer (default is 96 bytes) – Leave this as-is
  • Display log level – prints 3 characters identifying Info, Debug, Warnings or Error messages
  • Display log source component – prints a number which identifes which module the print statement is from
  • Display log timestamp – prints a decimal number of ticks since reset

Enabling any of these messages slightly increases the total FLASH usage. The bigger problem is that it increases the number of characters sent out the UART potentially causing the CPU to block and thus changing the program flow. I recommend leaving these at their defaults.

The Display Log Source component would be useful IF SSv5 decoded the numeric value for you and displayed the name in the console window. Unfortunately it just prints a number which you then must manually decode by looking up the value in the enumerated type zpal_log_component in the zpal_log.h file. The trick would be to send just the numeric number out the UART (thus not taking up significant amounts of time or FLASH) and then SSv5 expanding it to the component name. I have suggested this to the SSv5 team in the past but hasn’t yet come to fruition. The source component is useful if there are several similar or even identical PRINT statements in different blocks of code to help identify where it is coming from. Also if you enable a lot of PRINT statements, it can help narrow down which block a specific message is coming from.

If you enable all 3 of these switches you get: “000000023 [I] (1) ApplicationInit eResetReason = 7”. Where the 00000023 is the timestamp; [i] is the Log Level (Info in this case) and (1) is the component which you have to then decode yourself as mentioned above (ZPAL_LOG_APP in this case) .

Output Channels

The next block is the Output Channels which can enable the four levels of messages: Debug, Info, Warning and Error messages. The default has just Info enabled with the word “vcom” entered into the Info box. I recommend enabling all four of these by entering “vcom” into all four of them. This will increase FLASH usage as the strings for all these messages are now stored on-chip.

Component Filtering

The final configuration block in the Z-Wave Log component is the Component Filtering section. This section has a bunch of radio buttons you can enable which will turn on various messages from the respective module. If you enable ALL of these, it’ll add about 10K bytes of FLASH so maybe only enable ones you think you need.

UART Blocking

The EUSART is only running at 115200 baud which makes each character take over 10 microseconds to send out the UART. This might seem fast, but when you’re transmitting long strings of characters this can seriously impact the program flow in real time. If the UART buffer fills, the code will stall and wait for more buffer space to fill (see the “while” loop in eusart_tx in sl_iostream_eusart.c). If you’re spitting out a lot of messages, the UART will fill causing the program flow to change potentially masking the bug or sending you down the wrong rathole. The baud rate is easily increased to 1mbps which will speed up the printing by 10X which helps, but you need to be aware of the amount of messages pouring out the limited speed of the UART.

Disabling ZPAL_LOG

Once debugging is complete, the next step is to compile all of these messages out of the production code. Fortunately this is easy – just remove “vcom” from all four of the Output Channels section of the Z-Wave Log component. While this removes most of the code for debug messages, the Command Line Interface (CLI) is still there and the EUSART is still used by the sample applications. When developing your own application you will typically want to remove ZPAL_LOG and the CLI as it’s not something your application needs – it is only for the Silicon Labs demos.

Conclusion

Why did silabs make this “breaking change”? I don’t have specific insights from Silicon Labs but the new format provides easily configured “levels” of logging. Is that worth a “breaking change”? I wish they’d spend more time testing the code to reduce the bugs than making a lot of file changes tweaking features that don’t really improve the developers experience. If you’re going to change an important feature, it’s also important to document it which is sorely lacking. But I hope this post helps you utilize this new feature and not be quite so frustrated when updating your project to the latest SDK.

Dreaded Flash Memory Overflow Solutions

DrZWaveLeave a comment

The EFR32ZG23 Z-Wave 800 series MCU has limited FLASH and RAM available for the application. The 800 series actually has less FLASH than the 700 series which stored the bootloader in a dedicated 16K memory. Worse, the bootloader in the 800 series has grown from 16K to 24K! Features are always being added to the SDK making it ever larger leaving less for the application. Seems like Silicon Labs needs to spend some time squeezing the code instead of constantly adding features.

Here is the typical error message when FLASH overflows:

Description	
FLASH memory overflowed !	
make: *** [makefile:114: all] Error 2
make[1]: *** [makefile:123: SwOnOff_2024120_ZG23B_GeoLoc.axf] Error 1
region `FLASH' overflowed by 92 bytes
SwOnOff_2024120_ZG23B_GeoLoc.axf section `.nvm' will not fit in region `FLASH'

We can’t create more FLASH on the chip, it has what it has. But, there’s always software we can change! By default, the project has ZAF->Z-Wave Release installed which sets the C compiler optimization to -Os which optimizes for size which is probably what we want since we’re out of FLASH. However, deep in the configuration files there is the definition for SL_BOOTLOADER_STORAGE_SIZE which changes from 196K to 180Kbytes when NDEBUG is defined. NDEBUG is defined when the Z-Wave->ZAF->Z-Wave Debug component is installed. The question of why BOOTLOADER size is being reduced by only 16K when debug is enabled is unclear to me. However, in my testing, adding the DEBUG component still results in FLASH overflowing but now by 4344 bytes! Obviously the change in Optimization from -Os to -Og (debugging) blew up the code which is expected. I enabled DEBUGPRINT to get debugging information out the UART which increased the flash usage even more.

Since I am debugging and will not be testing OTA at this stage, I don’t care how big the bootloader storage size is since I am not using it. I need more FLASH space for debugging! Simply edit the sl_storage_config.h file and change SL_BOOTLOADER_STORAGE_SIZE from 0x2C000 to 0x20000 to free up another 48K bytes:

// <o SL_BOOTLOADER_STORAGE_SIZE> Size of the bootloader storage.
// <i> Default: 0x20000
// <i> Note that this value is only being used if BOOTLOADER_STORAGE_USE_DEFAULT
// <i> is set to false. This value will control how much of the flash memory
// <i> is reserved for bootloader storage.
#if defined(NDEBUG)
#define SL_BOOTLOADER_STORAGE_SIZE  0x00030000
#else /* defined(NDEBUG) */
//#define SL_BOOTLOADER_STORAGE_SIZE  0x0002C000    - original value
#define SL_BOOTLOADER_STORAGE_SIZE  0x00020000
#endif /* defined(NDEBUG) */

Now the project fits comfortably in FLASH with plenty of left over space. However, I cannot OTA it and definitely cannot ship it in this way for production. Once I’m done debugging, I’ll have to revert back to RELEASE mode and remove DEBUGPRINT. If FLASH is overflowing that will require some additional effort to squeeze back into the available space. I would first try Link-Time-Optimization (-flto) to the C compiler but that can introduce some instability and require significant amounts of testing time. Next, try looking for code you don’t need and remove it. After that, complain to Silicon Labs they need to shrink their code! 

Ram usage       :    65532 /    65532 B (100.00 %)
Flash usage     :   446868 /   491520 B ( 90.92 %)

RAM usage is at 100% is OK because the HEAP is expanded to fill the available space. But there is very little left over for the application as any RAM usage is making the HEAP smaller. The HEAP is used for all sorts of things like temporary variables, buffers and FreeRTOS. I am very concerned that some of the bugs in Z-Wave products are due to heap overflows. Heap overflows are very difficult to reproduce and debug as they typically require several failures to happen at just the right time. Unfortunately these failures seem to happen with regularity in the real world.

Hope this helps you get back to debugging quickly. Leave me a comment below with your helpful hints that I can include in a future post.

Geographic Location Command Class – GPS Coordinates to the Centimeter

DrZWave2 Comments
Z-Wavre Long Range Heat Map

First Pass is Rarely Perfect

Geographic Location Command Class was introduced around 2014 but it appears no one ever implemented it. How do I know no one implemented it you ask? Because version 1 is not particularly useful. I asked the Z-Wave Certification manager to search the certified database and no product has ever claimed support for it. The problem with V1 is that the 16-bit coordinates limit the resolution to about two kilometers. Two kilometers is sufficient to determine the time for sunrise or sunset, but not to locate a device within a home or yard. With the arrival of Z-Wave Long Range where devices could be placed in an area as large as twelve square miles, we need a way for the device to store and report its location within a few meters or less. Thus, while the first pass (version 1) has some usefulness, with new technology (ZWLR) we have new needs and thus there is a need for a new version of Geographic Location CC. Updating a command class demonstrates the living document nature of the Z-Wave specification and how you and I can add new features to the standard!

Resolution of a Location on the Earth

The circumference of the earth is about 40,075,000 meters. There are 360 degrees of longitude so each degree is 111,319 meters. The earth isn’t a perfect spheroid but for our purposes, a sphere is close enough. In embedded systems with limited resources, we need to represent the latitude/longitude with enough bits for sufficient accuracy to meet our needs. I propose a resolution of approximately one centimeter which is certainly more than enough and currently beyond the resolution of todays (but not tomorrows) low-cost GPS receivers.

The current Z-Wave Geographic Location Command Class V1 uses 1 bit for the sign, 8 bits for the Degrees and 7 bits for the Minutes. Since the 7 bits are in minutes instead of a fraction of a degree, the 7-bit value only ranges from 0-60 which means there are actually less than 6 bits of resolution. Thus, the resolution of the current V1 is 111319m/60=1.855km. Two kilometers of resolution isn’t enough to locate a device within a single Z-Wave network.

How many bits are needed for 1 centimeter resolution?

Degree Fraction BitsResolutionComments
0111,319m1 degree=111km
155,6560m
227,830m
3 … 16…Each bit doubles the resolution
170.85m
180.42m
190.21m
200.11m
210.05m
220.03m
230.01mCentimeter resolution
GPS Coordinate Degree Fraction Bits of Resolution

The proposal is to update Geographic Location CC to V2 and make the values 32-bits to achieve roughly 1 centimeter resolution. Using only fractional degrees gives more resolution with fewer bits and is easier to compute. We need 8 bits to represent Longitude from 0 to 180 plus the sign bit for a total of 9 bits. Then another 23 bits for the fraction. Version 1 has the sign bit in the Minutes field which doesn’t make for an easy number to manipulate. We have to bit-swizzle the sign and then divide minutes by 60 to get the fraction. The proposal for V2 is a simple fixed-point fraction as shown below:

Geographic Location SET

76543210
Command Class = COMMAND_CLASS_GEOGRAPHIC_LOCATION (0x8C)
Command = GEOGRAPHIC_LOCATION_SET (0x01)
Lo SignLongitude Degree Integer[7:1]
Lo[0]Long Fraction[22:16]
Longitude Fraction[15:8]
Longitude Fraction[7:0]
La SignLatitude Degree Integer[7:1]
La[0]Lat Fraction[22:16]
Latitude Fraction[15:8]
Latitude Fraction[7:0]
Altitude[23:16] MSB
Altitude[15:8]
Altitude[7:0] LSB
Geographic Location CC V2 proposal

Longitude/Latitude

Longitude and Latitude formats are the same with a sign bit, 8 bits of integer Degree and 23 bits of fraction. The values are signed Degrees which for longitude varies from -180 to +180 and for latitude varies from -90 to +90. The rest of the bits are a fraction of a degree which yields roughly centimeter resolution.

Altitude

Altitude is a twos-complement signed 24 bit integer which yields a maximum of 83km in centimeters (more than enough!) to as much as -6,000km which is the radius of the earth. Note that altitude can be negative as the altitude is relative to sea level. Most GPS receivers will provide altitude so why not include it here in the Z-Wave standard? We need altitude because ZWLR devices could be spaced out vertically as well as horizontally.

Geographic Location GET

Geographic Location GET is the same as the existing V1.

76543210
Command Class = COMMAND_CLASS_GEOGRAPHIC_LOCATION (0x8C)
Command = GEOGRAPHIC_LOCATION_Get (0x02)

Geographic Location REPORT

76543210
Command Class = COMMAND_CLASS_GEOGRAPHIC_LOCATION (0x8C)
Command = GEOGRAPHIC_LOCATION_REPORT (0x03)
Lon SignLongitude Integer[7:1]
Lon Int[0]Long Fraction[22:16]
Longitude Fraction[15:8]
Longitude Fraction[7:0]
Lat SignLatitude Integer[7:1]
Lat Int[0]Lat Fraction[22:16]
Latitude Fraction[15:8]
Latitude Fraction[7:0]
Altitude[23:16] MSB
Altitude[15:8]
Altitude[7:0] LSB
QualROAl ValidLa ValidLo Valid
REPORT is the same as SET with the additional STATUS byte

Status Byte

The additional Status byte provides additional information about the long/lat/alt values:

Qual: From the NMEA GPS Quality Indicator: GPS receivers need a minimum of four satellites to compute the location. Thus, QUAL is the number of satellites used for the most recent computation. If more than 15 satellites are used, then the value is clamped to 15. The values 0-3 are reserved for debugging.

RO: Read Only – Long/Lat/Alt are Read-Only when set to 1. Devices with GPS receivers set this bit to indicate that the values are from an on-board sensor. SET commands are ignored. Devices without a GPS receiver clear this bit to zero and will have their location set at commissioning time typically using a phone to set the GPS coordinates.

Al Valid: The Altitude value is valid when set to 1. When cleared to 0, the Altitude value is unknown and MUST be ignored.

La & Lo Valid: Each bit signifies when the Latitude and Longitude values are valid. When cleared to zero, the Latitude or Longitude MUST be ignored.

If a SET command was sent, the Longitude, Latitude and Altitude is then considered valid and is retained thru a power cycle but will be cleared if excluded or factory reset.

GPS Receiver to Geographic Location Conversion

All GPS receivers use the NMEA 0183 standard for reporting the coordinates. The string of ASCII characters for longitude and latitude is defined to be [D]DDMM.MMM[M] where D is decimal degrees and M are the miutes. The MM.MMMM value must be divided by 60 to convert minutes into fractions of a degree.

A typical NMEA sentence looks like: 

$GPGGA,134658.00,5106.9792,N,11402.3003,W,2,09,1.0,1048.47,M,-16.27,M,08,AAAA*60

Text color matches the field: Latitude, Longitude, altitude – see the details via the NMEA link above.

Converting the values in Geographic Location CC to decimal is accomplished using code similar to: const longitude=payload.readInt32BE(0) / (1 << 23);

GitHub Repo

An implementation of the Geographic Location CC V2 is at: https://github.com/drzwave/GeographicLocationCC

The repository implements Geographic Location CC in an end-device such as the Z-Wave Alliance ZRAD project or on a Silicon Labs Devkit using a QWIIC I2C based GPS receiver like the M8Q from Sparkfun.

See the repo for more examples and details. The official Z-Wave Alliance specification update with GeoLocV2 is currently being reviewed and expected to be published in one of the 2025 releases.

Heat Map Examples

One of the drivers to create GeoLocV2 is to generate heat maps of the RF Range for testing Z-Wave Long Range. In previous Unplugfests we use a very subjective measurement of having an LED stop blinking when out of range. Often the LED would pause, but then start blinking again, then stop so it was difficult to determine the exact edge of RF range. With GeoLocV2 we can map the exact locations where the device is when it is able to make 100% error free, encrypted connection.

The Silicon Labs Works With 2024 conference produced a fantastic video (featuring DrZWave! – well, I have a supporting role) demonstrating GeoLocV2 in action on a motorcycle! Skip to minute 43:40 (about 3/4 of the way thru the video) to see the video.

Z-Wave Long Range demonstration video from Silicon Labs Works With 2024 using Geographic Location Version 2

Below is a heat map from a skydiving test that we will be producing a video in the near future. Z-Wave Long Range demonstrated 2.7 mile range – straight UP! A ZRAD was used as the controller running Z-Wave JS and a small Javascript program to extract the GeoLoc data from a commercial Z-Wave device using a PCB antenna stuffed inside a fanny pack of the jumper. This example demonstrates the need for the Altitude in the specification.

Below is a heat map with the color showing the transmit power needed to make an error free connection which ranges from -6dBm to +20dBm. The test took place in a residential neighborhood outside Boston Massachusetts where the ZRAD controller is in a wood frame building on the second floor and a ZRAD End Device was driven around the neighborhood reaching a general 500m and a maximum of over 1.4km. This demonstrates the dynamic power of Z-Wave Long Range where it saves battery power anywhere within 100 meters but can extend the range thru many obstacles to over a kilometer.

Be sure to attend the upcoming Z-Wave Unplugfest and Summit in Barcelona Spain in February 2025 or the one in Carlsbad CA in April to see GeoLocV2 in action.

Z-Wave Summit 2024 – Austin TX

DrZWave5 Comments

The Z-Wave Summit & UnPlugFest took place last week in Austin TX. If you missed it, here is a quick Recap. I organized the UnPlugFest on Tuesday which included an RF Range test down the Colorado River right in downtown Austin. The Z-Wave Alliance Reference Application Design (ZRAD) won the maximum range with a distance of 1.1miles (1.7km) which wasn’t quite line-of-sight (LOS). I produced a video of the event which you have to be a member of the Alliance to gain access. Virtually all of the other Z-Wave Long Range Devices tied in a close second place at 0.7mi (1.1km) however we had limited LOS points to test at bridges across the river. We proved that PCB antennas and shipping Z-Wave devices in a noisy RF environment can easily achieve over a kilometer of range. Note that we measured the range where we are getting 100% corruption free, fully encrypted packets at 100kbps. Obviously we could go much farther if we are just trying to get a NOP to ACK but that’s not useful even though other protocols use that as their yardstick.

The Open Source Work Group met in-person in the afternoon to work on finalizing User Code Command Class. Additional Range testing was measured inside the hotel (with concrete floors) where most devices were able to pass thru several floors. Late in the afternoon was the Fireside Chat where we aired our hope, desires and disappointments for Z-Wave. Watch for a survey coming out soon!

Tuesday evening is the network event which was hosted by Silicon Labs where all the Z-Wave personalities meet and renew friendships and business relationships.

My presentation on the Z-Wave Alliance (ZWA) Reference Application Design (ZRAD) is a preview of the soon to be released github project. There were lots of presentations on all sorts of IoT related topics. You can find the presentation on the ZWA members web site.

FUN! Electric Shuffle

After the UnPlugFest and a full day of presentations it was time to relax and join the competition at Electric Shuffle.

Summit Takeaways

This is my personal set of takeaways. Please add yours in the comments below!

  • Z-Wave is very much alive!
    • Lots of new products have been certified and more are in the pipeline
    • Most are Z-Wave Long Range
  • Z-Wave spec and Open Source Code continues to improve
  • Z-Wave Long Range is indeed Long Range!
    • Over 1mi LOS in downtown Austin – over 2mi proven in NH
  • Certification for an SDK Update is Review ONLY!
    • No need to redo the entire certification process to update the Z-Wave SDK
    • Previously a full re-cert was required ($$$!)
    • Now you can get the latest bug fixes/security patches and just file paperwork for cheap
  • Can add Z-Wave Long Range (ZWLR) to a device and keep the same FCCID
    • Can OTA devices already in the field to add ZWLR!
    • Requires working with the “right” FCC test house and FCC must be redone with the new frequencies
    • Talk to Trident for more details
  • Why is the RF range so short in the EU for many devices?
    • 500 series devices can only transmit at -1dBm (hardware limitation)
    • 700/800 can transmit at +14! More than twice the range!
    • Update those EU devices!
  • USB Zniffer firmware can capture BOTH ZWLR frequencies
    • Select US_LR_END_DEVICE for the region to get ONLY the 2 ZWLR channels (no mesh channels)
    • Select US_LR_BACKUP to get the ZWLR B channel and mesh channels
    • Select US_LR to get ZWLR A channel and mesh channels
  • Z/IP Gateway has a maintenance release expected in June but there will probably only be 1 more maintenance release before it EOLs
    • Switch to Unify or Z-Wave JS soon!

How to Build the Z-Wave Bootloaders

DrZWave6 Comments

You’ve finished designing a new PCB for your Z-Wave product and are now ready to start testing with your own custom firmware. Well, the first thing you need are bootloaders. The bootloader is a standalone application that handles upgrading the application firmware among other things. Downloading a bootloader into a Silicon Labs devkit is easy, just click on “run”. But for custom PCBs you must build it from the source code. There are two types of bootloaders needed: One for End Devices which will receive the updated firmware image over the radio, the other is for Controllers which will receive the image via the UART wires. These are similar but there are a few important differences. This post is specifically for the Z-Wave 800 series and GSDK 4.4.1. Hopefully the process will be a little easier in a future release.

End Device Bootloader – OTA

Fortunately the End Device bootloader is easy with the release of GSDK 4.4.1 (Z-Wave 7.21.1). Plug your board into a ProKit (WSTK) via the Tag-Connect connector. The WSTK should show up in Simplicity Studio v5 (SSv5) Launcher Perspective with “custom board” and the EFR32ZG23 part number on your board. Click on Detect Target if not. Ensure the Debug Mode is set to Mini (or OUT for WSTK1). Select the debug adaptor then start the New Project Wizard via File->New. Make sure the latest SDK is selected and GCC12 (not GCC10). Click on Z-Wave to filter the list and uncheck Solution Examples. Scroll down to “Bootloader – SoC Internal Storage (For Z-Wave Applications)” and select that. Click Next then rename the project to something more meaningful with the chip (ZG23A) and GSDK version (_411 for 4.1.1) for example. Build the project which should complete without error. The bootloader has a lot of security options but I recommend using the defaults. If you have a complex device and need additional code space, you can relocate the OTA buffer to an off-chip serial flash chip which will free up nearly 200K of FLASH space but no additional RAM.

Controller Bootloader – OTW

This example uses a custom PCB and the EFR32ZG23A (mid-security) chip. I start with this combination as that is what most customers will start with. Using one of the devkits causes SSv5 to automagically “know” all sorts of things about the board and what GPIOs are wired to what and what other features are available. When you pick this chip, there are zero pre-built “demos” as all of the current devkits have B (high-security) parts on them.

Start the New Project Wizard via File->New. Ensure the IDE/Toolchain is GCC12 and not GCC10. scroll down and click on the “Bootloader – NCP UART XMODEM (for Z-Wave Applications)” then click on Next. This will create a project called bootloader-storage-internal-single-zwave then append the GSDK version to that which in this case is 4.4.1 so add “ZG23A_441” to the project name to keep track of which chip and which GSDK this is for. Click on Finish then build the project. This will fail because SL_SERIAL_UART_PERIPHERAL_NO is not defined as well as several other things related to the UART.

Clearly the UART needs to be configured but a guide is needed to figure out what that might be. Plug in a Devkit and build the same project but with a different name. This project builds just fine so search for SL_SERIAL_UART_PERIPHERAL_NO. btl_uart_driver_cfg.h has a define for this for USART0. The same file in the custom project says “bootloader UART peripheral not configured”. Obviously somehow it needs to be configured. The .slcp file has Platform->Bootloader->Drivers->Bootloader UART Driver configured.

We don’t need RTS/CTS as they are not used. Configure the custom project with USART0, RX=PA09 and TX=PA08 then the project compiles. This should be the default since you MUST use a UART for XMODEM. Maybe a future release will fix this! There are other configuration items under the Bootloader Core component but generally these can remain at the defaults.

Conclusion

Bootloaders are critical to being able to field-upgrade the firmware of any Z-Wave product which is mandatory for certification. See the Bootloader Users Guide (UG489) for more details on the many options available. The process to create the Z-Wave bootloaders is a bit more complicated than it should be but I hope this guide will bring your Z-Wave product to market a little quicker. Let me know what you think by commenting below.

Team Z-Wave Development Using Git

DrZWaveLeave a comment

Silicon Labs Simplicity Studio v5 (SSv5) has a steep learning curve but once you’re up the curve it can accelerate an IoT firmware development. However, sharing the project among several engineers isn’t as straightforward as it should be. Fortunately it is actually quite easy once you know the trick which I explain below.

Step 1 – Create the Repo

Create the repository using Github or your own private server. Typically this is done via a browser which also sets various options up such as the language and the license. Once this has been created, copy the name of the repository to use in the next step.

Step 2 – Clone the Repo locally

Clone the repo onto your computer using the typical “git clone HTTPS://github.com/<gitusername>/<projectName.git>“. Choose a folder on your computer that is convenient. I recommend the folder be under the SSv5 workspace folder which will make finding it later a little easier.

Step 3 – add a .gitignore file

Create a file at the top level of the repo to ignore the files you do not need to put under source code control. Use the lines below and include any other files or folders as needed. You may want to include the .hex, .gbl, .map, and .axf files which are under the GNU* folder or copy them to another folder so you have the binary files in case building the project proves to be difficult. Note that I am NOT checking in the SDK which is huge and Silabs keeps even quite old versions on github and via their website. Thus you don’t need to keep a copy of the SDK on your local servers – but you can if your are that kind of person.

################ Silabs files to ignore #####################
# Ignore the Build Directory entirely
GNU*
# Other SSv5 files to ignore
.trash
.uceditor
.projectlinkstore
*.bak

Step 4 – Create the SSv5 Project

Create the SSv5 project within this folder. Typically this is done using the Project Wizard or selecting one of the sample applications. Be sure to locate the project within the repo folder.

Step 5 – Commit the Files

Commit the files to the repo using:

git add *
git commit -am "Initial checking"
git push

At this point you can either clone the repo into a different folder to see if it works or have a team member clone it onto their computer. Try building the project to see if there are any missing files.

Step 6 – Import the Newly Cloned Repo into SSv5

This is the tricky bit! We’re going to Import the project into SSv5 but the TRICK is to import it into the cloned repo folder. By default, SSv5 will make a COPY of the project when importing. The problem with that is that you then lose the connection to the git repo which is the whole point!

Use “File – Import” then browse to the cloned git repo folder. The project name should show up with a Simplicity Studio .sls file. Select this file by clicking on it then click Next.

Then the next screen pops up. Ensure the proper compiler is selected for the project! GCC10 or GCC12! These settings should come from the .sls so you shouldn’t need to change them.

Click on Next

THIS IS THE MOST IMPORTANT STEP! In the next screen, UNCHECK the “Use Default Location” button! Click on Browse and select the repo folder.

Click on Finish. Then check that the project builds properly.

Team members can now work collaboratively on the project and manage the check in/out and merging using standard git commands.

When the project is complete, be sure everything is checked in and the repo is clean, then in SSv5 right click on the project and select delete. But do not check the “delete project contents on disk” checkbox unless you want to also delete the local repo. This removes the project from the workspace in SSv5 but leaves the files where they are. You can clean up the files later.

The key to using git with SSv5 is to UNCHECK the Default Location button during the import. If you leave that checked, or browse to the wrong folder, SSv5 will make a COPY of all the files and you lose the connection to the git repo.