### Initial Configuration

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Methods for performing the initial setup of the router via serial console commands.

```bash
set_sta "MyUpstreamWiFi" "mypassword"
set_ap "MyRouterAP" "routerpassword"
restart
```

--------------------------------

### Start WireGuard Server

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Enable and start the WireGuard service on the Linux server.

```bash
# Start and enable on boot
sudo systemctl enable --now wg-quick@wg0

# Verify
sudo wg show
```

--------------------------------

### Setup MCP Bridge for AI Integration

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Installs dependencies and configures the environment to control the router via the Model Context Protocol.

```bash
# Prerequisites
pip install fastmcp telnetlib3

# Router setup - enable remote console with password
set_router_password mypassword
remote_console enable

# Set environment variables
export ESP_NAT_HOST=192.168.4.1
export ESP_NAT_PORT=2323
export ESP_NAT_PASSWORD=mypassword

# Run MCP bridge (stdio mode for Claude Code)
python esp_nat_bridge.py

# Run with HTTP transport
python esp_nat_bridge.py --transport streamable-http --port 8000
```

--------------------------------

### Install WireGuard on Linux

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Install the WireGuard tools on various Linux distributions.

```bash
# Debian/Ubuntu
sudo apt install wireguard

# Fedora
sudo dnf install wireguard-tools

# Arch
sudo pacman -S wireguard-tools
```

--------------------------------

### Install esptool and pyserial

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Install the esptool utility and its Python dependency. This is required for manual flashing.

```bash
cd ~
python3 -m pip install pyserial
git clone https://github.com/espressif/esptool
cd esptool
python3 setup.py install
```

--------------------------------

### Install WireGuard on Linux

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Installs the WireGuard package on Debian/Ubuntu or Fedora systems.

```bash
sudo apt install wireguard    # Debian/Ubuntu
```

```bash
sudo dnf install wireguard-tools    # Fedora
```

--------------------------------

### Run the MCP Bridge

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MCP-Bridge

Start the bridge using either stdio mode for local clients or HTTP transport.

```bash
# stdio mode (for MCP clients like Claude Code)
python esp_nat_bridge.py

# HTTP transport
python esp_nat_bridge.py --transport streamable-http --port 8000
```

--------------------------------

### Get System Version

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Retrieves the version information for the ESP32 chip and the SDK it is running on.

```bash
version
```

--------------------------------

### MQTT Payload Examples

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

JSON structures for router telemetry and per-client statistics.

```json
{
  "uplink": "ON",
  "clients": 3,
  "bytes_tx": 1048576,
  "bytes_rx": 2097152,
  "free_heap": 120000,
  "uptime": 3600,
  "rssi": -52,
  "ssid": "MyNetwork",
  "web_ui": "ON",
  "remote_console": "OFF",
  "ap_enabled": "ON"
}
```

```json
{
  "present": "ON",
  "tx": 524288,
  "rx": 1048576,
  "rssi": -45
}
```

--------------------------------

### Syslog Message Format Example

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Syslog

Example of an RFC 3164 formatted log message.

```text
<134>Mar  9 14:23:01 myrouter I (12345) wifi: connected to AP
```

--------------------------------

### Install MCP Bridge Dependencies

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MCP-Bridge

Install the required Python packages for the MCP bridge.

```bash
pip install fastmcp telnetlib3
```

--------------------------------

### Get Help for CLI Commands

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Use the 'help' command to view a summary of all registered commands or detailed help for a specific command. The verbose flag can list commands by their verbose level.

```bash
help  [<string>] [-v <0|1>]
```

--------------------------------

### Allow Specific Protocols/Ports

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Firewall

Examples of adding rules to allow DNS (UDP port 53), HTTP (TCP port 80), and HTTPS (TCP port 443) traffic from clients to the internet.

```bash
# Allow only DNS and HTTP/HTTPS from clients to Internet
acl add to_ap UDP any * any 53 allow
acl add to_ap TCP any * any 80 allow
acl add to_ap TCP any * any 443 allow
```

--------------------------------

### Register ESP32 Component

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/components/http_server/CMakeLists.txt

Registers the HTTP server component with its source files, include directories, and required dependencies. This setup is crucial for building the ESP-IDF project.

```cmake
idf_component_register(
    SRCS "http_server.c"
    INCLUDE_DIRS "include"
    PRIV_REQUIRES esp_http_server esp_wifi esp_netif esp_event nvs_flash
                  esp_timer json cmd_router acl pcap_capture
                  remote_console dhcpserver wpa_supplicant
                  app_update esp_app_format
)
target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-function)
```

--------------------------------

### Configure Logging Level

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Set or get the logging level for the system or specific tags. Levels range from none (0) to verbose (5).

```bash
log_level  [<level>] [-t <tag>]
```

--------------------------------

### Connect Wireshark via Netcat

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Packet-Capture

Stream PCAP data to Wireshark using netcat. Ensure Wireshark is installed and accessible from your terminal.

```bash
nc <ESP32's IP address> 19000 | wireshark -k -i -
```

--------------------------------

### Block Specific Device by Name

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Firewall

Example of adding a rule to the 'from_ap' ACL to deny traffic from a device identified by its name in DHCP reservations.

