West Commands Every Zephyr User Should Know

All the West Commands You Should Know

West is the meta tool used by Zephyr to wrap myriad commands and tools. Zephyr calls west a Swiss army knife, and just like its namesake, there are some west commands you have available but likely have never used.

Today we’ll survey useful west commands that you may not know about. But let’s start with the obvious ones!

West commands you already know

west
west build
west flash
west debug
west attach

These are the go-to’s that should already be at the tips of your fingers. A simple west without anything else prints out usage where you’ll see all of the commands covered in the rest of the post.

The west build command will rebuild a project, but you will need to specify the board and path the first time to get things set up. Programming the board is handled by west flash, and depending on the runner, you can open a debugging session with west attach or west debug.

Installing toolchains

west sdk

One of the newer commands, west sdk will pull up information about the currently installed SDK and toolchains versions. Add the “i” flag to it (west sdk -i)  to drop into the interactive installation script. This is the same as you get when you go to the releases page, download, and run an SDK release. But it cuts out those steps.

Help me with Kconfig

west build -t menuconfig

Another one of those you should always have under your fingers, west is used to launch the ncurses-style menuconfig editor for working with Kconfig symbols. Once inside, use / to search, or navigate the menu system. You can use the ? to bring up help information on any symbol currently highlighted.

Working with Boards

west boards
west boards -n 52840

List every board definition in the Zephyr tree with a simple west boards command. However, the search option using -n is likely more useful. The command above will return (almost) every board that is built on an nRF52840 chip. I found that it does not search the SoC of the Hardware Model v2 naming scheme, so rak5010 wasn’t returned in the search even though its more verbose rak5010/nrf52840 name is .

Working with runners

west flash --context

This one is a bit obscure, but absolutely crucial when you need it. Zephyr uses the concept of runners to flash and debug targets. Using the context flag pulls up a ton of useful information. Bear with me while I paste a really long example output so we can discuss.

➜ west flash --context
-- west flash: rebuilding
ninja: no work to do.
build configuration:
  build directory: /home/mike/golioth-compile/golioth-firmware-sdk/modules/lib/golioth-firmware-sdk/build
  board: mimxrt1024_evk/mimxrt1024
  runners.yaml: /home/mike/golioth-compile/golioth-firmware-sdk/modules/lib/golioth-firmware-sdk/build/zephyr/runners.yaml
zephyr runners which support "west flash":
  blackmagicprobe, nrfutil, arc-nsim, dediprog, uf2, dfu-util, xsdb,
  teensy, ezflashcli, linkserver, nrfjprog, silabs_commander, esp32,
  spi_burn, pyocd, stm32cubeprogrammer, native, mdb-nsim, gd32isp,
  nios2, intel_adsp, canopen, openocd, probe-rs, hifive1, stm32flash,
  misc-flasher, bossac, trace32, intel_cyclonev, jlink, mdb-hw

  Note: not all may work with this board and build directory.
  Available runners are listed below.
available runners in runners.yaml:
  linkserver, jlink, pyocd
default runner in runners.yaml:
  linkserver
common runner configuration:
  - build_dir: /home/mike/golioth-compile/golioth-firmware-sdk/modules/lib/golioth-firmware-sdk/build
  - board_dir: /home/mike/golioth-compile/golioth-firmware-sdk/zephyr/boards/nxp/mimxrt1024_evk
  - elf_file: /home/mike/golioth-compile/golioth-firmware-sdk/modules/lib/golioth-firmware-sdk/build/zephyr/zephyr.elf
  - exe_file: None
  - hex_file: /home/mike/golioth-compile/golioth-firmware-sdk/modules/lib/golioth-firmware-sdk/build/zephyr/zephyr.hex
  - bin_file: /home/mike/golioth-compile/golioth-firmware-sdk/modules/lib/golioth-firmware-sdk/build/zephyr/zephyr.bin
  - uf2_file: None
  - file: None
  - file_type: FileType.OTHER
  - gdb: /home/mike/zephyr-sdk-0.17.0/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb-py
  - openocd: /home/mike/zephyr-sdk-0.17.0/sysroots/x86_64-pokysdk-linux/usr/bin/openocd
  - openocd_search: ['/home/mike/zephyr-sdk-0.17.0/sysroots/x86_64-pokysdk-linux/usr/share/openocd/scripts']
  - rtt_address: None
