Status: Functional · Backend QEMU process · WebSocket communication Engine: QEMU 10.0.x (
qemu-system-aarch64 -M raspi3b) Platform: BCM2837 ARM Cortex-A53 @ 1.2 GHz — 64-bit ARMv8, quad-core Runs: Real Raspberry Pi OS (Trixie armhf) + Python scripts — no Arduino compilation needed Available on: all platforms (Windows, macOS, Linux, Docker) Boot files: lazy-fetched from the licence-gated download endpoint at first run, then cached in a named docker volume — see Section 12 and BOOT_IMAGES.md.
- Overview
- Supported Boards
- Emulator Architecture
- System Components
- Boot Sequence — Step by Step
- GPIO Shim — How Python Controls GPIO
- WebSocket Protocol
- Serial Communication (UART)
- Pin Mapping — Physical to BCM GPIO
- Virtual File System (VFS)
- Multi-Board Integration — Pi + Arduino
- Boot Images
- QEMU Launch Command
- Known Limitations
- Differences vs Other Emulators
- Key Files
The Raspberry Pi 3B is a full Linux single-board computer based on the Broadcom BCM2837 SoC (4× ARM Cortex-A53, ARMv8 64-bit). Unlike the other boards in Velxio — which compile and run Arduino C++ code — the Raspberry Pi 3 emulation boots a real Raspberry Pi OS (Trixie) inside QEMU and lets you run Python scripts that interact with GPIO.
There is no compilation step for the Raspberry Pi: you write a Python script in the editor, the backend uploads it to the emulated filesystem, and the Pi OS executes it directly.
| Board | Engine | Location | Language |
|---|---|---|---|
| Arduino Uno / Nano / Mega | avr8js | Browser | C++ (Arduino) |
| Raspberry Pi Pico | rp2040js | Browser | C++ (Arduino) |
| ESP32-C3 / XIAO-C3 | RiscVCore.ts | Browser | C++ (Arduino) |
| ESP32 / ESP32-S3 | QEMU lcgamboa (Xtensa) | Backend WebSocket | C++ (Arduino) |
| Raspberry Pi 3B | QEMU 8.1.3 (raspi3b) | Backend WebSocket | Python |
- No FQBN — no arduino-cli compilation; the board kind has
FQBN = null - Boots a real OS — Raspberry Pi OS Trixie runs inside QEMU; 30–60 s wall for kernel + systemd to reach the autologin prompt (no Pi bootloader to short-circuit early steps; full systemd graph runs)
- Autologin to root — the SD image is pre-baked with a
serial-getty@ttyAMA0.service.d/autologin.confdrop-in (agetty --autologin root), so the user drops into a root shell without typing credentials. The browser canvas IS the authentication boundary. - Python runtime — scripts use
RPi.GPIO(or a compatible shim) to interact with GPIO - Persistent storage — the OS image is a real disk image; a qcow2 overlay is used per session so the base image is never modified
- Multi-board serial — the Pi can communicate with co-simulated Arduino boards via virtual serial lines
 Raspberry Pi 3B |
