Enabling power regulators automatically at boot in Zephyr

Zephyr has a lot of tricks up its sleeve and most recently I used it to enable power regulators on a custom Golioth board. Perhaps the most interesting part of this is that it can be done entirely with the configuration code, without needing to dive in to any of the C files. And as the icing on the cake, Zephyr even includes interactive shell for working with regulators!

If you’ve been following our blog for a while, or you’ve checked out our growing library of reference designs, you’ll know that we’ve been using an internal hardware platform codenamed “Aludel” for rapid prototyping. Chris Gammell has been busy working on a new version of the Aludel main board with the ability to shut off power to the mikroBUS Click board sockets for low-power operation.

For example, a GPIO from the onboard nRF9160 SIP is connected to the EN pin on the +5V boost regulator. This grants Zephyr firmware the power (ha!) to enable or disable the regulator:

When the first prototype boards arrived from the manufacturer, we needed to enable these power regulators as part of the hardware bring-up process. I was pleasantly surprised to discover that this is actually possible to do entirely with Devicetree & Kconfig without writing any C code!

Zephyr’s regulator bindings

Out of the box, Zephyr provides regulator-gpio and regulator-fixed devicetree bindings for variable and fixed-voltage regulators respectively. These bindings are used to define GPIO-controlled power regulators that can be enabled automatically when the OS boots.

Here’s the devicetree node we’re using for the +5V boost regulator on the Aludel board:

reg_mikrobus_5v: reg-mikrobus-5v {
    compatible = "regulator-fixed";
    regulator-name = "reg-mikrobus-5v";
    enable-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>;
    regulator-boot-on;
};

The compatible property matches this node to Zephyr’s regulator-fixed device tree binding, and the regulator-name property is just a descriptive name for the regulator output.

Next, the enable-gpios property is a phandle-array devicetree property which defines the GPIO connected to the regulator’s EN pin:

  • &gpio0 is the phandle for the GPIO0 controller node that controls the pin
  • 4 is the pin number on the controller
  • the pin is configured with the GPIO_ACTIVE_HIGH flag because the regulator EN pin is an active-high input

The regulator-boot-on property tells the regulator driver that the OS should turn on the regulator at boot (but shouldn’t prevent it from being turned off later). We just needed to set the following Kconfig symbol to enable the regulator drivers:

CONFIG_REGULATOR=y

Regulator shell

When you’re bringing up a new board, it’s really helpful to have full control over the power regulators from a diagnostic shell. Zephyr provides a regulator shell that allows you to interact with regulators on your board via the shell interface!

Set the following Kconfig symbols to enable the regulator shell:

CONFIG_SHELL=y
CONFIG_REGULATOR=y
CONFIG_REGULATOR_SHELL=y

With the regulator shell enabled, you can enable/disable the regulator. You can also get/set parameters like voltage, current limit, and operating modes.

Regulator shell example

First, we need to get the device node for the regulator. You can list the available devices and their states using the device list shell command:

uart:~$ device list
devices:
- nrf91_socket (READY)
- clock@5000 (READY)
- gpio@842500 (READY)
- psa-rng (READY)
- uart@9000 (READY)
- uart@8000 (READY)
- flash-controller@39000 (READY)
- i2c@a000 (READY)
- reg-mikrobus-5v (READY)
- reg-mikrobus-3v3 (READY)

To disable the reg-mikrobus-5v regulator, we can run the following shell command:

uart:~$ regulator disable reg-mikrobus-5v

To enable the reg-mikrobus-5v regulator again, we can run a similar shell command:

uart:~$ regulator enable reg-mikrobus-5v

Time to hit that play button on some Warren G!

🎵 “Regulators, mount up!” 🎵

Learn more about the Zephyr shell

Controlling power regulators is just one of the neat things you can do with the Zephyr shell. At Golioth we think the Zephyr shell is fantastic and we’ve written extensively about it on our blog. We also use it in the Golioth SDK for things like setting device credentials.

If you’d like to learn more about Zephyr in general, join us for a free Zephyr training. Our next session is coming up in February. Sign up now!

/by
,

Power Optimization Recommendations using Zephyr

In the last blog post about the PPK2,we explained operating modes for embedded devices and how current consumption is generally measured. With Nordic’s Power Profiler Kit II, we were successful in reducing the current draw of Golioth’s hello sample by a factor of 10 by simply turning the modem off. But, truth be told, 4mA is still a significant current draw for battery-operated devices in Standby mode. The aim for today is to lower the current consumption even more.

General Power Saving Recommendations

Let’s discuss some general recommendations for lowering current consumption. Every device/product has a set of constraints. From the sensor reading period to the number of sensors connected to the MCU, the current consumption for your particular device may vary based on which function you are performing and how much you are asking of your device.

Disable Unused peripherals

Some peripherals are enabled by default, depending on the devicetree of the board you are using. Peripherals that are not in use should be disabled in the overlay file. Even though it might not seem obvious at first,  some peripherals could potentially draw current just by being enabled. And the result could be milliamps of unnecessary current draw.

Peripherals are enabled or disabled in the device overlay file. For the hello sample, we won’t use any of the peripherals, and we’ll disable them all in the nrf9160dk_nrf9160_ns.overlay file.

You only need to disable the peripherals which are not utilized in your project. You can use the Device Power Management module to put peripherals into sleep mode in inactivity periods; more about that later on.

Disable Serial Logging

By default, logging is performed over the serial port associated with the UART(E) peripheral with Nordic SoCs. If a device is expected to work without human interaction over the serial port, then there is no need for logging over serial output and having the associated current consumption. By doing this, we can reduce the current consumption by ~1mA.

  • Disable serial output with: CONFIG_SERIAL=n
  • Disable serial logging with: CONFIG_LOG=n
  • Disable the UART console with: CONFIG_UART_CONSOLE=n