runner-specific context:
  linkserver capabilities:
    RunnerCaps(commands={'debugserver', 'flash', 'debug', 'attach'}, dev_id=True, flash_addr=True, erase=True, reset=False, extload=False, tool_opt=True, file=True, hide_load_files=False, rtt=False)
  linkserver options:
    -i DEV_ID, --dev-id DEV_ID
                          Device identifier. Use it to select which debugger, device, node or instance to target when multiple ones are available or connected.
    --dt-flash {Y,y,N,n,yes,no,YES,NO}
                          If 'yes', try to use flash address information from devicetree when flash addresses are unknown (e.g. when flashing a .bin)
    -f FILE, --file FILE  path to binary file
    -t FILE_TYPE, --file-type FILE_TYPE
                          type of binary file
    --elf-file FILE       Deprecated, use -f/--file instead.
    --hex-file FILE       Deprecated, use -f/--file instead.
    --bin-file FILE       Deprecated, use -f/--file instead.
    --erase, --no-erase   mass erase flash before loading, or don't. Default action depends on each specific runner.
    -O TOOL_OPT, --tool-opt TOOL_OPT
                          Option to pass on to the underlying tool used by this runner. This can be given multiple times; the resulting arguments will be given to the tool in the order they appear on the
                          command line.
    --device DEVICE       device name
    --core CORE           core of the device
    --probe PROBE         interface to use (index, or serial number, default is #1
    --tui                 if given, GDB uses -tui
    --gdb-port GDB_PORT   gdb port to open, defaults to 3333
    --semihost-port SEMIHOST_PORT
                          semihost port to open, defaults to the empty string and runs a gdb server
    --linkserver LINKSERVER
                          LinkServer executable, default is LinkServer
    --override OVERRIDE   configuration overrides as defined bylinkserver. Example: /device/memory/0/location=0xcafecafe
  linkserver arguments from runners.yaml:
    --dt-flash=y
    --device=MIMXRT1024xxxxx:MIMXRT1024-EVK
  jlink capabilities:
    RunnerCaps(commands={'debugserver', 'rtt', 'debug', 'flash', 'attach'}, dev_id=True, flash_addr=True, erase=True, reset=True, extload=False, tool_opt=True, file=True, hide_load_files=False, rtt=True)
  jlink options:
    -i DEV_ID, --dev-id DEV_ID
                          Device identifier. Use it to select the J-Link Serial Number of the device connected over USB. If the J-Link is connected over ip, the Device identifier is the ip.
    --dt-flash {Y,y,N,n,yes,no,YES,NO}
                          If 'yes', try to use flash address information from devicetree when flash addresses are unknown (e.g. when flashing a .bin)
    -f FILE, --file FILE  path to binary file
    -t FILE_TYPE, --file-type FILE_TYPE
                          type of binary file
    --elf-file FILE       Deprecated, use -f/--file instead.
    --hex-file FILE       Deprecated, use -f/--file instead.
    --bin-file FILE       Deprecated, use -f/--file instead.
    --erase, --no-erase   mass erase flash before loading, or don't. Default action depends on each specific runner.
    --reset, --no-reset   reset device after flashing, or don't. Default action depends on each specific runner.
    -O TOOL_OPT, --tool-opt TOOL_OPT
                          Additional options for JLink Commander, e.g. '-autoconnect 1'
    --rtt-address RTT_ADDRESS
                          address of RTT control block. If not supplied, it will be autodetected if possible
    --device DEVICE       device name
    --loader LOADER       specifies a loader type
    --id DEV_ID           obsolete synonym for -i/--dev-id
    --iface IFACE         interface to use, default is swd
    --speed SPEED         interface speed, default is autodetect
    --tui                 if given, GDB uses -tui
    --gdbserver GDBSERVER
                          GDB server, default is JLinkGDBServer
    --gdb-host GDB_HOST   custom gdb host, defaults to the empty string and runs a gdb server
    --gdb-port GDB_PORT   pyocd gdb port, defaults to 2331
    --commander COMMANDER
                          J-Link Commander, default is JLinkExe
    --reset-after-load, --no-reset-after-load
                          obsolete synonym for --reset/--no-reset
    --rtt-client RTT_CLIENT
                          RTT client, default is JLinkRTTClient
    --rtt-port RTT_PORT   jlink rtt port, defaults to 19021
  jlink arguments from runners.yaml:
    --dt-flash=y
    --device=MIMXRT1024xxx5A
  pyocd capabilities:
    RunnerCaps(commands={'debugserver', 'rtt', 'debug', 'flash', 'attach'}, dev_id=True, flash_addr=True, erase=True, reset=False, extload=False, tool_opt=True, file=False, hide_load_files=False, rtt=True)
  pyocd options:
    -i DEV_ID, --dev-id DEV_ID
                          Device identifier. Use it to select the probe's unique ID or substring thereof.
    --dt-flash {Y,y,N,n,yes,no,YES,NO}
                          If 'yes', try to use flash address information from devicetree when flash addresses are unknown (e.g. when flashing a .bin)
    --elf-file FILE       path to zephyr.elf
    --hex-file FILE       path to zephyr.hex
    --bin-file FILE       path to zephyr.bin
    --erase, --no-erase   mass erase flash before loading, or don't. Default action depends on each specific runner.
    -O TOOL_OPT, --tool-opt TOOL_OPT
                          Additional options for pyocd commander, e.g. '--script=user.py'
    --rtt-address RTT_ADDRESS
                          address of RTT control block. If not supplied, it will be autodetected if possible
    --target TARGET       target override
    --daparg DAPARG       Additional -da arguments to pyocd tool
    --pyocd PYOCD         path to pyocd tool, default is pyocd
    --flash-opt FLASH_OPT
                          Additional options for pyocd flash, e.g. --flash-opt="-e=chip" to chip erase
    --frequency FREQUENCY
                          SWD clock frequency in Hz
    --gdb-port GDB_PORT   pyocd gdb port, defaults to 3333
    --telnet-port TELNET_PORT
                          pyocd telnet port, defaults to 4444
    --tui                 if given, GDB uses -tui
    --board-id DEV_ID     obsolete synonym for -i/--dev-id
  pyocd arguments from runners.yaml:
    --dt-flash=y
    --target=mimxrt1024

Note: use -r RUNNER to limit information to one runner.

You can see so many helpful tidbits when running the west flash --context command after a successful build. First up, you get a list of what runners are currently supported for this board (line 17), along with all of the runners available to Zephyr (line 8). Not able to flash your chip? Perhaps the default runner (line 19) is different from the the programmer you have connected. This is the case for me with the mimxrt1024_evk board, so adding --runner jlink to all flash/attach commands is how I work with this board.

The rest of the output covers runner-specific configuration. Most of the time the defaults work great. But when you need to pass a different GDB port, or make some other tweak, this is where to go for help.

Managing Manifests

west manifest --path
west config manifest.file my-custom-manifest.yml
west manifest --resolve
west manifest --freeze

Manifests are near and dear to my heart. I think they are among the best features of the Zephyr ecosystem!

The Golioth Firmware SDK is an interesting use case for multiple distinct manifest files. We have one for projects that build on Zephyr, and another for projects that build on Nordic’s nrfConnect SDK (NCS). On workspaces installed with the Golioth SDK as the main manifest, I can switch between the two types of installations using west config manifest.file west-zephyr.yml.

When you just want to know where your manifest file is located, reach for west manifest --path. During development you might want to know what versions are being pulled in from inherited manifests. The west manifest --resolve will print that info out for you. When you’re getting to the end of the project, use west manifest --freeze to generate your manifest file with commit hashes for versions (locking in any branch names you used).

This tool goes deep

The west meta tool wraps up an incredible amount of functionality. Most of the time, you’ll find west can already do the things you want, it just takes a little digging to discover the syntax.

If west does fall short of your needs, you can always add your own custom commands. We do that here at Golioth, but Zephyr also does it to enable most of the commands mentioned above.  But that’s a story best saved for a future blog post.

/by
,

Zephyr for Hardware Engineers: Changing Boot Configurations

As a hardware engineer, Zephyr can be a bit confusing at first. I am used to tweaking registers, not layering file upon file. Today we’ll talk about how those layers and overlays can help you to configure your device differently than the default board startup sequence.

Devicetree (Re)Introduction

There are two pieces to the configuration of any board in Zephyr: KConfig and Devicetree. The former I think of like a control panel, toggling switches on and off to tell the West build system whether or not to include something. I recently did this to enable the i2c shell on a project, which pulled in code that might be unnecessary for production but helped me troubleshoot a problem. The latter (Devicetree) describes the various elements that make up your board, SoC, and architecture. As I said above, these are really layered on top of one another, which is a source of confusion for new Zephyr developers.

The topmost level of the devicetree is the board setting, and this is where I find myself making changes most often. If you include a boards/<boardname>.overlay file in your application, the build system will pull in those changes and give priority to them during the build. We often write about how we use this for swapping out a sensor, say on the i2c bus, and then add commands to control that sensor in the application code, like in main.c or app_sensors.c. Super useful!

Another key piece of knowledge for newcomers is that Zephyr has many development boards and products included in the overall repository. I find this to be critical for quickly trying out a new board and having sensible defaults for the built in Zephyr samples. Without these, I would be required to build a sample up from scratch, and the last thing I want to be doing is configuring clock trees and digging through register sheets just to blink an LED for the first time.

But with the good, comes the bad. The defaults of the board, aren’t always what we want. And in today’s example, those defaults were put there by…us!

Why not just change the board file?

When you’re in control of the entire board definition, this can make sense. But it’s not the default I would go for. Much like we won’t dive down into the SDK and change some fundamental aspect of the RTOS or a plugin, I wouldn’t normally go and change the board file. It changes the behavior on your computer for your future self and also it might not be tracked in your application’s repo, which could cause issues when building on different systems.

An Example in Action

For this example we’re looking at the Aludel Elixir board running the Reference Design Template. For the RD Template we employ a separate golioth zephyr boards repository called out in the west manifest of the Template. What this means in practice is we control an ‘official’ copy of the Zephyr board files for this hardware we make (a useful tip for your organization’s needs). In the aludel_elixir_common.dtsi file you can see that we call out the behavior of the 3v3 and 5v regulators onboard. This was the subject of the post about Enabling Power Regulators at Boot.

Well, guess who changed his mind? (me)

Now that I want to not enable the regulators at boot. Normally, this would be a simple overlay for a characteristic, say the delay times:

&reg_mikrobus_3v3 {
    startup-delay-us = <5000>;    /* 5ms - adjust as needed */
    off-on-delay-us = <5000>;     /* 5ms - adjust as needed */
};

But in the case of regulator-boot-on, it’s simply a property that is included or not, so there’s no way to set it to true or false. Instead, I need to delete it entirely. In my overlay, it would look like this:

&reg_mikrobus_3v3 {
    /delete-property/ regulator-boot-on;
};

Now when I build with west, the board won’t enable that regulator automatically, but I’ll still be able to configure it during runtime. This is exactly what we did using the Golioth Settings service in our recent Joulescope demo, which happened to be the genesis of this article/topic.

Deletion can also happen at the node level. This occurs when you want to change the behavior or the existence of some element of your configuration. For instance, say I wanted to change the button configuration for the mode_button in the Aludel Elixir board file:

/* Replace a button with different GPIO configuration */
/delete-node/ &mode_button;
mode_button: mode-button {
    gpios = <&gpio0 12 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>;
    /* additional properties */
};

This would allow me to keep the tooling in the rest of my code but potentially target a different behavior of that particular button. Say some irresponsible hardware engineer ripped a trace off the board and the only setup that would work after repairing it requires a new pin configuration; that would never happen with me, though, right?

Learning to climb the (Device)tree

Despite my trepidation about configuring the devicetree for a project, it really enables a lot of configuration tweaks, which suits the needs of hardware engineers everywhere. Learning how to modify your devicetree overlays to enable new capabilities will unlock the ability to prototype new parts at a moment’s notice. When you’re ready to send that data to the cloud, simply pop on the Golioth Firmware SDK and send some data through friendly device-side APIs. If you get stuck, we’re always happy to help over on the Golioth Forum. Happy hacking!

/by

Use Zephyr SoC config files to streamline hardware types

A computer chip labelled SoC has five arrows pointing to five different circuit boards

Zephyr’s inheritance scheme for configuration (and Devicetree) is pretty slick. The RTOS already has everything set up–from the System on Chip (SoC), to the board definition–so that you just need to add a config and overlay file to your application. Boards inherit almost everything from upstream definitions, but these files make tweaks for your specific use. Did you know that you can target the SoC itself in your application? Today, let’s take a look at how to use an application socs folder to configure multiple boards that use the same processor.

Example: Golioth Reference Design Template

Golioth’s Reference Designs are open source applications you can start from when building out your IoT devices. They are based on the Reference Design Template which supports three different boards that all use the nRF9160 cellular modem.

Up to this point we’ve copied the network configuration into separate .conf files for all three boards in the boards directory of the application. Here’s what that file tree looks like:

boards
├── aludel_elixir_nrf9160_ns.conf
├── aludel_elixir_nrf9160_ns.overlay
├── aludel_mini_nrf9160_ns.conf
├── aludel_mini_nrf9160_ns.overlay
├── nrf9160dk_nrf9160_ns.conf
└── nrf9160dk_nrf9160_ns.overlay

Without focusing on the details, a visual comparison of these files shows that most of the settings are the same for all three configurations.

Three configuration files shown side by side to visually compare the similarities

We can combine the SOC-based common configuration from all three of these boards into a single file. Most likely we will still a files to configure each variant, but they will only have a few lines in them containing configuration specific to that board type.

Determining the common SOC

If you’ve kept up with recent developments in Zephyr you know that hardware model v2 was adopted this year with the release of Zephyr v3.7.0. This made a change in device names so that they take the following format:

  • aludel_elixir/ns
  • aludel_mini/nrf9160/ns
  • nrf9160dk/nrf9160/ns

In this example, we see three different pieces of information separated by forward slashes: board name, SoC, and variant. There are a few other things that could be found in your board name, but let’s focus just on these.

For two of the boards, the nRF9160 is clearly shown in the SoC portion of the board name. However, the Aludel Elixir doesn’t include an SoC. Why is that?

The Elixir board is only built for the nRF9160 with no other SoCs in mind, so it’s been omitted from the board name. However, if you look in the custom board definition you’ll see that the board.yml file defines the upstream SoC:

board:
  name: aludel_elixir
  vendor: golioth
  revision:
    format: letter
    default: B
    exact: true
    revisions:
    - name: A
    - name: B
  socs:
    - name: nrf9160
      variants:
        - name: ns

Now that we know our common SoC, let’s move the common configuration to a file targeting that chip.

Target your SoC in an application-level configuration file

Configuration for an SoC is basically the same approach for boards. Just create a configuration file and place it in an socs directory at the root of your application. The west build system will give preference to your project version.

In this example, we create socs/nrf9160_ns.conf which also targets the ns variant that is used by all three boards.

boards
├── aludel_elixir_ns.conf
├── aludel_elixir_ns.overlay
├── aludel_mini_nrf9160_ns.conf
├── aludel_mini_nrf9160_ns.overlay
├── nrf9160dk_nrf9160_ns.conf
└── nrf9160dk_nrf9160_ns.overlay
socs
└── nrf9160_ns.conf

I moved all of the networking settings common to all three boards to the SoC configuration file. Seeing the change is jarring when we once again view the board config files side by side.

Side by side display of three different Zephyr board configuration files. Each has only one or two lines in them.

Using this approach, it is easy to immediately know what is different about each of the boards.

Benefits of common configuration

When the same configuration is copied to multiple board files, you’re bound to get out of sync and make errors. In fact, while writing this article I discovered a vestigial configuration in the config file for the Aludel Elixir.

When we converted our Golioth Ostentus code for use as a Zephyr driver module, I forgot to remove the library Kconfig symbol. It’s fine that it’s still there, but whenever there is an Ostentus node in the Devicetree overlay that library will be automatically selected so it doesn’t need to be in the board config. I didn’t notice it before. Now it’s obvious since the “noise” of the common network config code has been moved to the socs folder.

Give this approach a try with your own applications. It is certainly a lot easier to manage as you make updates for new versions of Zephyr.

/by
,

One more Zephyr training for 2024 (December 4th)

Golioth wants to make embedded engineers into better IoT engineers. That’s why we do a training where we not only show people how Zephyr works, but also how they can connect a device to the cloud and immediately get the benefit of streaming data, pipelines, Over-The-Air (OTA) updates, settings, Remote Procedure Calls (RPCs), and more.

After another successful year of Zephyr training, we will be holding our final training of 2024 on December 4th. Sign up today!

Changes over time

As Zephyr goes, so goes the Golioth Firmware SDK. Meaning, we are always updating our helper libraries and Zephyr implementation when new features are ready in the ecosystem. The latest changes from Zephyr 3.7 and NCS 2.7 have been incorporated into the Golioth SDK and are now part of the training as well. Not a lot has changed for our beginner content, but you’ll see things like the new board format while you’re compiling Zephyr programs.

By attending our upcoming training, you’ll gain hands-on experience with the latest version of our SDK and learn best practices for Zephyr development directly from the Golioth team. The training will cover topics such as:

Whether you’re new to Zephyr or an experienced embedded developer, this training will equip you with valuable skills and knowledge to build robust, secure, and scalable IoT solutions.

What’s Next?

As the winter begins in the northern hemisphere, many people find themselves inside with more time on their hands. Taking the Golioth training will unlock your Zephyr skills but also will have you on the path to becoming a better IoT developer. Use the same boards and underlying tools to build out your next IoT project or even utilize our Follow Along Hardware designs to replicate one of our many Reference Designs. As your data gets more and more complex, you can push that data through Pipelines to our variety of services, including many of our AI destinations for high complexity processing.

The best way to get started is to sign up for training today…we’ll see you on December 4th!

/by
, ,

Improve Electronic Design with Module Abstraction Layers

What if you kept the “core” or the “essence” of a board the same throughout your designs and only changed the peripherals? You could build a range of products that had similar processing capabilities, but might be completely different products. By defining an abstraction layer at the edge of the core module you design, it’s possible to achieve efficiencies for your variety of products, including when those products are manufactured over time.

The above video is a talk given at the Zephyr meetup hosted by NXP at Embedded World North America in October of 2024. I focus on modular hardware design for scalability and adaptability. The Drachm (pronounced “dram”) module is something we have been regularly streaming on YouTube. This talk describes some of the motivations, the challenges of unconstrained designs, and how to build modular systems that take advantage of Zephyr RTOS capabilities.

Many SKUs, One Core

The Drachm module was conceived to be an extension of the Aludel Platform. We currently target a range of different verticals and end-applications with Golioth Reference Designs. But these are somewhat bulky: made to accept MikroBus Click boards, the case measures roughly 80 x 80 x 40 mm. What if we want to go smaller, but not re-design the board every time we have a new product idea?

The Drachm module was meant to achieve this on multiple fronts. The castellated edge design would allow us to have a standard offering that covers a range of peripheral we want to hook up to the core module. But the module itself can change as well. The different versions of the Drachm module offer different capabilities of communication, processing power, and peripheral access on the underlying silicon. As in many modular systems, we trade off flexibility for an overall reduced feature set.

The Challenge of Hardware Changes

Modularity at the module connector edge benefits long term manufacturing as well. Building scalable IoT hardware requires constant adaptability. Component shortages, changing device requirements, and new tech trends demand flexible designs. Traditional methods, such as swapping processors or upgrading communications modules, can be tedious and impractical without a modular system.

How it works in Zephyr 

This talk built on top of the article we published about abstract hardware interfaces in Zephyr. The key change is how we think of each component of the design. The module is being mounted to a carrier board, so it seems like a component of the carrier board’s BOM and software system. But in fact, we need to think about the carrier board as a “shield” (in Zephyr/Arduino) parlance, and instead map pins based on how we define the module edge (castellated pins). See the linked article on how to use predefined node labels and GPIO nexus nodes to achieve those ends.

Another key piece is that each module variant would need to maintain its own board files (Devicetree and Kconfig) to match up the pins on the castellated edge connection to the silicon onboard. The “analog input 1” pin on the drachm-1 variant (nRF9151 + ESP32-C3) would have a different mapping than the drachm-2 variant (nRF52480 + BG77), but to the parts on the shield / carrier board, it’d be all the same, since they only interface via the “analog input 1” nomenclature.

How it fits with Golioth

Golioth works great with customized hardware, which is subject to the harsh realities of sourcing. Engineers who need to redesign their hardware to upgrade or even just keep their production line running don’t want to re-do every aspect of their design, including firmware and cloud software. That’s why engineers are increasingly choosing Zephyr to target many hardware SKUs and why they’re choosing Golioth to help create a seamless experience for those variety of targets.

Using Golioth’s features like Blueprints, Tags, and our new OTA Cohorts capability an engineer could deliver different main firmware updates to boards using drachm-1 or drachm-n modules, but still have a consistent set of AI models being delivered to all eligible units. Golioth can also help to target different cohorts in your fleet to ensure the right updates are going to the right devices in the field.

Want to create a more resilient fleet? We can help! Our Solutions Engineering team can help to introduce more modularity and have a robust OTA strategy for your fleet. If you’re interested in doing it yourself but you’d like to talk through the options with Golioth team members, head over to our forum to start a conversation there.

Slides

Golioth-Module-Abstraction-Layers-Zephyr-Meetup-Oct-9th-2024
/by

How to Publish a Summary to GitHub Actions for Zephyr/Pytest runs

How to publish GitHub Actions summaries

Automated testing is core to maintaining a stable codebase. But running the tests isn’t enough. You also need to get useful information from the outcome. The Golioth Firmware SDK is now running 530 tests for each PR/merge, and recently we added a summary to the GitHub action that helps to quickly review and discover the cause of failures. This uses a combination of pytest (with or without Zephyr’s twister test runner), some Linux command line magic, and an off-the-shelf GitHub summary Action.

Why summaries are helpful

A table with a different hardware device in each row and columns for passed, failed, skipped, and time

Test summary shown on GitHub Actions page

From this summary you can pretty quickly figure out if failures are grouped around a particular type of hardware, or across the board. Clicking the name of a dev board jumps to another table summarizing the outcomes.

A table with test names in each row and columns for passed, failed, skipped, and time

JUnit XML board summary

Reviewing the summary for the mimxrt1024_evk board, we can see that six test suites were run, with one test in the “ota” suite failing. Clicking that test suite name jumps to the block under the table that shows the error. In this case, we test all possible OTA reason and state codes the device can send to the server. This test failed because there is a latency issue between the device sending the code and the test reading it from the server.

While this doesn’t show everything you might want to know, it’s enough to decide if you need to dig further or if this is just a fleeting issue.

It’s worth noting that we also use Allure Reports (here is the latest for our main branch) to track our automated tests. This provides quite a bit more information, like historic pass/fail reporting. I’ll write a future post to cover how we added those reports to our CI.

Generating test summaries

Today we’re discussing test summaries using JUnit XML reports. Pytest already includes report generation for JUnit XML which makes it a snap to add to your existing tests. Browsing through pytest --help we see a simple flag will generate the report.

--junit-xml=path      Create junit-xml style report file at given path
--junit-prefix=str    Prepend prefix to classnames in junit-xml output

For our testing, we simply added a name for the summary file. Here’s an example using pytest directly:

pytest --rootdir . tests/hil/tests/$test      \
  --some-other-flags-here                     \
  --junitxml=summary/hil-linux-${test}.xml

If you use Zephyr, running twister with pytest already automatically produces JUnit XML formatted test reports at twister-out/twister_suite_report.xml.

Gathering and post-processing reports

Gathering up Twister-generated reports is pretty easy since Twister already batches reports into suites that are uniquely named by test. Since we’re running matrix tests, we give the files a unique name and store them in a summary/ folder in order to use the artifact-upload action later.

- name: Prepare CI report summary
  if: always()
  run: |
    rm -rf summary
    mkdir summary
    cp twister-out/twister_suite_report.xml summary/samples-zephyr-${{ inputs.hil_board }}.xml

On the other hand, the integration tests we run using pytest directly require a bit more post-processing. Since those generate individual suites, a bit of xml hacking is necessary to group them by the board used in the test run.

- name: Prepare summary
  if: always()
  shell: bash
  run: |
    sudo apt install -y xml-twig-tools
    xml_grep \
      --pretty_print indented \
      --wrap testsuites \
      --descr '' \
      --cond "testsuite" \
      summary/*.xml \
      > combined.xml
    mv combined.xml summary/hil-zephyr-${{ inputs.hil_board }}.xml

This step installs the xml-twig-tools package so that we have access to xml_grep. This magical Linux tool is able to match xml summary output filename patterns, unwrapping the testsuites item in each and rewrapping them all into one testsuites entry in a new file. This way we get a summary entry for each board instead of individual entries for every suite that a board runs.

As noted before, we use the upload-artifact action to upload all of these XML files for summarization at the end of the CI run.

Publish the comprehensive summary

The final step is to download all the XML files we’ve collected and publish a summary. I found the test-reporting action is excellent for this. We use a trigger at the end of our test run to handle the summary.

publish_summary:
  needs:
    - hil_sample_esp-idf
    - hil_sample_zephyr
    - hil_sample_zephyr_nsim_summary
    - hil_test_esp-idf
    - hil_test_linux
    - hil_test_zephyr
    - hil_test_zephyr_nsim_summary
  if: always()
  uses: ./.github/workflows/reports-summary-publish.yml

Note that this uses the needs property to ensure all of the tests running in parallel finish before trying to generate the summary.

name: Publish Summary of all test to Checks section

on:
  workflow_call:

jobs:
  publish-test-summaries:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Gather summaries
      uses: actions/download-artifact@v4
      with:
        path: summary
        pattern: ci-summary-*
        merge-multiple: true

    - name: Test Report
      uses: phoenix-actions/test-reporting@v15
      if: success() || failure()
      with:
        name: Firmware Test Summary
        path: summary/*.xml
        reporter: java-junit
        output-to: step-summary

Finally, the job responsible for publishing the test summary runs. Each different pytest job uploaded its JUnit XML summary files with the ci-summary- prefix, which is used now to download and merge all files into a summary directory. The test-reporting action is then called with a path pattern to locate those files. The summary is automatically added to the bottom of the GitHub actions summary page.

One note on visibility with this GitHub action: we added the output-to: step-summary after first implementing this system. Ideally, these summaries should be available as their own line item on the “checks” tab of a GitHub pull request. But in practice we found they got lumped in as a step on a random job often unrelated to the HIL tests. Outputting to the step-summary ensures we always know how to find them. Go to the HIL Action page and scrolling down past the job/step graph.

Making continuous integration more useful

There’s a lot that can go wrong in these types of integration tests. We rely on the build, the programmer, the device, the network connection (cellular, WiFi, and Ethernet), the device-to-cloud connection, and the test-runner to cloud API to all work flawlessly for these tests to pass. When they don’t, we need to know where to look for trouble and how to analyze the root cause.

Adding this summary has made it much easier to glean useful knowledge from hundreds of tests. The next installment of our hardware testing series will cover using Allure Reports to add more context to why and how often tests are failing. Until then, check our our guide on using pytest for hardware testing and our series on setting up your own Hardware-in-the-Loop (HIL) tests.

/by
, ,

Turn Off Subsystems Remotely To Reduce Power Usage with Golioth and Joulescope

As we previously wrote about, we attended the first Embedded World North America, held in Austin, Texas on October 8-10th, 2024. Part of our time there was to showcase Golioth’s Cloud + low power capabilities at the Joulescope booth. In this post and video, we’ll explain how to trigger different low power modes and how we measured the output.

Goals for the demo

When we were invited to showcase alongside Joulescope, I knew I wanted to be able to turn off elements of the PCB that I believed consumed power. This meant two things:

  1. Reviewing how Golioth can trigger actions from the cloud
  2. Calling the appropriate APIs from Zephyr

The first part I have done many times before. I targeted using Remote Procedure Calls (RPCs) and Settings to push information to the device. However, I could have also used LightDB State. Each has their place in different IoT setups, but as I’ll explain later, Settings seemed to work best for low power contexts. I wrote a Guide on how to add a new setting to a Golioth project a couple days ago.

All of the code mentioned here is targeted at our Aludel Elixir board. The basis for the code is our Reference Design Template, which also targets the nRF9160-DK, but that is off-the-shelf hardware that already has the kinks figured out (thanks Nordic!), so there was less interesting stuff I wanted to do. I will try to target that hardware in a future post as well.

Calling APIs to trigger lower power behavior

As you can see in the Golioth Joulescope demo repo on GitHub, the APIs we call are captive in app_rpc.c and app_settings.c, since that’s where we triggered these actions. I created two new RPCs to turn on rails and see what happened. The most extreme was the 3V3 rail, which controls the sensor + WiFi section of the board using a “downstream” power switch. You can see in the video that I trigger this and the power draw goes up nearly 5x. I also was able to use the same logic for the 5V rail. Both of these utilized the “Regulator” subsystem in Zephyr. I needed to modify the device tree using an overlay file to make sure these two rails were not turned on by default (an article for another day, basically the opposite behavior of this article). I triggered the behavior using these API calls:

I also wanted to trigger less frequent communication with the cloud, simulating a “sleepy device”. For this, I leaned on eDRX or Extended Discontinuous Reception. I had been calling the API using an RPC, but it wasn’t super optimized for low power modes. For instance, if I have eDRX mode enabled, I won’t be checking into the tower all that often; if I call the RPC to disable eDRX, there’s a chance the RPC will timeout in our 10 second window. Interestingly, we figured out that the first call will get cached at the tower (after a 10 second timeout) and the second will often return as a failure. Either way, it’s not a super reliable way to both send a command to a device and ensure it’s properly been received (nor when it has been received).

Instead, I moved the eDRX to use the Golioth Settings Subsystem. This worked great because the change in setting is transmitted to the device and it will send a callback to the server whenever it has been received. This is purpose built for asynchronous operation in low power states. Until the server receives the GOLIOTH_SETTINGS_SUCCESS enum back from the device, the Console will show that the device as “Synchronized” or “Out of sync”. Now whenever the device in eDRX mode is checking back in with the tower, it will see that an update is available and will do the synchronization.

Other modes we enabled

In addition to triggering different APIs remotely, I also set up the board to be in a lower power state to start with. This included turning off a good portion of the peripherals that would draw power. I followed Marko’s article for optimizing power on nRF9160 boards.

I had moved the shell output from UART0 to UART1 on the Elixir board (utilizing the MikroBus headers and plugging in a USB to Serial converter) because I was not using the USB to serial chip. I didn’t want to have the 5V from the USB interfering with the measurement, nor did I want to have that chip (CP2102) siphoning power from the rest of the board unknowingly. Even after all the work that I did the move over to using UART1, it was a pretty large power hog (<500 uA – 1 mA) because it’s always listening for commands. Instead, I relied on the Golioth Logging Subsystem, so I could see what was happening on the cloud. Since we were sending on an infrequent basis, adding in a couple of logs didn’t add much to the overall power when the device woke up from “sleepy mode”. If they did, I could always turn down the logging level using our standard set_log_level RPC in the Reference Design Template. See the demo video above for more detail.

How the measurement works

The Joulescope is a great tool for measuring low current applications. It has a 1 nA resolution, but is accurate to around 30 nA out of the box (way more accuracy than I need, sad to say); it also has super fast range switching, so catching spikes during RF transmissions are captured as well. You can see different modes activated in the demo that we shot with Matt Liberty at Embedded World North America.

In this setup, we have an off-the-shelf power supply that is simulating the Lithium-Ion battery we normally have plugged in. Then we use the Joulescope to measure the voltage and current as we flow current through the 2 mm JST battery connector on the Elixir board. We’re able to capture peaks and sleep currents of the design in different modes. See the video above for live views.

Power monitoring as a troubleshooting tool

One interesting behavior is the NAT timeout that Dan mentioned last week. I had been playing around with different KConfig settings, trying longer and longer keep alives and timeouts. With Dan’s help, we narrowed in on the 2 minute mark as a timeout, as explained in the “Configuring the Golioth Firmware SDK for Sleepy Devices”. Seeing the device using outsized amounts of current despite us having Connection ID enabled helped us narrow in on different parts of the system. In that case it was the NAT for our MVNO, and the fact that Connection ID wasn’t configured correctly on my project. Once we pushed a change for the Connection ID code, we were able to push the sleepiness of the device even further out. Connection ID also obviates the need to worry about NAT timeout for any particular MVNO, which means the Golioth SDK is helping to standardize offerings from different carriers.

Future Improvements

The cool thing about this kind of activity/demo is that it allows us to isolate and measure the power impact of each action. That means we can assign a “cost” to things like:

  • Doing an OTA update (including pushing out various artifacts using Cohorts)
  • Sending single log messages
  • Sending single Stream messages to push to different services using Pipelines
  • Connecting to the tower and the value/cost of ConnectionID

As I mentioned above, I’d also love to target some of this behavior directly at the nRF9160-DK and other development boards. It can be useful to be able to remotely trigger lower power modes, but it’s often tied directly to the capabilities of boards.

We really enjoyed optimizing for lower and lower power and will be writing more about this topic in the future. If you have suggestions, please let us know on the forum. If you want help getting your IoT device to lower and lower current levels, please get in touch with Golioth Solutions.

/by
,

Zephyr: What modules should you add to a manifest allow list?

Zephyr has all of the bells and whistles. Your project only needs a handful of them. But which handful? To be fair, you can build with every possible module in your local tree and only the necessary bits will be pulled in. But wouldn’t it be nice to know exactly which modules need to be added to a manifest allow list? Answer that question and your users won’t be stuck cloning tons of unnecessary files. That could save time on each build, which really adds up over the course of a project’s life.

The west meta-tool used by Zephyr includes a package management system based on manifest files, often called west.yml. Part of the power of this system is that manifest files may inherit other manifest files. The downside to this is that you may be cloning a large number of packages your project will never use. Limit this by using an allow-list in your manifest. But what packages do you need to add to your allow list?

There is no answer to this question

Let’s be up-front about this: there is no definitive answer to this question.

Your project needs to allow all of the modules it uses. Sometimes that means modules that are enabled for some builds and disabled for others. For instance, the Golioth Firmware SDK includes example apps that will build for Espressif, Nordic, and NXP processors. Each have their own HAL but only one of them is used in any given build. You can’t really programmatically generate a modules list in a case like this; you just need to know these packages are needed, even if currently not in the build.

Even without an automated tool, I’ve had to answer this question for myself and I have some pointers on how to approach the problem.

The low-hanging fruit: check your build directory

The first thing you need to do is make sure your project builds without an allow list. That all files inherited from Zephyr or from NCS (Nordic’s Zephyr-based nRF Connect SDK) will be included from the build.

manifest:
  projects:
    - name: zephyr
      revision: v3.7.0
      url: https://github.com/zephyrproject-rtos/zephyr  
      west-commands: scripts/west-commands.yml
      import: true

This manifest will include dozens of modules available from the upstream Zephyr repository. There isn’t actually anything wrong with that. You clone the modules once and they live on your hard drive. But, it does take a long time to clone all of them and it will occupy several gigabytes of space. And it’s a good practice to know exactly which packages are actually in use. So let’s try to limit what is cloned in the future.

Directory listing with a few dozen Zephyr modules names shown

The build/modules directory from a Zephyr app

Above is a listing of the build/modules directory from a Zephyr application. All of these modules were scanned during the build process, but almost none of them have any object files that will be used in the build.

├── hal_rpi_pico 
│   ├── CMakeFiles 
│   └── cmake_install.cmake 
├── hal_silabs 
│   ├── CMakeFiles 
│   └── cmake_install.cmake 
├── hal_st 
│   ├── CMakeFiles 
│   └── cmake_install.cmake 
├── hal_telink 
│   ├── CMakeFiles 
│   └── cmake_install.cmake

In fact, we can use this to help us find the modules that are actually at work in a project. Here’s a one-liner you can run from the build/modules directory to get a list of modules we know are needed for this build:

➜ find . -type f -not -name "cmake_install.cmake" | cut -d/ -f2 | uniq
mbedtls
golioth-firmware-sdk
zcbor
hal_nxp

Let’s add this these modules to an allow-list and move to the next step.

manifest:
  projects:
    - name: zephyr
      revision: v3.7.0
      url: https://github.com/zephyrproject-rtos/zephyr
      west-commands: scripts/west-commands.yml
      import:
        name-allowlist:
          - mbedtls
          - zcbor
          - hal_nxp

The trial-and-error step

Okay, the easy part is behind us. Now it’s time to figure things out the hard way. Begin by removing your module sources. These are usually in a modules directory that is a sibling of the zephyr directory where the Zephyr tree is stored. Check carefully that you do not have any uncommitted changes in these modules before removing them from your local storage. (I’ve learned this the hard way.)

Next, add an allow-list with the modules we found in the previous section. Run west update to clone the modules. This should happen rather quickly as we’ve greatly narrowed down what will be checked out. Try to build your application. If it fails, we need to divine which module was missing from the build and add that to the allow-list.

warning: HAS_CMSIS_CORE (defined at modules/cmsis/Kconfig:7) has direct dependencies 0 with value n, but is currently being y-selected by the following symbols:
 - CPU_CORTEX_M (defined at arch/arm/core/Kconfig:6), with value y, direct dependencies ARM (value: y), and select condition ARM (value: y)

Part the build error is pointing to a modules/cmsis. If you look in the west.yml from the Zephyr tree you’ll see there is indeed a module named cmsis. We can add to our allow list, run `west update`, and then rebuild.

Guess what? That was it… the project now builds! Here’s what my entire manifest looks like:

manifest:
  projects:
    - name: zephyr
      revision: v3.7.0
      url: https://github.com/zephyrproject-rtos/zephyr
      west-commands: scripts/west-commands.yml
      import:
        name-allowlist:
          - mbedtls
          - zcbor
          - hal_nxp
          - cmsis

  self:
    path: modules/lib/golioth-firmware-sdk
    west-commands: scripts/west-commands.yml
    userdata:
      patches_dirs:
        - patches/west-zephyr

Note that the golioth-firrmware-sdk was one of the modules our search of the build directory turned up. But since that module is being added explicitly in this manifest file, it doesn’t need to be on the allow-list for the inherited Zephyr manifest.

Take control of your manifest with allow lists

Knowing exactly what libraries are being used in your build is part of good project management. Since manifest files let you target libraries and modules with version tags or commit hashes, this locks your project to a known-working state. I’m a huge advocate of this and gave an entire talk about Zephyr manifest files at the Embedded Open Source Summit.

Limiting your manifest files to libraries you are explicitly using helps you understand when upstream dependencies change. It may be a bit of a hassle to go through this process the first time, but doing so is a basic form of vetting your build and your product will be better for it.

/by
,

Find us at Embedded World North America 2024

We love getting out into the real world and meeting Golioth users (and future users!). We’ll be hitting the road once again October 8-10th for the inaugural Embedded World North America! The popular conference, regularly held in Nuremberg in the spring, is rolling into Texas next week for an autumn, US-based version of the conference. Members of our Operations Team and Developer Relations Team will be on-site to discuss Golioth and check out the latest and greatest work from our partner companies.

Low power demo

I (Chris) will be showcasing a demo and helping out at the Joulescope booth, utilizing the JS220 to measure low power on our open source Aludel Elixir board. We’ll show different power modes, enabled over a cellular connection triggered from the Golioth Console. We’re able to turn different things on and off and see how it impacts current draw live. In a true meta capability, we can even see how much power it takes to send the command to use less power!

Joulescope is a favorite of our customers for measuring low power modes with high dynamic range. Stop by booth #1723 in the Austin convention center to see the Joulescope and the Golioth demos live.

The Joulescope JS220 that will be featured in the Golioth demo

Other events

As with any conference, there are night time events we like to take part in as well. We’d love to see you at some of these gatherings!

  • IoT Stars – This is a popular after-hours event at Embedded World DE, as well as at Mobile World Congress. Laurens and Marc put together a technical program and have a networking/social hour.
  • Zephyr meetup at NXP – I (Chris) will be speaking at this meetup about abstraction at the module layer of a design and how we have been creating the Drachm (“dram”) module on hardware livestreams.

See you there!

Just like any in-person event, we love the opportunity to catch up with partners, clients, and new contacts. If you have a project you need help with, we’re happy to discuss how Golioth Solutions can help you get off the ground, or how you can take Golioth for a spin for your next IoT project. Please get in touch if you’d like to meet during the conference.

/by

Zephyr for Hardware Engineers: GPIO

We’re huge fans of Zephyr around here. We have been targeting the popular RTOS and Ecosystem since the start of Golioth, including our latest Firmware SDK release (0.15.0). And while I’ve been here a good chunk of that time, my background is in hardware and I still struggle with some simple things in Zephyr. So I thought I’d write about one of them.

Let’s start with a gripe: There is no “GPIO” example in Zephyr.

What’s that, you say? There’s a blinky example? That’s correct! The blinky example is the canonical starting point for all Zephyr dev boards and is arguably one of the simplest samples. And this does indeed utilize GPIO to turn LEDs on and off! So let’s go look at the blinky example before we get back to my gripe.

The Blinky Example

From the Zephyr docs page for the blinky sample, it tells you to build for something like the Reel Board using this command:

west build -b reel_board samples/basic/blinky
west flash

A bit further down the page, you see that you need to have an overlay file (or a native node) for your device tree to contain the following:

/ {
     aliases {
             led0 = &myled0;
     };

     leds {
             compatible = "gpio-leds";
             myled0: led_0 {
                     gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
             };
     };
};

Inner hardware engineer dialog: “What the heck am I looking at right now?”

Overlay Files and DeviceTree

I’ll pause here and quickly point you at some resources. When I was getting started, I found this to be one of the most confusing parts of Zephyr. Ultimately I know that I am going to solder a part down to the board and that there’s a physical pin that the signals will squirt out of. Depending on the IDE or Ecosystem I’m using, there might be a configurator tool, or a config file, or a set of registers I need to decode in order to get a pin to do what I want. P0.13 on the nRF52840 of the Reel Board (as shown in the example above) is going to be blinking an LED on and off and, so I want to set that…but how?

Zephyr has a “DeviceTree” that represents the nodes of a particular chip or board. When we’re trying to blink an LED on or off, we will be writing code that searches through that element to find compatible elements, such as gpio-leds. When we write code that will control the LEDs, it will know to apply the data structures we create to the LED elements. If you’re new to DeviceTree, I suggest you don’t travel too far down the rabbit hole at the beginning of your journey (but you’ll get there).

Now, this is a far cry from the experience of many hardware engineers. My earliest control of microcontrollers involved OR’ing logic that basically directly sets and LED by toggling a bit on a memory mapped register. But there are benefits to these new ways! We can have similar code target a wider range of hardware. In fact, the overlay file shown above is just that: we’re only assigning one of the pins to change from its default behavior to instead have different behavior and be mapped as gpio-leds. Another benefit is that we’re building on top of many (many!) default configurations. So in the example above, we’re actually using the reel_board board configuration that is “in-tree” in Zephyr. That is actually built on top of the nrf52840 SOC configuration, also “in-tree”. The overlay is only telling the build system what is going to change. If you’d like to see more about Overlays, one of our most popular posts on the blog is about that very topic.

One important topic is understanding how different files are pieced together when you’re building your project. There are multiple layers of inheritance that includes things like SOC definition, board definition, project configurations, and more. This will be the basis of many of your errors and build problems, especially if you start building custom hardware and firmware. My co-worker Mike always calls out that you should look at the generated devicetree files during builds (even failed ones) in order to suss out what’s wrong. This is great advice.

All the devicetree files (including your overlay files) get combined into one build/zephyr/zephyr.dts file at build time.

But what about a GPIO example?

OK, back to my gripe: There is not a GPIO example in Zephyr.

This results in many projects using gpio-leds as their representation of GPIO. Someone is triggering the pin to the enable a chip on their board and it’s still…an LED? Why is that?

Other times you’ll see someone looking to interrupt a chip with another chip and they use a callback and the button compatible type. That’s not a button!

Oh I’m guilty of it too. On my post where I was driving input of a BJT with a PWM signal to trigger a buzzer I’m also using pwm-leds? What gives?

Bindings

All of the above compatible elements are called “bindings“. This is how the system knows that when I call out pin P0.13 as an LED GPIO, I can assign a struct that matches that type of GPIO and then trigger it accordingly. On the blinky example the top line showcases how that struct is assigned:

static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);

int main(void)
{
    int ret;

    if (!gpio_is_ready_dt(&led)) {
        return 0;
    }

    ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
    if (ret < 0) {
        return 0;
    }

    while (1) {
        ret = gpio_pin_toggle_dt(&led);
        if (ret < 0) {
            return 0;
        }
        k_msleep(SLEEP_TIME_MS);
    }
    return 0;
}

In this we’re searching the device tree to find LED0_NODE and then pulling that information through to associate the GPIO with the code we’re going to write in the main loop. Note the functions used in the blinky code are not the only way to configure and trigger a GPIO.

In this case we’re using the gpio-leds binding, which as I said, is often co-opted for hardware that isn’t controlling LEDs. This is not the only type of GPIO that is available though. Zephyr expects that you will make a custom GPIO type for your project, which is why there isn’t a generic GPIO example.

The custom_dts_binding Sample

I’ll be honest, I’m really not a fan that one of the “basic” samples in Zephyr is to start making custom types of GPIO. But I kind of get it. The Zephyr project has all types of people and projects walking through the door on a daily basis. So, we’re going to make a custom devicetree binding. Ultimately it isn’t that hard, but it leans on inheritance again. The custom_dts_binding sample shows the following files (as viewed in my VS Code)

In this case nucleo_l073rz.overlay is going to call out this new binding and power-switch.yaml is the actual binding itself. The code inside that yaml is…simple!

description: GPIO pin to switch a power output on or off

compatible: "power-switch"

properties:
  gpios:
    type: phandle-array
    required: true
    description: |
      The GPIO connected to the gate driver for the MOSFET.

All it does is create a single GPIO! But now it’s a custom GPIO type. If we look at the overlay file, it calls out that compatible to match.

/ {
    load_switch: load_switch {
        compatible = "power-switch";
                /* using built-in LED pin for demonstration */
        gpios = <&gpioa 5 GPIO_ACTIVE_HIGH>;
    };
};

