系统结构与调试指南
使用说明
本手册面向 WECON 通用 Linux 平台开发者,系统介绍设备产品线区分、系统版本差异、分区与存储结构、启动流程、系统关键路径与文件,并说明无网口 / 无 Qt 画面设备的调试方法。阅读本手册可帮助开发者快速定位自身产品类型、理解设备内部机制,避免因误操作破坏系统。
1. 产品线区分
WECON 通用 Linux 平台的产品分为 HMI 触摸屏 与 V-Box 盒子 两大类。两者基于同一 Linux 平台,系统分区结构、系统启动流程等底层机制完全相同(详见本手册后续章节),差异主要体现在产品形态、主要功能与是否带 Qt 画面显示。
| 产品线 | 硬件平台 | 主要功能 / 类型 | 说明 |
|---|---|---|---|
| HMI 触摸屏 | RK3308 / RK3566 | 触摸屏显示类,多个尺寸 / 分辨率 / 功能等级 | 带 Qt 画面显示,人机交互界面 |
| V-Box 盒子 | RK3308 / RK3566 | 盒式设备,通信 / 逻辑控制类 | 部分型号带 Qt 画面显示,部分不带 Qt 画面 |
注意: - 无 Qt 画面显示的版本不带
SysSet后台工具,系统默认不启动图形界面,开发时无需 Qt 相关配置。 - 带 Qt 画面型号的开发流程见开发环境指南。 - 各产品的有无网口细分及调试方法见第 7 章。
2. 系统版本说明
| 系统版本 | 发布日期 | 维护情况 | 说明 |
|---|---|---|---|
| 通用 Linux_V1.0 | 2023 | 停止维护 | 旧分区结构,仅作兼容参考 |
| 通用 Linux_V2.0 | 2025 | 维护中 | 新分区结构 |
| 通用 Linux_V2.1 | 2026 | 最新 | V2.0 的演变,将用户文件与系统重要文件分隔开 |
重要:本文档主要面向 V2.0 及以上版本。V2.1 是 V2.0 的演变,核心变化是将用户的文件与系统重要文件分隔开来存放(见第 5 章)。
版本检测命令
通过 SSH 登录设备后台,执行 env 命令查看是否存在 HMI_LOCAL_ROOT 环境变量:
- 存在
HMI_LOCAL_ROOT→ V2.0 及以上新分区 - 不存在 → V1.0 旧分区
3. 系统分区结构与掉电保存区域
设备存储划分为多个分区,不同分区在掉电后数据是否保留上存在差异,开发时必须将需要持久保存的数据写入正确的分区。
3.1 分区分类
| 分区 / 挂载点 | 掉电后数据 | 说明 |
|---|---|---|
/usr |
✔ 保存 | 掉电保存区,存放系统程序、库、配置文件及用户数据 |
/opt |
✔ 保存 | 旧分区(V1.0)应用程序存放位置 |
/mnt/data |
视设备而定 | 临时 / 辅助数据挂载区,掉电后不保证持久保存(见第 4 章) |
内存挂载区(如 /tmp、部分 /etc) |
✘ 不保存 | 挂载于内存(tmpfs),掉电 / 重启后自动恢复 |
查看实际分区与挂载情况,可使用以下命令:
3.2 数据保存建议
- 需要持久保存的数据(用户配置、日志、业务数据):写入
/usr下自定义目录(如/usr/local/data)。 - 临时数据(缓存、运行时临时文件):写入内存挂载区(如
/tmp),掉电自动清除,无需人工清理。 - 避免将关键数据放在
/mnt/data等不保证掉电保存的挂载点。
4. 大内存设备内存挂载区
部分大内存设备为提升读写性能与寿命,将部分路径(如 /etc 等系统配置目录)挂载到内存(tmpfs)。
- 特征:掉电或重启后,这些目录内的修改会自动恢复为出厂默认值。
- 影响:直接修改这些路径下的文件(如部分
/etc配置)在重启后不生效。
判断某路径是否为内存挂载:
若为 tmpfs / overlay 挂载,重启后修改会丢失。
如需持久修改此类配置,请将配置写入掉电保存区(如
/usr/local/etc)并通过启动脚本应用,或根据具体固件说明处理。
5. 分区路径详解与新旧分区对比
5.1 关键路径对比表
| 用途 | V1.0(旧分区) | V2.0(新分区) | 最新分区(V2.1) |
|---|---|---|---|
| 用户应用可执行文件 | /opt/wecon/app/usr/bin/ |
/usr/local/bin/ |
/usr/local/bin/ |
| 用户应用库文件 | /opt/wecon/app/usr/lib/ |
/usr/local/lib/ |
/usr/local/lib/ |
| 系统出厂服务 / 程序 | /opt/wecon/app/usr/bin/ |
/usr/local/bin/ |
/usr/local/system/bin/ |
| 系统出厂库文件 | /opt/wecon/app/usr/lib/ |
/usr/local/lib/ |
/usr/local/system/lib/ |
| 启动脚本目录 | /opt/wecon/app/etc/init.d/ |
/usr/local/etc/init.d/ |
/usr/local/etc/init.d/ |
| 长按触摸恢复脚本 | /opt/wecon/app/etc/... |
/usr/local/sbin/touchShell |
/usr/local/sbin/touchShell |
| FTP 配置文件 | /etc/vsftpd.conf |
/usr/local/etc/vsftpd.conf |
/usr/local/etc/vsftpd.conf |
5.2 最新分区(V2.1)路径详解
V2.1 将系统出厂自带的服务与程序迁移至独立目录,与用户文件分隔开,便于维护且降低误操作风险。
| 路径 | 作用 |
|---|---|
/usr/local/system/bin/ |
系统出厂自带服务与程序(如 bsd、iboxServer 等) |
/usr/local/system/lib/ |
系统出厂自带的库文件 |
/usr/local/bin/ |
用户应用可执行文件目录(如 HMIApp) |
/usr/local/lib/ |
用户应用动态库存放目录 |
/usr/local/etc/ |
系统配置文件目录(含 init.d/ 启动脚本、vsftpd.conf、ts.conf 等) |
/usr/local/etc/init.d/ |
系统启动脚本目录(如 S06HMIApp) |
/usr/local/sbin/ |
系统管理脚本目录(如 touchShell) |
/usr/local/data/ |
推荐的数据持久保存目录 |
V2.0 及以上版本由
HMI_LOCAL_ROOT环境变量定位系统根目录,开发时建议通过该变量引用路径,避免硬编码。
6. 危险路径警告与禁止修改文件
⚠️ 危险操作警告:以下路径 / 文件涉及系统底层运行,禁止随意修改、删除或覆盖,否则可能导致重要服务启动失败、设备无法连接,严重时设备变砖。
| 路径 / 文件 | 风险说明 |
|---|---|
/usr/local/system/bin/、/usr/local/system/lib/ |
系统出厂自带的重要服务与程序(如 bsd、iboxServer 等),属于重要危险区域,请勿随意改动 |
/usr/local/etc/init.d/ 中 除 S06HMIApp 以外的脚本 |
系统级启动脚本,均比较危险,请勿随意修改 |
| 分区表 / boot 相关 | 修改可能导致设备无法开机 |
| 系统核心库 | 错误替换可能导致应用无法运行 |
长按触摸恢复脚本 touchShell |
默认用于启动后台 SysSet 工具,误改可能导致无法通过长按返回系统配置工具 |
| 固件 / 分区镜像 | 错误烧录可能导致设备变砖 |
6.1 客户可操作的启动脚本
- 客户可以新增启动脚本,或将客户应用配置写入
S06HMIApp脚本中(该脚本为客户应用启动入口,可修改)。 - 除
S06HMIApp外的其他init.d脚本涉及系统级服务,不建议修改。
⚠️ 串口调试提示:在调试启动脚本或调整文件目录结构时,务必先开启串口调试(见第 7 章)。若修改不当导致重要服务启动失败,可能无法通过网络连接设备,此时只能通过串口进行排查恢复;正常使用场景下不会发生此类问题。
6.2 安全操作原则
- 修改前备份原文件。
- 只修改与自身业务相关的脚本 / 文件(如
S06HMIApp、客户应用脚本)。 - 不确定用途的文件不要删除。
- 涉及系统级修改时,先咨询技术支持。
7. 无网口设备调试方法
7.1 有网口设备(常规调试)
有网口设备可通过网线直连或接入局域网,使用 SSH 登录后台调试,具体见开发环境指南。
7.2 无网口设备
无网口设备无法直接使用以太网 SSH,可采用以下方式调试:
① 外接 USB 网卡
- 通过 USB 连接外接 USB 网卡,为设备提供网络接口。
- 配置同一网段静态 IP 后,即可通过 SSH 登录设备后台。
② 开启串口调试
串口调试用于无网口设备调试,或在重要服务启动失败、无法网络连接设备时进行排查恢复。开启方式有两种:
- 方式一(SSH 后台命令):登录设备后台执行
whal debug开启,执行whal release关闭。
- 方式二(后台系统配置工具):进入后台系统配置工具 → 通用设置 → 版本信息 → 连续点击 10 次版本号 启用开发者模式 → 开发者选项 → debug 调试开关。
串口连接参数:波特率 115200,数据位 8,停止位 1,校验 N(无校验)。
接线说明:设备调试串口为 RS-232 电平,通过 USB 转 RS-232 串口线连接电脑。设备 DB9 接口引脚定义如下:
| 引脚 | 信号 |
|---|---|
| 2 | RXD |
| 3 | TXD |
| 5 | GND |
接线时 TXD / RXD 交叉连接(设备 TXD 接电脑 RXD,设备 RXD 接电脑 TXD),GND 对接 GND。

