technology

A Z-Wave Developer’s Journey | Part 6

DrZWaveLeave a comment

Z-Wave Hardware Best Practices

This is an abbreviated version of the full blog on the Z-Wave Alliance website.

Scattered debug pins require a custom jig which is fragile and easily lost. Standard debug connectors are reliable and easy to replace.
Use a standard debug connector for reliable maintainable IoT Z-Wave designs

Introduction

Cost sensitive wireless smart home devices have different requirements compared to designing cell phones or laptops. The printed circuit boards (PCB) are usually only a few square inches and often only two layers. To fit inside of an electrical outlet box the entire product must be small and cost considerations require integrated microcontrollers to supply most of marketings requirements.

Basics of IoT Device Hardware

A key feature of having the engineer do the PCB design, is that the engineer can easily change the MCU pinout to solve PCB layout problems. Since both Silicon Labs and Trident IoTs Z-Wave chips can route nearly any peripheral to almost any GPIO, I often swap GPIOs while routing the PCB. Make a quick change to the schematic, reread the netlist in the layout tool and voilà, problem solved! Just remember to also change the pinout in the firmware.

I usually manually design, layout and hand-assemble prototypes. If I need to build more than five, I contract assembly out because assembly quickly becomes a huge time sink. I use the open source KiCAD electronic design software. I have contributed a few library components to the repo including the Silicon Labs ZG23 and Tridents CZ20. Many PCB vendors can directly import KiCAD files, but I prefer to send them good ol’ Gerber files to ensure I get exactly what I want. With the KiCAD files, the vendor may adjust parameters such as the solder mask clearance which results in no solder mask between the fine pitch pins of the MCU resulting in nothing but solder shorts between the tiny pins. I don’t even use the autorouter as it tends to make a mess of things with way too many vias. The routing is usually simple enough to complete in a few hours and is an enjoyable game of close-the-rats-nets.

Keeping Costs Low

The main cost driver for consumer electronics is volume. The higher the annual volume, the lower the cost for nearly every line item; PCB manufacturing, the MCU, passives, ICs, assembly, test and packaging. If the product volume isn’t at least in the 10K units/year range, then it must be unique enough to command a high price. There is a significant knee-of-the-curve at the 10k threshold.

Don’t spend too much time checking, rechecking, and reviewing the schematic and layout. The turnaround time for a new prototype PCB can be as little as overnight, and the cost of a new board is just a few dollars. Thus, it makes sense to send the board out quickly and expect to spin it once or twice to fix a couple of errors. I accidentally put the wrong size passive component on the board and only discovered the mistake when it barely fits in the footprint on the board. But that’s easily fixed and a new board is ready next week. I’ve also reversed the pinout of a connector or some other special component that gives the bottom view in the datasheet instead of the top view. Again, easily fixed and I have new boards in about a week. Be careful with GPIO selection as the 800 series has limitations on power domain and wakeup capabilities of certain pins. See my GPIO blog for more details.

Rules for low-cost IoT products

Naturally these “rules” are not absolute requirements but instead are recommendations. Engineering is the art of balancing the solution to meet the requirements in a cost-efficient manner. Often it is worthwhile to push back on a requirement if the cost is too high so don’t simply accept the requirements as non-negotiable. The first rule here is an example of these engineering tradeoffs: a four-layer PCB is more expensive, but you get better impedance (thus better RF) and likely a smaller PCB. The balance between 2 vs. 4 layers is unique for every product which means it must be engineered.

Rectangular PCBs are lower cost for your wireless Z-Wave IoT product. Use two layers instead of 4 and keep most components on one side.
Two layer rectangular PCBs are cheaper
  1. Minimize PCB layers
    1. 2 works for most Z-Wave designs
    2. 4 costs ~40% more for bare PCB but has better impedance/RF
  2. Minimize size
    1. PCB costs are computed by the square millimeter
    2. Remember the GND plane of the PCB is half of the antenna
  3. Rectangular outline
    1. Simple shapes maximizes array utilization
    2. Ideally v-scored for minimal waste
  4. 0.16-0.20mm (6-8mil) wire spacing
    1. Follow the design rules of the low-cost PCBs manufacturer
  5. Minimize special holes
    1. Slots, unusual sizes, edge features all cost $
  6. All SMT components on one side – cheaper, easier and higher yield
  7. Use 0402/0603 passive components with enough space for easy Pick&Place
    1. 0201s are the size of a grain of sand – difficult to manage
    2. Larger sizes cost more with no significant benefit
  8. Minimize manual assembly, wiring & soldering
  9. PCB cost is driven by turnaround time
    1. Waiting for an extra week saves money

