docs: update README with velxio.dev live URL, Docker run command, and full self-hosting guide
- Add live demo badge and link to velxio.dev at the top - Add Docker single-container run command with volume mount - Add env vars reference table - Simplify and modernize overall structure - Update package.json name and homepage to velxio.dev Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>pull/10/head
David Montero Crespo
parent
ea61bd5475
commit
746e735487
440
README.md
440
README.md
|
|
@ -1,16 +1,32 @@
|
||||||
# Velxio - Arduino Emulator
|
# Velxio — Arduino Emulator
|
||||||
|
|
||||||
A fully local, open-source Arduino emulator inspired by [Wokwi](https://wokwi.com). Write Arduino code, compile it, and simulate it with real AVR8 CPU emulation and 48+ interactive electronic components — all running in your browser.
|
**Live at [velxio.dev](https://velxio.dev)**
|
||||||
|
|
||||||
## Support This Project
|
A fully local, open-source Arduino emulator. Write Arduino code, compile it, and simulate it with real AVR8 CPU emulation and 48+ interactive electronic components — all running in your browser.
|
||||||
|
|
||||||
If you find this project helpful, please consider giving it a star! Your support helps the project grow and motivates continued development.
|
[](https://velxio.dev)
|
||||||
|
[](https://github.com/davidmonterocrespo24/velxio/pkgs/container/velxio)
|
||||||
|
[](https://github.com/davidmonterocrespo24/velxio/stargazers)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
[](https://github.com/davidmonterocrespo24/velxio/stargazers)
|
[](https://github.com/sponsors/davidmonterocrespo24)
|
||||||
[](https://github.com/sponsors/davidmonterocrespo24)
|
[](https://paypal.me/odoonext)
|
||||||
[](https://paypal.me/odoonext)
|
|
||||||
|
|
||||||
Every star counts and helps make this project better! You can also support the project financially through GitHub Sponsors or PayPal -- any contribution helps keep the development going.
|
---
|
||||||
|
|
||||||
|
## Try it now
|
||||||
|
|
||||||
|
**[https://velxio.dev](https://velxio.dev)** — no installation needed. Open the editor, write your sketch, and simulate directly in the browser.
|
||||||
|
|
||||||
|
To self-host with Docker (single command):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -d -p 3080:80 ghcr.io/davidmonterocrespo24/velxio:master
|
||||||
|
```
|
||||||
|
|
||||||
|
Then open **http://localhost:3080**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Screenshots
|
## Screenshots
|
||||||
|
|
||||||
|
|
@ -28,400 +44,218 @@ Library Manager loads the full Arduino library index on open — browse and inst
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Component Picker showing 48 available components with visual previews, search, and category filters (Boards, Displays, Input, Motors, Output, Passive, Sensors).
|
Component Picker showing 48 available components with visual previews, search, and category filters.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
### Code Editing
|
### Code Editing
|
||||||
- **Monaco Editor** — Full C++ editor with syntax highlighting, autocomplete, minimap, and dark theme
|
- **Monaco Editor** — Full C++ editor with syntax highlighting, autocomplete, minimap, and dark theme
|
||||||
|
- **Multi-file workspace** — create, rename, delete, and switch between multiple `.ino` / `.h` / `.cpp` files
|
||||||
- **Arduino compilation** via `arduino-cli` backend — compile sketches to `.hex` / `.uf2` files
|
- **Arduino compilation** via `arduino-cli` backend — compile sketches to `.hex` / `.uf2` files
|
||||||
- **Compile / Run / Stop / Reset** toolbar buttons with status messages
|
- **Compile / Run / Stop / Reset** toolbar buttons with status messages
|
||||||
- **Compilation console** — resizable output panel at the bottom of the editor showing full compiler output, warnings, and errors
|
- **Compilation console** — resizable output panel showing full compiler output, warnings, and errors
|
||||||
|
|
||||||
### Multi-Board Support
|
### Multi-Board Support
|
||||||
- **Arduino Uno** (ATmega328p) — full AVR8 emulation via avr8js
|
- **Arduino Uno** (ATmega328p) — full AVR8 emulation via avr8js
|
||||||
|
- **Arduino Nano** (ATmega328p) — full AVR8 emulation
|
||||||
|
- **Arduino Mega** (ATmega2560) — full AVR8 emulation
|
||||||
- **Raspberry Pi Pico** (RP2040) — full RP2040 emulation via rp2040js, compiled with arduino-pico core
|
- **Raspberry Pi Pico** (RP2040) — full RP2040 emulation via rp2040js, compiled with arduino-pico core
|
||||||
- Board selector in the toolbar — switch boards without restarting
|
- Board selector in the toolbar — switch boards without restarting
|
||||||
|
|
||||||
### AVR8 Simulation (Arduino Uno)
|
### AVR8 Simulation (Arduino Uno / Nano / Mega)
|
||||||
- **Real ATmega328p emulation** at 16 MHz using avr8js
|
- **Real ATmega328p emulation** at 16 MHz using avr8js
|
||||||
- **Intel HEX parser** with checksum verification
|
|
||||||
- **Full GPIO support** — PORTB (pins 8-13), PORTC (A0-A5), PORTD (pins 0-7)
|
- **Full GPIO support** — PORTB (pins 8-13), PORTC (A0-A5), PORTD (pins 0-7)
|
||||||
- **Timer0/Timer1/Timer2** peripheral support (enables `millis()`, `delay()`, PWM via `analogWrite()`)
|
- **Timer0/Timer1/Timer2** peripheral support (`millis()`, `delay()`, PWM via `analogWrite()`)
|
||||||
- **USART (Serial)** — full transmit and receive support
|
- **USART (Serial)** — full transmit and receive support
|
||||||
- **ADC** — `analogRead()` on pins A0-A5, voltage injection from UI components
|
- **ADC** — `analogRead()` on pins A0-A5, voltage injection from UI components
|
||||||
- **SPI** — hardware SPI peripheral (enables ILI9341, SD card, etc.)
|
- **SPI** — hardware SPI peripheral (enables ILI9341, SD card, etc.)
|
||||||
- **I2C (TWI)** — hardware I2C with virtual device bus (DS1307, temp sensor, EEPROM)
|
- **I2C (TWI)** — hardware I2C with virtual device bus
|
||||||
- **~60 FPS simulation loop** with `requestAnimationFrame` (~267k cycles/frame)
|
- **~60 FPS simulation loop** with `requestAnimationFrame`
|
||||||
- **Speed control** — adjustable from 0.1x to 10x
|
|
||||||
- **PWM monitoring** — reads OCR registers each frame to drive PWM-capable components
|
|
||||||
|
|
||||||
### RP2040 Simulation (Raspberry Pi Pico)
|
### RP2040 Simulation (Raspberry Pi Pico)
|
||||||
- **Real RP2040 emulation** via rp2040js at 133 MHz
|
- **Real RP2040 emulation** via rp2040js at 133 MHz
|
||||||
- **UART0** serial output captured and displayed in Serial Monitor
|
- **UART0** serial output displayed in Serial Monitor
|
||||||
- **ADC** — 12-bit, 3.3V reference on GPIO 26-29 (A0-A3)
|
- **ADC** — 12-bit, 3.3V reference on GPIO 26-29 (A0-A3)
|
||||||
- **I2C** bus with virtual device support
|
|
||||||
- Automatic `#define Serial Serial1` injection at compile time to route serial output to emulated UART
|
|
||||||
|
|
||||||
### Serial Monitor
|
### Serial Monitor
|
||||||
- **Live serial output** — displays characters as the sketch sends them via `Serial.print()`
|
- **Live serial output** — characters as the sketch sends them via `Serial.print()`
|
||||||
- **Baud rate indicator** — automatically detects the speed set by `Serial.begin()` reading hardware registers in real time — no manual configuration needed
|
- **Auto baud-rate detection** — reads hardware registers, no manual configuration needed
|
||||||
- **Send data** to the Arduino RX pin from the UI
|
- **Send data** to the Arduino RX pin from the UI
|
||||||
- **Line ending selector** — None, Newline, Carriage Return, or Both
|
|
||||||
- **Autoscroll** with toggle
|
- **Autoscroll** with toggle
|
||||||
- **Resizable panel** — drag the handle to adjust height
|
|
||||||
|
|
||||||
### ILI9341 TFT Display Simulation
|
|
||||||
- **Full SPI command decoding** — CASET, PASET, RAMWR, SWRESET, DISPON, MADCTL, and more
|
|
||||||
- **RGB-565 pixel rendering** directly to an HTML Canvas element in real time
|
|
||||||
- **240×320 resolution** with full framebuffer support
|
|
||||||
- Compatible with Adafruit_GFX + Adafruit_ILI9341 libraries
|
|
||||||
|
|
||||||
### Component System (48+ Components)
|
### Component System (48+ Components)
|
||||||
- **48 electronic components** auto-discovered from wokwi-elements source code
|
- **48 electronic components** from wokwi-elements
|
||||||
- **Component picker modal** with search bar, category filtering (Boards, Displays, Input, Motors, Output, Passive, Sensors), and live wokwi-element previews as thumbnails
|
- **Component picker** with search, category filters, and live previews
|
||||||
- **Dynamic component rendering** from build-time metadata (TypeScript AST parser extracts `@customElement` tags, `@property` decorators, and pin counts)
|
- **Drag-and-drop** repositioning on the simulation canvas
|
||||||
- **Drag-and-drop repositioning** on the simulation canvas
|
|
||||||
- **Component rotation** in 90° increments
|
- **Component rotation** in 90° increments
|
||||||
- **Property dialog** (single-click) — shows pin roles, Arduino pin assignment, rotate & delete actions
|
- **Property dialog** — pin roles, Arduino pin assignment, rotate & delete
|
||||||
- **Pin selector** (double-click) — assign Arduino pins D0-D13 and A0-A5 to component pins
|
|
||||||
- **Pin overlay system** — clickable cyan dots on each component pin with hover animation
|
|
||||||
- **Keyboard shortcuts** — Delete/Backspace to remove, Escape to cancel
|
|
||||||
|
|
||||||
### Part Simulation Behaviors
|
|
||||||
- **LED** — pin state drives LED on/off
|
|
||||||
- **RGB LED** — digital HIGH/LOW and PWM (`analogWrite`) mapped to R/G/B channels
|
|
||||||
- **Pushbutton / 6mm pushbutton** — press/release events inject active-LOW pin state
|
|
||||||
- **Slide switch** — toggle between HIGH and LOW
|
|
||||||
- **DIP Switch 8** — 8 independent toggles, each driving its own pin
|
|
||||||
- **Potentiometer** — reads slider value (0-1023), converts to voltage (5V for AVR, 3.3V for RP2040), injects into ADC
|
|
||||||
- **Slide potentiometer** — same as rotary, with configurable min/max range
|
|
||||||
- **Analog joystick** — two ADC axes (VRX/VRY) + button press
|
|
||||||
- **Photoresistor sensor** — injects mid-range voltage on AO pin; reacts to element input events
|
|
||||||
- **Servo** — reads Timer1 OCR1A/ICR1 registers to calculate pulse width and maps to 0-180° angle
|
|
||||||
- **Buzzer** — Web Audio API tone generation, frequency derived from Timer2 OCR2A/TCCR2B registers
|
|
||||||
- **LED Bar Graph** — 10 individual LEDs driven by pins A1-A10
|
|
||||||
- **7-Segment Display** — segments A-G + DP driven by individual pins
|
|
||||||
- **LCD 1602 & LCD 2004** — full HD44780 controller emulation in 4-bit mode (RS, E, D4-D7 pins)
|
|
||||||
- **ILI9341 TFT** — full SPI display simulation (see above)
|
|
||||||
|
|
||||||
### Wire System
|
### Wire System
|
||||||
- **Wire creation** — click a pin to start, click another pin to connect
|
- **Wire creation** — click a pin to start, click another pin to connect
|
||||||
- **Real-time preview** — dashed green wire with L-shaped orthogonal routing while creating
|
- **Orthogonal routing** — no diagonal paths
|
||||||
- **Orthogonal wire rendering** — no diagonal paths
|
|
||||||
- **Segment-based wire editing** — hover to highlight, drag segments perpendicular to their orientation
|
|
||||||
- **8 signal-type wire colors**: Red (VCC), Black (GND), Blue (Analog), Green (Digital), Purple (PWM), Gold (I2C), Orange (SPI), Cyan (USART)
|
- **8 signal-type wire colors**: Red (VCC), Black (GND), Blue (Analog), Green (Digital), Purple (PWM), Gold (I2C), Orange (SPI), Cyan (USART)
|
||||||
- **Automatic overlap offset** — parallel wires are offset symmetrically (6px spacing)
|
- **Segment-based wire editing** — drag segments perpendicular to their orientation
|
||||||
- **Auto-update positions** — wire endpoints recalculate when components move
|
|
||||||
- **Grid snapping** (20px grid)
|
|
||||||
|
|
||||||
### Library Manager
|
### Library Manager
|
||||||
- **Loads full library index on open** — no need to type first; shows spinner while fetching
|
- Browse and install the full Arduino library index directly from the UI
|
||||||
- **Live search with debounce** — filter while typing (400ms delay)
|
- Live search, installed tab, version display
|
||||||
- **Install libraries** directly from the UI via arduino-cli
|
|
||||||
- **Installed tab** — see all installed libraries with versions
|
### Auth & Project Persistence
|
||||||
- **Cross-reference** — installed libraries show "INSTALLED" badge in search results
|
- **Email/password** and **Google OAuth** sign-in
|
||||||
|
- **Project save** with name, description, and public/private visibility
|
||||||
|
- **Project URL** — each project gets a permanent URL at `/project/:id`
|
||||||
|
- **Sketch files stored on disk** per project (accessible from the host via Docker volume)
|
||||||
|
- **User profile** at `/:username` showing public projects
|
||||||
|
|
||||||
### Example Projects
|
### Example Projects
|
||||||
- **8 built-in example projects** with full code, components, and wire definitions:
|
- 8 built-in examples (Blink, Traffic Light, Button Control, Fade LED, Serial Hello World, RGB LED, Simon Says, LCD 20×4)
|
||||||
|
- One-click loading into the editor
|
||||||
|
|
||||||
| Example | Category | Difficulty |
|
---
|
||||||
|---------|----------|------------|
|
|
||||||
| Blink LED | Basics | Beginner |
|
|
||||||
| Traffic Light | Basics | Beginner |
|
|
||||||
| Button Control | Basics | Beginner |
|
|
||||||
| Fade LED (PWM) | Basics | Beginner |
|
|
||||||
| Serial Hello World | Communication | Beginner |
|
|
||||||
| RGB LED Colors | Basics | Intermediate |
|
|
||||||
| Simon Says Game | Games | Advanced |
|
|
||||||
| LCD 20x4 Display | Displays | Intermediate |
|
|
||||||
|
|
||||||
- **Examples gallery** with category and difficulty filters
|
## Self-Hosting
|
||||||
- **One-click loading** — loads code, components, and wires into the editor and simulator
|
|
||||||
|
|
||||||
### UI / Layout
|
### Option A: Docker (single container, recommended)
|
||||||
- **Resizable panels** — drag the vertical divider between editor and simulator
|
|
||||||
- **Resizable bottom panels** — Serial Monitor and compilation console share the same draggable handle; both start at the same height (200px)
|
|
||||||
- **Compilation console at the bottom** — output appears below the code editor, not between the toolbar and the code
|
|
||||||
- **Serial Monitor** opens automatically when simulation starts
|
|
||||||
|
|
||||||
### Wokwi Libraries (Local Clones)
|
|
||||||
- **wokwi-elements** — 48+ electronic web components (Lit-based Web Components)
|
|
||||||
- **avr8js** — AVR8 CPU emulator
|
|
||||||
- **rp2040js** — RP2040 emulator
|
|
||||||
- **Build-time metadata generation** — TypeScript AST parser reads wokwi-elements source to generate component metadata automatically
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
### 1. Node.js
|
|
||||||
- Version 18 or higher
|
|
||||||
- Download from: https://nodejs.org/
|
|
||||||
|
|
||||||
### 2. Python
|
|
||||||
- Version 3.12 or higher
|
|
||||||
- Download from: https://www.python.org/
|
|
||||||
|
|
||||||
### 3. Arduino CLI
|
|
||||||
Install arduino-cli on your system:
|
|
||||||
|
|
||||||
**Windows (with Chocolatey):**
|
|
||||||
```bash
|
```bash
|
||||||
choco install arduino-cli
|
# Pull and run
|
||||||
|
docker run -d \
|
||||||
|
--name velxio \
|
||||||
|
-p 3080:80 \
|
||||||
|
-v $(pwd)/data:/app/data \
|
||||||
|
ghcr.io/davidmonterocrespo24/velxio:master
|
||||||
```
|
```
|
||||||
|
|
||||||
**Windows (manual):**
|
Open **http://localhost:3080**.
|
||||||
1. Download from: https://github.com/arduino/arduino-cli/releases
|
|
||||||
2. Add to system PATH
|
|
||||||
|
|
||||||
**Verify installation:**
|
The `/app/data` volume contains:
|
||||||
```bash
|
- `velxio.db` — SQLite database (users, projects metadata)
|
||||||
arduino-cli version
|
- `projects/{id}/` — sketch files per project
|
||||||
```
|
|
||||||
|
|
||||||
**Initialize arduino-cli:**
|
### Option B: Docker Compose
|
||||||
```bash
|
|
||||||
arduino-cli core update-index
|
|
||||||
arduino-cli core install arduino:avr
|
|
||||||
```
|
|
||||||
|
|
||||||
**For Raspberry Pi Pico support:**
|
|
||||||
```bash
|
|
||||||
arduino-cli core install rp2040:rp2040
|
|
||||||
```
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### Option A: Docker (Recommended)
|
|
||||||
|
|
||||||
The fastest way to get started. Requires only [Docker](https://docs.docker.com/get-docker/) and Docker Compose.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/davidmonterocrespo24/velxio.git
|
git clone https://github.com/davidmonterocrespo24/velxio.git
|
||||||
cd velxio
|
cd velxio
|
||||||
docker compose up --build
|
cp backend/.env.example backend/.env # edit as needed
|
||||||
|
docker compose -f docker-compose.prod.yml up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
Once running:
|
#### Environment variables (`backend/.env`)
|
||||||
- **App**: http://localhost:3000
|
|
||||||
- **API**: http://localhost:8001
|
|
||||||
- **API Docs**: http://localhost:8001/docs
|
|
||||||
|
|
||||||
The Docker setup automatically installs `arduino-cli`, the AVR core, builds the wokwi-libs, and serves everything -- no other prerequisites needed.
|
| Variable | Default | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| `SECRET_KEY` | *(required)* | JWT signing secret |
|
||||||
|
| `DATABASE_URL` | `sqlite+aiosqlite:////app/data/velxio.db` | SQLite path |
|
||||||
|
| `DATA_DIR` | `/app/data` | Directory for project files |
|
||||||
|
| `FRONTEND_URL` | `http://localhost:5173` | Used for OAuth redirect |
|
||||||
|
| `GOOGLE_CLIENT_ID` | — | Google OAuth client ID |
|
||||||
|
| `GOOGLE_CLIENT_SECRET` | — | Google OAuth client secret |
|
||||||
|
| `GOOGLE_REDIRECT_URI` | `http://localhost:8001/api/auth/google/callback` | Must match Google Console |
|
||||||
|
| `COOKIE_SECURE` | `false` | Set `true` when serving over HTTPS |
|
||||||
|
|
||||||
To stop:
|
### Option C: Manual Setup
|
||||||
```bash
|
|
||||||
docker compose down
|
|
||||||
```
|
|
||||||
|
|
||||||
### Option B: Manual Setup
|
**Prerequisites:** Node.js 18+, Python 3.12+, arduino-cli
|
||||||
|
|
||||||
#### 1. Clone the repository
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/davidmonterocrespo24/velxio.git
|
git clone https://github.com/davidmonterocrespo24/velxio.git
|
||||||
cd velxio
|
cd velxio
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. Setup Backend
|
# Backend
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
cd backend
|
||||||
|
python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate
|
||||||
# Create virtual environment
|
|
||||||
python -m venv venv
|
|
||||||
|
|
||||||
# Activate virtual environment (Windows)
|
|
||||||
venv\Scripts\activate
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
|
||||||
|
|
||||||
#### 3. Setup Frontend
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running
|
|
||||||
|
|
||||||
### Start Backend
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
venv\Scripts\activate
|
|
||||||
uvicorn app.main:app --reload --port 8001
|
uvicorn app.main:app --reload --port 8001
|
||||||
```
|
|
||||||
|
|
||||||
The backend will be available at:
|
# Frontend (new terminal)
|
||||||
- API: http://localhost:8001
|
|
||||||
- Documentation: http://localhost:8001/docs
|
|
||||||
|
|
||||||
### Start Frontend
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
cd frontend
|
||||||
|
npm install
|
||||||
npm run dev
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
The frontend will be available at:
|
Open **http://localhost:5173**.
|
||||||
- App: http://localhost:5173
|
|
||||||
|
|
||||||
## Usage
|
**arduino-cli setup (first time):**
|
||||||
|
```bash
|
||||||
|
arduino-cli core update-index
|
||||||
|
arduino-cli core install arduino:avr
|
||||||
|
# For Raspberry Pi Pico:
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
1. Open http://localhost:5173 in your browser
|
---
|
||||||
2. Select a board (Arduino Uno or Raspberry Pi Pico) from the toolbar
|
|
||||||
3. Write Arduino code in the editor (a Blink example is loaded by default)
|
|
||||||
4. Click **Compile** to compile the code via the backend
|
|
||||||
5. Click **Run** to start simulation — the Serial Monitor opens automatically
|
|
||||||
6. Watch LEDs, LCDs, TFT displays, and other components react in real time
|
|
||||||
7. Click components to view properties or assign pin mappings
|
|
||||||
8. Click pins to create wires connecting components
|
|
||||||
9. Use the **Library Manager** to install Arduino libraries
|
|
||||||
10. Browse **Examples** to load pre-built projects
|
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
velxio/
|
velxio/
|
||||||
├── frontend/ # React + Vite + TypeScript
|
├── frontend/ # React + Vite + TypeScript
|
||||||
│ ├── src/
|
│ └── src/
|
||||||
│ │ ├── components/
|
│ ├── pages/ # LandingPage, EditorPage, ProjectByIdPage, ...
|
||||||
│ │ │ ├── ComponentPickerModal.tsx # Component search & picker
|
│ ├── components/ # Editor, simulator canvas, modals, layout
|
||||||
│ │ │ ├── DynamicComponent.tsx # Generic wokwi component renderer
|
│ ├── simulation/ # AVRSimulator, RP2040Simulator, PinManager
|
||||||
│ │ │ ├── editor/ # Monaco Editor + toolbar + compilation console
|
│ ├── store/ # Zustand stores (auth, editor, simulator, project)
|
||||||
│ │ │ └── simulator/ # Canvas, wires, pins, Serial Monitor, dialogs
|
│ └── services/ # API clients
|
||||||
│ │ ├── simulation/
|
|
||||||
│ │ │ ├── AVRSimulator.ts # AVR8 CPU emulator wrapper
|
|
||||||
│ │ │ ├── RP2040Simulator.ts # RP2040 emulator wrapper
|
|
||||||
│ │ │ ├── PinManager.ts # Pin-to-component mapping + PWM
|
|
||||||
│ │ │ └── parts/ # Part behaviors (LED, LCD, ILI9341, servo, buzzer...)
|
|
||||||
│ │ ├── store/ # Zustand state management
|
|
||||||
│ │ ├── services/ # API clients & ComponentRegistry
|
|
||||||
│ │ ├── types/ # TypeScript types (wires, components, metadata)
|
|
||||||
│ │ ├── utils/ # Hex parser, wire routing, pin calc
|
|
||||||
│ │ └── pages/ # EditorPage, ExamplesPage
|
|
||||||
│ └── public/
|
|
||||||
│ └── components-metadata.json # Auto-generated component metadata
|
|
||||||
│
|
|
||||||
├── backend/ # FastAPI + Python
|
├── backend/ # FastAPI + Python
|
||||||
│ └── app/
|
│ └── app/
|
||||||
│ ├── main.py # Entry point, CORS config
|
│ ├── api/routes/ # compile, auth, projects, libraries
|
||||||
│ ├── api/routes/compile.py # POST /api/compile
|
│ ├── models/ # User, Project (SQLAlchemy)
|
||||||
│ ├── api/routes/libraries.py # Library search, install, list
|
│ ├── services/ # arduino_cli, project_files
|
||||||
│ └── services/arduino_cli.py # arduino-cli subprocess wrapper
|
│ └── core/ # config, security, dependencies
|
||||||
│
|
├── wokwi-libs/ # Local clones of Wokwi repos
|
||||||
├── wokwi-libs/ # Cloned Wokwi repositories
|
│ ├── wokwi-elements/
|
||||||
│ ├── wokwi-elements/ # 48+ Web Components (Lit)
|
│ ├── avr8js/
|
||||||
│ ├── avr8js/ # AVR8 CPU Emulator
|
│ └── rp2040js/
|
||||||
│ └── rp2040js/ # RP2040 Emulator
|
├── deploy/ # nginx.conf, entrypoint.sh
|
||||||
│
|
├── Dockerfile.standalone # Single-container production image
|
||||||
├── scripts/
|
├── docker-compose.yml # Development compose
|
||||||
│ └── generate-component-metadata.ts # AST parser for component discovery
|
└── docker-compose.prod.yml # Production compose
|
||||||
│
|
|
||||||
├── doc/
|
|
||||||
│ ├── ARCHITECTURE.md # Detailed architecture documentation
|
|
||||||
│ ├── WOKWI_LIBS.md # Wokwi integration documentation
|
|
||||||
│ ├── img1.png # Screenshot: RP2040 + Serial Monitor
|
|
||||||
│ ├── img2.png # Screenshot: ILI9341 TFT simulation
|
|
||||||
│ ├── img3.png # Screenshot: Library Manager
|
|
||||||
│ └── img4.png # Screenshot: Component Picker
|
|
||||||
│
|
|
||||||
├── CLAUDE.md # AI assistant guidance
|
|
||||||
└── update-wokwi-libs.bat # Update local Wokwi libraries
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Technologies Used
|
---
|
||||||
|
|
||||||
### Frontend
|
## Technologies
|
||||||
- **React** 19 — UI framework
|
|
||||||
- **Vite** 7 — Build tool with local library aliases
|
|
||||||
- **TypeScript** 5.9 — Static typing
|
|
||||||
- **Monaco Editor** — Code editor (VS Code engine)
|
|
||||||
- **Zustand** 5 — State management
|
|
||||||
- **React Router** 7 — Client-side routing
|
|
||||||
|
|
||||||
### Backend
|
| Layer | Stack |
|
||||||
- **FastAPI** — Python web framework
|
|---|---|
|
||||||
- **uvicorn** — ASGI server
|
| Frontend | React 19, Vite 7, TypeScript 5.9, Monaco Editor, Zustand, React Router 7 |
|
||||||
- **arduino-cli** — Arduino compiler (subprocess)
|
| Backend | FastAPI, SQLAlchemy 2.0 async, aiosqlite, uvicorn |
|
||||||
|
| Simulation | avr8js (AVR8), rp2040js (RP2040), wokwi-elements (Web Components) |
|
||||||
|
| Compiler | arduino-cli (subprocess) |
|
||||||
|
| Auth | JWT (httpOnly cookie), Google OAuth 2.0 |
|
||||||
|
| Persistence | SQLite + disk volume (`/app/data/projects/{id}/`) |
|
||||||
|
| Deploy | Docker, nginx, GitHub Actions → GHCR + Docker Hub |
|
||||||
|
|
||||||
### Simulation & Components
|
---
|
||||||
- **avr8js** — Real AVR8 ATmega328p emulator (local clone)
|
|
||||||
- **rp2040js** — RP2040 emulator (local clone)
|
|
||||||
- **wokwi-elements** — 48+ electronic web components built with Lit (local clone)
|
|
||||||
|
|
||||||
## Planned Features
|
|
||||||
|
|
||||||
- **Project Persistence** — Save/load projects with SQLite
|
|
||||||
- **Undo/Redo** — Edit history for code and circuit changes
|
|
||||||
- **Wire Validation** — Electrical validation and error highlighting
|
|
||||||
- **Export/Import** — Share projects as files
|
|
||||||
- **More boards** — ESP32, Arduino Mega, Arduino Nano
|
|
||||||
|
|
||||||
## Update Wokwi Libraries
|
|
||||||
|
|
||||||
This project uses official Wokwi repositories cloned locally. To get the latest updates:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run update script
|
|
||||||
update-wokwi-libs.bat
|
|
||||||
```
|
|
||||||
|
|
||||||
Or manually:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd wokwi-libs/wokwi-elements
|
|
||||||
git pull origin main
|
|
||||||
npm install
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
See [WOKWI_LIBS.md](doc/WOKWI_LIBS.md) for more details about Wokwi integration.
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
### Error: "arduino-cli: command not found"
|
**`arduino-cli: command not found`** — install arduino-cli and add to PATH.
|
||||||
- Make sure arduino-cli is installed and in PATH
|
|
||||||
- Verify with: `arduino-cli version`
|
|
||||||
|
|
||||||
### Error: "arduino:avr core not found"
|
**LED doesn't blink** — check port listeners in browser console; verify pin mapping in the component property dialog.
|
||||||
- Run: `arduino-cli core install arduino:avr`
|
|
||||||
|
|
||||||
### Frontend doesn't connect to backend
|
**Serial Monitor shows nothing** — ensure `Serial.begin()` is called before `Serial.print()`.
|
||||||
- Verify backend is running at http://localhost:8001
|
|
||||||
- Check CORS logs in browser console
|
|
||||||
|
|
||||||
### Compilation errors
|
**Compilation errors** — check the compilation console; verify the correct core is installed.
|
||||||
- Check the compilation console output at the bottom of the editor
|
|
||||||
- Make sure Arduino code is valid
|
|
||||||
- Verify you have the correct core installed (`arduino:avr` for Uno, `rp2040:rp2040` for Pico)
|
|
||||||
|
|
||||||
### LED doesn't blink
|
---
|
||||||
- Check port listeners are firing (browser console logs)
|
|
||||||
- Verify pin mapping in the component property dialog
|
|
||||||
|
|
||||||
### CPU stuck at PC=0
|
|
||||||
- Ensure `avrInstruction()` is being called in the execution loop
|
|
||||||
- Check hex file was loaded correctly
|
|
||||||
|
|
||||||
### Serial Monitor shows nothing
|
|
||||||
- Make sure your sketch calls `Serial.begin()` before `Serial.print()`
|
|
||||||
- Check the baud rate indicator appears in the Serial Monitor header after the simulation starts
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
This is an open-source project. Suggestions, bug reports, and pull requests are welcome!
|
Suggestions, bug reports, and pull requests are welcome at [github.com/davidmonterocrespo24/velxio](https://github.com/davidmonterocrespo24/velxio).
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
MIT — see [LICENSE](LICENSE).
|
||||||
|
|
||||||
## References
|
## References
|
||||||
|
|
||||||
- [Wokwi](https://wokwi.com) — Project inspiration
|
- [Wokwi](https://wokwi.com) — Inspiration
|
||||||
- [avr8js](https://github.com/wokwi/avr8js) — AVR8 emulator
|
- [avr8js](https://github.com/wokwi/avr8js) — AVR8 emulator
|
||||||
- [wokwi-elements](https://github.com/wokwi/wokwi-elements) — Electronic web components
|
- [wokwi-elements](https://github.com/wokwi/wokwi-elements) — Electronic web components
|
||||||
- [rp2040js](https://github.com/wokwi/rp2040js) — RP2040 emulator
|
- [rp2040js](https://github.com/wokwi/rp2040js) — RP2040 emulator
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,8 @@
|
||||||
{
|
{
|
||||||
"name": "frontend",
|
"name": "velxio",
|
||||||
|
"homepage": "https://velxio.dev",
|
||||||
"private": true,
|
"private": true,
|
||||||
"version": "0.0.0",
|
"version": "1.0.0",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"generate:metadata": "cd .. && npx tsx scripts/generate-component-metadata.ts",
|
"generate:metadata": "cd .. && npx tsx scripts/generate-component-metadata.ts",
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue