Debug the Raspberry Pi Pico running Zephyr RTOS on MacOS

When resolving bugs in your code or wanting to understand the flow of your application, debugging helps a lot better than just using log messages.

In this tutorial you will install the needed software and configure it, so you can develop Zephyr RTOS applications with the Raspberry Pi Pico.

Install Homebrew

Homebrew is a package management system which we will use to install missing software to your mac.

Open a terminal window and paste

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

then press Enter. Now follow the instructions shown in your terminal.

Install Zephyr 3.2.0

(Click here for the latest guide by the Zephyr project and further information)

Install the missing dependencies with Homebrew. Paste the following command in your terminal window

brew install cmake ninja gperf python3 ccache qemu dtc wget libmagic

We will use a virtual environment, so run the following command to create it

python3 -m venv ~/zephyrproject/.venv

Then activate it (you will need to activate it every time you open a new terminal).

source ~/zephyrproject/.venv/bin/activate

Install west

pip install west

Initialise the Zephyr Project

west init ~/zephyrproject
cd ~/zephyrproject
west update

Export a Zephyr CMake package

west zephyr-export

Install additional Python dependencies

pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

Download and verify the Zephyr SDK for Intel x86 Macs:

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.15.2/zephyr-sdk-0.15.2_macos-x86_64.tar.gz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.15.2/sha256.sum | shasum --check --ignore-missing

Extract it

tar xvf zephyr-sdk-0.15.2_macos-x86_64.tar.gz

Or: Download and verify the Zephyr SDK for M1/M2 Arm Macs:

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.15.2/zephyr-sdk-0.15.2_macos-aarch64.tar.gz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.15.2/sha256.sum | shasum --check --ignore-missing

Extract it

tar xvf zephyr-sdk-0.15.2_macos-aarch64.tar.gz

Note: It is recommended to extract the Zephyr SDK bundle at one of the following locations:

• $HOME
• $HOME/.local
• $HOME/.local/opt
• $HOME/bin
• /opt
• /usr/local

Run the setup script:

cd zephyr-sdk-0.15.2
./setup.sh

To test if everything works, we build the blinky example:

cd ~/zephyrproject/zephyr
west build -p always -b rpi_pico samples/basic/blinky

Install tools to use the Raspberry Pi Debug Probe

(See here for the latest instructions)

Install open-ocd via Homebrew

brew install open-ocd

Install GDB for Intel x86 Macs:

brew install gdb

Or: Install (Arm) GDB for M1/M2 Arm Macs (currently GDB is not available via Homebrew for Arm Macs)

brew tap eblot/armeabi
brew install arm-none-eabi-gdb

Connect the Raspberry Pi Pico and Raspberry Pi Debug Probe

Serial Debug Signal:

• The Debug Probe "D" connector -> Pico H SWD JST connector

OR, if you don't have a Raspberry Pi Pico without a JST connector:

• The Debug Probe "D" connector GND (black cable) -> GND
• The Debug Probe "D" connector SD (bidirectional serial data) (red cable) -> SWDIO
• The Debug Probe "D" connector SC (serial clock) (yellow cable) -> SWCLK

UART Signal:

• The Debug Probe "U" connector GND (black cable) -> GND
• The Debug Probe "U" connector TX (red cable) -> GP1/UART0 RX
• The Debug Probe "U" connector RX (yellow cable) -> GP0/UART0 TX

Alternative: Connect the Raspberry Pi Pico and a second Raspberry Pi Pico with picoprobe

When you don't have a Raspberry Pi Debug Probe you can use a second Raspberry Pi Pico for debugging an application.

Download the latest Pico Probe firmware (picoprobe.uf2 file) here. Put the Raspberry Pi Pico in firmware upload mode by pressing the bootsel pin while connecting it to the USB cable. Copy the firmware to the automatically mounted USB mass storage device.

Now connect the Pico Probe (Pico A) to the Raspberry Pi Pico (Pico B):

