DEV Community: l5y

ArduLinux: running Arduino firmware on Linux

l5y — Mon, 01 Jun 2026 21:32:56 +0000

I'm writing this from a mesh repeater that has no microcontroller in it. It's a Linux box running MeshCore firmware natively, the same C++ that would normally live on an nRF52 or ESP32, compiled and running as an ordinary Linux process, talking to a real SPI radio. The thing that makes that possible is a small library called ArduLinux, and this post is the story of why it exists.

The idea: the Arduino API, as a Linux library

Embedded firmware is written against the Arduino API, digitalWrite(), SPI.transfer(), Serial.printf(), Wire.begin(), and friends. ArduLinux implements that API as a Linux user-space library, so firmware written for microcontrollers builds and runs on a PC or a Raspberry Pi unmodified. It wires the Arduino calls to real hardware, GPIO via libgpiod, SPI via spidev, I2C via i2c-dev, Serial via POSIX file descriptors, or to fully simulated devices when you just want to run in CI.

Using it is one block of platformio.ini:

[env:ardulinux]
platform = git+https://github.com/l5yth/ardulinux.git
framework = arduino
board = ardulinux

That's it. Your setup() and loop() run on Linux.

Standing on portduino's shoulders

None of this is a new idea. ArduLinux is a clean-room continuation of portduino, the project (from the Meshtastic world, Kevin Hester, Jonathan Bennett, and many others) that pioneered running Arduino firmware on Linux. Portduino did the genuinely hard part: proving the approach works and carrying it for years. I want to be clear up front, this is a continuation written in gratitude, not a complaint.

But when I went to use portduino as a dependency for a fresh project, I kept tripping over the same thing: it was held together with patches.

The monkey-patch problem

Here's the concrete example that started it. The upstream ArduinoCore-API Print class gives you print() and println(), but no printf(). Tons of firmware (MeshCore included) calls Serial.printf(...). Upstream hasn't added it. So you have to shim it in somewhere.

The way that shim had grown was, roughly:

# Copy the ENTIRE upstream API tree, minus Print.h...
shutil.copytree(upstream_api, "patched_api", ignore=ignore_patterns("Print.h"))
# ...then drop in our own hand-edited Print.h that adds printf().
write_patched_print_h("patched_api/Print.h")

Look at what that actually does: to add one method, you make a full, divergent copy of the upstream library at build time. And it wasn't only Print.h, the dependencies themselves (ArduinoCore-API, the WiFi library) were vendored as copied-and-patched source trees rather than tracked upstream.

That pattern has three nasty consequences:

You can't follow upstream. The pinned ArduinoCore-API had fallen ~180 commits behind, and bumping it meant re-doing the patches by hand. So nobody bumped it.
The copy silently goes stale. The cached copy keyed on a path, not a version, so after a bump it could happily keep serving the old copy, and you'd never know.
Bugs hide in the machinery. When the build is this baroque, latent bugs go unnoticed. (More on the two I found below.)

The general principle, and it applies to every monkey-patched library, not just this one: the moment you copy-and-edit a dependency, you've silently forked it, and given up the one thing a dependency is supposed to give you, which is the ability to pull upstream's fixes.

Why not just fix it inside portduino?

Fair question, and I tried to convince myself it was the right move. It wasn't, for two reasons.

It's structural, not cosmetic. The vendoring and the copytree shim weren't a bad function you could rewrite over a weekend; they were baked into the architecture, the package layout, the builder, the dependency model. Undoing them properly means re-laying the foundation. That's not a patch, it's a different building.

portduino is load-bearing for other people. It's a live dependency of Meshtastic. A sweeping "rip out the vendoring and rewrite the build" change against a tree that thousands of devices depend on is exactly the kind of disruptive churn you shouldn't push onto a working project to suit your own narrower goals.

So I did the open-source thing: fork, clean up, and present. A continuation lets you re-establish the invariant, depend on upstream, unmodified, from a clean slate, without destabilizing anyone who's happy with what they have. If it's useful to others, wonderful. If not, portduino is right where it was.

What changed in ArduLinux

The whole renovation is in service of one rule: clean upstream dependencies, and isolate the single unavoidable shim.

Dependencies are real git submodules, tracked at their upstream commits, not copied, not patched. Bumping ArduinoCore-API from 1.1.0 to 1.5.2 became a one-line gitlink change instead of a manual re-patching session.
The printf shim is now a symlink overlay. Instead of copying the whole API and stripping a file, every upstream header is symlinked as-is, and we shadow exactly one file, Print.h, re-synced verbatim from upstream with the printf() method added. No copy, nothing to drift.

# Symlink every upstream header as-is, the real files, never copied...
for name in upstream_headers:
    os.symlink(upstream / name, overlay / name)
