Velxio: Arduino & Embedded Board Emulator

Live at velxio.dev

A fully local, open-source multi-board emulator. Write Arduino C++ or Python, compile it, and simulate it with real CPU emulation and 48+ interactive electronic components — all running in your browser.

19 boards · 5 CPU architectures: AVR8 (ATmega / ATtiny), ARM Cortex-M0+ (RP2040), RISC-V RV32IMC/EC (ESP32-C3 / CH32V003), Xtensa LX6/LX7 (ESP32 / ESP32-S3 via QEMU), and ARM Cortex-A53 (Raspberry Pi 3 Linux via QEMU).

---

---

Support the Project

Velxio is free and open-source. Building and maintaining a full multi-board emulator takes a lot of time — if it saves you time or you enjoy the project, sponsoring me directly helps keep development going.

Platform	Link
GitHub Sponsors (preferred)	github.com/sponsors/davidmonterocrespo24
PayPal	paypal.me/odoonext

Your support helps cover server costs, library maintenance, and frees up time to add new boards, components, and features. Thank you!

---

Try it now

https://velxio.dev — no installation needed. Open the editor, write your sketch, and simulate directly in the browser.

To self-host with Docker (single command):

docker run -d \
  --name velxio \
  -p 3080:80 \
  -v velxio-data:/app/data \
  -v velxio-arduino-libs:/root/.arduino15 \
  -v velxio-arduino-user-libs:/root/Arduino \
  -v velxio-ccache:/var/cache/ccache \
  -v velxio-build:/var/lib/velxio-build \
  ghcr.io/davidmonterocrespo24/velxio:master

Then open http://localhost:3080. Tail logs any time with docker logs -f velxio.

The named volumes are what make compile times reasonable on subsequent runs — without them, every container restart wipes the ESP-IDF build cache and the first compile after each restart takes 5-7 minutes instead of 5-30 seconds.

---

Screenshots

Raspberry Pi Pico simulation — ADC read test with two potentiometers, Serial Monitor showing live output, and compilation console at the bottom.

Arduino Uno driving an ILI9341 240×320 TFT display via SPI — rendering a real-time graphics demo using Adafruit_GFX + Adafruit_ILI9341.

Library Manager loads the full Arduino library index on open — browse and install libraries without typing first.

Component Picker showing 48 available components with visual previews, search, and category filters.

Multi-board simulation — Raspberry Pi 3 and Arduino running simultaneously on the same canvas, connected via serial. Mix different architectures in a single circuit.

ESP32 simulation with an HC-SR04 ultrasonic distance sensor — real Xtensa emulation via QEMU with trigger/echo GPIO timing.

---

Supported Boards

Raspberry Pi Pico	Raspberry Pi Pico W	ESP32 DevKit C	ESP32-S3
ESP32-C3	Seeed XIAO ESP32-C3	ESP32-C3 SuperMini	ESP32-CAM
Seeed XIAO ESP32-S3	Arduino Nano ESP32	Raspberry Pi 3B	Arduino Uno · Nano · Mega 2560 ATtiny85 · Leonardo · Pro Mini (AVR8 / ATmega)

Board	CPU	Engine	Language
Arduino Uno	ATmega328p @ 16 MHz	avr8js (browser)	C++ (Arduino)
Arduino Nano	ATmega328p @ 16 MHz	avr8js (browser)	C++ (Arduino)
Arduino Mega 2560	ATmega2560 @ 16 MHz	avr8js (browser)	C++ (Arduino)
ATtiny85	ATtiny85 @ 8 MHz (int) / 16 MHz (ext)	avr8js (browser)	C++ (Arduino)
Arduino Leonardo	ATmega32u4 @ 16 MHz	avr8js (browser)	C++ (Arduino)
Arduino Pro Mini	ATmega328p @ 8/16 MHz	avr8js (browser)	C++ (Arduino)
Raspberry Pi Pico	RP2040 @ 133 MHz	rp2040js (browser)	C++ (Arduino)
Raspberry Pi Pico W	RP2040 @ 133 MHz	rp2040js (browser)	C++ (Arduino)
ESP32 DevKit V1	Xtensa LX6 @ 240 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
ESP32 DevKit C V4	Xtensa LX6 @ 240 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
ESP32-S3	Xtensa LX7 @ 240 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
ESP32-CAM	Xtensa LX6 @ 240 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
Seeed XIAO ESP32-S3	Xtensa LX7 @ 240 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
Arduino Nano ESP32	Xtensa LX6 @ 240 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
ESP32-C3 DevKit	RISC-V RV32IMC @ 160 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
Seeed XIAO ESP32-C3	RISC-V RV32IMC @ 160 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
ESP32-C3 SuperMini	RISC-V RV32IMC @ 160 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
CH32V003	RISC-V RV32EC @ 48 MHz	QEMU lcgamboa (backend)	C++ (Arduino)
Raspberry Pi 3B	ARM Cortex-A53 @ 1.2 GHz	QEMU raspi3b (backend)	Python

