a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
velxio/docs/getting-started.md

8.9 KiB
Raw Permalink Blame History

Getting Started

Velxio is an open-source multi-board emulator and electronics simulator. There are four ways to use it:

  1. Hosted (web) — open velxio.dev, no install.
  2. Self-host with Docker — one container, all 19 boards including ESP32 (Xtensa) and Raspberry Pi 3.
  3. Manual setup — frontend + backend separately, for development.
  4. Desktop app — native Tauri app for offline work (Pro).

Option 1: Use the Hosted Version

Open the live editor at velxio.dev — no install needed.

The hosted edition includes everything in OSS plus accounts, public profiles at /:username, persistent project URLs, and the Pro features (custom-chip cloud build, premium components, AI assistant on Pro Max). Free tier is fully usable for digital simulation; analog and a few advanced features sit behind Pro.

Option 2: Self-Host with Docker

One container, all 19 boards (AVR, RP2040, RISC-V, ESP32 Xtensa, Raspberry Pi 3):

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 the simulator at http://localhost:3080.

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.

Volume Mount Purpose
velxio-data /app/data SQLite (if Pro overlay is layered), sketch files
velxio-arduino-libs /root/.arduino15 arduino-cli config + installed cores
velxio-arduino-user-libs /root/Arduino Library Manager downloads
velxio-ccache /var/cache/ccache ccache for ESP-IDF compiles
velxio-build /var/lib/velxio-build Persistent ESP-IDF build dirs (per target)

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 min (downloads ESP-IDF, builds the frontend). Subsequent builds use Docker cache and finish in ~1 min.

Option 3: Manual Setup (Development)

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

Manual installs get the browser-side boards (AVR, RP2040, RISC-V TypeScript ISA) out of the box. ESP32 (Xtensa) and Raspberry Pi 3 need QEMU .so libraries that ship inside the Docker image — see BUILD-QEMU.md if you want them locally.

1. Clone the repository

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

No --recurse-submodules needed. @wokwi/elements, avr8js and rp2040js come from npm. The folders under third-party/ are reference-only.

2. Start the 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

3. Start the frontend

# In a new terminal:
cd frontend
npm install
npm run dev

Open the dev server at http://localhost:5173.

4. Set up arduino-cli cores (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

# For ESP32 / ESP32-S3 / ESP32-C3 (Arduino core 2.0.17 — the only version
# compatible with the lcgamboa WiFi shim):
arduino-cli config add board_manager.additional_urls \
  https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core install esp32:esp32@2.0.17

Option 4: Desktop App (Tauri)

The Velxio Desktop app is a native build (Tauri + the same React frontend) for offline work. Requires a Pro subscription; ships with a 30-day free trial.

  • Offline-capable — the simulator keeps running even with no internet. License is validated on launch with a grace period if the network is down.
  • No browser tab — runs in its own window with native menus and file-system access.
  • Bundled QEMU — ships with the libqemu binaries on Windows / macOS / Linux, so ESP32 and Pi boards work without Docker.

Download from velxio.dev/download. See docs/desktop-app.md for install paths, license flow, and the offline grace banner.

Your First Simulation

  1. Open the editor at velxio.dev/editor or your local instance.
  2. Select a board from the toolbar (e.g., Arduino Uno, ESP32 DevKit, Pi Pico, Pi 3B).
  3. Write code in the Monaco editor — Arduino C++ on every board, or MicroPython on Pico / ESP32 family, or Python 3 on Raspberry Pi.
void setup() {
  pinMode(13, OUTPUT);
}

void loop() {
  digitalWrite(13, HIGH);
  delay(500);
  digitalWrite(13, LOW);
  delay(500);
}
  1. Click Compile — the backend calls arduino-cli (or ESP-IDF, or rp2040 toolchain) and returns a .hex / .bin / .uf2.
  2. Click Run — the simulator executes.
  3. Add components — click the + button on the canvas, pick from 590+ components in the picker (search by name or category).
  4. Connect wires — click a pin to start, click another pin to finish.

Trying analog circuits

  1. Add a Power Supply (5V), a Resistor, and a Voltmeter from the picker.
  2. Wire the supply to the resistor, the resistor to a ground rail, and the voltmeter across the resistor.
  3. The voltmeter shows the steady-state voltage in real time — no MCU code needed.
  4. Add an Op-Amp or Transistor and the ngspice engine solves the netlist every frame.
  5. Drop an Oscilloscope on the canvas, attach probes, and watch waveforms.

See the Electrical Simulation User Guide for the full analog workflow.

Loading an Example Project

380+ examples ship in the gallery, organized into:

  • Basics / 100 Days of Code — Blink, traffic light, button-LED, fade, RGB, Simon Says, LCDs…
  • Circuits — pure analog (filters, dividers, RC, op-amp configurations, transistor amps)
  • Analog & Digital — labelled by signal type
  • E-Paper Displays — Waveshare-style panels
  • Pico W WiFi — networking demos on the Pico W
  • Retro Intel/Zilog — 4004, 4040, 8080, 8086, Z80 driving 7-segments and shift registers

Click Examples in the nav bar, filter by board or category, and click Load.

Troubleshooting

Problem Solution
arduino-cli: command not found Install arduino-cli and add it to your PATH.
LED doesn't blink Open the component property dialog and verify the Arduino pin assignment. Check the browser console for port-listener errors.
Serial Monitor is empty Ensure Serial.begin() is called inside setup().
Compilation errors Open the compilation console at the bottom of the editor for full toolchain output.
ESP32 fails to boot Use esp32:esp32@2.0.17 (the only version compatible with the lcgamboa WiFi shim). Check libqemu-xtensa.{dll,so,dylib} is present in backend/app/services/.
Pi 3 takes 5+ seconds to start Expected — QEMU boots a full Raspberry Pi OS. The "booting" status is normal.
Analog probe reads 0 V Make sure both ends of the wire actually land on a pin (the wire turns blue when valid). Re-check ground connections.
Custom chip won't compile The custom-chip toolchain ships in the Docker image. For manual setups, see Custom Chips: Build & Test.

Community & Links

Next steps