```bash
# Block a specific device by name (from DHCP reservation)
acl add from_ap IP any * MyPhone * deny
```

--------------------------------

### Enable MQTT Integration

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

Activate the MQTT service to begin publishing discovery configurations.

```text
mqtt enable
```

--------------------------------

### Flash pre-built binaries

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WT32-ETH01

Use esptool.py to manually write the bootloader, partition table, and firmware binaries to the ESP32.

```bash
esptool.py --chip esp32 \
--before default_reset --after hard_reset write_flash \
-z --flash_mode dio --flash_freq 40m --flash_size detect \
0x1000 firmware_wt32_eth01/bootloader.bin \
0x8000 firmware_wt32_eth01/partition-table.bin \
0x10000 firmware_wt32_eth01/esp32_nat_router.bin
```

--------------------------------

### Flash and monitor the device

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WT32-ETH01

Flash the compiled firmware to the device and open the serial monitor.

```bash
idf.py -B build_eth -p /dev/ttyUSB0 flash monitor
```

--------------------------------

### Build and Flash ESP32 Project

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Building

Compile the project and flash it to the ESP32. The `monitor` command opens a serial terminal to view output.

```bash
idf.py build
idf.py flash monitor

```

--------------------------------

### Configure Hardware Peripherals

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Control status LEDs, addressable LED strips, OLED displays, and antenna switching.

```bash
# Set GPIO for status LED
set_led_gpio 2
set_led_gpio none    # Disable

# Set LED to low-active mode (for active-low LEDs)
set_led_lowactive on
set_led_lowactive off

# Set GPIO for addressable LED strip (WS2812/SK6812)
set_led_strip 8
set_led_strip none    # Disable

# Enable/disable OLED display (ESP32-C3/S3 only)
set_oled enable
set_oled disable
set_oled            # Show status

# Set I2C pins for OLED (ESP32-C3/S3 only)
set_oled_gpio 5 6   # SDA=5, SCL=6

# Switch antenna on XIAO ESP32-C6
set_rf_switch_XIAO 0    # Built-in ceramic antenna
set_rf_switch_XIAO 1    # External antenna
```

--------------------------------

### Integrate with MQTT and Home Assistant

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Configures MQTT broker settings, publishing intervals, and Home Assistant auto-discovery for router telemetry.

```bash
# Configure MQTT broker
mqtt broker mqtt://192.168.1.100:1883

# Set broker credentials (if required)
mqtt user myuser mypassword

# Enable MQTT publishing
mqtt enable

# Set publish interval (5-3600 seconds)
mqtt interval 30

# Show MQTT status
mqtt status

# Re-publish HA discovery configs (after adding new clients)
mqtt rediscover

# Disable MQTT
mqtt disable

# Add client for per-device tracking in HA
dhcp_reserve add AA:BB:CC:DD:EE:FF 192.168.4.100 -n MyPhone
mqtt rediscover
```

--------------------------------

### Build and Monitor Commands

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/CLAUDE.md

Commands for building and managing the firmware on the ESP32 device.

```bash
idf.py menuconfig      # Configure build options
idf.py build           # Build the project
idf.py flash           # Flash to device
idf.py monitor         # Watch serial output (115200 bps)
idf.py flash monitor   # Flash and monitor combined
```

```bash
pio run                # Build
pio run -t upload      # Flash
pio device monitor     # Serial monitor
```

--------------------------------

### MQTT CLI Commands

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

Reference for managing MQTT settings and status via the command line.

```text
mqtt status                        # Show MQTT status, broker, and interval
mqtt enable                        # Enable and start MQTT publishing
mqtt disable                       # Disable and disconnect
mqtt broker <uri>                  # Set broker URI (e.g. mqtt://host:1883)
mqtt user <username> <password>    # Set broker credentials
mqtt interval <seconds>            # Set publish interval (5-3600)
mqtt rediscover                    # Re-publish HA discovery configs
```

--------------------------------

### Deny All Other Traffic

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Firewall

Example of adding a rule to the 'from_esp' ACL to deny all other IP traffic not explicitly allowed by previous rules.

```bash
acl add from_esp IP any * any * deny
```

--------------------------------

### Configure Web Interface

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Commands to toggle the web UI, change the server port, and manage password protection.

```bash
# Enable/disable web interface
web_ui enable
web_ui disable
web_ui             # Show current status

# Set web server port (default: 80)
web_ui port 8080

# Set password for web interface and remote console
set_router_password mypassword

# Remove password protection
set_router_password ""
```

--------------------------------

### Build All ESP32 Targets

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Building

Execute the provided script to automate the building process for multiple ESP32 targets.

```bash
./build_all_targets.sh

```

--------------------------------

### Configure WireGuard Server

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Sets up the WireGuard interface configuration and enables the service on the host machine.

```bash
cat > /etc/wireguard/wg0.conf << 'EOF'
[Interface]
PrivateKey = <server_private_key>
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE; sysctl -w net.ipv4.ip_forward=1
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
# ESP32 NAT Router
PublicKey = <esp32_public_key>
# PresharedKey = <preshared_key>
AllowedIPs = 10.0.0.2/32, 192.168.4.0/24
EOF

# Start WireGuard server
sudo systemctl enable --now wg-quick@wg0
sudo ufw allow 51820/udp

# Verify connection
sudo wg show
```