# ...and shadow ONLY Print.h: the one minimal, honest shim.

Dead code and clutter removed, out-of-line duplicates, unused board variants, IDE project files.

And the payoff that justifies the whole exercise: with the build no longer hiding things, two real bugs surfaced and got fixed.

#71 An I2C handle defaulted to file descriptor 0, stdin, so a read before begin() would silently block on the terminal forever. (It now defaults to -1 and fails fast, like the serial port already did.)
#72 The printf shim trusted vsnprintf's return value, which is the length it would have written, a classic buffer over-read on long strings. (Now clamped; verified under AddressSanitizer.)

Neither was introduced by the cleanup; both were lurking. Simpler machinery just made them visible.

Room to add new things

Tidying the dependency story is only half of why the fork was worth it. The other half: once you own the runtime outright, you can make it behave like a proper Linux program.

Binary customization. An app sets its own name, version, description, and bug-report address through a few optional weak symbols, no header required. It then introduces itself in its startup banner and --version, names its data directory after itself, and labels its libgpiod lines with it. meshcored shows up as meshcored, not a generic program.
XDG-compliant data directories. The virtual filesystem lives where a well-behaved Linux app keeps state, $XDG_DATA_HOME/<app>/default (so ~/.local/share/meshcored/...), instead of scattering dotfiles across $HOME.
A real command line. --fsdir to relocate that state, --erase to wipe it on startup, plus the usual --version, --help, and --usage.

And the list keeps growing, because now there's somewhere natural to put it. So I'd gently resist the idea that this was only about chasing upstream versions: tracking upstream cleanly is the discipline that made the rest possible, but the visible, day-to-day payoff is a binary that starts up, stores data, and takes its flags like every other tool on the box.

The proof

The real test wasn't the unit suite, it was whether a downstream project could actually consume this. So I pointed my MeshCore-Linux branch at the first release tag v0.2.0 as a pinned dependency and rebuilt.

It worked out of the box. I'm running a Linux-native MeshCore repeater on it right now, no complaints. That's the moment the whole "clean dependencies" thesis stopped being a principle and became a working radio on my desk.

Try it

ArduLinux is on the PlatformIO registry and GitHub, LGPL-2.1, built on the work of the Arduino project, the portduino authors, and everyone who came before this split. If you've got embedded C++ you'd like to run, test, or debug on a real Linux machine, with gdb, with sanitizers, in CI, on actual GPIO, give it a spin:

git clone --recurse-submodules https://github.com/l5yth/ardulinux.git
cmake -B build && cmake --build build
./build/ArduLinux --help

That's the spirit of open source: you fork, you clean up, you present, and you see if anyone else finds it useful. Maybe you will.

Enabling SPI on Arch Linux ARM (Raspberry Pi 4, aarch64)

l5y — Mon, 01 Jun 2026 16:06:59 +0000

You add dtparam=spi=on to /boot/config.txt, reboot, and... there's no /dev/spidev*. On the AArch64 Arch Linux ARM image this is expected, and the fix isn't more config.txt tweaking. Here's the clean way.

TL;DR

The AArch64 ALARM image boots the mainline kernel via U-Boot, which ignores config.txt. Switch to the Foundation kernel (linux-rpi) and SPI + overlays work natively. One board-specific trap to watch: the shipped cmdline.txt has the wrong root=.

ℹ️ Tested on: Raspberry Pi 4B, Arch Linux ARM aarch64, /boot on a separate FAT partition.

Why `dtparam=spi=on` does nothing

The GPU firmware reads config.txt and patches its own device tree, but U-Boot then loads a different mainline DTB from /boot/dtbs and boots that, throwing the firmware's edit away. Forcing the firmware DTB doesn't help either: the mainline spidev driver won't bind to its compatible = "spidev" nodes.

The Foundation kernel sidesteps all of it: the firmware boots it directly and applies config.txt + overlays the way every Pi guide assumes.

⚠️ This swaps your kernel and removes U-Boot. Keep a serial/HDMI console or SD-card access handy in case of a bad boot.

0. Prep

# Note your real root partition, you'll need this exact value in step 2.
cat /proc/cmdline                       # grab the root=PARTUUID=... part
lsblk -o NAME,PARTUUID,MOUNTPOINT

# Back up /boot and cache the current packages for rollback.
sudo tar czf /root/boot-backup.tar.gz -C /boot .
sudo pacman -Sw linux-aarch64 uboot-raspberrypi

1. Install the Foundation kernel

sudo pacman -S linux-rpi

It conflicts with uboot-raspberrypi and linux-aarch64 and removes both, that's expected. It drops in the Foundation kernel as /boot/kernel8.img, ~360 overlays, and fresh config.txt / cmdline.txt.

