Skip to content

Hardware

Jump to bottom
Martin Gergeleit edited this page Mar 26, 2026 · 3 revisions

Hardware

LED Status Indicator

The on-board LED provides visual feedback about connection and traffic status:

  • LED off: ESP32 is not connected to upstream AP
  • LED on (steady): ESP32 is connected to upstream, no traffic
  • LED flickering: ESP32 is connected, traffic is flowing through the router. The flickering intensity is proportional to the traffic volume — heavier traffic produces more intense flickering

Configuring the LED GPIO

By default, the LED is disabled. To enable it, configure the GPIO pin for your board:

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

Changes take effect after restart.

Common LED GPIO Pins by Board

Board / Chip Default LED GPIO
ESP32 DevKit v1 / WROOM GPIO 2
ESP32-S2 GPIO 2 (varies)
ESP32-S3 DevKitC GPIO 48 (RGB)
ESP32-C3 DevKitM / SuperMini GPIO 8
ESP32-C6 DevKitC GPIO 8
NodeMCU-32S GPIO 2
Lolin D32 GPIO 5
Lolin32 Lite GPIO 22

Note: Some boards have active-low LEDs. ESP32-S3 often uses GPIO 48 for an addressable RGB LED (WS2812) which may require different handling.

Addressable LED Strip (WS2812 / SK6812)

Instead of a plain on/off LED, you can use a single addressable LED (WS2812, SK6812, or compatible) to show router status via color:

Color Meaning
Red pulse Not connected to upstream AP (breathing effect, 2s cycle)
Yellow pulse Connecting to upstream AP
Green Connected (brightness increases with number of connected clients)
Cyan flash Traffic burst detected
Red/blue alternation Factory reset in progress (BOOT button held)

The addressable LED and the plain GPIO LED are mutually exclusive — configure one or the other, not both.

Configuration

The LED strip is disabled by default. To enable it, set the data GPIO pin:

set_led_strip 27         # Set LED strip data pin to GPIO 27
set_led_strip none       # Disable LED strip (default)
set_led_strip            # Show current setting

Changes take effect after restart. The setting is stored in NVS under key ls_gpio.

Wiring

Connect a single WS2812 or SK6812 LED:

LED Pin Connection
DIN GPIO pin (set via set_led_strip)
VDD +5V
GND GND

Note: Most WS2812 LEDs require 5V power but accept 3.3V logic on DIN. If the LED is unreliable, add a level shifter or power the LED from 3.3V (reduced brightness but more reliable signaling).

OLED Display (ESP32-C3 and ESP32-S3 only)

The firmware supports a 72x40 pixel (0.42") SSD1306 OLED display over I2C as found on certain ESP32-C3 mini boards and the display fold on the Heltec V3 dev board. The display is specifically designed for the small I2C OLEDs Other display sizes or drivers are not supported.

The display shows:

  • AP SSID
  • STA connection status and RSSI
  • STA IP address
  • Number of connected clients
  • Sent/received traffic in MB

Configuration

The OLED display is disabled by default. Enable and configure it via the serial console:

oled enable              # Enable OLED display (requires reboot)
oled disable             # Disable OLED display (requires reboot)
oled gpio <sda> <scl>    # Set I2C pins (default: SDA=5, SCL=6)
oled status              # Show current configuration

The default I2C pins (SDA=5, SCL=6) match the typical wiring on ESP32-C3 mini boards with built-in OLED.

XIAO ESP32-C6 Antenna Switch

The XIAO ESP32-C6 board has a hardware RF switch to select between the built-in ceramic antenna and an external antenna:

set_rf_switch_XIAO 0    # Built-in ceramic antenna (default)
set_rf_switch_XIAO 1    # External antenna

Uses GPIO3 (RF switch enable) and GPIO14 (antenna select). The setting is saved to NVS and applied on every boot.

Factory Reset via BOOT Button

You can factory reset the ESP32 NAT Router by holding the BOOT button for 5 seconds. This erases all settings stored in NVS (WiFi credentials, port mappings, DHCP reservations, ACL rules, passwords, etc.) and restarts the device with default configuration.

The BOOT button GPIO is selected automatically at compile time based on the chip:

Chip BOOT Button GPIO
ESP32, ESP32-S2, ESP32-S3 GPIO 0
ESP32-C3, ESP32-C2, ESP32-C6 GPIO 9
ESP32-C5 GPIO 28

How to Use

  1. Press and hold the BOOT button on your ESP32 board
  2. If an LED is configured, it will rapidly blink to indicate the button press is being detected
  3. Continue holding for 5 seconds
  4. The device will erase all settings and restart automatically

After reset, the ESP32 will boot with default settings (open AP with SSID "ESP32_NAT_Router").

Other Reset Methods

  • Serial console: Use the factory_reset command
  • Full flash erase: esptool.py -p /dev/ttyUSB0 erase_flash (also erases firmware)

ESP32 NAT Router

Clone this wiki locally
⚡