esp_wifi_repeater

一个功能完整的 WiFi NAT 路由器（现在也成为了 WiFi 中继器，即 L2 桥接）

2026 年新特性： 在首次发布 10 年后，它终于成为了它一直想要成为的东西：一个真正的 WiFi 中继器。为了不破坏现有的文档和链接，标准版仍然保留众所周知的 NAT 路由器版本，并包含所有高级功能。但如果你感兴趣的是一个精简的真正 L2 桥接，请看下面的 ESP8266 WiFi Repeater - L2 bridge 章节。

这是在 esp8266 和 esp8285 上实现的 WiFi NAT 路由器。它还包含对带有 ACL 的包过滤防火墙、端口映射、流量整形、远程监控（或数据包嗅探）钩子、MQTT 管理接口、简单 GPIO 交互以及电源管理的支持。为了在 mesh 中使用多个路由器覆盖更大区域，还加入了一种新模式 "Automesh"。

如果你正在寻找将 NAT 功能集成到 Arduino 项目中的方法 - 请参见 此处 。

EPS32 NAT Router 是针对 ESP32 的高级项目。

典型使用场景包括：

• 用于现有 WiFi 网络的简单范围扩展器
• 电池供电的户外（mesh）网络
• 为访客设置具有不同 SSID/密码的附加 WiFi 网络
• 为物联网设备设置安全且受限的网络
• 将 WPA2 Enterprise 网络转换为 WPA-PSK
• 用于 WiFi 流量分析的监控探针
• 使用路由、ACL 和流量整形进行网络实验
• 具有基本 I/O 能力和 MQTT 控制的 mesh 物联网设备

默认情况下，ESP 同时作为 STA 和 soft-AP，并透明地转发经过它的所有 IP 流量。由于它使用 NAT，网络侧和连接的站点都无需路由条目。站点默认通过 DHCP 在 192.168.4.0/24 网段中配置，并从现有 WiFi 网络获取 DNS 应答服务器地址。

测量结果表明，它在两个方向上都能达到约 5 Mbps 的吞吐量，因此即使是流媒体播放也是可行的。

一些细节在这个 视频 中有所说明。

Web 安装器

如需直接刷写到设备上，请使用 Web 安装器。

首次启动

esp_wifi_repeater 启动时采用以下默认配置：

• ap_ssid: MyAP, ap_password: none, ap_on: 1, ap_open: 1
• network: 192.168.4.0/24

首次启动（或出厂重置）后，它将提供一个开放 AP、SSID 为 "MyAP" 的 WiFi 网络。它暂时不会尝试自动重新连接上行 AP（因为它还不知道有效的 ssid 或密码）。

连接到这个 WiFi 网络，然后通过简单的 Web 界面进行基本配置，或通过控制台进行包含所有选项的完整配置。

基础 Web 配置界面

Web 界面允许配置基本转发功能所需的全部参数。感谢 rubfi 在此方面的主要工作：https://github.com/rubfi/esp_wifi_repeater/。将浏览器指向 "http://192.168.4.1"。应出现此页面：

首先为上行 WiFi 网络（"STA Settings"）输入合适的值。对于开放网络，使用密码 "none"。当且仅当你确实想使用 automesh 模式时，勾选 "Automesh" 复选框。点击 "Connect"。ESP 重新启动并将连接到你的 WiFi 路由器。几秒钟后状态 LED 应开始闪烁。

如果你选择了 automesh，配置就完成了。无需配置 "Soft AP Settings"，因为在 automesh 模式下这些设置与 "STA Settings" 相同。所有已连接的 ESP 中继器将提供相同的 ssid。

如果你不使用 automesh，现在可以重新加载页面并更改 "Soft AP Settings"。点击 "Set"，ESP 将再次重新启动。现在它已就绪，可以通过新配置的 Soft AP 转发流量。请注意，这些更改也会影响配置界面，即要进行进一步配置，请通过新配置的 WiFi 网络之一连接到 ESP。如果要通过 Soft AP 访问，请记住 Soft AP 网络的地址（如果你更改了它）（ESP 在此网络中始终具有地址 x.x.x.1）。

如果你愿意，可以勾选 "lock" 复选框并点击 "Lock"。此后，除非先用上行 WiFi 网络的密码解锁，否则无法再更改配置（即使网络是开放的，也要定义一个密码）。

如果要在 Web 界面中输入非 ASCII 或特殊字符，必须使用 HTTP 风格的十六进制编码，例如 "My%20AccessPoint"。这将得到字符串 "My AccessPoint"。使用这种十六进制编码，你可以输入任何字节值，但 0 除外（由于 C 内部原因）。

如果出现失误且与 ESP 失去了所有联系，你仍可以使用串行控制台来恢复它（"reset factory"，见下文）。

