NUCLEO-H5E5ZJ 移植 LVGL（ST7735 LCD + 五向摇杆）

日期：2026-10-16Zephyr 版本：v4.4.0（LVGL v9）目标板：NUCLEO-H5E5ZJ（STM32H5E5ZJT6）移植产物：D:\STM32\STM32H5E5\NUCLEO_H5E5ZJ\apps\lvgl_demo

---

0. 效果

LCD 显示 LVGL 菜单界面：标题 Joystick Menu + 4 个菜单按钮（LED1 GREEN / LED2 RED / LED3 BLUE / About）+ 底部状态行。LCD 扩展板上的五向摇杆导航：上下/左右移动焦点（黄色高亮框），按下确认——前 3 项直接翻转板载 LD1/LD2/LD3，状态行同步显示 LDx ON/OFF。已在实物上验证通过。

1. 系统架构五向摇杆(电阻分压)                    ST7735 LCD
       │                                  ▲
       ▼ 模拟电压                          │ SPI4 @10MHz
ADC1_INP9 (PB0, Arduino A3)               │
       │                                  │
       ▼                                  │
3 U. s; I+ I. rZephyr adc-keys 输入驱动                   │   ┌─────────────────────┐
* u: x( k) h! n& ]4 P(50ms 轮询 + 最近阈值匹配 + 消抖)            │   │ lcd_bare 裸 SPI 驱动  │
$ B% m  b. T! B) H& l+ h" S! `' g3 n       │ INPUT_KEY_* 事件                  ├──▶│ display_bare shim    │
* ^" G9 ^  N) b+ W% \- C       ▼                                  │   │ (Zephyr display API) │
# R& P" g& e' o+ T2 p7 e; D& [" jzephyr,lvgl-keypad-input                  │   └─────────────────────┘
(input-codes → lvgl-codes 映射)            │            ▲
       │ LV_KEY_*                         │ display_write(RGB565)
       ▼                                  │            │
+ x8 n1 e: |& ]4 e* z- MLVGL keypad indev → lv_group 焦点组 ──────┴─── LVGL 渲染(lv_timer_handler)

LVGL 显示与输入在 Zephyr 中全部通过设备树声明对接，应用代码零胶水。

