Add optional mothership IP override to the provisioning flow so nodes
on networks where mDNS is blocked (enterprise WiFi, mesh, VLANs) can
connect on first boot without manual intervention.
- Add ms_ip field to provisioning Payload and request structs
- Firmware writes ms_ip to both NVS_KEY_MS_IP and NVS_KEY_MS_IP_PROV
- Discovery prefers provisioned IP on first attempt, falls back to
mDNS, then cached IP
- Web Serial wizard adds Mothership IP field in Network Troubleshooting
- Auto-populates IP when browser accesses dashboard by IP address
- Document when/how to use the override in docs/notes/mdns-override.md
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
460800 causes the stub to hang mid-write on ESP32-S3 QFN56 boards with XMC
embedded flash. 115200 skips the post-stub baud rate negotiation entirely.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The XMC embedded flash on ESP32-S3 (QFN56) has JEDEC ID 164020 which esptool.js
does not recognise — it returns flash size -1 causing 'File doesn't fit in
available flash' before any bytes are written.
firmware/sdkconfig.defaults:
CONFIG_ESPTOOLPY_FLASHSIZE 16MB → 4MB
4MB is the minimum supported flash. The spi_flash check only panics when
physical < header, so 4MB header is safe on 16MB boards as well.
firmware/partitions.csv:
Redesigned to fit within 4MB flash:
factory 0x010000–0x200000 (~1.9MB, fits current 1.7MB binary + 330KB headroom)
ota_0 0x200000–0x3F0000 (~1.9MB, A/B OTA + rollback preserved)
otadata 0x3F0000–0x3F2000 (8KB)
Total flash used: 0x3F2000 (98.6% of 4MB). Drops ota_1 (was at 8MB, unusable
on 4MB devices anyway); rollback still works factory↔ota_0.
dashboard/js/onboard.js:
flashSize: 'detect' → '4MB' (detect returned -1 for this chip's JEDEC ID;
hardcoding '4MB' correctly sets the binary header for all supported boards)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- flashSize: 'detect' — esptool.js now detects the physical flash size and
updates the binary header before writing. Fixes boot panic on devices with
4MB embedded flash (e.g. ESP32-S3 WROOM-1-N4R2) when firmware was compiled
for 16MB: spi_flash_init() no longer sees a header/physical mismatch.
- Chip family validation — after loader.main() returns the detected chip,
check it against build.chipFamily from the manifest. Throw a UserError if
a non-ESP32-S3 (or unsupported chip family) is connected, instead of
silently flashing incompatible firmware.
- Better post-flash error messaging — track flashSucceeded flag; if flashing
succeeded but provisioning failed, show "Provisioning failed / unplug and
replug" instead of the misleading "Device not in download mode" help.
- Mothership auto-detection — offline fallback and ms-host placeholder now
use window.location.hostname instead of the hardcoded spaxel-mothership.local.
The browser is already talking to the mothership via this hostname, so it is
the correct default for the device to reach it as well.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The firmware prints 'SPAXEL READY <MAC>' a few seconds after the flash reset,
once the UART driver has initialised. Previously the browser sent the JSON
payload immediately when the port opened — the bytes arrived while the device
was still booting and were lost, causing a 15 s timeout.
New flow:
1. Open port (with retries for USB re-enumeration)
2. Read serial stream waiting for 'SPAXEL READY' line (up to 30 s)
3. Only then send the JSON provisioning payload
4. Wait for firmware's {"ok":true} acknowledgment (up to 10 s)
The MAC extracted from 'SPAXEL READY <MAC>' is used as a fallback in case
the firmware's JSON response is parsed before the mac field is available.
- SSID input: add autocorrect=off, autocapitalize=none, spellcheck=false to
prevent mobile browsers from silently altering SSIDs with special chars
- Password input: same attrs for consistency
- Firmware: accept WPA/WPA2 mixed mode (WIFI_AUTH_WPA_WPA2_PSK) so networks
with special characters in the password connect regardless of WPA version
- Firmware: detect open networks (empty password) and use WIFI_AUTH_OPEN so
passwordless networks are not rejected by the auth threshold
JSON encoding path (JSON.stringify → TextEncoderStream → cJSON) already
handles all characters correctly; these changes prevent browser-side mangling
and firmware-side connection rejection.
Previously: flash firmware → wait for 120s boot window → fill form → send over serial
Now: fill WiFi form → flash firmware → device reboots → send over serial immediately
The provisioning window opens at boot. With credentials already collected, the
browser sends the payload the moment the flash+reboot cycle completes — no human
action required and no race condition. Flash step now handles both flashing and
provisioning in one automated sequence (progress 0→80% flash, 80→100% provision).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Show real-time status messages and a collapsible log panel during WiFi provisioning
- Thread addProvLog/setProvStatus callbacks through provisionAndSend and sendPayloadOverSerial
- Log every stage: mothership fetch, payload assembly, port open retries, serial send/response
- All log lines also go to browser console.log/warn/error
- Firmware: extend provisioning window from 10s to 120s for fresh boards (15s for re-provisioning)
- Firmware: include MAC address in SPAXEL READY message for display
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Clears session state and returns to step 1. Useful when onboarding
multiple devices back-to-back without a page reload.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
getAuthorizedPort() is unreliable after esptool reboots the device.
Use state.port (the port the user explicitly selected) and retry port.open
up to 5 times with 1s gaps to handle the brief window while the device
re-enumerates. Show specific UserError messages instead of the generic one.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
On page reload the serial port reference is lost. If saved state points
to flash_firmware or later and port is null, drop back to connect_device
so the user can re-select their device.
Also add a small '← Back to Connect' link at the bottom of the flash
step so there is always a visible escape route.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove <esp-web-install-button> and all shadow DOM polling hacks.
Use esptool-js (vendored as dashboard/js/esptool-bundle.js) via dynamic
import to flash directly. Flash starts automatically when step 3 loads —
no button click required. Progress shown inline. On failure, shows
BOOT+RST instructions and a retry button.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The ewt-install-dialog tag name check was too strict — drop it and take
the first non-style element child that appears in the shadow root, then
poll _installState on it. This matches how the previous version found
the dialog before we narrowed the check.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
esp-web-tools v10 does not dispatch a state-changed DOM event for
firmware flashing — that event only exists for Improv WiFi provisioning.
Flash state lives on ewt-install-dialog._installState (a LitElement
@state property). Replace the broken event listener with a 100ms poll
on _installState once the dialog appears in the shadow root.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
esp-web-tools v10 removed flash-start/flash-progress/flash-success/flash-error
events. Only state-changed fires — but from inside the shadow root (not composed),
so host-element listeners never receive it.
Fix: MutationObserver watches the shadow root for the dialog element, then
attaches state-changed directly to it. States: erasing/writing drive inline
progress; finished auto-advances; error shows retry.
Also suppress the dialog overlay (CSS injection into shadow root) once erasing
starts, so the flash progress shows inline in the wizard with no separate modal.
The dialog remains visible briefly for the 'preparing' confirm step only.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
If esp-web-tools throws a JS error during progress display (e.g. the
manifest offset bug), flash-success never fires and the wizard gets stuck
with no way to advance. After reaching 100% progress, wait 4s for the
event; if it doesn't come, show a 'Continue →' button instead.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Dockerfile: use --flash_size 4MB and drop OTA data from merge_bin (OTA
data at 0xc10000 inflated binary to 12.6MB, exceeding 4MB chip flash)
- main.go: seedFirmwareDir now overwrites when source size differs, fixing
PVC staleness where old 1.6MB app-only binary was never replaced
- onboard.js: renderFlashFirmware() rewritten so all elements (button,
progress bar, status text, retry help, log panel) are inline in one
container — no separate floating modal
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Captures console.log/warn/error and esp-web-tools state-changed events
into a scrollable monospace log panel (collapsed by default, auto-opens
on flash-start and flash-error). Includes timestamps and error detail
from the flash-error event for diagnosing failures like the toString crash.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
On flash-error, show BOOT+RST instructions with board diagram and a
"Try Again" button instead of a dead-end error message. Escalates to
USB cable/hub advice after 2 failures. Adds a proactive collapsible
tips section before flashing starts for users who read ahead.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Interactive onboarding wizard:
- 8-step Web Serial-based provisioning flow
- Firmware flashing via esp-web-install-button (CDN)
- Live CSI waveform feedback during guided calibration
- Server-side provisioning with client-side fallback
- Serial JSON response handling with error mapping
- Post-calibration reinforcement card with link count
OTA firmware management:
- Firmware list with SHA-256 hashes and size display
- Per-node progress tracking (idle/pending/downloading/rebooting/verified/failed/rollback)
- Rolling update orchestration via REST API
- Status bar button with state indicators (normal/in-progress/has-update)
- Node list badges for OTA status and rollback warnings
Guided troubleshooting:
- First-time feature tooltips with 8s auto-dismiss
- Sequential tooltip tour triggered on first node connection
- Node offline cards with step-by-step recovery instructions
- Factory reset instructions modal
- Client-side link health check (60s no-frame threshold)
- Captive portal recovery documentation
Exit criteria: New ESP32-S3 from unboxed to streaming CSI in under 5 minutes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add troubleshooting infrastructure for non-technical users:
- TroubleshootManager: node offline cards with stepped recovery
guidance, factory reset modal, and detection quality banners
- TooltipManager: first-time feature tooltips with localStorage
persistence, auto-dismiss, and sequential tour
- Onboarding failure guidance: human-readable error messages for
browser compatibility, USB connection, WiFi provisioning, and
node detection failures
- Post-calibration reinforcement card with summary and next steps
- Client-side link health check with auto-recovery
- CSS for offline cards, tooltips, quality banners, and modals
- Script tags wired in index.html for troubleshoot.js and tooltips.js
- 30 tests covering all troubleshooting and tooltip functionality
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Web Serial-based wizard that takes a non-technical user from unboxed
ESP32-S3 to streaming CSI in under 5 minutes. 8-step state machine:
browser check → connect → flash firmware (esp-web-tools) → provision
WiFi → detect node → guided calibration → placement guidance → complete.
Includes sessionStorage persistence for resumability across page refreshes,
live CSI waveform during calibration, human-friendly error messages for
all failure modes, and comprehensive Jest test coverage (34 tests).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
