UniRTOS快速开发指导
本文档主要指导用户搭建适用于EG800Z系列？榭⒌腢niRTOS软件环境，并通过一个简单示例，展示如何使用UniRTOS配置功能选项、编译并烧录固件到对应？樾秃诺目。
开发准备
在开始之前，请准备下列软硬件：
硬件准备：
- pico开发板（以下内容以该开发板为例）。
- USB数据线 （USB-A转USB-C）。
- PC (Windows 10/Windows 11)。
软件准备：
- unirtos-toolchain.exe：编译工具链安装程序，点此获取。
- Python：用于运行unirtos-cli工具，需使用3.9及更高版本。安装步骤详见。
- Git：unirtos-cli使用该工具拉取SDK、依赖库等，需使用2.40及更高版本。安装步骤详见。
- unirtos-cli：UniRTOS的命令行工具，用于一键拉取SDK、快速创建工程。安装步骤详见。
- USB驱动：用于PC识别？榈腢SB枚举接口，点此获取。
- QFlash.exe：？楣碳烧录程序，用于烧录UniRTOS编译生成的固件，点此获取。
- EPAT工具：芯片厂商提供的日志抓取工具，用于查看？樵诵腥罩疽苑治鲇τ贸绦蛑葱星榭觯点此获取。
- QCOM工具：乐天使官方提供的串口调试工具，用于执行和验证AT命令，点此获取。
环境搭建
USB驱动安装
安装程序
1. 解压下载好的驱动压缩包，双击setup.exe执行安装。
2. 根据提示选择安装目录，点击“Next”即可。推荐选择默认路径。
3. 等待安装进度条完成，点击“Finish”。
验证驱动
使用USB数据线连接电脑与开发板，长按开发板的电源键开机。在设备管理器中查看是否识别出以“Quectel”开头的端口，如图所示：
unirtos-toolchain编译工具链安装
安装程序
1. 双击unirtos-toolchain.exe执行安装程序，提示申请管理员权限时，点击“同意”。
2. 根据提示选择解压目录，默认为D:\unirtos-toolchain，用户可根据需要自定义安装目录。解压后文件约占4.3GB空间，请确保磁盘空间充足。
3. 解压完成后，目录结构如下，包含CMake、Ninja、Python 3.8和GCC编译工具。
验证编译环境
新建命令行窗口，输入unirtos.exe --version检查版本信息。若成功显示版本信息，则表示编译环境安装完成。
Python环境安装
下载安装包
1. 进入Python官网，选择“Download”选项下的“Windows”版本。
2. 根据自身系统选择对应版本下载，例如Windows 64位系统选择“Windows installer (64-bit)”即可。
安装Python程序
1. 双击下载的“.exe”可执行程序开始安装，勾选底部“Use admin privileges when installing py.exe”和”Add python .exe to PATH“两个选项，点击“Install Now”。如需配置特定功能或修改安装路径，可选择“Customize installation”。
2. 显示此页面即表示Python安装成功。
3. 打开PowerShell或cmd窗口，输入“python --version”查询。若安装成功，将输出版本号。若未输出版本号或报错“找不到Python命令”，可能是安装过程中未勾选添加环境变量，可手动添加Python执行路径到环境变量中。
安装Git工具
1. 双击下载的“.exe”可执行程序开始安装，点击“Next”进入下一步。
2. 选择Git工具的安装路径。
3. 后续功能选项配置根据自身需求选择即可。最后出现此页面时，点击“Finish”完成安装。
4. 打开PowerShell或cmd窗口，输入“git --version”查询。若安装成功，PowerShell终端将输出版本号。若未输出版本号或报错“找不到git命令”，请确认Git的安装路径已添加到环境变量中。
unirtos-cli工具安装
安装unirtos-cli工具
1. 按下“Win + R”键，输入“powershell”，打开Windows的PowerShell窗口。
2. 在PowerShell窗口输入命令“pip install unirtos-cli”安装unirtos-cli工具，随后输入“unirtos-cli version”，若成功输出版本号，则表示工具安装成功。
QFlash烧录工具安装
QFlash为免安装工具，解压下载好的压缩包后，打开解压目录，双击其中的.exe可执行程序即可运行。
新增HelloWorld程序
查看远程可用示例
执行命令
打开新的PowerShell窗口，执行以下命令：
unirtos-cli ls-demos
执行结果如图：
创建Hello World新工程
执行命令
继续在PowerShell窗口执行以下命令：
unirtos-cli new -r unirtos_helloworld_demos
执行完成后，工具将自动从官方示例仓库下载helloworld示例，并生成新的项目工程。
执行结果如图：
命令格式与参数说明
unirtos-cli new [-r] <project-name> [-v <version>] [-d <project-dir>] [-f]
-
功能描述??创建一个新的项目，支持两种模式：一种是基于模板创建，另一种是直接基于现有示例创建。
- 参数说明
|
参数
|
默认值
|
说明 |
|
project-name
|
必填
|
项目名称（仅限名称，不可包含路径分隔符），与-r同时使用时为远程示例名称
|
|
-r, --from-demo
|
关闭
|
基于远程已有的示例创建项目
|
|
-v, --version
|
省略
|
指定远程示例的版本（支持 1.0.0、v1.0.0 等格式）。该参数仅可与参数-r同时使用；省略时自动选用最新版本
|
|
-d, --project-dir
|
.（当前目录）
|
指定项目基目录。项目最终会生成在<project-dir>/<project-name>路径下
|
|
-f, --force
|
关闭
|
强制更新<unirtos_root>/demos/manifests后再基于示例创建。该参数仅可与-r同时使用
|
初始化工程环境
执行命令
打开PowerShell窗口，进入上一步创建的工程目录（名称为unirtos_helloworld_demos-{版本号}），执行以下命令：
unirtos-cli env-setup
执行命令后，unirtos-cli会根据env_config.json的默认配置从远程拉取SDK到本地，默认存放路径为C:\Users\<用户名>\.unirtos。后续拉取相同版本时，将直接复用本地已缓存的SDK，无需再次从远程下载。
命令执行结果如图：
使用VS Code打开工程
环境拉取完成后，项目目录下会自动生成一个VS Code工作区文件。双击打开该文件，工作区将同时包含当前项目及拉取的SDK，方便在VS Code中直接查阅SDK、组件库等的源码等内容。
编译工程
工程目录结构
进入工程目录
进入新创建的工程所在目录，如下图所示：
目录结构说明
unirtos_helloworld_demos-1.0.0/ ├── CMakeLists.txt // CMake构建脚本 ├── env_config.json // unirtos-cli使用的环境配置文件 ├── hello_world.c // 应用源代码 ├── README.md // 应用说明文档 └── unirtos_helloworld_demos-1.0.0.code-workspace // VS Code项目工作区文件
SDK目录结构
SDK存放路径
默认路径为C:\Users\<用户名>\.unirtos，拉取的SDK位于该路径下的sdk目录。以1.0.1版SDK为例（如下图所示）：
目录结构说明
目录树： ├─cmake // CMake相关配置文件 ├─qos_applications/ // 存放应用示例与业务代码 │ ├─app_init // App层初始化相关文件 │ └─unirtos_std // AT侧相关功能 ├─qos_components/ // 系统组件与中间件 │ ├── components/ // 可裁剪功能组件 │ └── system/ // 系统服务、驱动、协议栈 ├─qos_kernel/ // 存放各平台内核适配相关工程 │ └── eigen_718/ // 平台适配代码 └─qos_tools // 编译及调试工具 │ └── python/ // 构建/配置/打包Python工具 ├─build.sh // 一键构建脚本 ├─CMakeLists.txt // UniRTOS编译的主CMake工程文件 ├─Kconfig // 主配置入口，管理宏控依赖及约束条件 └──...
编译固件
执行命令
当前以指定编译EG800ZCN_LA固件为例，在工程目录下打开PowerShell终端，输入以下命令。如果实际使用的并非EG800ZCN_LA？，需将命令中的？樾秃盘婊晃导适褂玫男秃。
unirtos-cli build -m EG800ZCN_LA -v EG800ZCNLAR01A01_OCPU_20260625
等待编译结束后，日志末尾会提示固件编译结果。编译成功的日志如下图所示：
命令格式与参数说明
unirtos-cli build [-d <project-dir>] [-j <jobs>] [-m <module>] [-v <version>]
-
功能描述??调用UniRTOS工具链编译当前外部应用。
- 参数说明
|
参数
|
默认值
|
优先级
|
说明 |
|
-d, --project-dir
|
.（当前命令执行路径）
|
—
|
项目目录
|
|
-j, --jobs
|
4
|
CLI > env_config.build.jobs > 4
|
并行编译线程数
|
|
-m, --module
|
env_config.build.module
|
CLI > env_config.build.module
|
模块名，例如 EG800ZCN_LA
|
|
-v, --version
|
应用根目录名称
|
CLI > env_config.build.version > 应用根目录名称
|
固件版本字符串
|
固件输出路径
固件包输出路径位于项目目录下的qos_build\release路径。
固件烧录
打开QFlash工具
双击运行QFlash_V8.0.exe可执行程序，打开QFlash工具。
烧录固件
在QFlash中加载固件
打开QFlash程序，点击“Load FW Files”：
选择固件包
在弹出的文件选择窗口中，定位至对应工程目录下的qos_build\release文件夹，选择.hbinpkg格式的固件包文件。
获取设备AT端口号
设备长按电源键开机。打开设备管理器，查看“端口 (COM和LPT)”中的Quectel USB AT Port，并记录COM端口号：
配置端口并开始烧录
在QFlash工具的COM Port下拉菜单中选择对应的COM端口，点击“Start”按钮开始烧录。等待进度条完成，且状态显示为PASS：
验证烧录结果
启动QCOM串口调试工具，选择之前记录的AT端口。在发送区输入AT并发送，若？榛馗OK，则证明固件烧录成功且设备运行正常。
日志查看
查看程序运行日志
不同平台查看日志使用的工具不同，以EG800Z为例，EG800Z属于移芯平台，查看日志使用EPAT工具，若未安装请前往下载专区下载安装。
1.打开EPAT工具，选择“Serial Device”并点击“OK”：
2.? 点击“Device Communication”，选择串口设备并点击“打开”：
3. 选择设备管理器中的“Quectel USB DIAG Port” COM通道，点击“OK”查看日志输出：
4. 点击“Database state”，选择数据库文件，匹配日志数据库：
5. 选择qos_build\release自定义版本文件夹下的DBG/comdb.txt文件，点击“Update”：
6. 在“UniLogViewer”选项卡，点击“Stop”停止日志记录：
7. 使用“Ctrl+F”搜索“hello world”，点击“Find Previous”查看hello world程序日志：
