diff --git a/CLAUDE.md b/CLAUDE.md index 19f51c0..630822a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -423,7 +423,7 @@ Enable verbose logging: ## Additional Resources - Main README: [README.md](README.md) -- Architecture Details: [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) +- Architecture Details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Wokwi Elements Repo: https://github.com/wokwi/wokwi-elements - AVR8js Repo: https://github.com/wokwi/avr8js - Arduino CLI Docs: https://arduino.github.io/arduino-cli/ diff --git a/README.md b/README.md index 9de4c5f..d0d0182 100644 --- a/README.md +++ b/README.md @@ -46,19 +46,19 @@ Then open **http://localhost:3080**. ## Screenshots -![Raspberry Pi Pico ADC simulation with Serial Monitor](doc/img1.png) +![Raspberry Pi Pico ADC simulation with Serial Monitor](docs/img1.png) Raspberry Pi Pico simulation — ADC read test with two potentiometers, Serial Monitor showing live output, and compilation console at the bottom. -![ILI9341 TFT display simulation on Arduino Uno](doc/img2.png) +![ILI9341 TFT display simulation on Arduino Uno](docs/img2.png) Arduino Uno driving an ILI9341 240×320 TFT display via SPI — rendering a real-time graphics demo using Adafruit_GFX + Adafruit_ILI9341. -![Library Manager with full library list](doc/img3.png) +![Library Manager with full library list](docs/img3.png) Library Manager loads the full Arduino library index on open — browse and install libraries without typing first. -![Component Picker with 48 components](doc/img4.png) +![Component Picker with 48 components](docs/img4.png) Component Picker showing 48 available components with visual previews, search, and category filters. diff --git a/doc/ARCHITECTURE.md b/docs/ARCHITECTURE.md similarity index 100% rename from doc/ARCHITECTURE.md rename to docs/ARCHITECTURE.md diff --git a/doc/MCP.md b/docs/MCP.md similarity index 100% rename from doc/MCP.md rename to docs/MCP.md diff --git a/doc/SETUP_COMPLETE.md b/docs/SETUP_COMPLETE.md similarity index 97% rename from doc/SETUP_COMPLETE.md rename to docs/SETUP_COMPLETE.md index c1d5461..c348051 100644 --- a/doc/SETUP_COMPLETE.md +++ b/docs/SETUP_COMPLETE.md @@ -121,9 +121,9 @@ Repositorios oficiales de Wokwi en `wokwi-libs/`: | Archivo | Descripción | |---------|-------------| | `README.md` | Instrucciones de instalación y uso | -| `doc/ARCHITECTURE.md` | Arquitectura detallada del proyecto | -| `doc/WOKWI_LIBS.md` | Guía de integración con Wokwi | -| `doc/SETUP_COMPLETE.md` | Este archivo — estado del proyecto | +| `docs/ARCHITECTURE.md` | Arquitectura detallada del proyecto | +| `docs/WOKWI_LIBS.md` | Guía de integración con Wokwi | +| `docs/SETUP_COMPLETE.md` | Este archivo — estado del proyecto | | `CLAUDE.md` | Guía para asistentes IA | | `update-wokwi-libs.bat` | Script de actualización automática | diff --git a/doc/WOKWI_LIBS.md b/docs/WOKWI_LIBS.md similarity index 100% rename from doc/WOKWI_LIBS.md rename to docs/WOKWI_LIBS.md diff --git a/docs/components.md b/docs/components.md new file mode 100644 index 0000000..3bbd866 --- /dev/null +++ b/docs/components.md @@ -0,0 +1,113 @@ +# Components Reference + +Velxio ships with **48+ interactive electronic components** powered by [wokwi-elements](https://github.com/wokwi/wokwi-elements). All components can be placed on the simulation canvas, connected with wires, and interact with your Arduino sketch in real time. + +--- + +## Adding Components + +1. Click the **+** button on the simulation canvas. +2. Use **search** or browse by **category** in the component picker. +3. Click a component to place it on the canvas. +4. **Drag** to reposition; click to open the **Property Dialog** (pin roles, Arduino pin assignment, rotate, delete). + +--- + +## Connecting Components + +1. Click a **pin** on any component — a wire starts from that pin. +2. Click a **destination pin** to complete the connection. +3. Wires are **color-coded** by signal type: + +| Color | Signal type | +|-------|-------------| +| 🔴 Red | VCC (power) | +| ⚫ Black | GND (ground) | +| 🔵 Blue | Analog | +| 🟢 Green | Digital | +| 🟣 Purple | PWM | +| 🟡 Gold | I2C (SDA/SCL) | +| 🟠 Orange | SPI (MOSI/MISO/SCK) | +| 🩵 Cyan | USART (TX/RX) | + +--- + +## Component Categories + +### Output + +| Component | Description | +|-----------|-------------| +| LED | Single LED with configurable color | +| RGB LED | Three-color LED (red, green, blue channels) | +| 7-Segment Display | Single digit numeric display | +| LCD 16×2 | 2-line character LCD (I2C or parallel) | +| LCD 20×4 | 4-line character LCD | +| ILI9341 TFT | 240×320 color TFT display (SPI) | +| Buzzer | Passive piezo buzzer | +| NeoPixel | Individually addressable RGB LED strip | + +### Input + +| Component | Description | +|-----------|-------------| +| Push Button | Momentary push button | +| Slide Switch | SPDT slide switch | +| Potentiometer | Analog voltage divider (ADC input) | +| Rotary Encoder | Incremental rotary encoder | +| Keypad 4×4 | 16-button matrix keypad | +| Joystick | Dual-axis analog joystick | + +### Sensors + +| Component | Description | +|-----------|-------------| +| HC-SR04 | Ultrasonic distance sensor | +| DHT22 | Temperature and humidity sensor | +| PIR Motion | Passive infrared motion sensor | +| NTC Thermistor | Analog temperature sensor | +| Photoresistor | Light-dependent resistor (LDR) | +| IR Receiver | 38 kHz infrared receiver | + +### Passive Components + +| Component | Description | +|-----------|-------------| +| Resistor | Standard resistor (configurable value) | +| Capacitor | Electrolytic capacitor | +| Inductor | Coil inductor | + +### Communication + +| Component | Description | +|-----------|-------------| +| I2C EEPROM | 24Cxx series EEPROM (I2C) | +| SPI Flash | 25-series SPI NOR flash | +| RFID (RC522) | SPI RFID reader/writer | + +### Power & Connectors + +| Component | Description | +|-----------|-------------| +| Power Rail | VCC / GND bus bar | +| Terminal Block | 2-pin screw terminal | + +--- + +## Component Properties + +Each component has a **Property Dialog** accessible by clicking it on the canvas: + +| Property | Description | +|----------|-------------| +| Arduino Pin | The digital or analog pin this component is connected to | +| Color | Visual color (LEDs, wires) | +| Value | Component value (e.g., resistance in Ω) | +| Rotation | Rotate in 90° increments | +| Delete | Remove the component from the canvas | + +--- + +## Adding Custom Components + +See [Architecture: Component System](./emulator.md#component-system) for details on registering new wokwi-elements components in the simulation. diff --git a/docs/emulator.md b/docs/emulator.md new file mode 100644 index 0000000..e3e6eae --- /dev/null +++ b/docs/emulator.md @@ -0,0 +1,132 @@ +# Emulator Architecture + +Velxio uses **real CPU emulation** rather than a simplified model. This document describes how each layer of the simulation works. + +--- + +## High-Level Data Flow + +``` +User Code (Monaco Editor) + │ + ▼ + Zustand Store (useEditorStore) + │ + ▼ + FastAPI Backend ──► arduino-cli subprocess ──► .hex / .uf2 file + │ + ▼ + AVRSimulator / RP2040Simulator + │ loadHex() + ▼ + CPU execution loop (~60 FPS via requestAnimationFrame) + │ + ▼ + Port listeners (PORTB / PORTC / PORTD) + │ + ▼ + PinManager ──► Component state updates ──► React re-renders +``` + +--- + +## AVR8 Emulation (Arduino Uno / Nano / Mega) + +The AVR backend uses **[avr8js](https://github.com/wokwi/avr8js)**, which implements a complete ATmega328p / ATmega2560 processor. + +### Execution Loop + +Each animation frame executes approximately 267,000 CPU cycles (16 MHz ÷ 60 FPS): + +```typescript +avrInstruction(cpu); // decode and execute one AVR instruction +cpu.tick(); // advance peripheral timers and counters +``` + +### Supported Peripherals + +| Peripheral | Details | +|-----------|---------| +| GPIO | PORTB (pins 8–13), PORTC (A0–A5), PORTD (pins 0–7) | +| Timer0 / Timer1 / Timer2 | `millis()`, `delay()`, PWM via `analogWrite()` | +| USART | Full transmit and receive — powers the Serial Monitor | +| ADC | 10-bit, 5 V reference on pins A0–A5 | +| SPI | Hardware SPI (enables ILI9341, SD card, etc.) | +| I2C (TWI) | Hardware I2C with virtual device bus | + +### Pin Mapping + +| Arduino Pin | AVR Port | Bit | +|-------------|----------|-----| +| 0–7 | PORTD | 0–7 | +| 8–13 | PORTB | 0–5 | +| A0–A5 | PORTC | 0–5 | + +--- + +## RP2040 Emulation (Raspberry Pi Pico) + +The RP2040 backend uses **[rp2040js](https://github.com/wokwi/rp2040js)**. + +### Features + +- Real RP2040 emulation at 133 MHz +- UART0 serial output displayed in the Serial Monitor +- 12-bit ADC on GPIO 26–29 (A0–A3) with 3.3 V reference + +### Compilation + +Pico sketches are compiled with the [arduino-pico](https://github.com/earlephilhower/arduino-pico) core via `arduino-cli`. The Serial redirect patch is applied only to `sketch.ino` to route `Serial.print()` output to UART0. + +--- + +## HEX File Format + +Arduino compilation produces **Intel HEX** format. The parser in `hexParser.ts`: + +1. Reads lines starting with `:` +2. Extracts the address, record type, and data bytes +3. Returns a `Uint8Array` of program bytes +4. `AVRSimulator` converts this to a `Uint16Array` (16-bit words, little-endian) and loads it into the CPU's program memory + +--- + +## Component System + +Components are rendered using **[wokwi-elements](https://github.com/wokwi/wokwi-elements)** — a library of Web Components for electronic parts. + +### Component Registration + +1. The component is rendered on the `SimulatorCanvas`. +2. A pin-change callback is registered in `PinManager`. +3. The callback updates component state in the Zustand store. +4. React re-renders the component with the updated state. + +### Wire Routing + +Wires use **orthogonal routing** (no diagonal paths). Each wire stores: + +```typescript +{ + id: string + start: { componentId, pinName, x, y } + end: { componentId, pinName, x, y } + color: string // e.g. 'red' for VCC + signalType: 'digital' | 'analog' | 'power-vcc' | 'power-gnd' +} +``` + +Wire positions update automatically when components are moved. + +--- + +## Key Source Files + +| File | Purpose | +|------|---------| +| `frontend/src/simulation/AVRSimulator.ts` | AVR8 CPU emulator wrapper | +| `frontend/src/simulation/PinManager.ts` | Maps Arduino pins to UI components | +| `frontend/src/utils/hexParser.ts` | Intel HEX parser | +| `frontend/src/components/simulator/SimulatorCanvas.tsx` | Canvas rendering | +| `backend/app/services/arduino_cli.py` | arduino-cli wrapper | +| `backend/app/api/routes/compile.py` | Compilation API endpoint | diff --git a/doc/examples/README.md b/docs/examples/README.md similarity index 100% rename from doc/examples/README.md rename to docs/examples/README.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..de9bb01 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,116 @@ +# Getting Started + +Velxio is an open-source Arduino emulator that runs entirely in your browser. Follow these steps to simulate your first Arduino sketch. + +--- + +## Option 1: Use the Hosted Version + +No installation needed — go to **[https://velxio.dev](https://velxio.dev)** and start coding immediately. + +--- + +## Option 2: Self-Host with Docker + +Run a single Docker command to start a fully local instance: + +```bash +docker run -d \ + --name velxio \ + -p 3080:80 \ + -v $(pwd)/data:/app/data \ + 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 + +```bash +git clone https://github.com/davidmonterocrespo24/velxio.git +cd velxio +``` + +### 2. Start the backend + +```bash +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 + +```bash +# In a new terminal: +cd frontend +npm install +npm run dev +``` + +Open **http://localhost:5173**. + +### 4. Set up arduino-cli (first time) + +```bash +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 +``` + +--- + +## Your First Simulation + +1. **Open the editor** at [velxio.dev/editor](https://velxio.dev/editor) (or your local instance). +2. **Select a board** from the toolbar (e.g., *Arduino Uno*). +3. **Write Arduino code** in the Monaco editor, for example: + +```cpp +void setup() { + pinMode(13, OUTPUT); +} + +void loop() { + digitalWrite(13, HIGH); + delay(500); + digitalWrite(13, LOW); + delay(500); +} +``` + +4. **Click Compile** — the backend calls `arduino-cli` and returns a `.hex` file. +5. **Click Run** — the AVR8 emulator executes the compiled program. +6. **Add components** using the component picker (click the **+** button on the canvas). +7. **Connect wires** by clicking a component pin and then another pin. + +--- + +## Loading an Example Project + +1. Click **Examples** in the navigation bar. +2. Choose a project such as *Blink*, *Traffic Light*, or *LCD 20×4*. +3. Click **Load** — the code and components are imported automatically. +4. Click **Run** to start the simulation. + +--- + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| `arduino-cli: command not found` | Install `arduino-cli` and add it to your PATH. | +| LED doesn't blink | Check the browser console for port listener errors; verify pin assignment in the component property dialog. | +| Serial Monitor is empty | Ensure `Serial.begin()` is called inside `setup()` before any `Serial.print()`. | +| Compilation errors | Check the compilation console at the bottom of the editor for full `arduino-cli` output. | diff --git a/doc/img1.png b/docs/img1.png similarity index 100% rename from doc/img1.png rename to docs/img1.png diff --git a/doc/img2.png b/docs/img2.png similarity index 100% rename from doc/img2.png rename to docs/img2.png diff --git a/doc/img3.png b/docs/img3.png similarity index 100% rename from doc/img3.png rename to docs/img3.png diff --git a/doc/img4.png b/docs/img4.png similarity index 100% rename from doc/img4.png rename to docs/img4.png diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 0000000..56ab891 --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,36 @@ +# Velxio — Introduction + +**Velxio** is a fully local, open-source Arduino emulator that runs entirely in your browser. + +Write Arduino C++ code, compile it with a real `arduino-cli` backend, and simulate it using true AVR8 / RP2040 CPU emulation — with 48+ interactive electronic components, all without installing any software on your machine. + +--- + +## Why Velxio? + +- **No installation required** — everything runs in the browser. +- **Real emulation** — not a simplified model, but accurate AVR8 / RP2040 CPU emulation. +- **Interactive components** — LEDs, buttons, potentiometers, displays, sensors, and more. +- **Open-source** — inspect, modify, and self-host it yourself. + +--- + +## Supported Boards + +| Board | CPU | Emulator | +|-------|-----|----------| +| Arduino Uno | ATmega328p @ 16 MHz | avr8js | +| Arduino Nano | ATmega328p @ 16 MHz | avr8js | +| Arduino Mega | ATmega2560 @ 16 MHz | avr8js | +| Raspberry Pi Pico | RP2040 @ 133 MHz | rp2040js | + +--- + +## Quick Links + +- [Getting Started](./getting-started.md) +- [Emulator Architecture](./emulator.md) +- [Components Reference](./components.md) +- [Roadmap](./roadmap.md) +- [Live Demo](https://velxio.dev) +- [GitHub Repository](https://github.com/davidmonterocrespo24/velxio) diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..8bc87b5 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,105 @@ +# Roadmap + +This document lists the features that are implemented, in progress, and planned for future releases of Velxio. + +--- + +## ✅ Implemented + +### Editor +- Monaco Editor with C++ syntax highlighting, autocomplete, and minimap +- Multi-file workspace — create, rename, delete, and switch between `.ino`, `.h`, `.cpp` files +- Unsaved-changes indicator on file tabs +- Resizable file explorer panel + +### Compilation +- Arduino compilation via `arduino-cli` backend +- Multi-file sketch support +- Compilation console with full output, warnings, and errors + +### Simulation — AVR (Uno / Nano / Mega) +- Real ATmega328p / ATmega2560 emulation at 16 MHz via avr8js +- Full GPIO: PORTB (8–13), PORTC (A0–A5), PORTD (0–7) +- Timer0/1/2 — `millis()`, `delay()`, `analogWrite()` +- USART — Serial transmit and receive +- ADC — `analogRead()` on A0–A5, voltage injection from potentiometers +- SPI — ILI9341 TFT display +- I2C (TWI) — virtual device bus + +### Simulation — RP2040 (Raspberry Pi Pico) +- Real RP2040 emulation at 133 MHz via rp2040js +- UART0 serial output in Serial Monitor +- 12-bit ADC on GPIO 26–29 + +### Components +- 48+ wokwi-elements components +- Component picker with search and category filters +- Drag-and-drop repositioning +- Component rotation (90° increments) +- Property dialog (pin assignment, rotate, delete) + +### Wire System +- Click-to-connect wire creation +- Orthogonal routing (no diagonal paths) +- 8 signal-type color codes +- Segment-based wire editing (drag segments) + +### Serial Monitor +- Live serial output +- Auto baud-rate detection +- Send data to Arduino RX + +### Library Manager +- Browse and install the full Arduino library index +- Live search, installed-tab, version display + +### Auth & Projects +- Email/password and Google OAuth sign-in +- Project save, update, and delete +- Permanent project URLs (`/project/:id`) +- User profile page (`/:username`) with public projects + +### Example Projects +- 8 built-in examples: Blink, Traffic Light, Button Control, Fade LED, Serial Hello World, RGB LED, Simon Says, LCD 20×4 + +### Deploy +- Single-container Docker image (GHCR + Docker Hub) +- GitHub Actions CI/CD pipeline + +--- + +## 🔄 In Progress + +- **Functional wire connections** — electrical signal routing and validation +- **Wire connection error handling** — detect short circuits and invalid connections + +--- + +## 🗓 Planned + +### Near-Term +- **Undo / redo** — for code edits and canvas changes +- **Export / import projects** as `.zip` files +- **More boards** — ESP32, Arduino Nano, Arduino Leonardo +- **Breadboard** — place components on a virtual breadboard with automatic wire routing + +### Mid-Term +- **TypeDoc API documentation** — auto-generated from source code +- **GitHub Pages docs site** — automatic deployment on push to `main` +- **More sensor simulations** — HC-SR04 (ultrasonic), DHT22 (temperature/humidity), IR receiver +- **EEPROM emulation** — persistent read/write across simulation restarts +- **Oscilloscope component** — plot analog pin voltages over time + +### Long-Term +- **Multiplayer** — share and co-edit simulations in real time +- **Embedded tutorial system** — step-by-step guided projects inside the editor +- **Custom component SDK** — define new components with a JSON/TypeScript API +- **Mobile / tablet support** — responsive layout for touch devices + +--- + +## Contributing + +Feature requests, bug reports, and pull requests are welcome at [github.com/davidmonterocrespo24/velxio](https://github.com/davidmonterocrespo24/velxio). + +All contributors must sign a Contributor License Agreement (CLA); a CLA check runs automatically on pull requests. diff --git a/frontend/README.md b/frontend/README.md index e19e288..73a0a84 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -209,8 +209,8 @@ See [backend documentation](../backend/README.md) for API details. - [Main Project README](../README.md) - [Development Guide (CLAUDE.md)](../CLAUDE.md) -- [Architecture Documentation](../doc/ARCHITECTURE.md) -- [Wokwi Integration](../doc/WOKWI_LIBS.md) +- [Architecture Documentation](../docs/ARCHITECTURE.md) +- [Wokwi Integration](../docs/WOKWI_LIBS.md) - [Monaco Editor API](https://microsoft.github.io/monaco-editor/api/index.html) - [Vite Documentation](https://vitejs.dev/) - [Zustand Guide](https://docs.pmnd.rs/zustand/getting-started/introduction) diff --git a/frontend/public/sitemap.xml b/frontend/public/sitemap.xml index 964b4eb..155dae9 100644 --- a/frontend/public/sitemap.xml +++ b/frontend/public/sitemap.xml @@ -16,6 +16,13 @@ 0.9 + + https://velxio.dev/docs + 2026-03-11 + weekly + 0.8 + + https://velxio.dev/examples 2026-03-06 diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 8fba3a6..b9e2fde 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -9,6 +9,7 @@ import { UserProfilePage } from './pages/UserProfilePage'; import { ProjectPage } from './pages/ProjectPage'; import { ProjectByIdPage } from './pages/ProjectByIdPage'; import { AdminPage } from './pages/AdminPage'; +import { DocsPage } from './pages/DocsPage'; import { useAuthStore } from './store/useAuthStore'; import './App.css'; @@ -28,6 +29,7 @@ function App() { } /> } /> } /> + } /> {/* Canonical project URL by ID */} } /> {/* Legacy slug route — redirects to /project/:id */} diff --git a/frontend/src/pages/DocsPage.css b/frontend/src/pages/DocsPage.css new file mode 100644 index 0000000..b09eeb5 --- /dev/null +++ b/frontend/src/pages/DocsPage.css @@ -0,0 +1,441 @@ +/* ── CSS Variables (match LandingPage) ─────────────────── */ +:root { + --accent: #007acc; + --bg: #09090b; + --bg-card: #0f0f12; + --bg-alt: #07070a; + --border: #18181f; + --border-hi: #252530; + --text: #d8d8e0; + --text-muted: #72727e; + --font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; + --mono: 'Fira Code', 'Cascadia Code', 'Consolas', monospace; + --radius: 3px; + --sidebar-w: 240px; + --nav-h: 52px; +} + +/* ── Page layout ────────────────────────────────────────── */ +.docs-page { + min-height: 100vh; + background: var(--bg); + color: var(--text); + font-family: var(--font); + display: flex; + flex-direction: column; +} + +/* ── Nav ─────────────────────────────────────────────────── */ +.docs-nav { + position: sticky; + top: 0; + z-index: 100; + display: flex; + align-items: center; + gap: 8px; + padding: 0 24px; + height: var(--nav-h); + background: rgba(9, 9, 11, 0.92); + backdrop-filter: blur(10px); + border-bottom: 1px solid var(--border); +} + +.docs-nav-brand { + display: flex; + align-items: center; + gap: 8px; + font-size: 16px; + font-weight: 700; + color: var(--text); + text-decoration: none; + font-family: var(--mono); +} + +.docs-nav-brand svg { + width: 18px; + height: 18px; + color: var(--accent); +} + +.docs-nav-divider { + color: var(--text-muted); + font-size: 18px; + margin: 0 2px; +} + +.docs-nav-section { + font-size: 14px; + color: var(--text-muted); + font-family: var(--mono); +} + +.docs-nav-links { + display: flex; + align-items: center; + gap: 4px; + margin-left: auto; +} + +.docs-nav-link { + display: flex; + align-items: center; + gap: 6px; + padding: 5px 10px; + color: var(--text-muted); + text-decoration: none; + font-size: 13px; + border-radius: var(--radius); + transition: color 0.15s, background 0.15s; +} + +.docs-nav-link svg { + width: 14px; + height: 14px; +} + +.docs-nav-link:hover { + color: var(--text); + background: rgba(255, 255, 255, 0.05); +} + +.docs-nav-btn { + padding: 5px 12px; + background: var(--bg-card); + border: 1px solid var(--border-hi); + color: var(--text); + text-decoration: none; + font-size: 13px; + border-radius: var(--radius); + transition: border-color 0.15s, background 0.15s; +} + +.docs-nav-btn:hover { + border-color: #444; + background: rgba(255, 255, 255, 0.06); +} + +.docs-sidebar-toggle { + display: none; + background: transparent; + border: 1px solid var(--border-hi); + color: var(--text-muted); + cursor: pointer; + padding: 5px 7px; + border-radius: var(--radius); + margin-left: auto; +} + +.docs-sidebar-toggle svg { + width: 16px; + height: 16px; + display: block; +} + +/* ── Body layout ─────────────────────────────────────────── */ +.docs-body { + display: flex; + flex: 1; +} + +/* ── Sidebar ─────────────────────────────────────────────── */ +.docs-sidebar { + width: var(--sidebar-w); + min-width: var(--sidebar-w); + background: var(--bg-card); + border-right: 1px solid var(--border); + display: flex; + flex-direction: column; + padding: 24px 0 24px; + position: sticky; + top: var(--nav-h); + height: calc(100vh - var(--nav-h)); + overflow-y: auto; +} + +.docs-sidebar-title { + font-size: 11px; + font-weight: 600; + color: var(--text-muted); + text-transform: uppercase; + letter-spacing: 0.08em; + padding: 0 20px 12px; +} + +.docs-sidebar-nav { + display: flex; + flex-direction: column; + gap: 2px; + padding: 0 8px; +} + +.docs-sidebar-item { + display: block; + width: 100%; + text-align: left; + padding: 7px 12px; + background: transparent; + border: none; + color: var(--text-muted); + font-size: 13.5px; + border-radius: var(--radius); + cursor: pointer; + transition: color 0.15s, background 0.15s; +} + +.docs-sidebar-item:hover { + color: var(--text); + background: rgba(255, 255, 255, 0.05); +} + +.docs-sidebar-item--active { + color: var(--accent); + background: rgba(0, 122, 204, 0.12); +} + +.docs-sidebar-footer { + margin-top: auto; + padding: 16px 20px 0; +} + +.docs-sidebar-gh { + display: flex; + align-items: center; + gap: 6px; + color: var(--text-muted); + text-decoration: none; + font-size: 12.5px; + transition: color 0.15s; +} + +.docs-sidebar-gh svg { + width: 14px; + height: 14px; + flex-shrink: 0; +} + +.docs-sidebar-gh:hover { + color: var(--text); +} + +/* ── Main content ─────────────────────────────────────────── */ +.docs-main { + flex: 1; + min-width: 0; + padding: 48px 64px; + max-width: 860px; +} + +/* ── Section typography ───────────────────────────────────── */ +.docs-section { + line-height: 1.7; +} + +.docs-label { + font-family: var(--mono); + font-size: 12px; + color: var(--accent); + letter-spacing: 0.04em; + display: block; + margin-bottom: 8px; +} + +.docs-section h1 { + font-size: 2rem; + font-weight: 700; + color: #fff; + margin: 0 0 20px; + letter-spacing: -0.02em; +} + +.docs-section h2 { + font-size: 1.25rem; + font-weight: 600; + color: #fff; + margin: 36px 0 14px; + padding-bottom: 8px; + border-bottom: 1px solid var(--border); +} + +.docs-section h3 { + font-size: 1rem; + font-weight: 600; + color: #d0d0e0; + margin: 24px 0 10px; +} + +.docs-section p { + color: var(--text); + margin: 0 0 16px; +} + +.docs-section ul, +.docs-section ol { + margin: 0 0 16px; + padding-left: 24px; + color: var(--text); +} + +.docs-section li { + margin-bottom: 6px; +} + +.docs-section a { + color: var(--accent); + text-decoration: none; +} + +.docs-section a:hover { + text-decoration: underline; +} + +.docs-section code { + font-family: var(--mono); + font-size: 0.88em; + background: rgba(255, 255, 255, 0.07); + border: 1px solid var(--border-hi); + border-radius: 3px; + padding: 1px 5px; + color: #c9d1d9; +} + +.docs-section pre { + background: var(--bg-alt); + border: 1px solid var(--border); + border-radius: 6px; + padding: 18px 20px; + overflow-x: auto; + margin: 0 0 20px; +} + +.docs-section pre code { + background: transparent; + border: none; + padding: 0; + font-size: 0.85rem; + color: #c9d1d9; + white-space: pre; +} + +/* ── Tables ───────────────────────────────────────────────── */ +.docs-section table { + width: 100%; + border-collapse: collapse; + font-size: 14px; + margin: 0 0 24px; +} + +.docs-section th { + background: var(--bg-card); + color: var(--text-muted); + font-weight: 600; + text-align: left; + padding: 9px 14px; + border: 1px solid var(--border); + font-size: 12px; + text-transform: uppercase; + letter-spacing: 0.04em; +} + +.docs-section td { + padding: 9px 14px; + border: 1px solid var(--border); + color: var(--text); + vertical-align: top; +} + +.docs-section tr:hover td { + background: rgba(255, 255, 255, 0.02); +} + +/* ── Callout ─────────────────────────────────────────────── */ +.docs-callout { + background: rgba(0, 122, 204, 0.08); + border: 1px solid rgba(0, 122, 204, 0.25); + border-radius: 6px; + padding: 14px 18px; + font-size: 14px; + color: var(--text); + margin: 24px 0; +} + +.docs-callout a { + color: var(--accent); +} + +/* ── Wire dot ─────────────────────────────────────────────── */ +.wire-dot { + display: inline-block; + width: 10px; + height: 10px; + border-radius: 50%; + margin-right: 6px; + vertical-align: middle; +} + +/* ── Pagination ──────────────────────────────────────────── */ +.docs-pagination { + display: flex; + justify-content: space-between; + align-items: center; + margin-top: 56px; + padding-top: 24px; + border-top: 1px solid var(--border); + gap: 12px; +} + +.docs-pagination-btn { + background: var(--bg-card); + border: 1px solid var(--border-hi); + color: var(--text-muted); + font-size: 13.5px; + border-radius: var(--radius); + padding: 9px 16px; + cursor: pointer; + transition: color 0.15s, border-color 0.15s, background 0.15s; +} + +.docs-pagination-btn:hover { + color: var(--text); + border-color: #444; + background: rgba(255, 255, 255, 0.05); +} + +.docs-pagination-btn--next { + margin-left: auto; +} + +/* ── Responsive ──────────────────────────────────────────── */ +@media (max-width: 768px) { + .docs-sidebar { + position: fixed; + top: var(--nav-h); + left: 0; + height: calc(100vh - var(--nav-h)); + z-index: 200; + transform: translateX(-100%); + transition: transform 0.25s ease; + box-shadow: 4px 0 20px rgba(0, 0, 0, 0.5); + } + + .docs-sidebar--open { + transform: translateX(0); + } + + .docs-sidebar-toggle { + display: flex; + align-items: center; + justify-content: center; + } + + .docs-nav-links { + display: none; + } + + .docs-main { + padding: 32px 20px; + } + + .docs-section h1 { + font-size: 1.6rem; + } +} diff --git a/frontend/src/pages/DocsPage.tsx b/frontend/src/pages/DocsPage.tsx new file mode 100644 index 0000000..1b93477 --- /dev/null +++ b/frontend/src/pages/DocsPage.tsx @@ -0,0 +1,562 @@ +import React, { useState } from 'react'; +import { Link } from 'react-router-dom'; +import { useAuthStore } from '../store/useAuthStore'; +import './DocsPage.css'; + +const GITHUB_URL = 'https://github.com/davidmonterocrespo24/velxio'; + +/* ── Icons ─────────────────────────────────────────────── */ +const IcoChip = () => ( + + + + + +); + +const IcoGitHub = () => ( + + + +); + +/* ── Doc sections ──────────────────────────────────────── */ +type SectionId = 'intro' | 'getting-started' | 'emulator' | 'components' | 'roadmap'; + +interface NavItem { + id: SectionId; + label: string; +} + +const NAV_ITEMS: NavItem[] = [ + { id: 'intro', label: 'Introduction' }, + { id: 'getting-started', label: 'Getting Started' }, + { id: 'emulator', label: 'Emulator Architecture' }, + { id: 'components', label: 'Components Reference' }, + { id: 'roadmap', label: 'Roadmap' }, +]; + +/* ── Section content ───────────────────────────────────── */ +const IntroSection: React.FC = () => ( +
+ // overview +

