开发环境指南
使用说明
本手册是专为 WECON 通用 Linux 平台(HMI / V-Box 系列,RK3308 / RK3566)开发者设计的全流程环境配置指南,基于工业自动化领域对嵌入式开发的特殊需求编写。手册以 Qt 交叉编译为核心,涵盖环境准备、虚拟机部署、开发环境配置、Qt 工程开发与交叉编译、设备连接与远程调试等关键环节,助力开发者快速构建稳定高效的开发环境体系。
版本说明:本指南基于 Ubuntu 22.04.4 LTS 虚拟机环境,主要面向通用 Linux_V2.0 系统。V1.0 旧系统相关配置仅作兼容参考。
一、环境准备
1.1 环境及软件版本说明
软件环境配置表
| 环境 | 软件 | 版本 | 描述 |
|---|---|---|---|
| 虚拟机 | VMware Workstation | 17.6.0 | |
| 操作系统 | Ubuntu | 22.04.4 LTS | 登录账号:wecon 密码:wecon2026 |
| IDE | Qt Creator | 4.15.0 | |
| Qt 库 | Qt | 5.12.11 / 4.8.7 / 4.8.4 / 5.15.14 | 5.15.14 对应 RK3566 平台 |
| SSH 工具 | Xshell、SecureCRT | ||
| 触摸屏后台登录 | 账号:root 密码:123456 |
Qt 版本与平台对应关系
| Qt 版本 | 对应平台 | 说明 |
|---|---|---|
| Qt 5.12.11 | RK3308 | 推荐版本 |
| Qt 4.8.7 | RK3566 | 兼容旧项目(需 -qws) |
| Qt 4.8.4 | RK3308 | 兼容旧项目(需 -qws) |
| Qt 5.15.14 | RK3566 | RK3566 平台推荐版本 |
免责声明
重要提示:上述触摸屏登录的密码是我们提供的初始密码,建议客户修改密码。未修改密码导致屏被他人恶意登录操作,由客户自行承担风险。
1.2 资源下载路径
资源下载清单表
| 资源名称 | 下载路径 | 网盘密码 |
|---|---|---|
| 工具包(含 SDK) | https://pan.baidu.com/s/1-g9wGvDndVldbzJhf_uY-w?pwd=ekx3 | ekx3 |
| 工具链(RK3308 / RK3566) | 文件较大,通过网盘下载或联系技术支持获取 |
二、虚拟机部署
本节提供两种虚拟机部署方案:从零搭建适合需要自定义配置的场景,镜像复用适合快速部署,开发者可根据需求选择。
2.1 从零搭建
第一步 系统环境准备
更新系统软件源,并安装 Qt Creator、CMake、构建工具链、SSH 服务以及 GDB 调试所需的依赖库。
# 1. 更新软件源
sudo apt update
# 2. 安装 Qt Creator 和基础构建环境 (gcc, make 等)
sudo apt install qtcreator build-essential -y
# 3. 安装 SSH 服务 (用于与开发板进行文件传输和远程调试)
sudo apt install openssh-server -y
# 4. 安装 CMake 构建工具
sudo apt install cmake -y
# 5. 安装调试器依赖 (GDB 运行库)
sudo apt install libncurses6 libncursesw6 python3 -y
注意:Ubuntu 22.04 中
ncurses包名为libncurses6(非旧版的libncurses5),调试器依赖请安装libncurses6与python3。
第二步 部署交叉编译工具链
工具链获取:下载对应平台的工具链压缩包(RK3308 / RK3566,见下载中心或网盘)。包内已包含交叉编译器和编译好的 Qt 库。下载完成后,请将其拷贝到虚拟机的用户目录中(例如 ~/Downloads)。
解压工具链:统一解压到标准的 /opt 目录下。
# 进入存放压缩包的目录 (请根据实际情况修改路径)
cd ~/Downloads
# 解压到 /opt 目录 (需要 sudo 权限)
sudo tar -xzvf toolchain.tar.gz -C /opt/
修正 Qt 配置文件路径
由于交叉编译的 Qt 库中 qmake.conf 通常包含硬编码的绝对路径,如果您的解压位置与原编译位置不一致,必须手动修正,否则编译时会报错。
详细步骤:
①:进入解压后的 Qt 库目录,找到 mkspecs 文件夹,进入与目标设备 / 架构对应的目录(如图中所示 linuxarm-rk3308,RK3566 平台选择对应架构目录)。
②:找到目录下的 qmake.conf 文件。