--------------------------------

### ACL Monitor Rules for PCAP

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Packet-Capture

Examples of ACL rules to selectively capture traffic for monitoring. Use 'allow_monitor' to flag packets for capture in ACL mode.

```bash
# Capture all DNS queries going to the Internet (for debugging)
acl add from_esp UDP any * any 53 allow_monitor
```

```bash
# Capture specific client's traffic without blocking (by IP)
acl add to_ap IP 192.168.4.100 * any * allow_monitor
```

```bash
# Capture specific client's traffic using device name
acl add to_ap IP MyPhone * any * allow_monitor
```

--------------------------------

### Build the Ethernet variant

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WT32-ETH01

Use the ESP-IDF build system to compile the firmware with the specific WT32-ETH01 configuration defaults.

```bash
idf.py -B build_eth -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.defaults.wt32_eth01' build
```

--------------------------------

### Block Incoming Traffic from Specific IP

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Firewall

Example of adding a rule to the 'to_esp' ACL to deny all incoming IP traffic from a specific source IP address.

```bash
# Block incoming traffic from a specific IP
acl add to_esp IP 203.0.113.50 * any * deny
```

--------------------------------

### Build Firmware from Source

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Commands to compile the firmware using the ESP-IDF toolchain for standard and Ethernet-enabled targets.

```bash
idf.py set-target esp32    # or esp32c3, esp32c5, esp32c6, esp32s3
idf.py build
idf.py flash monitor
```

```bash
idf.py -B build_eth -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.defaults.wt32_eth01' build
idf.py -B build_eth -p /dev/ttyUSB0 flash monitor
```

```bash
./build_all_targets.sh
```

--------------------------------

### Build all targets

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WT32-ETH01

Execute the multi-target build script to automatically include the Ethernet variant.

```bash
./build_all_targets.sh
```

--------------------------------

### Hardware and LED Configuration

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands for configuring hardware components like LEDs and OLED displays.

```APIDOC
## Hardware & LED

### `set_led_gpio` command

**Description**: Configures the GPIO pin used for the status LED. Use 'none' to disable the LED.

**Usage**: `set_led_gpio [<gpio_number> | none]`

**Parameters**:
- `<gpio_number>` (integer): The GPIO pin number to use for the status LED.
- `none`: Disables the status LED.

### `set_led_lowactive` command

**Description**: Configures the LED to operate in low-active (inverted) mode, suitable for active-low LEDs.

**Usage**: `set_led_lowactive`

### `set_led_strip` command

**Description**: Configures the GPIO pin for an addressable LED strip (WS2812/SK6812). Requires a restart to apply changes.

**Usage**: `set_led_strip <gpio_number | none>`

**Parameters**:
- `<gpio_number>` (integer): The GPIO pin number for the WS2812 data line (0-48).
- `none`: Disables the addressable LED strip (default).

Without arguments, this command displays the current setting.

### `set_oled` command

**Description**: Enables or disables the OLED display. This feature is supported on ESP32-C3 and ESP32-S3. Changes take effect after a reboot.

**Usage**: `set_oled <enable | disable>`

**Parameters**:
- `enable`: Enables the OLED display.
- `disable`: Disables the OLED display.

Without arguments, this command displays the current status of the OLED display.

### `set_oled_gpio` command

**Description**: Sets the I2C GPIO pins (SDA and SCL) for the OLED display. This configuration is supported on ESP32-C3 and ESP32-S3 and requires a restart to take effect.

**Usage**: `set_oled_gpio <sda> <scl>`

**Parameters**:
- `<sda>` (integer): The GPIO number for the SDA pin (0-48).
- `<scl>` (integer): The GPIO number for the SCL pin (0-48).

Without arguments, this command displays the current pin assignment for the OLED display.

### `set_rf_switch_XIAO` command

**Description**: For XIAO ESP32-C6 boards only. Switches between the built-in ceramic antenna (0) and an external antenna (1). This setting is saved to NVS and applied on every boot. It utilizes GPIO3 (RF switch enable) and GPIO14 (antenna select).

**Usage**: `set_rf_switch_XIAO <0 | 1>`

**Parameters**:
- `0`: Selects the built-in ceramic antenna (default).
- `1`: Selects the external antenna.
```

--------------------------------

### Configure ESP32 via CLI

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Apply VPN settings to the ESP32 using the CLI with specific flags.

```bash
set_vpn <esp32_private_key> <server_public_key> <server_ip> 10.0.0.2 -p 51820 -a 25 -e 1
```

--------------------------------

### Configure Router for Test Server

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Syslog

Points the router to the local machine for testing.

```text
syslog enable <your-pc-ip> 5140
```

--------------------------------

### Configure WireGuard Server

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Create the wg0.conf file on the Linux server to define the interface and peer settings.

```ini
[Interface]
PrivateKey = <contents of server_private.key>
Address = 10.0.0.1/24
ListenPort = 51820

# Enable IP forwarding and NAT for client traffic
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE; sysctl -w net.ipv4.ip_forward=1
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
# ESP32 NAT Router
PublicKey = <contents of esp32_public.key>
# PresharedKey = <contents of preshared.key>    # optional
AllowedIPs = 10.0.0.2/32, 192.168.4.0/24
```

