简介这是一套面向嵌入式GUI开发工程师与C进阶学习者的开源触摸屏开发全栈资源聚焦HmiFuncDesigner设计工具与HmiRunTime运行时系统的源码级技术交流。资源提供完整可编译的工程体系含2000个文件、21.15MB ZIP包主体为704个C源文件实现核心逻辑、669个头文件支撑模块化封装、139个PNG图像UI资源、71个Qt UI文件界面布局及87个C语言文件底层适配辅以Python/Shell脚本、TypeScript配置与Qt专用元对象文件体现跨语言协同开发特性。已有259人学习下载适合希望深入理解工业级触摸屏编辑器架构、掌握Qt嵌入式GUI混合开发流程、复用HmiRunTime运行时机制的开发者。资源包含HmiFuncDesignerBin与HmiRunTimeBin两个可执行二进制目录支持开箱即用验证配套readme.txt提供快速上手指南License文件明确开源合规边界是开展二次开发、性能调优与教学演示的高价值实践基座。1. HmiFuncDesigner 不是“又一个触摸屏组态工具”而是面向工业 HMI 开发者的开源协同设计中枢很多人第一次看到 HmiFuncDesigner会下意识把它归类为“类似 WinCC 或 MCGS 的国产替代组态软件”——这种理解既低估了它的技术定位也错失了它真正解决的问题。HmiFuncDesigner 的核心价值不在“运行时渲染能力有多强”而在于它把HMI 工程的设计过程本身变成了可版本化、可协作、可复现的软件开发流程。它用 Qt/C 实现跨平台编辑器用 JSON Schema 定义画面结构与逻辑绑定用 Git 友好的文本化资源组织方式替代传统二进制工程包。这意味着设计师改一个按钮颜色提交的是带 diff 的 commit工程师调试 Modbus 地址映射能直接git blame查到谁在上周五下午三点修改了tag_mapping.json新成员入职git clone cmake make即可获得完整可运行的本地开发环境无需安装授权锁、破解补丁或离线激活码。它服务的对象不是单点操作员而是由 UI 设计师、PLC 工程师、现场调试人员组成的 HMI 开发团队——尤其适合有持续迭代需求、需多版本并行管理、或正在构建自有 HMI 标准规范的中大型自动化项目。如果你还在用压缩包传工程、靠截图对需求、靠 U 盘拷 runtime那 HmiFuncDesigner 提供的不是新功能而是整套工作流的重构起点。2. 搭建 HmiFuncDesigner 本地开发环境从源码编译到最小可运行工程HmiFuncDesigner 的开源属性决定了其可追溯性与可控性但这也意味着必须亲手完成从源码到可执行文件的完整构建链路。官方仓库Gitee 或 GitHub通常提供master稳定发布、dev功能预览和release/xxx语义化版本三个主要分支。实际工程中我建议优先 checkoutrelease/v1.4.2这类带明确版本号的标签而非直接拉dev分支——后者虽含最新特性但常伴随未合入的调试日志、临时注释或未覆盖的边界 case对生产级调试反而增加干扰。2.1 环境依赖与编译前检查HmiFuncDesigner 依赖 Qt 5.15.2官方明确要求不兼容 Qt 6.xCMake ≥ 3.16以及标准 C17 编译器GCC 9.3/Clang 10/MSVC 19.28。在 Ubuntu 22.04 上需先安装 Qt 官方离线安装包非系统 apt 源中的 Qt5因其版本碎片化严重# 下载 qt-unified-linux-x64-4.8.2-online.run 后执行 chmod x qt-unified-linux-x64-4.8.2-online.run ./qt-unified-linux-x64-4.8.2-online.run --script install_qt5152.qs其中install_qt5152.qs是自定义安装脚本内容需指定安装路径为/opt/Qt5.15.2并勾选Desktop GCC 64-bit和Qt Creator组件。验证是否成功/opt/Qt5.15.2/5.15.2/gcc_64/bin/qmake -v # 输出应包含 Qt version 5.15.2且 QMAKESPEC/opt/Qt5.15.2/5.15.2/gcc_64/mkspecs/linux-g注意若使用apt install qt5-default极大概率导致qmake调用系统 Qt 5.12 或 5.14编译时会在hmi_core/src/hmi_project.cpp报QRegularExpression未声明错误——这是 Qt 5.15 新增 API低版本无此符号。2.2 源码编译与调试版生成进入解压后的源码根目录如hmi-func-designer-1.4.2/执行标准 CMake 构建流程mkdir build cd build /opt/Qt5.15.2/5.15.2/gcc_64/bin/qmake .. \ -spec linux-g \ CONFIGdebug \ DEFINESHMI_DEBUG_MODE \ PREFIX/usr/local/hmifunc make -j$(nproc) sudo make install关键参数说明-spec linux-g强制指定 Qt 构建规格避免自动探测失败CONFIGdebug启用调试符号便于后续用gdb跟踪画面加载卡顿问题DEFINESHMI_DEBUG_MODE宏开关使运行时输出qDebug()日志到终端非qInfo()后者默认关闭PREFIX安装路径影响后续hmi_func_designer命令的全局可见性。编译成功后/usr/local/hmifunc/bin/hmi_func_designer即为可执行文件。首次运行时它会自动生成~/.config/HmiFuncDesigner/配置目录并在~/.local/share/HmiFuncDesigner/下创建默认模板库。此时不要急于打开示例工程——先验证基础功能# 检查是否能解析内置模板 /usr/local/hmifunc/bin/hmi_func_designer --list-templates # 应输出basic_button, modbus_slider, alarm_panel_v2... # 尝试无 GUI 模式校验工程结构关键排错手段 /usr/local/hmifunc/bin/hmi_func_designer --validate-project /path/to/test.hmi # 若返回 Project OK说明 JSON Schema 校验通过若报 Invalid tag address format则需检查 tags.json 中地址格式是否为 MB:40001 而非 400012.3 创建首个可运行的触摸屏工程HmiFuncDesigner 的工程本质是文件夹而非单一.hmi文件。标准结构如下my_hmi_project/ ├── project.json # 工程元数据名称、版本、目标屏分辨率 ├── screens/ # 所有画面文件.screen.json │ └── main_screen.screen.json ├── tags/ # 标签定义.tags.json │ └── plc_tags.tags.json ├── resources/ # 图片、字体、脚本支持 SVG/PNG/TTF/JS │ ├── icons/ │ └── scripts/ └── hmi_runtime_config.json # 运行时参数串口波特率、Modbus TCP IP、刷新间隔手动创建project.json最小配置{ name: TestHmi, version: 1.0.0, target_resolution: { width: 800, height: 480 }, default_screen: main_screen.screen.json, author: dev-team }screens/main_screen.screen.json必须包含root_widget和至少一个widget{ schema_version: 1.2, root_widget: { type: container, children: [ { type: button, id: start_btn, text: 启动, x: 100, y: 100, width: 120, height: 60, bind_tag: MB:40001 // 绑定到 Modbus 寄存器 40001 } ] } }提示bind_tag字段值必须严格匹配tags/plc_tags.tags.json中定义的标签名且格式需符合 HmiFuncDesigner 内置协议解析器规则如MB:表示 Modbus Holding RegisterDB:表示 S7 DB 块。错误格式会导致运行时绑定失败但编辑器不会实时报错——必须通过--validate-project命令提前发现。3. 运行时通信机制解析如何让 HmiFuncDesigner 工程真正驱动物理触摸屏HmiFuncDesigner 的“运行时”并非独立进程而是通过hmi_runtime模块嵌入到目标设备的 Linux 系统中。其通信架构分三层前端画面渲染Qt Quick、中间协议适配层hmi_protocol、底层硬件驱动hmi_driver。三者解耦设计使得同一份.hmi工程可无缝切换 Modbus RTU/ASCII/TCP、CANopen、或自定义串口协议只需替换对应protocol_plugin.so。3.1 协议插件加载与配置文件映射运行时通过hmi_runtime_config.json中的protocol_plugin字段指定动态库路径{ protocol_plugin: /usr/lib/hmi_plugins/libmodbus_tcp.so, connection_params: { host: 192.168.1.100, port: 502, timeout_ms: 2000, reconnect_interval_ms: 5000 } }libmodbus_tcp.so是官方提供的标准插件源码位于src/protocols/modbus_tcp/。其核心逻辑在ModbusTcpProtocol::readTags()函数中将tags.json中所有MB:4xxxx类型标签按地址连续性分组构造 Modbus Function Code 03Read Holding Registers请求包批量读取以提升效率。例如若plc_tags.tags.json包含{motor_run: MB:40001, motor_speed: MB:40002, alarm_code: MB:40010}插件会发起两次请求[40001, 40002]和[40010, 40010]而非三次单点读取。3.2 标签地址解析器的工作原理地址字符串MB:40001并非直接传递给 Modbus 库而是经TagAddressParser解析为结构体struct TagAddress { ProtocolType protocol; // MB (Modbus), DB (Siemens), etc. uint16_t base_address; // 40001 → 0x9C41 (Modbus 地址从 0 开始故 40001 0) uint16_t length; // 默认 1可被 widget 的 data_type 推导如 float32 需 2 个寄存器 DataType data_type; // UINT16, FLOAT32, BOOL, etc. };该解析发生在HmiProject::loadTags()阶段且仅在工程加载时执行一次。这意味着若运行时 PLC 地址变更必须重启hmi_runtime进程无法热更新地址映射——这是设计权衡牺牲动态灵活性换取地址解析零开销。3.3 触摸事件回写到 PLC 的实现路径当用户点击start_btn时事件流如下Qt Quick SceneGraph 捕获触摸坐标 →ButtonWidget::onClicked()触发调用HmiRuntime::writeTag(motor_run, true)ModbusTcpProtocol::writeTag()将true转为0x0001调用modbus_write_register(ctx, 0, 1)注意Modbus 地址 0 对应 40001底层modbus库通过send()发送 TCP 数据包。关键验证点若按钮无响应先检查hmi_runtime日志中是否有Write tag motor_run - 0x0001 success再抓包确认 TCP payload 是否含00 00 00 00 00 06 00 06 00 00 00 01Function Code 06地址 0值 1。若日志无输出问题在 Qt 层若有日志但无网络包问题在协议插件或防火墙。4. 源码级定制开发为 HmiFuncDesigner 添加自定义控件与协议支持HmiFuncDesigner 的扩展能力体现在两个维度UI 控件Widget和通信协议Protocol。二者均通过 Qt 插件机制Q_PLUGIN_METADATA注入无需修改主程序源码。以添加一个“双色 LED 指示灯”控件为例展示完整开发闭环。4.1 自定义 Widget 插件开发步骤控件源码需继承HmiWidgetBase并实现paint()和updateFromTag()// led_indicator_widget.h #include hmi_widget_base.h class LedIndicatorWidget : public HmiWidgetBase { Q_OBJECT Q_PLUGIN_METADATA(IID org.hmi.widget.LedIndicator FILE led_indicator.json) public: explicit LedIndicatorWidget(QWidget *parent nullptr); void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override; void updateFromTag(const QVariant value) override; private: QColor m_on_color Qt::green; QColor m_off_color Qt::red; }; // led_indicator_widget.cpp void LedIndicatorWidget::updateFromTag(const QVariant value) { bool is_on value.toBool(); setBrush(is_on ? m_on_color : m_off_color); update(); // 触发重绘 }配套led_indicator.json元数据文件定义控件属性{ name: LED Indicator, category: Indicators, properties: [ { name: on_color, type: color, default: #00ff00 }, { name: off_color, type: color, default: #ff0000 } ] }编译为插件qmake led_indicator_widget.pro \ QTwidgets \ CONFIGplugin \ DESTDIR../plugins/widgets make生成的libled_indicator_widget.so放入~/.local/share/HmiFuncDesigner/plugins/widgets/重启编辑器即可在控件面板看到新控件。4.2 自定义协议插件开发要点协议插件需实现HmiProtocolInterface抽象类。以支持 CANopen SDO 上传为例关键函数class CanopenSdoProtocol : public HmiProtocolInterface { bool initialize(const QJsonObject config) override { m_can_interface config[can_interface].toString(can0); return QCanBus::instance()-createDevice(socketcan, m_can_interface) ! nullptr; } bool readTags(const QVectorTagAddress addresses, QVectorQVariant *values) override { for (int i 0; i addresses.size(); i) { // 构造 CANopen SDO upload request (COB-ID 0x600 node_id) QByteArray frame buildSdoUploadRequest(addresses[i]); if (!m_can_device-writeFrame(frame)) return false; // 同步等待响应帧超时处理必须严格 if (!waitForSdoResponse(values-operator[](i))) return false; } return true; } };注意CANopen 协议要求严格的时间约束SDO 响应超时通常 ≤ 100ms因此waitForSdoResponse()必须使用QEventLoopQTimer::singleShot实现异步等待而非阻塞usleep()——否则会冻结整个 Qt 事件循环导致触摸无响应。4.3 源码贡献与 Gitee Pull Request 流程HmiFuncDesigner 社区采用标准 Git Flow。向官方仓库提交代码前必须在src/widgets/或src/protocols/下新建模块目录命名符合lowercase_with_underscore规范所有头文件需包含#pragma once和#ifndef HMIFUNC_XXX_H双重保护新增功能必须附带单元测试位于tests/目录使用QTest框架验证核心逻辑修改CMakeLists.txt时确保target_link_libraries()正确声明依赖避免undefined reference错误。典型 PR 标题格式feat(widgets): add led_indicator_widget with color customization。描述中需明确说明解决了什么问题如“原生控件缺乏状态可视化指示”、影响范围“仅新增插件不影响现有工程”、测试方法“已通过 test_led_indicator.cpp 验证 on/off 切换与颜色设置”。5. 工程交付与现场部署从开发机到嵌入式触摸屏的全链路验证技巧HmiFuncDesigner 工程交付不是复制粘贴文件夹而是一套可审计、可回滚、可监控的部署流水线。核心挑战在于开发机x86_64 Ubuntu与目标屏ARM Cortex-A7 Linux的 ABI 兼容性、Qt 版本一致性、以及运行时依赖收敛。5.1 构建交叉编译环境与静态链接目标屏通常运行 Yocto 或 Buildroot 构建的精简 Linux无包管理器。推荐使用linux-arm-gnueabihf工具链静态链接 Qt# 使用 Qt 官方提供的交叉编译器 /opt/Qt5.15.2/5.15.2/gcc_64/bin/qmake .. \ -spec linux-arm-gnueabihf-g \ CONFIGstatic \ QMAKE_LFLAGS_STATIC_LIB-static-libgcc -static-libstdc \ LIBS -lts -latk-1.0 \ INCLUDEPATH/opt/sysroot/usr/include/ts \ LIBS-L/opt/sysroot/usr/lib -lts make -j4关键参数-spec linux-arm-gnueabihf-g指定 ARM 交叉编译规格CONFIGstatic启用静态链接避免目标机缺失libQt5Core.so.5LIBS -lts链接 tslib 触摸屏校准库必需否则触摸坐标错乱INCLUDEPATH/opt/sysroot/usr/include/ts指向 Yocto SDK 中的 tslib 头文件。生成的hmi_runtime可执行文件大小约 28MB含 Qt 静态库但可直接scp到目标机运行无需额外安装。5.2 现场部署的三阶段验证法阶段验证动作成功标志失败常见原因Stage 1基础运行./hmi_runtime --project /mnt/hmi/project/ --log-level debug终端输出HMI Runtime started. Listening on /dev/input/event0/dev/input/event0权限不足需chmod 666或 tslib 未校准ts_calibrate未执行Stage 2通信连通观察日志中Modbus TCP connected to 192.168.1.100:502及Read 3 tags success每秒出现Read tags success日志且hmi_runtime进程 CPU 占用 5%PLC 防火墙拦截 502 端口或hmi_runtime_config.json中host填写为localhost应填 PLC 实际 IPStage 3交互闭环在画面上操作按钮用tcpdump -i eth0 port 502抓包抓包显示Function Code 06写请求与03读响应交替出现且 PLC 侧 IO 实际动作标签地址映射错误如MB:40001对应 PLC 的 Q0.0 而非 M0.0需核对 PLC 程序地址表5.3 运行时日志分析与性能瓶颈定位HmiFuncDesigner 运行时默认输出INFO级日志到stdout但关键诊断需开启DEBUG./hmi_runtime --project /mnt/hmi/ --log-level debug 21 | grep -E (Tag|Paint|FPS)重点关注三类日志Tag read latency: 12ms单次标签读取耗时20ms 需检查网络延迟或 PLC 响应速度Paint frame time: 16msQt Quick 渲染一帧耗时33ms30fps表明画面过于复杂如含大量 SVG 动画FPS: 29.8实时帧率持续低于 25fps 会导致触摸跟手性下降。若发现Paint frame time波动剧烈如 8ms → 45ms → 12ms大概率是某个Repeater控件绑定了未优化的model如直接绑定QListQObject*而非QAbstractListModel需重构为QSortFilterProxyModel并启用setDynamicSortFilter(true)。提示在嵌入式 ARM 设备上禁用 Qt Quick 的sg.textureAtlasSize默认 2048×2048可减少显存占用。在main.cpp中添加QQuickWindow::setTextureAtlasSize(QSize(1024, 1024));能显著降低低端 GPU 的纹理切换开销。本文还有配套的精品资源点击获取