匠芯创 D125 / D133 / D213 Zephyr 开发入门：从源码构建到 AirBurn 烧录

从源码生成一份可供 AirBurn 烧录的镜像，需要准备应用、板级支持、引导程序和打包工具。本文以 Zephyr Dashboard 为示例，串起匠芯创 D125、D133、D213 的完整开发流程：建立工作区、获取依赖、编译 MCUboot 与应用、生成 .img，最后完成烧录和板上验收。

示例覆盖两款 D125 MIPI 屏开发板，以及 D133、D213 的 LVDS 屏开发板。按目标板型选择对应应用，即可沿用同一套构建流程。

开始前准备

• 构建主机：Ubuntu 24.04 x86_64，使用 Bash 和 Python 3.12。
• 源码环境：新建独立 west 工作区，无需预先编译 LubanLite。
• 硬件与工具：第 6 节列出的对应开发板和屏幕、升级 USB 连接、串口连接，以及原厂 AirBurn 烧录工具。
• 下载方式：以下命令按三个 GitHub 仓库公开可访问编写，使用 HTTPS 获取源码。

版本与验证范围

本文根据项目提供的 2026-10-12 构建记录整理，命令和产物路径对应下方固定快照。记录包含独立编译、打包和软件校验；其中四个内部基线应用的上板验证，不等同于本次新生成镜像的硬件验收。完成构建后，仍需按第 10 节检查烧录、启动和显示效果。

1. 仓库和版本

仓库	用途	对外开发分支
https://github.com/UltraSemiCN/zephyr-artinchip-demo-apps.git	应用、显示布局、west manifest	main
https://github.com/UltraSemiCN/zephyr-artinchip.git	Zephyr、SoC、板级和驱动支持	main-artinchip
https://github.com/UltraSemiCN/zephyr-artinchip-tools.git	AirBurn 打包脚本、芯片资源、镜像检查	main

以 demo-apps 的 west.yml 为版本入口。 它固定源码和工具提交，并导入 MCUboot、LVGL 等依赖；不要分别克隆三个仓库的最新分支后直接混合构建。源码仓库的 main 是官方基线，不能代替包含 ArtInChip 支持的版本。

项目记录中的独立 GitHub 克隆构建使用以下版本：

内容	Commit SHA
demo-apps	6c40300eaf76705360060f4b427f4dbd51fa4603
zephyr-artinchip	b16c5b6e4e171b7bdd1a9d9be3b33abfb43251b8
zephyr-artinchip-tools	e5f236d66aca67263c19f27435a0bee26d5890fc
Zephyr SDK	1.0.1

建议首次构建固定到以上提交，便于对照本文排查问题；后续升级时，以所选 demo-apps 版本的 west.yml 和源码中的 SDK_VERSION 为准。

2. 安装主机依赖

sudo apt update
sudo apt install --no-install-recommends \
  git cmake ninja-build gperf ccache dfu-util device-tree-compiler \
  wget python3-dev python3-venv python3-tk xz-utils file make \
  gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

python3 --version
cmake --version
dtc --version

以上软件包列表针对 Ubuntu x86_64。其他发行版需使用对应包名；不要直接套用到 Windows 原生命令行。

如需代理，在执行下载命令的终端设置自己的 HTTP 代理地址，例如：

# 可选；地址和端口须替换为自己的代理。
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY="$HTTPS_PROXY"

无需代理时跳过。下文不修改全局 Git 配置。

3. 创建独立工作区并克隆应用

选择一个新的空目录作为 west 工作区。示例采用 $HOME/zephyr-github-test；已有同名目录时，可改用其他目录，避免覆盖已有工程。不要在另一个 west 工作区内嵌套创建。

mkdir -p "$HOME/zephyr-github-test"
cd "$HOME/zephyr-github-test"

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 'west==1.5.0'

git clone --branch main \
  https://github.com/UltraSemiCN/zephyr-artinchip-demo-apps.git

若要复现本文验证版本，在初始化前固定应用提交：

git -C zephyr-artinchip-demo-apps checkout \
  6c40300eaf76705360060f4b427f4dbd51fa4603

省略这一步则使用克隆时的 main，依赖版本由该版本的 west.yml 决定。固定提交后的 detached HEAD 是正常状态。

4. 初始化 west 并下载全部依赖

以下命令仍在工作区根目录执行：

west init -l zephyr-artinchip-demo-apps

