a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update project documentation for clarity and consistency in feature descriptions

pull/10/head
David Montero Crespo 2026-03-04 19:16:00 -03:00
parent 9cbe15d0a5
commit bdb890eaf7
4 changed files with 85 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
CLAUDE.md
View File

@ -289,28 +289,28 @@ Enable verbose logging:
## Project Status ## Project Status
**Implemented:** **Implemented:**
- ✅ Full Arduino code editing with Monaco Editor - Full Arduino code editing with Monaco Editor
- ✅ Compilation via arduino-cli to .hex files - Compilation via arduino-cli to .hex files
- ✅ Real AVR8 emulation with avr8js - Real AVR8 emulation with avr8js
- ✅ Pin state tracking and component updates - Pin state tracking and component updates
- ✅ Dynamic component system with 48+ wokwi-elements components - Dynamic component system with 48+ wokwi-elements components
- ✅ Component picker modal with search and categories - Component picker modal with search and categories
- ✅ Component property dialog (single-click interaction) - Component property dialog (single-click interaction)
- ✅ Component rotation (90° increments) - Component rotation (90° increments)
- ✅ Wire creation and rendering (orthogonal routing) - Wire creation and rendering (orthogonal routing)
- ✅ Segment-based wire editing (drag segments perpendicular to orientation) - Segment-based wire editing (drag segments perpendicular to orientation)
- ✅ Real-time wire preview with grid snapping (20px) - Real-time wire preview with grid snapping (20px)
- ✅ Pin overlay system for wire connections - Pin overlay system for wire connections
**In Progress:** **In Progress:**
- 🚧 Functional wire connections (electrical signal routing) - Functional wire connections (electrical signal routing)
- 🚧 Wire validation and error handling - Wire validation and error handling
**Planned:** **Planned:**
- 📋 Serial monitor - Serial monitor
- 📋 Project persistence (SQLite) - Project persistence (SQLite)
- 📋 Multi-board support (Mega, Nano, ESP32) - Multi-board support (Mega, Nano, ESP32)
- 📋 Undo/redo functionality - Undo/redo functionality
## Additional Resources ## Additional Resources

98
README.md
View File

