mDNS Network

fastbeeAbout 4 min

mDNS and Multi-Device Network Access

FastBee Arduino devices use mDNS (Multicast DNS, RFC 6762) to achieve zero-configuration domain access on the local network, allowing users to log in to the device Web management interface without remembering IP addresses.

When multiple FastBee devices connect to the same network, the system automatically detects hostname conflicts and assigns unique domain names, ensuring each device can be accessed independently.

Core Components: DNSManager (include/network/DNSManager.h + src/network/DNSManager.cpp)

How mDNS Works

Service Registration

After mDNS starts, the device broadcasts the following services on the network:

Service Type	Protocol	Port	Purpose
`_http`	TCP	80	Web management interface
`_fastbee`	TCP	80	FastBee device discovery
`_ws`	TCP	81	WebSocket communication

Access Format

http://<hostname>.local

Default hostname is fastbee, so default access address is http://fastbee.local.

Multi-Device Same Network Conflict Handling

When multiple FastBee devices use the same hostname on the same network, the system ensures each device gets a unique domain name through a two-layer mechanism.

Layer 1: Application Layer Retry (DNSManager)

User configures hostname = "fastbee"
        ↓
MDNS.begin("fastbee") successful?
  ├─ Yes → Register as fastbee.local
  └─ No → Append suffix -2, retry MDNS.begin("fastbee-2")
            ├─ Successful → Register as fastbee-2.local
            └─ No → Append suffix -3, retry MDNS.begin("fastbee-3")
                      └─ Successful → Register as fastbee-3.local

Maximum 3 attempts, the actually registered hostname is saved to actualHostname field (queryable via getActualHostname()).

Layer 2: ESP-IDF Low-Level Conflict Detection (RFC 6762)

ESP-IDF built-in mDNS component follows RFC 6762 specification, performing network conflict detection after registering hostname:

If the same hostname already exists on the network, the low-level automatically appends numeric suffix
This mechanism provides additional protection beyond the application layer, no manual UDP probing needed

Note: ESP-IDF 5.5.4 strengthened lwIP TCPIP core lock assertions, prohibiting WiFiUDP::beginMulticast() calls in non-loopTask context, so the project no longer uses manual UDP probing.

Multi-Device Domain Assignment Example

Device #	Configured hostname	Actual registered domain	Access address
1st	`fastbee`	`fastbee`	`http://fastbee.local`
2nd	`fastbee`	`fastbee-2`	`http://fastbee-2.local`
3rd	`fastbee`	`fastbee-3`	`http://fastbee-3.local`

Access Methods for Each Network Mode

WiFi STA Mode (Connect to Router)

Access Method	Address	Condition
mDNS domain	`http://<hostname>.local`	mDNS enabled
LAN IP	`http://<router-assigned-IP>`	Always available

Both mDNS domain and IP can be accessed from any device on the same LAN
Recommended to set different custom domains for each device for easy identification

WiFi AP Mode (Device Self-Hotspot)

Access Method	Address	Condition
AP IP	`http://192.168.4.1`	Always available
mDNS domain	`http://<hostname>.local`	mDNS enabled

User must connect to device WiFi hotspot to access
AP IP is fixed at 192.168.4.1

4G Mode (4G + WiFi AP Hybrid)

4G networking uses a hybrid mode design: 4G provides internet connection, while simultaneously starting WiFi AP hotspot for local configuration access.

4G connection successful → Start WiFi AP (192.168.4.1) → Start mDNS

Access Method	Address	Condition	Access Source
AP hotspot IP	`http://192.168.4.1`	Always available	Connect to device AP hotspot
mDNS domain	`http://<hostname>.local`	mDNS enabled	Connect to device AP hotspot
4G public IP	`http://<carrier-assigned-IP>`	Requires real public IP	Public network (subject to carrier restrictions)

Public IP access limitations:

Most IoT SIM cards assign NAT-ed internal IPs (like 10.x.x.x, 100.x.x.x), not real public IPs
Even with public IP, carriers typically block port 80/443 inbound access
Verification method: Compare device-assigned IP with exit IP from ip.cn; if same, it's real public IP

4G failure fallback: When 4G connection fails, automatically falls back to pure AP mode (192.168.4.1), user can reconfigure via hotspot.

Ethernet Mode (Ethernet + WiFi AP Hybrid)

Similar to 4G, Ethernet also uses hybrid mode: Ethernet provides wired network connection, while simultaneously starting WiFi AP hotspot.

Access Method	Address	Condition	Access Source
Ethernet IP	`http://<ethernet-DHCP-assigned-IP>`	Always available	Devices on Ethernet LAN
AP hotspot IP	`http://192.168.4.1`	Always available	Connect to device AP hotspot
mDNS domain	`http://<hostname>.local`	mDNS enabled	Either interface

Web Server Network Binding

Web server (AsyncWebServer) listens on 0.0.0.0:80, i.e., all network interfaces:

0.0.0.0:80
  ├── WiFi STA interface (router-assigned IP)
  ├── WiFi AP interface (192.168.4.1)
  ├── Ethernet interface (W5500 DHCP-assigned IP)
  └── 4G cellular interface (carrier-assigned IP)

Therefore, in any network mode, all active interface IPs can access the Web management interface.

Custom Domain Configuration

Via Web Management Interface

Login to device → Network configuration page
Find "Advanced Configuration" → "Custom Domain"
Enter new domain (e.g., gateway-01)
After save, mDNS restarts immediately, no need to wait for network restart

Configuration Effective Logic

Scenario	Behavior
mDNS enabled + modify domain	Immediately restart mDNS, new domain takes effect instantly
mDNS disabled	mDNS not started, page prompts to use IP access and shows current IP
4G mode	Domain configuration area hidden in UI, mDNS not started

Multi-Device Naming Recommendations

For easy identification and management, recommended to configure different custom domains for each device:

Device 1: gateway-01.local
Device 2: gateway-02.local
Device 3: sensor-hub.local
Device 4: controller-01.local

Device Discovery

Besides directly entering domain name, FastBee devices on the LAN can also be discovered using mDNS service discovery tools:

macOS / Linux

# Scan for FastBee devices
dns-sd -B _fastbee._tcp local.

Issue	Troubleshooting Direction
Cannot access via `.local` domain	1. Confirm mDNS is enabled 2. Confirm client supports mDNS (Windows needs Bonjour) 3. Check serial log for actual hostname
Multiple devices domain conflict	Check serial log for `actualHostname`, confirm each device's actually registered domain
4G mode cannot remote access	Check if SIM card has public IP, if carrier blocks ports
mDNS intermittent unavailability	Check if network has many mDNS devices causing broadcast storms

File	Description
`include/network/DNSManager.h`	DNS manager header file, defines mDNS management interface
`src/network/DNSManager.cpp`	mDNS start/stop, conflict retry, custom domain implementation
`src/network/NetworkManager.cpp`	Network mode initialization and hybrid mode AP startup
`web-src/modules/runtime/network.js`	Frontend network configuration page, mDNS toggle and domain UI
`test/test_network_config.cpp`	mDNS functionality unit tests (8 test cases)