.. _orchestra-os-intro:

################################
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 :ref:`os-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 :ref:`os-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 :ref:`os-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.

.. list-table:: Distro variants
   :header-rows: 1

   * - 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.

.. list-table:: Image variants
   :header-rows: 1

   * - 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
:ref:`os-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 :ref:`os-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 :ref:`os-release-cycle` and :ref:`os-documentation-versions`.