# meta-raspberrypi is the Yocto layer that builds Raspberry Pi images

> meta-raspberrypi is a Yocto and OpenEmbedded BSP overlay for Raspberry Pi boards, approved as a Yocto Project Compatible Layer and built with bitbake or kas. It produces a bootable .wic.bz2 image for an SD card, and its real cost is the three upstream layers it depends on tracking master.

**agherzan/meta-raspberrypi** — Yocto/OE BSP layer for the Raspberry Pi boards

- Repository: https://github.com/agherzan/meta-raspberrypi
- Website: https://www.yoctoproject.org/
- Stars: 693 · Forks: 484
- Language: C
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/agherzan-meta-raspberrypi

## What a BSP layer actually is

meta-raspberrypi is described as the general hardware specific BSP overlay for the Raspberry Pi device, and it is a Yocto and OpenEmbedded layer rather than a distribution. That distinction is the whole mental model. A distribution bundles a kernel, a userland and a package set, while a layer adds hardware support on top of one, so the recipes here describe how to build a kernel, what firmware a board needs, which device trees to use and how the bootloader should be laid out on the SD card. The layer is written primarily in C, in the recipe and kernel configuration sense rather than as an application. Its scope is broad, with top level directories for recipes-bsp, recipes-connectivity, recipes-core, recipes-devtools, recipes-graphics, recipes-kernel, recipes-multimedia, recipes-sato and recipes-support, plus classes/, conf/, files/, dynamic-layers/, kas/ and docs/. The conf/ directory is where the per machine configuration lives, and that is how the same layer produces an image for a Pi Zero and a Pi 4 without forking.

## Three upstream layers, all pinned to HEAD

The dependencies section is short and it is the part that decides your upgrade policy. The layer depends on bitbake from git.openembedded.org with branch master and revision HEAD, on openembedded-core from the same host with branch master and revision HEAD, and on meta-yocto from git.yoctoproject.org, again master and HEAD. Pinning to a moving branch is unusual for a production build, and it has a direct consequence. A build that worked on Tuesday can fail on Friday without a single change in meta-raspberrypi, because the layer underneath it moved. For a hobbyist or a development board that is a reasonable trade, since you want current kernel and userspace fixes for free. For a product, you need to pin those revisions yourself, which the layer permits but does not do for you. The layer also states that the core BSP part should work with different OpenEmbedded and Yocto distributions and layer stacks, listing a distro-less setup with only OE-Core, the Yoe Distro aimed at video and camera products, and Yocto with Poky, which the README names as the main focus of testing.

## The kas path is the shorter route to a bootable card

There are two documented build paths and the kas one is considerably less work. The classic path starts by sourcing the OpenEmbedded build environment, adding the layer and its dependencies to bblayers.conf, setting MACHINE in local.conf to a supported board, running bitbake core-image-base, copying the generated .wic.bz2 file to the SD card with bmaptool and booting the Pi. The kas path avoids the manual layer configuration. You install the build tool from PyPI, choose a machine configuration file from the kas/ directory, and run a single build command.

```bash
   pip3 install kas
```

```bash
   kas build meta-raspberrypi/kas/<machine>.yml
```

The example machine files given are raspberrypi4.yml and raspberrypi3-64.yml, and the README is explicit that machine selection is done by choosing the appropriate kas file rather than by editing a machine variable. The configuration is split into a shared base.yml and per machine files, which is the sensible way to structure it, because the common settings live in one place and the per board differences stay small. The output is the same .wic.bz2 image, and bmaptool copies it to the SD card before you boot the Raspberry Pi.

## Adjusting the build without editing the layer

The mechanism for changing the build configuration is a local_conf_header section, and the README gives a concrete example rather than an abstract description of it. You extend the configuration with a local_conf_header block keyed by a machine pattern, which is how a build setting gets scoped to Raspberry Pi machines only.

```yaml
local_conf_header:
  rpi-specific: |
    ENABLE_I2C = "1"
    RPI_EXTRA_CONFIG = "dtoverlay=disable-bt"
```

The example turns on I2C and adds a dtoverlay that disables Bluetooth, and the two setting names are worth reading closely. ENABLE_I2C is a bitbake variable, so it is a compile time decision about which kernel configuration gets baked into the image, while RPI_EXTRA_CONFIG appends lines to the Raspberry Pi firmware configuration, which is a runtime decision applied by the bootloader. That distinction is the practical lesson here, because I2C, SPI and similar peripherals are kernel side, and a dtparam or a dtoverlay change does not enable the peripheral if the kernel was not built with the right support. The second lever is layering, since additional configurations can be included by passing extra kas files after a colon, and the example enables runtime testing with testimage.

