Linux开发常见问题 - 系统功能类
本类汇总 Linux 平台设备(HMI 屏)系统功能相关的常见问题,涵盖触摸、背光、字体显示、开机启动、Qt 程序运行等场景。
1. 触摸无反应或触摸失灵
故障现象
设备界面点击无反应,或触摸位置不准确。
排查与解决方法
①:执行触摸校准
远程进入设备后台,执行触摸校准命令,校准完成后触摸恢复正常:
②:替换 ts.conf 配置
若程序更新后出现无法触摸的问题,将对应固件的 ts.conf 文件发送到设备,替换到 /usr/local/etc/ 目录:
③:触摸失灵时通过 U盘脚本进入后台
当触摸完全失灵无法进入后台时,可通过 U盘脚本进入后台:
- 在 U盘根路径新建
/wecon/AutoRun.sh脚本 - 脚本功能:杀掉
HMIApp进程,并重新启动SysSet进程 - 屏下服务正常的情况下,U盘插入后会自动执行该脚本
2. 触摸多次触发(误触发)
故障现象
点击屏幕过程中出现多次触发的问题。
可能原因
触摸过滤不完善,信号抖动导致重复触发。
解决方法
替换新版 tslib 库(支持 iir、median 模块),并修改 /etc/ts.conf 参数:
3. 触摸校准方式与 ts.conf 配置说明
触摸校准方式
当设备触摸无反应、失灵或位置不准确时,可通过触摸校准解决:
①:执行触摸校准
按界面提示点击校准点,校准完成后触摸恢复正常。
②:替换 ts.conf
若程序更新后出现无法触摸的问题,将对应固件的 ts.conf 文件发送到设备,替换到 /usr/local/etc/ 目录:
ts.conf 配置方式与参数说明
tslib 的触摸配置主要通过 ts.conf 文件实现(路径:/usr/local/etc/ts.conf 或 /etc/ts.conf,视系统版本而定)。文件通过 module 指令加载处理模块,常见参数如下:
| 模块 / 参数 | 说明 |
|---|---|
module_raw input |
加载原始输入设备模块,从触摸设备读取原始数据 |
module pthres |
阈值过滤,去除触摸按下 / 松开的抖动 |
module variance |
方差过滤,去除噪声点 |
module dejitter |
去抖动,降低采样抖动 |
module linear |
线性校准,将原始坐标线性变换为屏幕坐标 |
module iir |
IIR 滤波,平滑触摸轨迹(新版 tslib) |
module median |
中值滤波,去除尖峰噪声(新版 tslib) |
配置示例:
module_raw input
module pthres pmin=1
module variance delta=30
module dejitter delta=100
module linear
触摸多次触发(误触发)处理:
- 替换新版
tslib库(支持iir、median模块),并修改/etc/ts.conf或/usr/local/etc/ts.conf参数,加入滤波模块以抑制抖动导致的重复触发。
官方文档:tslib 为开源的触摸屏访问库,更多模块与参数说明请参考 tslib 官方文档: - 官方 GitHub:https://github.com/libts/tslib - 官方文档(Configuration):https://github.com/libts/tslib/wiki/Configuration
4. 虚拟机编译正常,设备运行提示缺库
故障现象
程序在虚拟机交叉编译正常,部署到设备后运行提示缺少动态库(.so)。
原因分析
客户工程依赖的某些动态库未随程序部署到设备,或设备端缺少对应版本的库文件。
解决方法
①:确认缺失的库
运行程序,根据报错信息确认缺失的库名;也可使用以下命令检查程序依赖:
②:从虚拟机工具链获取对应库部署到设备
工具链中已包含交叉编译所需的库,可通过以下方式将对应库部署到设备:
- 在虚拟机中查找库文件:
- 将找到的库文件通过 SCP 拷贝到设备对应库目录(V2.0:
/usr/local/lib):
③:确认库版本匹配
使用 find / -name "libxxx*" 2>/dev/null 检查设备端已有库,确认与编译依赖的库版本一致;版本不一致时使用新 SDK 重新编译或替换对应库。
具体库文件与路径说明见系统结构与调试指南。
5. 字体缺失、字体下载与安装
故障现象
- 客户工程使用韩文等特殊字符不能正常显示。
- Qt 应用需要在 HMI 上使用自定义字体。
解决方法
①:系统字体缺失
从 Ubuntu 系统获取 NotoSansCJK-Regular.ttc 字库,替换到 /usr/fonts 目录下解决。
②:Qt 工程自定义字体
将字体手动放入 HMI 的 /opt/wecon/app/qtfonts 目录,并设置读写权限。Qt 应用启动时使用 QFontDatabase::addApplicationFont() 从固定绝对路径动态加载字体。
注:更换 HMI 或恢复系统后,需要重新手动安装字体。
字体获取与下载
- 系统字体:可从 Ubuntu 系统
/usr/share/fonts目录获取,或从 Google Fonts、Noto Fonts 等字体网站下载。 - 中文字体:建议使用
NotoSansCJK系列,涵盖中日韩字符。 - 字体格式:支持
.ttf、.ttc、.otf等常见格式。
安装步骤
①:下载所需字体文件(如 .ttf)。
②:将字体文件拷贝到设备对应目录(系统字体 /usr/fonts,Qt 工程字体 /opt/wecon/app/qtfonts)。
③:设置字体文件读写权限。
④:Qt 应用通过 QFontDatabase 加载并应用字体。
6. 文本显示顺序颠倒
故障现象
使用 9102iG 的通用 Linux 屏,在 QLabel 中显示纯文本和富文本混合的文本时出现显示顺序颠倒的问题。
可能原因
Qt 库对富文本支持不完整。
解决方法
选择富文本支持的选项,重新编译 4.8.7 版本的 Qt 库放到设备下,重新下载 Qt 工程或重启后即可解决。
7. 程序运行崩溃或启动失败
故障现象
客户工程在竞品屏下运行正常,在我们的屏下运行出现崩溃问题;或程序启动失败、白屏死机。
排查与解决方法
①:使用 gdb 调试定位崩溃
设备端提供 gdbserver,配合电脑端 gdb(下载中心提供 gdb-rk3308 / gdb-rk3566)可定位崩溃位置。
设备端准备:
确认设备端存在 gdbserver,若不存在可通过 U盘脚本部署(见系统结构与调试指南)。
调试流程:
- 将程序拷贝到设备,并启动 gdbserver:
- 在电脑端(虚拟机)使用 gdb 连接设备:
- 复现崩溃后,使用
bt(backtrace)查看崩溃堆栈定位问题代码。
②:常见导致程序崩溃的原因
- 物理内存不足:程序内存占用过大,建议优化内存、减少不必要的拷贝操作。
- 数组越界 / 空指针:访问非法内存导致段错误(Segmentation fault)。
- 动态库缺失 / 版本不匹配:运行提示缺库,见上文虚拟机编译正常,设备运行提示缺库。
- 启动脚本异常拷贝:启动脚本中存在将
/usr/local/bin下文件拷贝到/tmp/app等占用内存的操作,可能引发内存不足。
③:取消不必要的拷贝操作
检查启动脚本中是否有将 /usr/local/bin 下文件拷贝到 /tmp/app 的操作,该操作可能引发内存不足。取消该操作后可解决。
④:检查 /usr 分区空间
程序启动失败、白屏死机可能由 /usr 分区空间不足导致:
- 客户工程较大时,使用升级包升级可能因
/usr分区空间不足导致解压失败、系统文件缺失损坏。 - 解决方法:重新刷机恢复系统;在升级脚本中添加可用空间检测功能。
8. 开机启动异常
故障现象
- 刷入客户程序后从开机到显示画面时间较长
- 客户替换 SysSet 后无法通过长按右上角返回系统配置工具
- 程序无法开机自启动
解决方法
①:启动时间较长
启动时间与工程大小、开机初始化逻辑相关,建议精简开机启动流程、减少不必要的自启动程序。
②:正确使用 HMIApp 与 SysSet
新固件请保留 SysSet,将客户应用命名为 HMIApp 实现开机自启;长按右上角时由系统启动 SysSet 返回系统配置工具。
③:程序开机自启动配置
- 将编译生成的可执行文件重命名为
HMIApp - 根据系统版本复制到对应执行文件存放目录(详见个性化定制开发指南)
- 添加可执行权限
④:开机卡 LOGO 排查
设备开机后长时间停留在 LOGO 画面(卡 LOGO),无法进入系统 / 工程,可按以下步骤排查:
- 检查是否刷入了异常固件 / 程序:卡 LOGO 多由系统文件缺失或损坏导致(如升级中断、
/usr空间不足导致文件缺失)。 - 检查
/usr分区空间:使用df -h查看,若空间已满可能导致系统文件缺失,需清理空间或重新刷机。 - 检查客户程序:若刷入客户程序后卡 LOGO,检查程序是否为有效的
HMIApp,且依赖库完整。 - 重新刷机恢复:若无法定位原因,重新刷机恢复系统后,再逐步排查客户程序。
刷机恢复后建议先在设备上运行出厂工程验证系统正常,再部署客户程序排查。
9. Qt 程序编译运行其他问题
程序报 libts 相关库错误
- 确认编译时依赖的
libts与设备中的库版本不一致 - 使用
find / -name "libts*" 2>/dev/null检查设备端库文件 - 使用新 SDK 重新编译
10. 功能使用咨询
虚拟键盘使用
HMI 的 Qt 工程默认没有虚拟键盘,需要在工程中自行实现。
看门狗功能
2025 年 10 月版本固件没有看门狗功能。