spaxel/docs/notes/mdns-override.md

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.