• Pico A GND -> Pico B GND
• Pico A GP2 -> Pico B SWCLK
• Pico A GP3 -> Pico B SWDIO
• Pico A GP4/UART1 TX -> Pico B GP1/UART0 RX
• Pico A GP5/UART1 RX -> Pico B GP0/UART0 TX
• Optional: Pico A VSYS -> Pico B VSYS

⚠️ IMPORTANT If Pico B is a USB Host then you must connect VBUS to VBUS, not VSYS to VSYS, so that Pico B can provide 5V on its USB connector. If Pico B is using USB in device mode, or not using its USB at all, this is not necessary.

From https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf Page 65f.)

Build blinky example and debug it via gdb

Compile the blinky app with debug informations for open-ocd

cd ~/zephyrproject/zephyr
rm -rf build
west build -p always -b rpi_pico --force samples/basic/blinky -- -DOPENOCD=/opt/homebrew/bin/openocd -DOPENOCD_DEFAULT_PATH=/opt/homebrew/Cellar/open-ocd/0.12.0/share/openocd/scripts -DRPI_PICO_DEBUG_ADAPTER=cmsis-dap

(Maybe you have to pass other paths to open-ocd. Have a look at the parameter -DOPENOCD and -DOPENOCD_DEFAULT_PATH)

Flash the blinky example

west flash

Start the open-ocd server

openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000"

Open an other terminal window, navigate to the ~/zephyrproject/zephyr folder and run gdb

arm-none-eabi-gdb build/zephyr/zephyr.elf

Now run

target remote localhost:3333
monitor reset init
continue

If this was successful, we can now configure VS Code for debugging!

Configure VS Code

If you haven't installed VS Code yet, you can download it from https://code.visualstudio.com/download.

Now open VS Code and open the ~/zephyrproject/zephyr/samples/basic/blinky folder, as shown in the picture above.

We need to install the Cortex-Debug-extension. You can install it via the extension menu, as shown above or click install in the market place website here.

Now click on the launch menu button on the left, click on create a launch json file and choose Cortex Debug or create a launch.json file in the .vscode directory.

The launch json file should be opened. Change the content to:

{
    "version": "0.2.0",
    "configurations": 
    [
        {
            "name": "Pico Zephyr Debug",
            "cwd": "${workspaceRoot}",
            "executable": "build/zephyr/zephyr.elf",
            "request": "launch",
            "type": "cortex-debug",
            "servertype": "openocd",
            "gdbPath": "arm-none-eabi-gdb",
            "device": "RP2040",
            "configFiles": [
                "interface/cmsis-dap.cfg",
                "target/rp2040.cfg"
            ],
            "svdFile": "${workspaceFolder}/../../../modules/hal/rpi_pico/src/rp2040/hardware_regs/rp2040.svd",
            "runToEntryPoint": "main",
            "postRestartCommands": [
                "break main",
                "continue"
            ],
            "openOCDLaunchCommands": [
                "adapter speed 5000"
            ],
            "preLaunchTask": "Flash"
        }
    ]
}

Now create a tasks.json file in the .vscode directory and paste the following content

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "SetEnv",
            "type": "shell",
            "command": "west",
            "args": [
                "config",
                "zephyr.base","${workspaceFolder}/../../../../zephyr"
            ],
            "options": {
                "statusbar": {
                  "hide" : true
                }
              },
            "group": "test"
        },
        {
            "label": "Build",
            "dependsOn": [
				"SetEnv"
			],
            "type": "shell",
            "command": "west",
            "args": [
                "build",
                "-p","auto",
                "-b","rpi_pico",
                "--force",
                ".",
                "--",
                "-DOPENOCD=/opt/homebrew/bin/openocd",
                "-DOPENOCD_DEFAULT_PATH=/opt/homebrew/Cellar/open-ocd/0.12.0/share/openocd/scripts", 
                "-DRPI_PICO_DEBUG_ADAPTER=cmsis-dap"
            ],
            "options": 
            {
                "cwd": "${workspaceFolder}",
                "env": {
                    "ZEPHYR_TOOLCHAIN_VARIANT": "zephyr",
                    "ZEPHYR_SDK_INSTALL_DIR": "${env:HOME}/zephyr-sdk-0.15.2"
                }
            },
            "problemMatcher": {
                "base": "$gcc",
                "fileLocation": [
                    "absolute"
                ]
            },
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Build Verbose",
            "dependsOn": [
				"SetEnv"
			],
            "type": "shell",
            "command": "west",
            "args": [
                "-v",
                "build",
                "-p","auto",
                "-b","rpi_pico",
                "--force",
                ".",
                "--",
                "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
                "-DOPENOCD=/opt/homebrew/bin/openocd",
                "-DOPENOCD_DEFAULT_PATH=/opt/homebrew/Cellar/open-ocd/0.12.0/share/openocd/scripts", 
                "-DRPI_PICO_DEBUG_ADAPTER=cmsis-dap"
            ],
            "options": 
            {
                "cwd": "${workspaceFolder}",
                "env": {
                    "ZEPHYR_TOOLCHAIN_VARIANT": "zephyr",
                    "ZEPHYR_SDK_INSTALL_DIR": "${env:HOME}/zephyr-sdk-0.15.2"
                }
            },
            "problemMatcher": {
                "base": "$gcc",
                "fileLocation": [
                    "absolute"
                ]
            },
            "group": "build"
        },
        {
            "label": "Clean",
            "dependsOn": [
				"SetEnv"
			],
            "type": "shell",
            "command": "west",
            "args": [
                "build",
                "-p","auto",
                "-b","rpi_pico",
                "-t","clean",
                "--force",
                ".",
                "--",
                "-DOPENOCD=/opt/homebrew/bin/openocd",
                "-DOPENOCD_DEFAULT_PATH=/opt/homebrew/Cellar/open-ocd/0.12.0/share/openocd/scripts", 
                "-DRPI_PICO_DEBUG_ADAPTER=cmsis-dap"
            ],
            "options": 
            {
                "cwd": "${workspaceFolder}",
                "env": {
                    "ZEPHYR_TOOLCHAIN_VARIANT": "zephyr",
                    "ZEPHYR_SDK_INSTALL_DIR": "${env:HOME}/zephyr-sdk-0.15.2"
                }
            },
            "group": "build"
        },
        {
            "label": "Flash",
            "dependsOn": [
				"Build"
			],
            "type": "shell",
            "command": "west",
            "args": [
                "flash"
            ],
            "options": 
            {
                "cwd": "${workspaceFolder}",
                "env": {
                    "ZEPHYR_TOOLCHAIN_VARIANT": "zephyr",
                    "ZEPHYR_SDK_INSTALL_DIR": "${env:HOME}/zephyr-sdk-0.15.2"
                }
            },
            "problemMatcher": {
                "base": "$gcc",
                "fileLocation": [
                    "absolute"
                ]
            },
            "group": "build"
        }
    ]

(The tasks are based on the tutorials from MrGreenWorkshop)

Maybe you have to change the paths for your openocd installation.

Now add a settings.json file to your .vscode directory and paste

{
    "cortex-debug.openocdPath": "/opt/homebrew/bin/openocd",
}

Test your configurations:

• Open the Command Palette with the shortcut ⇧⌘P
• Search for task and choose Tasks: Run task
• Next, choose Build
• Now you should see output in the integrated terminal
• If it wasn't successful, have a look at the error messages. Maybe some paths aren't correct - Fix them and try again
• Next try the Flash task

Now you're ready for debugging!

Debugging with VS Code

Now add some breakpoints to your code. Open the main.c file, click left of the line numbers to add breakpoints.

Open the Run and Debug menu, then launch Pico Zephyr Debug. Now the program should be build and flashed to the Raspberry Pi Pico and the breakpoint should be hit soon.

Well done! You now can debug Zephyr RTOS applications on the Raspberry Pi Pico using VS Code on macOS! 🎉

Bonus Tips:

Serial connection:

To see the serial output you can use CoolTerm. You can install it via Homebrew

brew install --cask coolterm

Or use the Serial Monitor extension in VS Code.