368 lines
13 KiB
Markdown
368 lines
13 KiB
Markdown
# OpenWokwi - 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.
|
|
|
|
## Support This Project
|
|
|
|
If you find this project helpful, please consider giving it a star! Your support helps the project grow and motivates continued development.
|
|
|
|
[](https://github.com/davidmonterocrespo24/openwokwi/stargazers)
|
|
[](https://github.com/sponsors/davidmonterocrespo24)
|
|
[](https://paypal.me/dmonterocrepoclub)
|
|
|
|
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.
|
|
|
|
## Screenshots
|
|
|
|
|
|
|
|
Arduino emulator with Monaco code editor and visual simulator with wokwi-elements
|
|
|
|
|
|
|
|
Interactive component properties dialog and segment-based wire editing
|
|
|
|
## Features
|
|
|
|
### Code Editing
|
|
- **Monaco Editor** — Full C++ editor with syntax highlighting, autocomplete, minimap, and dark theme
|
|
- **Arduino compilation** via `arduino-cli` backend — compile sketches to `.hex` files
|
|
- **Compile / Run / Stop / Reset** toolbar buttons with status messages
|
|
|
|
### AVR8 Simulation (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)
|
|
- **Timer0 peripheral** support
|
|
- **USART (Serial)** support
|
|
- **~60 FPS simulation loop** with `requestAnimationFrame` (~267k cycles/frame)
|
|
- **Speed control** — adjustable from 0.1x to 10x
|
|
- **Single-step debugging** API
|
|
- **External pin state injection** for input components (buttons, potentiometers)
|
|
|
|
### Component System (48+ Components)
|
|
- **48 electronic components** auto-discovered from wokwi-elements source code
|
|
- **Component picker modal** with search bar, category filtering, and live wokwi-element previews as thumbnails
|
|
- **9 component categories**: Boards (4), Sensors (6), Displays (3), Input (5), Output (5), Motors (2), Passive (4), Other (19)
|
|
- **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
|
|
- **Component rotation** in 90° increments
|
|
- **Property dialog** (single-click) — shows pin roles, Arduino pin assignment, rotate & delete actions
|
|
- **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 mapped to individual R/G/B channels
|
|
- **Pushbutton** — press/release events inject active-LOW pin state into simulation
|
|
- **Potentiometer** — reads element value (0-1023), converts to voltage, injects into ADC channel
|
|
- **LCD 1602 & LCD 2004** — Full HD44780 controller emulation:
|
|
- 4-bit mode protocol (high nibble first, then low nibble)
|
|
- DDRAM with proper line address mapping
|
|
- Commands: Clear Display, Return Home, Entry Mode Set, Display On/Off, Cursor/Display Shift, Function Set
|
|
- Initialization sequence handling
|
|
- Enable pin falling-edge detection for data latching
|
|
|
|
### Wire System
|
|
- **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 wire rendering** — no diagonal paths
|
|
- **Segment-based wire editing** — hover to highlight, drag segments perpendicular to their orientation
|
|
- **Smooth dragging** with `requestAnimationFrame`
|
|
- **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)
|
|
- **Auto-update positions** — wire endpoints recalculate when components move
|
|
- **Grid snapping** (20px grid)
|
|
|
|
### Example Projects
|
|
- **8 built-in example projects** with full code, components, and wire definitions:
|
|
|
|
| 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
|
|
- **One-click loading** — loads code, components, and wires into the editor and simulator
|
|
|
|
### Wokwi Libraries (Local Clones)
|
|
- **wokwi-elements** — 48+ electronic web components (Lit-based Web Components)
|
|
- **avr8js** — AVR8 CPU emulator
|
|
- **rp2040js** — RP2040 emulator (cloned, for future use)
|
|
- **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
|
|
choco install arduino-cli
|
|
```
|
|
|
|
**Windows (manual):**
|
|
1. Download from: https://github.com/arduino/arduino-cli/releases
|
|
2. Add to system PATH
|
|
|
|
**Verify installation:**
|
|
```bash
|
|
arduino-cli version
|
|
```
|
|
|
|
**Initialize arduino-cli:**
|
|
```bash
|
|
arduino-cli core update-index
|
|
arduino-cli core install arduino:avr
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Option A: Docker (Recommended)
|
|
|
|
The fastest way to get started. Requires only [Docker](https://docs.docker.com/get-docker/) and Docker Compose.
|
|
|
|
```bash
|
|
git clone https://github.com/davidmonterocrespo24/openwokwi.git
|
|
cd openwokwi
|
|
docker compose up --build
|
|
```
|
|
|
|
Once running:
|
|
- **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.
|
|
|
|
To stop:
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
### Option B: Manual Setup
|
|
|
|
#### 1. Clone the repository
|
|
```bash
|
|
git clone https://github.com/davidmonterocrespo24/openwokwi.git
|
|
cd openwokwi
|
|
```
|
|
|
|
#### 2. Setup Backend
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
|
|
# Activate virtual environment (Windows)
|
|
venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
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
|
|
```
|
|
|
|
The backend will be available at:
|
|
- API: http://localhost:8001
|
|
- Documentation: http://localhost:8001/docs
|
|
|
|
### Start Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
|
|
The frontend will be available at:
|
|
- App: http://localhost:5173
|
|
|
|
## Usage
|
|
|
|
1. Open http://localhost:5173 in your browser
|
|
2. Write Arduino code in the editor (a Blink example is loaded by default)
|
|
3. Click **Compile** to compile the code via the backend
|
|
4. Click **Run** to start real AVR8 CPU simulation
|
|
5. Watch LEDs, LCDs, and other components react in real time
|
|
6. Click on components to view properties or assign pin mappings
|
|
7. Double-click components to open the pin selector
|
|
8. Click pins to create wires connecting components
|
|
9. Browse **Examples** to load pre-built projects (Blink, Traffic Light, Simon Says, LCD, etc.)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
openwokwi/
|
|
├── frontend/ # React + Vite + TypeScript
|
|
│ ├── src/
|
|
│ │ ├── components/
|
|
│ │ │ ├── ComponentPickerModal.tsx # Component search & picker
|
|
│ │ │ ├── DynamicComponent.tsx # Generic wokwi component renderer
|
|
│ │ │ ├── components-wokwi/ # Legacy React wrappers
|
|
│ │ │ ├── editor/ # Monaco Editor + toolbar
|
|
│ │ │ ├── examples/ # Examples gallery
|
|
│ │ │ └── simulator/ # Canvas, wires, pins, dialogs
|
|
│ │ ├── simulation/
|
|
│ │ │ ├── AVRSimulator.ts # AVR8 CPU emulator wrapper
|
|
│ │ │ ├── PinManager.ts # Pin-to-component mapping
|
|
│ │ │ └── parts/ # Part behaviors (LED, LCD, etc.)
|
|
│ │ ├── store/ # Zustand state management
|
|
│ │ ├── services/ # API clients & ComponentRegistry
|
|
│ │ ├── types/ # TypeScript types (wires, components)
|
|
│ │ ├── utils/ # Hex parser, wire routing, pin calc
|
|
│ │ └── pages/ # EditorPage, ExamplesPage
|
|
│ └── public/
|
|
│ └── components-metadata.json # Auto-generated component metadata
|
|
│
|
|
├── backend/ # FastAPI + Python
|
|
│ └── app/
|
|
│ ├── main.py # Entry point, CORS config
|
|
│ ├── api/routes/compile.py # POST /api/compile, GET /api/compile/boards
|
|
│ └── services/arduino_cli.py # arduino-cli subprocess wrapper
|
|
│
|
|
├── wokwi-libs/ # Cloned Wokwi repositories
|
|
│ ├── wokwi-elements/ # 48+ Web Components (Lit)
|
|
│ ├── avr8js/ # AVR8 CPU Emulator
|
|
│ ├── rp2040js/ # RP2040 Emulator (future)
|
|
│ └── wokwi-features/ # Features and documentation
|
|
│
|
|
├── scripts/
|
|
│ └── generate-component-metadata.ts # AST parser for component discovery
|
|
│
|
|
├── doc/
|
|
│ ├── ARCHITECTURE.md # Detailed architecture documentation
|
|
│ ├── WOKWI_LIBS.md # Wokwi integration documentation
|
|
│ ├── SETUP_COMPLETE.md # Project status overview
|
|
│ └── examples/ # Example screenshots
|
|
│
|
|
├── CLAUDE.md # AI assistant guidance
|
|
└── update-wokwi-libs.bat # Update local Wokwi libraries
|
|
```
|
|
|
|
## Technologies Used
|
|
|
|
### Frontend
|
|
- **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
|
|
- **Axios** — HTTP client
|
|
|
|
### Backend
|
|
- **FastAPI** — Python web framework
|
|
- **uvicorn** — ASGI server
|
|
- **arduino-cli** — Arduino compiler (subprocess)
|
|
|
|
### Simulation & Components
|
|
- **avr8js** — Real AVR8 ATmega328p emulator (local clone)
|
|
- **wokwi-elements** — 48+ electronic web components built with Lit (local clone)
|
|
- **rp2040js** — RP2040 emulator (local clone, for future use)
|
|
|
|
## Planned Features
|
|
|
|
- **Serial Monitor** — UI for reading USART output from the simulation
|
|
- **Project Persistence** — Save/load projects with SQLite
|
|
- **Undo/Redo** — Edit history for code and circuit changes
|
|
- **Multi-board Support** — Runtime board switching (Mega, Nano, ESP32)
|
|
- **Wire Validation** — Electrical validation and error highlighting
|
|
- **Export/Import** — Share projects as files
|
|
|
|
## 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
|
|
|
|
### Error: "arduino-cli: command not found"
|
|
- Make sure arduino-cli is installed and in PATH
|
|
- Verify with: `arduino-cli version`
|
|
|
|
### Error: "arduino:avr core not found"
|
|
- Run: `arduino-cli core install arduino:avr`
|
|
|
|
### Frontend doesn't connect to backend
|
|
- Verify backend is running at http://localhost:8001
|
|
- Check CORS logs in browser console
|
|
|
|
### Compilation errors
|
|
- Check backend console for arduino-cli logs
|
|
- Make sure Arduino code is valid
|
|
- Verify you have the `arduino:avr` core installed
|
|
|
|
### 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
|
|
|
|
## Contributing
|
|
|
|
This is an open-source project. Suggestions, bug reports, and pull requests are welcome!
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## References
|
|
|
|
- [Wokwi](https://wokwi.com) — Project inspiration
|
|
- [avr8js](https://github.com/wokwi/avr8js) — AVR8 emulator
|
|
- [wokwi-elements](https://github.com/wokwi/wokwi-elements) — Electronic web components
|
|
- [arduino-cli](https://github.com/arduino/arduino-cli) — Arduino compiler
|
|
- [Monaco Editor](https://microsoft.github.io/monaco-editor/) — Code editor
|
|
|