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

日期：2026-10-16Zephyr 版本：v4.4.0板级定义：NUCLEO_H5E5ZJ\boards\st\nucleo_h5e5zj验证固件：samples/net/dhcpv4_client

---

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.2 RMII 引脚分配（以原理图为准）RMII 信号MCU 引脚RMII 信号MCU 引脚
REF_CLKPA1CRS_DVPD1
, x; `6 G) m! VMDIOPA2RXD0PC4
MDCPC1RXD1PC5
) J$ a; R8 H- J- `! [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 */
&mac {
    status = "okay";
    pinctrl-0 = <&eth_rmii_rxd0_pc4
  E( J. O+ b% T$ I- E* {  I             &eth_rmii_rxd1_pc5
             &eth_rmii_ref_clk_pa1
             &eth_rmii_crs_dv_pd1
# {8 H0 i) c3 n. s             &eth_rmii_tx_en_pa5
' [' c9 {% f3 O0 n: f             &eth_rmii_txd0_pb12
" G/ C6 u7 I& \2 G, i) |             &eth_rmii_txd1_pg12>;
    pinctrl-names = "default";
    phy-connection-type = "rmii";
    phy-handle = <&eth_phy>;
" m: q7 E& |  D7 T2 r};
) H4 E" q( H$ b; N0 W+ S( ^​
&mdio {
    status = "okay";
    pinctrl-0 = <&eth_mdio_pa2 &eth_mdc_pc1>;
    pinctrl-names = "default";
1 f: t* [4 h4 y& W& G' Z+ z​
& z! Q" b9 r/ R( j    eth_phy: ethernet-phy@0 {
        compatible = "ethernet-phy";
7 a; S  T+ \0 {        reg = <0x00>;
    };
7 w$ Q+ `- w7 B* |1 F& v+ I9 o};

说明：

• &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 模式。
  
  

2.2 Kconfig（Kconfig.defconfig）if BOARD_NUCLEO_H5E5ZJ
3 f0 }/ |9 p! e( L9 p, b​
- O: f- T+ a- B* [configdefault NET_L2_ETHERNET
) @1 m9 J- k* A# P    default y
; y  b% a* i  A5 e" \3 ~5 s$ l​
6 \4 E6 [; z$ d& Q: ~- b8 U/ t% mendif # 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）。
  
  5 f$ k; U  v& j

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 的代码路径就对不上了。
  
  5 J# J) |! [+ e6 z3 M" |3 K

修复：参考 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
​
west build -b nucleo_h5e5zj zephyr/samples/net/dhcpv4_client -d build_h5e5_net -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
  {* P- S3 `# @# Zwest 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
! ~7 T  R& E, c& m8 }: O! n[00:00:00.051,000] <inf> net_dhcpv4_client_sample: Start on ethernet: index=1
, e. S0 O, X. D% y3 {5 p6 Z1 L1 j[00:00:02.853,000] <inf> phy_mii: PHY (0) Link speed 100 Mb, full duplex
7 V9 w4 }$ V" }: c1 w9 r% h[00:00:05.941,000] <inf> net_dhcpv4: Received: 192.168.3.15
* `3 a8 S3 A& U( ~% ~0 R2 c[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" W0 b( I  ?7 @7 d  S[00:00:05.941,000] <inf> net_dhcpv4_client_sample:     Router[1]: 192.168.3.1

PC 侧反向验证：

C:\> ping 192.168.3.15
$ O: Z' f$ o. d0 U3 z# Q( x& _已发送 = 4，已接收 = 4，丢失 = 0 (0% 丢失)，最短 = 0ms，最长 = 1ms，平均 = 0ms

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

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。
  
  9 y" u$ O* W2 _1 }" F2 Q