```bash
kas build meta-raspberrypi/kas/raspberrypi4.yml:meta-raspberrypi/kas/testimage.yml
```

The README points at the kas documentation for further detail on that syntax.

## A compatibility layer, not a product

The layer is officially approved as part of the Yocto Project Compatible Layers Program, with details on the Yocto Project website, and the README carries the corresponding badge. That badge is worth more than a logo. The program exists because BSP layers age badly, since a layer written against a particular kernel configuration stops building when the kernel underneath it changes, and the whole point of the compatible program is that a layer which keeps building across releases is a layer you can point new product work at. The sponsor named in the README is balena.io, which is consistent with how these layers are used, since balena builds device images for fleets of connected devices, and sponsoring a Raspberry Pi BSP layer fits that use case. The project also has a Matrix room, a mailing list on the Yocto list, a GitHub Issues tracker and hosted documentation, and a single named maintainer, Andrei Gherzan, who is also the author behind the layer. The licence is MIT with a COPYING.MIT file at the root, and there is a SECURITY.md in the repository, which is the file to read if you find a problem in the recipes.

## Where a BSP layer is the wrong tool

Three cases stand out. The first is a person who wants a working Raspberry Pi this afternoon. Building a Yocto image means installing a build host, fetching three layers, and waiting for a full build, and the result will be less polished than a distribution image with a desktop and a vendor support desk. The second is an application that must ship with a predictable base. Because the layer's dependencies are HEAD of master rather than tagged releases, a build is not reproducible out of the box, and reproducibility on a device fleet is not a nice to have, it is the difference between knowing what is on a device in the field and guessing. You can achieve it by pinning the three dependencies yourself, but then you are maintaining a fork of a moving target. The third is hardware the layer does not list. The layer is organised around machine configuration files, one per supported board, and a board without a machine file is simply not supported, which is why the kas/ directory is the thing to read before you commit to it. The layers directory of recipes also tells you what this project is not trying to be: there is no application framework here, no package feed, no release cadence for a user-facing image. It is the hardware enablement layer that goes underneath someone else's product.

## Conclusion

Adopt meta-raspberrypi if you are building a custom Linux image for a Raspberry Pi and you need a maintained BSP layer rather than a vendor image, and you have the build capacity to track three upstream layers on master. Skip it if you just need a working system, since a stock Raspberry Pi OS image will get you running faster, and skip it if your product needs a fixed, auditable base, because the layer's own dependencies are pinned to HEAD of moving branches. Before your first build, pick a machine configuration file from kas/ and set MACHINE in local.conf to a supported board, and read the local_conf_header example so you know how to add I2C or SPI without editing the layer.

## FAQ

### How do I build a Raspberry Pi image with meta-raspberrypi and kas?

Install the build tool with pip3 install kas, choose a machine configuration file from the kas/ directory such as raspberrypi4.yml, and run kas build meta-raspberrypi/kas/<machine>.yml. The resulting .wic.bz2 image is copied to the SD card with bmaptool.

### Which layers does meta-raspberrypi depend on?

Three: bitbake, openembedded-core and meta-yocto. Each is listed with branch master and revision HEAD, so the layer tracks moving upstream branches rather than fixed tags.

### How do I enable I2C or SPI in a meta-raspberrypi build?

Extend the configuration with a local_conf_header section rather than editing the layer. The README example sets ENABLE_I2C to 1 as a bitbake variable and uses RPI_EXTRA_CONFIG for a dtoverlay line, because kernel support and firmware overlays are configured separately.

### Is meta-raspberrypi part of the Yocto Project Compatible Layers program?

Yes, the README states that the layer is officially approved as part of the Yocto Project Compatible Layers Program, with details linked on the Yocto Project website. The project is maintained by Andrei Gherzan and sponsored by balena.io.

## Sources

- [agherzan/meta-raspberrypi on GitHub](https://github.com/agherzan/meta-raspberrypi)
- [Issues](https://github.com/agherzan/meta-raspberrypi/issues)
- [License: MIT](https://github.com/agherzan/meta-raspberrypi/blob/master/LICENSE)
- [Project website](https://www.yoctoproject.org/)
- [README](https://github.com/agherzan/meta-raspberrypi/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agherzan-meta-raspberrypi