2. Fix `cmdline.txt`, the one guaranteed gotcha

The shipped /boot/cmdline.txt hardcodes root=/dev/mmcblk0p2. If your card enumerates differently (mine is mmcblk1), that's an instant no-boot. Replace the root= with your value from step 0:

# /boot/cmdline.txt  (single line)
root=PARTUUID=xxxxxxxx-02 rw rootwait fsck.repair=yes console=serial0,115200 console=tty1

Use blkid to determine UUID.

3. Re-enable SPI in `config.txt`

The new config.txt ships with SPI commented out. Add:

# /boot/config.txt
enable_uart=1
dtparam=spi=on

4. Sanity-check before rebooting

Can't hurt to run mkinitcpio -p linux-rpi again.

ls -l /boot/kernel8.img            # multi-MB = Foundation kernel (U-Boot was ~700 KB)
grep root= /boot/cmdline.txt       # YOUR PARTUUID, not mmcblk0p2
grep -E 'spi|initramfs' /boot/config.txt
ls -l /boot/initramfs-linux.img    # freshly rebuilt
ls /lib/modules/                   # e.g. 6.x-rpi

5. Reboot & verify

sudo reboot
# once it's back:
uname -r                           # ...-rpi
ls -l /dev/spidev*                 # spidev0.0  spidev0.1

6. Optional: use SPI without root

# /etc/udev/rules.d/99-spi.rules
SUBSYSTEM=="spidev", GROUP="spi", MODE="0660"

sudo groupadd -f spi && sudo usermod -aG spi "$USER"   # re-login to apply

Quick loopback test: jumper pin 19 ↔ pin 21 (MOSI↔MISO) and run spidev_test, TX should equal RX.

SPI0 pinout (40-pin header)

Signal	BCM	Pin
MOSI	GPIO10	19
MISO	GPIO9	21
SCLK	GPIO11	23
CE0	GPIO8	24 → `spidev0.0`
CE1	GPIO7	26 → `spidev0.1`

Rollback

If it won't boot: pull the SD card, restore /boot from boot-backup.tar.gz, and reinstall linux-aarch64 + uboot-raspberrypi from the pacman cache.

Bonus: now that the firmware honors config.txt, other peripherals are one line away too, dtparam=i2c_arm=on for I2C, or any overlay in /boot/overlays via dtoverlay=.... No device-tree surgery required.

psn - a minimalist process navigator for Linux

l5y — Sat, 07 Mar 2026 15:45:40 +0000

When a process hangs up on me on a server, my usual workflow is a mix of ps aux | grep, pgrep, copying PIDs, and reaching for kill. It works, but it interrupts my workflows. I decided to go for a little quality-of-life upgrade and implement psn, the process status navigator.

psn is a small Rust TUI. You launch it, find the process, and send it a signal; all without leaving the terminal or typing a PID by hand.

The problem it solves

The command-line is where I spend most of my time and earn a living: personal laptops, remote servers, etc. The tooling story for process management is surprisingly fragile. I started to become a power user of btop, my favorite *top-derivate, but kept falling back to ps when I had to deal with processes. However, its output is a wall of text that you have to mentally parse or pipe through grep and then act on with a subsequent command.

The real need is simple: find a process by name and send it a signal. It cannot be so hard? ;)

What it does

psn displays a table of running processes inside a navigatable terminal user interface. Each row of the table shows the process name, PID, user, CPU and memory usage, status, and the full command string. Processes are arranged in a parent–child tree so you can see what spawned what.

From there you can:

Navigate with arrow keys up/down and page up/down
Collapse and expand subtrees with arrow keys left/right
Filter on the fly by pressing / and typing - the list narrows as you type, and matched text is highlighted in the name and command columns
Pre-filter at launch by passing a substring (psn cargo) or a regular expression (psn -r '^rust') as an argument
Send a signal by pressing 1 through 9; the key maps directly to the Unix signal number - 9 is SIGKILL, 1 is SIGHUP, 2 is SIGINT, and so on

That's it. I didn't ask for more and I also don't think it needs more.

Installation

The fastest path is via crates.io:

cargo install psn

On Arch Linux the psn-bin AUR package installs a prebuilt binary:

yay -S psn-bin

Or build from the GitHub repository directly with cargo build --release. A Nix flake and a Gentoo ebuild are also available.

The only runtime dependency is a GNU/Linux system with procfs support. No ps wrapper, no external binaries - process data is read directly via sysinfo.

If you spend any meaningful time on Linux servers and find yourself reaching for ps | grep | kill more than you'd like, give psn a try. Feedback and issues are welcome!