---

Features

Code Editing

• Monaco Editor — Full C++ / Python editor with syntax highlighting, autocomplete, minimap, and dark theme
• Multi-file workspace — create, rename, delete, and switch between multiple .ino / .h / .cpp / .py files
• Arduino compilation via arduino-cli backend — compile sketches to .hex / .bin files
• Compile / Run / Stop / Reset toolbar buttons with status messages
• Compilation console — resizable output panel showing full compiler output, warnings, and errors

Multi-Board Simulation

AVR8 (Arduino Uno / Nano / Mega / ATtiny85 / Leonardo / Pro Mini)

• Real ATmega328p / ATmega2560 / ATmega32u4 / ATtiny85 emulation at native clock speed via avr8js
• Full GPIO — PORTB, PORTC, PORTD (Uno/Nano/Mega); all ATtiny85 ports (PB0–PB5)
• Timer0/Timer1/Timer2 — millis(), delay(), PWM via analogWrite()
• USART — full transmit and receive, auto baud-rate detection
• ADC — analogRead(), voltage injection from potentiometers on canvas
• SPI — hardware SPI peripheral (ILI9341, SD card, etc.)
• I2C (TWI) — hardware I2C with virtual device bus
• ATtiny85 — all 6 I/O pins, USI (Wire), Timer0/Timer1, 10-bit ADC; uses AttinyCore
• ~60 FPS simulation loop via requestAnimationFrame

RP2040 (Raspberry Pi Pico / Pico W)

• Real RP2040 emulation at 133 MHz via rp2040js — ARM Cortex-M0+
• All 30 GPIO pins — input/output, event listeners, pin state injection
• UART0 + UART1 — serial output in Serial Monitor; Serial input from UI
• ADC — 12-bit on GPIO 26–29 (A0–A3) + internal temperature sensor (ch4)
• I2C0 + I2C1 — master mode with virtual device bus (DS1307, TMP102, EEPROM)
• SPI0 + SPI1 — loopback default; custom handler supported
• PWM — available on any GPIO pin
• WFI optimization — delay() skips ahead in simulation time instead of busy-waiting
• Oscilloscope — GPIO transition timestamps at ~8 ns resolution
• Compiled with the earlephilhower arduino-pico core

See docs/RP2040_EMULATION.md for full technical details.

ESP32 / ESP32-S3 (Xtensa QEMU)

• Real Xtensa LX6/LX7 dual-core emulation via lcgamboa/qemu
• Full GPIO — all 40 GPIO pins, direction tracking, state callbacks, GPIO32–39 fix
• UART0/1/2 — multi-UART serial, baud-rate detection
• ADC — 12-bit on all ADC-capable pins (0–3300 mV injection from potentiometers)
• I2C — synchronous bus with virtual device response
• SPI — full-duplex with configurable MISO byte injection
• RMT / NeoPixel — hardware RMT decoder, WS2812 24-bit GRB frame decoding
• LEDC/PWM — 16-channel duty cycle readout, LEDC→GPIO mapping, LED brightness
• WiFi — SLIRP NAT emulation (WiFi.begin("PICSimLabWifi", ""))
• Requires arduino-esp32 2.0.17 (IDF 4.4.x) — only version compatible with lcgamboa WiFi

See docs/ESP32_EMULATION.md for setup and full technical details.

ESP32-C3 / XIAO-C3 / SuperMini / CH32V003 (RISC-V via QEMU)

• RV32IMC emulation through QEMU lcgamboa with libqemu-riscv32 and the esp32c3-picsimlab machine — same backend pattern as Xtensa ESP32, different libqemu binary
• GPIO 0–21 via W1TS/W1TC MMIO registers (ESP32-C3); PB0–PB5 (CH32V003)
• UART0 serial output in Serial Monitor
• CH32V003 — RV32EC core at 48 MHz, 16 KB flash, DIP-8 / SOP package — ultra-compact
• TypeScript ISA layer (RiscVCore.ts, Esp32C3Simulator.ts) is kept as Vitest-only unit-test infrastructure — it cannot handle the 150+ ROM functions ESP-IDF needs and is not the production emulation path

