# wifi-eth

**Repository Path**: Hackerpro/wifi-eth

## Basic Information

- **Project Name**: wifi-eth
- **Description**: 主要功能:基于WT32-ETH01，实现wifi与eth透传
基于https://github.com/wei-ei-ei/wt32-eth01-wireless-bridge项目
增加了oled显示，改为ap模式，web配网
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-31
- **Last Updated**: 2026-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WT32-ETH01 通用无线网桥 · 多类型有线设备无感 WiFi 接入

> SoftAP 网页配网 · 128×32 OLED 状态屏 · WiFi↔以太网 L2 透明桥接 · 静态 IP / DHCP · 多 Wi-Fi 配置管理
>
> 让只有**有线网口**的设备（IP 摄像头、电脑、NVR、工控板等）——**插上网线即接入 WiFi 网络**，无需安装驱动。当前固件同一时间支持一台有线客户端。

---

## 一、应用场景

```
                 ┌──────────────────┐  网线   ┌─────────────────┐   WiFi    ┌────────┐
  局域网 / 云端  │ IPC / PC / NVR / │────────│  WT32-ETH01 网桥  │──────────│  路由器  │
                │ 工控板等有线设备 │        │ ESP32+LAN8720    │  2.4GHz  └────────┘
                 └──────────────────┘        └─────────────────┘
```

- 设备只拥有百兆以太网口、**没有 WiFi**，靠网桥接入无线网络；
- 网桥对设备透明：设备**保持自己的 IP**（静态或 DHCP 均可），同一局域网内仍可直接访问该 IP，无需端口映射；
- 支持不同设备类型依次接入，通过网线插拔触发客户端 MAC 重学；
- 网桥最多保存 16 组 Wi-Fi，正常启动只读取当前选中的一组；
- 换 WiFi 环境：**长按按键 2 秒** → 手机连接网桥热点、打开网页选 SSID 输入密码，全程不需要装 App。

## 二、特性

| 特性 | 说明 |
|------|------|
| L2 透明桥接 | 以太网混杂模式 + MAC 改写，同一广播域、端到端会话，IP 层无 NAT |
| 多类型设备兼容 | IPC、电脑、NVR、工控板等标准以太网设备共用同一固件；一次接入一台 |
| **通用 MAC 学习** | 从有线侧第一个合法单播帧学习，不依赖 DHCP 或 ARP；网线断开后自动重学 |
| **SoftAP 网页配网** | 长按 IO2（2 秒）进入 AP 模式，手机浏览器打开 `192.168.4.1`，可扫描附近 SSID、选择并输入密码 |
| **随机 AP 密码** | 每次进入配网模式生成新的 **8 位数字 WPA2 密码**，显示在 OLED 屏幕并打印到串口日志 |
| **OLED 状态屏** | 128×32 SSD1306（I2C，SDA=IO14 / SCL=IO15）：配网时显示热点名/密码/地址，桥接时显示连接状态/SSID/客户端 IP |
| 多 Wi-Fi 配置库 | 默认保存 16 组 SSID/密码，NVS 持久化；启动时只加载当前配置 |
| 开机自动回连 | 当前凭据存 NVS，断电重启自动重连；连不上自动回退配网模式 |
| 拥塞可观测 | WiFi 发送队列丢帧计数告警（`WiFi TX drop #N`），量化空口拥塞 |
| 省电关闭 | `WIFI_PS_NONE`，避免下行流量在休眠窗口丢失 |

## 三、硬件

| 器件 | 型号/要求 | 备注 |
|------|-----------|------|
| 网桥 | WT32-ETH01（ESP32-D0WD-V3 + LAN8720AI，百兆） | 5V 供电 |
| 状态屏 | 128×32 SSD1306 OLED，I2C 接口（地址通常 `0x3C`） | **SDA → IO14，SCL → IO15**，3.3V 供电，SDA/SCL 需上拉（多数模块板载 4.7k）；不接屏也能正常运行 |
| 有线设备 | 任意带标准 10/100M 以太网口和 TCP/IP 栈的设备 | 网桥不向外设供电，IPC 等设备需独立供电 |
| 实测参考设备 | 海思 HI3516CV610 方案 IPC 模组 | **DC 12V/2A，不能依赖 POE 供电** |
| 路由器 | 任意 2.4GHz WiFi 路由器 | 建议关闭"无线隔离/AP 隔离"；有双频时监控端连 5G 可显著改善延迟 |