--------------------------------

### Manage Network Settings

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Adjust TTL, DHCP hostnames, transmission power, timezones, and byte counters via the CLI.

```bash
# Override TTL for upstream packets (hide NAT from ISP)
set_ttl 64
set_ttl 0          # Disable (default)
set_ttl            # Show current

# Set DHCP hostname (appears in upstream router's client list)
set_hostname myrouter
set_hostname ""    # Clear (default: "espressif")

# Set WiFi TX power in dBm (2-20, 0 = max/default)
set_tx_power 15
set_tx_power 0     # Max power

# Set timezone (POSIX TZ string)
set_tz "CET-1CEST,M3.5.0/2,M10.5.0/3"    # Central Europe
set_tz "EST5EDT,M3.2.0,M11.1.0"           # US Eastern
set_tz "PST8PDT,M3.2.0,M11.1.0"           # US Pacific
set_tz "JST-9"                             # Japan (no DST)
set_tz clear                               # Revert to UTC
set_tz                                     # Show current

# Show/reset byte counters
bytes
bytes reset
```

--------------------------------

### Configure MQTT Broker

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

Set the MQTT broker URI and optional authentication credentials.

```text
mqtt broker mqtt://192.168.1.100:1883
```

```text
mqtt user myuser mypassword
```

--------------------------------

### MQTT Configuration Commands

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

Commands to configure the MQTT broker connection and enable the integration.

```APIDOC
## MQTT Configuration

### Description
Configure the MQTT broker URI, credentials, and enable the integration.

### Commands
- `mqtt broker <uri>` - Set broker URI (e.g., mqtt://192.168.1.100:1883)
- `mqtt user <username> <password>` - Set broker credentials
- `mqtt enable` - Enable and start MQTT publishing
- `mqtt interval <seconds>` - Set publish interval (5-3600s)
```

--------------------------------

### Configure VPN via CLI

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Use the set_vpn command to configure VPN parameters. Settings are persisted in NVS and applied after a restart.

```bash
set_vpn <your_private_key> <peer_public_key> <endpoint_ip> <tunnel_ip> -e 1
```

--------------------------------

### Add Client for Tracking

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

Reserve a DHCP address and trigger a rediscovery to add a client to Home Assistant.

```text
dhcp_reserve add AA:BB:CC:DD:EE:FF 192.168.4.100 -n MyPhone
mqtt rediscover
```

--------------------------------

### System and Diagnostics CLI Commands

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Commands for monitoring system health, managing power states, and testing network connectivity.

```bash
show status
show config
version
heap
tasks
ping 8.8.8.8 -c 5 -i 1000 -W 1000 -s 64
factory_reset
restart
deep_sleep -t 60000
deep_sleep --io=0 --io_level=0
```

--------------------------------

### Conditional MQTT Home Assistant Source

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/components/mqtt_ha/CMakeLists.txt

Conditionally sets the source file for MQTT Home Assistant integration based on configuration. Requires the MQTT component to be enabled.

```cmake
if(CONFIG_MQTT_HOMEASSISTANT)
    set(MQTT_HA_SRCS "mqtt_ha.c")
else()
    set(MQTT_HA_SRCS "")
endif()
```

--------------------------------

### Show DHCP and Port Forward Mappings

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Displays current DHCP reservations and active port forwarding configurations.

```bash
show mappings
```

--------------------------------

### Flash Firmware via esptool

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Commands to flash the NAT router firmware to various ESP32 hardware targets using the esptool utility.

```bash
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
```

```bash
esptool.py --chip esp32c3 \
--before default_reset --after hard_reset write_flash \
-z --flash_size detect \
0x0 firmware_esp32c3/bootloader.bin \
0x8000 firmware_esp32c3/partition-table.bin \
0xf000 firmware_esp32c3/ota_data_initial.bin \
0x20000 firmware_esp32c3/esp32_nat_router.bin
```

```bash
esptool.py --chip esp32c5 \
--before default_reset --after hard_reset write_flash \
-z --flash_size detect \
0x2000 firmware_esp32c5/bootloader.bin \
0x8000 firmware_esp32c5/partition-table.bin \
0xf000 firmware_esp32c5/ota_data_initial.bin \
0x20000 firmware_esp32c5/esp32_nat_router.bin
```

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

--------------------------------

### Console Output Configuration

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Instructions on how to configure the console output to use the USB Serial/JTAG Controller instead of UART.

```APIDOC
## Console Output: UART vs USB Serial/JTAG

Newer ESP32 boards feature a built-in USB Serial/JTAG Controller. If this controller is connected via USB, the console output might not be available over UART.

### Configuring Console Output:

**Using Menuconfig:**
Navigate to `Component config` → `ESP System Settings` → `Channel for console output` and select `USB Serial/JTAG Controller`.

**Directly Modifying `sdkconfig`:**
Set the following options in your `sdkconfig` file:
```
CONFIG_ESP_CONSOLE_UART_DEFAULT=n
CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y
```
```

--------------------------------

### Required SDK Configuration

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/CLAUDE.md