And now GPIO A5 is assigned to that one type of new pin. The GPIO types were hiding in plain sight.

OK, but I actually had to learn this for my own uses. I was trying to assign two GPIOs to control the pins on a programmable gain amplifier. If I tried to use the above binding (really mis-using it because it wouldn’t be for a power-switch), I wouldn’t be able to assign two pins because it’s only made for one. It’s called a ‘parent’ node.

Instead, I went and copied the devicetree binding for our old friend gpio-leds and renamed that:

description: GPIO pins to control gain on the INA225

compatible: "ina225-gain"

child-binding:
  description: The GPIOs controlling the pins for gain
  properties:
    gpios:
     type: phandle-array
     required: true
    label:
      type: string
      description: |
        Human readable string describing the LED. It can be used by an
        application to identify this LED or to retrieve its number/index
        (i.e. child node number) on the parent device.

As I’m copying this over to the blog post, I even notice I forgot to change the ‘description’ to match. Yeah, I should (and will) change that.

This allowed me to add the following to my overlay file (among many other nodes):

gain-pins {
    compatible = "ina225-gain";
    gs0: gs0 {
        gpios = <&gpio0 31 0>;
        label = "GS0 pin for INA225";
    };
    gs1: gs1 {
        gpios = <&gpio0 30 0>;
        label = "GS1 pin for INA225";
    };


};

