From bdb890eaf77d1cbaa2ffb4325997f3fa310eb54c Mon Sep 17 00:00:00 2001 From: David Montero Crespo Date: Wed, 4 Mar 2026 19:16:00 -0300 Subject: [PATCH] docs: update project documentation for clarity and consistency in feature descriptions --- CLAUDE.md | 36 ++++++++--------- README.md | 98 ++++++++++++++++++++++----------------------- doc/ARCHITECTURE.md | 24 +++++------ doc/WOKWI_LIBS.md | 12 +++--- 4 files changed, 85 insertions(+), 85 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 25491f3..727d4a7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -289,28 +289,28 @@ Enable verbose logging: ## Project Status **Implemented:** -- ✅ Full Arduino code editing with Monaco Editor -- ✅ Compilation via arduino-cli to .hex files -- ✅ Real AVR8 emulation with avr8js -- ✅ Pin state tracking and component updates -- ✅ Dynamic component system with 48+ wokwi-elements components -- ✅ Component picker modal with search and categories -- ✅ Component property dialog (single-click interaction) -- ✅ Component rotation (90° increments) -- ✅ Wire creation and rendering (orthogonal routing) -- ✅ Segment-based wire editing (drag segments perpendicular to orientation) -- ✅ Real-time wire preview with grid snapping (20px) -- ✅ Pin overlay system for wire connections +- Full Arduino code editing with Monaco Editor +- Compilation via arduino-cli to .hex files +- Real AVR8 emulation with avr8js +- Pin state tracking and component updates +- Dynamic component system with 48+ wokwi-elements components +- Component picker modal with search and categories +- Component property dialog (single-click interaction) +- Component rotation (90° increments) +- Wire creation and rendering (orthogonal routing) +- Segment-based wire editing (drag segments perpendicular to orientation) +- Real-time wire preview with grid snapping (20px) +- Pin overlay system for wire connections **In Progress:** -- 🚧 Functional wire connections (electrical signal routing) -- 🚧 Wire validation and error handling +- Functional wire connections (electrical signal routing) +- Wire validation and error handling **Planned:** -- 📋 Serial monitor -- 📋 Project persistence (SQLite) -- 📋 Multi-board support (Mega, Nano, ESP32) -- 📋 Undo/redo functionality +- Serial monitor +- Project persistence (SQLite) +- Multi-board support (Mega, Nano, ESP32) +- Undo/redo functionality ## Additional Resources diff --git a/README.md b/README.md index c0f43f4..ffe62f9 100644 --- a/README.md +++ b/README.md @@ -23,39 +23,39 @@ 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 +- **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) +- **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 +- **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: +- **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 @@ -63,18 +63,18 @@ Interactive component properties dialog and segment-based wire editing - 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) +- **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: +- **8 built-in example projects** with full code, components, and wire definitions: | Example | Category | Difficulty | |---------|----------|------------| @@ -87,14 +87,14 @@ Interactive component properties dialog and segment-based wire editing | 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 +- **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 +- **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 @@ -265,12 +265,12 @@ openwokwi/ ## 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 +- **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 diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 488ecce..1f74b12 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -438,44 +438,44 @@ This allows: ## Architecture Advantages -### ✅ Real Emulation +### Real Emulation - True AVR8 CPU execution, not simulation mockups - Same avr8js engine used by Wokwi.com - Accurate timing with configurable speed -### ✅ Plugin-Based Component Behaviors +### Plugin-Based Component Behaviors - PartSimulationRegistry decouples simulation logic from rendering - Easy to add new component behaviors - 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 - No manual component registration needed - New wokwi-elements components appear automatically after rebuild -### ✅ Separation of Concerns +### Separation of Concerns - **Frontend**: UI, visualization, simulation engine - **Backend**: Compilation via arduino-cli - **Wokwi Libs**: Emulation and components (maintained by Wokwi community) -### ✅ Wokwi Compatibility +### Wokwi Compatibility - Official repositories = same functionality as Wokwi.com - Automatic updates with `git pull` - New components available immediately after rebuild -### ✅ Local Development +### Local Development - No internet required after initial setup - Local compilation with arduino-cli - All simulation runs in the browser ## Planned Improvements -- 📋 **Serial Monitor** — UI for USART output display -- 📋 **Project Persistence** — SQLite database for save/load -- 📋 **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 +- **Serial Monitor** — UI for USART output display +- **Project Persistence** — SQLite database for save/load +- **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 ## References diff --git a/doc/WOKWI_LIBS.md b/doc/WOKWI_LIBS.md index 5138574..095b0b5 100644 --- a/doc/WOKWI_LIBS.md +++ b/doc/WOKWI_LIBS.md @@ -4,28 +4,28 @@ Este proyecto utiliza los repositorios oficiales de Wokwi clonados localmente, l ## Repositorios Clonados -### 📦 wokwi-elements +### wokwi-elements - **Ubicación**: `wokwi-libs/wokwi-elements/` - **Descripción**: Web Components (Lit) para 48+ elementos electrónicos (LEDs, resistencias, botones, LCDs, sensores, etc.) - **Repositorio**: https://github.com/wokwi/wokwi-elements - **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. -### 🎮 avr8js +### avr8js - **Ubicación**: `wokwi-libs/avr8js/` - **Descripción**: Emulador completo de microcontroladores AVR8 (ATmega328p) en JavaScript - **Repositorio**: https://github.com/wokwi/avr8js - **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. -### 🚀 rp2040js +### rp2040js - **Ubicación**: `wokwi-libs/rp2040js/` - **Descripción**: Emulador de Raspberry Pi Pico (RP2040) en JavaScript - **Repositorio**: https://github.com/wokwi/rp2040js - **Licencia**: MIT - **Uso**: Clonado para futuro soporte de Raspberry Pi Pico -### 📝 wokwi-features +### wokwi-features - **Ubicación**: `wokwi-libs/wokwi-features/` - **Descripción**: Documentación y tracking de features de Wokwi - **Repositorio**: https://github.com/wokwi/wokwi-features @@ -300,7 +300,7 @@ const metadata = registry.getById('led'); ## Ventajas de Este Enfoque -### ✅ Ventajas +### Ventajas 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 @@ -310,7 +310,7 @@ const metadata = registry.getById('led'); 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 -### ⚠️ Consideraciones +### Consideraciones 1. **Espacio en Disco**: Los repositorios clonados ocupan más espacio (~200MB) 2. **Compilación**: Debes compilar los repositorios después de actualizarlos