网络连接问题¶

本文引用的文件 - main.c - wifi_manager.c - eth_manager.c - wifi_manager.h - eth_manager.h - network_manager.h - config.h - wifi_provision.h - README_Gateway.md - led_indicator.h

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考虑
故障排除指南
结论
附录

简介¶

本文件面向ESP32S3 BLE网关的网络连接问题，提供系统化的故障排除与优化指南。内容覆盖WiFi连接失败、DHCP获取失败、以太网连接异常等常见问题；提供网络状态检查命令、IP配置验证方法、路由跟踪工具使用建议；说明WiFi密码错误、路由器不兼容、信号干扰等诊断步骤；包含网络配置重置、DNS解析测试与防火墙规则检查的操作指引；并给出网络性能优化、带宽监控与连接稳定性改善的方法。

项目结构¶

该仓库采用分层模块化设计：应用层（WebUI/REST/MQTT）、核心层（BLE网关/网络管理/配置管理）、驱动层（HCI传输/以太网/WiFi）与硬件层（nRF52833/CH390D/WLAN/GPIO）。网络相关的关键路径包括： - 启动流程：主程序根据配置选择以太网或WiFi模式，初始化网络子系统，进入服务阶段。 - 网络模式：支持仅以太网、仅WiFi、以太网优先、WiFi优先四种模式，并具备自动切换能力。 - 状态反馈：通过LED指示灯与日志输出提供网络状态可视化反馈。

graph TB
subgraph 应用层
WEBUI["WebUI 服务器"]
REST["REST API"]
MQTT["MQTT 客户端"]
end
subgraph 核心层
BLE["BLE 网关"]
NET["网络管理器"]
CFG["配置管理器"]
end
subgraph 驱动层
HCI["HCI 传输"]
ETH["以太网管理器"]
WIFI["WiFi 管理器"]
LED["LED 指示灯"]
end
subgraph 硬件
NRF["nRF52833"]
CH390["CH390D"]
WLAN["WiFi 收发器"]
GPIO["GPIO"]
end
WEBUI --> REST
REST --> BLE
REST --> CFG
MQTT --> BLE
MQTT --> CFG
BLE --> HCI
NET --> ETH
NET --> WIFI
HCI --> NRF
ETH --> CH390
WIFI --> WLAN
LED --> GPIO

图表来源 - README_Gateway.md

章节来源 - README_Gateway.md

核心组件¶

网络模式与状态
网络模式枚举：仅以太网、仅WiFi、以太网优先、WiFi优先。
网络状态：断开、以太网已连、WiFi已连、AP模式。
WiFi管理器
提供STA/AP模式切换、连接/断开、扫描、状态查询、IP字符串获取等接口。
内部维护连接状态、RSSI、信道、MAC、IP/掩码/网关等信息。
以太网管理器
基于CH390D SPI驱动，提供链路状态、速度、双工、IP/掩码/网关等信息。
网络管理器
统一协调ETH/WiFi的初始化、启动、停止、模式切换与状态汇总。
配置与引导
默认网络模式、WiFi AP参数、引脚定义等全局配置。
WiFi引导（AP+Web门户）用于首次配置与凭据保存。

章节来源 - config.h - network_manager.h - wifi_manager.h - eth_manager.h - wifi_manager.c - eth_manager.c

架构总览¶

下图展示从主程序到网络子系统的调用关系与职责分工。

sequenceDiagram
participant Main as "主程序"
participant LED as "LED指示灯"
participant NVS as "NVS"
participant NET as "网络管理器"
participant ETH as "以太网管理器"
participant WIFI as "WiFi 管理器"
participant Prov as "WiFi 引导"
participant SVC as "服务(REST/MQTT/WebUI)"
Main->>LED : 初始化LED(闪烁)
Main->>NVS : 初始化NVS
Main->>Main : 加载配置
Main->>NET : 初始化(按配置模式)
NET->>ETH : 初始化(如需要)
NET->>WIFI : 初始化(如需要)
NET->>NET : 启动(按模式)
alt 以太网优先
NET->>ETH : 启动以太网
ETH-->>NET : 已连/未连
NET->>WIFI : 启动WiFi(备用)
else WiFi优先
NET->>WIFI : 启动WiFi
WIFI-->>NET : 已连/未连
NET->>ETH : 启动以太网(备用)
end
Main->>SVC : 启动HTTP/WS/MQTT服务
Main->>LED : 系统就绪(常亮)

图表来源 - main.c - network_manager.h - eth_manager.c - wifi_manager.c

详细组件分析¶

WiFi连接与状态检查¶

