MWRouter

基于 ESP32-S3 的多 WAN / 多 LAN 路由器固件：在单一上行出口的前提下，将蜂窝（USB PPP）、Wi-Fi STA、W5500 有线等上行与 SoftAP、RJ45（LAN）、SPI 网桥（下联 MCU）等 LAN 侧组合，通过 LwIP NAPT 做 NAT 转发与路由策略。

Supported Targets	ESP32	ESP32-C2	ESP32-C3	ESP32-C6	ESP32-C5	ESP32-S2	ESP32-S3

---

开发背景

• 上游基底：Espressif esp-iot-bridge 及示例 examples/4g_nic，在 ESP-IDF 上实现多种网卡桥接与 NAT。
• 产品目标：在资源受限的 MCU 上实现「类似家用路由器」的体验——多上行可选与优先级、多 LAN 形态（Wi-Fi 热点、有线、SPI 供其他 MCU 上网）、Web 配网、长时间运行稳定。
• 本仓库定位：components/iot_bridge 内嵌维护（来自上游组件并含 Windows / ESP-IDF 5.5+ 兼容性补丁）；业务逻辑分布在 main/、components/multiwan/、components/system/、components/webService/、components/mw_common/ 等。

---

目标硬件与典型拓扑

• 主控：ESP32-S3（默认配置面向带 PSRAM 的模组，如 sdkconfig 注释中的 N8R2）。
• 蜂窝：USB CDC 类 Cat.1 / LTE 模组（PPPoS）。
• 有线：W5500（SPI 以太网控制器），同一时刻 RJ45 作 WAN 或作 LAN 由工作模式决定，与 SPI 网桥区分。
• SPI 下联：BRIDGE_DATA_FORWARDING_NETIF_SPI — ESP 作路由侧，经 SPI 给协 MCU 提供 L2/L3 转发能力（与 W5500 使用不同 SPI 设备/引脚，避免总线冲突）。

---

已实现功能

网络与桥接

• 上行类型：USB Modem（PPP）、Wi-Fi STA、W5500 有线 WAN（mwr_wan_type_t）。
• 下行 / LAN：SoftAP、以太网 LAN（ETH_LAN，含 DHCPS 策略注册）、SPI 转发网卡。
• 工作模式表：通过 mwr_work_mode_profile.c 定义 37 种 组合（例如「4G 上行 → WiFi+有线+SPI」「仅配网 → WiFi 热点」等），Web/NVS 以 work_mode 选用；详见 components/mw_common/include/mwr_work_mode_profile.h。
• 多 WAN：multiwan 组件支持优先级列表、失败回切、最小切换间隔、应用层探测与健康标记（multiwan_manager_*）。
• IoT Bridge 集成：esp_bridge_create_all_netif() 流程由 router_bootstrap + system_bridge_runtime 按硬件探测与 NVS 工作模式选择性创建网卡。

启动与硬件探测

• W5500：上电早期探测（避免与后续 SPI 主机资源冲突），结果影响是否创建 SPI 以太网。
• USB 4G：枚举与识别（VID/PID），与 Modem 拨号流程配合。
• SPI 网桥参数：spi_net_settings 在 bridge 创建前从 NVS 恢复时钟、队列等。

Web 与配置

• HTTP 服务：esp_http_server，REST API（系统信息、WiFi AP/STA、网络配置、日志等），静态页面（LittleFS）；详见 components/webService/README.md。
• 配网体验：bridge 创建前启动 Web，缩短长时间「连接被拒绝」窗口；SoftAP SSID/密码支持 menuconfig 默认可写入。

蜂窝与链路维护

• PPP 获取 IP 后：启动 WAN keepalive（UDP/空闲策略可配置），减轻蜂窝侧静默断开。
• 时间：RTC / NTP / 模组时间同步（system_time 等，见 components/system/README.md）。

稳定性与自愈（System）

• 内存与 LwIP 统计：周期性堆内存、LwIP memp/pbuf 统计；可选 PBUF 水位守护、SPI 丢包告警窗口。
• Modem 自愈：在持续内存压力下可对 PPP 做软重拨（可配置冷却与 streak），避免整机重启。
• 任务布局日志：关键任务绑核、优先级、栈水位打印，便于对照 sdkconfig.defaults 中的亲和性策略。

工程级修复（维护记录）

• W5500：PPP 获取 DNS 后曾触发「Hardware Reset Ethernet PHY」类链路抖动，已通过 禁用 ETH_LAN 网段冲突检测 等策略缓解（见历史提交与注释）。
• Windows + ESP-IDF 5.5+：IoT Bridge 补丁脚本问题已通过 tools/iot_bridge_fix/ 覆盖 patch_utils.cmake / patches.list 修复（根目录 CMakeLists.txt 自动拷贝）。
• LwIP TCPIP 消息池：默认 MEMP_NUM_TCPIP_MSG_INPKT 偏小，在 PPP + NAT + SPI 突发下易导致 pppos_input_tcpip / -1（ERR_MEM）；根目录 CMakeLists 对 __idf_lwip 提升 MEMP_NUM_TCPIP_MSG_INPKT / MEMP_NUM_TCPIP_MSG_API。

