update wording, add CLion, drop MCP not used in this experiment

Author: georgik

content/blog/2025/11/debugging-embedded-graphics-with-wokwi-and-ai/index.md

@@ -17,14 +17,16 @@ Raylib is a popular game programming library that recently gained software rende
 
 The initial port compiled and ran, but there was a problem: instead of showing solid colors, the display showed vertical yellow/blue stripes. The framebuffer format was clearly wrong, but determining exactly where and how required multiple iterations.
 
-## Enter Wokwi: Hardware Simulation in CI/CD
+## Enter Wokwi: Hardware Simulation for Bug Hunting
 
-Rather than flash to physical hardware for every test, we integrated Wokwi - a hardware simulator that can emulate ESP32 boards with displays. This gave us several advantages:
+Rather than flash to physical hardware for every test, we used Wokwi - a powerful hardware simulator that can emulate ESP32 boards with displays. Wokwi is particularly valuable for bug hunting in embedded graphics applications because it provides:
 
-1. **Fast iteration cycles**: No need to physically flash devices
-2. **Screenshot capability**: Wokwi can capture display output as PNG files
-3. **Reproducible testing**: Same simulation conditions every time
-4. **CI/CD integration**: Automated testing in GitHub Actions
+1. **Screenshot Capability**: Capture display output as PNG files at any point in execution - crucial for visual debugging
+2. **Integrated Debugger**: Step through code, set breakpoints, and inspect variables without physical hardware
+3. **Fast Iteration Cycles**: No need to physically flash devices between tests
+4. **Reproducible Testing**: Same simulation conditions every time, eliminating hardware variability
+5. **IDE Integration**: Works seamlessly with VSCode and CLion for professional development workflows
+6. **CI/CD Ready**: Automated testing in GitHub Actions with screenshot validation
 
 Our Wokwi setup included:
 - ESP32-S3-BOX-3 board definition (320x240 ILI9341 display)
@@ -47,7 +49,7 @@ Here's where it got interesting. Instead of manually analyzing each screenshot a
 
 ### 1. Initial Problem Identification
 
-**Human**: "The screen should have a red background, but as you can see, it's not true. It has some kind of Yellow, blue, vertical line patterns."
+**Developer**: "The screen should have a red background, but as you can see, it's not true. It has some kind of Yellow, blue, vertical line patterns."
 
 **AI Action**: Read the screenshot, identified the vertical stripe pattern indicating likely color format mismatch or byte-order issues.
 
@@ -126,60 +128,64 @@ This was then integrated into the CI pipeline using ImageMagick.
 Here's what a typical debugging iteration looked like:
 
 ```text path=null start=null
-┌─────────────────────────────────────────────────┐
-│ 1. Human describes problem + shares screenshot  │
-└────────────────┬────────────────────────────────┘
+┌─────────────────────────────────────────────────────┐
+│ 1. Developer describes problem + shares screenshot │
+└────────────────┬────────────────────────────────────┘
                  │
-┌────────────────▼────────────────────────────────┐
-│ 2. AI analyzes code + screenshot via vision API │
-│    - Identifies vertical stripes pattern        │
-│    - Reviews framebuffer handling code          │
-│    - Checks RGB565 format documentation         │
-└────────────────┬────────────────────────────────┘
+┌────────────────▼────────────────────────────────────┐
+│ 2. AI analyzes code + screenshot via vision API    │
+│    - Identifies vertical stripes pattern           │
+│    - Reviews framebuffer handling code             │
+│    - Checks RGB565 format documentation            │
+└────────────────┬────────────────────────────────────┘
                  │
-┌────────────────▼────────────────────────────────┐
-│ 3. AI proposes code changes                     │
-│    - Direct framebuffer access                  │
-│    - Byte swapping for endianness               │
-└────────────────┬────────────────────────────────┘
+┌────────────────▼────────────────────────────────────┐
+│ 3. AI proposes code changes                        │
+│    - Direct framebuffer access                     │
+│    - Byte swapping for endianness                  │
+└────────────────┬────────────────────────────────────┘
                  │
-┌────────────────▼────────────────────────────────┐
-│ 4. Build and simulate                           │
-│    $ idf.py build                               │
-│    $ wokwi-cli --screenshot-time 5000 ...       │
-└────────────────┬────────────────────────────────┘
+┌────────────────▼────────────────────────────────────┐
+│ 4. Build and simulate in Wokwi                     │
+│    $ idf.py build                                  │
+│    $ wokwi-cli --screenshot-time 5000 ...          │
+│    [Wokwi captures display screenshot]             │
+└────────────────┬────────────────────────────────────┘
                  │
-┌────────────────▼────────────────────────────────┐
-│ 5. AI reads new screenshot                      │
-│    tool: read_any_files(screenshot.png)         │
-│    Result: Solid green color ✅                 │
-└─────────────────────────────────────────────────┘
+┌────────────────▼────────────────────────────────────┐
+│ 5. AI reads new screenshot                         │
+│    tool: read_any_files(screenshot.png)            │
+│    Result: Solid green color ✅                    │
+└────────────────────────────────────────────────────┘
 ```
 
 ## Key Insights
 
 ### Why This Worked Well
 