See docs/RISCV_EMULATION.md for full technical details.

Raspberry Pi 3B (QEMU raspi3b)

• Full BCM2837 emulation via qemu-system-aarch64 -M raspi3b
• Boots real Raspberry Pi OS (Trixie) — runs Python scripts directly
• RPi.GPIO shim — drop-in replacement for the GPIO library; sends pin events to the frontend over a text protocol
• GPIO 0–27 — output and input, event detection, PWM (binary state)
• Dual serial — ttyAMA0 for user Serial Monitor, ttyAMA1 for GPIO protocol
• Virtual File System — edit Python scripts in the UI, upload to Pi at boot
• Multi-board serial bridge — Pi ↔ Arduino serial communication on the same canvas
• qcow2 overlay — base SD image never modified; session changes are isolated

See docs/RASPBERRYPI3_EMULATION.md for full technical details.

Serial Monitor

• Live serial output — characters as the sketch/script sends them
• Auto baud-rate detection — reads hardware registers, no manual configuration needed
• Send data to the RX pin from the UI
• Autoscroll with toggle

Component System (48+ Components)

• 48 electronic components from wokwi-elements
• Component picker with search, category filters, and live previews
• Drag-and-drop repositioning on the simulation canvas
• Component rotation in 90° increments
• Property dialog — pin roles, Arduino pin assignment, rotate & delete

Wire System

• Wire creation — click a pin to start, click another pin to connect
• Orthogonal routing — no diagonal paths
• 8 signal-type wire colors: Red (VCC), Black (GND), Blue (Analog), Green (Digital), Purple (PWM), Gold (I2C), Orange (SPI), Cyan (USART)
• Segment-based wire editing — drag segments perpendicular to their orientation

Library Manager

• Browse and install the full Arduino library index directly from the UI
• Live search, installed tab, version display

Portable Project Persistence

• .vlx file format — single-file JSON snapshot of the whole workspace (boards, file groups, components, wires). Download with the Save button, restore with the Open .vlx button. The format is versioned so files round-trip cleanly across versions.
• Zero server-side state — OSS Velxio has no database, no accounts, no login. Your projects live wherever you keep your .vlx files (local disk, Dropbox, GitHub, Google Drive — your choice).
• Need accounts, public profiles at /:username, server-side project URLs and admin panels? Those live in the private overlay used to run velxio.dev — see velxio-prod for the open-core split details.

Example Projects

• Built-in examples including Blink, Traffic Light, Button Control, Fade LED, Serial Hello World, RGB LED, Simon Says, LCD 20×4, and Pi + Arduino serial control
• One-click loading into the editor

---

Self-Hosting

Pick the install path that matches your appetite for setup. All three work out-of-the-box without an .env file — defaults are picked automatically.

Path	Boards available	Build time	Best for
A. Docker (prebuilt image)	All 19 (AVR, RP2040, RISC-V, ESP32, Raspberry Pi 3)	~30 s download	Just want it running
B. Docker Compose (build from source)	All 19	~10–15 min first build	Want to modify the code
C. Manual install	Browser-only boards (AVR, RP2040, RISC-V)	~5 min	Frontend / backend dev

ESP32 (Xtensa) and Raspberry Pi 3 emulation rely on QEMU .so libraries that ship inside the Docker image. Manual installs get the browser-side boards out of the box — for ESP32 you'll want Docker (or follow docs/ESP32_EMULATION.md to wire up the QEMU binaries by hand).

---

Option A: Docker (prebuilt image)

docker run -d \
  --name velxio \
  -p 3080:80 \
  -v velxio-data:/app/data \
  -v velxio-arduino-libs:/root/.arduino15 \
  -v velxio-arduino-user-libs:/root/Arduino \
  -v velxio-ccache:/var/cache/ccache \
  -v velxio-build:/var/lib/velxio-build \
  ghcr.io/davidmonterocrespo24/velxio:master

Open http://localhost:3080.

The five named volumes persist:

• velxio-data → /app/data: SQLite DB, project sketch files, auto-generated SECRET_KEY
• velxio-arduino-libs → /root/.arduino15: arduino-cli config + installed cores (saves a 5–10 min reinstall on every container restart)
• velxio-arduino-user-libs → /root/Arduino: Library Manager-installed Arduino libraries (e.g. Adafruit_BMP280, DHT, GFX). Without this, every container restart re-downloads them on next compile.
• velxio-ccache → /var/cache/ccache: ccache C/C++ object cache for ESP-IDF compiles. Empty on first compile, populated as you go; subsequent compiles hit the cache and finish in seconds instead of minutes.
• velxio-build → /var/lib/velxio-build: persistent ESP-IDF build dir (one subdir per target — esp32, esp32c3, esp32s3). Lets ninja's incremental build skip everything that hasn't changed; a re-compile of an unchanged sketch finishes in 2-5 seconds.