2. 硬件连接（LCD 扩展板插 Arduino 排针）功能Arduino 位H5E5ZJ 引脚外设
6 c3 U2 l, [0 _& z3 n. pSPI_SCKD13PE12SPI4_SCK
SPI_MISOD12PE13SPI4_MISO
" t6 H" o# v* s% {SPI_MOSID11PE14SPI4_MOSI
LCD CSD10PE11GPIO（软件控制）
: `6 m. d1 K7 h; U: KLCD DCD8PA9GPIO
+ r6 b# l' S: W+ m- f( u8 S五向摇杆A3PB0ADC1_INP9

引脚依据为 MB2129 原理图第 5 页连接器部分：

摇杆原理

电阻分压式：3.3 V 经上拉，拨向某方向把对应电阻短到 GND，输出不同分压。ADC（12 位，3.3 V 基准）实测各方向电压：

方向ADC raw（约）电压（约）press-thresholds-mv
右8871 mV71
1 n0 J% e- e9 ]" p上738595 mV595
确认（按下）13101055 mV1055
左20481650 mV1650
下33762720 mV2720
  i7 w+ D! s5 D+ Z+ F+ U4 c% H" s松开（开路）40953298 mVkeyup = 33003. 逐步实现第 1 步：应用骨架apps/lvgl_demo/
* R% l+ R* g" ^( \├── CMakeLists.txt
├── prj.conf
+ y# K" s! l7 l: E3 K├── boards/nucleo_h5e5zj.overlay
├── dts/bindings/display/
( v5 H; C$ j5 d8 s' Z5 U│   ├── uniknect,lcd-bare.yaml   # display shim 绑定
+ ?4 q6 s7 F. m2 c│   └── uniknect,lcd-io.yaml     # LCD DC/CS GPIO 绑定
7 \' l4 P/ ^, e5 U4 `└── src/
    ├── main.c                   # LVGL 菜单 UI + 摇杆焦点组
    ├── lcd_bare.c / lcd_bare.h  # ST7735 裸 SPI 驱动（板级无关）
  X" e8 h0 R! c' L5 J  y    ├── display_bare.c           # Zephyr display API shim（LVGL 的显示后端）
5 a7 K# _2 ?& }) y% I% a    └── font_petme128_8x8.h第 2 步：overlay —— 摇杆接入 Zephyr 输入子系统

Zephyr 自带 adc-keys 输入驱动（drivers/input/input_adc_keys.c），专为电阻分压式按键设计：按 sample-period-ms 轮询 ADC，找电压最接近的阈值判定按键，内置两周期消抖，无需自写驱动：

#include <zephyr/dt-bindings/input/input-event-codes.h>
: w5 }7 h- U* V, _#include <zephyr/dt-bindings/lvgl/lvgl.h>
​
/ {
% V! C3 g+ I- N" B  _    joystick: joystick {
7 i- v6 D2 U3 H        compatible = "adc-keys";
        io-channels = <&adc1 9>;
        sample-period-ms = <50>;
$ {! d) K% d! w        keyup-threshold-mv = <3300>;          /* 松开=开路电压 */
( ?9 D* v4 T* ]  |" p​
        key_right  { press-thresholds-mv = <71>;   zephyr,code = <INPUT_KEY_RIGHT>; };
% t" P6 d7 a" r: k, z& q/ `# B! _. d2 x        key_up     { press-thresholds-mv = <595>;  zephyr,code = <INPUT_KEY_UP>; };
        key_center { press-thresholds-mv = <1055>; zephyr,code = <INPUT_KEY_ENTER>; };
6 m6 s4 F& w4 Z& F        key_left   { press-thresholds-mv = <1650>; zephyr,code = <INPUT_KEY_LEFT>; };
# i1 h  V( R: o9 t0 A, c        key_down   { press-thresholds-mv = <2720>; zephyr,code = <INPUT_KEY_DOWN>; };
; I8 v; L4 U' l$ X    };
};

ADC 通道配置（v4.4 的 H5E5 设备树中 adc1 是独立节点，无 adc12_common 包装层，adc_ker 时钟和分频直接写在 &adc1 上）：

&adc1 {
    clocks = <&rcc STM32_CLOCK(AHB2, 10)>,
         <&rcc STM32_SRC_HCLK ADCDAC_SEL(0)>;
0 @/ w. R% R: z! D6 i    clock-names = "adcx", "adc_ker";
# W) Q4 |9 c: X$ n    pinctrl-0 = <&adc1_inp9_pb0>;
; t" K. h2 e4 D8 d( w    pinctrl-names = "default";
  Q3 ~* T% D5 @9 I( i9 M2 L    st,adc-clock-source = "ASYNC";
    st,adc-prescaler = <6>;
' C9 p  s! M" `# o    status = "okay";
1 R# f. V  n/ r( T% M1 w    #address-cells = <1>;
    #size-cells = <0>;
" x* `0 z2 G$ \$ u8 b5 q​
    channel@9 {
& `) x* {& f* i+ i9 @        reg = <9>;
! M% K- l' }) {- I0 d1 D" x        zephyr,gain = "ADC_GAIN_1";
        zephyr,reference = "ADC_REF_INTERNAL";
! g) S+ x' T8 F3 a2 J4 M& e        zephyr,vref-mv = <3300>;          /* adc-keys 按 mV 判定，必须给基准 */
9 y3 m- e' |- h        zephyr,acquisition-time = <ADC_ACQ_TIME_MAX>;
        zephyr,resolution = <12>;
: R% Q! }, ^* p7 o) n8 }    };
};第 3 步：overlay —— 输入事件映射给 LVGL（关键踩坑点）

Zephyr 的 LVGL 模块提供 zephyr,lvgl-keypad-input 伪设备：监听指定输入设备的 INPUT_KEY_* 事件，按 input-codes→lvgl-codes 表翻译成 LV_KEY_* 注入 LVGL keypad 输入设备：

/ {
) b+ `, j0 ~+ K6 ?  Q  m6 X    lvgl_keypad {
        compatible = "zephyr,lvgl-keypad-input";
  N" u* k4 P, X/ \5 ^; J        input = <&joystick>;
+ s* f# x* L  t$ y* y        input-codes = <INPUT_KEY_UP INPUT_KEY_DOWN INPUT_KEY_LEFT INPUT_KEY_RIGHT
                   INPUT_KEY_ENTER>;
        lvgl-codes = <LV_KEY_PREV LV_KEY_NEXT LV_KEY_PREV LV_KEY_NEXT
6 i9 @6 y# B: l; T- T- \; c                  LV_KEY_ENTER>;
    };
; k8 f0 g- o( u+ l};

踩坑记录：最初把方向映射成 LV_KEY_UP/DOWN/LEFT/RIGHT，结果确认键正常、方向完全不动。原因是 LVGL 中 LV_KEY_PREV/NEXT 才负责移动焦点组焦点，方向键是派发给当前焦点控件自己处理的（按钮不处理方向）。用 INPUT_CALLBACK_DEFINE(NULL, cb, NULL) 打印全部输入事件确认事件码正确（上=103/下=108/左=105/右=106）后，定位为 LVGL 侧映射问题，改映射为 PREV/NEXT 即恢复。菜单类导航的正确映射：上/左→LV_KEY_PREV，下/右→LV_KEY_NEXT，确认→LV_KEY_ENTER。

LCD 部分（SPI4 + lcd_bare + lcd_io 节点）与纯 LCD 工程相同，不重复展开。

第 4 步：prj.confCONFIG_GPIO=y
! x% L! w# O$ ]8 _; D/ p" hCONFIG_SPI=y
2 t% ]8 W8 M2 f  u: nCONFIG_DISPLAY=y
: h& G3 B- G) d: ZCONFIG_ADC=y
CONFIG_INPUT=y          # adc-keys / lvgl-keypad-input 均 default y（节点使能即生效）
+ F* Z/ z! ?( h( V, f  J​
) P7 L0 V9 C  v0 L  S3 J, ~" V% `CONFIG_MAIN_STACK_SIZE=4096
  I6 C2 W0 J8 ?+ H( O+ N​
CONFIG_LVGL=y
% j2 B1 X5 ]# ~) u" \CONFIG_LV_Z_MEM_POOL_SIZE=16384
) A$ Z- t) {  J/ |CONFIG_LV_COLOR_DEPTH_16=y
CONFIG_LV_COLOR_16_SWAP=y    # 与 display_bare shim 约定：LVGL 缓冲即大端 RGB565，直透传
2 `0 z3 O1 [/ g+ w" JCONFIG_LV_USE_BUTTON=y
4 x: P; S2 q+ `# ~, o& e6 KCONFIG_LV_USE_LABEL=y

CONFIG_LV_COLOR_16_SWAP=y 必须与 display shim 的字节序约定一致（shim 不做逐像素交换，直接透传 SPI）。

第 5 步：应用代码要点（src/main.c）/* 1. 找到 LVGL keypad 输入设备并绑定焦点组 */
+ n/ k0 J/ O3 Slv_indev_t *indev = NULL;
while ((indev = lv_indev_get_next(indev)) != NULL) {
    if (lv_indev_get_type(indev) == LV_INDEV_TYPE_KEYPAD) {
        keypad = indev;
    }
}
lv_group_t *group = lv_group_create();
/* lv_group_add_obj(group, btn); 每个菜单项都加入 */
/ P& E+ C, X' R1 f* {. Ilv_indev_set_group(keypad, group);
​
/* 2. 焦点可见性：给菜单按钮加 FOCUS_KEY/FOCUSED 两个状态的样式 */
. q! K3 C& G& V/ q& ~. @& qlv_obj_add_style(btn, &style_focus, LV_STATE_FOCUS_KEY);
lv_obj_add_style(btn, &style_focus, LV_STATE_FOCUSED);
​
/* 3. 主循环 */
/ T- c# `! M. x. @8 V% Tdisplay_blanking_off(display_dev);
while (1) {
    uint32_t sleep_ms = lv_timer_handler();
    k_msleep(MIN(sleep_ms, 20));
/ R0 S. @3 q: ?2 D3 w2 x}

输入事件在 lv_timer_handler() 内部从消息队列取出处理，主循环单线程即可，无需额外同步。

第 6 步：编译、烧录、验证cd /d/luglZephyrproject
, Z+ @: ~$ n$ _2 \( j0 N8 nexport ZEPHYR_SDK_INSTALL_DIR=/d/luglZephyrproject/zephyr-sdk-1.0.1/zephyr-sdk-1.0.1
​
west build -b nucleo_h5e5zj /d/STM32/STM32H5E5/NUCLEO_H5E5ZJ/apps/lvgl_demo \
9 K6 r6 O. j( {; i' G6 A% c% }  -d build_h5e5_lvgl -p always -- -DBOARD_ROOT=D:/STM32/STM32H5E5/NUCLEO_H5E5ZJ
west flash -d build_h5e5_lvgl

实测结果（2026-10-16）：

• 菜单正常渲染，字体/颜色正确（RGB565 字节序约定有效）；
• 摇杆上/下/左/右：焦点框在 4 个菜单项间循环移动；
• 摇杆按下：触发当前项，板载 LD1/LD2/LD3 随之翻转，状态行显示 LDx ON/OFF。
  
  + Z1 ~/ a. A" x( t0 |1 c

4. 经验总结

• 电阻分压式摇杆不要自己写驱动：Zephyr 自带 adc-keys 输入驱动（最近阈值匹配 + 消抖），dts 里填电压阈值即可；通道记得配 zephyr,vref-mv，驱动按 mV 判定；
• LVGL 菜单导航映射 LV_KEY_PREV/NEXT，不是方向键——方向键发给焦点控件自用，这是本次唯一的逻辑踩坑点；
• 输入链路可分段验证：INPUT_CALLBACK_DEFINE(NULL, cb, NULL) 全局打印输入事件，先确认事件码（上=103/下=108/左=105/右=106/确认=28）再查 LVGL 侧；
• 显示与输入的对接全部在设备树声明（zephyr,display + zephyr,lvgl-keypad-input），应用代码只负责建 UI 和焦点组；
• 自定义 dts 节点的 GPIO 属性必须写绑定（type: phandle-array），同 LCD 工程的经验。
  
  8 y/ A6 s0 P* Y- f6 m