Introduction

+

+ Velxio is a fully local, open-source Arduino emulator that runs entirely in your browser. + Write Arduino C++ code, compile it with a real arduino-cli backend, and simulate it using + true AVR8 / RP2040 CPU emulation — with 48+ interactive electronic components, all without installing + any software on your machine. +

+ +

Why Velxio?

+
    +
  • No installation required — everything runs in the browser.
    • +
  • Real emulation — not a simplified model, but accurate AVR8 / RP2040 CPU emulation.
    • +
  • Interactive components — LEDs, buttons, potentiometers, displays, sensors, and more.
    • +
  • Open-source — inspect, modify, and self-host it yourself.
    • +
+ +

Supported Boards

+ + + + + + + + + + +
BoardCPUEmulator
Arduino UnoATmega328p @ 16 MHzavr8js
Arduino NanoATmega328p @ 16 MHzavr8js
Arduino MegaATmega2560 @ 16 MHzavr8js
Raspberry Pi PicoRP2040 @ 133 MHzrp2040js
+ +
+ Live Demo:{' '} + velxio.dev + {' '}— no installation needed, open the editor and start simulating immediately. +
+
+); + +const GettingStartedSection: React.FC = () => ( +
+ // setup +

Getting Started

+

Follow these steps to simulate your first Arduino sketch.

+ +

Option 1: Use the Hosted Version

+

+ No installation needed — go to{' '} + https://velxio.dev{' '} + and start coding immediately. +

+ +

Option 2: Self-Host with Docker

+

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

+ 
{`docker run -d \\
+  --name velxio \\
+  -p 3080:80 \\
+  -v $(pwd)/data:/app/data \\
+  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`}
+ +

2. Start the backend

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

3. Start the frontend

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

Open http://localhost:5173.

+ +

4. Set up arduino-cli (first time)

+ 
{`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`}
+ +

Your First Simulation

+
    +
  1. Open the editor at velxio.dev/editor.
    2. +
  2. Select a board from the toolbar (e.g., Arduino Uno).
    3. +
  3. Write Arduino code in the Monaco editor, for example:
    4. +
+ 
{`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 and returns a .hex file.
    2. +
  2. Click Run — the AVR8 emulator executes the compiled program.
    3. +
  3. Add components using the component picker (click the + button on the canvas).
    4. +
  4. Connect wires by clicking a component pin and then another pin.
    5. +
+ +

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + +
ProblemSolution
arduino-cli: command not foundInstall arduino-cli and add it to your PATH.
LED doesn't blinkCheck the browser console for port listener errors; verify pin assignment in the component property dialog.
Serial Monitor is emptyEnsure Serial.begin() is called inside setup() before any Serial.print().
Compilation errorsCheck the compilation console at the bottom of the editor for full arduino-cli output.
+
+); + +const EmulatorSection: React.FC = () => ( +
+ // internals +

Emulator Architecture

+

+ Velxio uses real CPU emulation rather than a simplified model. + This document describes how each layer of the simulation works. +

+ +

High-Level Data Flow

+ 
{`User Code (Monaco Editor)
+        │
+        ▼
+   Zustand Store (useEditorStore)
+        │
+        ▼
+  FastAPI Backend ──► arduino-cli ──► .hex / .uf2 file
+        │
+        ▼
+  AVRSimulator / RP2040Simulator
+        │ loadHex()
+        ▼
+  CPU execution loop (~60 FPS via requestAnimationFrame)
+        │
+        ▼
+  Port listeners (PORTB / PORTC / PORTD)
+        │
+        ▼
+  PinManager ──► Component state ──► React re-renders`}
+ +

AVR8 Emulation (Arduino Uno / Nano / Mega)

+

+ The AVR backend uses avr8js, + which implements a complete ATmega328p / ATmega2560 processor. +

+ +

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`}
+ +

Supported Peripherals

+ + + + + + + + + + + + +
PeripheralDetails
GPIOPORTB (pins 8–13), PORTC (A0–A5), PORTD (pins 0–7)
Timer0 / Timer1 / Timer2millis(), delay(), PWM via analogWrite()
USARTFull transmit and receive — powers the Serial Monitor
ADC10-bit, 5 V reference on pins A0–A5
SPIHardware SPI (enables ILI9341, SD card, etc.)
I2C (TWI)Hardware I2C with virtual device bus
+ +

Pin Mapping

+ + + + + + + + + +
Arduino PinAVR PortBit
0–7PORTD0–7
8–13PORTB0–5
A0–A5PORTC0–5
+ +

RP2040 Emulation (Raspberry Pi Pico)

+

+ The RP2040 backend uses rp2040js. +

+
    +
  • Real RP2040 emulation at 133 MHz
    • +
  • UART0 serial output displayed in the Serial Monitor
    • +
  • 12-bit ADC on GPIO 26–29 (A0–A3) with 3.3 V reference
    • +
+ +

HEX File Format

+

Arduino compilation produces Intel HEX format. The parser in hexParser.ts:

+
    +
  1. Reads lines starting with :
    2. +
  2. Extracts the address, record type, and data bytes
    3. +
  3. Returns a Uint8Array of program bytes
    4. +
  4. AVRSimulator converts this to a Uint16Array (16-bit words, little-endian)
    5. +
+ +

Key Source Files

+ + + + + + + + + + + + +
FilePurpose
frontend/src/simulation/AVRSimulator.tsAVR8 CPU emulator wrapper
frontend/src/simulation/PinManager.tsMaps Arduino pins to UI components
frontend/src/utils/hexParser.tsIntel HEX parser
frontend/src/components/simulator/SimulatorCanvas.tsxCanvas rendering
backend/app/services/arduino_cli.pyarduino-cli wrapper
backend/app/api/routes/compile.pyCompilation API endpoint
+
+); + +const ComponentsSection: React.FC = () => ( +
+ // reference +

Components Reference

+

+ 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. +

+ +

Adding Components

+
    +
  1. Click the + button on the simulation canvas.
    2. +
  2. Use search or browse by category in the component picker.
    3. +
  3. Click a component to place it on the canvas.
    4. +
  4. Drag to reposition; click to open the Property Dialog.
    5. +
+ +

Connecting Components

+
    +
  1. Click a pin on any component — a wire starts from that pin.
    2. +
  2. Click a destination pin to complete the connection.
    3. +
  3. Wires are color-coded by signal type:
    4. +
+ + + + + + + + + + + + + + +
ColorSignal Type
RedVCC (power)
BlackGND (ground)
BlueAnalog
GreenDigital
PurplePWM
GoldI2C (SDA/SCL)
OrangeSPI (MOSI/MISO/SCK)
CyanUSART (TX/RX)
+ +

Component Categories

+ +

Output

+ + + + + + + + + + + + +
ComponentDescription
LEDSingle LED with configurable color
RGB LEDThree-color LED (red, green, blue channels)
7-Segment DisplaySingle digit numeric display
LCD 16×22-line character LCD (I2C or parallel)
LCD 20×44-line character LCD
ILI9341 TFT240×320 color TFT display (SPI)
BuzzerPassive piezo buzzer
NeoPixelIndividually addressable RGB LED strip
+ +

Input

+ + + + + + + + + + +
ComponentDescription
Push ButtonMomentary push button
Slide SwitchSPDT slide switch
PotentiometerAnalog voltage divider (ADC input)
Rotary EncoderIncremental rotary encoder
Keypad 4×416-button matrix keypad
JoystickDual-axis analog joystick
+ +

Sensors

+ + + + + + + + + +
ComponentDescription
HC-SR04Ultrasonic distance sensor
DHT22Temperature and humidity sensor
PIR MotionPassive infrared motion sensor
PhotoresistorLight-dependent resistor (LDR)
IR Receiver38 kHz infrared receiver
+ +

Passive Components

+ + + + + + + +
ComponentDescription
ResistorStandard resistor (configurable value)
CapacitorElectrolytic capacitor
InductorCoil inductor
+ +

Component Properties

+

Each component has a Property Dialog accessible by clicking it on the canvas:

+ + + + + + + + + +
PropertyDescription
Arduino PinThe digital or analog pin this component is connected to
ColorVisual color (LEDs, wires)
ValueComponent value (e.g., resistance in Ω)
RotationRotate in 90° increments
DeleteRemove the component from the canvas
+
+); + +const RoadmapSection: React.FC = () => ( +
+ // future +

Roadmap

+

Features that are implemented, in progress, and planned for future releases of Velxio.

+ +

✅ Implemented

+
    +
  • Monaco Editor with C++ syntax highlighting, autocomplete, and minimap
    • +
  • Multi-file workspace — create, rename, delete, and switch between files
    • +
  • Arduino compilation via arduino-cli (multi-file sketch support)
    • +
  • Real ATmega328p / ATmega2560 emulation at 16 MHz via avr8js
    • +
  • Full GPIO, Timers, USART, ADC, SPI, I2C support
    • +
  • Real RP2040 emulation at 133 MHz via rp2040js
    • +
  • 48+ wokwi-elements components with component picker
    • +
  • Wire creation, orthogonal routing, and segment-based editing
    • +
  • Serial Monitor with auto baud-rate detection and send support
    • +
  • Library Manager (browse and install Arduino libraries)
    • +
  • Email/password and Google OAuth authentication
    • +
  • Project save, update, delete with permanent URLs
    • +
  • 8 built-in example projects
    • +
  • Single-container Docker image published to GHCR + Docker Hub
    • +
+ +

🔄 In Progress

+
    +
  • Functional wire connections — electrical signal routing and validation
    • +
  • Wire connection error handling — detect short circuits and invalid connections
    • +
+ +

🗓 Planned — Near-Term

+
    +
  • Undo / redo for code edits and canvas changes
    • +
  • Export / import projects as .zip files
    • +
  • More boards — ESP32, Arduino Leonardo
    • +
  • Breadboard — place components with automatic wire routing
    • +
+ +

🗓 Planned — Mid-Term

+
    +
  • TypeDoc API documentation — auto-generated from source code
    • +
  • GitHub Pages docs site — automatic deployment on push to main
    • +
  • More sensor simulations — HC-SR04, DHT22, IR receiver
    • +
  • EEPROM emulation — persistent read/write across simulation restarts
    • +
  • Oscilloscope component — plot analog pin voltages over time
    • +
+ +

🗓 Planned — Long-Term

+
    +
  • Multiplayer — share and co-edit simulations in real time
    • +
  • Embedded tutorial system — step-by-step guided projects inside the editor
    • +
  • Custom component SDK — define new components with a JSON/TypeScript API
    • +
  • Mobile / tablet support — responsive layout for touch devices
    • +
+ +
+ Want to contribute?{' '} + Feature requests, bug reports, and pull requests are welcome at{' '} + github.com/davidmonterocrespo24/velxio. +
+
+); + +const SECTION_MAP: Record = { + intro: IntroSection, + 'getting-started': GettingStartedSection, + emulator: EmulatorSection, + components: ComponentsSection, + roadmap: RoadmapSection, +}; + +/* ── Page ─────────────────────────────────────────────── */ +export const DocsPage: React.FC = () => { + const [activeSection, setActiveSection] = useState('intro'); + const [sidebarOpen, setSidebarOpen] = useState(false); + const user = useAuthStore((s) => s.user); + + const ActiveContent = SECTION_MAP[activeSection]; + + return ( +
+ {/* Nav */} + + +
+ {/* Sidebar */} + + + {/* Main content */} +
+ + + {/* Prev / Next navigation */} +
+ {NAV_ITEMS.findIndex((i) => i.id === activeSection) > 0 && ( + + )} + {NAV_ITEMS.findIndex((i) => i.id === activeSection) < NAV_ITEMS.length - 1 && ( + + )} +
+
+
+
+ ); +}; diff --git a/scripts/generate-example-screenshots.md b/scripts/generate-example-screenshots.md index d99e06d..78f39a3 100644 --- a/scripts/generate-example-screenshots.md +++ b/scripts/generate-example-screenshots.md @@ -30,7 +30,7 @@ Abre http://localhost:5173 **Guardar la imagen:** 1. Abre Paint o cualquier editor 2. Pega (Ctrl + V) -3. Guarda como PNG en `doc/examples/[nombre-ejemplo].png` +3. Guarda como PNG en `docs/examples/[nombre-ejemplo].png` ### 4. Nombres de Archivo @@ -55,7 +55,7 @@ Una vez tengas las imágenes, edita `frontend/src/data/examples.ts`: description: 'Classic Arduino blink example - toggle an LED on and off', category: 'basics', difficulty: 'beginner', - thumbnail: '/doc/examples/blink-led.png', // ← Agregar esta línea + thumbnail: '/docs/examples/blink-led.png', // ← Agregar esta línea code: `...`, // ... resto }