-
Notifications
You must be signed in to change notification settings - Fork 419
WiFi and Network
To ensure devices behind the router always get the same IP address, you can configure DHCP reservations:
dhcp_reserve add AA:BB:CC:DD:EE:FF 192.168.4.10 -n MyServer
↑ optional friendly name
↑ reserved IP address
↑ device MAC address
This is useful for servers or IoT devices that other devices need to connect to reliably.
You can block specific WiFi clients by MAC address. Blocked clients are immediately deauthenticated when they try to connect to the AP. This reuses the DHCP reservation table with a special IP address of 0.0.0.0 to indicate a blocked client.
Serial Console:
dhcp_reserve block AA:BB:CC:DD:EE:FF -n "Unwanted Device"
Web Interface: On the /mappings page, click the Block button next to a connected client, then submit the form. Blocked entries show BLOCKED in red in the reservations table.
To unblock a client, delete its reservation:
dhcp_reserve del AA:BB:CC:DD:EE:FF
If you want to access a device behind the esp32 NAT router: PC -> local router -> esp32NAT -> server
Let's say "server" is exposing a webserver on port 80 and you want to access that from your PC outside the NAT network.
For that you need to configure a port mapping (via the web interface at /mappings or the serial console):
portmap add TCP 8080 192.168.4.2 80
↑ port of the webserver
↑ server's ip in esp32NAT network
↑ exposed port in the local router's network
Assuming the esp32NAT's IP address in your local router is 192.168.0.57, you can access the server by typing 192.168.0.57:8080 into your browser. Be aware that you can't forward to the routers port 80 as long as the conig webserver runs here. If you absolutly need that, either turn off the web server or recompile the sources with a different config port.
Each port mapping can be bound to either the STA (upstream WiFi) or VPN (WireGuard tunnel) interface. This controls which external IP the mapping is exposed on:
- STA (default): The port is forwarded on the router's upstream WiFi IP. Use this for standard port forwarding.
- VPN: The port is forwarded on the WireGuard tunnel IP. Use this to expose services through the VPN. VPN port mappings are only active while the VPN tunnel is connected.
Via the serial console, append VPN to bind a mapping to the VPN interface:
portmap add TCP 8080 192.168.4.2 80 VPN
Tip: When you assign a name to a DHCP reservation, you can use that name instead of the IP address when creating firewall (ACL) rules. For example, after creating a reservation with -n MyPhone, you can use MyPhone as source or destination in ACL rules.
The ESP32-C5 supports dual-band WiFi (2.4 GHz and 5 GHz). Since the ESP32 operates in AP+STA mode with a single radio, the AP channel always follows the STA channel — there is no independent channel selection.
When connecting to an upstream network that is available on both bands, you can configure a band preference:
| Setting | Behavior |
|---|---|
auto |
Connect to the strongest signal regardless of band (default) |
2.4 |
Prefer 2.4 GHz — longer range, more congested |
5 |
Prefer 5 GHz — higher throughput, shorter range |
The router performs a BSSID-aware connection: it scans for all access points with the configured SSID, filters by the preferred band, and connects to the strongest one. If no APs are found on the preferred band, it falls back to the other band automatically.
Web Interface: On the /config page, a "Band Preference" dropdown appears in the Station Settings section (ESP32-C5 only).
Serial Console:
set_sta_band auto # Auto-select best signal (default)
set_sta_band 2.4 # Prefer 2.4 GHz
set_sta_band 5 # Prefer 5 GHz
set_sta_band # Show current setting
Changes require a restart. The show status and show config commands display the current band and preference on ESP32-C5. The scan command includes a Band column showing 2.4G or 5G for each network.
The router supports connecting to WPA2-Enterprise (802.1X) networks, commonly used in corporate and university environments. This allows the ESP32 to bridge an enterprise network to a standard WPA2-PSK access point.
| Value | Method | Description |
|---|---|---|
| 0 | Auto | Automatic detection (default) |
| 1 | PEAP | Protected EAP (most common in corporate networks) |
| 2 | TTLS | Tunneled TLS |
| 3 | TLS | Certificate-based TLS |
| Value | Method |
|---|---|
| 0 | MSCHAPv2 (default) |
| 1 | MSCHAP |
| 2 | PAP |
| 3 | CHAP |
Web Interface: On the /config page, the Station Settings section includes fields for Enterprise username, identity, EAP method, TTLS Phase 2, and options for CA cert bundle and certificate time check.
Serial Console:
set_sta MyCorpWiFi mypassword -u john.doe -a anonymous -e 1 -p 0 -c 1 -t 1
| Flag | Description |
|---|---|
-u |
Enterprise username |
-a |
Enterprise identity (defaults to username if omitted) |
-e |
EAP method (0=Auto, 1=PEAP, 2=TTLS, 3=TLS) |
-p |
TTLS Phase 2 (0=MSCHAPv2, 1=MSCHAP, 2=PAP, 3=CHAP) |
-c 1 |
Enable CA certificate bundle for server validation |
-t 1 |
Skip certificate time check (useful if device has no RTC) |
All settings are persisted in NVS and applied on next connection.
The AP can be configured to hide its SSID from network scans. When enabled, clients must know the exact SSID to connect.
set_ap_hidden on # Hide the AP SSID
set_ap_hidden off # Show the AP SSID (default)
set_ap_hidden # Show current setting
Changes require a restart to take effect.
Note: Hiding the SSID provides minimal security benefit. The SSID is still transmitted in probe responses and association frames. Use strong WPA2 passwords for actual security.
The router can override the TTL (Time To Live) value in the IP header for all packets sent upstream via the STA interface. This can be useful to:
- Hide the presence of a NAT router from ISPs that detect multiple devices via TTL variations
- Ensure consistent TTL values for all outgoing traffic
set_ttl 64 # Set TTL to 64 for all upstream packets
set_ttl 0 # Disable TTL override (default, no change)
set_ttl # Show current setting
The setting is stored in NVS and takes effect immediately (no restart required).
Note: TTL override only affects packets going to the upstream network (via STA interface). It does not affect traffic between the ESP32 and its connected clients.
By default, the ESP32 identifies itself as "espressif" when requesting an IP address from the upstream network (DHCP Option 12). You can change this to a custom hostname:
set_hostname myrouter # Set hostname to "myrouter"
set_hostname "" # Clear (reverts to default "espressif")
The hostname appears in your upstream router's DHCP client list. Only letters, digits, and hyphens are allowed (max 32 characters). Changes require a restart.
By default, the DNS server distributed to AP clients via DHCP is automatically learned from the upstream WiFi connection. Before the first successful STA connection, 1.1.1.1 is used as a fallback.
You can override this with a custom DNS server that is always used regardless of the upstream:
Web Interface: On the /config page, set the "DNS Server" field in Access Point Settings (leave empty for automatic/upstream DNS).
Serial Console:
set_ap_dns 1.1.1.1 # Use Cloudflare DNS
set_ap_dns 8.8.8.8 # Use Google DNS
set_ap_dns "" # Clear custom DNS (use upstream, default)
The show config command displays the current DNS setting under AP Settings. Changes require a restart to take effect.