@ -23,39 +23,39 @@ Interactive component properties dialog and segment-based wire editing
## 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
- ✅ **Arduino compilation** via `arduino-cli` backend — compile sketches to `.hex` files - **Arduino compilation** via `arduino-cli` backend — compile sketches to `.hex` files
- ✅ **Compile / Run / Stop / Reset** toolbar buttons with status messages - **Compile / Run / Stop / Reset** toolbar buttons with status messages
### AVR8 Simulation (avr8js) ### AVR8 Simulation (avr8js)
- ✅ **Real ATmega328p emulation** at 16 MHz using avr8js - **Real ATmega328p emulation** at 16 MHz using avr8js
- ✅ **Intel HEX parser** with checksum verification - **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 peripheral** support - **Timer0 peripheral** support
- ✅ **USART (Serial)** support - **USART (Serial)** support
- ✅ **~60 FPS simulation loop** with `requestAnimationFrame` (~267k cycles/frame) - **~60 FPS simulation loop** with `requestAnimationFrame` (~267k cycles/frame)
- ✅ **Speed control** — adjustable from 0.1x to 10x - **Speed control** — adjustable from 0.1x to 10x
- ✅ **Single-step debugging** API - **Single-step debugging** API
- ✅ **External pin state injection** for input components (buttons, potentiometers) - **External pin state injection** for input components (buttons, potentiometers)
### Component System (48+ Components) ### Component System (48+ Components)
- ✅ **48 electronic components** auto-discovered from wokwi-elements source code - **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 - **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) - **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) - **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** (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 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 - **Pin overlay system** — clickable cyan dots on each component pin with hover animation
- ✅ **Keyboard shortcuts** — Delete/Backspace to remove, Escape to cancel - **Keyboard shortcuts** — Delete/Backspace to remove, Escape to cancel
### Part Simulation Behaviors ### Part Simulation Behaviors
- ✅ **LED** — pin state drives LED on/off - **LED** — pin state drives LED on/off
- ✅ **RGB LED** — digital HIGH/LOW mapped to individual R/G/B channels - **RGB LED** — digital HIGH/LOW mapped to individual R/G/B channels
- ✅ **Pushbutton** — press/release events inject active-LOW pin state into simulation - **Pushbutton** — press/release events inject active-LOW pin state into simulation
- ✅ **Potentiometer** — reads element value (0-1023), converts to voltage, injects into ADC channel - **Potentiometer** — reads element value (0-1023), converts to voltage, injects into ADC channel
- ✅ **LCD 1602 & LCD 2004** — Full HD44780 controller emulation: - **LCD 1602 & LCD 2004** — Full HD44780 controller emulation:
- 4-bit mode protocol (high nibble first, then low nibble) - 4-bit mode protocol (high nibble first, then low nibble)
- DDRAM with proper line address mapping - DDRAM with proper line address mapping
- Commands: Clear Display, Return Home, Entry Mode Set, Display On/Off, Cursor/Display Shift, Function Set - Commands: Clear Display, Return Home, Entry Mode Set, Display On/Off, Cursor/Display Shift, Function Set
@ -63,18 +63,18 @@ Interactive component properties dialog and segment-based wire editing
- Enable pin falling-edge detection for data latching - Enable pin falling-edge detection for data latching
### 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 - **Real-time preview** — dashed green wire with L-shaped orthogonal routing while creating
- ✅ **Orthogonal wire rendering** — no diagonal paths - **Orthogonal wire rendering** — no diagonal paths
- ✅ **Segment-based wire editing** — hover to highlight, drag segments perpendicular to their orientation - **Segment-based wire editing** — hover to highlight, drag segments perpendicular to their orientation
- ✅ **Smooth dragging** with `requestAnimationFrame` - **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) - **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) - **Automatic overlap offset** — parallel wires are offset symmetrically (6px spacing)
- ✅ **Auto-update positions** — wire endpoints recalculate when components move - **Auto-update positions** — wire endpoints recalculate when components move
- ✅ **Grid snapping** (20px grid) - **Grid snapping** (20px grid)
### Example Projects ### Example Projects
- ✅ **8 built-in example projects** with full code, components, and wire definitions: - **8 built-in example projects** with full code, components, and wire definitions:
| Example | Category | Difficulty | | Example | Category | Difficulty |
|---------|----------|------------| |---------|----------|------------|
@ -87,14 +87,14 @@ Interactive component properties dialog and segment-based wire editing
| Simon Says Game | Games | Advanced | | Simon Says Game | Games | Advanced |
| LCD 20x4 Display | Displays | Intermediate | | LCD 20x4 Display | Displays | Intermediate |
- ✅ **Examples gallery** with category and difficulty filters - **Examples gallery** with category and difficulty filters
- ✅ **One-click loading** — loads code, components, and wires into the editor and simulator - **One-click loading** — loads code, components, and wires into the editor and simulator
### Wokwi Libraries (Local Clones) ### Wokwi Libraries (Local Clones)
- ✅ **wokwi-elements** — 48+ electronic web components (Lit-based Web Components) - **wokwi-elements** — 48+ electronic web components (Lit-based Web Components)
- ✅ **avr8js** — AVR8 CPU emulator - **avr8js** — AVR8 CPU emulator
- ✅ **rp2040js** — RP2040 emulator (cloned, for future use) - **rp2040js** — RP2040 emulator (cloned, for future use)
- ✅ **Build-time metadata generation** — TypeScript AST parser reads wokwi-elements source to generate component metadata automatically - **Build-time metadata generation** — TypeScript AST parser reads wokwi-elements source to generate component metadata automatically
## Prerequisites ## Prerequisites
@ -265,12 +265,12 @@ openwokwi/
## Planned Features ## Planned Features
- 📋 **Serial Monitor** — UI for reading USART output from the simulation - **Serial Monitor** — UI for reading USART output from the simulation
- 📋 **Project Persistence** — Save/load projects with SQLite - **Project Persistence** — Save/load projects with SQLite
- 📋 **Undo/Redo** — Edit history for code and circuit changes - **Undo/Redo** — Edit history for code and circuit changes
- 📋 **Multi-board Support** — Runtime board switching (Mega, Nano, ESP32) - **Multi-board Support** — Runtime board switching (Mega, Nano, ESP32)
- 📋 **Wire Validation** — Electrical validation and error highlighting - **Wire Validation** — Electrical validation and error highlighting
- 📋 **Export/Import** — Share projects as files - **Export/Import** — Share projects as files
## Update Wokwi Libraries ## Update Wokwi Libraries

