MCU Programmer

MCU programmer/debugger running wirelessly on a Raspberry Pi.

Compatible Raspberry Pi models:

• Raspberry Pi 3
• Raspberry Pi 4
• Raspberry Pi 5
• Raspberry Pi Zero 2 W (cheapest and preferred option)

Raspberry PI SWD pinout

• ✱ Required
• RESET is optional
• UART RX is for optional serial debug
• UART TX should not be connected

Usage

Program from remote:

arm-none-eabi-gdb -ex="target remote mcuprogrammer.local:3333" my-firmware.elf -ex "load" -ex "monitor reset" -ex "det" -ex "q"

Serial debug

MCU Programmer exposes a network service at port 1337 which echoes all serial messages received on UART RX.

You can connect to this service from a remote machine using netcat:

nc mcuprogrammer.local 1337

Configuration

MCU Programmer can be configured through a telnet service running on port 8888.
Connect to the service:

telnet mcuprogrammer.local 8888

Trying mcuprogrammer.local...
Connected to mcuprogrammer.local.
Escape character is '^]'.
Connected to MCU Programmer CLI. Type 'help' for a list of commands

Target device can be set with the target command:

target rp2040

MCU Programmer supports every target supported by the latest build of OpenOCD.

The baud rate for serial debugging can be set with the baudrate command:

baudrate 115200

Install

Prerequisites

• Raspberry PI 3/4/5/Zero 2 W
• Latest MCU Programmer image (no need to unzip)
• Raspberry Pi Imager

Flash SD card

1. Open Raspberry Pi Imager
2. Click CHOOSE OS
3. Click Use Custom and select the MCUProgrammer image downloaded above
4. Click the cogwheel at the bottom right corner
5. Add your Wi-Fi credentials and save
6. Click WRITE
7. Boot your Raspberry PI with the SD card you just flashed

Building locally (for developers)

Build script can be found in .github/workflows/main.yml

Setup build environment

MacOS

Install act and gh:

brew install gh act

Linux (Debian/Ubuntu)

Install Docker:

curl -fsSL https://get.docker.com -o install-docker.sh
sudo sh install-docker.sh

Install act:

cd /
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Install gh:

type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

Building Raspberry PI image

Sign in to git to get access token (this only has to be done once):

gh auth login

Build image:

act -s GITHUB_TOKEN="$(gh auth token)" --artifact-server-path ./build

Connecting to the Raspberry PI

SSH is enabled and can be reached at mcuprogrammer.local:

ssh mcuprogrammer@mcuprogrammer.local

Default username: mcuprogrammer
Default password: mcuprogrammer

Troubleshooting

Case: Host cannot resolve (find) mcuprogrammer.local

Most likely it's an issue with your local network, specificaly a subnet issue. mDNS cannot operate across networks. If your Wi-Fi brodcasts multiple bands on the same SSID, and your computer is on 5GHz and the MCU Programmer is on the 2.4GHz, this could result in them not resolving each others mDNS services.

Solution:

Add a DNS entry in the host machines /etc/hosts file:

[MCU Programmer IP] mcuprogrammer.local

Replace [MCU Programmer IP] with the MCU Programmer IP address on your network.