关键接口
连接/断开：wifi_manager_connect、wifi_manager_disconnect
状态查询：wifi_manager_is_connected、wifi_manager_get_state、wifi_manager_get_status
IP查询：wifi_manager_get_ip_str
扫描：wifi_manager_scan
事件与状态
连接事件：WIFI_EVENT_STA_CONNECTED、WIFI_EVENT_STA_DISCONNECTED
IP事件：IP_EVENT_STA_GOT_IP、IP_EVENT_STA_LOST_IP
最多重试次数：MAX_RETRY（内部逻辑）
故障定位要点
若长时间处于“连接中”，检查WIFI_EVENT事件是否触发连接成功或断开事件。
若IP事件未触发，确认DHCP客户端是否正常运行（路由器侧DHCP可用性）。
若断开频繁，查看断开原因码并结合信号强度与干扰情况分析。

flowchart TD
Start(["开始连接"]) --> SetCfg["配置STA参数<br/>SSID/密码/认证方式"]
SetCfg --> StartSTA["启动STA并发起连接"]
StartSTA --> WaitEvt{"等待事件"}
WaitEvt --> |连接成功| GotIP["等待IP事件"]
WaitEvt --> |断开事件| Retry{"重试次数 < 最大值?"}
Retry --> |是| Reconnect["重新连接"]
Retry --> |否| Fail["连接失败"]
GotIP --> HasIP{"获得IP?"}
HasIP --> |是| OK["连接成功"]
HasIP --> |否| LostIP["丢失IP/未获IP"]
LostIP --> WaitEvt

图表来源 - wifi_manager.c - wifi_manager.c

章节来源 - wifi_manager.c - wifi_manager.h

以太网连接与状态检查¶

关键接口
初始化/启动/停止：eth_manager_init、eth_manager_start、eth_manager_stop
状态查询：eth_manager_is_connected、eth_manager_get_state、eth_manager_get_status
IP查询：eth_manager_get_ip_str
事件与状态
链路事件：ETHERNET_EVENT_CONNECTED、ETHERNET_EVENT_DISCONNECTED
IP事件：IP_EVENT_ETH_GOT_IP、IP_EVENT_ETH_LOST_IP
速率与双工：通过ioctl查询10/100Mbps与全双工状态
故障定位要点
若链路未UP，检查物理连接、网线、交换机端口指示灯。
若链路UP但无IP，确认DHCP服务器可达，检查网段与ACL策略。
若速率异常，检查网线质量、交换机端口协商设置。

flowchart TD
Init["初始化CH390D驱动"] --> StartEth["启动以太网"]
StartEth --> LinkUp{"链路是否UP?"}
LinkUp --> |否| HWFault["硬件/线缆/交换机问题"]
LinkUp --> |是| WaitIP["等待IP事件"]
WaitIP --> GotIP{"获得IP?"}
GotIP --> |否| DHCPFail["DHCP失败/网络策略限制"]
GotIP --> |是| EthOK["以太网连接成功"]

图表来源 - eth_manager.c - eth_manager.c

章节来源 - eth_manager.c - eth_manager.h

网络模式与切换¶

模式定义
仅以太网、仅WiFi、以太网优先、WiFi优先
切换策略
以太网优先：先尝试以太网，失败则回退到WiFi。
WiFi优先：先尝试WiFi，失败则回退到以太网。
状态汇总
network_manager_get_status返回当前模式、可用性、IP、网关、活跃接口等。

flowchart TD
Start(["启动"]) --> CheckMode{"当前模式?"}
CheckMode --> |ETH_ONLY| UseETH["仅使用以太网"]
CheckMode --> |WIFI_ONLY| UseWIFI["仅使用WiFi"]
CheckMode --> |ETH_PRIMARY| TryETH["优先以太网"]
CheckMode --> |WIFI_PRIMARY| TryWIFI["优先WiFi"]
TryETH --> ETHOK{"以太网已连?"}
ETHOK --> |是| ActiveETH["活跃接口=ETH"]
ETHOK --> |否| UseWIFI
TryWIFI --> WIFIOK{"WiFi已连?"}
WIFIOK --> |是| ActiveWIFI["活跃接口=WIFI"]
WIFIOK --> |否| UseETH

图表来源 - config.h - network_manager.h - main.c

章节来源 - config.h - network_manager.h - main.c

依赖关系分析¶

组件耦合
主程序依赖网络管理器进行模式选择与启动。
网络管理器同时依赖以太网与WiFi管理器，实现双栈协同。
LED指示灯与日志输出作为外部可观测性手段，辅助诊断。
外部依赖
ESP-IDF网络栈（esp-netif、esp-wifi、esp-eth）。
CH390D SPI驱动（esp_eth_mac_ch390、esp_eth_phy_ch390）。
潜在风险
SPI总线初始化冲突（CH390D引脚配置）。
中断引脚配置不当导致事件丢失。
NVS存储空间不足导致配置无法持久化。

graph LR
Main["主程序"] --> NetMgr["网络管理器"]
NetMgr --> EthMgr["以太网管理器"]
NetMgr --> WfiMgr["WiFi 管理器"]
NetMgr --> Prov["WiFi 引导"]
Main --> Led["LED指示灯"]
Main --> Cfg["配置管理器"]

图表来源 - main.c - network_manager.h

章节来源 - main.c - eth_manager.c - wifi_manager.c