mDNS Network

Overview: FastBee 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 devices join the same network, the firmware automatically assigns a unique domain name to each device so that every device can be accessed independently.

mDNS is an independent switch: it can be enabled or disabled in any AP/STA network mode. It is controlled by the Feature Configuration page or by Peripheral Execution rule actions 31 (enable feature) / 32 (disable feature); switch state changes take effect after a reboot. It is enabled by default from the factory.

1. How mDNS Works

1.1. 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

1.2. Access Format

http://<hostname>.local

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

2. Multi-Device Domain Assignment on the Same Network

When multiple FastBee devices are on the same LAN, it is recommended to keep the default naming on all of them (customDomain = fastbee) without renaming each device:

• At startup the firmware enumerates _http._tcp to pre-probe hostnames already in use, and automatically assigns a unique suffix (fastbee, fastbee-2 ... fastbee-8)
• At runtime, same-name convergence runs every 30 seconds (the device with the higher IP yields the name), so new devices are plug-and-play
• The actually registered domain name is determined by the current build, the serial log, and the /api/network/status response (login required); do not infer the automatic suffix from device labels or power-on order
• When a stable name is required, set customDomain on the Network Configuration page, then verify the result via the above interface or the serial log

For fleet verification methods, see Device Testing.

3. Access Methods for Each Network Mode

3.1. WiFi STA Mode (Connect to Router)

Access Method	Address	Condition
LAN IP	http://<router-assigned-IP>	Always available (recommended)
mDNS domain	http://<hostname>.local	mDNS enabled and client supports it

• Both the mDNS domain and the IP can be accessed from any device on the same LAN
• Windows users are advised to use the IP directly: Windows does not ship with full mDNS resolution by default (it relies on components such as Bonjour/iTunes), so fastbee.local may fail intermittently or take several seconds on first resolution, creating the illusion of a "slow page". The IP can be found in the device serial boot log or in the router's DHCP client list

3.2. 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

• The user must connect to the device WiFi hotspot first
• The AP IP is fixed at 192.168.4.1

3.3. 4G Mode (4G + WiFi AP Hybrid)

4G networking uses a hybrid mode design: 4G provides the internet connection while a WiFi AP hotspot is started at the same time 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 a real public IP	Public network (subject to carrier restrictions)

Public IP access limitations:

• Most IoT SIM cards are assigned NAT-ed internal IPs (such as 10.x.x.x, 100.x.x.x), not real public IPs
• Even with a public IP, carriers typically block inbound access on ports 80/443
• Verification method: compare the IP obtained by the device with the exit IP shown by ip.cn; if they match, it is a real public IP

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

3.4. Ethernet Mode (Ethernet + WiFi AP Hybrid)

Similar to 4G, Ethernet also uses a hybrid mode: Ethernet provides the wired network connection while a WiFi AP hotspot is started at the same time.

Access Method	Address	Condition	Access Source
Ethernet IP	http://<ethernet-DHCP-assigned-IP>	Always available	Devices on the 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

4. Web Server Network Binding

The 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, the Web management interface is reachable on the IPs of all active interfaces.

5. Web Access Performance and Loading Mechanism

The built-in Web server applies concurrency and memory protection for the resource-constrained ESP32. Understanding the following mechanisms helps determine whether a "slow page" is normal behavior or a fault:

• Serial first-screen loading: the core JS of the login page is split into 5 boot chunks loaded serially in order (the ESP32 socket pool is limited and concurrent requests are easily rejected). A full first screen typically takes 2-5 seconds, which is normal
• Static resource concurrency limiting: the number of simultaneous static file transfers is capped (2 by default); excess requests wait briefly and then receive a 503, and the frontend automatically retries with incremental backoff of 300/1200/2700ms. Do not open multiple tabs to the same device at the same time, as they compete for connections
• Memory gating: when available memory (DRAM) falls below the threshold, new requests are rejected; in this case wait for background tasks such as MQTT reconnection to finish first. Heavy MQTT and Web traffic should not run at the same time
• Automatic retry on failure: under a weak network, individual chunks that fail to load are retried automatically (up to 4 times); no manual refresh is needed

Troubleshooting suggestions:

1. Prefer direct IP access (see the Windows note above)
2. Close extra browser tabs and network throttling in developer tools
3. Watch the serial log: if the device reboots during Web requests, that is abnormal

6. Custom Domain Configuration

The custom domain (customDomain) is set in "Advanced Configuration → Custom Local Domain" on the Network Configuration page. After saving, mDNS restarts immediately and the new domain takes effect instantly, without waiting for a network restart.

Scenario	Behavior
mDNS enabled + domain modified	mDNS restarts immediately; the new domain takes effect instantly
mDNS disabled	mDNS does not start; the page prompts to use IP access and shows the current IP
4G mode	The domain configuration area is hidden in the UI and mDNS does not start

In multi-device scenarios, it is recommended to keep the default naming and let the firmware assign unique suffixes automatically (see Section 2), rather than renaming each device manually.

7. Device Discovery

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

macOS / Linux:

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

Windows: use Bonjour Browser or an mDNS viewer tool to scan for the _fastbee._tcp service.

Programmatic method: any library supporting mDNS/Bonjour can discover all FastBee devices on the network by querying the _fastbee._tcp service type. The returned results include the device hostname and IP address.

8. Troubleshooting

Issue	Troubleshooting Direction
Cannot access via the .local domain	1. Confirm mDNS is enabled 2. Confirm the client supports mDNS (Windows requires Bonjour) 3. Check the serial log for the actual domain name 4. Use direct IP access instead (most reliable)
.local resolution is slow or fails intermittently (Windows)	Unstable mDNS resolution on Windows is a known phenomenon, not a device fault; using the IP directly eliminates it
Domain conflicts among multiple devices	Check the serial log or /api/network/status (login required) to confirm the actually registered domain of each device
No remote access in 4G mode	Check whether the SIM card is assigned a public IP and whether the carrier blocks the ports
mDNS intermittently unavailable	Check whether a large number of mDNS devices on the network are causing broadcast storms

9. FAQ

Should I use the mDNS domain or direct IP access?

Prefer direct IP access in the field, especially for Windows clients (whose mDNS resolution relies on the Bonjour component and may fail intermittently). The mDNS domain is suitable for zero-configuration access and multi-device discovery on the same LAN, and should not be the only reliable entry point.

Do I need to set a different custom domain for each device?

No. It is recommended to keep the default naming on all devices (customDomain = fastbee). At startup the firmware pre-probes hostnames already in use and assigns a unique suffix automatically, and same-name convergence runs every 30 seconds at runtime. Only set an individual customDomain when a specific device needs a fixed, unchanging domain name.

Do I need to reboot the device after changing the custom domain?

No. After the custom domain is saved, mDNS restarts immediately and the new domain takes effect instantly. However, enabling or disabling the mDNS switch itself takes effect only after a reboot.

Why is the device .local domain unreachable in 4G mode?

In 4G mode the domain configuration area is hidden in the UI and mDNS does not start; in addition, most IoT SIM cards are assigned NAT-ed internal IPs, so the device is not directly reachable from the public network. Connect to the device's WiFi AP hotspot and access it via http://192.168.4.1.

10. Related Files

File	Description
include/network/DNSManager.h	DNS manager header, defines the mDNS management interface
src/network/DNSManager.cpp	mDNS start/stop, domain assignment, and 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, domain configuration UI