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

日期：2026-10-16Zephyr 版本：v4.4.0板级定义：NUCLEO_H5E5ZJ\boards\st\nucleo_h5e5zj验证固件：samples/net/dhcpv4_client
) S0 K2 N9 f, T8 q  |. [

---

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 输出会干扰扩展口引脚。
  
    K! r* X1 p, P; q

1.2 RMII 引脚分配（以原理图为准）RMII 信号MCU 引脚RMII 信号MCU 引脚
9 l3 C0 T, E/ F. C# E  kREF_CLKPA1CRS_DVPD1
. M) \4 T! M- OMDIOPA2RXD0PC4
MDCPC1RXD1PC5
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 */
, X" ^: z0 u7 W. Y/ Q, }6 F&mac {
3 ]9 h4 ]" @. i8 l    status = "okay";
. ?/ t3 `: t  ]6 t; Q7 b" q, Z( ]    pinctrl-0 = <&eth_rmii_rxd0_pc4
             &eth_rmii_rxd1_pc5
             &eth_rmii_ref_clk_pa1
! B$ k; f' a( e. I2 m& Q+ C! F             &eth_rmii_crs_dv_pd1
             &eth_rmii_tx_en_pa5
& J" V% y# Y5 k0 M  P/ S& v# H             &eth_rmii_txd0_pb12
- v5 H& @- ~+ u6 y* x             &eth_rmii_txd1_pg12>;
    pinctrl-names = "default";
3 t  A- S4 B$ W# A( _5 A7 V- Y    phy-connection-type = "rmii";
) |" p% S2 `1 ~7 B" T    phy-handle = <&eth_phy>;
9 t' e  |) |$ ~" H1 E5 K. T};
& t) X+ D1 a1 Y! t8 i* x, Z6 o​
&mdio {
    status = "okay";
    pinctrl-0 = <&eth_mdio_pa2 &eth_mdc_pc1>;
! L+ w/ x* R& V2 ~    pinctrl-names = "default";
​
$ E( x6 h; T2 y& P% c, ^    eth_phy: ethernet-phy@0 {
        compatible = "ethernet-phy";
9 T! K" [9 H, L) i0 \        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 模式。
  
  % p' R' g/ v8 g0 r% U6 z/ G+ G' g# i

2.2 Kconfig（Kconfig.defconfig）if BOARD_NUCLEO_H5E5ZJ
4 U: R. u, [+ K/ o& C0 n​
configdefault NET_L2_ETHERNET
    default y
* d8 b; s3 {' _! I5 C. h​
' S: i* u) V! C4 X9 _2 E0 `$ |endif # 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 的代码路径就对不上了。
  
  # b0 F5 g0 Y# Y: f# ^

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

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

4. 构建与验证
export ZEPHYR_SDK_INSTALL_DIR=/d/Zephyrproject/zephyr-sdk-1.0.1/zephyr-sdk-1.0.1
/ v4 t, \# F7 J9 T​
# U5 f9 U8 ^& q4 s- q( ^west build -b nucleo_h5e5zj zephyr/samples/net/dhcpv4_client -d build_h5e5_net -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
4 C' t5 M9 f; h5 L) U( Wwest 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
( J- Q3 k  N1 {/ k: G" V*** Booting Zephyr OS build v4.4.0-25-ga51fc4394abb ***
( q9 F# Q+ g5 j3 t[00:00:00.051,000] <inf> net_dhcpv4_client_sample: Run dhcpv4 client
, m! C2 D' p& n% d; b$ j[00:00:00.051,000] <inf> net_dhcpv4_client_sample: Start on ethernet: index=1
4 ~4 ^1 O; ]; N* E, m[00:00:02.853,000] <inf> phy_mii: PHY (0) Link speed 100 Mb, full duplex
[00:00:05.941,000] <inf> net_dhcpv4: Received: 192.168.3.15
0 k3 Z) z, L( x+ @) A$ b[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
; V+ \0 u/ U. U6 R) O& C* w[00:00:05.941,000] <inf> net_dhcpv4_client_sample:     Router[1]: 192.168.3.1

PC 侧反向验证：

C:\> ping 192.168.3.15
已发送 = 4，已接收 = 4，丢失 = 0 (0% 丢失)，最短 = 0ms，最长 = 1ms，平均 = 0ms

• PHY ID 0x7C131 = LAN8742A（OUI/型号核对一致）→ MDIO/MDC 通信正常；
• Link up 100 Mb 全双工 → RMII 数据通路正常；
• DHCP 成功 + 双向 ping 通 → MAC 收发包、DMA、中断全部正常。
  
  

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。
  
  6 t4 |! u4 g  ?3 P$ T: q6 i7 _