NUCLEO-H5E5ZJ 以太网（Ethernet）移植记录

日期：2026-10-16Zephyr 版本：v4.4.0板级定义：NUCLEO_H5E5ZJ\boards\st\nucleo_h5e5zj验证固件：samples/net/dhcpv4_client
$ H' v2 K& U5 y

---

1. 硬件分析1.1 方案概述

NUCLEO-H5E5ZJ 通过 LAN8742A-CZ-TR（U17）PHY + RJ45（CN14）支持 10/100M 以太网，PHY 与 STM32H5E5 之间走 RMII 接口。

关键硬件事实（来源：UM3601 §7.11 + MB2129 原理图交叉核对）：

• PHY 自带 25 MHz 晶振（X4），经内部 PLL 从 nINT/REFCLKO 脚输出 50 MHz，作为 RMII_REF_CLK 送给 MCU 的 PA1——MCU 侧无需为以太网提供时钟；
• PHY 复位：LAN8742A 的 nRST（pin 15）经 SB35（0Ω，已贴）接板级 NRST，跟随系统复位，不需要 GPIO 控制复位；
• PHY 地址 = 0（由 RXER/PHYAD0 等 MODE 上下拉电阻 strap 决定；实测 MDIO 扫描到地址 0，ID = 0x7C131）；
• UM3601 提醒：进入低功耗前需把 LAN8742A 置为 power-down（写寄存器 0x00 的 bit11），否则其 REF_CLK 输出会干扰扩展口引脚。
  
  1 x' i5 R1 N/ G. o4 ]

1.2 RMII 引脚分配（以原理图为准）RMII 信号MCU 引脚RMII 信号MCU 引脚
REF_CLKPA1CRS_DVPD1
MDIOPA2RXD0PC4
  j+ j1 m6 H" sMDCPC1RXD1PC5
TX_ENPA5TXD0PB12
TXD1PG12

文档勘误：UM3601 Table 10 末尾列了 "ETH CLK → PD4"，这是从其他板型 UM 拷贝的残留错误——原理图中 PD4 实际接电源开关控制信号 T_PWR_SEL1，与以太网完全无关。UM 表格本身是双栏排版，PDF 文本提取后会错位（例如把 RXD1 错标成 PB7），一切以原理图网络标号 RMII.xxx 为准。

与 LED 无冲突：本板 RMII_RXD1 走 PC5（部分 Nucleo 板型占用 PE5，会与 LD3 冲突，本板不存在此问题）。

2. Zephyr 侧改动2.1 设备树（nucleo_h5e5zj.dts）/* LAN8742A PHY (U17), RMII; PHY nRST tied to board NRST via SB35, addr 0 */
: }2 _' |6 {# @, {; e. P( e& |&mac {
* d: |( d' E2 u  x- U0 {    status = "okay";
; d& o( V9 s* k* S% Y' ~: O    pinctrl-0 = <&eth_rmii_rxd0_pc4
) o; B7 h4 j. m! G% l             &eth_rmii_rxd1_pc5
3 f6 G+ A* q* X! a1 o. P  Z             &eth_rmii_ref_clk_pa1
% n4 O, T+ z7 E             &eth_rmii_crs_dv_pd1
             &eth_rmii_tx_en_pa5
             &eth_rmii_txd0_pb12
             &eth_rmii_txd1_pg12>;
    pinctrl-names = "default";
    phy-connection-type = "rmii";
    phy-handle = <&eth_phy>;
+ y: N- |/ q* N};
/ W2 q- h. E. C( y6 E​
' u* N$ b* ]" G&mdio {
1 o/ s/ t$ `1 x- i( o% _1 B    status = "okay";
! _1 C3 S, [; E1 @8 o  {: I+ R4 |    pinctrl-0 = <&eth_mdio_pa2 &eth_mdc_pc1>;
    pinctrl-names = "default";
​
    eth_phy: ethernet-phy@0 {
# T- f) Q( b* x! B        compatible = "ethernet-phy";
1 v- g- n1 O" J/ M        reg = <0x00>;
    };
};

说明：

• &mac/&mdio 节点由 stm32h5e5.dtsi ← stm32h5e4.dtsi ← stm32h563.dtsi 继承链提供，直接使能即可；
• pinctrl 节点来自 hal_stm32 模块的 dts/st/h5/stm32h5e5zjtx-pinctrl.dtsi，注意 H5E/H5F 系列的命名是 eth_rmii_*（而 H563 等老系列是 eth_rxd0_pc4 这种无前缀风格，抄板子配置时别混用）；
• phy-connection-type = "rmii" 必须写，驱动据此配置 SYSCFG 的 RMII 模式。
  
  8 p# J6 `3 E( n. |6 g7 J

2.2 Kconfig（Kconfig.defconfig）if BOARD_NUCLEO_H5E5ZJ
8 D: W8 }# B8 y. `1 {7 {: @3 t​
/ s/ c) m$ U- R! Yconfigdefault NET_L2_ETHERNET
    default y
