Getting Started with Zephyr on ArtInChip D125 / D133 / D213: From Source to AirBurn Flashing

Creating an image for AirBurn requires the application, board support, bootloader and packaging tools. Using Zephyr Dashboard as an example, this guide covers the development workflow for the ArtInChip D125, D133 and D213: create a workspace, fetch dependencies, build MCUboot and the application, generate an .img, then flash and validate it on hardware.

The examples cover two D125 boards with MIPI displays, plus D133 and D213 boards with LVDS displays. All four dashboards show animated simulated readings, a centered chip-specific title, four gauges, a chart, progress bars and status lights. Landscape and portrait layouts use two equal-width columns to center the partner logos and websites. A separate D213 boot-shell helps isolate NAND startup and LVDS display issues.

Before you start

• Build host: Ubuntu 24.04 x86_64, Bash, Python 3.12+, CMake 3.28+ and Ninja.
• Source environment: a new, independent west workspace. Building LubanLite first is not required.
• Hardware and tools: a board and display listed in section 6, an upgrade USB connection, a serial connection and the vendor's AirBurn flashing tool.
• Downloads: the commands assume all three GitHub repositories are publicly accessible and use HTTPS to fetch source code.

Versions and validation scope

Updated on 2026-10-17 against the repository README and west.yml, with application commit 6ca0dbb (2026-10-16). Dependencies remain pinned by the manifest. Historical build and board records do not establish complete hardware validation of this latest commit; hardware verification of the latest branding remains pending. No firmware builds or board tests were rerun for this article update. See section 9 for the recorded evidence.

1. Repositories and versions

Repository	Purpose	Public development branch
https://github.com/UltraSemiCN/zephyr-artinchip-demo-apps.git	Applications, display layouts and west manifest	main
https://github.com/UltraSemiCN/zephyr-artinchip.git	Zephyr, SoC, board and driver support	main-artinchip
https://github.com/UltraSemiCN/zephyr-artinchip-tools.git	AirBurn packaging scripts, chip resources and image checks	main

Use the demo-apps west.yml as the version entry point. It pins source and tool commits and imports dependencies such as MCUboot and LVGL. Do not clone the latest branches of all three repositories separately and combine them. The source repository's main is the upstream baseline, not the version containing ArtInChip support.

This update references the following application commit and manifest dependencies:

Component	Commit SHA or version
demo-apps	6ca0dbbd785a9d7efd64cffb46805fe2627a1fcb
zephyr-artinchip	b16c5b6e4e171b7bdd1a9d9be3b33abfb43251b8
zephyr-artinchip-tools	e5f236d66aca67263c19f27435a0bee26d5890fc
Zephyr SDK	1.0.1

For the first build, pin these commits to simplify troubleshooting against this guide. When upgrading later, follow the selected demo-apps version's west.yml and the source tree's SDK_VERSION.

2. Install host dependencies

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

This package list targets Ubuntu x86_64. Use the appropriate package names on other distributions; these commands are not intended for a native Windows command prompt.

If a proxy is required, set your HTTP proxy address in the terminal used for downloads. For example:

# Optional: replace the address and port with your own proxy.
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY="$HTTPS_PROXY"

Skip this step if no proxy is needed. The instructions below do not change global Git configuration.

3. Create an independent workspace and clone the application

Choose a new, empty directory for the west workspace. This example uses $HOME/zephyr-github-test. If it already exists, choose another directory to avoid overwriting an existing project. Do not nest this workspace inside another west workspace.

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

To use the source snapshot referenced by this guide, pin the application commit before initialization:

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

Skipping this step uses main as it exists when cloned, with dependency versions determined by that revision's west.yml. A detached HEAD is expected after checking out a specific commit.

4. Initialize west and download dependencies

Run these commands from the workspace root:

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 should display the workspace you just created. The current manifest uses HTTPS, so run west update directly without an SSH URL rewrite. Retry interrupted downloads without deleting the workspace. west manifest --validate checks manifest syntax; it does not replace build or hardware validation.

The main directories are shown below. West creates the dependency directories automatically:

zephyr-github-test/
├── .venv/
├── .west/
├── zephyr-artinchip-demo-apps/
├── zephyr-artinchip/
├── zephyr-artinchip-tools/
├── bootloader/mcuboot/
├── modules/
└── build/                       # Generated during the build

5. Install the Zephyr SDK

With the virtual environment active and ZEPHYR_BASE set, run:

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

The RISC-V GNU toolchain supports both the 32-bit D125/D133 and the 64-bit D213 in this guide. The command also installs the default host tools; the QEMU tests later in this guide require the corresponding emulator.

If SDK 1.0.1 is already installed, reuse its directory. For example, if it is installed at $HOME/zephyr-sdk-1.0.1:

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

Adjust the variable if your SDK is elsewhere, and ensure the directory exists. Use the SDK version specified by SDK_VERSION in your source tree; this guide's pinned snapshot requires 1.0.1.

After opening a new terminal, restore the workspace environment before building:

cd "$HOME/zephyr-github-test"
source .venv/bin/activate
export ZEPHYR_BASE="$PWD/zephyr-artinchip"
# Set ZEPHYR_SDK_INSTALL_DIR again if the SDK is not auto-discovered.

6. Select a board

Application and build directory	west board target	Display and storage
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-inch 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

The D125 Demo uses MIPI; D133 and D213 use LVDS. Matching display resolution alone does not make images interchangeable.

7. Build and automatically generate flashing images

Run each command group from the workspace root. Build only the board you need, or run all four groups in sequence.

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 builds MCUboot and the application together; the applications already contain the required sysbuild configuration. ZEPHYR_EXTRA_MODULES includes the packaging tools so that the build generates an AirBurn image automatically. There is no need to invoke mkimage manually.

The commands use -p always to clean the directory specified by -d before rebuilding. Remove this option for incremental builds only when the source directory, board and configuration are unchanged; retain it when switching configurations. If memory is limited, add -o=-j2 to reduce build parallelism.

All four applications use MCUboot RAM-load and ECDSA-P256 signatures. Development keys are used by default. For production firmware, configure your own signing key through SB_CONFIG_BOOT_SIGNATURE_KEY_FILE.

7.5 D213 boot-shell: isolate startup and display tests

For a minimal NAND boot test without display initialization, build 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

To test LVDS color bars and a moving marker, append these CMake arguments to the same west build command (add a continuation backslash \ to the preceding line), keeping -p always:

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

When switching back to the shell-only test, remove both arguments and run a pristine build again. The output remains build/d213_mcuboot_shell/airburn/artinchip_d21x_demo128_nand_v0.1.0.img. Keep this build directory separate from the Dashboard builds.

8. Locate the generated images

These example image paths are relative to the workspace root. Read the actual filename from the generated image-path.txt for your build:

Board	AirBurn image
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

Filenames are generated from the board target and build version. Version fields may change after a source update. Read the generated path record instead of manually renaming images or moving the default output location.

For example, for the 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"

Other useful outputs include:

• build/<application>/airburn/build-info.json: packaging and build information.
• build/<application>/airburn/image_cfg.json: image components and packaging configuration.
• build/<application>/mcuboot/zephyr/zephyr.elf: MCUboot debugging file.
• build/<application>/<application>/zephyr/zephyr.elf: application debugging file.
• build/<application>/<application>/zephyr/zephyr.signed.bin: signed application.

Select the .img in AirBurn. A standalone zephyr.bin or zephyr.signed.bin is not a complete flashing package. The normal boot chain is ROM → PBP → MCUboot → Zephyr. The upgrader included in the tool resources is used only during flashing; its presence does not mean the application still boots through tinySPL at runtime.

9. Save build records and run software checks

Save the manifest, repository commits and tool versions to help reproduce issues:

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'

To run QEMU regression tests for UART and D213 reboot logic:

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

The repository validation records distinguish these scopes:

Scope	Recorded evidence
Four baseline dashboards	User-reported board tests passed on 2026-10-12
Latest landscape branding	Internal D125 MIPI build and 19 MCUboot/AirBurn checks passed on 2026-10-16
Four applications at public commit 786c40e	All built; 19 checks passed per NOR image and 23 for D213 NAND; no new board results
New portrait branding	Internal build and 19 MCUboot/AirBurn checks passed; hardware verification pending
Latest branding on hardware	Not yet confirmed

