Enable serial monitor in diagram.json and add firmware verification

Critical fix for missing serial output:
- Add serialMonitor configuration to diagram.json with display:"always"
  - Required for capturing serial output in headless/CI mode
  - Without this, firmware output is not recorded
- Add firmware hexdump verification in boot check workflow
  - Displays first 64 bytes to verify valid ESP32 header (0xe9 magic byte)
  - Helps diagnose corrupt or invalid firmware files
- Update README with comprehensive Serial Monitor Configuration section
  - Explains why serialMonitor config is required
  - Documents configuration options
  - Adds troubleshooting steps for missing serial output
  - Includes firmware verification commands

This should resolve the issue where boot check runs but shows no firmware serial output

Co-authored-by: softhack007 <[email protected]>

Author: Copilot

.github/workflows/wokwi-test.yml

@@ -105,6 +105,15 @@ jobs:
             echo "⚠️  firmware.elf not found (optional for simulation)"
           fi
           
+          # Verify firmware can be read and has valid ESP32 header
+          echo ""
+          echo "Firmware file details:"
+          ls -lh firmware.bin firmware.elf 2>/dev/null || true
+          echo ""
+          echo "Firmware.bin first 64 bytes (hex):"
+          hexdump -C firmware.bin | head -4 || echo "Cannot read firmware.bin"
+          echo "Note: ESP32 firmware should start with magic byte 0xe9"
+          
           echo ""
           echo "Running quick boot check scenario (15 seconds)..."
           echo "Wokwi CLI location: $(which wokwi-cli || echo 'NOT FOUND')"

test/wokwi/README.md

@@ -12,11 +12,39 @@ The Wokwi testing workflow:
 
 ## Files
 
-- `diagram.json` - Wokwi hardware configuration (ESP32 DevKit)
+- `diagram.json` - Wokwi hardware configuration (ESP32 DevKit) with serial monitor settings
 - `wokwi.toml` - Wokwi CLI configuration and port forwarding
 - `prepare-firmware.sh` - Script to copy built firmware to test directory
 - `run-simulator.sh` - Script to start the Wokwi simulator
 
+## Serial Monitor Configuration
+
+The `diagram.json` file includes critical serial monitor configuration required for capturing firmware output in CI environments:
+
+```json
+"serialMonitor": {
+  "display": "always",
+  "newline": "lf"
+}
+```
+
+**Why this is needed:**
+- Without `display: "always"`, serial output is not captured in headless/CI mode
+- The Wokwi simulator only records serial output when explicitly configured
+- This is **required** for debugging boot issues and verifying firmware execution
+
+**Configuration options:**
+- `display: "always"` - Ensures serial output is captured even in headless mode (CI)
+- `display: "auto"` - Only shows serial monitor when running interactively (not suitable for CI)
+- `newline: "lf"` - Line ending format (LF for Unix-style, CRLF for Windows)
+
+**Troubleshooting missing serial output:**
+If you see empty serial logs (`boot-check-serial.log` or `serial.log`):
+1. Verify `serialMonitor` section exists in `diagram.json`
+2. Check firmware.bin has valid ESP32 header (starts with `0xe9` magic byte)
+3. Ensure firmware was built successfully and copied to test directory
+4. Review firmware build logs for compilation errors
+
 ## Running Tests Locally
 
 ### Prerequisites
@@ -150,6 +178,16 @@ To add more tests:
 - Verify Wokwi CLI is installed: `wokwi-cli --version`
 - Check Wokwi CLI logs for errors
 
+### No serial output from firmware
+- Verify `serialMonitor` configuration in diagram.json
+- Check firmware.bin is valid:
+  ```bash
+  hexdump -C firmware.bin | head -4
+  # Should show ESP32 magic byte 0xe9 at start
+  ```
+- Ensure firmware was copied: `ls -lh test/wokwi/firmware.bin`
+- Check firmware build logs for errors
+
 ### Web server not accessible
 - Wait 30-60 seconds for the ESP32 to boot and start WiFi
 - Check that port 8080 is not already in use

test/wokwi/diagram.json

@@ -12,5 +12,9 @@
     }
   ],
   "connections": [],
-  "dependencies": {}
+  "dependencies": {},
+  "serialMonitor": {
+    "display": "always",
+    "newline": "lf"
+  }
 }