跳转至

系统结构与调试指南

使用说明

本手册面向 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),掉电 / 重启后自动恢复

查看实际分区与挂载情况,可使用以下命令:

df -h          # 查看各分区容量与使用情况
mount          # 查看所有挂载点及其类型
cat /proc/mounts

3.2 数据保存建议

  • 需要持久保存的数据(用户配置、日志、业务数据):写入 /usr 下自定义目录(如 /usr/local/data)。
  • 临时数据(缓存、运行时临时文件):写入内存挂载区(如 /tmp),掉电自动清除,无需人工清理。
  • 避免将关键数据放在 /mnt/data 等不保证掉电保存的挂载点。

4. 大内存设备内存挂载区

部分大内存设备为提升读写性能与寿命,将部分路径(如 /etc 等系统配置目录)挂载到内存(tmpfs)。

  • 特征:掉电或重启后,这些目录内的修改会自动恢复为出厂默认值。
  • 影响:直接修改这些路径下的文件(如部分 /etc 配置)在重启后不生效。

判断某路径是否为内存挂载:

mount | grep -E "tmpfs|overlay"
df -h /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 安全操作原则

  1. 修改前备份原文件。
  2. 只修改与自身业务相关的脚本 / 文件(如 S06HMIApp、客户应用脚本)。
  3. 不确定用途的文件不要删除。
  4. 涉及系统级修改时,先咨询技术支持。

7. 无网口设备调试方法

7.1 有网口设备(常规调试)

有网口设备可通过网线直连或接入局域网,使用 SSH 登录后台调试,具体见开发环境指南。

7.2 无网口设备

无网口设备无法直接使用以太网 SSH,可采用以下方式调试:

① 外接 USB 网卡

  • 通过 USB 连接外接 USB 网卡,为设备提供网络接口。
  • 配置同一网段静态 IP 后,即可通过 SSH 登录设备后台。

② 开启串口调试

串口调试用于无网口设备调试,或在重要服务启动失败、无法网络连接设备时进行排查恢复。开启方式有两种:

  • 方式一(SSH 后台命令):登录设备后台执行 whal debug 开启,执行 whal release 关闭。
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 启动服务

/usr/bin/vsftpd   # 启动 FTP 服务

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 命令说明见开发环境指南。