velxio/frontend/src/i18n/locales/en/docs.json

352 lines
21 KiB
JSON

{
"docs": {
"components": {
"label": "// reference",
"heading": "Components Reference",
"lead": "Velxio ships with <strong>48+ interactive electronic components</strong> powered by <a>wokwi-elements</a>. 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 <strong>+</strong> button on the simulation canvas.",
"adding2": "Use <strong>search</strong> or browse by <strong>category</strong> in the component picker.",
"adding3": "Click a component to place it on the canvas.",
"adding4": "<strong>Drag</strong> to reposition; click to open the <strong>Property Dialog</strong>.",
"connectingHeading": "Connecting Components",
"connecting1": "Click a <strong>pin</strong> on any component, a wire starts from that pin.",
"connecting2": "Click a <strong>destination pin</strong> to complete the connection.",
"connecting3": "Wires are <strong>color-coded</strong> 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 <strong>Property Dialog</strong> 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 <a>rp2040js</a>, 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 <code>arduino-cli</code> targeting <code>rp2040:rp2040:rpipico</code> and returns a raw ARM binary (<code>.bin</code>) 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 <code>#define Serial Serial1</code> to the sketch so that Arduino <code>Serial</code> 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 <code>delay()</code> and <code>millis()</code>",
"wfiHeading": "WFI Optimisation",
"wfiBody": "When the CPU executes a <strong>WFI</strong> (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 <code>delay()</code> calls.",
"simLoopHeading": "Simulation Loop",
"simLoopBody": "The simulation runs inside <code>requestAnimationFrame</code> at ~60 FPS. Each frame executes approximately <strong>2,200,000</strong> 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, <code>multicore_launch_core1()</code> has no effect",
"fullDocsHeading": "Full Documentation",
"fullDocsBody": "See the complete technical reference: <a>RP2040_EMULATION.md</a>"
},
"rpi3": {
"label": "// qemu raspi3b",
"heading": "Raspberry Pi 3 Emulation (QEMU)",
"lead": "The Raspberry Pi 3B is emulated using <strong>QEMU 8.1.3</strong> with <code>-M raspi3b</code>. This is the only board in Velxio that runs a full operating system, a real <strong>Raspberry Pi OS (Trixie)</strong> 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": "<strong>ttyAMA0</strong>: User serial: interactive terminal (Serial Monitor). The user's <code>print()</code> output appears here.",
"serialGpio": "<strong>ttyAMA1</strong>: GPIO shim: carries a text protocol between the GPIO shim inside the VM and the backend.",
"shimHeading": "RPi.GPIO Shim",
"shimBody1": "A custom <code>RPi.GPIO</code> shim is injected at <code>/usr/local/lib/python3.11/dist-packages/RPi/GPIO.py</code> inside the VM. When user code calls <code>GPIO.output(pin, value)</code>, the shim writes a line like <code>GPIO 17 1</code> to <strong>ttyAMA1</strong>. The backend reads this, fires a <code>gpio_change</code> WebSocket event, and the frontend updates the visual component on the canvas.",
"shimBody2": "The reverse also works: the frontend can send <code>SET 17 1</code> via WebSocket - backend - ttyAMA1 - shim - user code reads it via <code>GPIO.input(17)</code>.",
"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 <strong> qcow2 overlay</strong> 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: <a>RASPBERRYPI3_EMULATION.md</a>"
},
"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 <a>https://velxio.dev</a> 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 <strong>http://localhost:3080</strong> in your browser.",
"option3Heading": "Option 3: Manual Setup (Development)",
"option3Prereq": "<strong>Prerequisites:</strong> Node.js 18+, Python 3.12+, <code>arduino-cli</code>",
"option3Step1": "1. Clone the repository",
"option3Step2": "2. Start the backend",
"option3Step3": "3. Start the frontend",
"option3Step3After": "Open <strong>http://localhost:5173</strong>.",
"option3Step4": "4. Set up arduino-cli (first time)",
"firstSimulationHeading": "Your First Simulation",
"firstSim1": "<strong>Open the editor</strong> at <a>velxio.dev/editor</a>.",
"firstSim2": "<strong>Select a board</strong> from the toolbar (e.g., <em>Arduino Uno</em>).",
"firstSim3": "<strong>Write Arduino code</strong> in the Monaco editor, for example:",
"firstSim4": "<strong>Click Compile</strong>: the backend calls <code>arduino-cli</code> and returns a <code>.hex</code> file.",
"firstSim5": "<strong>Click Run</strong>: the AVR8 emulator executes the compiled program.",
"firstSim6": "<strong>Add components</strong> using the component picker (click the <strong>+</strong> button on the canvas).",
"firstSim7": "<strong>Connect wires</strong> by clicking a component pin and then another pin.",
"troubleshootingHeading": "Troubleshooting",
"thProblem": "Problem",
"thSolution": "Solution",
"tsArduinoCliMissingProblem": "<code>arduino-cli: command not found</code>",
"tsArduinoCliMissingSolution": "Install <code>arduino-cli</code> 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 <code>Serial.begin()</code> is called inside <code>setup()</code> before any <code>Serial.print()</code>.",
"tsCompileErrorsProblem": "Compilation errors",
"tsCompileErrorsSolution": "Check the compilation console at the bottom of the editor for full <code>arduino-cli</code> output."
},
"thirdParty": {
"label": "// open-source libs",
"heading": "Wokwi Libraries",
"lead": "Velxio uses official Wokwi open-source repositories cloned locally in <code>third-party/</code>. 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 <code>frontend/package.json</code>. Reference clones may live under <code>third-party/</code> for credits and offline hacking, but the build does not require them.",
"updatingHeading": "Updating the Libraries",
"updatingBody": "Edit the version pins in <code>frontend/package.json</code> (<code>@wokwi/elements</code>, <code>avr8js</code>, <code>rp2040js</code>) and run <code>npm install</code> in <code>frontend/</code>.",
"afterBumpHeading": "After bumping wokwi-elements (only when adding new components)",
"afterBumpBody": "The metadata generator scans the upstream <code>src/</code>, which the npm package doesn't ship. Clone wokwi-elements once into <code>third-party/</code> 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": "<strong>Full details:</strong> See <a>docs/WOKWI_LIBS.md</a> in the repository."
},
"mcp": {
"label": "// AI integration",
"heading": "MCP Server",
"lead": "Velxio exposes a <a>Model Context Protocol</a> (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 <code>diagram.json</code> - Velxio circuit",
"toolExportDesc": "Serialise a Velxio circuit - Wokwi <code>diagram.json</code>",
"toolCreateDesc": "Create a new circuit definition",
"toolUpdateDesc": "Merge changes into an existing circuit",
"toolGenerateDesc": "Generate starter <code>.ino</code> code from a circuit",
"transportHeading": "Transport Options",
"stdioHeading": "1. stdio: Claude Desktop / CLI agents",
"stdioConfigBody": "Claude Desktop config (<code>~/.claude/claude_desktop_config.json</code>):",
"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": "<strong>Full reference:</strong> See <a>docs/MCP.md</a> in the repository."
},
"pagesNav": {
"home": "Home",
"editor": "Editor",
"examples": "Examples"
},
"toggleSidebar": "Toggle sidebar",
"viewOnGitHub": "View on GitHub",
"pageTitle": "Documentation",
"pages": "Pages"
}
}