> 接线与引脚注意事项见 [`docs/WT32-ETH01硬件说明.md`](docs/WT32-ETH01硬件说明.md)，通用接入流程和摄像头实测示例见 [`docs/设备接入示例.md`](docs/设备接入示例.md)。

## 四、快速开始

### 1. 环境

- 本仓库当前在 **ESP-IDF v5.5.5** 下编译验证通过；工程源自官方示例 `examples/network/sta2eth`（原开发环境 v6.0.2），
  不同 IDF 版本的示例目录位置与内部 API 可能有差异（如 `esp_wifi_internal_reg_rxcb` 等私有接口），升级前请先核对；
- 依赖组件随 `main/idf_component.yml` 由 Component Manager 自动拉取：`espressif/ethernet_init`（必需）、
  `espressif/network_provisioning`（仅为可选的 BLE 配网方案保留，当前配置下不会被使用）；
- Windows 下推荐直接使用仓库根目录的 `idf.ps1`，它会自动设置 `IDF_TOOLS_PATH`、`TEMP`、`TMP` 并加载 ESP-IDF。

### 2. 编译烧录

WT32-ETH01 **没有自动下载电路**，烧录需手动进 bootloader：

1. **IO0 接 GND** → 模块断电再上电（进入下载模式）
2. 烧录：
   ```powershell
   .\idf.ps1 -p COM15 flash monitor
   ```
3. **拔掉 IO0 接地线** → 断电重新上电，模块自动运行

> 刷机后首次开机（NVS 无凭据）自动进入 **SoftAP 网页配网**；已有配置时串口会打印
> `Loaded N profiles, active id M`，用于确认当前配置库状态。
>
> 已有可用配置、只想新增另一组网络时，**长按 IO2 2 秒** 即可重新进入配网模式。

### 3. 网页配网（换 WiFi 也用这一步）

1. **长按网桥 IO2 按键 2 秒**（设备重启，进入 AP 配网模式）；
2. OLED 上会显示本次的 **热点名、8 位数字密码和地址**，串口同时打印：
   ```text
   I (xxxx) wt32_ap_prov: SoftAP SSID: WT32-Bridge-3A7C
   I (xxxx) wt32_ap_prov: SoftAP password: 48213906
   I (xxxx) wt32_ap_prov: Open http://192.168.4.1 in a browser to configure Wi-Fi
   ```
3. 手机连接该热点（密码见 OLED 或串口日志）；
4. 浏览器打开 `http://192.168.4.1`，页面会自动扫描附近 Wi-Fi：
   点选目标 SSID（隐藏网络可手动输入）→ 输入密码 → **保存并连接**；
5. 设备保存凭据并自动重启进入桥接模式；成功后 OLED 显示 `WIFI:CONNECTED` 与客户端 IP，
   串口看到 `Wi-Fi STA connected`。

> 每次进入配网模式都会**重新生成** 8 位密码，旧密码立即失效。
> 若密码错误或目标网络不可达，设备会在 10 秒后自动回到配网模式（并生成新密码），重新操作即可。
> 扫描期间 AP 需要短暂切换信道，手机可能出现 1~3 秒卡顿或瞬断，属正常现象。

### 4. 接入有线设备

1. DHCP 设备直接接入即可；静态 IP 设备配置为**与路由器同网段、掩码一致、网关指向路由器**；
2. 网线接入网桥；直连插拔会触发链路重连和自动 MAC 重学；
3. 从同一 WiFi 的电脑 `ping` 设备 IP，或在串口确认 `Wi-Fi STA connected`；
4. 串口出现 `Wired client MAC learned: xx:xx:...` = 设备已被网桥识别；
5. 更换设备时断开并重新插入网线；通过交换机更换且链路不中断时，需要重启网桥。

> OLED 的 `IP:` 是**桥后有线设备的 IP**：网桥在桥接模式下是纯二层转发、自身没有 IP，
> 该地址由 ARP / DHCP ACK 学习得到（静态 IP 设备靠 ARP 学习）。
> 摄像头供电、静态 IP 和 RTMP 推流验证步骤见 [`docs/设备接入示例.md`](docs/设备接入示例.md)。

