ESP32 .local non funziona su Android: mDNS spiegato

Perché un nome .local come gizmo-ticker.local non si apre su Android o col router, come trovare la causa e come usare l'indirizzo IP con una riserva DHCP.

Pubblicato
Tempo di lettura
9 min
Un maker si gratta la testa davanti a un browser che mostra gizmo.local con un punto interrogativo, un telefono triste, un router Wi-Fi e un'etichetta mDNS.

In breve

Un nome .local richiede mDNS: una query multicast su UDP 5353 che telefono, router ed ESP32 devono lasciar passare. Se fallisce, usa l'IP della scheda e riservalo sul router.

Un nome .local dell'ESP32 non funziona quando il dispositivo che lo cerca non riesce a inviare una query mDNS, o non riceve mai risposta. mDNS (multicast DNS) chiede a tutti i dispositivi della rete Wi-Fi in una volta sola, invece di passare da un server DNS. Reti ospiti, VPN, dati mobili, alcuni router e i resolver Android senza mDNS possono romperlo. Il ripiego è l'indirizzo IP della scheda.

In questa guida uso come esempio i tre dispositivi OpenGizmo, perché ognuno annuncia un nome .local dopo essersi connesso al tuo Wi-Fi: gizmo-ticker.local, gizmo-reolink-switch.local e gizmo-camera.local. Ho letto il firmware, la libreria gizmo-common e le fonti AOSP, Apple, Espressif e RFC linkate qui sotto, e segnalo ciò che non sono riuscito a verificare. Hai fretta? Vai alla checklist, poi torna a leggere il perché.

Cos'è mDNS e come viene risolto gizmo-ticker.local?

mDNS è definito nella RFC 6762. Invia messaggi in stile DNS in multicast IP sulla porta UDP 5353 e considera ogni nome che finisce in .local. come link-local, cioè valido solo sulla rete in cui è stato annunciato. Le query vanno a 224.0.0.251 (IPv4) o FF02::FB (IPv6). Non c'è nessun server di mezzo: risponde il dispositivo che possiede il nome.

Un telefono chiede in multicast chi ha gizmo-ticker.local, il router inoltra la richiesta e l'ESP32 risponde con il proprio indirizzo IP; Wi-Fi ospiti, VPN e porta 5353 bloccata interrompono la catena