使用文本编辑器打开该文件(需 sudo 权限),重点检查并修改以下三处路径信息,更新为当前系统中的真实路径:
- 区域 ①(编译器):修改
QMAKE_CC、QMAKE_CXX、QMAKE_LINK等变量,确保指向正确的 gcc/g++ 路径。 - 区域 ②(工具集):修改
QMAKE_AR、QMAKE_OBJCOPY、QMAKE_STRIP等变量,确保指向正确的工具链路径。 - 区域 ③(Sysroot):修改
QMAKE_CFLAGS、QMAKE_CXXFLAGS、QMAKE_LFLAGS中的--sysroot参数路径。
修改完成后,保存并关闭文件。

第三步 配置 Qt Creator
打开 Qt Creator,点击菜单栏 Tools -> Options,在左侧列表选择 Kits,进入构建套件配置界面。按照依赖顺序依次配置:Debuggers -> Compilers -> Qt Versions -> Devices -> Kits。
配置 Debuggers(调试器)
①:点击顶部标签栏的 Debuggers 选项卡。
②:点击右侧的 Add 按钮,新增一个调试器配置。
③:在 Name 栏中输入自定义名称。
④:点击 Path 栏右侧的 Browse...,选择工具链目录下的 gdb 可执行文件。
路径示例:
/opt/toolchain/rk3308/.../bin/arm-linux-gnueabihf-gdb
⑤:确认路径无误后,点击右下角的 Apply 保存。

配置 Compilers(编译器)
①:点击顶部标签栏的 Compilers 选项卡。
②:分别添加 C++ 和 C 两个编译器:
- 点击
Add -> GCC -> C++,配置 C++ 编译器。 - 点击
Add -> GCC -> C,配置 C 编译器。
③:在 Name 栏输入自定义名称(C++ 建议 GCC_rk3308,C 建议 GCC_rk3308_C)。
④:点击 Compiler path 右侧的 Browse...,分别选择对应的编译器文件:
- C++:选择工具链中的 g++ 文件(如
.../bin/arm-linux-gnueabihf-g++)。 - C:选择工具链中的 gcc 文件(如
.../bin/arm-linux-gnueabihf-gcc)。
⑤:确认无误后,点击右下角的 Apply 保存。

配置 Qt Versions(Qt 版本)
①:点击 Qt Versions 选项卡。
②:点击右侧 Add... 按钮,选择工具链目录下的 qmake 可执行文件。
路径示例:
/opt/toolchain/rk3308/qt5.15.14/bin/qmake(RK3566)或对应平台的 qmake。
③:选中添加好的版本,在 Version name 栏修改名称(建议格式:Qt 版本号(平台),如 Qt 5.15.14 (rk3566))。
④:确认 qmake location 栏路径是否正确,如有误可点击 Browse... 重新选择。
⑤:配置完成后,点击右下角的 Apply 保存。

配置远程设备(Devices)
为了让 Qt Creator 能通过网络将程序传输到开发板并进行调试,需要配置设备的连接信息。
①:点击左侧列表中的 Devices 选项卡。
②:点击右侧 Add... 按钮。
③:选择 Generic Linux Device(通用 Linux 设备)。
④:点击 Start Wizard 开始配置向导。
⑤:填写设备详情:
- Host name:输入开发板的 IP 地址(如 192.168.1.1)。
- Username:输入登录用户名(通常为
root)。 - Authentication:推荐选择
Default(密码认证)或配置SSH Key。 - 注意:填写完成后建议点击右侧
Test按钮测试连接是否成功。
⑥:确认无误后,点击右下角的 Apply 保存。