## 五、性能实测（供参考）

| 项目 | 数据 | 条件 |
|------|------|------|
| iperf3 TCP（单跳） | 13~14 Mbps | 对端接路由器有线侧 |
| iperf3 TCP（两跳同频） | ~9.6 Mbps | 对端与网桥同为路由器 2.4G 无线终端 |
| ping 延迟（两跳） | 5~11 ms | 信号 RSSI -44 时 |
| 摄像头 RTMP 推流 | 可用 | 两跳场景建议码率 ≤2~3 Mbps，并观察串口 `WiFi TX drop` 计数 |

> 同频两跳的吞吐约为单跳的 5~7 折（空口时间共享所致），是物理规律而非故障。改善：路由器开双频，监控端走 5G。

## 六、与官方示例的差异

本工程基于 Espressif 官方 `sta2eth` 示例（ESP-IDF）改造。**逐项改动说明（含原因与验证方法）见 [`docs/官方示例改动说明.md`](docs/官方示例改动说明.md)**，概要：

1. **硬件适配三项**：WPA2 握手需要 SHA1（默认预设被禁）；LAN8720 复位脚 GPIO16 需拉高；RMII 50MHz 时钟为 GPIO0 **输入**（LAN8720 晶振倍频输出）；
2. **配网方案**：官方网页配网 → BLE 配网 → 现改为 **SoftAP + 自建网页配网**（含 SSID 扫描、随机 8 位数字密码、OLED 显示），BLE 已关闭；
3. **开启以太网混杂模式**：官方默认关闭，关闭时 EMAC 硬件过滤会丢弃"目的 MAC 非本机"的单播帧——这是"能上网但无法与 WiFi 侧设备互通"的直接根因；
4. **通用 MAC 学习**：官方 MAC 槽位只认 DHCP DISCOVER，静态 IP 设备无法接入；现从首个合法上行单播帧学习，并在链路断开后清空重学；
5. **多 Wi-Fi 配置库**：NVS 保存多组凭据，正常启动只读取当前一组，不引入逐包开销；
6. **OLED 状态显示**：128×32 SSD1306（I2C），配网时显示热点与随机密码，桥接时显示连接状态与客户端 IP；
7. **TX 丢包计数**：官方对 WiFi 发送失败只打 LOGD（不可见），现改为 WARN 级计数告警；
8. **编译优化改为 `-Os`**：默认 Debug(-Og) 在 ESP32 的 128KB IRAM 下余量很小，`-Os` 为显示屏与 HTTP 服务留出安全余量；关闭 BLE 后 IRAM 余量约 36KB。

## 七、已知限制与排查口诀

| 限制/现象 | 原因 | 处理 |
|-----------|------|------|
| 手机搜不到 `WT32-Bridge-XXXX` 或连不上 | 密码错误（每次配网都会变）；或设备并未处于配网模式 | 看 OLED / 串口日志中的本次密码；长按 IO2 2 秒重新进入配网 |
| 网页打开是空白 / 打不开 | 手机仍走蜂窝数据，或未加入网桥热点 | 关闭移动数据后访问 `http://192.168.4.1` |
| SSID 列表为空 | 2.4G 环境没有可见网络，或目标为隐藏 SSID | 在页面中手动输入 SSID 与密码 |
| OLED 无显示 | 接线错误、无上拉、地址不对、供电不足 | 核对 SDA=IO14 / SCL=IO15 / 3.3V，I2C 地址默认 `0x3C`（部分模块 `0x3D`，改 `CONFIG_EXAMPLE_STATUS_DISPLAY_I2C_ADDR`） |
| OLED `IP:` 一直显示 `--` | 桥后设备尚未产生 ARP/DHCP 报文 | 等设备发起一次通信（推流、ping、ARP）即可学到 |
| 能上网但无法与 WiFi 侧设备互通 | 混杂模式未开启（本仓库已默认开启） | 确认 `CONFIG_EXAMPLE_ETHERNET_USE_PROMISCUOUS=y` |
| 通过交换机更换有线设备后新设备不通 | 链路没有断开，网桥仍保持第一个客户端 MAC | 断开网桥与交换机链路后重试，或重启网桥 |
| 第二台有线设备同时接入 | 当前设计只支持单台有线客户端 | 使用交换机后仍需保证同一时间只有一台业务设备 |
| 推流延迟持续升高不回落 | 空口容量不足 → 看串口 `WiFi TX drop` 计数 | 降码率（≤3 Mbps）、双频分流、换干净信道 |
| 想在不同已保存网络间切换 | 当前固件没有列表/切换界面，启动只使用 `active` 那一组 | 长按 IO2 重新配网，选择目标网络后它会成为当前配置 |

