by martin-ger
An AI-enabled NAT Router/Firewall for the ESP32
# Add to your Claude Code skills
git clone https://github.com/martin-ger/esp32_nat_routerThis is a firmware to use the ESP32 as WiFi NAT router. It routes between the network of the AP interface and the STA or ETH interface as uplink network. It can also work as a VPN router using WireGuard as uplink.
If you have a W32-ET01 board and you are looking for a plain ESP32 Ethernet AP, or correctly for an Ethernet to WiFi Layer 2 Bridge, check out esp32_eth_wifi_bridge. If you are looking for an ESP32 router with reverse direction, i.e. WiFi STA as uplink (Internet) and Ethernet as downlink (LAN), check out esp32_ethernet_router.
Use cases:
No comments yet. Be the first to share your thoughts!
The maximum number of simultaniously connected WiFi clients is 8 (5 on the ESP32c3) due to RAM limitations (uses about 5KB per client). Each of the features: Web Interface, PCAP Capture, Wireguard VPN, Remote Console, WPA Enterprise and MQTT Home Assistant require several KB of additional RAM. So using all of them at once will probably burst the ESP32's ressources. Unused/disabled features are optimized for minimal to no RAM usage. Have a look at remaining heap size if in doubt.
After first boot the ESP32 NAT Router will offer a WiFi network with an open AP and the ssid "ESP32_NAT_Router". Configuration can either be done via a web interface or via the serial console.
Flash directly from your browser — no tools or command line required:
Requires Chrome, Edge, or Opera. Select your firmware variant (WiFi or Ethernet) and click "Connect & Install".
Install esptool and flash using the pre-built binaries from the firmware_* directories. 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).
See the Installation wiki page for all chip-specific commands.
Full documentation is available in the Wiki:
| Page | Description | |------|-------------| | Web Interface | Web UI pages, security, backup/restore | | WiFi and Network | DHCP reservations, port forwarding, WPA2-Enterprise, TTL, DNS | | Firewall | ACL packet filtering rules and configuration | | Packet Capture | PCAP streaming to Wireshark | | WireGuard VPN | VPN tunnel configuration and server setup | | Remote Console | Network-accessible CLI via TCP | | Security | Hardening guide: interface binding, VPN, ACL, credential handling | | MQTT Home Assistant | MQTT telemetry with HA auto-discovery | | MCP Bridge | AI assistant integration via Model Context Protocol | | CLI Reference | Full command listing for the serial/remote console | | Hardware | LED status, OLED display, antenna switch, factory reset | | WT32-ETH01 | Ethernet uplink variant (LAN8720 PHY) | | Installation | Flashing pre-built binaries | | Building | Compiling from source with ESP-IDF or PlatformIO |
idf.py menuconfig # Enable LWIP IP forwarding, NAT, and L2-to-L3 copy
idf.py build
idf.py flash monitor
See the Building wiki page for PlatformIO, WT32-ETH01, and multi-target build instructions.
The performance of the Router depends on several factors, of course including WiFi signal strength and congestion of the used frequencies. Expect something in the range from 5 - 15 mbps under reasonable conditions. Single video streams should be possible, but it is not intended as a 2$ full replacement for a professional home router.
Internally the speed depends on the processing power of the used ESP32 chip (single core vs. dual core, clock speed) and available RAM for buffering. All "hot pathes", i.e. the direct routing of packets are optimized, any additional features, especially VPN, ACL processing, per client statistics, and packet capturing, introduce some delays. If you need maximum speed, dynamically disable all unused features in the configuration. However in default config everything is already disabled, the only major feature, that is running, is the web interface. Especially on the C3 and C5 with small RAM (and combined DRAM and IRAM) disabling it can result in an additional performance boost, due to the additional buffer space. If required, you can re-enable it via the remote console at any time (with a reboot).
The WireGuard submodul has the following licence_
Copyright (c) 2021 Kenta Ida (fuga@fugafuga.org)
The original license is below:
Copyright (c) 2021 Daniel Hope (www.floorsense.nz)
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
* Neither the name of "Floorsense Ltd", "Agile Workspace Ltd" nor the names of
its contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Author: Daniel Hope <daniel.hope@smart