These settings must be defined in sdkconfig.defaults to enable NAT and IP forwarding functionality.

```text
CONFIG_LWIP_IP_FORWARD=y    # Enable IP forwarding
CONFIG_LWIP_IPV4_NAPT=y     # Enable NAT (code won't compile without this)
CONFIG_LWIP_L2_TO_L3_COPY=y # LWIP layer support
```

--------------------------------

### Verify Connection on Server

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Check the connection status on the server side.

```bash
sudo wg show
```

--------------------------------

### Configure Remote Console Interface Binding

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Remote-Console

Specify which network interfaces the remote console should listen on. Options include AP (Access Point), STA (Station), and VPN. Multiple interfaces can be selected by comma-separation.

```bash
remote_console bind <ap,sta,vpn>
```

--------------------------------

### Enable Syslog Forwarding

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Syslog

Configures the remote syslog server and optional port.

```text
syslog enable <server> [<port>]
```

```text
syslog enable 192.168.4.100          # Default port 514
syslog enable syslog.local 1514      # Custom port
```

--------------------------------

### Build ESP32 NAT Router Firmware

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/README.md

Commands to configure, build, flash, and monitor the ESP32 NAT Router firmware using the ESP-IDF build system. Ensure LWIP IP forwarding, NAT, and L2-to-L3 copy are enabled in menuconfig.

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

--------------------------------

### Configure and Enable WireGuard VPN

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Sets up and enables a WireGuard VPN tunnel with essential parameters: private key, peer public key, endpoint IP, local tunnel IP, and optional port, keepalive, and enable flag.

```bash
set_vpn <your_private_key> <peer_public_key> <endpoint_ip> 10.0.0.2 -p 51820 -a 25 -e 1
```

--------------------------------

### Project Source Structure

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/CLAUDE.md

Directory layout of the main source code and include files.

```text
main/
├── esp32_nat_router.c   # Entry point: WiFi init, event handling, LED status
├── dhcp_manager.c       # DHCP reservation management (add/del/lookup/print)
├── netif_hooks.c        # Network interface hooks for byte counting and ACL
├── portmap.c            # Port mapping table management
└── vpn_manager.c        # VPN/WireGuard configuration and management

include/
├── router_globals.h     # Global variables and shared state
├── router_config.h      # NVS namespace and config constants
├── dhcp_reservations.h  # DHCP reservation API
├── portmap.h            # Port mapping API
├── vpn_config.h         # VPN configuration structures
├── web_password.h       # Web password hashing API
└── wifi_config.h        # WiFi config parameter helpers

components/
├── acl/                 # Stateless packet filtering firewall (4 ACL lists, 16 rules each)
├── dhcpserver/          # Custom DHCP server with reservation support (overrides ESP-IDF built-in)
├── http_server/         # Web UI server at 192.168.4.1 (pages: /, /config, /mappings, /firewall)
├── oled_display/        # Optional OLED display support
├── pcap_capture/        # PCAP packet capture with TCP streaming to Wireshark
├── remote_console/      # Network-accessible CLI via TCP (password protected)
├── cmd_router/          # CLI commands: set_sta, set_ap, portmap, dhcp_reserve, web_ui, set_web_password, show, acl, remote_console
└── cmd_system/          # System commands: free, heap, restart, factory_reset, tasks
```

--------------------------------

### Flash ESP32-C5 Firmware with esptool

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Use esptool to flash the ESP32 NAT Router firmware onto the ESP32-C5 chip. Ensure you are in the project directory and use the correct firmware files.

```bash
esptool.py --chip esp32c5 \
--before default_reset --after hard_reset write_flash \
-z --flash_size detect \
0x2000 firmware_esp32c5/bootloader.bin \
0x8000 firmware_esp32c5/partition-table.bin \
0xf000 firmware_esp32c5/ota_data_initial.bin \
0x20000 firmware_esp32c5/esp32_nat_router.bin
```

--------------------------------

### Display Running Task Information

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Provides information about the tasks currently running on the ESP32.

```bash
tasks
```

--------------------------------

### Flash WT32-ETH01 Firmware with esptool

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Use esptool to flash the ESP32 NAT Router firmware onto the WT32-ETH01 board. Ensure you are in the project directory and use the correct firmware files.

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

--------------------------------

### System Management

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands for packet capture, web interface management, and remote console access.

```APIDOC
## System Management

### Packet Capture
- **pcap <action> [<mode>] [<bytes>]** - Control PCAP packet capture.

### Web Interface
- **web_ui <enable|disable|port>** - Manage the web interface.
- **set_router_password** - Set router password.

### Remote Console
- **remote_console <action> [<args>]** - Manage remote console (network CLI access).
```

--------------------------------

### Generate WireGuard Keys

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Generate private and public keys for the server and the ESP32 client, along with an optional preshared key.

```bash
# Server keys
wg genkey | tee server_private.key | wg pubkey > server_public.key

# ESP32 client keys
wg genkey | tee esp32_private.key | wg pubkey > esp32_public.key

# Optional: preshared key for extra security
wg genpsk > preshared.key
```

--------------------------------

### Flash ESP32-C6 Firmware with esptool

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Use esptool to flash the ESP32 NAT Router firmware onto the ESP32-C6 chip. Ensure you are in the project directory and use the correct firmware files.