| Board | QEMU Machine | CPU | Notes |
|---|---|---|---|
| Raspberry Pi 3B | raspi3b |
BCM2837, 4× Cortex-A53 | Full Raspberry Pi OS support |
Raspberry Pi 3B+ and Pi 4 are not currently supported. The
raspi3bmachine type in QEMU closely matches the standard 3B hardware.
Python Script (user writes in editor)
│
▼ (uploaded via WebSocket / VFS)
/home/pi/script.py (inside Raspberry Pi OS)
│
▼ python3 /home/pi/script.py
RPi.GPIO (shim) ← intercepted by gpio_shim.py
│
├── GPIO.output(17, HIGH) → "GPIO 17 1\n" → ttyAMA1 → Backend
│ │
│ ▼
│ gpio_change event
│ WebSocket → Frontend
│ PinManager → LED visual
│
└── Serial.print() → ttyAMA0 → Backend → serial_output → Serial Monitor
The Raspberry Pi uses two independent TCP serial ports exposed through QEMU:
| Channel | QEMU Serial | TCP Port | Purpose |
|---|---|---|---|
| User Serial | -serial tcp:...:N |
dynamic | User print() output and input() — visible in Serial Monitor |
| GPIO Protocol | -serial tcp:...:M |
dynamic | GPIO shim protocol (GPIO <pin> <val>\n) |
Both ports are allocated dynamically at startup to avoid conflicts on the host machine.
| Component | File | Responsibility |
|---|---|---|
QemuManager |
backend/app/services/qemu_manager.py |
Singleton that manages all Pi instances (one per WebSocket client) |
PiInstance |
backend/app/services/qemu_manager.py |
Runtime state for one running Pi: QEMU process, TCP ports, overlay path |
gpio_shim |
backend/app/services/gpio_shim.py |
RPi.GPIO drop-in replacement; speaks the GPIO text protocol over ttyAMA1 |
| WebSocket route | backend/app/api/routes/simulation.py |
GET /api/simulation/ws/{client_id} — bidirectional JSON message bus |
| Component | File | Responsibility |
|---|---|---|
RaspberryPi3Bridge |
frontend/src/simulation/RaspberryPi3Bridge.ts |
WebSocket connection manager; sends/receives JSON messages |
useSimulatorStore |
frontend/src/store/useSimulatorStore.ts |
Zustand store; wires bridge events to board state and pin manager |
useVfsStore |
frontend/src/store/useVfsStore.ts |
Virtual filesystem tree per board; Python script editing |
RaspberryPi3.tsx |
frontend/src/components/components-wokwi/RaspberryPi3.tsx |
React board component (SVG image, 40-pin header) |
boardPinMapping.ts |
frontend/src/utils/boardPinMapping.ts |
Physical pin → BCM GPIO number translation |
1. User clicks "Start" (or "Run")
│
▼
2. SimulatorCanvas detects board kind 'raspberry-pi-3'
→ calls startBoard(boardId)
3. useSimulatorStore calls RaspberryPi3Bridge.connect()
4. Bridge opens WebSocket:
ws://localhost:8001/api/simulation/ws/<boardId>
→ sends { type: 'start_pi', data: { board: 'raspberry-pi-3' } }
5. Backend (simulation.py) routes to:
QemuManager.start_instance(client_id, 'raspberry-pi-3', callback)
6. QemuManager._boot(inst):
a. Ask the BootImageProvider for the Pi 3 image set
(kernel8.img + bcm2710-rpi-3-b.dtb + raspios-trixie-armhf.img).
First call downloads + verifies SHA256 + decompresses .zst —
~30 s cold; subsequent calls hit the cache instantly.
See Section 12 and docs/BOOT_IMAGES.md for the architecture.
b. Allocate two free TCP ports (serial_port, gpio_port)
c. Create qcow2 overlay over the SD image returned by the provider:
qemu-img create -f qcow2 -b raspios-trixie-armhf.img overlay_<id>.qcow2
qemu-img resize overlay_<id>.qcow2 8G (raspi3b requires SD size = power of 2)
d. Launch qemu-system-aarch64 (see Section 13 for full command)
e. Emit { type: 'system', event: 'booting' }
7. Wait ~2 seconds for QEMU to initialize TCP servers
8. QemuManager._connect_serial(inst):
→ Connect to ttyAMA0 TCP socket
→ Start async reader loop (forwards bytes as serial_output events)
→ Emit { type: 'system', event: 'booted' }
9. QemuManager._connect_gpio(inst):
→ Connect to ttyAMA1 TCP socket
→ Start async reader loop (parses "GPIO <pin> <val>\n" lines)
10. Frontend receives 'booted' event
→ Board UI updates to "running" state
→ Serial Monitor shows first Linux kernel output
11. systemd reaches `multi-user.target` and starts
`serial-getty@ttyAMA0.service`, which auto-logs in as root via the
drop-in in `/etc/systemd/system/serial-getty@ttyAMA0.service.d/
autologin.conf` (baked into the SD image by
`scripts/configure-pi3-autologin.sh`).
→ User sees a `root@raspberrypi:~#` prompt on the Serial Monitor.
12. From the prompt, the user runs the uploaded Python script:
→ python3 /home/pi/script.py
(script upload happens via the VFS bridge in step 4-8.)
The gpio_shim.py module is injected into the Raspberry Pi OS at the standard RPi.GPIO installation path:
/usr/local/lib/python3.11/dist-packages/RPi/GPIO.py
When a Python script does import RPi.GPIO as GPIO, it gets this shim instead of the real hardware driver. The shim communicates over /dev/ttyAMA1 (the second QEMU serial port) using a simple text protocol.
Pi → Backend (output state change):
"GPIO <bcm_pin> <0|1>\n"
Example: "GPIO 17 1\n" ← GPIO 17 driven HIGH
Backend → Pi (external input, e.g. button press from canvas):
"SET <bcm_pin> <0|1>\n"
Example: "SET 22 1\n" ← button wired to GPIO 22 pressed
import RPi.GPIO as GPIO
# Numbering mode
GPIO.setmode(GPIO.BCM) # use BCM numbers (GPIO17, GPIO22, ...)
GPIO.setmode(GPIO.BOARD) # use physical pin numbers (11, 15, ...)
# Pin direction
GPIO.setup(17, GPIO.OUT)
GPIO.setup(22, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# Digital output
GPIO.output(17, GPIO.HIGH) # → sends "GPIO 17 1\n" to backend
GPIO.output(17, GPIO.LOW) # → sends "GPIO 17 0\n" to backend
GPIO.output(17, True) # equivalent to GPIO.HIGH
# Digital input
state = GPIO.input(22) # reads last known state (updated by "SET" messages)
# Event detection
GPIO.add_event_detect(22, GPIO.RISING, callback=my_callback)
GPIO.add_event_detect(22, GPIO.FALLING, callback=my_callback)
GPIO.add_event_detect(22, GPIO.BOTH, callback=my_callback)
# PWM (simplified — simulated as digital output)
pwm = GPIO.PWM(18, 1000) # pin 18, 1000 Hz
pwm.start(75) # 75% duty cycle → HIGH (duty > 50% → HIGH, else LOW)
pwm.ChangeDutyCycle(25) # 25% duty cycle → LOW
pwm.stop()
# Cleanup
GPIO.cleanup()
GPIO.cleanup(17) # clean specific pinPWM limitation: The shim does not implement real PWM waveforms. It converts duty cycle to a binary state:
duty > 50→ HIGH,duty ≤ 50→ LOW. Visual LED dimming is not supported for Pi GPIO PWM.
#!/usr/bin/env python3
import time
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(17, GPIO.OUT)
try:
while True:
GPIO.output(17, GPIO.HIGH)
print("LED ON")
time.sleep(1)
GPIO.output(17, GPIO.LOW)
print("LED OFF")
time.sleep(1)
finally:
GPIO.cleanup()All communication between the frontend and backend passes through a single WebSocket connection per board instance.
Endpoint: GET /api/simulation/ws/{client_id}
| Message Type | Payload | Description |
|---|---|---|
start_pi |
{ board: "raspberry-pi-3" } |
Launch QEMU, start the Pi |
stop_pi |
(empty) | Stop QEMU, clean up overlay |
serial_input |
{ bytes: number[] } |
Send bytes to ttyAMA0 (Serial Monitor → Pi) |
gpio_in |
{ pin: number, state: 0|1 } |
Inject external GPIO state (button press from canvas) |
| Message Type | Payload | Description |
|---|---|---|
serial_output |
{ data: string } |
String data from ttyAMA0 (Pi print output) |
gpio_change |
{ pin: number, state: 0|1 } |
A GPIO pin changed state (driven by Python script) |
system |
{ event: "booting"|"booted"|"exited" } |
Boot lifecycle events |
error |
{ message: string } |
Error from QEMU or backend |
The Raspberry Pi 3 exposes two UART ports through QEMU:
| Port | Device | Physical Pins | Role |
|---|---|---|---|
| UART0 (ttyAMA0) | /dev/ttyAMA0 |
GPIO14 (TX), GPIO15 (RX) | User serial — print() output, input(), serial.Serial() |
| UART1 (ttyAMA1) | /dev/ttyAMA1 |
— (internal) | GPIO shim protocol — reserved, not accessible to user scripts |
Anything the Python script writes to stdout or to /dev/ttyAMA0 appears in the Serial Monitor panel:
# stdout (print) — captured automatically
print("Hello from Pi!")
# Direct ttyAMA0 (explicit serial)
import serial
port = serial.Serial('/dev/ttyAMA0', baudrate=9600, timeout=1)
port.write(b"Hello Arduino!\n")Text typed in the Serial Monitor input box is sent to ttyAMA0 as a serial_input message, which the Pi receives via input() or by reading /dev/ttyAMA0.
The Raspberry Pi 3B has a standard 40-pin GPIO header (2 rows × 20 columns). The table below shows the mapping from physical pin number to BCM GPIO number:
| Physical | BCM | Function | Physical | BCM | Function |
|---|---|---|---|---|---|
| 1 | — | 3.3 V | 2 | — | 5 V |
| 3 | 2 | I2C1 SDA | 4 | — | 5 V |
| 5 | 3 | I2C1 SCL | 6 | — | GND |
| 7 | 4 | GPIO | 8 | 14 | UART TX |
| 9 | — | GND | 10 | 15 | UART RX |
| 11 | 17 | GPIO | 12 | 18 | PWM0 |
| 13 | 27 | GPIO | 14 | — | GND |
| 15 | 22 | GPIO | 16 | 23 | GPIO |
| 17 | — | 3.3 V | 18 | 24 | GPIO |
| 19 | 10 | SPI MOSI | 20 | — | GND |
| 21 | 9 | SPI MISO | 22 | 25 | GPIO |
| 23 | 11 | SPI SCLK | 24 | 8 | SPI CE0 |
| 25 | — | GND | 26 | 7 | SPI CE1 |
| 27 | — | ID_SD | 28 | — | ID_SC |
| 29 | 5 | GPIO | 30 | — | GND |
| 31 | 6 | GPIO | 32 | 12 | PWM0 |
| 33 | 13 | PWM1 | 34 | — | GND |
| 35 | 19 | SPI1 MISO | 36 | 16 | SPI1 CE2 |
| 37 | 26 | GPIO | 38 | 20 | SPI1 MOSI |
| 39 | — | GND | 40 | 21 | SPI1 SCLK |
Pins 27 and 28 are reserved for ID EEPROM. Power and GND pins have BCM = —.
// Wire connects physical pin "8" on the Pi board
boardPinToNumber('raspberry-pi-3', '8') // → 14 (BCM GPIO14, UART TX)
boardPinToNumber('raspberry-pi-3', 'GPIO17') // → 17
boardPinToNumber('raspberry-pi-3', 'GND') // → null (not a GPIO)Each Raspberry Pi 3 board instance has its own virtual filesystem tree stored in the useVfsStore Zustand store. This lets you create and edit Python scripts directly in the Velxio editor before they are uploaded to the Pi.
/
└── home/
└── pi/
├── script.py ← main Python script (editable)
└── hello.sh ← example shell script
#!/usr/bin/env python3
import time
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(17, GPIO.OUT)
while True:
GPIO.output(17, GPIO.HIGH)
print("LED on")
time.sleep(1)
GPIO.output(17, GPIO.LOW)
print("LED off")
time.sleep(1)const vfs = useVfsStore.getState();
vfs.initBoardVfs(boardId) // create default tree
vfs.createNode(boardId, parentId, 'app.py', 'file') // add new file
vfs.setContent(boardId, nodeId, pythonCode) // update file content
vfs.serializeForUpload(boardId) // returns [{ path, content }, ...]Files in the VFS are uploaded to the Pi OS at boot via the WebSocket connection before the script is executed.
The Raspberry Pi 3 can be placed on the same canvas as Arduino or other boards. When wires connect a Pi GPIO pin to an Arduino pin, the stores route data between them automatically.
Pi Python script:
port.write(b"LED_ON\n")
│
▼ ttyAMA0 byte output
serial_output WebSocket message
│
▼ useSimulatorStore (serial callback)
AVRSimulator.serialWrite("L") ← feeds byte into Arduino RX FIFO
│
▼ Arduino sketch:
String cmd = Serial.readStringUntil('\n');
if (cmd == "LED_ON") digitalWrite(8, HIGH);
Arduino sketch:
Serial.println("SENSOR:1023");
│
▼ USART byte emitted
useSimulatorStore serial callback
│
▼ bridge.sendSerialBytes([charCode, ...])
serial_input WebSocket message → Backend
│
▼ qemu_manager.send_serial_bytes(client_id, bytes)
ttyAMA0 receives bytes → Pi reads with:
line = port.readline() # "SENSOR:1023\n"
This example (included in the gallery as pi-to-arduino-led-control) demonstrates bidirectional serial communication:
Pi Script:
import serial, time
port = serial.Serial('/dev/ttyAMA0', baudrate=9600, timeout=1)
for _ in range(3):
port.write(b"LED1_ON\n")
time.sleep(0.5)
port.write(b"LED1_OFF\n")
time.sleep(0.5)
port.write(b"LED2_ON\n")
time.sleep(2)
port.write(b"LED2_OFF\n")Arduino Sketch:
const int LED1 = 8, LED2 = 9;
void setup() {
Serial.begin(9600);
pinMode(LED1, OUTPUT);
pinMode(LED2, OUTPUT);
}
void loop() {
if (Serial.available()) {
String cmd = Serial.readStringUntil('\n');
if (cmd == "LED1_ON") digitalWrite(LED1, HIGH);
else if (cmd == "LED1_OFF") digitalWrite(LED1, LOW);
else if (cmd == "LED2_ON") digitalWrite(LED2, HIGH);
else if (cmd == "LED2_OFF") digitalWrite(LED2, LOW);
}
}The Pi 3 simulator needs three files that QEMU reads at launch. None of
them are committed to the repo or baked into the Docker image — they're
fetched lazily on first boot by the
BootImageProvider and cached in a docker named
volume.
| File (cache slot) | Size | Source | Purpose |
|---|---|---|---|
kernel8.img |
24 MB | decompressed PE-COFF ARM64 Image from Pi OS Trixie armhf boot partition | The Linux kernel QEMU jumps to. Must be decompressed — the original kernel8.img on Pi OS is gzipped and QEMU's -kernel does NOT auto-decompress. |
bcm2710-rpi-3-b.dtb |
34 KB | unmodified from Pi OS boot partition | Device tree blob describing the BCM2837 SoC (Cortex-A53 cluster, PL011 UART at 0x3f201000, BCM2835 SDHCI at 0x3f300000, etc.). The Pi 3 Model B *-b.dtb matches the QEMU raspi3b machine exactly. |
raspios-trixie-armhf.img |
5.4 GB raw / 1.4 GB on the wire (zstd -19) | Raspberry Pi OS Trixie 2026-04-21 armhf, patched by scripts/configure-pi3-autologin.sh (see below) |
Root filesystem. Patched in-place via loop-mount + sed before re-compression. |
The base SD image is never modified at runtime. Each session creates a qcow2 copy-on-write overlay that records only the changes made during that session; the overlay is deleted on stop.
The pristine Pi OS Trixie image won't give a usable shell experience
inside QEMU on its own (no default user, half a dozen network-wait
services that timeout slowly, etc.). Before upload, every SD image
goes through scripts/configure-pi3-autologin.sh:
| Patch | Why |
|---|---|
Drop-in serial-getty@ttyAMA0.service.d/autologin.conf → agetty --autologin root |
Pi OS Trixie ships without a default pi/raspberry user. The drop-in skips the credential prompt entirely. |
sed -i 's|^root:[^:]*:|root::|' /etc/shadow (passwordless root) |
Defence-in-depth in case a future PAM policy rejects passwordless login -f. |
Mask systemd-networkd-wait-online, NetworkManager-wait-online, wpa_supplicant, dhcpcd5, raspi-config, firstboot, userconfig |
These wait for network / first-boot resize that never happens in QEMU. Masking saves ~60-90 s of boot. |
The script is idempotent — re-run it whenever you bump Pi OS to a
newer Trixie build. It also prints the new sha256 + size_bytes for
both the compressed and decompressed forms; paste those into
backend/app/services/boot_images/manifest.json.
┌──────────────────────────────────────────────────────┐
│ velxio-prod container starts │
└───────────────────────┬──────────────────────────────┘
│
▼
lifespan hook in qemu_manager.py → provider.warmup_all()
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ for image in manifest['raspberry-pi-3'].images: │
│ target = /var/cache/velxio/boot-images/raspberry-pi-3/<name> │
│ if target.exists() and target.sha256_sidecar == manifest.sha256: │
│ continue # cache hit │
│ else: │
│ downloader.fetch(image.asset_id, staging) │
│ verify SHA256 (wire format) │
│ if image.compressed: zstd-decompress staging → tmp │
│ verify SHA256 (decompressed) │
│ rename atomically → target │
│ write sidecar <target>.sha256 │
└──────────────────────────────────────────────────────────────────────┘
│
▼
User clicks "Pi 3 → Run" → instant qemu launch
The provider is described in detail in BOOT_IMAGES.md;
its public API is app.services.boot_images.get_default_provider().
Three places hold copies, each serving a different role:
| Location | Role |
|---|---|
/var/velxio-pro/binaries/{kernel8-pi3,dtb-bcm2710-rpi-3-b,raspios-trixie-armhf-zst}/ |
Asset store — bind-mounted from the host. Populated by scripts/upload-binary.sh. Served by the licence module at /api/pro/license/downloads/{asset} for OSS users with a key. |
/var/cache/velxio/boot-images/raspberry-pi-3/ (named docker volume boot-images) |
Runtime cache — what QEMU actually reads. Materialised on first request, content-verified via the sidecar SHA file, kept across docker compose down/up. |
backend/app/services/boot_images/manifest.json |
Source of truth — declared SHA256 + size for each file. A SHA bump here invalidates the cache and forces a re-fetch on next container start. |
# 1. Download the new Pi OS Trixie armhf release from raspberrypi.com
curl -fO https://downloads.raspberrypi.com/raspios_armhf/images/raspios_armhf-<DATE>/<DATE>-raspios-trixie-armhf.img.xz
unxz <DATE>-raspios-trixie-armhf.img.xz
# 2. Bake autologin + service masks
./scripts/configure-pi3-autologin.sh \
--src <DATE>-raspios-trixie-armhf.img \
--out raspios-trixie-armhf-autologin.img.zst
# script prints the new sha256/size values — copy them.
# 3. Upload to the licence-module asset store
PRO_BINARIES_DIR=$PWD/binaries ./scripts/upload-binary.sh \
--asset raspios-trixie-armhf-zst \
--version <DATE>+autologin \
--file raspios-trixie-armhf-autologin.img.zst
# 4. Update upstream manifest with the printed SHA + sizes, commit, push,
# bump the velxio submodule pointer in velxio-prod, push, deploy.
./scripts/deploy.shOn the next container start, the BootImageProvider sees a sidecar SHA mismatch and re-fetches the new SD image. The kernel + DTB stay cached.
# Backend does this automatically for each session:
qemu-img create -f qcow2 \
-b /var/cache/velxio/boot-images/raspberry-pi-3/raspios-trixie-armhf.img \
-F raw \
/tmp/overlay_<session_id>.qcow2
qemu-img resize /tmp/overlay_<session_id>.qcow2 8G8 GiB resize —
raspi3brequires the SD image size to be a power of 2. The raw 5.4 GiB image fails QEMU's check; the overlay pads up to 8 GiB with zero-cost qcow2 sparse blocks.
qemu-system-aarch64 \
-M raspi3b \
-kernel /var/cache/velxio/boot-images/raspberry-pi-3/kernel8.img \
-dtb /var/cache/velxio/boot-images/raspberry-pi-3/bcm2710-rpi-3-b.dtb \
-drive file=/tmp/overlay_<id>.qcow2,if=sd,format=qcow2 \
-m 1G \
-smp 4 \
-nographic \
-serial tcp:127.0.0.1:<serial_port>,server,nowait \
-serial tcp:127.0.0.1:<gpio_port>,server,nowait \
-append 'earlycon=pl011,mmio32,0x3f201000 \
console=ttyAMA0,115200 \
root=/dev/mmcblk0p2 rootwait rw \
dwc_otg.lpm_enable=0'| Flag | Value | Meaning |
|---|---|---|
-M raspi3b |
machine type | Emulate the Raspberry Pi 3B hardware |
-m 1G |
RAM | 1 GB RAM (matches real Pi 3B) |
-smp 4 |
CPU cores | 4 ARM Cortex-A53 cores |
-nographic |
no display | No HDMI/video output — serial only |
-serial tcp:...:N,server,nowait |
first serial | ttyAMA0 (user serial) served on TCP port N |
-serial tcp:...:M,server,nowait |
second serial | ttyAMA1 (GPIO shim protocol) served on TCP port M |
-drive ...,format=qcow2 |
disk | qcow2 overlay over the base SD image (resized to 8 GiB per raspi3b's power-of-2 SD requirement) |
-kernel kernel8.img |
kernel | Pre-decompressed PE-COFF ARM64 Linux Image. Must NOT be gzipped — QEMU's -kernel does not auto-decompress; a gzipped kernel results in a silent boot. |
| Flag | Why |
|---|---|
earlycon=pl011,mmio32,0x3f201000 |
Critical. Without the explicit MMIO address, the kernel can't initialise the BCM2837 PL011 UART early enough for printk to reach the serial console (real Pi 3 relies on the Pi firmware to set up the UART before kernel handover; QEMU skips that step). Address = BCM2837 peripheral base 0x3f000000 + PL011 offset 0x201000. |
console=ttyAMA0,115200 |
Main console output to the first serial port at 115200 baud. Matches the baud rate the autologin drop-in passes to agetty. |
root=/dev/mmcblk0p2 |
Root filesystem on the second SD partition (p1 is /boot/firmware/). |
rootwait rw |
Wait for the SD card to appear before mounting root, then mount writable so the qcow2 overlay can record changes. |
dwc_otg.lpm_enable=0 |
Standard Pi cmdline option — disables USB Low Power Mode (no functional effect inside QEMU but kept for parity with real hardware). |
No
init=/bin/sh, noquiet. Earlier versions used these but the combination produced a silent boot followed by a non-interactive shell (no PS1, no echo). Letting systemd boot normally + the serial-getty autologin drop-in is the correct approach.
| Limitation | Detail |
|---|---|
| Cold boot time | First QEMU launch after a fresh container goes through a full Pi OS systemd boot in emulation: kernel ~15 s + systemd graph ~30-60 s (varies with the masked-services set in configure-pi3-autologin.sh). The frontend shows a "booting" state during this time. Cached boot images keep the QEMU launch itself ~1 s; the delay is all guest-side. |
| Boot file size | The decompressed SD image is 5.4 GiB and lives in the boot-images docker volume after first use. Initial download via the licence-gated endpoint is 1.4 GiB (zstd -19). Allocate ~7 GiB of free disk for the named volume. |
| No real PWM | GPIO.PWM simulates duty cycle as binary state (>50% = HIGH, ≤50% = LOW); no analog dimming |
| No I2C emulation | smbus, smbus2, i2c_msg — I2C bus transactions are not forwarded to virtual devices |
| No SPI emulation | Hardware SPI registers not forwarded; spidev library will fail |
| Single UART for GPIO | ttyAMA1 is reserved for the GPIO shim; scripts cannot use it for other serial devices |
| No GUI / display | HDMI output is disabled (-nographic); GUI Python libraries (Tkinter, pygame, etc.) will not work |
| No networking | QEMU does not expose a network interface; requests, socket, urllib will fail |
| No persistent state | The qcow2 overlay is deleted after shutdown; files written to the Pi OS do not survive a restart |
| Reset is reconnect | resetBoard() is not implemented; to restart the Pi, stop it and start it again |
| Session isolation | Each board instance creates an independent QEMU process; two Pi boards do not share any state |
| Resource usage | Each Pi instance launches a full QEMU process (~200 MB RAM); hosting many simultaneous sessions is resource-intensive |
| Aspect | Raspberry Pi 3B | Raspberry Pi Pico | ESP32 (Xtensa) | Arduino AVR |
|---|---|---|---|---|
| Engine | QEMU raspi3b | rp2040js (browser) | QEMU lcgamboa (backend) | avr8js (browser) |
| Backend required | Yes (QEMU process) | No | Yes (QEMU process) | No |
| Language | Python | C++ (Arduino) | C++ (Arduino) | C++ (Arduino) |
| Compilation step | No | Yes (arduino-cli) | Yes (arduino-cli) | Yes (arduino-cli) |
| OS | Raspberry Pi OS (Linux) | None (bare metal) | None (ESP-IDF) | None (bare metal) |
| Boot time | ~2–5 s | Instant | ~1–2 s | Instant |
| GPIO protocol | Text over ttyAMA1 | MMIO direct | QEMU callbacks + WebSocket | Port listeners |
| Serial | ttyAMA0 (real UART) | UART0/1 (rp2040js) | UART0 (QEMU) | USART0 (avr8js) |
| I2C | Not forwarded to frontend | 2 buses + virtual devices | Emulated | Not emulated |
| PWM | Binary (no waveform) | Hardware PWM | LEDC (mapped) | Timer-based |
| Multi-board comms | Yes (serial bridge) | No | No | No |
| Oscilloscope | No | Yes (8 ns resolution) | No | Yes |
| CI tests | No | Yes (Vitest) | No | Yes (Vitest) |
| Disk image required | Yes (~5.67 GB) | No | No | No |
| File | Description |
|---|---|
backend/app/services/qemu_manager.py |
QemuManager — manages QEMU process lifecycle, TCP sockets, qcow2 overlays |
backend/app/services/gpio_shim.py |
RPi.GPIO drop-in replacement; speaks text protocol over ttyAMA1 |
backend/app/api/routes/simulation.py |
WebSocket endpoint /api/simulation/ws/{client_id} |
frontend/src/simulation/RaspberryPi3Bridge.ts |
WebSocket client; routes serial_output, gpio_change, system events |
frontend/src/store/useSimulatorStore.ts |
Board lifecycle, serial bridge to co-simulated AVR/Pico boards |
frontend/src/store/useVfsStore.ts |
Per-board virtual filesystem (Python script editor) |
frontend/src/utils/boardPinMapping.ts |
Physical pin → BCM GPIO number mapping table |
frontend/src/components/components-wokwi/RaspberryPi3.tsx |
Board React component (SVG, 40-pin header coordinates) |
frontend/src/components/components-wokwi/RaspberryPi3Element.ts |
Web Component for canvas rendering and wire endpoints |
frontend/src/types/board.ts |
BoardKind type, FQBN = null for Raspberry Pi 3 |
backend/app/services/boot_images/ |
Module that fetches + caches + verifies the kernel/DTB/SD image. See BOOT_IMAGES.md. |
backend/app/services/boot_images/manifest.json |
Versioned source-of-truth for which SHA256 the cached boot files must match. Bumping a SHA here forces a re-fetch on next container start. |
velxio-prod:scripts/configure-pi3-autologin.sh |
The one-shot tool that bakes an agetty --autologin root systemd drop-in into the SD image + masks 9 boot-blocking services. Run when bumping to a newer Pi OS build. Prints the new SHA256 + size values to paste into manifest.json. |
velxio-prod:scripts/upload-binary.sh |
Drops a built asset into /var/velxio-pro/binaries/<asset>/ with a generated manifest. The licence module then serves it at /api/pro/license/downloads/{asset}?key=.... |
velxio-prod:binaries/{kernel8-pi3,dtb-bcm2710-rpi-3-b,raspios-trixie-armhf-zst}/ |
The host directory bind-mounted to /var/velxio-pro/binaries inside the container. Gitignored (the files are licence-gated assets, not source). |
velxio-prod:docker-compose.yml (boot-images volume) |
Named docker volume for the runtime cache. Survives compose down/up. |