DOCSEARCHbyAlgolia
Submit Docs

ESP32 NAT Router

repository·master·Indexed 22 days ago

https://github.com/martin-ger/esp32_nat_router

Firmware that transforms an ESP32 into a WiFi NAT router, acting as a range extender, VPN gateway, or corporate-to-home WiFi converter. It supports routing between an AP interface and uplinks via STA, Ethernet, or WireGuard VPN. Key features include WPA2-Enterprise support, DHCP reservations, port forwarding, a firewall, PCAP capture, and a password-protected Web UI. Compatible with various chips including ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3, and WT32-ETH01.

Tokens
1.2K
Snippets
2
Records
6
Agent score
35%

What's inside esp32_nat_router

  1. Key Features of ESP32 NAT Router

    master

    The ESP32 NAT Router provides several networking and management features:

    • NAT Routing: Full WiFi NAT router with IP forwarding (15+ Mbps throughput).
    • WireGuard VPN: Optional VPN tunnel for upstream traffic with automatic MSS clamping and Path MTU.
    • DHCP Reservations: Assign fixed IPs to specific MAC addresses.
    • Port Forwarding: Map external ports to internal devices.
    • Firewall: Define ACL to restrict or monitor traffic.
    • PCAP Capture: Live packet capture streamable to Wireshark.
    • WPA2-Enterprise Support: Connect to corporate networks (PEAP, TTLS, TLS) and convert them to WPA2-PSK.
    • 5 GHz WiFi: Dual-band support on ESP32-C5.
    • Ethernet Support: Use a W32-ET01 board with LAN8720 PHY for Ethernet uplink.
    • Web Interface: Password-protected Web UI for configuration.
    • Serial/Remote Console: Full CLI via serial or network-accessible TCP.
    • mDNS: Reachable via esp32-nat-router.local.
    • OTA Updates: Flash new firmware via the Web UI.
    • MQTT Home Assistant: Telemetry and per-client stats with HA auto-discovery.
    • MCP Bridge (BETA): Control the router via Model Context Protocol (AI assistants).

  2. Resource Constraints and Performance

    master

    RAM Limitations

    • The maximum number of simultaneously connected WiFi clients is 8 (or 5 on the ESP32-C3) due to RAM limitations (approx. 5KB per client).
    • Features like Web Interface, PCAP Capture, WireGuard VPN, Remote Console, WPA Enterprise, and MQTT Home Assistant require additional RAM. Using all features simultaneously may exhaust ESP32 resources.
    • Unused/disabled features are optimized for minimal RAM usage.

    Throughput

    • Expect throughput in the range of 5 - 15 Mbps under reasonable conditions.
    • Performance depends on the ESP32 chip (single vs. dual core, clock speed) and available RAM for buffering.
    • Optimization Tip: To achieve maximum speed, dynamically disable all unused features in the configuration. On chips with small RAM (like C3 and C5), disabling the Web Interface can provide a performance boost by freeing up buffer space.

  4. Build the ESP32 NAT Router from Source

    master

    To compile the firmware yourself using the ESP-IDF build system, follow these steps:

    1. Configure the project (ensure LWIP IP forwarding, NAT, and L2-to-L3 copy are enabled via menuconfig):
      idf.py menuconfig
    2. Build the project:
      idf.py build
    3. Flash and monitor:
      idf.py flash monitor

    For PlatformIO, WT32-ETH01, or multi-target build instructions, see the Building wiki page.

    idf.py menuconfig    # Enable LWIP IP forwarding, NAT, and L2-to-L3 copy
idf.py build
idf.py flash monitor

  5. Flash Pre-built Binaries via esptool

    master

    You can flash the firmware manually using esptool.py. This method requires downloading the pre-built binaries from the firmware_* directories in the repository.

    Example for ESP32:

    esptool.py --chip esp32 \
--before default_reset --after hard_reset write_flash \
-z --flash_mode dio --flash_freq 40m --flash_size detect \
0x1000 firmware_esp32/bootloader.bin \
0x8000 firmware_esp32/partition-table.bin \
0xf000 firmware_esp32/ota_data_initial.bin \
0x20000 firmware_esp32/esp32_nat_router.bin

    Pre-built binaries are available for: ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3, and WT32-ETH01 (Ethernet). For chip-specific commands, refer to the Installation wiki page.

  6. First Boot and Initial Configuration

    master

    After the first boot, the ESP32 NAT Router creates an open WiFi access point with the SSID ESP32_NAT_Router. You can configure the router's upstream WiFi and AP settings using either the Web UI or the serial console.

    Steps to configure via Web UI:

    1. Connect your device to the ESP32_NAT_Router WiFi network.
    2. Open http://esp32-nat-router.local (or http://192.168.4.1) in a web browser.
    3. Navigate to the Getting Started page to configure your upstream WiFi and AP settings.
    4. Click Save & Reboot to apply changes.