24
doc/ARCHITECTURE.md
View File

@ -438,44 +438,44 @@ This allows:
## Architecture Advantages ## Architecture Advantages
### ✅ Real Emulation ### Real Emulation
- True AVR8 CPU execution, not simulation mockups - True AVR8 CPU execution, not simulation mockups
- Same avr8js engine used by Wokwi.com - Same avr8js engine used by Wokwi.com
- Accurate timing with configurable speed - Accurate timing with configurable speed
### ✅ Plugin-Based Component Behaviors ### Plugin-Based Component Behaviors
- PartSimulationRegistry decouples simulation logic from rendering - PartSimulationRegistry decouples simulation logic from rendering
- Easy to add new component behaviors - Easy to add new component behaviors
- Supports both input (event-driven) and output (pin-state-driven) components - Supports both input (event-driven) and output (pin-state-driven) components
### ✅ Automatic Component Discovery ### Automatic Component Discovery
- Build-time TypeScript AST parser extracts metadata from wokwi-elements source - Build-time TypeScript AST parser extracts metadata from wokwi-elements source
- No manual component registration needed - No manual component registration needed
- New wokwi-elements components appear automatically after rebuild - New wokwi-elements components appear automatically after rebuild
### ✅ Separation of Concerns ### Separation of Concerns
- **Frontend**: UI, visualization, simulation engine - **Frontend**: UI, visualization, simulation engine
- **Backend**: Compilation via arduino-cli - **Backend**: Compilation via arduino-cli
- **Wokwi Libs**: Emulation and components (maintained by Wokwi community) - **Wokwi Libs**: Emulation and components (maintained by Wokwi community)
### ✅ Wokwi Compatibility ### Wokwi Compatibility
- Official repositories = same functionality as Wokwi.com - Official repositories = same functionality as Wokwi.com
- Automatic updates with `git pull` - Automatic updates with `git pull`
- New components available immediately after rebuild - New components available immediately after rebuild
### ✅ Local Development ### Local Development
- No internet required after initial setup - No internet required after initial setup
- Local compilation with arduino-cli - Local compilation with arduino-cli
- All simulation runs in the browser - All simulation runs in the browser
## Planned Improvements ## Planned Improvements
- 📋 **Serial Monitor** — UI for USART output display - **Serial Monitor** — UI for USART output display
- 📋 **Project Persistence** — SQLite database for save/load - **Project Persistence** — SQLite database for save/load
- 📋 **Undo/Redo** — Edit history for code and circuit changes - **Undo/Redo** — Edit history for code and circuit changes
- 📋 **Multi-board Support** — Runtime board switching (Mega, Nano, ESP32) - **Multi-board Support** — Runtime board switching (Mega, Nano, ESP32)
- 📋 **Wire Validation** — Electrical validation and error highlighting - **Wire Validation** — Electrical validation and error highlighting
- 📋 **Export/Import** — Share projects as files - **Export/Import** — Share projects as files
## References ## References

12
doc/WOKWI_LIBS.md
View File