These are repository records, not tests rerun for this article, and do not establish full acceptance of the latest commit 6ca0dbb. Before release, build affected applications from the public manifest and check boot, UART input, animated display and ROM upgrade entry on hardware. The tool and QEMU commands above remain available for regression checks; old snapshot test counts are not presented as results for the latest version.

10. Flash and validate on hardware

1. Connect the board's upgrade USB port and enter the vendor's ROM USB upgrade mode.
2. Select the matching .img from section 8 in the AirBurn/ArtInChip flashing tool and flash it.
3. Wait until all components are written successfully, then restart the board.
4. Connect the serial console at 115200, 8N1, hardware flow control disabled.
5. Confirm that MCUboot verifies and starts the application, and that Dashboard gauges and curves keep updating.
6. Enter help at aic:~$ and check continuous output, key echo and display smoothness.
7. To flash again, enter aicupg or its alias, uart aicupg.

All four applications include the upgrade command. It restarts the board into ROM USB upgrade mode; the host still needs the vendor's flashing tool. This is not a USB upload service running inside Zephyr. Before testing the command, connect the upgrade USB port and be prepared for the device to re-enumerate.

11. Compare builds

sha256sum helps detect corruption when transferring the same image. Different .img hashes from independent builds do not necessarily indicate different program behavior. Git history, tags and shallow clone depth can affect version strings embedded in binaries; ECDSA signatures can also change the final image.

When reproducing or troubleshooting a build, check the following in order:

1. Build inputs: pinned manifest commits, SDK version, configuration and target board.
2. Image structure: whether verify_mcuboot_build.py passes and the PBP, upgrader, partitions and application components match.
3. Program differences: compare unsigned programs when needed to determine whether differences come from version metadata.
4. Hardware behavior: after flashing, check startup logs, display, Shell and the upgrade entry point.

Identify the board from the build target, device tree and packaging information. Do not rely solely on a version string or overwrite real version information just to obtain identical hashes.

12. Troubleshooting

Symptom	Action
Permission denied (publickey)	The current manifest uses HTTPS. Check for an older manifest or local Git URL rewrite and confirm the pinned commit.
Missing littlefs Python module	Install littlefs-python in the workspace virtual environment as shown in section 4.
ArtInChip board target not found	Use the source revision pinned by the demo-apps manifest and point ZEPHYR_BASE to this workspace. Do not use the source repository's upstream main.
west or Python packages not found	Activate the workspace's .venv and install dependencies with python -m pip.
SDK or compiler not found	Check west sdk list, SDK_VERSION and ZEPHYR_SDK_INSTALL_DIR.
Application built, but no MCUboot or .img	Use --sysbuild and the correct ZEPHYR_EXTRA_MODULES, and ensure the entire build succeeds.
CMake reports a source directory/cache mismatch	Use a separate build directory for each application and rebuild that directory with -p always.
Build process killed by the system	Check host memory and reduce parallelism with -o=-j2.
Download fails or times out	Check the network or proxy and retry the failed download step without deleting the source tree.
Serial Shell works, but the display stays dark	Check MIPI/LVDS, display power, connections and the application board target. Do not swap images between board targets.
NAND upgrader reports unknown raw ID	Confirm XT26G01CW hardware and the pinned tool resources. Save complete flashing and serial logs.
Boot stops at PBP or MCUboot after upgrading	Save complete logs from power-on, the image SHA and version records. Distinguish flashing from runtime startup; successful flashing alone does not prove successful boot.

Locate the first error before investigating later failures. When reporting an issue, include the board target, display interface, source SHAs, full build command, verification script results and serial logs.

Related resources

• ArtInChip Zephyr demos repository

• README snapshot for this guide · Dependency manifest

• ArtInChip cJTAG / JTAG Board Debugging: FT232H, OpenOCD and GDB

• ArtInChip D126 Wi-Fi / BLE

• ArtInChip IC catalog