命令行界面

高级配置必须通过控制台界面上的命令行完成。此控制台可通过串行端口（115200 波特）或 TCP 端口 7777 访问（例如，从已连接的 STA 执行 "telnet 192.168.4.1 7777"）。

使用以下命令进行初始设置：

• set ssid your_home_router's_SSID
• set password your_home_router's_password
• set ap_ssid ESP's_ssid
• set ap_password ESP's_password
• show (to check the parameters)
• save
• reset

同样，如果要输入非 ASCII 或特殊字符，可以使用 HTTP 风格的十六进制编码（例如 "My%20AccessPoint"），或者仅在 CLI 上使用带反斜杠的 C 风格引号作为快捷方式（例如 "My\ AccessPoint"）。两种方法都会得到字符串 "My AccessPoint"。

命令行还支持更多命令：

基本命令

足以让它在几乎所有环境中正常工作。

• help: 打印一条简短的帮助信息
• set [ssid|password] value: 更改上行 AP 的设置（你家路由器的 WiFi 配置），对于开放网络使用密码 "none"。
• set [ap_ssid|ap_password] value: 更改 ESP 的 soft-AP 设置（供你的站点使用）
• show [config|stats]: 打印当前配置或一些状态信息和统计信息
• save [dhcp]: 将当前配置参数、ACL 和路由条目 [+ 当前 DHCP 租约] 保存到闪存
• lock [password]: 保存并锁定当前配置，不允许更改。如果之前已设置密码，则可以留空（默认是上行 WiFi 的密码）
• unlock password: 解锁配置，需要 lock 命令中的密码
• reset [factory]: 重置 esp，'factory' 可选择将 WiFi 参数重置为默认值（对于已锁定的设备，只能从串行控制台操作）
• quit: 终止远程会话

高级命令

大多数 set 命令只有在 save 和 reset 之后才会生效。

命令行输入中单个 "#" 之后直到行尾的任何部分都将被视为注释并被忽略。

Automesh 配置

• set automesh [0|1]: 选择 automesh 模式是开启还是关闭（默认），详情请参见 https://github.com/martin-ger/esp_wifi_repeater#automesh-mode
• set am_threshold dB: 设置“差”连接的阈值（以负 dB 为单位，默认 85，即 -85 dB）
• set am_scan_time secs: 设置 ESP 在 automesh 模式下尝试查找上行 AP 后进入休眠前的时间间隔（秒）（0 为禁用，默认）
• set am_sleep_time secs: 设置 ESP 在 automesh 模式下找不到上行 AP 时休眠的时间间隔（秒）（0 为禁用，默认）

WiFi 配置

• set ap_on [0|1]: 选择 soft-AP 是禁用（ap_on=0）还是启用（ap_on=1，默认）
• set ap_open [0|1]: 选择 soft-AP 是使用 WPA2-PSK 安全（ap_open=0，如果设置了 ap_password 则自动）还是开放（ap_open=1）
• set auto_connect [0|1]: 选择 STA 是否应持续重试重新连接 AP。首次刷写后或执行 "reset factory" 后，auto_connect 处于关闭状态（0）。当你输入新的 SSID 时，它将自动设为开启（1）。
• set ssid_hidden [0|1]: 选择 soft-AP 的 SSID 是隐藏（ssid_hidden=1）还是可见（ssid_hidden=0，默认）
• set phy_mode [1|2|3]: 设置 WiFi 的 PHY_MODE（1=b，2=g，3=n（默认））
• set country CC: 将 WiFi 监管国家代码设置为 2 字母 ISO 3166-1 代码（例如 "US"、"DE"、"CN"、"JP"）。非美国代码会解锁频道 12 和 13。留空（默认）则保持 SDK 默认值不变。该设置会保存到闪存，并在每次启动时重新应用。
• set bssid xx:xx:xx:xx:xx:xx: 设置要连接的上行 AP 的特定 BSSID（默认 00:00:00:00:00:00，表示任意）
• set [ap_mac|sta_mac] xx:xx:xx:xx:xx:xx: 将 STA 和 SOFTAP 的 MAC 地址设置为用户定义的值（MAC 地址首字节的第 0 位不能为 1）
• set sta_mac random: 每次重启后设置一个新的随机 STA MAC
• set sta_hostname name: 设置 STA 的名称（对上行 AP 可见）
• set max_clients [1-8]: 设置可以连接到 SoftAP 的 STA 数量（ESP 的 SoftAP 实现限制为 8，默认）
• scan: 扫描 AP
• connect: 尝试使用当前配置的 ssid 和 password 连接到 AP
• disconnect: 断开与任何上行 AP 的连接

WPA2 Enterprise 配置