③ 使用 iBoxTool 工具
- 使用配套 iBoxTool 工具,通过 USB 或以太网通道连接设备,对设备进行信息查看、程序部署与配置(见iBoxTool 使用指南)。
7.3 无 Qt 画面设备
无 Qt 画面显示的版本不带 SysSet 后台工具,系统默认不启动图形界面,调试方式同一般嵌入式设备:
- 通过 SSH 登录后台执行命令、查看日志。
- 通过 U盘脚本进行程序部署与系统操作。
- 程序运行日志通过后台输出或写入文件查看。
8. 系统主程序启动流程
8.1 启动流程概览
设备上电后,系统按照以下流程启动主要程序:
内核启动
└─ 系统初始化(挂载分区、启动系统服务)
└─ init.d 启动脚本按顺序执行
├─ 系统服务脚本(bsd、iboxServer 等)
├─ 挂载脚本(如 auto-mount.sh)
├─ 系统配置工具(SysSet,仅带 Qt 画面版本)
└─ 主应用程序(HMIApp)启动
└─ 客户工程运行
8.2 主要程序说明
| 程序 | 作用 |
|---|---|
HMIApp |
客户主应用程序,开机自启动,负责显示与业务逻辑 |
SysSet |
系统配置工具,长按屏幕右上角时启动,用于网络、系统等配置(仅带 Qt 画面版本) |
bsd |
系统出厂自带服务(位于 /usr/local/system/bin/) |
iboxServer |
系统出厂自带服务(位于 /usr/local/system/bin/) |
8.3 启动脚本说明
| 脚本 | 作用 |
|---|---|
init.d/S06HMIApp |
主应用启动脚本,负责启动 HMIApp(客户可修改,配置方法见个性化定制开发指南) |
init.d/ 其他脚本 |
系统级服务启动脚本,较危险,不建议修改 |
auto-mount.sh |
自动挂载脚本,负责挂载 SD 卡、U盘 等存储设备 |
touchShell |
长按触摸恢复脚本,默认用于启动后台 SysSet 工具(使用 / 定制方法见个性化定制开发指南) |
各脚本的配置 / 定制方法,详见个性化定制开发指南与系统配置工具使用指南。
9. FTP 功能说明
设备内置 FTP 服务,可用于在电脑与设备之间上传 / 下载文件(如程序部署、日志提取、文件传输)。
9.1 配置文件
| 系统版本 | 配置文件路径 |
|---|---|
| Linux_V2.0 及以上 | /usr/local/etc/vsftpd.conf |
| Linux_V1.0 | /etc/vsftpd.conf |
9.2 启动服务
9.3 常用配置参数
| 配置参数 | 默认值 | 功能说明 |
|---|---|---|
local_enable |
YES | 允许本地用户登录 |
local_root |
/mnt/data/ftppath | FTP 根目录 |
write_enable |
YES | 允许文件写入 |
max_clients |
5 | 最大客户端连接数 |
max_per_ip |
5 | 单 IP 最大连接数 |
9.4 常用 FTP 命令
| 命令 | 功能 |
|---|---|
ftp <IP> |
连接 FTP 服务器 |
put <本地文件> |
上传文件 |
get <远程文件> |
下载文件 |
mput *.txt |
批量上传 |
mget *.jpg |
批量下载 |
完整 FTP 命令说明见开发环境指南。