教程前言
在Zynq嵌入式工业开发中，LCD触控人机交互界面（HMI）是工业网关、智能终端、工控设备的核心功能。本文基于米联客H3-CZ08P-7100（Zynq7100）开发板，复刻官方QT触控屏完整方案，从零讲解硬件工程解析、设备树配置、系统构建、QT交叉编译、板级触控演示全流程。
教程全程基于官方REV2024版demo文档，无删减、无魔改，适配Zynq7000系列ARMHF架构，新手可直接跟着步骤落地触控显示项目，解决LCD无画面、触控失灵、QT程序无法运行等常见问题。
✅ 开发环境与硬件适配
- 硬件平台：米联客 H3-CZ08P-7100（Zynq7100）
- 软件工具版本：Vivado2021.1 + Vitis2021.1
- 系统环境：Ubuntu18.04 64位
- 核心开发包：uisrc-lab-xlnx20220601、uisrc-lab-qt-armhf.tar.gz
- 实现功能：VDMA帧缓存画面输出、GT9157触控IC驱动、I2C触控数据交互、QT触控应用程序运行、屏幕滑动触控
一、方案原理与系统架构
1.1 核心功能简介
本方案实现LCD画面显示+多点触控一体化功能：通过VDMA驱动实现Framebuffer图像输出，依托I2C总线驱动GT9157触控芯片，注册Linux Input子系统，最终基于QT框架开发触控交互程序，实现屏幕滑动、触控响应等人机交互效果。
⚠️ 重点说明：本方案实现的是Linux标准input子系统触控功能，并非系统全局触控界面，仅适配QT应用程序触控交互。
1.2 硬件驱动架构
- 显示驱动：VDMA驱动，提供Framebuffer显存管理，负责LCD画面渲染输出
- 触控驱动：I2C总线驱动，适配GT9157触控芯片，采集触控坐标、手势数据
- 背光驱动：PWM背光控制接口，支持屏幕亮度调节
二、Vivado硬件工程解析（H3-CZ08P-7100专属）
无需自行搭建BD工程，直接使用官方配套demo工程即可，重点掌握硬件资源配置要点：
2.1 关键硬件接口资源
- lcd_*系列接口：LCD屏幕图像显示专用数据接口
- lcd_pwm：屏幕背光亮度PWM控制引脚
- gpio_rtl：触控芯片复位控制引脚
- lcd_iic：触控I2C数据采集与复位接口
2.2 寄存器地址说明
VDMA、I2C、GPIO相关寄存器地址由Vivado综合后自动生成，Vitis导出设备树时会自动适配填充，新手无需手动修改寄存器参数，保证硬件资源匹配H3-CZ08P-7100板卡引脚定义。
三、设备树配置解析（核心关键）
❌ 新手禁止随意修改设备树，建议直接使用官方demo自带设备树文件，仅需理解核心节点作用。
3.1 LCD显示设备树节点
对应内核驱动路径：/uisrc-lab-xlnx/sources/kernel/drivers/video/fbdev/vdmafb.c
核心配置要点：
- 配置dmas属性，绑定VDMA控制器地址，匹配硬件axi_vdma_0节点
- 本工程采用3缓存VDMA架构，必须将park参数设置为1，否则画面闪烁、无显示
3.2 GT9157触控设备树节点
对应内核驱动路径：/uisrc-lab-xlnx/sources/kernel/drivers/input/touchscreen/gt9xx
核心配置要点：
- 直接挂载在系统根节点下，可与zynqmp默认i2c0节点共存，无冲突
- 固定reg地址为0x14，匹配H3-CZ08P-7100板卡I2C触控芯片硬件地址
- 自动注册为Linux Input子系统设备，上电自动识别触控设备
四、系统工程搭建与镜像编译
4.1 前置文件准备
从官方demo包中提取核心工程文件，适配H3-CZ08P-7100：
- boot启动文件：替换SD卡boot分区，适配任意合法文件系统
- QT工程文件：包含PC端编译工程与板端运行压缩包
- 系统工程文件：soc_dts(设备树)、soc_hw(硬件配置)、soc_prj(Vivado工程)、soc_sdk(Vitis工程)
开发包下载地址（官方原版）：02_米联客uisrc-lab-Zynq|MPSoc Linux开发环境|镜像下载 - 资料下载 FPGA+AI数字世界 -
4.2 核心文件拷贝部署
进入系统开发包路径/uisrc-lab-xlnx/boards/mz7x/ubuntu/output/files，放置对应文件：
- 直接放置：fsbl.elf、system_wrapper.bit
- 内核设备树：放入kernel-dts文件夹（支持多文件include引用）
- Uboot设备树：仅支持命名为zynq-mz7x.dts的文件，不支持include
4.3 一键编译系统镜像
进入脚本目录，依次执行编译命令，全程自动化构建：
Plain Text |
执行分区时输入设备号sdb，确认y即可完成系统烧录。
五、QT程序交叉编译（ARMHF架构）
H3-CZ08P-7100为Zynq7000架构，必须使用armhf版本QT交叉编译工具。
5.1 部署QT编译环境
工具包下载地址：05_Linux资料常用软件&环境下载备用链接(2024版) - 资料下载 FPGA+AI数字世界 -
Plain Text |
5.2 编译官方触控Demo
Plain Text |
5.3 部署QT程序到开发板
- 将编译生成的可执行文件替换qt_play文件夹内程序；
- 修改run_arm_app.sh脚本，替换为新程序文件名；
- 将整个qt_play文件夹拷贝至SD卡根文件系统/home/uisrc目录；
- 安全弹出SD卡，准备板级测试。
六、H3-CZ08P-7100板级实操演示
6.1 硬件接线
- 开发板插入烧录好系统的SD卡，拨码切换为SD卡启动模式；
- 连接LCD触控屏幕、串口USB、5V电源；
- 串口波特率设置115200，打开PuTTY等待开机。
6.2 系统登录与程序运行
开机完成后使用官方默认账号密码登录：
- 账号：uisrc
- 密码：root
此时LCD屏幕自动加载系统命令行界面，执行QT触控程序：
Plain Text |
6.3 功能验证
程序启动后，LCD屏幕显示可滑动气泡界面，支持手指触控、滑动拖拽，触控响应灵敏，无卡顿、无失灵，代表整套QT触控方案部署成功。
七、常见问题排查（H3-CZ08P-7100专属）
问题1：屏幕无画面、黑屏
- 未使用配套VDMA设备树，park参数未设置为1；
- 镜像未重新编译，Framebuffer驱动未加载；
- LCD背光PWM引脚未正常初始化。
问题2：有画面但触控无响应
- GT9157设备树reg地址与硬件不匹配；
- I2C驱动未加载，Input子系统未识别触控设备；
- 触控复位引脚硬件接线异常。
问题3：QT程序编译报错、无法运行
- 误用aarch64版本QT工具，Zynq7100需使用armhf版本；
- QT环境变量未正确加载，编译架构不匹配。
八、项目拓展总结
本文实现的基于QT的LCD触控方案，是Zynq工业人机界面开发的基础模板。基于本工程可快速拓展：工业参数触控配置、动态数据显示、按键交互、界面动画、多页面切换等功能，完全适配H3-CZ08P-7100工业板卡的工控、智能终端、物联网网关项目场景。
