Zephyr RTOS Real Application Tutorial series

In this post, I’ll walk you through the process of creating a real Zephyr RTOS application based on the Raspberry Pi Pico. I assume that you have finished all the other episodes. Please watch all Zephyr RTOS tutorial videos to better understand the subject.

Introduction

Since I promised to make a real application with Zephyr RTOS, I decided it would be more informative to build a tutorial around an actual, functional application. So I decided to remake the PicoDRO application using Zephyr RTOS. It is dedicated to learning Zephyr RTOS drivers, devicetrees, modules, pin control, overlays, macros, and more. The requirement for RTOS is out of scope for the content.

PicoDRO is an open-source digital readout project that reads linear scales (encoders) with the Raspberry Pi Pico and Pico SDK. This video demonstrates how it is designed and works. Here is the PicoDRO repository, which also contains a circuit schematic, etc.

I took my time breaking down this project into small pieces to make it easy to understand. All tags are compilable and executable. Some tags have a slightly different readme file that specifies compilation than others.

Thank you for considering supporting my work!

Tags and video links

As I post new tutorial videos for the Real Application series, I will add new tags to the repo.

v1.0.0 VS Code environment settings for Linux, macOS, and Windows. Debug config is added.
v1.1.0 Setting USB CDC ACM as console output.
v1.2.0 DTR line control for logging.
v1.3.0 Setting USB CDC ACM as the default console.

Preparation

I assume you have;

Finished the Zephyr development environment setup. It is covered in this video.
Zephyr RTOS source code on the paths below.
Linux or macOS Windows
cd ~/zephyrproject cd %USERPROFILE%/zephyrproject
Installed VS Code. (not mandatory)

If so, you are good to go. At each part, execute the command specified in the part that applies to you. When you get to the end of the page, the application will have been compiled and will be running.

* Except as otherwise specified, the commands are the same for Linux, macOS, and Windows.

* The commands were tested on Linux (Ubuntu 22.04), macOS (Ventura 13.2), and Windows (10).

Initialization

Please choose your desired project type (workspace app or freestanding app) and follow the instructions below. I will be using the workspace application in the tutorial videos. Then select a tag and replace <tag_name> with your preferred tag (for example, v1.0.0) in the commands below. For more about Zephyr RTOS application types, please watch this video.

Initialization as a workspace application
1. Navigate to the project’s desired location by changing the directory.
Linux or macOS Windows
cd ~/Desktop cd %USERPROFILE%/Desktop
2. Initialize the workspace.
```
  # initialize the workspace
  west init -m https://github.com/MrGreensWorkshop/ZephyrOS_RasPiPico_PicoDRO --mr <tag_name> PicoDRO
  # cd to project and update Zephyr modules
  cd PicoDRO
  west update
```
* Please don’t forget to comment the terminal.integrated.env settings in .vscode/settings.json.

Linux or macOS	Windows
`cd ~/Desktop`	`cd %USERPROFILE%/Desktop`

Initialization as a freestanding application

1. Navigate to Zephyr RTOS source code directory.

Linux or macOS	Windows
`cd ~/zephyrproject`	`cd %USERPROFILE%/zephyrproject`

2. For this project, we will be using Zephyr v3.2.0, so we need to switch zephyrproject/zephyr to it. Or if you don’t want to change your zephyrproject then go to step 3.

  # switch to zephyr v3.2.0
  git -C zephyr checkout tags/v3.2.0
  # update Zephyr modules
  west update

3. If you already ran the commands in step 2, jump to step 4. Rename the current zephyrproject and get Zephyr v3.2.0, as shown below.

Linux or macOS

# rename the current zephyrproject directory
move ~/zephyrproject ~/zephyrproject_old
# initialize
west init --mr v3.2.0 ~/zephyrproject
# cd to project and update Zephyr modules
cd ~/zephyrproject
west update

Windows

# rename the current zephyrproject directory
move %USERPROFILE%/zephyrproject %USERPROFILE%/zephyrproject_old
# initialize
west init --mr v3.2.0 %USERPROFILE%/zephyrproject
# cd to project and update Zephyr modules
cd %USERPROFILE%/zephyrproject
west update