If you skip the volume flags, the Dockerfile declares all five paths as VOLUME, so docker creates anonymous volumes and the caches still survive container restarts (just harder to inspect/back up than named ones). Only docker rm -v or docker volume prune would wipe them.

---

Option B: Docker Compose (build from source)

git clone https://github.com/davidmonterocrespo24/velxio.git
cd velxio
docker compose up -d --build

First build takes ~10–15 minutes (downloads ESP-IDF, builds the frontend). Subsequent builds are cached and take ~1 min.

Then open http://localhost:3080. The container generates a random SECRET_KEY on first boot and persists it in ./data/, so no .env is required to get going.

Optional: customize environment

The OSS image has almost no configuration — there's no database, no auth, no third-party integrations. Create backend/.env only if you want to change the CORS origin used during local development.

Variable	Default	Description
FRONTEND_URL	http://localhost:5173	Origin allowed by CORS for local Vite dev

Deploying behind a reverse proxy? The container listens on plain HTTP on port 80 and accepts any Host header — no server_name whitelist.

Running velxio.dev itself? Production-only configuration (host nginx

• HTTPS, backups, pinned upstream commit) lives in its own repo: github.com/velxio/velxio-prod.

---

Option C: Manual Setup (frontend + backend separately)

Prerequisites: Node.js 18+, Python 3.12+, arduino-cli

git clone https://github.com/davidmonterocrespo24/velxio.git
cd velxio

No --recurse-submodules needed. @wokwi/elements, avr8js and rp2040js come from the npm registry. Board SVGs live in frontend/public/boards/. The folders under third-party/ are reference-only — you only need to clone wokwi-elements if you're adding a new component to the catalog (the metadata generator scans its src/).

# Terminal 1 — backend
cd backend
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001

# Terminal 2 — frontend
cd frontend
npm install
npm run dev

Open http://localhost:5173.

arduino-cli setup (first time):

arduino-cli core update-index
arduino-cli core install arduino:avr

# For Raspberry Pi Pico / Pico W:
arduino-cli config add board_manager.additional_urls \
  https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
arduino-cli core install rp2040:rp2040

# For ATtiny85:
arduino-cli config add board_manager.additional_urls \
  http://drazzy.com/package_drazzy.com_index.json
arduino-cli core install ATTinyCore:avr

ESP32 (Xtensa) compilation in manual install requires the ESP-IDF 4.4.7 toolchain installed locally. The Docker image bundles this — for manual installs see docs/ESP32_EMULATION.md. If you only need AVR / RP2040 / RISC-V boards you can skip ESP-IDF entirely.

---

Project Structure

velxio/
├── frontend/                    # React + Vite + TypeScript
│   └── src/
│       ├── pages/               # LandingPage, EditorPage, UserProfilePage, ...
│       ├── components/          # Editor, simulator canvas, modals, layout
│       ├── simulation/          # AVRSimulator, RP2040Simulator, RiscVCore,
│       │                        # RaspberryPi3Bridge, Esp32Bridge, PinManager
│       ├── store/               # Zustand stores (auth, editor, simulator, project, vfs)
│       └── services/            # API clients
├── backend/                     # FastAPI + Python
│   └── app/
│       ├── api/routes/          # compile, auth, projects, libraries, simulation (ws)
│       ├── models/              # User, Project (SQLAlchemy)
│       ├── services/            # arduino_cli, esp32_worker, qemu_manager, gpio_shim
│       └── core/                # config, security, dependencies
├── third-party/                  # Reference-only upstream clones (credits)
│   │                            # — runtime libs come from npm; the only
│   │                            # one used by the build is qemu-lcgamboa.
│   ├── wokwi-elements/          # (npm: @wokwi/elements)
│   ├── avr8js/                  # (npm: avr8js)
│   ├── rp2040js/                # (npm: rp2040js)
│   └── qemu-lcgamboa/           # QEMU fork for ESP32 Xtensa (build from source)
├── img/                         # Raspberry Pi 3 boot images (kernel8.img, dtb, OS)
├── docker/                      # In-container nginx.conf + entrypoint.sh
├── docs/                        # Technical documentation
├── Dockerfile.standalone        # Single-container image used for self-hosting
└── docker-compose.yml           # Self-hosting compose
                                 # (production deployment lives in
                                 # https://github.com/velxio/velxio-prod)