For the purposes of the hello sample, we won’t disable the logging subsystem because we want the log messages to be sent to Golioth’s Logging device service, but we have disabled the uart0 peripheral, which is used as a serial console by default.

Enabling Device Power Management

The idea behind the Device Power Management module is to allow device drivers to handle power management operations. For instance, it turns off clocks and peripherals, lowering the current consumption. The Device PM module provides an interface that the device drivers use to be informed about entering the suspended state or resuming from the suspended state. This enables the application developer to suspend peripherals when the CPU goes to sleep, depending on the application’s behavior.

For example, we can turn of an SPI peripheral while it is not in use to reduce the current draw. A device driver must have an implementation of the PM action callback used by the PM subsystem to suspend or resume devices.

Since we won’t use any of the nRF9160 SoC peripherals in the hello sample, we won’t see any benefit from using the Device PM. Nordic’s documentation explains how to utilize the PM module on the external flash case.

Results

As in the previous blog post, we are going to connect to the cellular tower, Golioth Cloud, and send 5 hello messages; afterward, we’ll stop the Golioth system client and call the lte_lc_offline API function, which sets the device to flight mode, disabling both transmit and receive RF circuits and deactivating LTE and GNSS services.

 

From the picture above, we achieved an average current of 2.69 µA when all peripherals are disabled, the modem is turned off, and the CPU is in IDLE. It’s up to the application developer to decide when to enter this minimal operating state, and deal with the consequences when coming back online after this deep sleep. Things like ConnectionID can help cellular devices save power on handshakes with the tower when re-connecting.

Conclusion

We showed how disabling unused peripherals can benefit our current consumption bottom line and save milliamps in the process by achieving ~3uA current draw. In the next blog post, we’ll talk about Power Optimizations specific to the nRF9160 SoC and how to use Power Saving Mode (PSM) with the modem and eDRX method instead of turning the modem off completely.

/by

Debugging nRF9160 Zephyr applications with Ozone

Ozone is a free graphical debugger for embedded firmware from SEGGER. It’s a powerful tool that can give you deep visibility into what’s happening in your embedded system. It’s especially useful when debugging nRF9160 Zephyr apps. Sorting out multiple threads and multi image builds can be tough, but this is the tool you want.

In our previous post Taking the next step: Debugging with SEGGER Ozone and SystemView on Zephyr, Chris Gammell wrote about how to set up a SEGGER Ozone project to debug a Zephyr app running on the i.MX RT1060 Evaluation Kit. It’s a great general introduction to debugging a Zephyr app in Ozone and profiling the RTOS runtime behavior SystemView.

When I was trying to set up a similar Ozone project for debugging the Nordic nRF9160 SIP, I ran into a few snags along the way. Today, I’ll share what I’ve learned!

In this article, I’ll walk through how to:

  • Configure a nRF9160 Zephyr app for thread-aware debugging
  • Create an Ozone project for nRF9160 with the New Project Wizard
  • Modify the Ozone project to support debugging nRF9160 multi-image builds

Hardware Configuration

In the examples that follow, I’ll be using the Nordic nRF9160 DK board. This development kit from Nordic has a SEGGER J-Link OB debugger built into the board, so an external J-Link debugger is not required to follow-along with the examples.

 

Thread-awareness support in Zephyr

In a typical Zephyr app built using the Golioth Zephyr SDK, there will be multiple threads. For instance, one for the app’s main loop, one for the Golioth system client, and others for the UART shell, logging subsystem, network management, etc.

SEGGER provides a Zephyr RTOS plugin for Ozone that can show the status of each thread, but it requires that the Zephyr firmware is built with support for thread-aware debugging. Zephyr provides a CONFIG_DEBUG_THREAD_INFO Kconfig symbol that instructs the kernel to maintain a list of all threads and enables thread names to be visible in Ozone.

While you could simply add CONFIG_DEBUG_THREAD_INFO=y to your app’s prj.conf file, you probably only want to enable this extra debug info when you are building for debugging purposes. Instead, we can create an additional debug.conf Kconfig file that will only get merged in when we pass the -DEXTRA_CONF_FILE=debug.conf argument to the build system.

Since this article is about using Ozone for thread-aware debugging, we’ll use the zephyr/samples/basic/threads/ app from the nRF Connect SDK Zephyr repo as our example app in this article.

If this is your first time building one of the Zephyr sample apps, make sure to complete the nRF Connect SDK Installation Guide first to make sure your dev environment is set up correctly.

How to Enable Thread-Awareness

First, create a zephyr/samples/basic/threads/debug.conf file and add the following lines:

CONFIG_DEBUG_THREAD_INFO=y

# CONFIG_DEBUG_THREAD_INFO needs the heap memory pool to
# be defined for this app
CONFIG_HEAP_MEM_POOL_SIZE=256

Next, build the firmware, specifying the debug.conf file to be merged into the build configuration:

cd <your ncs workspace>/
west build -p -b nrf9160dk_nrf9160_ns zephyr/samples/basic/threads/ -- -DEXTRA_CONF_FILE="debug.conf"

If the build completed successfully, you’ll see the build/zephyr/zephyr.elf file we need to start a debugging session in Ozone.

Create the Ozone project

Now that we’ve built the firmware, you can launch Ozone and use the New Project Wizard to create an Ozone project:

Choose the nRF9160_xxAA device:

Select the J-Link device you want to use:

Select the build/zephyr/zephyr.elf ELF file we generated in the previous section:

Leave these fields the default values for now (we’ll update them later on):

After clicking “Finish”, you’ll see the Ozone project window appear.

In the “Console” window, run the following command to load the Zephyr RTOS plugin:

Project.SetOSPlugin("ZephyrPlugin.js");

You should now see a new “Zephyr” window in the Ozone project (if not, click on “View” → “Zephyr” to show the window):

Finally, save the project file by clicking on “File” → “Save Project as…”:

Start the debug session

Now that we’ve configured the Ozone project, we can start the debug session.

Click on “Debug” → “Start Debug Session” → “Download & Reset Program”:

Surprise! When the firmware starts to run, you’ll see a pop-up window indicating that the target has stopped in a HardFault exception state!

At this point, you might be wondering what’s going on here…

We’ve followed the same basic steps as outlined in our previous article, so why isn’t this working for the nRF9160?

Here’s a hint: the answer has to do with multi-image builds.

The missing step: flashing the merged image

You may have noticed that the board argument we passed to west build (nrf9160dk_nrf9160_ns) ends in _ns. This suffix is an indicator that the firmware will be built with Trusted Firmware-M (TF-M). This is the reference implementation of ARM’s IoT Security Framework called Platform Security Architecture (PSA).

TFM uses the ARM TrustZone security features of the nRF9160’s Cortex-M33 MCU to partition the MCU into a Secure Processing Environment (SPE) and Non-Secure Processing Environment (NSPE).

Here’s how the boot process works in a nutshell:

  1. When the MCU boots up, it starts executing in the secure environment (SPE).
  2. The boot process can optionally start with a secure bootloader chain using NSIB and/or MCUboot.
  3. If used, the bootloader starts TF-M, which configures a part of the MCU memory and peripherals to be non-secure.
  4. TF-M starts your Zephyr application which runs in the non-secure environment (NSPE).

When we build for _ns build targets, the TF-M image is automatically built and linked with the Zephyr app. If you look in the build/zephyr/ output directory, you’ll see a file named merged.hex, which is a single merged file containing the MCUboot bootloader (optional), the TF-M secure image, and the non-secure Zephyr app.

west flash knows to flash the full merged image, but Ozone doesn’t do this by default!

We need to configure Ozone to load the full merged image and start execution in the secure environment.

Fixing the Ozone project file

We’ll make a couple changes directly in the Ozone project file, which can be opened within Ozone by clicking “File” → “Edit Project File”:

Flash the merged image

Navigate to the TargetDownload section of the Ozone project file and add the following to configure Ozone to flash the merged image (changing the path to match the merged image file in your project):

/*********************************************************************
*
* TargetDownload
*
* Function description
* Replaces the default program download routine. Optional.
*
**********************************************************************
*/
void TargetDownload(void)
{
  Exec.Download("$(ProjectDir)/build/zephyr/merged.hex");
}

Fix the Vector Table & PC addresses

Navigate to the _SetupTarget section of the Ozone project file and make the following changes:

  1. Set the vector table address to 0
  2. Read the entry point program counter address from the vector table
/*********************************************************************
*
*       _SetupTarget
*
* Function description
*   Setup the target.
*   Called by AfterTargetReset() and AfterTargetDownload().
*
*   Auto-generated function. May be overridden by Ozone.
*
**********************************************************************
*/
void _SetupTarget(void) {
  unsigned int SP;
  unsigned int PC;
  unsigned int VectorTableAddr;

  VectorTableAddr = 0;
  //
  // Set up initial stack pointer
  //
  SP = Target.ReadU32(VectorTableAddr);
  if (SP != 0xFFFFFFFF) {
    Target.SetReg("SP", SP);
  }
  //
  // Set up entry point PC
  //
  PC = Target.ReadU32(VectorTableAddr + 4);
  if (PC != 0xFFFFFFFF) {
    Target.SetReg("PC", PC);
  } else {
    Util.Error("Project script error: failed to set up entry point PC", 1);
  }
}

When you save the project file, you should get a modal pop-up asking if you want to reload the project.

Choose “Yes”:

Restart the debug session:

After the image has been flashed to the device, you should see the debugger halted at main:

Click “Debug” → “Continue”:

The firmware should now run without exceptions!

Summary

Hopefully this helped you get started debugging the nRF9160 with Ozone.

The nRF9160 is fully supported in Zephyr, and has the highest level of support in the Golioth IoT device management platform (Continuously Verified). With Golioth, you can connect and secure your devices, send sensor data to the web, update firmware over-the-air, and scale your fleet with an instant IoT cloud.

Try it today—with Golioth’s Dev tier your first 50 devices are free!

/by

How to turn Helper Code into a Zephyr Module

Embedded developers always maintain sets of helper code that get used across multiple projects. With Zephyr RTOS, you can easily turn your helper code into a portable Zephyr module.

Creating a Zephyr module means you can version control your code, making changes in one centralized place, while targeting a specific git commit, tag, or branch of that code in a project. You only need to add two or three additional files to qualify as a Zephyr module. And once the module is published you can make the code available to your Zephyr projects simply by adding it to your manifest file.

A Working Example

Ostentus faceplate installed on Aludel-mini reference design

You may remember reading about Ostentus, Golioth’s custom faceplate for conference demos. This I2C display can be added to any Zephyr project by leveraging some helper code that simplifies sending data from the device to the faceplate. As this code will change in the future, it isn’t maintainable to copy it between projects, so we turned it into a Zephyr module. Let’s use this as an example. Here are the steps:

  1. Create a new repository to store your helper code
  2. Add a CMake file and an optional Kconfig file
  3. Add a module.yml file that tells Zephyr where to find files in the module repo

