Introduction to meta-orchestraos

This repository provides the OrchestraOS Yocto distribution layer (meta-orchestraos), related meta-orchestraos-* layers, and the CI/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) to assemble reproducible builds locally and in CI

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.

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, bootloader update handling, and hawkBit updater integration.

meta-orchestraos-crypt

Optional storage encryption integration layer. It extends the base partitioning and initramfs flow when encrypted LVM-backed runtime storage is required. Access to this layer is restricted - please contact support@cthings.co for more 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 provided by meta-orchestraos-bsp (e.g. eigm, eigmdin, eigma, eigxs).

Features (DISTRO_FEATURES)

Used to enable or disable optional subsystems such as:

  • update mechanism: rauc or rdfm (mutually exclusive)

  • 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, OrchestraD, 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.

Update features are selected through DISTRO_FEATURES. rauc and rdfm are mutually exclusive; enabling one of them pulls in the matching image configuration from recipes-core/images. RAUC is the preferred update mechanism for OrchestraOS images.