Join Wi-Fi

mDNS LAN discovery

Find the device on the LAN without memorising its IP.

Join Wi-Fi Find on LAN ESP32 Wi-Fi parts

Official path: examples/protocols/mdns

01 Overview

mDNS (Multicast DNS) lets a device be discovered on the local network by hostname and service type, without typing an IP address.

It solves the problem of changing IPs: as long as the device is on the same Wi-Fi, a computer or phone can reach it via a name like `my-esp32.local`.

Typical uses: local web configuration pages, quick connection during development, and automatic discovery in smart home setups.

mDNS works only within the same broadcast domain — not across the public internet or VLANs.

It is not a replacement for provisioning; it is a post-provisioning discovery mechanism. Provisioning usually needs a separate path (SoftAP or BLE).

In industrial or enterprise networks, multicast may be blocked, so mDNS can fail — always keep an IP fallback.

02 Hardware

Wi-Fi module: Requires ESP32's Wi-Fi, 2.4 GHz band.
Antenna: Ensure proper antenna connection for stable signal.
Power: Stable 3.3V supply to avoid Wi-Fi drops due to voltage fluctuations.
Multicast support: mDNS relies on multicast; routers/switches must allow multicast packets.
AP isolation: If the device is on an isolated AP, mDNS may not work.
IP fallback: Display or print the IP address on the device for manual access if mDNS fails.
No extra hardware: This example needs only Wi-Fi, no other peripherals.

03 Software flow

1. Initialize NVS and Wi-Fi, connect to the target network.

2. Wait for IP address (WIFI_EVENT_STA_GOT_IP).

3. Call `mdns_init()` to initialize the mDNS service.

4. Set the hostname (e.g., `my-esp32`), ensuring it is unique.

5. Add a service type (e.g., `_http._tcp`) and port (e.g., 80).

6. Start an HTTP server or other service to pair with mDNS.

7. In the main loop, handle events: if Wi-Fi disconnects, stop mDNS; restart after reconnect.

8. Error handling: if mDNS init fails, print an error and fall back to IP access.

04 Core points

Names must be unique per unit. Use MAC or serial number as suffix to avoid collisions.
If multicast is blocked, mDNS fails — provide an IP direct access fallback.
Do not use across subnets; mDNS works only on the same LAN.
Custom work: discovery plus provisioning portal.
Firewalls may block mDNS responses; test on supported OSes (macOS, iOS, Windows 10+).
Testing: ensure clients support mDNS.

中文

连上 Wi-Fi

mDNS 局域网发现

不用记 IP，电脑和手机在局域网里找到设备。

连上 Wi-Fi 局域网发现 ESP32 Wi-Fi parts

官方路径: examples/protocols/mdns

01 项目概述

mDNS（多播 DNS）让设备在局域网内通过主机名和服务类型被自动发现，无需手动输入 IP 地址。

它解决的是“设备 IP 经常变化，用户记不住”的问题：只要设备连上同一 Wi-Fi，电脑或手机就能通过类似 `my-esp32.local` 的名字访问。

典型应用场景包括：本地 Web 配置界面、开发调试时快速连接设备、以及智能家居中设备自动发现。

mDNS 仅适用于同一广播域内的局域网，不能跨公网或跨 VLAN 发现设备。

它不是设备配网的替代方案，而是配网后的发现机制；配网通常需要单独处理（如 SoftAP 或 BLE）。

在工业现场或企业网络中，组播可能被禁用，导致 mDNS 失效，因此必须保留 IP 直连的兜底方案。

02 项目硬件描述

Wi-Fi 模块： 需要 ESP32 的 Wi-Fi 功能，支持 2.4GHz 频段。
天线： 确保天线连接正确，以获得稳定的信号。
电源： 稳定的 3.3V 供电，避免因电压波动导致 Wi-Fi 断开。
组播支持： mDNS 依赖组播，路由器或交换机需允许组播包通过。
网络隔离： 若设备处于 AP 隔离模式，mDNS 可能无法工作。
IP 兜底： 建议在设备上显示或打印 IP 地址，以便在 mDNS 失败时手动访问。
无额外硬件： 本示例仅需 Wi-Fi，无需其他外设。

03 项目软件流程描述

1. 初始化 NVS 和 Wi-Fi，连接指定网络。

2. 等待 Wi-Fi 获取 IP 地址（WIFI_EVENT_STA_GOT_IP）。

3. 调用 `mdns_init()` 初始化 mDNS 服务。

4. 设置主机名（如 `my-esp32`），确保唯一。

5. 添加服务类型（如 `_http._tcp`）和端口（如 80）。

6. 启动 HTTP 服务器或其他服务，与 mDNS 配合。

7. 在主循环中处理事件，若 Wi-Fi 断开则停止 mDNS，重连后重新启动。

8. 错误处理：若 mDNS 初始化失败，打印错误并回退到 IP 访问。

04 项目核心点

名字必须按设备唯一，否则现场撞名。 建议使用设备 MAC 或序列号作为后缀。
组播被禁则 mDNS 失效，必须提供 IP 直连的备选方案。
不要跨网段使用，mDNS 只在同一局域网内有效。
可定制： 发现协议、与配网门户结合。
注意防火墙，某些系统可能阻止 mDNS 响应。
测试时，确保电脑和手机支持 mDNS（如 macOS、iOS、Windows 10+）。