---

性能与资源策略

以下为仓库 默认策略摘要（以 sdkconfig.defaults 与 CMakeLists.txt 为准，可按板级内存调整）。

方向	做法
RAM	PSRAM：Wi-Fi/LwIP 大块优先外部 RAM；mbedTLS 外部分配；小对象仍落内部 SRAM；SPIRAM_MALLOC_ALWAYSINTERNAL / RESERVE_INTERNAL 控制阈值。
LwIP	TCPIP 任务绑 CPU0、TCPIP_RECVMBOX_SIZE 放大；WND_SCALE 解除 receive mbox 上限；关闭 L2→L3 额外拷贝（CONFIG_LWIP_L2_TO_L3_COPY 未设置）减轻 pbuf 压力；LWIP_STATS 便于观测池用量。
USB Modem	RX 偏向 USB_HOST_HW_BUFFER_BIAS_IN；增大 USB DTE buffer / CDC 任务栈（iot_bridge Kconfig）。
SPI 网桥	TX/RX 队列深度（如 8）限制背压；转发任务优先级低于 tcpip_thread，绑 Core1，减轻与 Wi-Fi/LwIP 争用。
编译	-O2 性能优化（CONFIG_COMPILER_OPTIMIZATION_PERF），减轻 GCC/IDF 组合下调试优化的已知问题。

运行表现：在开启 SPI 给其他 MCU 转发等高压路径下，曾出现长时间运行后 PPP / 全局缓冲区耗尽 类问题；当前方案通过队列丢弃、释放路径审查、LwIP/TCPIP 池扩展与系统自愈等多层缓解。具体机理与排查要点见仓库内文档
doc/webdeploy/内存泄露问题解决.md。长期拷机与进阶调优方向见
doc/webdeploy/新的持续优化思路.md。

---

环境与构建

1. 安装 ESP-IDF（与 IoT Bridge 组件声明的版本匹配）。
2. 在项目根目录执行：

idf.py set-target esp32s3
idf.py build flash monitor

• iot_bridge 源码位于 components/iot_bridge；其余托管依赖由 main/idf_component.yml 解析到 managed_components/。

---

menuconfig（与上游 Bridge 一致）

• Modem 侧：Component config → Bridge Configuration → Modem Configuration（UART / USB 等）。
• 对外数据转发网卡：Component config → Bridge Configuration → The interface used to provide network data forwarding for other devices（ETH / SPI / SDIO 等）。
• 系统选项：Component config → System options（W5500 探测、USB Modem 枚举、堆日志间隔、WAN keepalive、多 WAN、稳定性自愈等）。

---

下一步优化与开发方向

结合代码现状与 doc/webdeploy/新的持续优化思路.md，建议优先级如下。

1. 内存与 LwIP：按剩余内部 RAM 调整 CONFIG_LWIP_PBUF_POOL_SIZE、CONFIG_LWIP_MAX_NAPT_ENTRIES、TCP_MSS 与 MTU 对齐，避免分片与 NAPT 表耗尽。
2. SPI 转发吞吐：确认 SPI DMA；评估 包聚合（一次事务多帧）、硬件 READY/握手 GPIO，减少无效传输与上下文切换。
3. 零拷贝路径：在安全前提下让 SPI 发送路径尽量直接使用 pbuf/ DMA，减少额外 malloc + memcpy。
4. 总线隔离：W5500 与 SPI 协 MCU 若引脚允许，分 独立 SPI 主机（如 SPI2/SPI3），降低互斥与抖动。
5. 观测与降级：延续 PBUF 水位、SPI 丢包统计；压力下 有限度自愈（已有 modem self-heal / 冷却策略）与可选 SPI 任务/接口复位 策略细化。
6. 任务划分：保持转发与监控任务与 Core1、LwIP Core0 的划分，并按实测调整优先级与栈大小。

---

仓库结构（简要）

路径	说明
main/	app_main、bridge 与 multiwan 引导、system_bridge_runtime
components/iot_bridge/	esp-iot-bridge 及 SPI/驱动补丁
components/multiwan/	多 WAN 策略、模式应用、Wi-Fi 双连等
components/system/	稳定性、探测、keepalive、时间等
components/webService/	HTTP API 与静态资源
components/mw_common/	工作模式表与 ETH LAN DHCPS 策略
components/spi_net_settings/	SPI 网桥 NVS 参数
doc/webdeploy/	部署说明与问题分析 Markdown
tools/iot_bridge_fix/	Windows/IDF 5.5+ 补丁文件

---

参考文档

• 上游 IoT Bridge 用户指南：User_Guide.md
• 项目内：内存泄露问题解决 · 新的持续优化思路
• 组件说明：components/iot_bridge/README.md、components/system/README.md、components/webService/README.md