PCB Design Recommendations

  • Use the Mini Simplicity debug footprint
    • Avoid custom footprints!
      • Requires fragile & expensive jig for debug/production
    • Use the standard Tag-Connect footprint & cable
      • The spring post cable has alignment pins enabling reliable programming and test
    • Ideally make the footprint visible under a battery door to allow (re)programming after the device has been inserted into the enclosure.
  • No wires under the RF traces
    • Ideally all RF traces are all on component side
    • Minimize vias on RF traces which are impedance discontinuities
    • Surround RF traces with ground vias
  • Use the vendor recommended crystals as they have been vetted by the vendor
  • Continuous Ground fills
    • Ideally have a continuous ground fill on the back for better RF
  • Add thru-hole vias to the VCOM TX signal
    • See when printfs are coming out on a scope compared to current consumption
    • Can be done by making a via larger (1mm)
  • Connect extra GPIOs to thru-hole test points
    • Accessible from both sides of the PCB
    • Easily prototype hardware changes or future features
  • Add a hardware version GPIO Resistor Divider Pair or capacitor
    • High ohms so little currentVersion 1=pulled up, Version 2=pulled down
    • Version 3 onward uses the ADC to measure voltage or a cap and a timer
  • Review the ground plane flood fills
    • Ensure current paths do not require changing layers – No antennas – No floating areas
    • Array vias between top and bottom
  • Avoid wires under the Z-Wave chip
    • The EP prevents this anyway
  • Silkscreen signal names on connectors and test points
  • All ground connections must have thermal reliefs
    • WSTK has several pins flood filled to a thru-hole connector – nearly impossible to solder!
  • Analog has special rules! Follow them!
  • Have a checklist, follow it, add new items to avoid previous mistakes
    • DRC rules must pass
    • All nets routed

See my public ZRAD github repo for detailed procedures for going from schematics to PCB layout to assembling prototypes.

Next Steps

Part 7 of the Z-Wave Developer’s Journey discusses how to debug and optimize battery life. Matching the proper type of battery to the needs of your product and achieving the desired battery life requires classic engineering skills. I’ll go over a few tips from my years of optimizing coin cell battery devices to last for years. 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 4

DrZWaveLeave a comment

Coding and Debugging Z-Wave Firmware

This is an abbreviated version of the full blog on the Z-Wave Alliance website.

Each of the silicon vendors, Silicon Labs and Trident IoT, have their own coding and debugging tools and methods. Each vendor has training on their tools which will help you up the learning curve. In this part of the journey, I present my tips and hints to help you up that steep learning curve. The first step is to watch the training videos or read the getting started guides from each vendor. They are well worth your time. While the videos are not particularly entertaining, you can skip through some parts and watch them at 1.5x which is what I did.

Silicon Labs Simplicity Studio 6

Moving from Simplicity Studio 5 to version 6 requires significant learning as the Integrated Development Environment (IDE) is now based on Microsoft’s Visual Studio Code instead of eclipse. While some parts are familiar, the IDE is markedly different and will take some getting used to. Simplicity Studio 6 (SSv6) is new and has a few wrinkles and rough spots that Silicon Labs will be smoothing out in the coming months. Don’t hesitate to file a case on the support portal or contact your Silabs FAE for help. The first step is to install SSv6 and Visual Studio (VS) Code and the Silabs extension for VS Code. Open SSv6 and you get a broad view of all the wireless protocols Silabs supports, click on Z-Wave to open the list of sample applications. Pick a sample application such as Switch On/Off which is recommended to start with. I recommend using the Copy Contents option. Using the Link SDK and Copy Project Sources option limits VS Code’s ability to find and search through files. The ProjectName.slcp file will open which is where most configuration takes place. The Software Components tab is the doorway to installing command classes or peripheral drivers. Search then install and configure command classes or APIs as needed for your application. The Pin Tool shows a graphical and tabular representation of the GPIOs. The .slpb file is the post-build editor which is where the scripts for keys and OTA file creation are configured but I recommend leaving those at their defaults. Now for the big step – in the upper right corner is the Open in VS Code. Click on that to open the Microsoft tool.

