{ "docs": { "components": { "label": "// reference", "heading": "Components Reference", "lead": "Velxio ships with 48+ interactive electronic components powered by wokwi-elements. All components can be placed on the simulation canvas, connected with wires, and interact with your Arduino sketch in real time.", "addingHeading": "Adding Components", "adding1": "Click the + button on the simulation canvas.", "adding2": "Use search or browse by category in the component picker.", "adding3": "Click a component to place it on the canvas.", "adding4": "Drag to reposition; click to open the Property Dialog.", "connectingHeading": "Connecting Components", "connecting1": "Click a pin on any component, a wire starts from that pin.", "connecting2": "Click a destination pin to complete the connection.", "connecting3": "Wires are color-coded by signal type:", "thColor": "Color", "thSignalType": "Signal Type", "colorRed": "Red", "colorBlack": "Black", "colorBlue": "Blue", "colorGreen": "Green", "colorPurple": "Purple", "colorGold": "Gold", "colorOrange": "Orange", "colorCyan": "Cyan", "sigVcc": "VCC (power)", "sigGnd": "GND (ground)", "sigAnalog": "Analog", "sigDigital": "Digital", "sigPwm": "PWM", "sigI2c": "I2C (SDA/SCL)", "sigSpi": "SPI (MOSI/MISO/SCK)", "sigUsart": "USART (TX/RX)", "categoriesHeading": "Component Categories", "outputHeading": "Output", "thComponent": "Component", "thDescription": "Description", "compLed": "LED", "compLedDesc": "Single LED with configurable color", "compRgbLed": "RGB LED", "compRgbLedDesc": "Three-color LED (red, green, blue channels)", "comp7Seg": "7-Segment Display", "comp7SegDesc": "Single digit numeric display", "compLcd16x2": "LCD 16x2", "compLcd16x2Desc": "2-line character LCD (I2C or parallel)", "compLcd20x4": "LCD 20x4", "compLcd20x4Desc": "4-line character LCD", "compIli9341": "ILI9341 TFT", "compIli9341Desc": "240x320 color TFT display (SPI)", "compBuzzer": "Buzzer", "compBuzzerDesc": "Passive piezo buzzer", "compNeoPixel": "NeoPixel", "compNeoPixelDesc": "Individually addressable RGB LED strip", "inputHeading": "Input", "compPushButton": "Push Button", "compPushButtonDesc": "Momentary push button", "compSlideSwitch": "Slide Switch", "compSlideSwitchDesc": "SPDT slide switch", "compPotentiometer": "Potentiometer", "compPotentiometerDesc": "Analog voltage divider (ADC input)", "compRotaryEncoder": "Rotary Encoder", "compRotaryEncoderDesc": "Incremental rotary encoder", "compKeypad": "Keypad 4x4", "compKeypadDesc": "16-button matrix keypad", "compJoystick": "Joystick", "compJoystickDesc": "Dual-axis analog joystick", "sensorsHeading": "Sensors", "compHcSr04": "HC-SR04", "compHcSr04Desc": "Ultrasonic distance sensor", "compDht22": "DHT22", "compDht22Desc": "Temperature and humidity sensor", "compPir": "PIR Motion", "compPirDesc": "Passive infrared motion sensor", "compPhoto": "Photoresistor", "compPhotoDesc": "Light-dependent resistor (LDR)", "compIrRecv": "IR Receiver", "compIrRecvDesc": "38 kHz infrared receiver", "passiveHeading": "Passive Components", "compResistor": "Resistor", "compResistorDesc": "Standard resistor (configurable value)", "compCapacitor": "Capacitor", "compCapacitorDesc": "Electrolytic capacitor", "compInductor": "Inductor", "compInductorDesc": "Coil inductor", "propsHeading": "Component Properties", "propsLead": "Each component has a Property Dialog accessible by clicking it on the canvas:", "thProperty": "Property", "propArduinoPin": "Arduino Pin", "propArduinoPinDesc": "The digital or analog pin this component is connected to", "propColor": "Color", "propColorDesc": "Visual color (LEDs, wires)", "propValue": "Value", "propValueDesc": "Component value (e.g., resistance in Ohm)", "propRotation": "Rotation", "propRotationDesc": "Rotate in 90 degree increments", "propDelete": "Delete", "propDeleteDesc": "Remove the component from the canvas" }, "sectionMeta": { "intro": { "title": "Introduction | Velxio Documentation", "description": "Learn about Velxio, the free open-source Arduino emulator with real AVR8 and RP2040 CPU emulation and 48+ interactive electronic components." }, "gettingStarted": { "title": "Getting Started | Velxio Documentation", "description": "Get started with Velxio: use the hosted editor, self-host with Docker, or set up a local development environment. Simulate your first Arduino sketch in minutes." }, "emulator": { "title": "Emulator Architecture | Velxio Documentation", "description": "How Velxio emulates AVR8 (ATmega328p), RP2040, and RISC-V (ESP32-C3) CPUs. Covers execution loops, peripherals, and pin mapping for all supported boards." }, "riscvEmulation": { "title": "RISC-V Emulation (ESP32-C3) | Velxio Documentation", "description": "Browser-side RV32IMC emulator for ESP32-C3, XIAO ESP32-C3, and C3 SuperMini. Covers memory map, GPIO, UART0, the ESP32 image parser, RV32IMC ISA, and test suite." }, "esp32Emulation": { "title": "ESP32 Emulation (Xtensa) | Velxio Documentation", "description": "QEMU-based emulation for ESP32 and ESP32-S3 (Xtensa LX6/LX7). Covers the lcgamboa fork, libqemu-xtensa, GPIO, WiFi, I2C, SPI, RMT/NeoPixel, and LEDC/PWM." }, "components": { "title": "Components Reference | Velxio Documentation", "description": "Full reference for all 48+ interactive electronic components in Velxio: LEDs, displays, sensors, buttons, potentiometers, and more. Includes wiring and property details." }, "roadmap": { "title": "Roadmap | Velxio Documentation", "description": "Velxio's feature roadmap: what's implemented, what's in progress, and what's planned for future releases." }, "architecture": { "title": "Project Architecture | Velxio Documentation", "description": "Detailed overview of the Velxio system architecture: frontend, backend, AVR8 emulation pipeline, data flows, Zustand stores, and wire system." }, "thirdParty": { "title": "Wokwi Libraries | Velxio Documentation", "description": "How Velxio integrates the official Wokwi open-source libraries: avr8js, wokwi-elements, and rp2040js. Covers configuration, updates, and the 48 available components." }, "mcp": { "title": "MCP Server | Velxio Documentation", "description": "Velxio MCP Server reference: integrate AI agents (Claude, Cursor) with Velxio via Model Context Protocol. Covers tools, transports, circuit format, and example walkthroughs." }, "setup": { "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." }, "rp2040Emulation": { "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." }, "raspberryPi3Emulation": { "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." }, "buildQemu": { "title": "Build QEMU from Source | Velxio Documentation", "description": "Step-by-step guide to compiling libqemu-xtensa and libqemu-riscv32 from the lcgamboa/qemu fork. Self-hosters who would rather not run Velxio prebuilt binaries get full transparency under the AGPLv3 license." } }, "rp2040": { "label": "// arm cortex-m0+", "heading": "RP2040 Emulation (Raspberry Pi Pico)", "lead": "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.", "boardsHeading": "Supported Boards", "boardPico": "Raspberry Pi Pico", "altPico": "Raspberry Pi Pico", "boardPicoW": "Raspberry Pi Pico W", "altPicoW": "Raspberry Pi Pico W", "thBoard": "Board", "thFqbn": "FQBN", "thBuiltinLed": "Built-in LED", "ledGpio25": "GPIO 25", "ledCyw43": "GPIO 25 (via CYW43)", "binaryHeading": "Binary Format", "binaryBody1": "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.", "binaryBody2": "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).", "peripheralsHeading": "Peripherals", "thPeripheral": "Peripheral", "thSupport": "Support", "thNotes": "Notes", "perGpio": "GPIO (30 pins)", "supFull": "Full", "perGpioNotes": "Digital read/write, pull-up/down", "perUart": "UART0 / UART1", "perUartNotes": "Serial Monitor via UART0", "perAdc": "ADC (ch 0-3)", "perAdcNotes": "GPIO 26-29; ch 4 = temperature sensor", "perI2c": "I2C0 / I2C1", "supPartial": "Partial", "perI2cNotes": "DS1307 RTC, TempSensor, EEPROM virtual devices", "perSpi": "SPI0 / SPI1", "supLoopback": "Loopback", "perSpiNotes": "TX looped back to RX", "perPwm": "PWM", "supFreqOnly": "Frequency only", "perPwmNotes": "No waveform output to components", "perTimer": "Timer / Alarm", "perTimerNotes": "Used by delay() and millis()", "wfiHeading": "WFI Optimisation", "wfiBody": "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.", "simLoopHeading": "Simulation Loop", "simLoopBody": "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.", "limitsHeading": "Known Limitations", "limit1": "Pico W wireless chip (CYW43439) is not emulated, WiFi/Bluetooth will not work", "limit2": "SPI loopback only, no real SPI device emulation", "limit3": "PWM produces correct frequency but no visual waveform on components", "limit4": "DMA not emulated", "limit5": "Second CPU core (core 1) not emulated, multicore_launch_core1() has no effect", "fullDocsHeading": "Full Documentation", "fullDocsBody": "See the complete technical reference: RP2040_EMULATION.md" }, "rpi3": { "label": "// qemu raspi3b", "heading": "Raspberry Pi 3 Emulation (QEMU)", "lead": "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.", "boardsHeading": "Supported Boards", "boardRpi3": "Raspberry Pi 3B", "altRpi3": "Raspberry Pi 3B", "thBoard": "Board", "thQemuMachine": "QEMU Machine", "thCpu": "CPU", "boardRpi3Name": "Raspberry Pi 3B", "cpuBcm": "BCM2837, 4x Cortex-A53 @ 1.2 GHz", "serialHeading": "Dual-Channel Serial Architecture", "serialLead": "QEMU exposes two UART channels to the backend:", "serialUser": "ttyAMA0: User serial: interactive terminal (Serial Monitor). The user's print() output appears here.", "serialGpio": "ttyAMA1: GPIO shim: carries a text protocol between the GPIO shim inside the VM and the backend.", "shimHeading": "RPi.GPIO Shim", "shimBody1": "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.", "shimBody2": "The reverse also works: the frontend can send SET 17 1 via WebSocket - backend - ttyAMA1 - shim - user code reads it via GPIO.input(17).", "vfsHeading": "Virtual File System (VFS)", "vfsBody": "Each Raspberry Pi board instance has its own VFS that maps to files inside the running VM. The default tree is:", "overlayHeading": "Overlay Images", "overlayBody": "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.", "limitsHeading": "Known Limitations", "limit1": "No I2C or SPI device emulation", "limit2": "No PWM waveform output to components", "limit3": "No networking (WiFi/Ethernet not emulated)", "limit4": "Session state is not persisted, overlay is discarded on stop", "limit5": "Boot time is slow (~10-20 s) as a full OS must start", "limit6": "Requires the ~5.67 GB base SD image to be present on the server", "fullDocsHeading": "Full Documentation", "fullDocsBody": "See the complete technical reference: RASPBERRYPI3_EMULATION.md" }, "gettingStarted": { "label": "// setup", "heading": "Getting Started", "lead": "Follow these steps to simulate your first Arduino sketch.", "option1Heading": "Option 1: Use the Hosted Version", "option1Body": "No installation needed, go to https://velxio.dev and start coding immediately.", "option2Heading": "Option 2: Self-Host with Docker", "option2Body": "Run a single Docker command to start a fully local instance:", "option2After": "Then open http://localhost:3080 in your browser.", "option3Heading": "Option 3: Manual Setup (Development)", "option3Prereq": "Prerequisites: Node.js 18+, Python 3.12+, arduino-cli", "option3Step1": "1. Clone the repository", "option3Step2": "2. Start the backend", "option3Step3": "3. Start the frontend", "option3Step3After": "Open http://localhost:5173.", "option3Step4": "4. Set up arduino-cli (first time)", "firstSimulationHeading": "Your First Simulation", "firstSim1": "Open the editor at velxio.dev/editor.", "firstSim2": "Select a board from the toolbar (e.g., Arduino Uno).", "firstSim3": "Write Arduino code in the Monaco editor, for example:", "firstSim4": "Click Compile: the backend calls arduino-cli and returns a .hex file.", "firstSim5": "Click Run: the AVR8 emulator executes the compiled program.", "firstSim6": "Add components using the component picker (click the + button on the canvas).", "firstSim7": "Connect wires by clicking a component pin and then another pin.", "troubleshootingHeading": "Troubleshooting", "thProblem": "Problem", "thSolution": "Solution", "tsArduinoCliMissingProblem": "arduino-cli: command not found", "tsArduinoCliMissingSolution": "Install arduino-cli and add it to your PATH.", "tsLedNoBlinkProblem": "LED doesn't blink", "tsLedNoBlinkSolution": "Check the browser console for port listener errors; verify pin assignment in the component property dialog.", "tsSerialEmptyProblem": "Serial Monitor is empty", "tsSerialEmptySolution": "Ensure Serial.begin() is called inside setup() before any Serial.print().", "tsCompileErrorsProblem": "Compilation errors", "tsCompileErrorsSolution": "Check the compilation console at the bottom of the editor for full arduino-cli output." }, "thirdParty": { "label": "// open-source libs", "heading": "Wokwi Libraries", "lead": "Velxio uses official Wokwi open-source repositories cloned locally in third-party/. This gives you up-to-date, compatible emulation engines and visual components without npm registry dependencies.", "clonedHeading": "Cloned Repositories", "thLibrary": "Library", "thLocation": "Location", "libElementsDesc": "48+ Lit Web Components (LEDs, LCDs, sensors, buttons...)", "libAvr8jsDesc": "ATmega328p / ATmega2560 CPU emulator at 16 MHz", "libRp2040jsDesc": "Raspberry Pi Pico (RP2040) emulator", "npmIntro": "All three libraries are pulled directly from the npm registry by frontend/package.json. Reference clones may live under third-party/ for credits and offline hacking, but the build does not require them.", "updatingHeading": "Updating the Libraries", "updatingBody": "Edit the version pins in frontend/package.json (@wokwi/elements, avr8js, rp2040js) and run npm install in frontend/.", "afterBumpHeading": "After bumping wokwi-elements (only when adding new components)", "afterBumpBody": "The metadata generator scans the upstream src/, which the npm package doesn't ship. Clone wokwi-elements once into third-party/ and regenerate:", "availableHeading": "Available Wokwi Components (48)", "thCategory": "Category", "thComponents": "Components", "catBoards": "Boards", "catBoardsList": "Arduino Uno, Mega, Nano, ESP32 DevKit", "catSensors": "Sensors", "catSensorsList": "DHT22, HC-SR04, PIR, Photoresistor, NTC, Joystick", "catDisplays": "Displays", "catDisplaysList": "LCD 16x2, LCD 20x4, 7-Segment", "catInput": "Input", "catInputList": "Push button, 6mm button, Slide switch, DIP switch 8, Potentiometer", "catOutput": "Output", "catOutputList": "LED, RGB LED, LED bar graph, Buzzer, NeoPixel", "catMotors": "Motors", "catMotorsList": "Servo, Stepper motor", "catPassive": "Passive", "catPassiveList": "Resistor, Slide potentiometer, LED ring, Matrix keypad", "catOther": "Other", "catOtherList": "IR receiver, DS1307 RTC, breadboards, etc.", "howAvrHeading": "How avr8js Powers the Simulation", "fullDetailsCallout": "Full details: See docs/WOKWI_LIBS.md in the repository." }, "mcp": { "label": "// AI integration", "heading": "MCP Server", "lead": "Velxio exposes a Model Context Protocol (MCP) server that lets AI agents (Claude, Cursor, and others) create circuits, generate code, and compile Arduino sketches directly.", "toolsHeading": "Available Tools", "thTool": "Tool", "toolCompileDesc": "Compile Arduino sketch files - Intel HEX / binary", "toolRunDesc": "Compile and mark artifact as simulation-ready", "toolImportDesc": "Parse a Wokwi diagram.json - Velxio circuit", "toolExportDesc": "Serialise a Velxio circuit - Wokwi diagram.json", "toolCreateDesc": "Create a new circuit definition", "toolUpdateDesc": "Merge changes into an existing circuit", "toolGenerateDesc": "Generate starter .ino code from a circuit", "transportHeading": "Transport Options", "stdioHeading": "1. stdio: Claude Desktop / CLI agents", "stdioConfigBody": "Claude Desktop config (~/.claude/claude_desktop_config.json):", "sseHeading": "2. SSE / HTTP: Cursor IDE / web agents", "sseConfigBody": "MCP client config:", "circuitFormatHeading": "Circuit Data Format", "circuitFormatLead": "Velxio circuits are plain JSON objects:", "fqbnHeading": "Supported Board FQBNs", "thFqbn": "FQBN", "exampleHeading": "Example: Blink LED from Scratch", "setupHeading": "Setup", "fullRefCallout": "Full reference: See docs/MCP.md in the repository." }, "pagesNav": { "home": "Home", "editor": "Editor", "examples": "Examples" }, "toggleSidebar": "Toggle sidebar", "viewOnGitHub": "View on GitHub", "pageTitle": "Documentation", "pages": "Pages" } }