# 当前发布 manifest 使用 git@github.com: 地址。
# 仅为这次 west update 将其转换成匿名 HTTPS 下载。
env GIT_CONFIG_COUNT=1 \
  GIT_CONFIG_KEY_0=url.https://github.com/.insteadOf \
  GIT_CONFIG_VALUE_0=git@github.com: \
  west update

export ZEPHYR_BASE="$PWD/zephyr-artinchip"
west zephyr-export

python -m pip install \
  -r zephyr-artinchip/scripts/requirements-base.txt \
  -r bootloader/mcuboot/scripts/requirements.txt

west topdir
west list

west topdir 应显示刚创建的工作区。Git URL 转换通过环境传给 west 启动的 Git 子进程，命令结束后不保留；后续再次执行 west update 时，也使用这段 env 命令。若下载中断，直接重试即可，不需要删除工作区。

主要目录如下，依赖目录由 west 自动创建：

zephyr-github-test/
├── .venv/
├── .west/
├── zephyr-artinchip-demo-apps/
├── zephyr-artinchip/
├── zephyr-artinchip-tools/
├── bootloader/mcuboot/
├── modules/
└── build/                       # 编译时生成

5. 安装 Zephyr SDK

在已激活虚拟环境、设置 ZEPHYR_BASE 的工作区中执行：

west sdk install --version 1.0.1 --gnu-toolchains riscv64-zephyr-elf
west sdk list

RISC-V GNU 工具链同时用于本文的 32 位 D125/D133 和 64 位 D213。该命令还安装默认主机工具；后文 QEMU 测试需要相应模拟器。

若已经安装 SDK 1.0.1，可复用安装目录，无需重复下载。例如安装位置为 $HOME/zephyr-sdk-1.0.1 时：

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-1.0.1"

实际安装在其他位置时应调整变量。不要让变量指向不存在的目录。SDK 版本以所用源码中的 SDK_VERSION 为准；本文固定快照要求 1.0.1。

重新打开终端后，构建前恢复工作区环境：

cd "$HOME/zephyr-github-test"
source .venv/bin/activate
export ZEPHYR_BASE="$PWD/zephyr-artinchip"
# 若 SDK 不在自动发现位置，还需重新设置 ZEPHYR_SDK_INSTALL_DIR。

6. 选择板型

应用和构建目录	west 板型	显示与存储
dashboard_1024x600_d125_mipi	artinchip_d12p_demo88_nor/d125ccr	D125 Demo，1024×600 EK79007AD MIPI，NOR
dashboard_720x1280_d125_mipi	ultrasemi_d12p_usbdisp_demo88_nor_5_5/d125ccv	UltraSemi D125，5.5 寸 720×1280 MIPI，NOR
dashboard_1024x600_d133_lvds	artinchip_d13x_demo88_nor/d13x	D133 Demo，1024×600 LVDS，NOR
dashboard_1024x600_d213_lvds	artinchip_d21x_demo128_nand/d21x	D213EC-V4 demo128，1024×600 LVDS，XT26G01CW SPI NAND、128 MiB DDR3

D125 Demo 使用 MIPI；D133、D213 使用 LVDS。不要仅根据分辨率互换镜像。

7. 编译并自动生成烧录镜像

以下四组命令均从工作区根目录执行。可只执行所需板型，也可依次执行全部四组。

7.1 D125 Demo：1024×600 MIPI

west build --sysbuild \
  -b artinchip_d12p_demo88_nor/d125ccr \
  zephyr-artinchip-demo-apps/applications/dashboard_1024x600_d125_mipi \
  -d build/dashboard_1024x600_d125_mipi -- \
  -DZEPHYR_EXTRA_MODULES="$PWD/zephyr-artinchip-tools"

python zephyr-artinchip-tools/tests/verify_mcuboot_build.py \
  build/dashboard_1024x600_d125_mipi

7.2 UltraSemi D125：720×1280 MIPI

west build --sysbuild \
  -b ultrasemi_d12p_usbdisp_demo88_nor_5_5/d125ccv \
  zephyr-artinchip-demo-apps/applications/dashboard_720x1280_d125_mipi \
  -d build/dashboard_720x1280_d125_mipi -- \
  -DZEPHYR_EXTRA_MODULES="$PWD/zephyr-artinchip-tools"

python zephyr-artinchip-tools/tests/verify_mcuboot_build.py \
  build/dashboard_720x1280_d125_mipi

7.3 D133 Demo：1024×600 LVDS

