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

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

示例覆盖两款 D125 MIPI 屏开发板，以及 D133、D213 的 LVDS 屏开发板。四款 Dashboard 均显示模拟动态读数，包含居中的芯片型号标题、四个仪表、曲线、进度条和状态灯；横屏与竖屏采用两列等宽区域，分别居中展示合作方标识和网站。另提供 D213 boot-shell，用于单独排查 NAND 启动和 LVDS 显示。

开始前准备

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

版本与验证范围

本文于 2026-10-17 对照仓库 README和 west.yml更新，固定应用提交为 6ca0dbb（2026-10-16）。依赖仍由 manifest 固定。仓库中的历史编译和上板记录不等同于该最新提交已完成全部硬件验收；最新品牌布局的硬件验证仍待确认。本文更新未重新编译固件或执行上板测试，具体记录见第 9 节。

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 支持的版本。

本次文档对照的应用提交与 manifest 依赖如下：

内容	Commit SHA
demo-apps	6ca0dbbd785a9d7efd64cffb46805fe2627a1fcb
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 \
  6ca0dbbd785a9d7efd64cffb46805fe2627a1fcb

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

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

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

west init -l zephyr-artinchip-demo-apps

west update
west manifest --validate

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

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

west topdir
west list

west topdir 应显示刚创建的工作区。当前 manifest 已使用 HTTPS，可直接运行 west update，不再需要 SSH 地址转换。若下载中断，直接重试即可，不需要删除工作区。west manifest --validate 用于检查 manifest 格式，不能代替后续编译和硬件验收。

主要目录如下，依赖目录由 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 -p always \
  -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 -p always \
  -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 -p always \
  -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 -p always \
  -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。

上述命令使用 -p always，每次清理 -d 指定的构建目录后重新编译。确认源码目录、板型和配置不变时，可移除此参数以增量编译；切换配置时保留它。内存不足时可增加 -o=-j2 限制构建并行度。

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

7.5 D213 boot-shell：单独验证启动与显示

需要先定位 NAND 启动问题时，可构建不初始化显示的最小 boot-shell：

west build --sysbuild -p always -b artinchip_d21x_demo128_nand/d21x \
  zephyr-artinchip-demo-apps/applications/boot-shell -d build/d213_mcuboot_shell -- \
  -DZEPHYR_EXTRA_MODULES="$PWD/zephyr-artinchip-tools"
python zephyr-artinchip-tools/scripts/mk_image_zephyr.py --build-dir build/d213_mcuboot_shell

若要测试 LVDS 彩条和移动标记，在上面同一条 west build 命令的 CMake 参数末尾追加以下参数（上一行需添加续行符 \），并保留 -p always：

-Dboot-shell_EXTRA_CONF_FILE=d213-lvds.conf
-Dboot-shell_EXTRA_DTC_OVERLAY_FILE=d213-lvds.overlay

切回纯串口测试时，移除这两个参数并重新执行 pristine 构建。输出仍为 build/d213_mcuboot_shell/airburn/artinchip_d21x_demo128_nand_v0.1.0.img。该测试使用自己的构建目录，不与 Dashboard 混用。

8. 找到生成的镜像

以下为对应板型的镜像路径示例，均相对于工作区根目录；实际文件名以本次构建生成的 image-path.txt 为准：

板型	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

截至本次更新，仓库 README 的验证记录区分了以下范围：

范围	已记录证据
四款基线 Dashboard	2026-10-12 用户报告上板测试通过
最新横屏品牌布局	2026-10-16 内部 D125 MIPI 编译及 19 项 MCUboot/AirBurn 检查通过
公开提交 786c40e 的四款应用	全部编译通过；每个 NOR 镜像 19 项检查通过，D213 NAND 镜像 23 项通过；无新增上板记录
新竖屏品牌布局	内部编译及 19 项 MCUboot/AirBurn 检查通过，硬件验证待完成
最新品牌布局上板效果	尚未确认

这些是仓库记录，并非本文重新执行的测试，也不能直接视为最新提交 6ca0dbb 的完整验收结果。发布前应从公开 manifest 构建受影响的应用，并检查启动、UART 输入、动态显示及 ROM 升级入口。上方工具测试和 QEMU 命令可用于回归检查，但本次不沿用旧快照的测试数量作为最新版本结果。

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 使用 HTTPS；检查是否仍在使用旧 manifest 或本地 Git URL 重写配置，并核对固定提交。
提示缺少 littlefs Python 模块	在工作区虚拟环境中安装 littlefs-python，见第 4 节。
找不到 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、完整构建命令、验证脚本结果和串口日志。

相关资料

• ArtInChip Zephyr demos 源码仓库

• 本文对应 README 快照 · 依赖 manifest

• 匠芯创 cJTAG / JTAG 实板调试：FT232H、OpenOCD 与 GDB

• 匠芯创 D126 Wi-Fi / BLE 使用

• 匠芯创芯片型号汇总