-1. **Visual Feedback is Critical**: Color bugs can't be debugged with logs alone - you need to see the actual output
-2. **Wokwi's Consistency**: Same simulation every time meant we could isolate variables
-3. **AI Vision + Code Understanding**: The AI could correlate visual output with code changes
-4. **Fast Iteration**: ~2 minutes per cycle (build + simulate + analyze) vs. hours with physical hardware
-5. **Executable Investigation**: The AI could directly build, simulate, and capture screenshots
+1. **Visual Feedback is Critical**: Color bugs can't be debugged with logs alone - you need to see the actual output. Wokwi's screenshot capability made this trivial
+2. **Wokwi's Debugging Power**: The integrated debugger would have allowed stepping through framebuffer operations if screenshots weren't sufficient
+3. **Wokwi's Consistency**: Same simulation every time meant we could isolate variables and prove fixes definitively
+4. **AI Vision + Code Understanding**: The AI could correlate visual output with code changes by reading Wokwi screenshots
+5. **Fast Iteration**: ~2 minutes per cycle (build + simulate + analyze) vs. hours with physical hardware
+6. **Professional Development Environment**: Wokwi's VSCode and CLion integration meant we could debug just like with physical hardware
 
 ### Limitations We Hit
 
-1. **MCP Connection Drops**: Wokwi MCP server would occasionally disconnect, requiring restart
-2. **Screenshot Timing**: Had to carefully time captures to match test sequence (red at 2.7s, green at 3.9s, etc.)
-3. **Endianness Assumptions**: Even AI made wrong guesses about byte order initially
+1. **Screenshot Timing**: Had to carefully time captures to match test sequence (red at 2.7s, green at 3.9s, etc.) - though Wokwi's debugger could have helped pause at exact moments
+2. **Endianness Assumptions**: Even AI made wrong guesses about byte order initially, requiring multiple iterations
 
 ## Lessons for Embedded Development
 
-### 1. Simulation-First Development
+### 1. Simulation-First Development with Wokwi
 
-Don't wait until hardware is available. Tools like Wokwi let you:
-- Test display output without physical devices
-- Capture exact visual state for comparison
-- Integrate visual testing into CI/CD
+Don't wait until hardware is available. Wokwi provides a complete development environment:
+- **Screenshot capture** for visual debugging - essential for graphics bugs
+- **Integrated debugger** with breakpoints and variable inspection
+- **IDE integration** with VSCode and CLion for professional workflows
+- **Test display output** without physical devices
+- **Capture exact visual state** for comparison and regression testing
+- **CI/CD integration** for automated visual testing
 
 ### 2. AI as Debugging Partner
 
@@ -196,7 +202,7 @@ The key was having a repeatable process:
 Observe → Hypothesize → Code → Build → Simulate → Capture → Verify → Repeat
 ```
 
-Each step was automated or AI-assisted, keeping human focus on problem-solving.
+Each step was automated or AI-assisted, keeping developer focus on problem-solving. Wokwi's screenshot capability was the key enabler - without it, we'd need physical hardware and manual camera captures for each test.
 
 ## The Complete Solution