配置 Kits(构建套件)
①:点击顶部标签栏的 Kits 选项卡。
②:点击右侧 Add 按钮,新增套件项。
③:在 Name 栏输入自定义名称(如开发板型号):
- Device type:选择
Generic Linux Device。 - Sysroot:指向工具链解压目录下的
sysroot路径(如有)。
④:配置编译器(Compiler):
- C:选择对应的交叉编译器(GCC)。
- C++:选择对应的交叉编译器(G++)。
⑤:配置调试器(Debugger):选择对应的 GDB 调试器。
⑥:配置 Qt 版本(Qt version):选择对应的 Qt 版本。
⑦:配置完成后,点击右下角的 Apply 保存。

2.2 镜像复用(快速部署)
虚拟机部署步骤表
| 步骤 | 操作内容 | 配置要求 | 说明 |
|---|---|---|---|
| 1 | 软件准备 | VMware 17.6.0 | 下载并安装虚拟机软件 |
| 2 | 虚拟机配置 | Ubuntu 系统文件 | 配置虚拟机环境 |
| 3 | 系统启动 | wecon Ubuntu 22.04.4 | 启动虚拟机系统 |
| 4 | 系统登录 | wecon / wecon2026 | 登录虚拟机系统 |
详细操作步骤:
①:软件准备:下载并安装 VMware Workstation 17.6.0。
②:虚拟机配置:启动 VMware Workstation Pro,解压 wecon Ubuntu 镜像压缩包,将解压后的文件添加到虚拟机中。

③:系统启动:选择 wecon Ubuntu 22.04.4 的 .vmx 文件,点击开启此虚拟机。

④:系统登录:输入用户名 wecon、密码 wecon2026 登录系统。

三、开发环境配置
3.1 SSH 工具的使用方法
连接配置表
| 步骤 | 参数 | 值 | 说明 |
|---|---|---|---|
| 1 | 会话类型 | 新建会话 | 创建新的 SSH 连接 |
| 2 | 目标地址 | 触摸屏 IP 地址 | HMI 设备网络地址 |
| 3 | 用户名 | root | 系统管理员账户 |
| 4 | 密码 | 初始密码 | 首次登录使用默认密码 |
操作步骤:
①:会话创建与目标地址设置:打开 Xshell(这里以 Xshell 为例),添加会话,输入对应的触摸屏 IP 地址,点击确定。

②:用户认证:输入用户名 root 并点击确定。

③:密码验证:输入初始密码并点击确定,成功进入触摸屏后台。

3.2 Linux 访问 Windows 共享目录
3.2.1 Windows 端配置
Windows 共享配置表
| 配置步骤 | 操作路径 | 关键参数 | 说明 |
|---|---|---|---|
| 1 | 设置 → 账户 → 家庭和其他用户 | 创建新用户 | 设置共享访问账户 |
| 2 | 文件夹属性 → 共享 | 设置共享权限 | 配置文件夹共享 |
| 3 | 共享配置窗口 | 设置用户权限 | 控制读写访问 |
详细操作:
①:按下【Win + I】打开设置界面,点击左侧【账户】,选择【家庭和其他用户】。

②:点击"其他用户"下的"添加账户",填写用户名、密码,点击【下一步】完成创建。

③:选择要共享的文件夹,右键点击【属性】→【共享】→【共享】按钮设置共享。

④:在共享配置窗口中设置共享用户及其读写权限。