That creates the module, and the final step is to add it to your project’s West manifest.

1. Create a new repository

For our example, we have just one C file and one header file. I created a new repository to store these files. Place the header file in a directory named include; you may add subdirectories if you want there be a category-like prefix when the header is included (e.g. #include <yoursubdirectory/yourfile.h>).

Here are the important parts of my tree for this module:

➜ tree
.
├── include
│   └── libostentus.h
└── libostentus.c

2. Add CMake and Kconfig files

Next we need to add a CMake file to include our source code in the build. You also have the option of including a Kconfig file. I’m going to do this optional step because it allows me to create a symbol that will turn on or off this library in the project build.

First, I create the Kconfig file in the root of the repo that adds a unique symbol (LIB_OSTENTUS) for this library:

config LIB_OSTENTUS
    bool "Enable the helper library for the Golioth Ostentus faceplate"
    default n
    depends on I2C
    help
      Helper functions for controlling the Golioth Ostentus faceplate.
      Features include controlling LEDs, adding slides and slide data,
      enabling slideshows, etc.

Next, I add the C file and the header file to the build using a CMakeLists.txt file in the root directory of the repository. Note that this uses the Kconfig symbol created in the last step to decide whether or not to build with these files.

if (CONFIG_LIB_OSTENTUS)
  zephyr_include_directories(include)
  zephyr_library_sources(libostentus.c)
endif()

3. Add module.yml

The glue that holds this together is the module.yml file, which must be placed in a zephyr subdirectory of the repository. Here I tell it where to look for the CMake and Kconfig files, although there are other options that can be added to this file.

build:
  cmake: .
  kconfig: Kconfig

I find the relative paths of this file to be a bit confusing. But the gist of it is that this file will be located at zephyr/module.yml and the paths in the file are based on the parent of that zephyr subdirectory.

Congratulations, we now have a Zephyr module made up of the following files:

➜ tree
.
├── CMakeLists.txt
├── include
│   └── libostentus.h
├── Kconfig
├── libostentus.c
└── zephyr
    └── module.yml

Using the Module in a Zephyr Project

Using the newly created module follows the familiar Zephyr pattern of adding it to the projects section of your West manifest file. (You can find your manifest file by running west manifest --path.)

manifest:
  projects:
    - name: libostentus
      path: modules/lib/libostentus
      revision: v1.0.0
      url: https://github.com/golioth/libostentus

self:
  path: app

Calling west update will now checkout the helper code and place it in modules/lib/libostentus. Remember that I added a Kconfig symbol in my example, so I need to add that to the project prj.conf file or a <board>.conf file to include this code in the build.

CONFIG_LIB_OSTENTUS=y

Using the module in your C files is a simple matter of adding the #include and then calling the functions.

#include <libostentus.h>

int main(void)
{
    clear_memory();
    show_splash();

    k_sleep(K_FOREVER);
}

Summary

Golioth supports a wide variety of hardware and use cases, and part of our strategy to make that scalable is to write and maintain modular code. The Golioth Zephyr SDK is a Zephyr module, which makes it easy to include in your project and easy to lock to a known version until you’re ready to upgrade to a newer version. We’ve used this same Zephyr module approach for helper code when building our numerous reference designs. It works well and I encourage you to adopt modular practices for your own work.

This process of creating a Zephyr module is a nice improvement over copying and pasting code between projects because it implements reliable revision control. It is also an intermediary step between implementing a project-specific driver, and creating a modular Zephyr driver. The Ostentus faceplate should eventually be converted to a full Zephyr driver, and enabled directly from Devicetree. But that’s a post for another day!

In the meantime, if you find yourself in need of a device management service with robust OTA, data handling, fleet settings, RPC, and more, give us a try. With Golioth’s Dev tier your first 50 devices are free!

/by

Troubleshooting IoT Cellular Connections with Nordic nRF9160

Troubleshooting IoT Cellular

Cellular connected IoT can be intimidating, especially when the cellular connection doesn’t work, or only works intermittently. Today we will explore Nordic’s LTE Link Monitor and Cellular Monitor applications to show how you can troubleshoot cellular connection using the nRF9160 DK as the development board.

Programming the modem firmware

The modem allows applications to send and receive data on the cellular network, and the application talks to the modem via the AT commands. Every nRF9160 SiP has modem firmware (separate from your application code) that is provided as a pre-compiled binary file, signed and encrypted by Nordic Semiconductor.

It’s always beneficial to update the modem firmware to the latest version. In fact, this is the first thing you should try. Make sure you have the nRF Connect for Desktop tool installed and follow these steps to do so:

  1.  Download the latest modem firmware (at the moment of writing, it’s v1.3.5),
  2. Open the Programmer Application from nRF Connect for Desktop
  3. Connect the nRF9160 DK to your computer and select it in the Programmer Application
  4. Click the Add file button, add the mfw_nrf9160_1.3.5.zip file
  5. Flash modem firmware with the Write button

LTE Link Monitor

If updating the firmware didn’t work, it’s time to look at the status of the cellular connection. LTE Link Monitor is part of the nRF Connect for Desktop tool. I works alongside a modem client application that monitors the modem status and activity using AT commands.

For this demo, we’ll use Nordic’s at_client sample for the nRF9160 DK, which can be found at nrf/samples/nrf9160/at_client (Nordic changed folder names over the summer so this may be in samples/cellular/at_client for you).

The AT Client sample demonstrates the asynchronous serial communication taking place over UART to the nRF9160 modem, enabling you to use an external computer to send AT commands to the LTE-M/NB-IoT modem. This facilitates the reading of responses or analyzing of events related to the nRF9160 modem.

Note that not all commands are supported in all modem firmware versions; that is why the first step was to update the modem firmware to the latest version.

Switch to NB-IoT standard with AT commands

In our recent blog post, we showed how to switch the preferred cellular connection standard from LTE-M to NB-IoT with configuration files. Now, we are going to do the same thing with AT commands and later show how the two are connected with Zephyr’s Kconfig Configuration System.

To switch from the default LTE-M connection standard to NB-IoT, do the following:

  • Flash the at_client example built for the nRF9160 DK,
  • open the LTE Link Monitor Application and connect to the development board,
  • check the modem system mode with AT%XSYSTEMMODE? command.

XSYSTEMMODE AT command is used for enabling system modes, and the command response syntax is:
%XSYSTEMMODE: <LTE_M_support>,<NB_IoT_support>,<GNSS_support>,<LTE_preference>.

The response we got was: 1,0,1,0, which means our device is set for LTE-M and GNSS support.
Now, let’s change it to NB-IoT.

  • Send AT%XSYSTEMMODE=0,1,0,0,
  • Send AT+CFUN=1 to set the device to full functionality
  • Send AT+CFUN?

After sending the AT+CFUN? command, the nRF9160 DK has connected to the cellular network T-Hrvatski Telekom using the NB-IoT standard and has obtained an IP address 178.160.19.177.


With the at_client sample, you can test and manually send all AT commands to the modem.

Cellular Monitor

Cellular Monitor is another nRF Connect for Desktop application used for capturing and analyzing modem traces to evaluate communication and view network parameters. Let’s use it with Golioth’s hello sample, which can be found at https://github.com/golioth/golioth-zephyr-sdk/tree/main/samples/hellogolioth/samples/hello.

But before we start, we need to add CONFIG_NRF_MODEM_LIB_TRACE=y to prj.conf file in the sample directory, PSK and PSK-ID as stated in the README file, build the sample, and flash the nRF9160 DK.

After that, open the Cellular Monitor Application, click the Start button in the upper left corner to capture a trace and reset the nRF9160 DK. When capturing a trace, the data is saved to the .mtrace binary file so you can view previously collected traces in the Cellular Monitor Application.

The trace data is categorized into the following 6 dashboard panels:

  • LTE Network
  • Device
  • Power Saving Mode
  • SIM
  • Connectivity Statistics
  • PDN (Packet Data Network)

The Packet Event Viewer visualizes communication at the AT command, Radio Resource Control (RRC), Non-access Stratum (NAS), and Internet Protocol (IP) levels.

For this example, I have enabled the CONFIG_LTE_NETWORK_MODE_NBIOT symbol in the configuration file, and we can see in the Packet Event Viewer the XSYSTEMMODE AT command is sent to the modem automatically during the configuration.

Conclusion

In this demo, we have shown how to start troubleshooting Cellular Network problems with LTE Link Monitor, how to use the Cellular Monitor Application, and how the modem can be configured with Zephyr’s Kconfig Configuration System. You should consider using these tools to observe your modem configuration when it is correctly functioning. This provides much of the intuition you will need when you are called upon to troubleshoot a misbehaving cellular modem!

Want to see what happens when your device is sending and receiving data over the network? Give Golioth a try, our Zephyr SDK has a number of ready-to-use samples and your first 50 devices are free on our Dev Tier.

/by

Displaying Firmware Version and Battery State with Zephyr

We recently open-sourced the Golioth Reference Design Template that we have been using internally as the starting point for our growing library of reference designs. Out of the box, the template provides an end-to-end working firmware example showcasing all of Golioth’s key features. You can read more about what’s included in the Reference Design Template in the announcement post Open Sourcing Golioth Reference Designs and Template.

The Reference Design Template firmware currently supports two boards: the Nordic nRF9160-DK and the Golioth Aludel Mini. The Aludel Mini is an internal prototyping platform designed by Golioth for rapidly building and testing proof-of-concept ideas using widely available off-the-shelf modules. The Aludel Mini integrates a nice ePaper display (Ostentus) into the enclosure, and we have been using it to display custom sensor readings specific to each reference design—for example, on the DC Power Monitor it displays current & voltage, and on the Air Quality Monitor it displays particulate matter, CO₂, and weather data.

As I was working on some of the Golioth reference designs, I found myself occasionally checking the Golioth Console to confirm the firmware version was correct (for example after an OTA update) or to check the remaining battery level. The Golioth Console makes it easy to monitor values like this once the device has connected to the network, but it would be helpful to display this info immediately on the ePaper display when the device boots up (and without having to connect to the device’s UART console).

Luckily, this turned out to be a really easy addition!

Displaying the firmware version

The Golioth Reference Design Template is built with support for the MCUboot bootloader. The firmware version is defined and later made available to the Zephyr application firmware via the KConfig symbol CONFIG_MCUBOOT_IMAGE_VERSION.

When the app boots up, the firmware logs the current firmware version:

LOG_INF("Firmware version: %s", CONFIG_MCUBOOT_IMAGE_VERSION);

Now, it also displays a “Firmware” slide that shows the currently running firmware version on the Ostentus ePaper display:

Displaying the battery voltage

The Aludel Mini board uses a SparkFun nRF9160 Thing Plus module that has the ability to run off a Li-Poly battery. The battery voltage can be sampled using the ADC on the nRF9160 using the onboard voltage-divider circuit:

We can enable support for this voltage-divider circuit in Zephyr by adding a voltage-divider-compatible node to the board’s device tree definition. This specifies the ADC channel to use, the values of the resistors in the voltage divider circuit, and which GPIO is used to enable power to the divider:

/ {
  vbatt {
    compatible = "voltage-divider";
    io-channels = <&adc 7>;
    output-ohms = <100000>;
    full-ohms = <(100000 + 100000)>;
    power-gpios = <&gpio0 25 0>;
  };
};

The Zephyr tree provides an example of how to read this voltage divider circuit in zephyr/samples/boards/nrf/battery. I was able to use this sample as a starting point for quickly adding some simple battery monitoring to the Reference Design Template.

Now, whenever the template firmware is built with our custom  CONFIG_ALUDEL_BATTERY_MONITOR Kconfig symbol enabled, the firmware displays two slides: one that shows the current battery voltage and another that displays the estimated remaining battery level.

Golioth Reference Designs

Firmware version and battery status display slides are now included in all the Golioth reference designs we’ve published. You can check out the full set of reference designs on the Project page at https://projects.golioth.io. And as always, we’d love to hear about what you’re building. Show off your projects and ask questions over on the Golioth Forum.

/by

Manifests: Project Sanity in the Ever-Changing Zephyr World

If you take one thing away from this [talk], it should be this: Manifest files are a great way to manage revision control in your Zephyr applications.

Mike Szczys is my teammate in the Developer Relations group and the primary firmware engineer creating Golioth Reference Designs. We build on top of the Golioth Zephyr SDK to create showcase examples of how you can use Golioth firmware and cloud capabilities to create real-world applications quickly.

To keep everything straight, we rely heavily on Zephyr manifest files to ensure we are always building the correct code each time. We include things like the Zephyr codebase, the Golioth Zephyr SDK codebase, the Nordic Connect SDK codebase, and any custom code we write, all of which might be at different points in their lifecycles. It’s not a stretch to say that it’d be nearly impossible to manage all the code we use on a daily basis without manifest files. Mike used the knowledge he has built to give the above talk at the Zephyr Developer Summit 2023, which was part of the larger Embedded Open Source Summit in Prague in June of this year.

What is a manifest?

Zephyr utilizes a manifest file, which is part of the west meta-tool. These are a tough topic at first because they have multiple levels of inheritance possible. If you’re using a vendor-provided manifest file (or using one of the vendor SDK tools that hides the complexity), you likely will have an easy time following along their path. But once you want to start customizing your own project, you need to dig in and learn how they work.

A visualization of the west meta tool, showing how confusing things can get (image from Zephyr West page)

Mike points out that at their core, manifest files manage hierarchy and provide a revision-controlled record of what should be included in a project. You can directly call out which version of a piece of code you want to include. As the subsystems you utilize in your project continue to upgrade over time, you can choose to lock to the older version. More importantly, you can make a concerted effort to change the version and then test the upgrade has not broken your build or introduced unknown behaviors in your program.

Structuring your Zephyr application

While we normally avoid being overly prescriptive on this blog, we have a few opinions about how to find success with Zephyr applications. Some of this comes from seeing Zephyr projects go wrong in the past. Some examples of this are:

  • Cloning the Zephyr tree and putting it into your project repository
  • Placing your code among Zephyr samples
  • Having a standalone application repository (good) that references the Zephyr tree somewhere else on your machine (bad, because you don’t have a guarantee that the tree isn’t being used by some other Zephyr repo)

The Right Way™ (at least how we see it!) is to put a manifest file in your application and then specifically call out the versions of all dependencies. Asgeir Stavik Hustad guest-wrote about this method on the Golioth blog last year and we have taken those ideas and extended them even further (and changed a few things). The downside is that you will have many independent copies of the Zephyr tree on your hard drive…but hard drive space is cheap and making mistakes in a repo is very expensive. 

Examples and more!

I could continue to summarize the talk here, but it’s best to go and watch Mike’s examples as part of the talk. If you’re not a video person, feel free to scroll through the slides, embedded below. We love talking about Zephyr and would love to hear about your challenges and successes using manifests over on our forum.

https://www.youtube.com/watch?v=PVhu5rg_SGY

/by
,

How to Configure VS Code for Zephyr Development

Visual Studio Code, colloquially known as VS Code, has become the de-facto Swiss Army Knife of Integrated Development Environments (IDEs). It is already configured for a lot of different languages and ecosystems when first installed. It’s also great for developing Zephyr RTOS projects, but not out of the box. Jonathan Beri presented at talk at the 2023 Embedded Open Source Summit detailing how to configure VS Code for Zephyr development.

To follow along, check out Jonathan’s example repository for us Zephyr in Visual Studio Code.

New to Golioth? Sign up for our newsletter to keep learning more about IoT development or create your free Golioth account to start building now.

VS Code for Embedded Development

Most of the pre-configuration rolled into the stock installation of VS Code centers around languages used in web development. But increasingly we see the IDE called upon for embedded system development–moving beyond merely working with source code to include native debugging and flashing. These more specialized features tend to be the areas requiring custom configuration. Notably, Nordic and NXP are both actively developing VS Code environments for Zephyr.

For those who prefer to maintain their own workspace configuration, selecting the right extensions is a good place to start. The Microsoft’s extensions for C/C++ and Cmake are table stakes for embedded development. Jonathan also recommends the Cortex Debug plugin and suggests that Microsoft’s Embedded Tools is a newer plugin you may find useful.

Diving into Configuration Files

The meat of the talk comes about sixteen minutes in as Jonathan walks through the settings files he’s using to configure his workspace: settings.json, tasks.json, launch.json, and extensions.json. You can view these files in the example code repository.

Telling VS Code where to find GCC will get syntax highlighting and linting working well. Preventing CMake from trying to auto-configure Zephyr projects will silence a lot of the popup window noise when opening a new VS Code window. And setting up the task runner is akin to configuring aliases for your oft-used commands, accessible from the VS Code command palette. Finally, debugging configuration and recommended extensions round out the workspace-specific configurations using the built-in “profile” features.

All the Things You’ve Been Missing from VS Code

If you’ve already tried developing for Zephyr in VS Code it’s easy to forget what you’ve been missing. The live demo begins at about 20:30 and immediately shows the most basic annoyances have been solved. There are no longer random red squigglies sprinkled throughout your code, because VS Code now knows where to find all of the header files. You can jump to OS-specific function declarations as expected and access the function syntax hinting because the entire Zephyr tree is accessible for the extensions. These features are not novel, they’re just not fully configured out-of-the-box.

Building and flashing works as expected, because your target board and programmer have now been specified in the configuration. They’re triggered via simple to remember commands like west build that Jonathan added to the command palette via those JSON files. The serial terminal connection to the device is available in the IDE without having to juggle external console windows. The general noise floor of the IDE is almost non-existent at this point, all thanks to a comprehensive configuration that makes the developer experience worlds better.

Modern Tools for Modern IoT

Zephyr RTOS is paving the way for the next generation of embedded devices. As the Founder and CEO of Golioth, Jonathan Beri recognized the power of Zephyr to support cross-vendor hardware in the IoT space, which makes it possible for Golioth to support the hardware that you the choose (and not a narrow set of hardware required by your IoT Cloud). As this talk shows, he spends a lot of hands-on time with the RTOS and is sharing the workflow he has developed over the last several years.

Set aside an afternoon to prototype your IoT Fleet. Your first 50 devices are free with Golioth’s Dev Tier. Follow Jonathan’s examples for using VS Code, and you’ll be sending sensor data to the cloud in a matter of hours!

/by
,

Switching Between LTE-M and NB-IoT Cellular Standards in Zephyr

It’s a tale as old as IoT. You get a project with a cellular connection working, but when you move to a different physical location, all of a sudden you cannot connect to the internet. You know your network provider has cellular coverage in the area, and your SIM card is paid up. So why is data not working?

While there are a number of carriers that offer nearly global coverage, not all coverage is the same. IoT devices generally use the NB-IoT or the LTE-M standard. Each is different and has different use cases. Golioth is your instant IoT cloud, and works with devices using either standard. Let’s learn more about what the differences are and how to use them in your IoT projects.

NB-IoT vs. LTE-M

NB-IoT stands for Narrowband IoT. It is a low-power wide-area network (LPWAN) radio technology standard developed by 3GPP for cellular network devices. NB-IoT uses a subset of the LTE standard, but limits the bandwidth to a single narrow-band of 200kHz. It’s suitable for applications that require more frequent communication with the backend (cloud), and it doesn’t support tower handoff. NB-IoT is suitable for stationary devices, such as smart metering devices.

On the other hand, LTE-M standard is designed to transfer low-to-medium amounts of data (200-400 kbps) across a wide geographical range and supports cellular tower handoff. LTE-M is suitable for mobile applications such as asset tracking and fleet management.

There are a couple of older standards you may remember hearing about. Largely these have been grouped into the two mentioned above. LTE Cat-M1 is part of the LTE-M standard. LTE Cat-NB1 and Cat-NB2 are part of the NB-IoT standard.

Cellular World Coverage

Screenshot of an interactive world map of NB-Iot and LTE-M coverage from gmsa.com

Click the image to open an interactive map of NB-Iot/LTE-M coverage at gmsa.com

Depending on your location, you might have NB-IoT or LTE-M coverage. Some areas of the world have coverage for both standards, so choosing which one to use can be challenging. Check the interactive map at GSMA to see how your country is adopting for the future.

Switch Between Cellular Standard in Zephyr

Nordic’s nRF Connect SDK (based on Zephyr RTOS) offers an elegant and simple way of prioritising the connection standard. A pair of network mode Kconfig symbols are available when building for the Nordic nRF9160 cellular modem.

By defining the CONFIG_LTE_NETWORK_MODE_NBIOT symbol in board-specific conf files, the NB-IoT cellular standard will be preferred. On the other hand, CONFIG_LTE_NETWORK_MODE_LTE_M will prioritise the LTE-M standard.

Try including one of these KConfig symbols in your application, and compare the differences in connection time when connecting to Golioth.

# Prioritise NB-IoT
CONFIG_LTE_NETWORK_MODE_NBIOT=y

# Prioritise LTE-M
CONFIG_LTE_NETWORK_MODE_LTE_M=y

Conclusion

In this blog post we talked about differences between NB-IoT and LTE-M standards and how to prefer one over the other in the Zephyr ecosystem. In the next blog post, we’ll investigate automatic switching between NB-IoT and LTE-M, connection time-out, and how Zephyr RTOS handles all of that.

Get your IoT fleet started today. With the Golioth Dev Tier your first 50 devices are free, so try Golioth now!

/by

Zephyr Devicetree Troubleshooting: Generated Files

Learning Devicetree is one of the more difficult parts of getting comfortable with Zephyr. I find the error messages can be extremely long and hard to decipher. One tool that has helped me along the way is the ability to look at the header files that are being generated when the Devicetree files are combined at build time. Every project has a build/include/generated/devicetree_generated.h file that you can reference against error messages.

Let’s look an example of a common Devicetree error message and how I might troubleshoot it.

Building zephyr/samples/sensor/bme280

The Bosche BME280 sensor is one of our favorites here at Golioth. Let’s build the Zephyr sample application for that sensor, using a Nordic nRF9160-DK. The only change we need to make is to add an overlay file for this board:

/* Warning: we've made an error in this file for the demo */
&i2c3 {
    pinctrl-0 = < &i2c2_default >;
    pinctrl-1 = < &i2c2_sleep >;
    pinctrl-names = "default", "sleep";

    bme280@77 {
        compatible = "bosch,bme280";
        reg = <0x77>;
    };
};

&pinctrl {
    i2c2_default: i2c2_default {
        group1 {
            psels = <NRF_PSEL(TWIM_SDA, 0, 12)>,
                <NRF_PSEL(TWIM_SCL, 0, 13)>;
        };
    };

    i2c2_sleep: i2c2_sleep {
        group1 {
            psels = <NRF_PSEL(TWIM_SDA, 0, 12)>,
                <NRF_PSEL(TWIM_SCL, 0, 13)>;
            low-power-enable;
        };
    };
};

Now if you try to build this application:

$ west build -b nrf9160dk_nrf9160_ns . -p

You will eventually be greeted by dozens of lines of error output. The part of the error I usually look at most closely is the line that actually says error in it:

/home/mike/golioth-ncs-workspace/zephyr/include/zephyr/device.h:83:41:
 error: '__device_dts_ord_109' undeclared here (not in a function);
 did you mean '__device_dts_ord_19'?                                                                                                     
   83 | #define DEVICE_NAME_GET(dev_id) _CONCAT(__device_, dev_id)                                                                       
      |                                         ^~~~~~~~~

Now __device_dts_ord_109 is certainly not part of my code. But I recognize the format as belonging to the Devicetree build process. Let’s see if we can make more sens of that identifier.

Troubleshooting Devicetree with generated header files

Look in the build/include/generated/devicetree_generated.h file that was generated during the build process. Near the top, in comments for this file, you will find the Node dependency ordering list.

* Node dependency ordering (ordinal and path):
*   0   /
*   1   /aliases
*   2   /analog-connector
*   3   /chosen
*   4   /connector
*   5   /entropy_bt_hci
*   6   /gpio-interface
*   7   /soc
*   8   /soc/peripheral@40000000
*   9   /soc/peripheral@40000000/gpio@842500
*   10  /gpio-reset
 
... 96 lines removed for blog post brevity ...
 
*   107 /soc/peripheral@40000000/flash-controller@39000/flash@0/partitions/partition@f0000
*   108 /soc/peripheral@40000000/flash-controller@39000/flash@0/partitions/partition@fa000
*   109 /soc/peripheral@40000000/i2c@b000
*   110 /soc/peripheral@40000000/i2c@b000/bme280@77

Okay, now we’re getting somewhere! I can see in the list above that node 109 (the number that appeared in the error message) is an i2c bus, and node 110 is our BME280 node on that i2c bus. So the error we’re getting relates in some way to this node being undeclared.

The easiest way to look at the declaration of the nodes is to view the build/zephyr/zephyr.dts file that is the combination of all Devicetree files during the build process:

i2c3: i2c@b000 {
    compatible = "nordic,nrf-twim";
    #address-cells = < 0x1 >;
    #size-cells = < 0x0 >;
    reg = < 0xb000 0x1000 >;
    clock-frequency = < 0x186a0 >;
    interrupts = < 0xb 0x1 >;
    status = "disabled";
    pinctrl-0 = < &i2c2_default >;
    pinctrl-1 = < &i2c2_sleep >;
    pinctrl-names = "default", "sleep";
    bme280@77 {
        compatible = "bosch,bme280";
        reg = < 0x77 >;
    };
};

I was able to find i2c@b000 in this file. It corresponds to the i2c3 node I want to use for my sensor. And indeed, you can see the sensor node is present. So why can’t the build system locate this node? The answer is in line 264: status = "disabled“.

Disabled nodes are not included in the build. So even though we see information here, the preprocessor will not include symbols for this node. If we want to use this peripheral, we need to enable it. That is the mistake I made in my overlay file.

Correcting the Overlay File

Correcting the overlay file is a simple matter of enabling our target node. If you’re like me, you might assume the opposite of disabled is enabled, but you would be wrong. Zephyr wants enabled nodes to use the okay keyword:

&i2c3 {
    status = "okay";
    pinctrl-0 = < &i2c2_default >;
    pinctrl-1 = < &i2c2_sleep >;
    pinctrl-names = "default", "sleep";
    bme280@77 {
        compatible = "bosch,bme280";
        reg = <0x77>;
    };
};

&spi3 {
    /* The nRF9160 cannot have both
     * i2c3 and spi3 enabled concurrently */

    status = "disabled";
};

&pinctrl {
    i2c2_default: i2c2_default {
        group1 {
            psels = <NRF_PSEL(TWIM_SDA, 0, 12)>,
                <NRF_PSEL(TWIM_SCL, 0, 13)>;
        };
    };

    i2c2_sleep: i2c2_sleep {
        group1 {
            psels = <NRF_PSEL(TWIM_SDA, 0, 12)>,
                <NRF_PSEL(TWIM_SCL, 0, 13)>;
            low-power-enable;
        };
    };
};

When solving this issue I also received an error after enabling i2c3 because spi3 was already enabled by default. This device can only have one of those enabled at a time, which explains the additional node above that disables the unused SPI bus.

Conclusion

Understanding Devicetree errors is a bit like playing jazz. There’s a pattern to it, but you do need to develop a bit of a feel for it. That begins with developing a sense for what the error output is telling you. I hope this tidbit will make things a bit easier.

If you have other Zephyr troubleshooting tricks we should know about, we’d love to hear it! Please share your experiences on the Golioth Forum!

/by