.. _orchestra-os-intro:

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

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