Lato ESP32, la libreria gizmo-common fa tre cose, tutte in wifi_setup.cpp (versione 2.5.1, quella fissata da ticker e switch Reolink; la camera fissa la 2.4.0, dove ho controllato lo stesso MDNS.begin e lo stesso controllo dell'host):

  • Avvia mDNS solo dopo che la scheda è entrata nel Wi-Fi: startMdns() esce subito se WiFi.status() != WL_CONNECTED.
  • Chiama MDNS.begin(hostname) e aggiunge un servizio http sulla porta TCP 80 con MDNS.addService("http", "tcp", 80).
  • Lo ferma di nuovo quando la connessione cade o si apre l'hotspot di setup, e lo riavvia dopo la connessione successiva.

Quindi, dopo il riavvio del router, il nome sparisce finché la scheda non si riconnette. L'hostname è sempre il nome del progetto, impostato nel firmware di ciascuno, per esempio nel wifi.cpp del ticker: "gizmo-ticker". Gizmo Ticker, Gizmo Reolink Switch e Gizmo Camera funzionano allo stesso modo. Per capire come la scheda è entrata nel tuo Wi-Fi all'inizio, vedi ESP32 captive portal non funziona? Come sistemare il popup Wi-Fi.

Perché .local non funziona su alcuni telefoni Android?

Il supporto ai nomi .local dipende dal resolver del sistema operativo del client, non dall'ESP32. L'ESP32 risponde allo stesso modo a tutti: se un Mac risolve il nome e un telefono no, il problema è nel telefono.

ClientRisolve i nomi .local?Fonte e data
AndroidSì, tramite getaddrinfo(), da novembre 2021, ma non su VPN o dati mobiliPagina AOSP DNS Resolver
macOSSì, tramite BonjourDocumentazione Apple (pagina del 2013, era OS X)
iOSNon indicato in quella pagina AppleNon verificato qui
Linux con systemd-resolvedSolo se mDNS è attivo per il link: MulticastDNS= vale false di default in systemd.networkMan page di systemd.network
Windows 10 e 11Non verificato quiNessuna fonte primaria trovata

Per Android, la documentazione del DNS Resolver di AOSP dice: "Starting from November 2021, Android resolver supports mDNS .local resolution". Implementa la query multicast one-shot della RFC 6762, e le app la ottengono chiamando getaddrinfo() con un nome *.local. La stessa pagina dice che le connessioni VPN e dati mobili sono escluse. L'ho confermato nel codice del resolver: res_cache.cpp ha una funzione is_mdns_supported_transport_types() che restituisce false per le reti cellulari e VPN, e res_send.cpp invia la query mDNS per i nomi marcati come mDNS.

Quello che la pagina non dice è quali versioni di Android lo includono. Il codice sta in packages/modules/DnsResolver, una directory di modulo, quindi la versione del resolver di un telefono può non coincidere con la sua versione di Android. Non ho trovato nessun elenco ufficiale delle versioni, quindi non ne do uno. I consigli scritti prima di novembre 2021 potrebbero essere superati.

Quattro condizioni per .local su Android: Wi-Fi e non dati mobili o VPN, un resolver con mDNS da novembre 2021, un'app che usa getaddrinfo e un router che lascia passare il multicast

Altre due cose possono ancora dare problemi su un telefono recente:

  1. L'app deve interrogare il resolver di sistema. Un browser o un'app che fa le proprie ricerche DNS, per esempio con un client DNS sicuro integrato, non arriva mai a quel codice. È la mia lettura della pagina AOSP: non l'ho provato su un telefono.
  2. Le app possono trovare il dispositivo anche senza il nome. La scheda registra un servizio _http._tcp e la Network Service Discovery API di Android cerca i servizi DNS-SD sulla rete locale. È pensata per chi sviluppa app, ma un'app che la usa può trovare la scheda dal tipo di servizio, senza risolvere il nome .local.

Puoi provare un telefono con un computer collegato via adb: la pagina AOSP suggerisce adb shell ping6 HOSTNAME.local, quindi per il ticker è adb shell ping6 gizmo-ticker.local. Se risponde ma il browser no, la causa probabile è il browser o le sue impostazioni DNS.

Come trovi l'indirizzo IP dell'ESP32?

Un indirizzo IP non richiede nessuna ricerca di nomi, quindi funziona ogni volta che il telefono riesce a raggiungere la scheda. I dispositivi OpenGizmo accettano richieste con tre nomi, secondo il README di gizmo-common: l'indirizzo IP, <hostname> o <hostname>.local. Qualsiasi altra cosa restituisce un errore host_not_allowed. Questo protegge la scheda dal DNS rebinding, ma significa anche che un nome inventato dal router, come gizmo-ticker.lan, non aprirà la web app: usa l'IP.

Un telefono non riesce ad aprire gizmo-ticker.local mentre un router elenca i suoi client con 192.168.1.50 evidenziato, l'indirizzo della scheda ESP32

Dove leggerlo, dal più semplice al più laborioso:

  1. Il dispositivo stesso. L'LCD dello switch Reolink mostra il suo indirizzo nella schermata di setup dell'NVR, secondo il suo README, e la pagina Dispositivo della dashboard lo elenca. La pagina Dispositivo e GET /api/device restituiscono ip e hostname una volta connesso. La pagina della camera nella web app di Gizmo Camera mostra l'indirizzo esatto e il comando MCP.
  2. Il log seriale. Una build di debug del firmware dello switch Reolink scrive Connected, open http://gizmo-reolink-switch.local or http://<ip>. Non ho controllato se gli altri due hanno questa riga.
  3. L'elenco client del router. Cerca un dispositivo nuovo. Senza un hostname impostato nel firmware, il nome DHCP è quello di default: la documentazione di Arduino-ESP32 dice che è "assigned based on the chip type and MAC address". Per quanto ho letto, gizmo-common non chiama WiFi.setHostname(), quindi aspettati un nome di quel tipo, non gizmo-ticker.

Poi apri http://192.168.1.50 con l'indirizzo della tua scheda. Se una pagina si apre via IP ma non via nome, la scheda e la web app sono a posto, e il colpevole è la risoluzione del nome.

Quali impostazioni di router e rete bloccano mDNS?

Diverse cose sulla rete possono bloccare mDNS. Cambia una cosa alla volta e poi riprova.

CausaCosa vediCosa controllare
Client o AP isolationTelefono e scheda online, il nome non funziona e nemmeno l'IPDisattiva la client isolation sull'SSID; evita le reti ospiti
Subnet o VLAN diverseIl nome non funziona; l'IP potrebbe funzionare se il router instrada tra le due retiMetti telefono e scheda sulla stessa subnet, oppure usa l'IP
Firewall sul computer che cercaIl nome non funziona da un solo computerConsenti UDP 5353 in ingresso su quel computer
VPN o dati mobili sul telefonoIl nome non funziona solo sul telefonoSpegni la VPN; usa il Wi-Fi

La pagina di troubleshooting di espboards.dev elenca tra le cause il blocco da parte del router, un firewall su UDP 5353, hotspot isolati o reti ospiti, e la chiamata a MDNS.begin() solo a Wi-Fi attivo. È un elenco per risolvere i problemi, non una specifica, quindi lo uso come checklist, e l'ordine di MDNS.begin() l'ho verificato io stesso in gizmo-common. L'ESP32 in sé non richiede nessuna impostazione sul router.

Cosa ti dice il test:

  • Anche l'IP fallisce: la rete blocca il traffico tra i client (isolation) oppure il router non instrada tra le due reti. Sistema prima questo: non è un problema di mDNS.
  • L'IP funziona, il nome fallisce su ogni dispositivo: il responder mDNS della scheda non è attivo, oppure i dispositivi sono su subnet diverse. Controlla che la scheda sia connessa e cerca Failed to start mDNS nel log di una build di debug.
  • L'IP funziona, il nome funziona su un portatile ma non sul telefono: è il telefono, come nella sezione sopra.

Come dai un indirizzo fisso all'ESP32?

Una riserva DHCP dice al router di dare sempre lo stesso indirizzo allo stesso MAC address, quindi la scheda usa ancora il DHCP e il firmware non si tocca. È la mia scelta per i dispositivi OpenGizmo, perché gizmo-common prende l'indirizzo dal router e il firmware non chiama WiFi.config() per averne uno statico.

  1. Trova il MAC address della scheda nell'elenco client del router, accanto all'IP attuale.
  2. Apri la sezione DHCP o LAN del router e cerca "address reservation", "static lease" o "bind IP to MAC". I nomi cambiano da router a router.
  3. Scegli un indirizzo nel range della LAN, fuori dal pool DHCP se il router lo richiede, e salva.
  4. Riavvia la scheda e controlla che l'elenco client mostri ora l'indirizzo riservato.

Un IP statico nel firmware è l'altra opzione. La documentazione dell'API WiFi di Arduino-ESP32 descrive WiFi.config() per impostare IP locale, gateway, subnet e server DNS prima di begin. Poi ti tocca evitare da solo i conflitti col pool del router. In una rete domestica, la riserva è più sicura.

Se mai metti due dispositivi OpenGizmo uguali sulla stessa rete, proveranno a prendersi lo stesso nome .local. La RFC 6762, sezione 9, dice che chi perde deve smettere di usare il nome e sceglierne uno nuovo. La documentazione mDNS di Espressif che ho letto non descrive come lo gestisce il componente ESP32, e non l'ho provato, quindi raggiungi ciascuno col proprio IP.

Come imposti l'hostname nel codice Arduino?

Esistono due nomi diversi, e spesso si confondono. Il nome mDNS è quello impostato da MDNS.begin(). Il nome DHCP, impostato con WiFi.setHostname(), è come la scheda appare nell'elenco del router. La documentazione di Arduino-ESP32 dice che setHostname() "must be called BEFORE Wi-Fi is started", mentre mDNS parte dopo la connessione. Questo è uno sketch minimo, costruito da quella documentazione e dalla logica di gizmo-common, non compilato per questo articolo:

hostname.ino
hostname.ino
#include <WiFi.h>
#include <ESPmDNS.h>

void setup() {
    WiFi.setHostname("gizmo-ticker"); // DHCP name in the router's list, before WiFi.begin()
    WiFi.begin("my-ssid", "my-password");
    while (WiFi.status() != WL_CONNECTED) {
        delay(250);
    }

    // Only after the connection is up
    if (MDNS.begin("gizmo-ticker")) {
        MDNS.addService("http", "tcp", 80);
    }
}

void loop() {}
Riga 17, col. 1UTF-8cpp

Lo raggiungi su http://gizmo-ticker.local. ESPmDNS non valida il nome, quindi usa solo lettere minuscole, cifre e trattini, come negli hostname OpenGizmo. Per un esempio completo con le riconnessioni, leggi startMdns() in gizmo-common, oppure la build dello switch Reolink che lo usa.

Checklist: il nome .local non si apre

  1. Telefono e scheda sono sulla stessa rete Wi-Fi, e il telefono è sul Wi-Fi e non sui dati mobili, con la VPN spenta?
  2. L'indirizzo IP della scheda apre la web app? Se no, sistema prima la client isolation o la subnet.
  3. Il nome funziona da un portatile sulla stessa rete? Se sì, la scheda è a posto e la causa è il resolver del telefono o l'app.
  4. Su un telefono con adb: adb shell ping6 gizmo-ticker.local risponde?
  5. La scheda si è riconnessa dopo il riavvio del router? mDNS funziona solo finché è connessa.
  6. Un altro dispositivo rivendica lo stesso nome?
  7. Ancora bloccato? Usa l'IP e riservalo sul router, così l'indirizzo smette di cambiare.

Per la camera vale la stessa regola con gli script: la guida all'URL di snapshot e la guida al server MCP funzionano entrambe con l'IP al posto di gizmo-camera.local.

Cosa è stato verificato e i limiti

Ho letto la logica di avvio e arresto di mDNS e il controllo dell'host in gizmo-common 2.5.1, gli hostname nei tre firmware, e il codice e la documentazione del resolver di Android, a novembre 2026. Non ho eseguito nulla di tutto questo su un telefono, un router o una scheda per questo articolo: il comando adb, i passaggi sul router e lo sketch derivano dalle fonti, non da misure. Il supporto di Windows non è verificato, nessuna fonte che ho trovato elenca le versioni di Android con mDNS, e i router variano molto in come chiamano le loro impostazioni.

Se il nome continua a fallire dopo la checklist, l'IP e una riserva non sono una sconfitta: sono quello che vuole una rete domestica. Per capire come la scheda ha preso il Wi-Fi all'inizio, confronta le opzioni in ESP32 Wi-Fi provisioning: captive portal, BLE, Improv, e per il sistema completo vedi cos'è OpenGizmo.

Domande frequenti

Trova risposte rapide alle domande più comuni su questo argomento.

Un nome .local si risolve solo se il telefono invia una query multicast mDNS e il router la inoltra. Secondo l'AOSP, il resolver di Android la supporta da novembre 2021, ma non su VPN o dati mobili, e un router con client isolation la blocca. La soluzione affidabile è aprire l'indirizzo IP dell'ESP32.

Pubblicato

Pronto a costruire il tuo gizmo?

Scegli un progetto ESP32 open source e segui la sua guida passo passo, dalla lista dei componenti e dai collegamenti fino al firmware e al primo avvio.

Leggi anche

Esplora le categorie