From eb4b691f2dff9315058e122da8b3f253a0bf2913 Mon Sep 17 00:00:00 2001 From: David Montero Crespo Date: Mon, 16 Mar 2026 14:37:08 -0300 Subject: [PATCH] feat: add RP2040 and Raspberry Pi 3 emulation sections to documentation --- frontend/src/pages/DocsPage.tsx | 182 ++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) diff --git a/frontend/src/pages/DocsPage.tsx b/frontend/src/pages/DocsPage.tsx index 40bccbe..4fd4e52 100644 --- a/frontend/src/pages/DocsPage.tsx +++ b/frontend/src/pages/DocsPage.tsx @@ -21,6 +21,8 @@ type SectionId = | 'emulator' | 'riscv-emulation' | 'esp32-emulation' + | 'rp2040-emulation' + | 'raspberry-pi3-emulation' | 'components' | 'roadmap' | 'architecture' @@ -34,6 +36,8 @@ const VALID_SECTIONS: SectionId[] = [ 'emulator', 'riscv-emulation', 'esp32-emulation', + 'rp2040-emulation', + 'raspberry-pi3-emulation', 'components', 'roadmap', 'architecture', @@ -53,6 +57,8 @@ const NAV_ITEMS: NavItem[] = [ { id: 'emulator', label: 'Emulator Architecture' }, { id: 'riscv-emulation', label: 'RISC-V Emulation (ESP32-C3)' }, { id: 'esp32-emulation', label: 'ESP32 Emulation (Xtensa)' }, + { id: 'rp2040-emulation', label: 'RP2040 Emulation (Raspberry Pi Pico)' }, + { id: 'raspberry-pi3-emulation', label: 'Raspberry Pi 3 Emulation (QEMU)' }, { id: 'components', label: 'Components Reference' }, { id: 'architecture', label: 'Project Architecture' }, { id: 'wokwi-libs', label: 'Wokwi Libraries' }, @@ -108,6 +114,14 @@ const SECTION_META: Record = { title: 'Project Status — Velxio Documentation', description: 'Complete status of all implemented Velxio features: AVR emulation, component system, wire system, code editor, example projects, and next steps.', }, + 'rp2040-emulation': { + title: 'RP2040 Emulation (Raspberry Pi Pico) — Velxio Documentation', + description: 'How Velxio emulates the Raspberry Pi Pico and Pico W using rp2040js: ARM Cortex-M0+ at 133 MHz, GPIO, UART, ADC, I2C, SPI, PWM and WFI optimization.', + }, + 'raspberry-pi3-emulation': { + title: 'Raspberry Pi 3 Emulation (QEMU) — Velxio Documentation', + description: 'How Velxio emulates a full Raspberry Pi 3B using QEMU raspi3b: real Raspberry Pi OS, Python + RPi.GPIO shim, dual-channel UART, VFS, and multi-board serial bridge.', + }, }; /* ── Section content ───────────────────────────────────── */ @@ -1194,12 +1208,180 @@ const Esp32EmulationSection: React.FC = () => ( ); +/* ── RP2040 Emulation Section ─────────────────────────── */ +const Rp2040EmulationSection: React.FC = () => ( +
+ // arm cortex-m0+ +

RP2040 Emulation (Raspberry Pi Pico)

+

+ The Raspberry Pi Pico and Pico W are emulated entirely in the browser using{' '} + rp2040js, + an open-source ARM Cortex-M0+ emulator. No QEMU or backend process is required — the binary runs at full speed inside a Web Worker. +

+ +

Supported Boards

+
+
+ Raspberry Pi Pico + Raspberry Pi Pico +
+
+ Raspberry Pi Pico W + Raspberry Pi Pico W +
+
+ + + + + + +
BoardFQBNBuilt-in LED
Raspberry Pi Picorp2040:rp2040:rpipicoGPIO 25
Raspberry Pi Pico Wrp2040:rp2040:rpipicowGPIO 25 (via CYW43)
+ +

Binary Format

+

+ The backend compiles the sketch with arduino-cli targeting rp2040:rp2040:rpipico and returns + a raw ARM binary (.bin) encoded in base64. Unlike AVR, there is no Intel HEX — the binary is loaded + directly into the RP2040 flash at offset 0. +

+

+ The backend also prepends #define Serial Serial1 to the sketch so that Arduino Serial calls + are redirected to UART0 (the virtual serial port streamed to the Serial Monitor). +

+ +

Peripherals

+ + + + + + + + + + + +
PeripheralSupportNotes
GPIO (30 pins)FullDigital read/write, pull-up/down
UART0 / UART1FullSerial Monitor via UART0
ADC (ch 0–3)FullGPIO 26–29; ch 4 = temperature sensor
I2C0 / I2C1PartialDS1307 RTC, TempSensor, EEPROM virtual devices
SPI0 / SPI1LoopbackTX looped back to RX
PWMFrequency onlyNo waveform output to components
Timer / AlarmFullUsed by delay() and millis()
+ +

WFI Optimisation

+

+ When the CPU executes a WFI (Wait For Interrupt) instruction, the emulator fast-forwards + the system clock to the next scheduled alarm instead of spinning through idle cycles. This dramatically + reduces CPU usage during delay() calls. +

+ +

Simulation Loop

+

+ The simulation runs inside requestAnimationFrame at ~60 FPS. + Each frame executes approximately 2,200,000 CPU cycles (133 MHz / 60 fps). + GPIO listeners fire whenever a pin state changes and update the visual components on the canvas. +

+ +

Known Limitations

+
    +
  • Pico W wireless chip (CYW43439) is not emulated — WiFi/Bluetooth will not work
    • +
  • SPI loopback only — no real SPI device emulation
    • +
  • PWM produces correct frequency but no visual waveform on components
    • +
  • DMA not emulated
    • +
  • Second CPU core (core 1) not emulated — multicore_launch_core1() has no effect
    • +
+ +

Full Documentation

+

+ See the complete technical reference:{' '} + + RP2040_EMULATION.md + +

+
+); + +/* ── Raspberry Pi 3 Emulation Section ─────────────────── */ +const RaspberryPi3EmulationSection: React.FC = () => ( +
+ // qemu raspi3b +

Raspberry Pi 3 Emulation (QEMU)

+

+ The Raspberry Pi 3B is emulated using QEMU 8.1.3 with -M raspi3b. + This is the only board in Velxio that runs a full operating system — a real{' '} + Raspberry Pi OS (Trixie) image booted inside the emulator. + Users write Python scripts (not C++), which are executed by the real Python 3 interpreter inside the VM. +

+ +

Supported Boards

+ + + + + +
BoardQEMU MachineCPU
Raspberry Pi 3Braspi3bBCM2837, 4× Cortex-A53 @ 1.2 GHz
+ +

Dual-Channel Serial Architecture

+

+ QEMU exposes two UART channels to the backend: +

+
    +
  • ttyAMA0 — User serial: interactive terminal (Serial Monitor). The user's print() output appears here.
    • +
  • ttyAMA1 — GPIO shim: carries a text protocol between the GPIO shim inside the VM and the backend.
    • +
+ +

RPi.GPIO Shim

+

+ A custom RPi.GPIO shim is injected at /usr/local/lib/python3.11/dist-packages/RPi/GPIO.py + inside the VM. When user code calls GPIO.output(pin, value), the shim writes + a line like GPIO 17 1 to ttyAMA1. + The backend reads this, fires a gpio_change WebSocket event, and the frontend + updates the visual component on the canvas. +

+

+ The reverse also works: the frontend can send SET 17 1 via WebSocket → backend → ttyAMA1 → shim → user code reads it via GPIO.input(17). +

+ +

Virtual File System (VFS)

+

+ Each Raspberry Pi board instance has its own VFS that maps to files inside the running VM. + The default tree is: +

+ 
{`/home/pi/
+├── script.py     ← user's main Python script
+└── lib/
+    └── helper.py ← optional helper library`}
+ +

Overlay Images

+

+ The base Raspberry Pi OS SD image is never modified. Each session creates a fresh + qcow2 overlay on top of the base image, so all runtime changes are + isolated and discarded when the session ends. +

+ +

Known Limitations

+
    +
  • No I2C or SPI device emulation
    • +
  • No PWM waveform output to components
    • +
  • No networking (WiFi/Ethernet not emulated)
    • +
  • Session state is not persisted — overlay is discarded on stop
    • +
  • Boot time is slow (~10–20 s) as a full OS must start
    • +
  • Requires the ~5.67 GB base SD image to be present on the server
    • +
+ +

Full Documentation

+

+ See the complete technical reference:{' '} + + RASPBERRYPI3_EMULATION.md + +

+
+); + const SECTION_MAP: Record = { intro: IntroSection, 'getting-started': GettingStartedSection, emulator: EmulatorSection, 'riscv-emulation': RiscVEmulationSection, 'esp32-emulation': Esp32EmulationSection, + 'rp2040-emulation': Rp2040EmulationSection, + 'raspberry-pi3-emulation': RaspberryPi3EmulationSection, components: ComponentsSection, roadmap: RoadmapSection, architecture: ArchitectureSection,