3.2.2 HMI 挂载 Windows 共享目录
挂载命令详解
参数说明表
| 参数 | 值 | 说明 |
|---|---|---|
| -t | cifs | 文件系统类型 |
| -o | username=wecon | Windows 共享用户名 |
| -o | password=123456 | Windows 共享密码 |
| -o | vers=2.1 | SMB 协议版本 |
| 源路径 | //192.168.1.1/share | Windows 共享路径 |
| 目标路径 | /mnt/data/share | Linux 挂载点(新建或已存在的空目录) |
推荐目标路径
| 系统版本 | 挂载路径 |
|---|---|
| 通用 Linux_V1.0 | /mnt/data/ 路径下 |
| 通用 Linux_V2.0 | /usr/localoriginal/data 路径下 |
注:推荐在 Qt 工程中使用挂载节点,在程序初始化时通过执行该命令进行 Windows 目录挂载,保证挂载节点掉电重启后不会丢失。
访问 Windows 共享目录:进入 /mnt/data/share 即可访问 Windows 共享的目录,访问权限取决于设置的用户权限。
3.3 FTP 服务配置
3.3.1 HMI 触摸屏 FTP 环境搭建
FTP 配置文件路径
①:通用 Linux_V1.0:/etc/vsftpd.conf
②:通用 Linux_V2.0:/usr/local/etc/vsftpd.conf
FTP 配置文件参数表
| 配置参数 | 默认值 | 功能说明 |
|---|---|---|
| local_enable | YES | 允许本地用户登录 |
| local_root | /mnt/data/ftppath | FTP 根目录 |
| chroot_local_user | YES | 限制用户在主目录 |
| allow_writeable_chroot | YES | 允许主目录写入 |
| chroot_list_enable | YES | 启用特例用户列表 |
| chroot_list_file | /mnt/data/etc/vsftp/chroot_list | 特例用户列表文件 |
| secure_chroot_dir | /mnt/data/etc/vsftp/empty | 安全目录设置 |
| max_clients | 5 | 最大客户端连接数 |
| max_per_ip | 5 | 单 IP 最大连接数 |
| write_enable | YES | 允许文件写入 |
服务管理命令
3.3.2 FTP 常用命令
| 序号 | 命令 | 功能描述 | 语法格式 | 使用示例 |
|---|---|---|---|---|
| 1 | ftp | 进入 FTP 命令行环境 | ftp |
ftp |
| 2 | open | 连接到远程 FTP 服务器 | open [IP地址] [端口号] |
open 192.168.1.106 21 |
| 3 | user | 输入用户名认证 | user [用户名] |
user admin |
| 4 | pwd | 查询远程服务器当前工作目录 | pwd |
pwd |
| 5 | dir/ls | 列出服务器当前目录文件 | dir / ls |
ls -l |
| 6 | cd | 切换远程服务器目录 | cd [目录名] |
cd public_html |
| 7 | bin | 设置二进制传输模式 | bin |
bin |
| 8 | put | 上传单个文件 | put [本地文件路径] |
put "D:\docs\report.pdf" |
| 9 | get | 下载单个文件 | get [远程文件名] |
get index.html |
| 10 | prompt | 开启 / 关闭交互模式 | prompt |
prompt |
| 11 | mput | 批量上传文件 | mput [文件掩码] |
mput *.txt |
| 12 | mget | 批量下载文件 | mget [文件掩码] |
mget *.jpg |
| 13 | mkdir | 创建远程目录 | mkdir [目录名] |
mkdir backups |
| 14 | rmdir | 删除远程空目录 | rmdir [目录名] |
rmdir temp |
| 15 | delete | 删除远程文件 | delete [文件名] |
delete log.txt |
| 16 | mdelete | 批量删除远程文件 | mdelete [文件掩码] |
mdelete *.bak |
| 17 | rename | 重命名远程文件 | rename [旧名] [新名] |
rename old.doc new.doc |
| 18 | !dir | 查看本地当前目录文件 | !dir |
!dir |
| 19 | lcd | 切换本地文件目录 | lcd [本地路径] |
lcd D:\ftp_uploads |
| 20 | bye/quit | 退出 FTP 环境 | bye / quit |
bye |
四、Qt 工程开发与交叉编译
4.1 创建 Qt 工程
QT 工程创建步骤表
| 步骤 | 操作 | 配置选项 | 说明 |
|---|---|---|---|
| 1 | 启动 Qt Creator | - | 打开开发环境 |
| 2 | 新建工程 | 新建项目,QT 应用程序,嵌入式设备 | 创建新项目 |
| 3 | 设置信息 | 工程名称和路径 | 项目基本信息 |
| 4 | 编译器选择 | qmake(默认) | 构建工具配置 |
| 5 | 界面设置 | 主画面相关信息 | UI 界面配置 |
| 6 | 国际化设置 | 默认不选择 | 多语言支持 |
| 7 | 平台选择 | 根据需要选择 | 目标平台配置 |
| 8 | 完成创建 | 点击完成 | 项目创建结束 |
操作步骤:
①:启动开发环境:打开虚拟机中的 Qt Creator 软件。

②:新建工程向导:新建工程,选择 QT 应用程序,设备选择嵌入式设备。

③:工程路径设置:设置工程的名称和工程路径。

④:编译器配置:编译器默认选择 qmake。