---

Technologies

Layer	Stack
Frontend	React 19, Vite 7, TypeScript 5.9, Monaco Editor, Zustand, React Router 7
Backend	FastAPI, uvicorn (stateless: compile, libraries, simulation, MCP)
AVR Simulation	avr8js (ATmega328p / ATmega2560)
RP2040 Simulation	rp2040js (ARM Cortex-M0+)
RISC-V Simulation	RiscVCore.ts (RV32IMC, custom TypeScript)
ESP32 Simulation	QEMU 8.1.3 lcgamboa fork (Xtensa LX6/LX7)
Raspberry Pi 3 Simulation	QEMU 8.1.3 (qemu-system-aarch64 -M raspi3b) + Raspberry Pi OS Trixie
UI Components	wokwi-elements (Web Components)
Compiler	arduino-cli (subprocess) + ESP-IDF (subprocess)
Auth	None — anonymous, single-user editor by design
Persistence	.vlx file export/import (no server-side database)
Deploy	Docker, nginx, GitHub Actions → GHCR + Docker Hub

---

Documentation

Topic	Document
Getting Started	docs/getting-started.md
Architecture Overview	docs/ARCHITECTURE.md
Emulator Architecture	docs/emulator.md
Wokwi Libraries Integration	docs/WOKWI_LIBS.md
RP2040 Emulation (Pico)	docs/RP2040_EMULATION.md
Raspberry Pi 3 Emulation	docs/RASPBERRYPI3_EMULATION.md
ESP32 Emulation (Xtensa)	docs/ESP32_EMULATION.md
RISC-V Emulation (ESP32-C3)	docs/RISCV_EMULATION.md
Components Reference	docs/components.md
MCP Server	docs/MCP.md
Roadmap	docs/roadmap.md

---

Troubleshooting

arduino-cli: command not found — install arduino-cli and add to PATH.

LED doesn't blink — check port listeners in browser console; verify pin mapping in the component property dialog.

Serial Monitor shows nothing — ensure Serial.begin() is called before Serial.print().

ESP32 not starting — verify libqemu-xtensa.dll (Windows) or libqemu-xtensa.so (Linux) is present in backend/app/services/.

Pi 3 takes too long to boot — QEMU needs 2–5 seconds to initialize; the "booting" status in the UI is expected.

Compilation errors — check the compilation console; verify the correct core is installed for the selected board.

---

Community

Join the Discord server to ask questions, share projects, and follow updates:

discord.gg/3mARjJrh4E

Contributing

Suggestions, bug reports, and pull requests are welcome at github.com/davidmonterocrespo24/velxio.

If you'd like to support the project financially, see the Support the Project section above or sponsor directly at github.com/sponsors/davidmonterocrespo24.

Note: All contributors must sign a Contributor License Agreement (CLA) so that the dual-licensing model remains valid. A CLA check runs automatically on pull requests.

License

Velxio uses a dual-licensing model:

Use case	License	Cost
Personal, educational, open-source (AGPLv3 compliant)	AGPLv3	Free
Proprietary / closed-source product or SaaS	Commercial License	Paid

The AGPLv3 is a certified Open Source license. It is free for all uses — including commercial — as long as any modifications or network-accessible deployments make their source code available under the same license. Companies that cannot comply with that requirement can purchase a Commercial License.

For commercial licensing inquiries: davidmonterocrespo24@gmail.com

See LICENSE and COMMERCIAL_LICENSE.md for full terms.

Star History

References

• Wokwi — Inspiration
• avr8js — AVR8 emulator
• wokwi-elements — Electronic web components
• wokwi-boards — Board SVG assets
• wokwi-features — Wokwi feature definitions
• rp2040js — RP2040 emulator
• ngspice-wasm — ngspice compiled to WebAssembly (electrical simulation)
• lcgamboa/qemu — QEMU fork for ESP32 Xtensa emulation
• espressif/qemu — Espressif QEMU ESP32 emulator
• esp32-camera — ESP32 camera driver reference
• fritzing-parts — Electronic component SVG assets
• picowi — Raspberry Pi Pico W WiFi reference
• 100 Days 100 IoT Projects — IoT example projects collection
• arduino-cli — Arduino compiler
• Monaco Editor — Code editor
• QEMU — Machine emulator (Raspberry Pi 3)