Carrier proto

riscv-pico

A Raspberry Pi Pico running real Linux, with its own keyboard and screen.
The RP2040 emulates a RISC-V CPU, SPI PSRAM becomes system memory,
and the Linux guest drives real GPIO pins.

Website • Try it • How it works • Build one • Programming • Downloads • PLAN.md

The story, photos, full pin map and wiring diagrams: flyboy-byte.github.io/riscv-pico

[!NOTE] This is a build log, not an upstream improvement. It's my own vibe-coded "Linux on a Pico" project — the real projects below did the hard work; this repo forks, ports, and glues them together and writes down what happened. Posted in case it's useful to someone chasing the same idea. The code, docs, and this README were written by Claude Code; I directed it, tested on real hardware, and made the calls.

Built on

Go star their repos, not this one.

The short version

A Pico has no MMU and about 264 KB of RAM. It was never meant to run an operating system. So: core 1 of the RP2040 runs a full RV32IMA interpreter, two SPI PSRAM chips stand in for system memory, and an SD card holds the kernel and root filesystem. Linux boots on top of that — and custom kernel drivers let the guest reach back out through the emulator to drive real hardware.

Add a PS/2 keyboard, a VGA monitor and a breadboard power supply, and it runs with no computer attached. You can write a program in nano on the Pico, run it, and have it blink an LED.