```bash
esptool.py --chip esp32c6 \
--before default_reset --after hard_reset write_flash \
-z --flash_size detect \
0x0 firmware_esp32c6/bootloader.bin \
0x8000 firmware_esp32c6/partition-table.bin \
0xf000 firmware_esp32c6/ota_data_initial.bin \
0x20000 firmware_esp32c6/esp32_nat_router.bin
```

--------------------------------

### Build WT32-ETH01 Ethernet Variant

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Building

Build the firmware for the WT32-ETH01 board using Ethernet as the upstream connection. This command specifies default configuration files for the Ethernet build.

```bash
idf.py -B build_eth -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.defaults.wt32_eth01' build

```

--------------------------------

### Open Firewall Port

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Allow UDP traffic on the WireGuard port using UFW.

```bash
sudo ufw allow 51820/udp
```

--------------------------------

### Flash ESP32-C3 Firmware with esptool

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Use esptool to flash the ESP32 NAT Router firmware onto the ESP32-C3 chip. Ensure you are in the project directory and use the correct firmware files.

```bash
esptool.py --chip esp32c3 \
--before default_reset --after hard_reset write_flash \
-z --flash_size detect \
0x0 firmware_esp32c3/bootloader.bin \
0x8000 firmware_esp32c3/partition-table.bin \
0xf000 firmware_esp32c3/ota_data_initial.bin \
0x20000 firmware_esp32c3/esp32_nat_router.bin
```

--------------------------------

### Check VPN Status

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN

Verify the current status of the VPN connection.

```bash
show vpn
```

--------------------------------

### Configure Status LED GPIO

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Hardware

Sets the GPIO pin for the status LED. Changes require a device restart to take effect.

```shell
set_led_gpio 2          # Set LED to GPIO 2
set_led_gpio none       # Disable LED (default)
set_led_gpio            # Show current setting
```

--------------------------------

### Set OLED Display GPIO Pins

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Configure the I2C SDA and SCL GPIO pins for the OLED display on ESP32-C3 and ESP32-S3. Requires a restart.

```bash
set_oled_gpio  <sda> <scl>
```

--------------------------------

### Flash ESP32 Firmware with esptool

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Use esptool to flash the ESP32 NAT Router firmware onto the ESP32 chip. Ensure you are in the project directory and use the correct firmware files.

```bash
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
```

--------------------------------

### Logging Configuration

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands to manage system logging levels and remote syslog forwarding.

```APIDOC
## Logging

### `log_level` command

**Description**: Get or set the logging level for the system or specific tags. Without arguments, it displays the usage instructions.

**Usage**: `log_level [<level>] [-t <tag>]`

**Parameters**:
- `<level>` (string): The desired log level. Accepted values are `none`, `error`, `warn`, `info`, `debug`, `verbose`, or their corresponding numeric values (0-5).
- `-t, --tag=<tag>` (string): Optional. Specifies a tag to set the log level for a particular component or module.

### `syslog` command

**Description**: Manage remote syslog forwarding to a server.

**Usage**: `syslog <action> [<args>]`

**Actions**:
- `status`: Displays the current syslog configuration.
- `enable <server> [<port>]`: Enables syslog forwarding to the specified server. An optional port can be provided; defaults to 514.
- `disable`: Disables syslog forwarding.
```

--------------------------------

### Set LED Mode

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Configure the status LED to operate in low-active (inverted) mode, suitable for active-low LEDs.

```bash
set_led_lowactive
```

--------------------------------

### ESP32 NAT Router CMakeLists Boilerplate

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/CMakeLists.txt

This boilerplate must be included in your project's CMakeLists.txt in the specified order for the build system to function correctly. It sets up the project version, includes necessary IDF build tools, and ensures the application descriptor recompiles on every build to keep timestamps current.

```cmake
cmake_minimum_required(VERSION 3.16)

set(PROJECT_VER "2.4.6")
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(esp32_nat_router)

# Force esp_app_desc.c to recompile on every build so that
# __DATE__/__TIME__ in the app descriptor stay current.
set(APP_DESC_OBJ "${CMAKE_BINARY_DIR}/esp-idf/esp_app_format/CMakeFiles/__idf_esp_app_format.dir/esp_app_desc.c.obj")
add_custom_target(force_app_desc_rebuild ALL
    COMMAND ${CMAKE_COMMAND} -E remove -f "${APP_DESC_OBJ}"
    COMMENT "Ensuring app descriptor timestamp is current"
)
add_dependencies(${PROJECT_NAME}.elf force_app_desc_rebuild)
```

--------------------------------

### Network Settings Configuration

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands for configuring network-related parameters such as hostname, TTL, and WiFi transmission power.