My tips and tricks for using VS Code:

  • Always press to save after editing a file!
    • SSv5 would automatically save when you click on Build, VS Code does NOT
    • It has taken me weeks for this to become a habit. I have been debugging for an hour only to realize the change I made is not in the download because I didn’t hit save
  • Copilot AI is a huge productivity improvement – learn it – use it!
    • Add a comment to any line of code by typing “//” at the end, Copilot usually produces a decent, often wordy, comment on what the code is doing
    • Start typing any function, Copilot fills in the required parameters in the right format(s)
    • Start typing “for”, “while” or “switch”, Copilot fills in much of a likely block of code and as you fill in more code, Copilot guesses what else you need – press TAB to accept the suggestion
    • Copilot hallucinates – it is not perfect so be careful and obviously check the results
  • Searching for variables or functions is different in VS Code than SSv5
    • Hovering will display some information, ask Copilot for more details
    • Right Click opens a popup with many options – recommend Find All References
    • Use the Search menu on the left instead of the bar across the top
      • In Files to Include – add “*.c,*.h” otherwise the search will include object files, .map files and other useless hits
      • Note that the search is across your entire workspace so look carefully at which project the search result is in
    • I sometimes still end up greping to find things
  • Can’t see a file in the Si Extension? Use the Explorer tab (upper left) to see all the files
  • Clean and then Build from scratch if something is not working
  • From the Silabs Extension you can flash firmware, open a terminal, open commander, and other tools
  • The gnudbg debugger is reliable
    • but I still use Segger Ozone when I hit a really squirrely problem
  • Get a new computer with at least 32GB of RAM
    • SSv6 and VSCode are memory hogs
    • I bought a new laptop with an i9 CPU and 32GB which made the experience more efficient and stable

Trident IoT

Trident takes a quite different approach to embedded programming than Silicon Labs. Building a project, compiling and flashing are done using their command line tool called “Elcap”. Elcap relies on Docker or Podman containers to make for a unified development environment regardless of the platform: Windows, Linux or Mac. Trident has a VS Code plugin called “TIDE” which makes for a familiar environment for writing and exploring the embedded code. These features make for frictionless setup as the environment is encapsulated within the container. The container environment also makes support easier as the entire environment can be recreated months or years later and reproduce the identical firmware download. They also claim that upgrading to newer SDK versions will be possible with a single command line. Silabs developers usually must rebuild their entire application starting from a fresh sample application in a newer SDK to upgrade.

Trident IoT Tips and Tricks:

  • Use the latest version of elcap – elcap about
  • elcap self doctor – checks your environment, execute this if something is not working
    • The problem is you usually need to start the Docker Desktop application
  • Append –help to any elcap command for more information
  • Trident relies on the Segger Ozone Debugger
    • VS Code integration with Ozone is expected in a future release. elcap creates a Segger .jdebug file for Ozone as part of the build process
    • In config.cmake set the following so Ozone finds all source code
      • Set(ZWDSK_CONFIG_USE_SOURCES “ON”)
      • Takes a little longer to compile but can single step ALL the code
      • Turn it off again when close to release for faster compile times
  • Use a Segger J-Link to debug your own PCB
    • The connector pinout is NOT the same as the Silabs MiniSimplicity header. The Trident devkit has a J-Link built in but does not debug external PCBs
    • The DKR-HOST can be used to debug trident based PCBs
  • The build environment is based on CMake
    • To configure the project, edit:
      • CMakeLists.txt
      • App/CMakeLists.txt
      • Configuration will be simplified in a future release
  • Complete reference firmware is available on request for several sensor types
  • Start the PCC, Zniffer or Tridents own cross-platform Z-Wave/Zigbee Sniffer from elcap

Next Steps

Part 5 of the Z-Wave Developer’s Journey discusses an often-overlooked schedule hit that in my view is absolutely critical, Firmware Hardening. Developers must keep in mind that IoT devices are often wired to mains power and may run for years without ever rebooting. Thus, the firmware must be resilient to account for impossible conditions that should never happen, but in the real world they often do. Remaining connected to the Z-Wave network and never “bricking” is critical to the success of your product and the reputation of Z-Wave. Do you have some Tips and Tricks to share? Please 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.