Building a Base Yocto Image for Raspberry Pi Zero 2W

A step-by-step guide to building and booting a clean base Yocto image for the Raspberry Pi Zero 2W

December 11, 2025

Building a Base Yocto Image for Raspberry Pi Zero 2W

I'm planning to work on a small project based on the Raspberry Pi Zero 2W.
Due to the nature of the project, significant modifications to the bootloader and kernel may be required, so I've decided to build a custom image using the Yocto environment instead of using existing Ubuntu or Raspbian images.

1. Setting up the Yocto Environment

First, you need to set up the build environment by downloading the Yocto Project (Poky) and the Raspberry Pi-specific layer, meta-raspberrypi.

Installing Prerequisites

Based on an Ubuntu host (22.04 or 24.04 LTS), install the essential packages required for Yocto builds.


Installing Prerequisites for Yocto
shell

Cloning Sources

Clone poky and the necessary meta-* recipes required for the Yocto build. We will use scarthgap, which is the latest LTS branch of the Yocto Project.


Cloning Sources
shell

2. Initializing Build Environment

Run the oe-init-build-env script to create the build directory.

You need to add the meta layer for the Raspberry Pi build.

Configure the MACHINE setting in the conf file.
To use linux-firmware-rpidistro, you also need to configure the license settings.


vi conf/local.conf
diff

3. Building the Image

Now, build the image. You can perform the build with core-image-base.

4. Flashing and Testing

Once the build is successful, a wic image will be generated.
The <mark>wic</mark> file is a complete disk image containing the partition table, bootloader, and root filesystem, allowing it to be bootable immediately after flashing without additional partitioning.


Flashing to SD Card
shell

5. Verifying Boot

Insert the SD card into the Raspberry Pi Zero 2W and connect it via Mini-HDMI to check the serial console logs.

PreviousGetting Started with the SmartThings API - Environment Setup