```APIDOC
## Network Settings

### `set_hostname` command

**Description**: Sets the DHCP client hostname for the upstream network. An empty value reverts to the default hostname.

**Usage**: `set_hostname <name>`

**Parameters**:
- `<name>` (string): The desired hostname. Must consist of letters, digits, and hyphens, with a maximum length of 32 characters.

### `set_ttl` command

**Description**: Sets the Time-To-Live (TTL) override for upstream STA packets. A value of 0 disables this feature.

**Usage**: `set_ttl`

### `set_tx_power` command

**Description**: Sets the WiFi transmission power in dBm. Values are saved and applied immediately, and also persist across reboots. Setting to 0 reverts to maximum power on the next restart.

**Usage**: `set_tx_power <dBm>`

**Parameters**:
- `<dBm>` (integer): The desired TX power in dBm. Accepted values are 2, 5, 7, 8, 11, 13, 14, 15, 16, 18, 20. A value of 0 indicates maximum/default power.

Without arguments, this command displays the current and saved TX power settings.

### `set_tz` command

**Description**: Sets the system timezone using POSIX TZ strings. This setting affects syslog timestamps and other time-related displays, and is persisted in NVS.

**Usage**: `set_tz [<TZ string> | clear]`

**Parameters**:
- `<TZ string>` (string): A POSIX TZ string defining the timezone (e.g., `CET-1CEST,M3.5.0/2,M10.5.0/3`).
- `clear`: Clears the current timezone setting, reverting to UTC.

Without arguments, this command displays the current timezone setting.
```

--------------------------------

### Show Router Status and Information

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Displays various router information including status, configuration, mappings, ACL rules, VPN details, or OTA status. The 'status' option provides uptime, connection details, IPs, byte counts, AP state, and connected clients.

```bash
show  [status|config|mappings|acl|vpn|ota]
```

--------------------------------

### System & Diagnostics Commands

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands for managing system state, diagnostics, and power modes.

```APIDOC
## System Commands

### Description
Commands to manage system operations, diagnostics, and power states.

### Commands
- **help [<string>] [-v <0|1>]** - Print command summaries or verbose details.
- **version** - Get chip and SDK version.
- **restart** - Software reset of the chip.
- **factory_reset** - Erase all settings (NVS namespace 'esp32_nat') and restart.
- **heap** - Get current and total free heap memory.
- **tasks** - Get information about running tasks.
- **ping <host> [-c <n>] [-i <ms>] [-W <ms>] [-s <bytes>]** - Send ICMP echo requests.
- **deep_sleep [-t <t>] [--io=<n>] [--io_level=<0|1>]** - Enter deep sleep mode.
- **light_sleep [-t <t>] [--io=<n>]... [--io_level=<0|1>]...** - Enter light sleep mode.
```

--------------------------------

### Set Addressable LED Strip GPIO

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Configure the GPIO pin for an addressable LED strip (WS2812/SK6812). Use 'none' to disable. Requires a restart to apply changes.

```bash
set_led_strip  <gpio_number|none>
```

--------------------------------

### Full WireGuard VPN Configuration

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Provides a comprehensive WireGuard VPN configuration including preshared key, tunnel netmask, peer port, keepalive, enable flag, kill switch, and routing options.

```bash
set_vpn <private_key> <public_key> vpn.example.com 10.0.0.2 \
  -k <preshared_key> \
  -m 255.255.255.0 \
  -p 51820 \
  -a 25 \
  -e 1 \
  -K 1 \
  -R 1
```

--------------------------------

### Configure Bridge Environment Variables

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MCP-Bridge

Set environment variables to define the connection parameters for the router.

```bash
export ESP_NAT_HOST=192.168.4.1     # Router IP address (default)
export ESP_NAT_PORT=2323            # Remote console port (default)
export ESP_NAT_PASSWORD=mypassword  # Remote console password
```

--------------------------------

### Configure Station Enterprise Authentication

Source: https://github.com/martin-ger/esp32_nat_router/wiki/WiFi-and-Network

Sets up enterprise authentication for the station interface. Use flags to specify username, identity, EAP method, TTLS Phase 2, and certificate validation options. Settings are persisted in NVS.

```bash
set_sta MyCorpWiFi mypassword -u john.doe -a anonymous -e 1 -p 0 -c 1 -t 1
```

--------------------------------

### Factory Reset via Serial Console

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Hardware

Use the 'factory_reset' command in the serial console to reset the device to its factory defaults. This method is non-destructive to the firmware.

```text
factory_reset
```

--------------------------------

### Analyze PCAP with Zeek via Docker

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Packet-Capture

Pipe PCAP data to Zeek for analysis using Docker. This command sets up a Zeek container and processes the incoming stream.

```bash
mkdir zeek_logs && chmod 777 zeek_logs
nc <ESP32's IP address> 19000 | docker run --rm -i -v $(pwd)/zeek_logs:/logs -w /logs zeek/zeek:latest zeek -r -
```

--------------------------------

### Test Syslog with Netcat

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Syslog

Listens for incoming UDP syslog packets on a specified port.

```bash
nc -u -l 514
```

```bash
nc -u -l 5140
```

--------------------------------

### Serial Console Commands

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/CLAUDE.md

A comprehensive list of commands available via the serial console (115200 bps) for configuring WiFi, port mapping, DHCP reservations, and firewall rules.

