From 16164372cf48e018ff5c2bab365edeeb22ae3521 Mon Sep 17 00:00:00 2001 From: David Montero Crespo Date: Mon, 16 Mar 2026 14:44:06 -0300 Subject: [PATCH] feat: replace code snippets with CodeBlock component for improved formatting in documentation --- frontend/src/pages/DocsPage.tsx | 104 ++++++++++++++++---------------- 1 file changed, 52 insertions(+), 52 deletions(-) diff --git a/frontend/src/pages/DocsPage.tsx b/frontend/src/pages/DocsPage.tsx index 1bcd338..85b1709 100644 --- a/frontend/src/pages/DocsPage.tsx +++ b/frontend/src/pages/DocsPage.tsx @@ -183,40 +183,40 @@ const GettingStartedSection: React.FC = () => (

Option 2: Self-Host with Docker

Run a single Docker command to start a fully local instance:

- 
{`docker run -d \\
+    {`docker run -d \\
   --name velxio \\
   -p 3080:80 \\
   -v $(pwd)/data:/app/data \\
-  ghcr.io/davidmonterocrespo24/velxio:master`}
+ ghcr.io/davidmonterocrespo24/velxio:master`}

Then open http://localhost:3080 in your browser.

Option 3: Manual Setup (Development)

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

1. Clone the repository

- 
{`git clone https://github.com/davidmonterocrespo24/velxio.git
-cd velxio`}
+ {`git clone https://github.com/davidmonterocrespo24/velxio.git +cd velxio`}

2. Start the backend

- 
{`cd backend
+    {`cd backend
 python -m venv venv && source venv/bin/activate
 pip install -r requirements.txt
-uvicorn app.main:app --reload --port 8001`}
+uvicorn app.main:app --reload --port 8001`}

3. Start the frontend

- 
{`cd frontend
+    {`cd frontend
 npm install
-npm run dev`}
+npm run dev`}

Open http://localhost:5173.

4. Set up arduino-cli (first time)

- 
{`arduino-cli core update-index
+    {`arduino-cli core update-index
 arduino-cli core install arduino:avr
 
 # For Raspberry Pi Pico support:
 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`}
+arduino-cli core install rp2040:rp2040`}

Your First Simulation

    @@ -224,7 +224,7 @@ arduino-cli core install rp2040:rp2040`}
  1. Select a board from the toolbar (e.g., Arduino Uno).
  2. Write Arduino code in the Monaco editor, for example:
- 
{`void setup() {
+    {`void setup() {
   pinMode(13, OUTPUT);
 }
 
@@ -233,7 +233,7 @@ void loop() {
   delay(500);
   digitalWrite(13, LOW);
   delay(500);
-}`}
+}`}
  1. Click Compile — the backend calls arduino-cli and returns a .hex file.
  2. Click Run — the AVR8 emulator executes the compiled program.
    3. @@ -278,7 +278,7 @@ const EmulatorSection: React.FC = () => (

    High-Level Data Flow

    - 
    {`User Code (Monaco Editor)
+    {`User Code (Monaco Editor)
         │
         ▼
    Zustand Store (useEditorStore)
@@ -296,7 +296,7 @@ const EmulatorSection: React.FC = () => (
   Port listeners (PORTB / PORTC / PORTD)
         │
         ▼
-  PinManager ──► Component state ──► React re-renders`}
    + PinManager ──► Component state ──► React re-renders`}

    AVR8 Emulation (Arduino Uno / Nano / Mega)

    @@ -306,8 +306,8 @@ const EmulatorSection: React.FC = () => (

    Execution Loop

    Each animation frame executes approximately 267,000 CPU cycles (16 MHz ÷ 60 FPS):

    - 
    {`avrInstruction(cpu);  // decode and execute one AVR instruction
-cpu.tick();           // advance peripheral timers and counters`}
    + {`avrInstruction(cpu); // decode and execute one AVR instruction +cpu.tick(); // advance peripheral timers and counters`}

    Supported Peripherals

    @@ -554,7 +554,7 @@ const ArchitectureSection: React.FC = () => (

    High-Level Overview

    - 
    {`Browser (React + Vite)
+    {`Browser (React + Vite)
   ├── Monaco Editor ──► useEditorStore (Zustand)
   ├── SimulatorCanvas ──► useSimulatorStore (Zustand)
   │     ├── AVRSimulator (avr8js)   16 MHz AVR8 CPU
@@ -563,21 +563,21 @@ const ArchitectureSection: React.FC = () => (
   │     ├── PartSimulationRegistry  16 interactive parts
   │     └── 48+ wokwi-elements      Lit Web Components
   └── HTTP (Axios) ──► FastAPI Backend (port 8001)
-        └── ArduinoCLIService ──► arduino-cli subprocess`}
    + └── ArduinoCLIService ──► arduino-cli subprocess`}

    Data Flows

    1. Compilation

    - 
    {`Click "Compile"
+    {`Click "Compile"
   → EditorToolbar reads all workspace files
   → POST /api/compile/  { files, board_fqbn }
   → Backend: ArduinoCLIService writes temp dir
   → arduino-cli compile --fqbn  --output-dir build/
   → Returns hex_content (Intel HEX string)
-  → useSimulatorStore.setCompiledHex() → loadHex()`}
    + → useSimulatorStore.setCompiledHex() → loadHex()`}

    2. Simulation Loop

    - 
    {`Click "Run"
+    {`Click "Run"
   → AVRSimulator.start()
   → requestAnimationFrame loop @ ~60 FPS
   → Each frame: Math.floor(267 000 × speed) cycles
@@ -586,16 +586,16 @@ const ArchitectureSection: React.FC = () => (
   → PORTB/C/D write listeners fire
   → PinManager.updatePort() → per-pin callbacks
   → PartSimulationRegistry.onPinStateChange()
-  → wokwi-elements update visually`}
    + → wokwi-elements update visually`}

    3. Input Components

    - 
    {`User presses button on canvas
+    {`User presses button on canvas
   → wokwi web component fires 'button-press' event
   → DynamicComponent catches event
   → PartSimulationRegistry.attachEvents() handler
   → AVRSimulator.setPinState(arduinoPin, LOW)
   → AVRIOPort.setPin() injects external pin state
-  → CPU reads pin in next instruction`}
    + → CPU reads pin in next instruction`}

    Key Frontend Stores (Zustand)

    @@ -627,13 +627,13 @@ const ArchitectureSection: React.FC = () => (

    Wire System

    Wires are stored as objects with start/end endpoints tied to component pin positions:

    - 
    {`{
+    {`{
   id: string
   start: { componentId, pinName, x, y }
   end:   { componentId, pinName, x, y }
   color: string
   signalType: 'digital' | 'analog' | 'power-vcc' | 'power-gnd'
-}`}
    +}`}
    @@ -737,7 +737,7 @@ npx tsx ../scripts/generate-component-metadata.ts`}

    How avr8js Powers the Simulation

    - 
    {`import { CPU, avrInstruction, AVRTimer, AVRUSART, AVRADC, AVRIOPort } from 'avr8js';
+    {`import { CPU, avrInstruction, AVRTimer, AVRUSART, AVRADC, AVRIOPort } from 'avr8js';
 
 const cpu   = new CPU(programMemory);          // ATmega328p at 16 MHz
 const portB = new AVRIOPort(cpu, portBConfig); // digital pins 8-13
@@ -751,7 +751,7 @@ function runFrame() {
     cpu.tick();          // advance timers + peripherals
   }
   requestAnimationFrame(runFrame);
-}`}
    +}`}
    Full details:{' '} @@ -797,31 +797,31 @@ const McpSection: React.FC = () => (

    Transport Options

    1. stdio — Claude Desktop / CLI agents

    - 
    {`cd backend
-python mcp_server.py`}
    + {`cd backend +python mcp_server.py`}

    Claude Desktop config (~/.claude/claude_desktop_config.json):

    - 
    {`{
+    {`{
   "mcpServers": {
     "velxio": {
       "command": "python",
       "args": ["/absolute/path/to/velxio/backend/mcp_server.py"]
     }
   }
-}`}
    +}`}

    2. SSE / HTTP — Cursor IDE / web agents

    - 
    {`cd backend
-python mcp_sse_server.py --port 8002`}
    + {`cd backend +python mcp_sse_server.py --port 8002`}

    MCP client config:

    - 
    {`{
+    {`{
   "mcpServers": {
     "velxio": { "url": "http://localhost:8002/sse" }
   }
-}`}
    +}`}

    Circuit Data Format

    Velxio circuits are plain JSON objects:

    - 
    {`{
+    {`{
   "board_fqbn": "arduino:avr:uno",
   "version": 1,
   "components": [
@@ -832,7 +832,7 @@ python mcp_sse_server.py --port 8002`}
    { "from_part": "uno", "from_pin": "13", "to_part": "led1", "to_pin": "A", "color": "green" } ] -}`} +}`}

    Supported Board FQBNs

    @@ -848,7 +848,7 @@ python mcp_sse_server.py --port 8002`}

    Example — Blink LED from Scratch

    - 
    {`// Step 1 — Create a circuit
+    {`// Step 1 — Create a circuit
 {
   "tool": "create_circuit",
   "arguments": {
@@ -892,10 +892,10 @@ python mcp_sse_server.py --port 8002`}
    ], "board": "arduino:avr:uno" } -}`} +}`}

    Setup

    - 
    {`cd backend
+    {`cd backend
 pip install -r requirements.txt
 
 # Ensure arduino-cli is installed
@@ -904,7 +904,7 @@ arduino-cli core update-index
 arduino-cli core install arduino:avr
 
 # Run tests
-python -m pytest tests/test_mcp_tools.py -v`}
    +python -m pytest tests/test_mcp_tools.py -v`}
    Full reference:{' '} @@ -1385,10 +1385,10 @@ const RaspberryPi3EmulationSection: React.FC = () => ( Each Raspberry Pi board instance has its own VFS that maps to files inside the running VM. The default tree is:

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

    Overlay Images