4. Clone the repository as shown below, or download the desired tag from the release page.

  git clone -b <tag_name> https://github.com/MrGreensWorkshop/ZephyrOS_RasPiPico_PicoDRO.git

* Please don’t forget to uncomment the terminal.integrated.env settings in .vscode/settings.json as mentioned in the build process below.

Build process

1. Setting up environment variables

Workspace application
- Using VS Code
  - No action is required.
  - If you are not planing to use debugging you can delete the .vscode directory at all.
- Using the Shell or Command Prompt
  - No action is required.
Freestanding application
- Using VS Code
  - Open the .vscode/settings.json file and uncomment terminal.integrated.env settings.
  - Reopen the project directory in VS Code after making any modifications to the .vscode/settings.json file.
  - Please don’t forget to reopen the project directory in VS Code after changing tags. Since environment variables may differ between tags.
- Using the Shell or Command Prompt
  Please make sure to set environment variables using the following command when using Shell or Command Prompt (not PowerShell).
  Linux or macOS Windows
  source ~/zephyrproject/zephyr/zephyr-env.sh %USERPROFILE%/zephyrproject/zephyr/zephyr-env.cmd

Linux or macOS	Windows
`source ~/zephyrproject/zephyr/zephyr-env.sh`	`%USERPROFILE%/zephyrproject/zephyr/zephyr-env.cmd`

2. Building

Some tags may have different build commands. Please refer to the readme file on the project repo for each tag for build commands.

Running

1. Put the Raspberry Pi Pico into bootloader mode by pushing the bootsel button while plugging it into your computer. Or you can use PicoProbe to write the binary. For more about that, check out Debugging.

2. Copy the build/zephyr/zephyr.uf2 file to the Raspberry Pi Pico either by dragging and dropping or using the cp command as shown below.

Linux	macOS
`cp build/zephyr/zephyr.uf2 /media/<user>/RPI-RP2`	`cp build/zephyr/zephyr.uf2 /Volumes/RPI-RP2`

3. Getting Console Output

Please make sure to build with the desired configuration (USB or UART). USB configuration available with and after tag v1.1.0.

Using Raspberry Pi Pico USB CDC ACM (built with USB configuration)
Please connect to your PC via USB.
Using UART0 over USB serial adapter (built with UART configuration)
Please connect its UART0 to your PC via the USB serial adapter.
Pin Function USB / Serial converter
1 UART0 TX RX
2 UART0 RX TX
3 GND GND
Using PicoProbe as USB serial adapter
When you are using PicoProbe just as a USB serial adapter, you don’t need to install anything on your PC.
Connect your target Raspberry Pi Pico to PicoProbe. As shown in the schematic diagram, connect three Serial I/F pins. Please make sure DTR is turned on. Otherwise, you will not get serial output.
Final step
Open your favorite serial terminal app and set the baud rate to 115200, then open the corresponding serial port.

Pin	Function	USB / Serial converter
1	UART0 TX	RX
2	UART0 RX	TX
3	GND	GND

Debugging

For more about debugging on Zephyr RTOS using PicoProbe, please watch this video. You can also check this blog post for the circuit diagram and how to guide.

1. Connect your target Raspberry Pi Pico to PicoProbe. As shown in the schematic diagram, connect three pins each for SWD I/F and Serial I/F pins.

2. For debugging set the svdFile on .vscode/launch.json file based on your project configuration (freestanding app or workspace app).

You Can Support My Work

Creating projects like this takes a great amount of time. Much appreciated if you consider supporting me so that I can continue projects like this and creating new contents for everyone.

You might consider supporting me via GitHub Sponsors, Patreon, or Ko-fi. For links, please see the About page.

Credits

I’d like to thank all project(s) that gave me an opportunity to make this project possible.

Zephyr Project is a scalable real-time operating system (RTOS) supporting multiple hardware architectures, optimized for resource constrained devices, and built with security in mind.

Final words

You can access the dedicated repository through this link.

Tell me what you think in the comments.

To be continued…