Introduction to meta-orchestraos

This repository provides the OrchestraOS Yocto distribution layer (meta-orchestraos), related meta-orchestraos-* layers, and the KAS manifests used to build OrchestraOS images.

Scope

meta-orchestraos contains:

  • Distribution configuration (conf/distro/*.conf and conf/distro/include/*.inc)

  • Image recipes (recipes-core/images/*) defining what goes into OrchestraOS images

  • Policy and integration recipes (systemd, udev, partition mounting, NetworkManager, Docker, SSH, default user, etc.)

  • Dynamic layer bbappends to apply BSP or feature-specific tweaks without forking upstream layers

  • KAS manifests (ci/orcos/*.yml) and reusable fragments (ci/fragments/*.yml) defining the machine, distribution, image, and layer revisions used for a build. These build definitions are part of the release.

To check the currently supported Yocto release, see LAYERSERIES_COMPAT_cthingsco-orchestraos in conf/layer.conf.

Layer responsibilities

The documentation in this chapter focuses on the OrchestraOS-owned layers:

meta-orchestraos

Main distribution layer. It defines distros, image recipes, common package policy, the default LVM-based storage layout, initramfs integration, systemd units, udev rules, NetworkManager integration, SSH configuration, and the default user setup.

meta-orchestraos-bsp

Hardware enablement layer for supported CTHINGS.CO gateways. It provides machine configurations such as eigm, eigmdin, eigma, and eigxs, plus board-specific kernel, bootloader, firmware, OP-TEE, ATF, and signing integration. It also supplies U-Boot and UEFI configurations for the upstream qemuarm64 machine.

meta-orchestraos-misc

Shared helper layer for extra distro configuration and WIC partition templates used by the reference image layouts.

meta-orchestraos-rauc

RAUC update integration layer. It defines RAUC image and bundle behavior, slot metadata, U-Boot and EFI boot selection, bootloader update handling, first-boot slot population, and hawkBit updater integration.

meta-orchestraos-crypt

Optional extended-security layer. It integrates hardware-backed key protection and encrypted storage with the base partitioning and initramfs flow. See Extended Security for the capability overview and this layer’s README.md for its build and configuration instructions.

meta-orchestraos-nitrokey-nethsm

Optional integration with Nitrokey NetHSM for hardware-backed signing of boot artifacts and RAUC bundles. See NetHSM Signing for the capability overview and the layer’s README.md for setup and key selection.

meta-orchestraos-ml

Optional machine-learning integration for supported i.MX8M Plus targets, including the NXP inference stack and runtime compatibility adjustments. See Machine Learning and the layer’s README.md.

These optional extensions are available under separate commercial licenses. Contact sales@cthings.co for access and licensing information.

Key concepts

Distribution (DISTRO)

Controls global policies and feature sets. This repository defines distros such as:

  • orcos-cmdline

  • orcos-fb

  • orcos-xwayland

Machine (MACHINE)

Target hardware platform, such as eigm, eigmdin, eigma, or eigxs. Virtual configurations reuse MACHINE = "qemuarm64" and add a BSP include selecting U-Boot or UEFI.

Features (DISTRO_FEATURES)

Used to enable or disable optional subsystems such as:

  • system updates: rauc

  • security: tpm2

Images

OrchestraOS images are defined in recipes-core/images and include minimal and full cmdline variants.

Image And Distro Variants

The distro selects the global feature set, while the image recipe selects the installed package set and generated artifacts.

Distro variants

DISTRO

Purpose

Main feature policy

orcos-cmdline

Headless command-line systems.

Removes graphical stacks and disables the framebuffer console.

orcos-fb

Framebuffer-oriented systems.

Enables directfb and removes conflicting OpenGL, X11, and Wayland features.

orcos-xwayland

Graphical systems using Wayland/XWayland.

Enables x11, wayland, and pam; selects Plymouth as the splash provider.
Image variants

Image

Purpose

Notes

orchestraos-image-minimal

Base OrchestraOS image.

Includes the common runtime set, read-only rootfs policy, OpenSSH, NetworkManager, Docker, TPM2 packages, Fluent Bit, Telegraf, and LVM tooling.

orchestraos-image-full-cmdline-sshkey

Command-line image for key-based SSH access.

Extends the minimal image with OrchestraOS SSH key configuration.

orchestraos-image-full-cmdline-sshpass

Command-line image for password-based SSH access.

Uses the default user/password policy instead of the SSH key package.

orchestraos-image-weston

Wayland GUI image.

Extends the minimal image with Weston, XWayland, GPU/display packages, splash support, and hardware codecs.

orchestraos-image-initramfs

Initramfs paired with rootfs-on-LVM images.

Provides the early userspace modules that create, populate, activate, or unlock LVM-backed storage before the real rootfs is mounted.

System updates use RAUC. Adding rauc to DISTRO_FEATURES selects the matching image configuration from recipes-core/images. See RAUC Update Flow for the bundle and slot configuration.

The UEFI QEMU configuration adds installer ISO output to orchestraos-image-minimal; it does not introduce another image recipe. For disk images, firmware, and installation, see Virtual Platforms.

Documentation Baseline

This documentation describes the Scarthgap configuration. A documentation branch identifies a maintained Yocto series; an OrchestraOS release tag and its KAS release fragments identify a particular image baseline. Development manifests follow layer branches and can select newer metadata than the release fragments. See OrchestraOS Releases and Maintenance and LTS Versions.