west build --sysbuild \
  -b artinchip_d13x_demo88_nor/d13x \
  zephyr-artinchip-demo-apps/applications/dashboard_1024x600_d133_lvds \
  -d build/dashboard_1024x600_d133_lvds -- \
  -DZEPHYR_EXTRA_MODULES="$PWD/zephyr-artinchip-tools"

python zephyr-artinchip-tools/tests/verify_mcuboot_build.py \
  build/dashboard_1024x600_d133_lvds

7.4 D213 Demo：1024×600 LVDS、NAND

west build --sysbuild \
  -b artinchip_d21x_demo128_nand/d21x \
  zephyr-artinchip-demo-apps/applications/dashboard_1024x600_d213_lvds \
  -d build/dashboard_1024x600_d213_lvds -- \
  -DZEPHYR_EXTRA_MODULES="$PWD/zephyr-artinchip-tools"

python zephyr-artinchip-tools/tests/verify_mcuboot_build.py \
  build/dashboard_1024x600_d213_lvds

--sysbuild 同时构建 MCUboot 和应用；应用已有对应 sysbuild 配置。ZEPHYR_EXTRA_MODULES 引入打包工具，构建完成后自动生成 AirBurn 镜像，不需要手工调用 mkimage。

重复执行对应构建命令会增量编译。如更换源码目录、板型或需要清除旧 CMake 配置，在该命令的 west build 后增加 -p always，只清理 -d 指定的构建目录。内存不足时可增加 -o=-j2 限制构建并行度。

四种应用均使用 MCUboot RAM-load 和 ECDSA-P256 签名。默认使用开发密钥；正式发布固件时通过 SB_CONFIG_BOOT_SIGNATURE_KEY_FILE 配置自己的签名密钥。

8. 找到生成的镜像

本文固定版本的输出路径如下，均相对于工作区根目录：

板型	AirBurn 镜像
D125 Demo	build/dashboard_1024x600_d125_mipi/airburn/artinchip_d12p_demo88_nor_v4.5.0-rc1.img
UltraSemi D125	build/dashboard_720x1280_d125_mipi/airburn/ultrasemi_d12p_usbdisp_demo88_nor_5_5_v4.5.0-rc1.img
D133 Demo	build/dashboard_1024x600_d133_lvds/airburn/artinchip_d13x_demo88_nor_v4.5.0-rc1.img
D213 Demo	build/dashboard_1024x600_d213_lvds/airburn/artinchip_d21x_demo128_nand_v0.1.0.img

文件名由板型和构建版本自动生成。更新源码后版本字段可能变化，应读取生成记录，不要手动重命名镜像或移动默认输出路径。

以 D125 Demo 为例：

app=dashboard_1024x600_d125_mipi
cat "build/$app/airburn/image-path.txt"
img=$(cat "build/$app/airburn/image-path.txt")
ls -lh "$img"
sha256sum "$img"

其他有用产物：

• build/<应用>/airburn/build-info.json：打包构建信息。
• build/<应用>/airburn/image_cfg.json：镜像组件及打包配置。
• build/<应用>/mcuboot/zephyr/zephyr.elf：MCUboot 调试文件。
• build/<应用>/<应用>/zephyr/zephyr.elf：应用调试文件。
• build/<应用>/<应用>/zephyr/zephyr.signed.bin：签名后的应用。

AirBurn 应选择 .img。单独的 zephyr.bin 或 zephyr.signed.bin 不等于完整烧录包。正常启动链为 ROM → PBP → MCUboot → Zephyr；工具资源中的升级器仅用于烧录过程，不代表运行时仍通过 tinySPL 启动应用。

9. 保存构建记录和运行软件检查

建议保存 manifest、各仓库提交和工具版本，以便复现问题：

mkdir -p test-results
west manifest --freeze > test-results/west-frozen.yml
python -m pip freeze > test-results/python-packages.txt
west --version > test-results/west-version.txt
cat zephyr-artinchip/SDK_VERSION > test-results/sdk-version.txt
for repo in zephyr-artinchip-demo-apps zephyr-artinchip zephyr-artinchip-tools; do
  git -C "$repo" rev-parse HEAD > "test-results/$repo.sha"
done

python -m unittest discover \
  -s zephyr-artinchip-tools/tests -p 'test_*.py'

如需运行 UART 和 D213 重启逻辑的 QEMU 回归测试：

python -m pip install \
  -r zephyr-artinchip/scripts/requirements-build-test.txt natsort

