以太网配置管理¶
本文档引用的文件 - ch390.h - esp_eth_mac_ch390.h - esp_eth_phy_ch390.h - esp_eth_mac_ch390.c - esp_eth_phy_ch390.c - eth_manager.h - eth_manager.c - config.h - gateway_config.c - main.c - CH390H_Wiring.md - README.md
目录¶
简介¶
本文件面向以太网配置管理系统，围绕 CH390H 以太网控制器的 SPI 驱动进行深入技术文档编写，涵盖以下主题： - 以太网参数配置：SPI 主机选择、时钟频率设置、DMA 通道配置 - CH390 配置参数、PHY 地址设置、中断引脚配置 - 网络接口配置、MAC 地址获取、网络参数验证 - 静态 IP 配置、DHCP 客户端设置、自动协商配置方法 - 配置参数的动态修改、配置备份恢复、配置验证机制 - 配置故障排除与性能调优建议
本系统基于 ESP-IDF 的以太网框架，使用 CH390H 作为 SPI 接口的以太网控制器，通过 ESP-IDF 的 MAC/PHY 抽象层完成初始化、事件处理与数据收发。
项目结构¶
该仓库采用按功能模块划分的组件化结构，以太网相关的核心位于 components/ch390 与 components/eth_manager，配置信息集中在 include/config.h 与 components/gateway_config。
graph TB
subgraph "应用入口"
MAIN["main.c<br/>应用主程序"]
end
subgraph "以太网管理"
EMH["eth_manager.h<br/>接口定义"]
EMC["eth_manager.c<br/>实现"]
end
subgraph "CH390 驱动"
CMH["esp_eth_mac_ch390.h<br/>MAC 接口"]
PH["esp_eth_phy_ch390.h<br/>PHY 接口"]
CMAC["esp_eth_mac_ch390.c<br/>MAC 实现"]
PDRV["esp_eth_phy_ch390.c<br/>PHY 实现"]
REG["ch390.h<br/>寄存器定义"]
end
subgraph "配置与平台"
CFG["config.h<br/>全局配置"]
GWCFG["gateway_config.c<br/>NVS 配置管理"]
end
MAIN --> EMH
MAIN --> CFG
MAIN --> GWCFG
EMH --> EMC
EMC --> CMH
EMC --> PH
CMH --> CMAC
PH --> PDRV
CMAC --> REG
PDRV --> REG
EMC --> CFG图表来源 - main.c - eth_manager.h - eth_manager.c - esp_eth_mac_ch390.h - esp_eth_phy_ch390.h - esp_eth_mac_ch390.c - esp_eth_phy_ch390.c - ch390.h - config.h - gateway_config.c
章节来源 - main.c - eth_manager.h - eth_manager.c - config.h
核心组件¶
- CH390 MAC 驱动：负责 SPI 读写、帧收发、中断/轮询模式、PHY 寄存器访问、流控配置等。
- CH390 PHY 驱动：负责自动协商、速度/双工/链路状态更新、环回控制等。
- 以太网管理器：封装 ESP-IDF 以太网栈，完成初始化、事件回调、状态查询、IP 获取等。
- 全局配置：定义 SPI 引脚、时钟频率、PHY 地址、中断引脚等硬件参数。
- NVS 配置管理：提供设备名称、WiFi/MQTT/BLE 参数的持久化存储与加载。
章节来源 - esp_eth_mac_ch390.h - esp_eth_phy_ch390.h - eth_manager.h - config.h - gateway_config.c
架构总览¶
下图展示从应用入口到 CH390 控制器的数据通路与控制流：
sequenceDiagram
participant APP as "应用主程序(main.c)"
participant EM as "以太网管理器(eth_manager.c)"
participant MAC as "CH390 MAC 驱动(esp_eth_mac_ch390.c)"
participant PHY as "CH390 PHY 驱动(esp_eth_phy_ch390.c)"
participant REG as "CH390 寄存器(ch390.h)"
participant NET as "ESP-IDF 网络栈"
APP->>EM : 初始化与启动
EM->>MAC : 创建 MAC 实例
EM->>PHY : 创建 PHY 实例
EM->>MAC : 软复位/寄存器默认配置
MAC->>REG : 写入寄存器(默认设置/中断/流控)
EM->>NET : 附加到 TCP/IP 栈
EM->>EM : 注册事件回调(连接/断开/获取 IP)
NET-->>EM : 连接事件/IP 分配事件
EM-->>APP : 回调通知(状态变更)
MAC-->>NET : 接收任务处理帧
NET-->>MAC : 发送帧图表来源 - main.c - eth_manager.c - esp_eth_mac_ch390.c - esp_eth_phy_ch390.c - ch390.h
详细组件分析¶
CH390 MAC 驱动（SPI 以太网 MAC）¶
- SPI 主机与 DMA：驱动内部通过 SPI 设备句柄与互斥量保护访问，支持自定义 SPI 驱动或默认 SPI 驱动；接收缓冲区分配在 DMA 友好内存区域。
- 中断与轮询：支持中断模式（INT 引脚）与轮询模式（定时器），二者二选一；中断模式下通过 ISR 唤醒接收任务。
- 寄存器与内存访问：提供寄存器读写与内部 RAM 读写函数，用于配置寄存器与传输帧数据。
- 默认配置：初始化时执行软件复位、芯片 ID 校验、寄存器默认值写入、多播表清理、MAC 地址读取等。
- 流控：根据对端能力启用/禁用流控，配置高低水位阈值。
- 事件处理：接收任务循环读取中断状态，解析帧头与长度，过滤错误帧，向 TCP/IP 栈提交数据。
classDiagram
class emac_ch390_t {
+parent : esp_eth_mac_t
+eth : esp_eth_mediator_t*
+spi : eth_spi_custom_driver_t
+rx_task_hdl : TaskHandle_t
+int_gpio_num : int
+poll_timer : esp_timer_handle_t
+addr[6] : uint8_t
+flow_ctrl_enabled : bool
+rx_buffer : uint8_t*
+rx_len : uint32_t
+init()
+deinit()
+start()
+stop()
+transmit(buf, len)
+receive(buf, len)
+read_phy_reg(addr, reg)
+write_phy_reg(addr, reg, val)
+set_addr(addr)
+get_addr(out)
+set_promiscuous(enable)
+set_peer_pause_ability(ability)
+enable_flow_ctrl(enable)
}
class eth_spi_custom_driver_t {
+init(cfg)
+deinit()
+read(ctx, cmd, addr, data, len)
+write(ctx, cmd, addr, data, len)
}
emac_ch390_t --> eth_spi_custom_driver_t : "使用"图表来源 - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c
章节来源 - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c
CH390 PHY 驱动（802.3）¶
- 自动协商：读取 BMSR/BMCR/ANLPAR 等寄存器，判断链路、速度与双工；在全双工且对端支持 PAUSE 时启用流控。
- 循环测试：在自动协商开启时禁止环回，在环回开启时禁止自动协商。
- 基础初始化：检查 OUI 与型号，确保为 CH390。
sequenceDiagram
participant MAC as "MAC 驱动"
participant PHY as "PHY 驱动"
participant REG as "PHY 寄存器"
MAC->>PHY : get_link()
PHY->>REG : 读取 BMSR/ANLPAR
REG-->>PHY : 返回状态
PHY->>MAC : 更新链路/速度/双工/对端 PAUSE 能力图表来源 - esp_eth_phy_ch390.c - esp_eth_phy_ch390.c - esp_eth_phy_ch390.c
章节来源 - esp_eth_phy_ch390.c - esp_eth_phy_ch390.c
以太网管理器（eth_manager）¶
- 初始化流程：创建事件组、初始化网络接口、配置 SPI 总线、硬件复位 CH390、创建 MAC/PHY、安装驱动、获取 MAC 地址、附加到 TCP/IP 栈、注册事件处理器。
- 事件处理：处理连接/断开、获取 IP/丢失 IP 事件，维护状态与 IP 信息。
- 查询接口：获取当前状态、是否连接、IP 字符串、速率与双工信息。
- 生命周期：支持启动/停止与反初始化。
flowchart TD
Start(["eth_manager_init"]) --> BusCfg["配置 SPI 总线"]
BusCfg --> Reset["硬件复位 CH390"]
Reset --> CreateMac["创建 CH390 MAC"]
CreateMac --> CreatePhy["创建 CH390 PHY"]
CreatePhy --> Install["安装以太网驱动"]
Install --> GetMac["获取 MAC 地址"]
GetMac --> Attach["附加到 TCP/IP 栈"]
Attach --> RegEvt["注册事件处理器"]
RegEvt --> Done(["初始化完成"])图表来源 - eth_manager.c
章节来源 - eth_manager.c - eth_manager.c
全局配置与 NVS 配置管理¶
- 全局配置（config.h）：定义 SPI 引脚、时钟频率、PHY 地址、中断/复位引脚等硬件参数；同时包含设备名称、MQTT/WiFi/BLE 等系统参数（供其他模块使用）。
- NVS 配置管理（gateway_config.c）：提供配置的加载/保存/重置/校验接口，使用互斥锁保证并发安全；键空间包含设备名、WiFi、MQTT、BLE 等。
章节来源 - config.h - gateway_config.c
依赖关系分析¶
- 应用入口 main.c 依赖 eth_manager 接口，间接依赖 CH390 MAC/PHY 与配置模块。
- eth_manager.c 依赖 ESP-IDF 的以太网与网络接口、GPIO/SPI 驱动、CH390 MAC/PHY 接口与寄存器定义。
- CH390 MAC/PHY 实现依赖寄存器定义与 SPI 访问抽象。
- 配置模块依赖 NVS 与互斥量同步。
graph LR
MAIN["main.c"] --> EMH["eth_manager.h"]
MAIN --> CFG["config.h"]
MAIN --> GWCFG["gateway_config.c"]
EMH --> EMC["eth_manager.c"]
EMC --> CMH["esp_eth_mac_ch390.h"]
EMC --> PH["esp_eth_phy_ch390.h"]
CMH --> CMAC["esp_eth_mac_ch390.c"]
PH --> PDRV["esp_eth_phy_ch390.c"]
CMAC --> REG["ch390.h"]
PDRV --> REG图表来源 - main.c - eth_manager.h - eth_manager.c - esp_eth_mac_ch390.h - esp_eth_phy_ch390.h - esp_eth_mac_ch390.c - esp_eth_phy_ch390.c - ch390.h - config.h - gateway_config.c
章节来源 - main.c - eth_manager.c
性能考虑¶
- SPI 时钟频率：默认 20MHz，可通过配置项调整；过高可能导致 SPI 时序不满足或误读，过低影响吞吐。
- DMA 通道：接收缓冲区分配在 DMA 友好内存区域，有助于提升 DMA 收发效率。
- 中断/轮询：中断模式延迟更低但占用 ISR 资源；轮询模式简单稳定，适合低负载场景。
- 流控：在全双工且对端支持 PAUSE 时启用，可避免上行拥塞导致丢包。
- 任务栈大小：MAC 接收任务栈大小可按需增大，避免栈溢出导致异常。
[本节为通用性能建议，无需特定文件引用]
故障排除指南¶
- 无法获取 IP 或连接失败
- 检查以太网线缆与交换机端口指示灯；确认以太网管理器事件回调是否触发连接/断开事件。
- 查看链路状态与速率/双工信息，确认 PHY 是否正确识别对端能力。
-
SPI 访问失败或帧错误
- 确认 SPI 引脚连接与时钟频率设置；检查 CH390 是否完成软复位与寄存器默认配置。
- 观察接收任务中的错误帧处理逻辑，必要时重启接收子系统。
-
参考路径：esp_eth_mac_ch390.c，esp_eth_mac_ch390.c，esp_eth_mac_ch390.c
-
中断不触发或轮询无效
- 确认 INT 引脚配置与中断类型；若使用轮询模式，检查轮询定时器创建与启动。
-
MAC 地址异常
- 确认从 CH390 寄存器读取 MAC 地址的流程；如需固定 MAC，可在初始化后调用设置接口。
-
NVS 配置未生效
- 确认配置保存成功与键空间有效性；必要时执行重置并重新保存。
- 参考路径：gateway_config.c，gateway_config.c
章节来源 - eth_manager.c - eth_manager.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - gateway_config.c - gateway_config.c
结论¶
本以太网配置管理系统通过 CH390H SPI 驱动与 ESP-IDF 以太网栈的结合，提供了完整的以太网接入能力。通过对 SPI 主机、时钟频率、DMA、中断/轮询、PHY 地址与寄存器配置的统一管理，系统实现了稳定的网络连接与良好的可维护性。配合 NVS 的配置持久化与以太网管理器的状态查询接口，用户可以方便地进行参数动态修改、备份恢复与验证。
[本节为总结性内容，无需特定文件引用]
附录¶
以太网参数配置指南¶
- SPI 主机选择
- 在配置中指定 SPI 主机编号，确保与实际硬件一致。
-
参考路径：config.h
-
时钟频率设置
- 设置 SPI 时钟频率（MHz），默认 20MHz；过高可能引起通信错误。
-
参考路径：config.h，eth_manager.c
-
DMA 通道配置
- 接收缓冲区分配在 DMA 友好内存区域，减少 DMA 访问冲突。
-
参考路径：esp_eth_mac_ch390.c
-
CH390 配置参数
- 包括寄存器默认值、中断控制、流控阈值、接收长度限制等。
-
PHY 地址设置
- 在初始化时设置 PHY 地址，确保与硬件一致。
-
参考路径：eth_manager.c，config.h
-
中断引脚配置
- 配置 INT 引脚与中断类型，或启用轮询模式。
-
网络接口配置、MAC 地址获取与网络参数验证
- 初始化后通过 IOCTL 获取 MAC 地址；通过事件回调获取 IP 与网关信息。
-
静态 IP 配置、DHCP 客户端设置与自动协商配置
- 使用 ESP-IDF 的网络接口配置静态 IP 或 DHCP；自动协商由 PHY 驱动处理。
-
配置参数的动态修改、备份恢复与验证
- 通过 NVS 提供的接口进行保存/加载/重置；对外提供只读指针与有效性检查。
-
硬件接线参考
- 引脚定义与接线图见硬件文档。
- 参考路径：CH390H_Wiring.md，README.md
章节来源 - config.h - eth_manager.c - esp_eth_mac_ch390.c - esp_eth_mac_ch390.c - esp_eth_phy_ch390.c - gateway_config.c - CH390H_Wiring.md - README.md