e676694fdc
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>
46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
# Mothership IP Override (mDNS-less Networks)
|
|
|
|
## Problem
|
|
|
|
mDNS (multicast DNS, port 5353) is blocked or filtered on some networks:
|
|
|
|
- Enterprise WiFi with AP isolation
|
|
- Mesh WiFi systems that suppress multicast between bands
|
|
- VLAN-segmented networks where multicast traffic doesn't cross boundaries
|
|
- Networks with aggressive multicast-to-unicast conversion that breaks mDNS
|
|
|
|
On first boot, an ESP32 node has no cached mothership IP and relies entirely on mDNS discovery (`_spaxel._tcp`). If mDNS is blocked, the node enters `MOTHERSHIP_UNAVAILABLE` state and never connects.
|
|
|
|
## Solution: Provisioning-time IP override
|
|
|
|
The provisioning payload now supports an optional `ms_ip` field — a direct IPv4 address that bypasses mDNS on first connect.
|
|
|
|
### How it works
|
|
|
|
1. During provisioning (Web Serial wizard), the dashboard sends `ms_ip` in the POST body to `/api/provision`
|
|
2. The mothership includes it in the provisioning payload JSON
|
|
3. The firmware writes it to two NVS keys:
|
|
- `ms_ip` — the runtime fallback cache (used on subsequent boots if mDNS fails)
|
|
- `ms_ip_prov` — the provisioning-time override (used on first boot only)
|
|
4. On first boot, the discovery order is:
|
|
1. **Provisioned IP** (`ms_ip_prov`) — tried first, skips mDNS entirely on first attempt
|
|
2. **mDNS query** (`_spaxel._tcp`) — standard discovery
|
|
3. **Cached IP** (`ms_ip`) — fallback from a previous successful connection
|
|
|
|
After a successful connection, `ms_ip` is updated to the current IP. The `ms_ip_prov` value persists but is only preferred on the very first connection attempt (`discovery_fail_count == 0`). If the provisioned IP fails, mDNS is tried next, then the cached IP.
|
|
|
|
### When to use the override
|
|
|
|
- The node is on a different VLAN/subnet from the mothership and mDNS doesn't cross boundaries
|
|
- Enterprise or campus WiFi that blocks multicast
|
|
- Mesh WiFi systems where nodes on different bands can't discover each other via mDNS
|
|
- Any network where `ping spaxel.local` from a computer fails but `ping <mothership-ip>` works
|
|
|
|
### When NOT to use it
|
|
|
|
- On normal home networks where mDNS works — leaving `ms_ip` blank lets the node adapt to DHCP IP changes automatically
|
|
- The mothership IP changes frequently — the cached `ms_ip` updates on each successful connection, but a stale provisioned IP would cause one failed attempt before falling back to mDNS
|
|
|
|
### Dashboard wizard
|
|
|
|
The Web Serial onboarding wizard has an "Advanced: Network Troubleshooting" section on the WiFi credentials step. The "Mothership IP" field is auto-populated when the browser is accessing the dashboard via IP address (e.g., `http://192.168.1.100:8080`). Users on mDNS-blocking networks should enter the mothership's LAN IP there.
|