west twister -p qemu_riscv32 \
  -T zephyr-artinchip/tests/drivers/uart/artinchip_poll \
  -T zephyr-artinchip/tests/soc/artinchip/d21x_reboot \
  --outdir tests-out/uart-reboot --inline-logs -j 2

项目提供的固定快照构建记录包含以下结果，可作为复现时的对照：

检查项	记录结果
打包工具测试	31 项通过
QEMU 回归测试	7 项通过
四个构建的 MCUboot 镜像检查	共 80 项通过

以上为已有项目记录，并非本文发布时重新执行的测试。软件检查用于验证程序行为和镜像结构；显示接口、电源和实际 Flash 的工作情况，以板上验收为准。

10. 烧录和板上验收

1. 使用对应板型的升级 USB 接口，将板子进入原厂 ROM USB 升级模式。
2. 在原有 AirBurn/ArtInChip 烧录工具中选择第 8 节对应 .img，执行烧录。
3. 等待所有组件成功写入后重启板子。
4. 连接串口：115200、8N1、关闭硬件流控。
5. 确认 MCUboot 校验并跳转，Dashboard 仪表和曲线持续更新。
6. 在 aic:~$ 输入 help，检查连续输出、按键回显和画面流畅度。
7. 需要再次烧录时可输入 aicupg，或别名 uart aicupg。

四个应用均包含升级命令。它使板子重启进入 ROM USB 升级模式，主机仍需使用原厂烧录工具；它不是 Zephyr 中运行的 USB 上传服务。测试该命令前连接升级 USB 口，并准备接收设备重新枚举。

11. 如何判断构建是否一致

sha256sum 适合确认同一镜像在传输前后是否损坏，但两个独立构建的 .img 哈希不同，并不一定表示程序功能不同。Git 历史、标签和浅克隆深度可能影响写入二进制的版本字符串；ECDSA 签名也可能使最终镜像产生差异。

复现或排查时，建议依次核对：

1. 构建输入：manifest 固定提交、SDK 版本、配置和目标板型是否一致。
2. 镜像结构：对应构建的 verify_mcuboot_build.py 是否通过，PBP、升级器、分区和应用组件是否匹配。
3. 程序差异：必要时比较未签名程序，判断差异是否来自版本元数据。
4. 实际运行：烧录后检查启动日志、显示、Shell 和升级入口。

板型应以构建目标、设备树和打包信息为准，不要只依据版本字符串判断，也不要为追求哈希一致而覆盖真实版本信息。

12. 常见问题

现象	处理方法
Permission denied (publickey)	manifest 仍使用 SSH；按第 4 节的 env ... west update 进行 HTTPS 转换。
找不到 ArtInChip 板型	确认使用 demo-apps manifest 固定源码，且 ZEPHYR_BASE 指向本工作区；不要使用源码仓库官方 main。
west 或 Python 包找不到	激活本工作区 .venv，使用 python -m pip 安装依赖。
找不到 SDK / 编译器	检查 west sdk list、SDK_VERSION 和 ZEPHYR_SDK_INSTALL_DIR。
只有应用、没有 MCUboot 或 .img	使用 --sysbuild 和正确的 ZEPHYR_EXTRA_MODULES，并确认整个构建成功。
CMake 提示应用目录与缓存不一致	每个应用使用独立构建目录；对该目录执行 -p always 重建。
编译进程被系统终止	检查主机内存，使用 -o=-j2 降低并行度。
提示下载失败或超时	检查网络/代理；重新执行失败的下载步骤，无需清空源码。
串口能进入 Shell，但屏幕不亮	核对 MIPI/LVDS、屏幕供电、接口和应用板型，不要交换不同板型镜像。
NAND 升级器提示 unknown raw ID	核对是否为 XT26G01CW、是否使用固定版本工具资源，保存完整烧录和串口日志。
升级后卡在 PBP 或 MCUboot	保留从上电开始的完整日志、镜像 SHA 和版本记录，区分烧录阶段与运行阶段；单凭“烧录成功”不能确认启动成功。

遇到失败时应先定位第一个错误。提交问题记录时附上板型、屏幕接口、源码 SHA、完整构建命令、验证脚本结果和串口日志。

相关资料

• 匠芯创 cJTAG / JTAG 实板调试：FT232H、OpenOCD 与 GDB
• 匠芯创 D126 Wi-Fi / BLE 使用
• 匠芯创芯片型号汇总