aliases {
    gs0 = &gs0;
    gs1 = &gs1;
};

Notice that like the gpio-leds, I have multiple children elements (thanks to the child-binding) that I can name and then search later. I could have also set up two custom bindings for gs0 and gs1, but that seems like unnecessary duplication of effort.

I added ‘aliases’ so I had an easy way to search the device tree from the code in my application:

static const struct gpio_dt_spec ina225_gs0 = GPIO_DT_SPEC_GET(DT_ALIAS(gs0), gpios);
static const struct gpio_dt_spec ina225_gs1 = GPIO_DT_SPEC_GET(DT_ALIAS(gs1), gpios);

And then further down main.c

err = gpio_pin_configure_dt(&ina225_gs0, GPIO_OUTPUT_HIGH);
if (err) {
    LOG_ERR("Unable to set ina225_gs0 high");
}

err = gpio_pin_configure_dt(&ina225_gs1, GPIO_OUTPUT_HIGH);
if (err) {
    LOG_ERR("Unable to set ina225_gs1 high");
}

Since I actually only needed to have these pins be high all the time, I didn’t need to do anything else, I simply configured them at boot and left them on for the duration of my program.

Notice that the files live in the application I’m building (repeating the image here from above):

When the build system is crawling this application, it sees that there are files in dts/bindings that are custom and which will be added to the other bindings that are already in-tree in Zephyr. Same goes for the boards directory, which contains the overlays. CMakeLists.txt doesn’t need to change unless we’re adding additional files to compile in the src folder.

Aspiring Firmware Engineer

I’ve been saying for the past few years that I’m an “aspiring firmware engineer” because it’s hard to be a hardware engineer without the code to control all this silicon. I think it’s worthwhile to climb up the learning curve and take on new challenges in Zephyr. GPIO is one of many topics that will be part of that curve. As you build your skills, you’ll start to recognize more patterns and reduce your confusion during firmware build. Then you get to take advantage of all the great open source firmware that has been written by the community and you’ll accelerate your next IoT project.

If you’re having problems with this or other Zephyr topics, be sure to stop by our forum!

/by