⑤:主画面设置:设置主画面相关信息。

⑥:国际化配置:默认不选择,直接点击下一步。

⑦:平台选择:根据需要选择相应的平台。

⑧:完成创建:点击完成结束工程的创建。

4.2 切换 Qt 版本
QT 版本切换配置表
| QT 版本 | 配置要求 | 特殊参数 | 说明 |
|---|---|---|---|
| Qt 5.12.11 | 默认配置 | 无 | RK3308 推荐版本 |
| Qt 5.15.14 | 默认配置 | 无 | RK3566 推荐版本 |
| Qt 4.8.7 | 需要额外配置 | -qws | 兼容旧项目 |
| Qt 4.8.4 | 需要额外配置 | -qws | 兼容旧项目 |
操作步骤:
①:打开设置选项:点击 Tools 中的 Option。

②:选择 QT 版本:点击 Kits -> Qt version 可切换 Qt 版本。

③:Qt4 特殊配置:如果选择 Qt4 版本,需要在 Projects -> Run 的命令行参数增加 -qws。

4.3 Qt 代码编译
编译状态说明表
| 编译状态 | 显示特征 | 含义 |
|---|---|---|
| 编译中 | 进度条显示 | 正在编译 |
| 编译成功 | 绿色满格进度条 | 无错误,编译完成 |
| 编译错误 | 红色错误提示 | 需要修复代码错误 |
编译操作:点击小锤子进行编译,有错误显示红色提示,无错误显示绿色满格进度条。

五、设备连接与调试
5.1 设备连接
网络连接配置表
| 配置项目 | 要求 | 检测方法 | 故障处理 |
|---|---|---|---|
| 虚拟机网络 | 桥接模式 | 网络设置检查 | 重新配置网络 |
| IP 地址 | 同一网段 | ping 命令测试 | 修改 IP 配置 |
| 设备连接 | SSH 可达 | 连接测试 | 检查网络和权限 |
详细配置步骤:
①:网络桥接配置:检查虚拟机网络是否正常启动,将虚拟机的网络桥接到物理网卡。

②:网络连通性测试:测试虚拟机和触摸屏网络是否连通,需确保电脑和屏处于同一网段。触摸屏接上网线获取 IP 后,打开虚拟机终端【快捷键:Ctrl+Alt+T】ping 触摸屏。

③:调试设备配置:配置调试设备参数,并进行网络连通性测试。

④:连接测试结果:点击测试后,输入 HMI 的密码后查看检测结果。

⑤:故障处理方案:如果出现测试失败,在终端中执行命令 rm -rf /home/wecon/.ssh/* 可以解决此问题。

⑥:静态 IP 配置:当设备采用静态 IP 或直连时,需对虚拟机的 IP 进行配置保证其在相同网段下。
- 打开菜单,点击设置。

- 打开网络设置。

- 设置静态 IP 地址。

- 当出现连接速度慢导致无法连接的问题,需修改连接等待时间,最后点击 Test 测试,测试通讯成功即可应用保存。

5.2 运行 Qt 程序
程序运行模式表
| 运行模式 | 功能 | 适用场景 |
|---|---|---|
| 运行程序 | 发布运行 | 功能测试 |
| 调试运行 | 调试运行 | 问题排查 |
运行操作:在设备连接成功的基础上进行程序运行,运行程序和调试运行程序。

5.3 调试快捷键说明
调试快捷键功能对照表
| 快捷键 | 功能描述 | 使用场景 | 操作说明 |
|---|---|---|---|
| F5 | 开始调试 | 启动调试会话 | 从当前断点开始执行程序,进入调试模式 |
| Shift + F5 | 停止调试 | 终止调试会话 | 立即停止正在进行的调试过程 |
| F9 | 设置 / 取消断点 | 代码断点管理 | 在当前行设置或移除断点 |
| F10 | 单步前进 | 逐过程调试 | 执行当前行代码,不进入函数内部(Step Over) |
| F11 | 单步进入函数 | 逐语句调试 | 执行当前行代码,并进入被调用函数内部(Step Into) |
| Shift + F11 | 单步跳出函数 | 函数跳出调试 | 执行完当前函数剩余代码,返回到调用处(Step Out) |