_{The OLED is reporting on the machine it's plugged into: 16 MB across 2 chips, live MIPS, uptime, 400 MHz clock.}

And running on its own: PS/2 keyboard in, VGA monitor out, no PC anywhere.

sysinfo: Linux 6.6 on an emulated RV32, 14 MB of RAM	GNU nano editing hello.c, full screen
Tiny BASIC, then c4 compiling and running that hello.c	Minesweeper, in Lua

Status

What's actually verified, versus what merely compiles. No wishful thinking in this table.

Try it in 60 seconds (no hardware)

A desktop build of the real emulator core, booting the same SD card image the Pico uses.

git clone https://github.com/flyboy-byte/riscv-pico && cd riscv-pico
harness/build.sh

mkdir images
REL=https://github.com/flyboy-byte/riscv-pico/releases/download/sdcard-v2
curl -L $REL/riscv-pico-sdcard-v2.tar.gz | tar xz -C images

# lay the three files out on a FAT image, the way the firmware expects
dd if=/dev/zero of=harness/disk.img bs=1M count=80
mformat -F -i harness/disk.img ::
mcopy -i harness/disk.img images/IMAGE images/DTB images/ROOTFS ::

python3 harness/desktop_terminal.py harness/disk.img

Needs mtools, plus PyQt6 and python-pyte (sudo pacman -S python-pyte on Arch). Boots to a shell in a couple of seconds. Then try:

[!IMPORTANT] These images won't boot under stock mini-rv32ima. This project's emulator core adds custom block-device and console CSRs that upstream doesn't implement, so harness/build.sh builds this repo's own desktop copy of the real core instead. Background in CLAUDE.md.

How it actually works

The interesting part isn't that Linux boots. It's that the emulated guest can reach real hardware — so echo 1 > /sys/class/gpio/gpio512/value, typed into a Linux shell, ends with current flowing out of a physical pin.

┌─────────────────────────────────────────────────────────────────┐
│  RISC-V Linux guest                                 (emulated)  │
│                                                                 │
│      shell  ·  BASIC  ·  Lua  ·  c4  ·  nano                    │
│                       │                                         │
│      Linux 6.6, nommu, RV32IMA                                  │
│                       │                                         │
│      drivers:  gpio-tinyrv32  ·  block  ·  console              │
└───────────────────────┬─────────────────────────────────────────┘
                        │   CSR instructions   (GPIO = 0x1a0-0x1a3)
┌───────────────────────┴─────────────────────────────────────────┐
│  RP2040  @ 400 MHz                              (real silicon)  │
│                                                                 │
│      core 1  ──▶  tiny-rv32ima, the RV32IMA interpreter         │
│      core 0  ──▶  CSR handlers, VGA, PS/2, OLED                 │
└───────────────────────┬─────────────────────────────────────────┘
                        │
     ┌──────────────────┼──────────────────┬──────────────────┐
     ▼                  ▼                  ▼                  ▼
 2x SPI PSRAM      microSD card        GPIO pins        console I/O
 16 MB = RAM     kernel + rootfs     LEDs, buttons    PS/2, VGA, OLED

Linux sees ordinary devices — a block device, a gpiochip, a console. The RP2040 does the translating underneath. Full GPIO walkthrough, including wiring an LED and the exact ioctls, is in docs/GPIO_AND_BASIC_TUTORIAL.md. The website draws the whole machine, including where the 16 MB of memory actually lives.

Build one yourself

The whole path, start to finish. No compiler needed: the firmware and the SD card image are both prebuilt.

Parts — about $20 for the core

Everything here is what's on the verified build. No minimum order quantities, all single-quantity friendly. Prices drift; this isn't a live feed.

To run it without a PC, add:

[!CAUTION] Get the -SN (SOP-8) suffix, not -ZR. Same silicon, but -ZR is USON-8 — a 3×2 mm leadless package that is genuinely painful to hand-solder or rework. Plain APS6404L-3SQR with no suffix is bare die, not a packaged part at all.

Substitutes work fine. ESP-PSRAM64H, LY68L6400, and IPUS equivalents share the SOP-8 pinout and the 0x5D known-good-die ID the firmware checks for. For stock across distributors, try Findchips or Octopart.

Wiring

The core build is 3.3 V native and its console is USB serial, so no adapter is needed. The website has the full 40-pin map, a power and ground diagram, and a VGA wiring bench card.

[!WARNING] On the SD card module, MOSI and CLK cross over. The module's header order does not match the Pico's pin order. This is the single easiest mistake to make on the whole board, and it costs you an afternoon.

[!WARNING] The PS/2 keyboard runs at 5 V, and RP2040 pins are not 5 V tolerant. Route CLK and DATA through the level converter. Before the Pico is connected, meter the converter's low-voltage outputs: they must idle at 3.3 V, never 5 V. A resistor divider does not work on this bus.

[!WARNING] Breadboard power is the thing that will actually bite you. Wiring up the OLED destabilised the PSRAM bus and crashed boot — despite the two sharing no GPIO pins at all. The cause was a single 3V3 supply pin feeding PSRAM VCC, both chips' pull-ups, the SD card and the OLED, so any load spike on that node bled into everything else on it.

The fix was a single-point (star) power layout: separate supply for OLED/SD, PSRAM on its own clean VCC/GND, short jumpers, and decoupling caps at each chip's supply pins. If you see random resets or PSRAM failures that only appear once a second peripheral is wired up, check power distribution before you suspect the chip. Full writeup — including the wrong theories tried first — in PLAN.md and docs/HARDWARE_SCHEMATIC.md.

Firmware

Just want to flash something? Grab pico-rv32ima-boards-v6 — prebuilt .uf2 for all four board variants, ready to go. It includes the VGA, PS/2 and OLED consoles, and a VGA terminal that full-screen programs like nano can draw on.

# once — Pico SDK, shallow clone with just the tinyusb submodule (~65 MB)
git clone -b 2.1.1 --depth 1 https://github.com/raspberrypi/pico-sdk.git ~/pico-sdk
git -C ~/pico-sdk submodule update --init --depth 1 lib/tinyusb

firmware/build.sh              # all four boards → firmware/out/*.uf2
firmware/build.sh pico2_w      # or just one

SD card

1. Format a 4–32 GB microSD card as FAT32.
2. From sdcard-v2, download IMAGE, DTB and ROOTFS. The same three files are also bundled as riscv-pico-sdcard-v2.tar.gz.
3. Copy all three to the root of the card, not into a folder. Their names must stay exactly as they are.

First boot

Plug the Pico into a PC over USB and open its serial console: screen /dev/ttyACM0 115200 on Linux, or PuTTY on the new COM port on Windows. With the VGA screen attached you can skip this and watch the monitor instead.

1. The console prints PSRAM OK, then SD init OK, and waits for a keypress. Press any key, on the serial console or on the PS/2 keyboard. On the VGA screen, all you see before that is the pico-rv32ima, compiled … banner.
2. Loading kernel image, then Starting RISC-V VM, then the Linux boot log.
3. A ~ # shell prompt, in well under a minute. Try sysinfo.

Before unplugging, type halt, or at least sync. The root filesystem is ext2 and doesn't survive a hard power-off well.

Programming on the Pico

You can write and run programs on the machine itself: open a file in nano, save it, run it. No PC.

Every command for all of this is on one page in docs/CHEATSHEET.md. A shorter copy sized for the VGA screen is on the card: nano -v /root/help.txt pages through it when there's no PC attached.

The examples are in /root on the SD image. Blinking an LED in Lua looks like this:

local function put(path, text)
  local f = io.open(path, "w"); f:write(text); f:close()
end

put("/sys/class/gpio/export", "512")                 -- GPIO line 0 = Pico GP1, pin 2
put("/sys/class/gpio/gpio512/direction", "out")
for i = 1, 10 do
  put("/sys/class/gpio/gpio512/value", "1"); sys.sleep(0.2)
  put("/sys/class/gpio/gpio512/value", "0"); sys.sleep(0.2)
end
put("/sys/class/gpio/unexport", "512")               -- release it, or gpioset says busy

There's a game, too: lua /root/mines.lua is minesweeper on the VGA screen. Arrow keys move, space digs, f flags, r restarts, q quits. Board size is optional — lua /root/mines.lua 20 14 40. Single keypresses need sys.raw(), another call the Lua build adds; where that isn't available it falls back to typed commands, so it works over a pipe too.

os.execute and io.popen don't work from Lua here: they need fork(), which a no-MMU machine doesn't have. Details on c4's language and limits are in apps/c4/README.md.

Downloads

Build outputs ship as GitHub releases rather than committed binaries, which keeps git clone fast.

Firmware -v5 boots sdcard-v2, but nano on its VGA screen is unusable. -v3/-v4 still boot too. -v1/-v2 are superseded single-chip 8 MB builds that don't boot the current rootfs.

Repo layout

All three upstream/ paths are git subtrees with full history, so git log -- upstream/<x> works and upstream changes can still be pulled — commands in CLAUDE.md.

PLAN.md is the living state doc — every decision, every bug, every dead end, and what's next. It's far more detailed than this file.

License

This repo's own code (harness/, apps/, firmware/, buildroot-overlay/, site/, docs) is MIT — see LICENSE — except apps/c4/, which is GPL-2.0 like the c4 it comes from. Everything under upstream/ keeps its original licensing (MIT / Apache-2.0 / BSD-3); see the LICENSE in each subtree.