@ -4,28 +4,28 @@ Este proyecto utiliza los repositorios oficiales de Wokwi clonados localmente, l
## Repositorios Clonados ## Repositorios Clonados
### 📦 wokwi-elements ### wokwi-elements
- **Ubicación**: `wokwi-libs/wokwi-elements/` - **Ubicación**: `wokwi-libs/wokwi-elements/`
- **Descripción**: Web Components (Lit) para 48+ elementos electrónicos (LEDs, resistencias, botones, LCDs, sensores, etc.) - **Descripción**: Web Components (Lit) para 48+ elementos electrónicos (LEDs, resistencias, botones, LCDs, sensores, etc.)
- **Repositorio**: https://github.com/wokwi/wokwi-elements - **Repositorio**: https://github.com/wokwi/wokwi-elements
- **Licencia**: MIT - **Licencia**: MIT
- **Uso actual**: Renderizado visual de todos los componentes en el canvas de simulación. Un script de generación de metadata (`scripts/generate-component-metadata.ts`) parsea el código fuente TypeScript para descubrir automáticamente todos los componentes, sus propiedades y pines. - **Uso actual**: Renderizado visual de todos los componentes en el canvas de simulación. Un script de generación de metadata (`scripts/generate-component-metadata.ts`) parsea el código fuente TypeScript para descubrir automáticamente todos los componentes, sus propiedades y pines.
### 🎮 avr8js ### avr8js
- **Ubicación**: `wokwi-libs/avr8js/` - **Ubicación**: `wokwi-libs/avr8js/`
- **Descripción**: Emulador completo de microcontroladores AVR8 (ATmega328p) en JavaScript - **Descripción**: Emulador completo de microcontroladores AVR8 (ATmega328p) en JavaScript
- **Repositorio**: https://github.com/wokwi/avr8js - **Repositorio**: https://github.com/wokwi/avr8js
- **Licencia**: MIT - **Licencia**: MIT
- **Uso actual**: Emulación real del CPU a 16MHz, con Timer0/1/2, USART, ADC, y puertos GPIO (PORTB/C/D). Ejecuta ~267,000 ciclos por frame a ~60fps. - **Uso actual**: Emulación real del CPU a 16MHz, con Timer0/1/2, USART, ADC, y puertos GPIO (PORTB/C/D). Ejecuta ~267,000 ciclos por frame a ~60fps.
### 🚀 rp2040js ### rp2040js
- **Ubicación**: `wokwi-libs/rp2040js/` - **Ubicación**: `wokwi-libs/rp2040js/`
- **Descripción**: Emulador de Raspberry Pi Pico (RP2040) en JavaScript - **Descripción**: Emulador de Raspberry Pi Pico (RP2040) en JavaScript
- **Repositorio**: https://github.com/wokwi/rp2040js - **Repositorio**: https://github.com/wokwi/rp2040js
- **Licencia**: MIT - **Licencia**: MIT
- **Uso**: Clonado para futuro soporte de Raspberry Pi Pico - **Uso**: Clonado para futuro soporte de Raspberry Pi Pico
### 📝 wokwi-features ### wokwi-features
- **Ubicación**: `wokwi-libs/wokwi-features/` - **Ubicación**: `wokwi-libs/wokwi-features/`
- **Descripción**: Documentación y tracking de features de Wokwi - **Descripción**: Documentación y tracking de features de Wokwi
- **Repositorio**: https://github.com/wokwi/wokwi-features - **Repositorio**: https://github.com/wokwi/wokwi-features
@ -300,7 +300,7 @@ const metadata = registry.getById('led');
## Ventajas de Este Enfoque ## Ventajas de Este Enfoque
### ✅ Ventajas ### Ventajas
1. **Actualización Fácil**: Un simple `git pull` + rebuild te da las últimas mejoras 1. **Actualización Fácil**: Un simple `git pull` + rebuild te da las últimas mejoras
2. **Compatible con Wokwi**: Usas exactamente el mismo código que Wokwi.com 2. **Compatible con Wokwi**: Usas exactamente el mismo código que Wokwi.com
@ -310,7 +310,7 @@ const metadata = registry.getById('led');
6. **Sin Dependencia de npm**: No dependes de que publiquen actualizaciones en npm 6. **Sin Dependencia de npm**: No dependes de que publiquen actualizaciones en npm
7. **100% Offline**: Funciona completamente sin internet después de la configuración inicial 7. **100% Offline**: Funciona completamente sin internet después de la configuración inicial
### ⚠️ Consideraciones ### Consideraciones
1. **Espacio en Disco**: Los repositorios clonados ocupan más espacio (~200MB) 1. **Espacio en Disco**: Los repositorios clonados ocupan más espacio (~200MB)
2. **Compilación**: Debes compilar los repositorios después de actualizarlos 2. **Compilación**: Debes compilar los repositorios después de actualizarlos