• set use_peap[0|1]: 选择 STA 应通过简单的 WPA-PSK（use_peap=0，默认）还是 WPA2 Enterprise（PEAP）连接
• set peap_identity value: 设置 PEAP “外部”身份（首先呈现给 RADIUS 服务器的字符串，可能是 [email protected]）
• peap_username value: 设置 PEAP 用户名
• peap_password value: 设置 PEAP 密码

TCP/IP 配置

• set network ip-addr: 设置内部网络的 IP 地址，网络始终为 /24，路由器始终为 x.x.x.1
• set dns dns-addr: 设置通过 DHCP 分发给客户端的静态 DNS 地址
• set dns dhcp: 配置使用来自 DHCP 的动态 DNS 地址，默认
• set ip ip-addr: 为 STA 接口设置静态 IP 地址
• set ip dhcp: 为 STA 接口配置动态 IP 地址，默认
• set netmask netmask: 为 STA 接口设置静态子网掩码
• set gw gw-addr: 为 STA 接口设置静态网关地址
• set max_nat no_of_entries: 设置 NAPT 表的大小（默认 512）
• set max_portmap no_of_entries: 设置端口映射表的大小（默认 32）
• set tcp_timeout secs: 设置 TCP 连接的 NAPT 超时（0=默认（1800 秒））
• set udp_timeout secs: 设置 UDP 连接的 NAPT 超时（0=默认（2 秒））
• set lease min: 设置内部网络 DHCP 服务器的租约时间（分钟）（默认 120）
• show dhcp: 打印 dhcp 租约表的当前状态

路由

• show route: 显示当前路由表
• route clear: 清除所有静态路由
• route add network gw: 通过网关 gw 向网络添加静态路由（网络以 CIDR 表示法（'x.x.x.x/n'）给出）
• route delete network: 删除到某个网络的静态路由
• interface inX [up|down]: 将接口状态设置为 up 或 down（不通过 down 接口进行 IP 路由/流量转发，默认：up）
• set nat [0|1]: 选择 soft-AP 接口是否进行 NAT（nat=1，默认）或不进行（nat=0）。没有 NAT，来自内部 STA 的流量透明转发将无法工作！主要与静态路由结合使用。
• portmap add [TCP|UDP] external_port internal_ip internal_port: 添加端口转发
• portmap remove [TCP|UDP] external_port: 删除端口转发
• nslookup name: 对给定名称执行 DNS 查找并显示结果
• ping host: 通过 ICMP 回显请求/回复检查 IP 连通性（主机为 IP 地址或 DNS 名称）

防火墙/监控配置

• acl [from_sta|to_sta|from_ap|to_ap] [TCP|UDP|IP] src-ip [src_port] desr-ip [dest_port] [allow|deny|allow_monitor|deny_monitor]: 向 ACL 添加新规则
• acl [from_sta|to_sta|from_ap|to_ap] clear: 清除整个 ACL
• show acl: 显示已定义的 ACL 和一些统计信息
• set acl_debug [0|1]: 打开/关闭 ACL 调试输出 - 所有被拒绝的数据包将记录到终端
• set [upstream_kbps|downstream_kbps] bitrate: 设置最大上行/下行比特率（0 = 无限制，默认）
• set daily_limit limit_in_KB: 定义 STA 每天可以传输的最大千字节数（0 = 无限制，默认）
• set timezone hours_offset: 定义本地时区（用于知道一天在 00:00 结束的时间）
• monitor [on|off|acl] port: 在给定端口上启动和停止监控服务器

用户界面配置

• set config_port portno: 设置控制台登录的端口号（默认 7777，0 禁用远程控制台配置）
• set web_port portno: 设置 Web 配置服务器的端口号（默认 80，0 禁用 Web 配置）
• set config_access mode: 控制允许控制台和 Web 进行配置访问的网络（0：不允许访问，1：仅内部，2：仅外部，3：两者（默认））

GPIO 配置

• show gpio: 显示 gpio 配置
• gpio [0-16] mode [in|in_pullup|out]: 配置 ESP 的 GPIO 端口（保存到闪存）
• gpio [0-16] set [high|low]: 向输出端口写入
• gpio [0-16] set [high|low] for seconds: 向输出端口写入并在一定时间后恢复
• gpio [0-16] get: 从输入端口读取
• gpio [0-16] trigger [0-16] [monostable_NO|monostable_NC|bistable_NO|bistable_NC]: 将输入端口连接到输出端口，可以是单稳态常开（状态变为低电平时触发按钮）、单稳态常闭（状态变为高电平时触发按钮）、双稳态常开（复制输入的开关）或双稳态常闭（状态与输入相反的开关）
• gpio [0-16] trigger none: 清除该链接