```APIDOC
## Serial Console Commands

### Description
Commands to manage router configuration, network settings, and firewall rules via serial interface.

### Commands
- **set_sta <ssid> <passwd>** - Set upstream WiFi credentials.
- **set_sta_static <ip> <subnet> <gw>** - Set static IP for STA interface.
- **set_ap <ssid> <passwd>** - Configure AP hotspot credentials.
- **portmap add TCP <ext_port> <int_ip> <int_port>** - Add a TCP port mapping.
- **dhcp_reserve add <mac> <ip> [-n <name>]** - Add a DHCP reservation.
- **acl add <list> <proto> <src> <sport> <dst> <dport> <action>** - Add an ACL firewall rule.
- **show status** - Display current router connection and client status.
```

--------------------------------

### Enable Remote Console on Router

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MCP-Bridge

Commands to be executed in the router console to enable remote access.

```text
set_router_password mypassword
remote_console enable
```

--------------------------------

### Network and AP Configuration

Source: https://context7.com/martin-ger/esp32_nat_router/llms.txt

Commands to configure the upstream connection (STA) and the local WiFi Access Point (AP).

```APIDOC
## SET_STA_STATIC

### Description
Configures the upstream connection to use a static IP or reverts to DHCP.

### Parameters
- **ip** (string) - Required - IP address (e.g., 192.168.1.100)
- **netmask** (string) - Required - Subnet mask (e.g., 255.255.255.0)
- **gateway** (string) - Required - Gateway IP (e.g., 192.168.1.1)

## SET_AP

### Description
Sets the Access Point SSID and password.

### Parameters
- **ssid** (string) - Required - The network name
- **password** (string) - Required - The WPA password
```

--------------------------------

### Set Status LED GPIO

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Assign a GPIO pin for the status LED. Use 'none' to disable the LED.

```bash
set_led_gpio
```

--------------------------------

### Flash ESP32-S3 Firmware with esptool

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Installation

Use esptool to flash the ESP32 NAT Router firmware onto the ESP32-S3 chip. The --no-stub option may be useful for ESP32s with JTAG-USB.

```bash
esptool.py --chip esp32s3 \
--before default_reset --after hard_reset write_flash \
-z --flash_size detect \
0x0 firmware_esp32s3/bootloader.bin \
0x8000 firmware_esp32s3/partition-table.bin \
0xf000 firmware_esp32s3/ota_data_initial.bin \
0x20000 firmware_esp32s3/esp32_nat_router.bin
```

--------------------------------

### Register ACL Component with CMake

Source: https://github.com/martin-ger/esp32_nat_router/blob/master/components/acl/CMakeLists.txt

Use this registration block in the component's CMakeLists.txt to define source files and dependencies for the ACL firewall.

```cmake
idf_component_register(
    SRCS "acl.c" "acl_nvs.c"
    INCLUDE_DIRS "include"
    REQUIRES lwip esp_netif esp_timer
    PRIV_REQUIRES nvs_flash cmd_router
)
```

--------------------------------

### Set ESP32 Target Chip

Source: https://github.com/martin-ger/esp32_nat_router/wiki/Building

Use this command to select the specific ESP32 chip you are targeting for the build. Replace `<YOUR_ESP_TYPE>` with your chip's model.

```bash
idf.py set-target <YOUR_ESP_TYPE>

```

--------------------------------

### WireGuard VPN Configuration

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands to configure and enable a WireGuard VPN tunnel.

```APIDOC
## VPN (WireGuard)

### Description
Configure WireGuard VPN tunnel settings.

### Commands
- **set_vpn <private_key> <public_key> <endpoint> <address> [-k <psk>] [-m <mask>] [-p <port>] [-a <keepalive>] [-e <0|1>] [-K <0|1>]** - Configure WireGuard VPN tunnel.
```

--------------------------------

### DHCP and Port Mapping

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Commands for managing DHCP reservations and network port forwarding rules.

```APIDOC
## DHCP & Port Mapping

### Description
Manage DHCP client reservations and port mapping rules for the router.

### Commands
- **dhcp_reserve [add|del|block] <mac> [<ip>] [-- <name>]** - Add/delete DHCP reservation or block a client by MAC.
- **portmap [add|del] [TCP|UDP] <ext_portno> <int_ip> <int_portno> [STA|VPN]** - Add or delete a portmapping to the router.
```

--------------------------------

### Manage Syslog Forwarding

Source: https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference

Control remote syslog forwarding. Use 'status' to view configuration, 'enable' with server and optional port, or 'disable'.

```bash
syslog   <action> [<args>]
```

--------------------------------

### MQTT Topics and Payloads

Source: https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant

Overview of the MQTT topics used for telemetry, commands, and client statistics.

```APIDOC
## MQTT Topics

### Description
Topics used for publishing router state and subscribing to remote commands.

### Topics
- `esp32_nat_router/state` (Publish) - Router telemetry JSON
- `esp32_nat_router/availability` (Publish) - `online` / `offline` status
- `esp32_nat_router/command/restart` (Subscribe) - Restart command
- `esp32_nat_router/clients/<MAC>` (Publish) - Per-client stats JSON

### State Payload Example
{
  "uplink": "ON",
  "clients": 3,
  "bytes_tx": 1048576,
  "bytes_rx": 2097152,
  "free_heap": 120000,
  "uptime": 3600,
  "rssi": -52,
  "ssid": "MyNetwork",
  "web_ui": "ON",
  "remote_console": "OFF",
  "ap_enabled": "ON"
}
```