## 八、目录结构

```
├── main/
│   ├── bridge_main.c         # 主逻辑：桥接/配网分支、WiFi/IP 事件、收发回调、OLED 状态联动
│   ├── softap_web.c          # SoftAP + 网页配网：随机密码、HTTP 服务、SSID 扫描/连接 API
│   ├── web/index.html        # 独立自包含配网页面（内联 CSS/JS，无外部依赖）
│   ├── status_display.c/.h   # 128×32 SSD1306 状态屏（I2C，内置 8×8 字库）
│   ├── ethernet_iface.c      # 以太网侧：MAC 改写、通用客户端学习、桥接收发、客户端 IP 学习
│   ├── wifi_profile_store.c  # 多 Wi-Fi NVS 配置库
│   ├── provisioning.c        # (可选) 原 BLE 配网方案；默认关闭，启用需打开 BT
│   ├── wifi_profile_prov.c   # (可选) BLE 配置管理端点，仅随 BLE 方案编译
│   ├── scheme_generic_httpd.c# (可选) 原 httpd 配网方案
│   ├── manual_config.c       # (可选) 有线网页手动配置方案
│   └── usb_ncm_iface.c       # (备用) USB NCM 有线接口，以太网方案下不参与编译
├── docs/
│   ├── 官方示例改动说明.md     # 逐项改动、原因、验证方法
│   ├── WT32-ETH01硬件说明.md  # 模块构成、引脚、OLED 接线、时钟设计、官方资料链接
│   ├── 设备接入示例.md          # 通用接入流程与 IPC 实测经验
│   └── WiFi多配置管理.md      # NVS 数据结构和配置管理说明
├── mbedtls_preset_bridge.conf   # mbedtls 裁剪预设（已修正 SHA1）
└── sdkconfig.defaults        # 本仓库全部配置差异（AP 配网、OLED、PHY、时钟、-Os…）
```

## 九、许可与致谢

- 代码基于 **Espressif 官方示例 `examples/network/sta2eth`**（ESP-IDF）改造，原文件保留 Espressif 的 SPDX 标识（`Unlicense OR CC0-1.0`）；本仓库的修改同样以该许可发布；
- OLED 驱动使用 ESP-IDF 内置 `esp_lcd` 的 SSD1306 面板驱动（Apache-2.0）；8×8 点阵字库为公共领域（Daniel Hepper / Marcel Sondaar）；
- 依赖组件（`espressif/ethernet_init` 等）许可随 IDF Component Manager 声明；
- WT32-ETH01 规格资料版权归原厂（Wireless-Tag / 启明云端）所有，本仓库**不转载原厂 PDF**，只提供原创整理笔记与官方链接；
- 各商标归其所有者所有。

---

## 附录：特殊环境配置（工具链非默认位置）

使用仓库自带的 PowerShell 入口，不需要每次手动设置路径：

```powershell
cd E:\esp-idf\esp-idf-v6.0.2\project\wt32-eth01-bridge
.\idf.ps1 build
.\idf.ps1 -p COM15 flash monitor
.\idf.ps1 menuconfig
```

默认配置：

- ESP-IDF：`E:\esp-idf\esp-idf-v6.0.2`
- IDF 工具链：`E:\.espressif`
- 临时目录：仓库内 `tmp\esp_temp`

换电脑或更换工具链位置时，只需设置环境变量，不需要改脚本：

```powershell
$env:WT32_IDF_PATH = "D:\esp-idf\esp-idf-v6.0.2"
$env:WT32_IDF_TOOLS_PATH = "D:\.espressif"
$env:WT32_TEMP = "D:\esp_temp"
.\idf.ps1 build
```

如果 PowerShell 禁止执行本地脚本，可在当前用户范围允许签名脚本：

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```