Yoe Embedded Linux Distribution 🐑

Yoe is an Embedded Linux Distribution optimized for product development. It is built on Yocto and OpenEmbedded with a focus on simplicity. This distribution does not end at demo images but rather begins there.

Example 👀

The following is an example of building and installing a linux system from scratch on a Raspberry PI 3:

Install Pre-requisites 💻

Install docker on host distribution

debian-like systems - sudo apt install docker
RPM based systems - sudo dnf install docker
Archlinux based systems - sudo pacman -S docker

Add yourself to the docker group:

sudo gpasswd -a $USER docker
log out and log back in

Install nftable version of iptables on host distribution this is needed for VNC port forwarding to work on docker

Archlinux based systems - sudo pacman -S iptables-nft
On host systems with 8G RAM or less it will be necessary to ensure a swap file of 8G.

Workspace Setup 👷

git clone --recurse-submodules -j8 -b master https://github.com/YoeDistro/yoe-distro.git yoe
cd yoe
. ./envsetup.sh rpi4-64
yoe_setup
bitbake yoe-simple-image
insert SD card
lsblk (note sd card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image (Note, Etcher can also be used to write images to SD cards).
optional: configure console for serial port
sudo eject /dev/sdX
Install SD card in a Raspberry PI and enjoy your new image

Detailed documentation

Vision 🔭

There are many Embedded Linux distributions built on top of OpenEmbedded/Yocto. There is the Poky reference distribution. Most SOC and SOM vendors provide a Yocto variant that supports their products (often put together with repo). While these all provide good ways to build demo images, we feel something slightly different is needed for product development. Thus, the following goals:

simple: directory layout is logical so it is easy to find things, and tooling is as simple as possible. Emphasis is on logical organization, minimal magic, and good tooling where it makes sense. We try to minimize unneeded indirection or abstraction unless it really adds value.
modern: generate a modern Linux root filesystem using the latest technologies.
broad platform support: support a range of single board computers (SBC), system on chips (SoC), and system on modules (SOM). You should not have to use a different build system for every SBC/SOC/SOM you might choose to use in your products. Rather, one build system should easily support building images for a number of different targets in one build tree. Most companies support multiple products with SOCs from multiple vendors, thus the build system should be centered around the user’s products and software.
repeatable: easy to lock down subprojects (layers) to known versions for repeatable builds
extendable: simple to modify and add your own custom software, scripts and tooling. The focus is not on hiding or abstracting Yocto functionality, but rather provide simpler and clearer ways to use it.
maintainable: product lifecycles run for many years, so we need a solution where we can build images on a number of different hosts as time marches on. We achieve this through a simple and transparent docker wrapper that contains all the host dependencies needed. This wrapper is invisible (the file system still lives on the host), and is optional if you choose not to use it.
transparent: we try to use industry standard tools (git, bitbake, etc) where possible and not invent a lot of new tooling that needs to be learned to use the system. As an example, much of the tooling (envsetup.sh) are simple bash functions and are easy to learn from. Using Yoe will teach you about Yocto.
minimal: Embedded Linux images can quickly become bloated so we support technologies like musl libc, opkg package manager, etc. where appropriate.

Supported Machines

See the output of ./envsetup.sh for examples of projects we regularly test with.

There is also machine specific documentation available.

Additional machines can be added by including appropriate BSP layers.

Using ⚙️

envsetup.sh

This is where all the magic happens. In general, this build system must be run in a bash shell. To set up the environment, source the following file:

. ./envsetup.sh <project>

Or, you can export a PROJECT environment variable, and then source envsetup.sh.

This file will create a bunch of functions in the environment prefixed with yoe_ that can be executed. Type yoe_ to see them.

directories and key files

build: temporary directory where build actually takes place
conf: configuration files for the build
sources: various sources used for the build. The entries in this directory are git submodules. Note, by default, submodules are shallow clones. If you need the full git history of a submodule, then run git fetch --unshallow in the submodule directory.
downloads: contains files that are downloaded by various recipes during builds.
tools: utility scripts
localconfig.sh: file created by envsetup.sh that contains directory specific variables based on the build system location.
local.sh: can be used to customize MACHINE, and other variables

building for another machine

export MACHINE=[my machine]
bitbake [recipe name]

Layer management

Adding rocko branch of meta-altera layer to layer mix:

yoe_add_layer https://github.com/kraj/meta-altera rocko

Remove meta-altera:

yoe_remove_layer meta-altera

Customizing the distribution

conf/site.conf contains settings that are common for the project. The YOE_PROFILE templates make it easy to select common options.

customizing settings for your build machine

conf/local.conf contains settings that are commonly modified such as parallel build options.

starting a local feed server

Sometimes you want to install packages you build on the target system without building and re-installing the entire rootfs. This can be done using a feed server.

The advantage of a feed server versus scp’ing opkg files to the target and installing manually is that dependencies will automatically get installed. This mechanism is very useful for packages that are only needed occasionally during development (gdb, screen, strace, iperf, etc).

updating the submodules to the latest

Assuming you have a recent version of git, you can make use of the branch values specified in .gitmodules to update each submodule branch to the HEAD of the specified branch:

git submodule update --remote

Support and Contributing

Pull requests are welcome.

For support or to discuss this project, use one of the following options:

License

This build system is licensed under the MIT license which is the same license as oe-core, etc. See COPYING.MIT

Raspberry Pi

BSP Layer documentation

Yoe supports the following Raspberry Pi projects:

Project	Board	Architecture
`rpi4-32`	Raspberry Pi 4	32-bit ARM
`rpi4-64`	Raspberry Pi 4	64-bit ARM
`rpi5`	Raspberry Pi 5	64-bit ARM

Raspberry Pi 5

The Raspberry Pi 5 is the latest generation featuring a Broadcom BCM2712 SoC with quad Cortex-A76 cores at 2.4 GHz, VideoCore VII GPU, and 4 or 8 GB LPDDR4X RAM. It adds a PCIe 2.0 x1 connector (for NVMe HATs), dual 4Kp60 HDMI output, and a dedicated UART connector for the Raspberry Pi Debug Probe.

The Pi 5 requires a USB-C power supply capable of 5V/5A (25W) for full performance. A 5V/3A supply will work but may throttle under load.

Raspberry Pi 4

The Raspberry Pi 4 features a Broadcom BCM2711 SoC with quad Cortex-A72 cores at 1.8 GHz, up to 8 GB LPDDR4 RAM, dual micro-HDMI (4Kp60), Gigabit Ethernet, USB 3.0, and dual-band WiFi. Both 32-bit (rpi4-32) and 64-bit (rpi4-64) builds are supported.

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh <project> (e.g., rpi4-64, rpi5)
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image (Note, Etcher can also be used to write images to SD cards).
Optional: configure console for serial port (see below)
sudo eject /dev/sdX
Install SD card in the Raspberry Pi and enjoy your new image

Enable serial console

The serial console for the rPi3/4 can be enabled by adding ENABLE_UART = "1" to local.conf. This is currently done in local.conf, but has tradeoffs as described in the BSP layer documentation.

Connecting to the serial console

The Raspberry Pi serial console is available on the 40-pin expansion header. A USB-to-serial cable with flying leads is a convenient way to connect to this. FTDI (as well as many other companies) supply these cables. The below image shows how the FTDI cable is connected:

rPI serial console

The relevant signals are:

FTDI Black (GND) <-> rPI Pin 6 (GND)
FTDI Yellow (RXD) <- rPI Pin 8 (TXD)
FTDI Orange (TXD) -> rPI Pin 10 (RXD)

On the Raspberry Pi 5, you can also use the dedicated 3-pin UART connector with the official Raspberry Pi Debug Probe.

See the Raspberry Pi documentation for more information.

Power Supply

Some Raspberry Pi products are sensitive to power quality. It is recommended to use the official power supply for your model:

Pi 4: 5.1V/3A USB-C supply
Pi 5: 5V/5A (27W) USB-C supply for full performance

An inadequate supply may result in lockups or SD card file system corruption.

References

BeagleBone Black

BSP Layer README

BeagleBone Black system reference manual

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh beaglebone
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image (Note, Etcher can also be used to write images to SD cards).
cp deploy/beaglebone_0.0.1.upd /run/media/<SD card boot partition>/
sudo eject /dev/sdX
Connect serial console (instructions below)
Install SD card in a BeagleBone
Hold the boot switch, apply power, and the BeagleBone will boot from the SD card and install Yoe to the eMMC flash
Remove power and SD card. Yoe should now boot from eMMC.

Serial Console

The BeagleBone Black serial console is available on a 6-pin header as shown in the image below. The pinout matches a standard 3.3V FTDI 6-pin connector.

BeagleBone Serial Console

NXP i.MX 8M Mini DDR4 EVK

The i.MX 8M Mini is an applications processor from NXP featuring quad Arm Cortex-A53 cores and a Cortex-M4 core. The DDR4 EVK is NXP’s evaluation kit for this SoC using DDR4 memory.

Key Features

Quad Arm Cortex-A53 up to 1.8 GHz
Arm Cortex-M4 up to 400 MHz
2 GB DDR4 RAM
GPU (GC NanoUltra / GCNanoLite)
1080p video decode
Dual camera input (MIPI CSI-2)
MIPI DSI display interface
Gigabit Ethernet, USB 2.0, PCIe, UART, SPI, I2C

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh imx8mm-ddr4-evk
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card in the EVK and apply power

Serial Console

The debug UART is exposed via the micro-USB connector on the board. It will appear as /dev/ttyUSB0 (or similar) on a Linux host. Connect at 115200 baud, 8N1.

References

NVIDIA Jetson Orin

Yoe supports several NVIDIA Jetson Orin developer kits:

Jetson AGX Orin Developer Kit — the high-end Orin module with up to 64 GB RAM and 2048 CUDA cores
Jetson Orin Nano Developer Kit — the entry-level Orin module with up to 8 GB RAM and 1024 CUDA cores
Jetson Orin Nano Developer Kit (NVMe) — same as above, configured to boot from NVMe SSD

Key Features (Jetson AGX Orin)

Arm Cortex-A78AE CPU (up to 12 cores)
NVIDIA Ampere GPU with up to 2048 CUDA cores
Up to 64 GB LPDDR5 RAM
Up to 275 TOPS AI performance
PCIe Gen4, USB 3.2, Gigabit Ethernet, HDMI 2.1
Multiple camera inputs (MIPI CSI-2)

Key Features (Jetson Orin Nano)

Arm Cortex-A78AE CPU (up to 6 cores)
NVIDIA Ampere GPU with up to 1024 CUDA cores
Up to 8 GB LPDDR5 RAM
Up to 40 TOPS AI performance
PCIe Gen3, USB 3.2, Gigabit Ethernet, DisplayPort

Building/installing an image

Jetson AGX Orin

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh jetson-agx-orin-devkit
yoe_setup
bitbake yoe-simple-image

Jetson Orin Nano

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh jetson-orin-nano-devkit
yoe_setup
bitbake yoe-simple-image

For NVMe boot, use jetson-orin-nano-devkit-nvme instead.

Flashing

NVIDIA Jetson boards are typically flashed using the NVIDIA SDK Manager or the tegraflash tool. After building, the deploy directory will contain the necessary files. Refer to the NVIDIA Jetson documentation for detailed flashing instructions.

Serial Console

The Jetson developer kits provide a debug UART via micro-USB connector. Connect at 115200 baud, 8N1.

References

Allwinner Nezha D1

The Nezha D1 is a RISC-V single-board computer based on the Allwinner D1 SoC, featuring the XuanTie C906 64-bit RISC-V core. It is one of the first affordable RISC-V Linux SBCs.

Key Features

Allwinner D1 SoC with XuanTie C906 RISC-V core at 1 GHz
1 GB DDR3 RAM
HDMI output
Gigabit Ethernet
USB 2.0 Host and OTG
GPIO header (compatible with Raspberry Pi HATs)
MicroSD card slot
WiFi/BT module (optional)

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh nezha-d1
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card in the Nezha and apply power

Serial Console

The debug UART is available on the GPIO header. Connect a 3.3V USB-to-serial adapter:

GND to GND
TX to RX
RX to TX

Serial settings: 115200 baud, 8N1.

References

ODROID C4

The ODROID-C4 is a single-board computer from Hardkernel powered by the Amlogic S905X3 SoC. It offers a compact form factor with capable processing power at a low price point.

Key Features

Amlogic S905X3: quad Cortex-A55 at up to 1.9 GHz
Mali-G31 MP2 GPU
4 GB DDR4 RAM
eMMC module socket and MicroSD card slot
Gigabit Ethernet
4x USB 3.0, 1x USB 2.0 OTG
HDMI 2.0 (up to 4K@60)
40-pin GPIO header
IR receiver

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh odroid-c4
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card in the ODROID-C4 and apply power

Serial Console

The debug UART is available on the 40-pin GPIO header. Connect a 3.3V USB-to-serial adapter:

Pin 6 (GND) to GND
Pin 8 (TX) to RX
Pin 10 (RX) to TX

Serial settings: 115200 baud, 8N1.

Although ODROID provides a serial console adapter, many of us have rPi-style flying-lead cables on hand. These can be attached directly to the connector on the ODROID. If you have a HAT on the board, then an option is to solder a small header on the bottom as shown below.

odroid serial console top

odroid serial console bottom

References

Radxa ROCK Pi 4B

The ROCK Pi 4B is a single-board computer from Radxa powered by the Rockchip RK3399 SoC. It offers a Raspberry Pi-like form factor with significantly more processing power.

Key Features

Rockchip RK3399: dual Cortex-A72 at 1.8 GHz + quad Cortex-A53 at 1.4 GHz
Mali-T860MP4 GPU
1/2/4 GB LPDDR4 RAM
eMMC socket and MicroSD card slot
M.2 connector for NVMe SSD
Gigabit Ethernet
802.11ac WiFi and Bluetooth 5.0
USB 3.0, USB 2.0, USB-C (with DisplayPort alt-mode)
HDMI 2.0 (up to 4K@60)
MIPI DSI and CSI interfaces
40-pin GPIO header (Raspberry Pi compatible)

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh rockpi-4b
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card in the ROCK Pi 4B and apply power

Serial Console

The debug UART is available on the 40-pin GPIO header (pins 6/8/10). Connect a 3.3V USB-to-serial adapter:

Pin 6 (GND) to GND
Pin 8 (TX) to RX
Pin 10 (RX) to TX

Serial settings: 1500000 baud, 8N1. Note the high baud rate — make sure your serial adapter supports it.

References

SiFive RISC-V Boards

Yoe supports two SiFive RISC-V development boards:

Project	Board	SoC	Cores
`unleashed`	HiFive Unleashed	FU540-C000	4x U54 + 1x E51
`unmatched`	HiFive Unmatched	FU740-C000	4x U74 + 1x S7

HiFive Unleashed

The HiFive Unleashed was the first RISC-V board capable of running Linux. It features the SiFive Freedom U540 SoC with four U54 application cores (RV64GC) at 1.5 GHz and one E51 monitor core, 8 GB DDR4 RAM, Gigabit Ethernet, and a MicroSD card slot.

HiFive Unmatched

The HiFive Unmatched is a mini-ITX form factor RISC-V development board. It features the SiFive Freedom U740 SoC with four U74 application cores (RV64GC) at 1.2 GHz and one S7 monitor core, 16 GB DDR4 RAM, PCIe x16 slot (x8 electrically), M.2 for NVMe and WiFi, Gigabit Ethernet, and four USB 3.2 Gen 1 ports.

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh <project> (e.g., unmatched)
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card and apply power

Serial Console

Both boards expose a debug UART via micro-USB connector. Connect at 115200 baud, 8N1.

References

StarFive VisionFive

Yoe supports two generations of the StarFive VisionFive RISC-V single-board computer:

Project	Board	SoC	Cores
`visionfive`	VisionFive	JH7100	2x U74 (RV64GC) @ 1 GHz
`visionfive2`	VisionFive 2	JH7110	4x U74 (RV64GC) @ 1.5 GHz

VisionFive (V1)

The StarFive VisionFive is an affordable RISC-V SBC based on the JH7100 SoC with dual SiFive U74 cores at 1 GHz, 8 GB LPDDR4 RAM, Gigabit Ethernet, USB 3.0, HDMI, and a 40-pin GPIO header.

VisionFive 2

The StarFive VisionFive 2 is the successor featuring the JH7110 SoC with quad SiFive U74 cores at 1.5 GHz, a GPU (IMG BXE-4-32), 2/4/8 GB LPDDR4X RAM, dual Gigabit Ethernet, USB 3.0, HDMI 1.4, MIPI DSI/CSI, M.2 for WiFi/BT, and a 40-pin GPIO header.

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh <project> (e.g., visionfive2)
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card and apply power

Serial Console

Both boards expose a debug UART on the 40-pin GPIO header. Connect a 3.3V USB-to-serial adapter:

Pin 6 (GND) to GND
Pin 8 (TX) to RX
Pin 10 (RX) to TX

Serial settings: 115200 baud, 8N1.

References

Variscite System on Modules

Yoe supports several Variscite System on Module (SOM) products based on NXP i.MX processors. These SOMs are designed for industrial and embedded applications and are typically mounted on carrier boards.

Project	SOM	SoC	Architecture
`var-dart-imx6ul`	DART-6UL	i.MX 6UL	Cortex-A7
`var-som-mx8`	VAR-SOM-MX8	i.MX 8QuadMax	Cortex-A72/A53
`var-som-mx8m-nano`	VAR-SOM-MX8M-NANO	i.MX 8M Nano	Cortex-A53
`var-som-mx8x`	VAR-SOM-MX8X	i.MX 8QuadXPlus	Cortex-A35

DART-6UL

The DART-6UL is a compact SOM based on the NXP i.MX 6UltraLite featuring a single Cortex-A7 core at up to 696 MHz. It targets cost-sensitive, low-power applications with Ethernet, USB, CAN, UART, SPI, and I2C interfaces.

VAR-SOM-MX8

The VAR-SOM-MX8 is a high-performance SOM based on the NXP i.MX 8QuadMax with dual Cortex-A72 and quad Cortex-A53 cores, dual GPUs, 4K video encode/decode, and up to 4 GB LPDDR4 RAM. Suitable for multimedia, HMI, and edge computing applications.

VAR-SOM-MX8M-NANO

The VAR-SOM-MX8M-NANO is based on the NXP i.MX 8M Nano with quad Cortex-A53 cores and a Cortex-M7 real-time core. It offers a balance of performance and power efficiency with 1080p video, 3D GPU, and machine learning acceleration via the NPU.

VAR-SOM-MX8X

The VAR-SOM-MX8X is based on the NXP i.MX 8QuadXPlus with quad Cortex-A35 cores. It is optimized for low-power applications with 4K video output, dual-camera input, and industrial temperature support.

Building/installing an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh <project> (e.g., var-som-mx8m-nano)
yoe_setup
bitbake yoe-simple-image
Insert SD card
lsblk (note SD card device, and substitute for /dev/sdX below)
yoe_install_image /dev/sdX yoe-simple-image
sudo eject /dev/sdX
Install SD card in the evaluation kit and apply power

Serial Console

Variscite evaluation kits typically provide a debug UART via micro-USB connector on the carrier board. Connect at 115200 baud, 8N1.

References

QEMU Virtual Machines

Yoe supports a variety of QEMU targets for testing and development without physical hardware. These are useful for build testing, application development, and CI pipelines.

Project	Architecture	Description
`qemuarm`	ARM 32-bit	Versatile Express Cortex-A15
`qemuarm64`	ARM 64-bit	Generic ARM64 (Cortex-A57)
`qemux86`	x86 32-bit	Generic PC (i586)
`qemux86-64`	x86 64-bit	Generic PC (x86-64)
`qemumips`	MIPS 32-bit	Malta board
`qemuppc`	PowerPC 32-bit	Mac99 machine
`qemuppc64`	PowerPC 64-bit	pseries machine
`qemuriscv32`	RISC-V 32-bit	Generic RISC-V (virt)
`qemuriscv64`	RISC-V 64-bit	Generic RISC-V (virt)

Building an image

git clone https://github.com/YoeDistro/yoe-distro.git
cd yoe-distro
. ./envsetup.sh <project> (e.g., qemuarm64)
yoe_setup
bitbake yoe-simple-image

Running the image

After building, launch the image in QEMU with:

runqemu yoe-simple-image

Common options:

runqemu yoe-simple-image nographic — serial console only, no GUI window
runqemu yoe-simple-image kvm — use KVM acceleration (x86 host only, for qemux86/qemux86-64)
runqemu yoe-simple-image slirp — user-mode networking (no root required)

Notes

The qemucommon project contains shared configuration used by other QEMU projects. It is not intended to be built directly.
KVM acceleration is available on x86 hosts for qemux86 and qemux86-64, providing near-native performance.
For ARM and RISC-V targets, QEMU uses full system emulation which is slower but functional.

References

Yoe Docker Integration

The Yoe project provides a docker container that has all the dependencies needed to build Yoe. This container is mostly transparent as it simply wraps the bitbake command. Every time you run bitbake, the container is started and all bitbake operations happen in the container. The build files still exist in the host file system so they can be accessed using any of your host tools.

Using this container has the following benefits:

you don’t have to worry about installing host dependencies
you can build on any Linux host distro, even those that are not compatible with Yoe
as host distributions are updated, then eventually become incompatible with older versions of OpenEmbedded. Using a container allows you to build old version of Yoe over long product life cycles.

Yoe uses docker by default, but this can be disabled by setting DOCKER_REPO=none in your local.sh file. You can also set DOCKER_REPO to a custom container if you need something different.

Any tool (such as devtool) that uses bitbake must also be run in the container. As these tools are not yet wrapped, you must enter the docker container first, and then run the tool. This can be done by running dkr first, which drops you into a container shell.

Packages

During an image build, OpenEmbedded builds all software into packages, which are then combined into a rootfs. One benefit of this is you can install packages later into a running system, much like you would a desktop distribution like Debian, Ubuntu, Arch, etc. OE supports the RPM, DEB, and IPK package formats, and the format can be set using the PACKAGE_CLASSES variable.

Installing packages from a local build

You can install packages directly from your local OE build onto a target system with the following procedure:

packaging information must be included in the target image:
- IMAGE_FEATURES += "packages-management"
a ssh server must be enabled in the target image:
- IMAGE_FEATURES += "ssh-server-dropbear"
see yoe-simple-image for an example.
target system must be on the same network as your build computer.
run yoe_setup_feed_server <target ip address>. This configures the target to fetch packages from your build computer. Alternatively you can set the MACHINE_IP environment variable.
run yoe_feed_server. This starts a web server that serves packages.
on target system, run:
- opkg update
- opkg list (list packages available)
- opkg install python3 (install python3)

If the package is not built yet, simply:

bitbake <recipe for package to install>
bitbake package-index (required to rebuild the package index)
on target:
- opkg update
- opkg install <package>

This technique is very useful for testing new packages, or for installing packages that are only needed for development that you don’t want to include in production images (strace, gdb, testing tools, etc). Dependencies are automatically handled by the package manager.

For larger development teams or field deployments, you might want to set up a feed server to serve packages to any connected device.

Working with Git Submodules

Git submodules are used in this project to manage the various OE layers for reasons described in this document. See this article for an introduction to Git submodules.

There are a few commonly encountered issues described below.

Modifying Submodules

Git submodules are not checked out on a branch, but at a specific git commit. The first thing you should do when working on a submodule is check out the appropriate branch, documented in the .gitmodules file. If you forget to do this, you may get an error when pushing. If you run git branch, you’ll discover you are on the (no branch) branch. To recover from this situation, check out the branch you want to work on and then run git reflog. This command will list recent commits which you can then cherry-pick to your working branch. See this article for more information.

Submodule merge conflicts

If you get a submodule merge conflict, run git reset \<sources/submodule\>

Submodule remote changes

If the remote repository for a submodule changes, run git submodule sync to synchronize the new remote information into your working directory. This problem is most often noticed when the git submodule update command cannot find a version.

KAS

KAS is a tool for managing layer repositories, configuration, and build environments for Yocto/OE builds. It is the recommended approach for new Yoe projects (see Superproject Management for background).

Getting Started

KAS configurations live in the kas/ directory. Each YAML file defines a complete build for a target machine, including layer repositories, local.conf settings, and bblayers.conf entries.

Available configurations:

jetson-agx-orin-devkit.yml
jetson-orin-nano-devkit-nvme.yml
rpi4-64.yml
visionfive.yml
visionfive2.yml

Running a Build

To set up a container and drop into a shell ready for bitbake:

cd kas/
./kas-container \
    --runtime-args "--volume ./../sources/meta-yoe:/work/layers/meta-yoe" \
    --ssh-dir ~/.ssh \
    shell jetson-agx-orin-devkit.yml

The --volume flag mounts the local meta-yoe layer into the container so that local changes are available in the build.

Once inside the container shell, run bitbake as usual:

bitbake yoe-simple-image

Local Configuration

To add machine-specific or user-specific settings without modifying the checked-in YAML files, create kas/local.yml (git-ignored) and append it when invoking KAS:

./kas-container <...> <target>.yml:local.yml

References

Yoe Init/Updater 🚀

Requirements

There are two functions of the Init/Updater system:

verify the system is initialized such that it can run (disk partitions, etc)
update the system with new software

Both of these functions are critical for a reliable system. Having an initialization system also greatly simplifies production deployment as the system can completely initialize itself as long as a kernel can boot.

single partition update
update u-boot, kernel, dtb, etc.
init/updater located in kernel initramfs
most systems will have 3 partitions
- boot: contains bootloaders, kernel+initramfs+init/updater
- rootfs: root file system that is re-written during update
- data: data that is preserved between updates
Initializes disk partitions
- if disk is not partitioned correctly (# partitions), re-partition disk
- optionally re-partition disk if sizes are not correct (example rootfs is too small)
  - try to preserve data if possible
Mounts all partitions
- mount rootfs
- optionally mount boot into rootfs mount
- mount data into rootfs mount
- re-format data if it cannot be mounted
Update
- check for update file on USB disk and data partition
- if found, select latest version
- verify checksums for all files
- compare contents of boot and kernel images and only update them if they have changed. This is very important to minimize flash wear in boot partition, and minimize windows where unit may be bricked.
- unconditionally write rootfs
- optionally ask user to remove USB disk (if updating from USB)
Platform-specific hooks
- any platform-specific setup that needs to be done
Switch root from initramfs to main rootfs

Adding updater support for a new machine

You generally need to do two things to add updater support for your machine:

modify the image recipes to generate update files, initramfs, etc. See examples in sources/meta-yoe/recipes-core/images/machines/
configure the updater for your machine. See examples in sources/meta-yoe/recipes-support/updater/files/

Rationale for single image system

Most update systems focus on an A/B update system where you ping/pong between two sets of images on the disk. The thought is that if the system does not boot or has other problems, you can roll back to the other set of images. This is a nice feature, but has the following complexities:

maintaining two boot paths requires you to touch bootloader, kernel, and possibly rootfs code to process an update.
there has to be some state that determines current boot path (typically a u-boot variable)
typically update is handled in the main rootfs context, so pretty much the entire system needs to be running.
more disk space is required
you have to have some policy or mechanism for switching to the other set of images if there is a failure. This is not trivial.

For remote or ultra-critical systems, this type of A/B setup may make sense. However it is critical to understand that this system is only as reliable as weakest link in the boot/update process. Any bug, no matter how small, can render the system useless. Because so many pieces of the boot process are modified in the A/B system, it is critical that you budget enough time to thoroughly test the process and all edge conditions.

An alternative implementation (described above in the above Requirements section) is much simpler because the complete update process lives in an initramfs bundled with the kernel. As long as the kernel boots, you can easily recover the system from a USB disk, or perhaps a recovery update image stored in the data partition. Because the bootloader and kernel are stored in a boot partition that is rarely written to (only on updates), this data is fairly reliable. Network updates can be managed from an application running in the main rootfs that fetches an update, stores it in the data partition and then reboots. Overall, this system has worked extremely well on 10,000+ deployed systems and is adequate for many embedded Linux systems. The simplicity also allows it to be deployed quickly on new systems with very low risk.

Configuration Files

OpenEmbedded is configured through “conf” files. These exist at various places in the sources. At the top level of the project are several files that contain high level, or build specific configuration options. For the Yoe project, these files include:

conf/auto.conf: This file is automatically generated by the build system and should not be modified.
conf/site.conf: This file includes Yoe defaults and project specific changes that you want to store in git. This file includes samples of things you might want to add.
conf/local.conf: This file includes changes that are specific to a user or build machine, and are not checked into git. This file includes samples of things you might want to add.

The above configuration files are included into the build by the bitbake.conf file in the OE Core layer.

For a full list of variables available in the OpenEmbedded build system, see the Variables Glossary.

Yoe Profile

The Yoe Distribution makes it easy to select the libc, init, and graphics subsystem for your project. To select a profile, set YOE_PROFILE in conf/site.conf equal to one of the following:

yoe-glibc-busyboxinit-eglfs
yoe-glibc-busyboxinit-wayland
yoe-glibc-busyboxinit-x11
yoe-glibc-systemd-eglfs
yoe-glibc-systemd-wayland
yoe-glibc-systemd-x11
yoe-glibc-sysvinit-eglfs
yoe-glibc-sysvinit-wayland
yoe-glibc-sysvinit-x11
yoe-musl-busyboxinit-eglfs
yoe-musl-busyboxinit-wayland
yoe-musl-busyboxinit-x11
yoe-musl-systemd-eglfs
yoe-musl-systemd-wayland
yoe-musl-systemd-x11
yoe-musl-sysvinit-eglfs
yoe-musl-sysvinit-wayland
yoe-musl-sysvinit-x11

These profiles are provided for convenience. You can manually configure these options as well – use the files in the yoe conf directory for reference.

libc and init system selection

Selection

Selection of the libc and init system can be done by selecting a Yoe Profile.

Comparison of disk space used

Musl + Busybox init/dev/login
- space used in ext4 filesystem on running system using df: 1.9MB
- adding sizes of files in image from buildhistory: 1.5MB
- number of files in image: 595
Busybox init/dev/login
- space used in ext4 filesystem on running system using df: 3.5MB
- adding sizes of files in image from buildhistory: 3.1MB
- number of files in image: 621
SysVinit
- space used in ext4 filesystem on running system using df: 4.7MB
- adding sizes of files in image from buildhistory: 4.3MB
- number of files in image: 696
Systemd
- space used in ext4 filesystem on running system using df: 33.2MB
- adding sizes of files in image from buildhistory: 22MB
- number of files in image: 1,806

The space on disk used by a systemd image is much larger than adding the size of the files in the image. We’re not sure why this is – perhaps there is filesystem overhead for small files.

GCC

The primary use for OE is to cross-compile software on a fast workstation, but there are times during development or evaluating technology where it may be useful to compile software on the target device. There is also some software that is simply too nasty for most of us to figure out how to cross-compile so one workaround is to build a binary on the target system, and then package that binary in subsequent image builds. This hack should only be used as a last resort in production builds.

The following packages can be added to the image, or installed at runtime using a package manager such as opkg.

packagegroup-core-buildessential - this is most often what you need and is very similar to the build-essential package on Debian/Ubuntu. recipe
packagegroup-self-hosted - a much more extensive list of packages that includes what is in buildessential, plus a lot more. recipe

Git Superproject Management

One controversial choice in Yoe is the use of Git Submodules vs Repo. Because we need to manage multiple Git repositories, something is needed. There are a number of solutions including:

Git submodules (legacy, still supported)
KAS (recommended for new projects)
Google repo
Git subtree
custom scripts
Poky style combo repo

In this document, we will use the OE term “layers” to refer to git subrepositories (submodules). Superproject is the term that describes the project that manages all the subprojects (layers).

Requirements

Yoe is designed foremost for product development, or using Yocto/OE to build software that will be deployed in real products (vs a technology demo build). It is also designed to be used by people who may not be embedded Linux/Git experts, but yet want to create builds and make incremental improvements over long product lifecycles (can be 5 years or more). From this, we derive Yoe’s requirements (somewhat ordered by priority).

know exactly what version of all software (layers) were used in a particular build, and be able to rebuild any version on any machine.
all build and configuration files (local.conf, etc) must be stored in git.
project structure is obvious and easy to understand. Obscure steps such as copying or soft-linking setup scripts that may be modified is minimized.
hard to make mistakes such as changing a layer version or config file, and then forgetting to record this change.
easy to add/remove layers to the build.
easy to make changes to layers and submit changes back upstream.
easy to fork layers if tweaks need to be made that are not available upstream.

Every solution has tradeoffs. To accomplish one goal, you often have to accept compromises on another goal, so it is likely no one tool is best to accomplish all of these goals.

Git Submodules

pros
- super/sub project organization is obvious – top level git repo is the superproject, and subprojects live under it in the directory tree
- git status gives you status of submodules and files in one command
- easy to store layer versions and conf file changes in the superproject
- difficult to forget to record layer versions (git status shows you)
- well documented in git documentation
- .gitmodules file is simple and easy to read
- easy to track development of layers by specifying branch in .gitmodules, and updating to latest on branch with “git submodule update –remote”
- a number of application developers are already using git submodules in various projects, where repo is less common except in large build systems (like Android)
- easy to do recursive changelogs into submodules (again, useful for production)
- optimized for development when subprojects are not changing a lot
cons
- no-branch issue when making changes to a submodule: http://bec-systems.com/site/696/git-submodules-what-to-do-when-you-commit-to-no-branch
- removing submodules can be a little confusing
- updating a submodule URL requires a “sync” to propagate changes to working submodule.

Google Repo

pros
- repo manifest is flexible/powerful
- repo manifest can include other manifests
- easy to switch/sync git urls
- a lot of users due to use in Android build system
- good at managing large numbers of subprojects where you own all the subprojects (example, repo can apply a tag to all the subprojects). However, with Yocto, you are typically using 3rd party layers where you don’t own the repository and can’t push tags to these repositories.
- optimized for development when subprojects are changing a lot
cons
- To lock down layers, you have to specify the git hash in the manifest: https://github.com/Angstrom-distribution/angstrom-manifest/blob/angstrom-v2018.06-sumo/default.xml#L22. This requires additional tooling to be practical for product development.
- Repo is a separate tool from git that needs to be installed and learned
- official documentation is sparse
- manifest file is more complex and harder to read at a glance than .gitmodules
- location of manifest file is somewhat hidden and less obvious how to manage
- difficult to store both subproject info and other files in the superproject.

KAS

KAS is a build tool for Yocto/OE that manages layer repositories, configuration, and build environments from a single YAML file. Yoe is moving toward KAS as the recommended approach for managing builds.

pros
- single YAML file defines layers, repos, and configuration — easy to read and maintain
- built-in container support for reproducible build environments
- layer repository URLs, branches, and revisions are declared in one place
- no separate tooling needed to lock down layer versions — commit hashes go directly in the YAML
- supports configuration includes for sharing common settings across projects
- actively maintained with good documentation
- growing adoption in the Yocto community
cons
- separate tool that needs to be installed (though container mode reduces this)
- less familiar to developers who already know git submodules

KAS addresses many of the same goals as git submodules — reproducible builds, version locking, and configuration management — while providing a more integrated and streamlined workflow. See the KAS documentation for details on using KAS with Yoe.

Git Subtree

At this point git subtree is not actively being considered as it mixes all the subprojects into one repo, and likely not optimal for managing layers, most of which will rarely change during a product lifecycle. It seems to be a tool for more advanced users.

Poky style combo repo

One popular trend these days are monorepos which are popular in various large companies (like Google and Facebook). Poky is somewhat of a monorepo in that it contains bitbake, oe-core, and some other things in one git repo. This makes it easy to checkout one repository and build a demo image if you want to test Yocto. However, once you want to add other layers, you still have to deal with multiple repositories or figure out the combo-layer tool. Additionally, if you make changes to one of the pieces of Poky, extracting these changes to submit back upstream is not as easy as if the repositories were simply split out in their original form. Also, it is less obvious that you might update just one part of the combo repo, but not others.

It seems monorepos are best for projects where a company owns everything in the repo. With a Yocto build, most of the layers come from third parties. In this scenario, it seems a superproject type setup is a better fit. We favor the transparency of showing clearly where each layer came from so it is obvious where to go for support, etc.

Summary

As mentioned before, each solution has trade-offs. Superproject management is messy at best, because there are conflicting goals. Changing layer urls and tracking floating layers is easier in Repo, but locking down layer versions is easier in git submodules. With any solution, some amount of tooling will likely be required to smooth out, or at least document, the pain points.

For the typical Yoe user who is building a product, by far the most common use of Yoe is simply building iterative releases for a product where very little changes from release to release except application code. These product cycles can be 5 years or more with 100’s of releases. During this time, the layers may change from time to time to add new packages, tweak the system files, or update to a new version of Yocto, but these layer changes are relatively few compared to the application changes. We want to optimize the experience for this use case where a developer using Yoe is not a Yocto expert, but knows enough to tweak recipes, run builds, etc.

The ability to manage both configuration files, documentation, scripts/tools, and subprojects in a single superproject with git submodules seems like a much simpler model than repo, where the only thing you can really manage in a repo manifest is the subproject. This is a simpler setup because everything the user typically needs to interact with is near the top of the directory tree and easy to find. Things that change from one iterative build to the next are located in the top level superproject, so all you need to tag a build is a simple git add/tag/commit/push of the superproject. Convenience tooling and conf file changes can easily be made, and it is obvious where they are stored. With repo, this is often a layer of indirection where local.conf and other files are copied (or generated) to a temporary build directory and it is not obvious how this happens, or how to capture changes in git. Additionally, if you want to lock down layers to a git version, typically tooling is written to add these git hashes to the manifest file for a release build, and then revert this back to floating branches for development. This tooling is unnecessary with git submodules.

There is a cost to complexity. We may be tempted to reach for the most powerful tool at our disposal, but there is a cost if a simpler tool would work. With tooling, there is no one-size-fits all. We don’t pick up a sledge hammer to drive a tack, nor do we use a tack hammer to bust up concrete, nor do we buy a robot if we only need to drive a few nails. The best solution is the simplest one that does the job well. “Clear” and “obvious” are the best solutions in a build system. “Neat” and “clever” usually are not.

(Note, I don’t claim Yoe meets this lofty goal, but this is the vision.)

Yoe is moving toward KAS as the recommended way to manage builds. KAS combines layer management and build configuration into a single YAML file, eliminating much of the complexity discussed above. Git submodules remain supported for existing projects, but new projects are encouraged to use KAS.

That said, the beauty of OE layers is that you can put them together using whatever tools work best for you. Yoe is just an attempt at keeping things as simple as possible for product developers.

Yoe Layer Management

All OE layers that are being used in Yoe project are mirrored in the YoeDistro space on github. These layers are synced every two hours with upstream since the global namespace is kept intact, there are no conflicts. We reserve namespaces for local branches

yoe/<topic> - Distro Specific branch, created for yoe release we support this has specific fixes which are not
- upstreamable, this is rare situation
- Required for yoe and are in flight for upstream inclusion - Submissions from yoe community
we also create additional integration branches e.g. yoe/<branch>-next which are used for regular CI builds.
<user>/<topic> - This namespace is reserved for developers, these are also short lived branches primarily used for development which are deleted after pull request is accepted in a public branch

Why do we mirror the layers ?

This provides needed redundancy and development space for Yoe Distro developers. Since we create pure mirrors for public branches and offer namespaces for development, this makes it a good combination for hosting changes when they are in flight. It also provides a mechanism for running a CI loop on the changes to be submitted upstream for specific layers.
If a product is to be released one can easily mirror the yoe mirrors internally and keep a local copy, or one can use same mirroring policy and local branching policy to create internal branches. Just keep / namespace safe.
For some reason if upstream layers disappear and we still need to maintain the layers, which can happen over a long life of products, then we offer a redundancy

OE/Yocto Feedback

It is no secret that OpenEmbedded/Yocto has a steep learning curve. Many people who try to use it get discouraged and write it off as poorly done and impossible to understand. This is one of the problems that motivated us to create Yoe.

Below is some of the feedback we’ve collected and links to various discussions.

If a build breaks, it is not always obvious what went wrong. If there weren’t Google, I’d be dead in the water!
If I modify some code in a package, how do I know that a bitbake will properly pull in my changes and rebuild what I want it to? I’d expect that a simple bitbake would do what I’d think it should do, but in some cases, it does not.
https://news.ycombinator.com/item?id=21677639

Yoe Projects

Idea

The Yoe Distribution makes it easy to switch between projects. Before you had to switch between local.conf and bblayers.conf a lot. With the introduction of the conf/projects this got a lot easier. You can switch between a lot of pre made projects. A project consists of a config.conf and a layers.conf file. The layers.conf file is the bblayers.conf for that specific project. And the config.conf is everything you would normally put into your local.conf file. To choose between configurations, simply do the following

. ./envsetup.sh beaglebone
yoe_setup

After this point you are able to bitbake e.g. yoe-simple-image for that project/platform.

Supported projects

Currently these projects are supported.

beaglebone
imx8mm-ddr4-evk
jetson-agx-orin-devkit
jetson-orin-nano-devkit
jetson-orin-nano-devkit-nvme
nezha-d1
odroid-c4
qemuarm
qemuarm64
qemumips
qemuppc
qemuppc64
qemuriscv32
qemuriscv64
qemux86
qemux86-64
rockpi-4b
rpi4-32
rpi4-64
rpi5
unleashed
unmatched
var-dart-imx6ul
var-som-mx8
var-som-mx8m-nano
var-som-mx8x
visionfive
visionfive2

Converting a project

If you used Yoe before, you might want to convert a project to the new config. In the simplest case you just need to create a new directory at conf/project/your_project_name and copy over your local.conf to config.conf and bblayers.conf to layers.conf.

Creating a new project

Choose the project that most closely resembles your needs, copy it to conf/project/your_project_name and change it to your needs.

Supporting a custom SOM baseboard

A very common scenario is that you might want to create a custom baseboard for a SOM (system on module). The starting point is the SOM vendor’s reference baseboard, but we need to customize the build to account for the differences between the reference and custom baseboards. In this case it is very useful to have a separate PROJECT and MACHINE so that you can build images for the reference board and your custom board in one build system. This allows you to easily compare the systems to debug problems. Steps to do this include:

machine conf sources/meta-<your custom layer>/conf/machine/mymachine.conf. This typically requires the original baseboard machine conf file.
- add: MACHINEOVERRIDES =. "<ref machine name>:"
- specify custom machine DTB: KERNEL_DEVICETREE = "freescale/mymachine.dtb"
- optionally specify custom uboot DTB: UBOOT_DTB_NAME = "imx8qm-var-som-m80.dtb"
- specify kernel/uboot default providers (FIXME, is this required?)
kernel bbappend
- adds your custom mymachine.dts
- patch kernel to build mymachine.dtb
- optionally create a custom kernel config or add config fragments to customize the kernel config
- this should probably be put in a dynamic layer if the kernel recipe is found in a meta-<...> layer.
updater config sources/meta-yoe/recipes-support/update/files/<mymachine>/
- generally, copying the reference design updater and changing a few variables in the platform file is enough.
image update task
- copy reference machine inc file to: sources/meta-yoe/recipes-core/images/machines/<mymachine>.inc.
custom Yoe project
- copy the reference design Yoe project to conf/projects/<myproject>
- the config.conf should reference your custom MACHINE

Contribute

If you feel like your project config fits the yoe-distribution well feel free to start a pull request.

Build Machine Requirements

Build machine requirements vary depending on what you are building. You may get by with 8GB of RAM for simple images, but building anything with Chromium in it will likely require 64GB of RAM. We recommend at least 16GB and preferably 32 or 64GB.

Yocto aggressively parallelizes the build, so it will max out your CPUs. Generally, you need to have 2GB of RAM for each virtual core. To determine the number of cores, run cat /proc/cpuinfo and locate the siblings field. For x86 CPUs, this is typically twice the number of CPU cores due to hyperthreading.

processor       : 0
vendor_id       : AuthenticAMD
cpu family      : 23
model           : 113
model name      : AMD Ryzen 9 3900X 12-Core Processor
stepping        : 0
microcode       : 0x8701021
cpu MHz         : 2200.000
cache size      : 512 KB
physical id     : 0
siblings        : 24
core id         : 0
cpu cores       : 12

For the above 12-core machine, we have 24 virtual cores, so need ~48GB of RAM.

If you are running out of memory during builds, you can add the following to local.conf:

PARALLEL_MAKE = "-j 11"
BB_NUMBER_THREADS = "11"
XZ_THREADS = "8"
# Max 10% of memory to be used during parallel xz
XZ_MEMLIMIT = "10%"

A single build can take 50GB of disk space or more. SSD drives speed up builds quite a bit over rotating disks.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2026.02] - 2026-02-28

Changed

Add CVE_PRODUCT product name entries in several recipes
Upgrade PHP to 8.5.3
Upgrade rpidistro ffmpeg to 7.1.13
Switch kerel for K1 SOCs to linux-mainline-k1 6.19
Update L4T from R36.4.4 to R36.5.0
Update affected recipes to build with Jetpack R36.5.0
Add recipe for linux-yocto 6.12 in tegra layer
Upgrade coreutils to 9.10
Upgrade go compiler to 1.26.0
Disable TLS 1.0/1.1 by default in OpenSSL
Upgrade mesa to 26.0.0
Update linux-yocto/6.18 to v6.18.8

Keyboard shortcuts

Yoe Embedded Linux Distribution