​
( q% p( z/ M( b0 [) Tendif # BOARD_NUCLEO_H5E5ZJ

这里有个坑（详见 §3）：不要照抄 stm32h5f5j_dk 的 configdefault ETH_DRIVER，在 Zephyr v4.4 中必须默认打开 NET_L2_ETHERNET；ETH_DRIVER 自身带 default y if NET_L2_ETHERNET，链路会自动闭合，ETH_STM32_HAL 由设备树 DT_HAS_ST_STM32_ETHERNET_ENABLED 自动使能。

2.3 其他

• nucleo_h5e5zj.yaml 的 supported 增加 netif:eth；
• 时钟无需改动：RMII 50 MHz 由 PHY 提供，MAC 内核时钟走 AHB（PLL 250 MHz 配置见主文档 §4）。
  
  

3. 踩坑记录：NET_L2_ETHERNET 未使能导致的编译错误

现象：配置好设备树后编译 samples/net/dhcpv4_client，报：

subsys/net/lib/shell/iface.c:899: error: implicit declaration of function 'net_eth_get_phy'

排查过程：

• net_eth_get_phy 在 include/zephyr/net/ethernet.h 明明有无条件声明——但 iface.c 顶部的 #include <zephyr/net/ethernet.h> 被 #if defined(CONFIG_NET_L2_ETHERNET) 包着；
• 而调用点 cmd_net_link_speed 由 CONFIG_ETH_PHY_DRIVER 控制；
• 查 autoconf.h 发现 CONFIG_ETH_DRIVER=y、CONFIG_ETH_STM32_HAL=y、CONFIG_ETH_PHY_DRIVER=y，唯独没有 CONFIG_NET_L2_ETHERNET；
• 原因：最初 Kconfig.defconfig 照抄了 stm32h5f5j_dk（上游 main）的 configdefault ETH_DRIVER default y if NETWORKING。但在 Zephyr v4.4 中，ETH_STM32_HAL 不会 select NET_L2_ETHERNET（main 上 Kconfig 结构已变化，不能跨版本照抄），于是出现"驱动编了、L2 没编"的不一致状态，net shell 的代码路径就对不上了。
  
  

修复：参考 nucleo_h563zi / nucleo_f429zi 的 Kconfig.defconfig，默认打开 NET_L2_ETHERNET（见 §2.2）。

经验：跨 Zephyr 版本抄板级 Kconfig 时要小心，同系列新板（main 上的）的写法在旧版本里可能不成立；遇到"隐式声明"错误先查 autoconf.h 里相关配置项的组合是否一致。

4. 构建与验证
$ ]/ n% R* p; d4 jexport ZEPHYR_SDK_INSTALL_DIR=/d/Zephyrproject/zephyr-sdk-1.0.1/zephyr-sdk-1.0.1
​
west build -b nucleo_h5e5zj zephyr/samples/net/dhcpv4_client -d build_h5e5_net -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
( N2 S) @' y) `  B( _west flash -d build_h5e5_net

网线插到 RJ45（CN14），对端需有 DHCP 服务（路由器/交换机）。串口（ST-LINK VCP，115200 8N1）观察启动日志。

实测结果（2026-10-16）[00:00:00.050,000] <inf> phy_mii: PHY (0) ID 7C131
*** Booting Zephyr OS build v4.4.0-25-ga51fc4394abb ***
[00:00:00.051,000] <inf> net_dhcpv4_client_sample: Run dhcpv4 client
& c+ m) X5 W; o7 t' [: _[00:00:00.051,000] <inf> net_dhcpv4_client_sample: Start on ethernet: index=1
* q" `. o. ~& V5 }% R( i[00:00:02.853,000] <inf> phy_mii: PHY (0) Link speed 100 Mb, full duplex
- {: G- q+ `; G& |4 _[00:00:05.941,000] <inf> net_dhcpv4: Received: 192.168.3.15
[00:00:05.941,000] <inf> net_dhcpv4_client_sample:    Address[1]: 192.168.3.15
[00:00:05.941,000] <inf> net_dhcpv4_client_sample:     Subnet[1]: 255.255.255.0
# a8 e" p2 k% ?" b! k[00:00:05.941,000] <inf> net_dhcpv4_client_sample:     Router[1]: 192.168.3.1

PC 侧反向验证：

C:\> ping 192.168.3.15
# J7 F9 C: x# h2 C8 u$ l已发送 = 4，已接收 = 4，丢失 = 0 (0% 丢失)，最短 = 0ms，最长 = 1ms，平均 = 0ms

• PHY ID 0x7C131 = LAN8742A（OUI/型号核对一致）→ MDIO/MDC 通信正常；
• Link up 100 Mb 全双工 → RMII 数据通路正常；
• DHCP 成功 + 双向 ping 通 → MAC 收发包、DMA、中断全部正常。
  
  5 [, J8 X% w% j3 ^, F5 i# R$ q

5. 后续可选

• shell 网络命令：编译带 CONFIG_NET_SHELL=y 的固件后可用 net iface、net ipv4、net ping <ip> 等命令在板子上自测；
• PTP：H5E5 的 MAC 支持 IEEE 1588，需要时在 &mac 上加 ptp-clock 并使能 CONFIG_PTP_CLOCK；
• 低功耗：进低功耗前按 UM3601 要求把 PHY 置 power-down（MDIO 写 reg 0x00 bit11），或断开 R77。