.. _orchestra-os-quickstart:

######################
OrchestraOS Quickstart
######################

OrchestraOS builds are executed via **kas** manifests stored under ``ci/orcos/``.

Prerequisites
=============

- Linux build host (recommended)
- ``kas`` installed

Install kas
===========

.. code-block:: bash

   python3 -m pip install --upgrade kas

Set Up Layer Access
===================

Configure Git identity before building:

.. code-block:: bash

   git config --global user.name "[your_name] [your_surname]"
   git config --global user.email [your_name].[your_surname]@<YOUR-COMPANY-DOMAIN>.com

Then configure layer access for ``kas`` and BitBake using either an access
token or SSH keys.

.. note::

   Access token and SSH key authentication are alternatives. Configure one of
   them; both are not required.

Access Token
------------

Create a token in CTHINGS.CO Gitea with ``Code: Read`` access:

.. code-block:: text

   https://git.share.cthings.co/user/settings/applications

Store the token in a local credentials file:

.. code-block:: bash

   touch ~/.git-credentials

Add the credential entry:

.. code-block:: text

   https://<username>:<your-pat>@git.share.cthings.co

Configure Git to use that credentials file and export the ``kas-container``
access option:

.. code-block:: bash

   git config --global credential.helper 'store --file $HOME/.git-credentials'
   export REPO_ACCESS="--git-credential-store ${HOME}/.git-credentials"
   export KAS_PREMIRRORS='https://git\.share\.cthings\.co/orchestraos/ https://git.share.cthings.co/<YOUR_ORGANIZATION>/'

SSH Keys
--------

Add your public key in CTHINGS.CO Gitea:

.. code-block:: text

   https://git.share.cthings.co/user/settings/keys

Then export the ``kas-container`` access option and SSH premirror mapping:

.. code-block:: bash

   export REPO_ACCESS="--ssh-dir ${HOME}/.ssh"
   export KAS_PREMIRRORS='https://git\.share\.cthings\.co/orchestraos/ ssh://git@git.share.cthings.co:2222/<YOUR_ORGANIZATION>/'

Keep the credentials file and private SSH keys readable only by trusted local
users.

Environment variables used by builds
====================================

Common variables used across CI and local workflows:

- ``KAS_CONTAINER_IMAGE_DISTRO`` – container base (recommended: ``debian-bookworm``)
- ``CACHE_MIRROR`` – local/CI cache location for downloads and sstate
- ``ORCOS_VERSION`` – version string used as ``DISTRO_VERSION`` and the image version suffix

Build an image
==============

Example build for the EIG-M target:

.. code-block:: bash

   export KAS_CONTAINER_IMAGE_DISTRO="debian-bookworm"
   kas-container ${REPO_ACCESS} build ci/orcos/orcos-cmdline-rauc-eigm-release.yml

The default build configuration is defined by the ``*.yml`` file you pass to ``kas-container``. To change the ``DISTRO``, enable an update mechanism, or include additional features, edit the selected manifest and add the appropriate fragment (for example from ``ci/orcos/fragments/*``).

.. warning::

   Any secrets committed to this repository are for demonstration purposes only and must not be used in production images.

Build outputs
=============

Yocto build artifacts are typically located under:

.. code-block:: text

   work/build/tmp/deploy/images/<machine>/

Depending on the manifest and enabled features, you may see:

- ``*.uuu.zip`` – pre-packaged bundle of rootfs, bootloader, and flashing scripts
- update artifacts (e.g. ``*.rdfm`` or ``*.rauc``)
- checksums (``sha256sum``)

BSP Flashing And Device Securing
================================

The ``meta-orchestraos-bsp`` layer adds flashing support for supported
CTHINGS.CO gateways. Machine includes enable the ``image_types_uuu`` image
class, so i.MX builds can produce ``*.uuu.zip`` bundles containing the image
artifacts and generated UUU scripts.

The generated UUU bundle normally includes scripts such as:

- ``uuu-<UBOOT_CONFIG>.auto`` – standard flashing flow.
- ``uuu-no-bmap-<UBOOT_CONFIG>.auto`` – flashing flow that does not use a bmap
  file.
- ``uuu-fuse-<UBOOT_CONFIG>.auto`` – fuse-oriented flow used to provision
  secure-boot fuses and secure the device.

Example flashing commands for EIG-M:

.. code-block:: bash

   # EIG-M 2/4GB
   sudo uuu build/tmp/deploy/images/eigm/orchestraos-image-minimal-eigm.rootfs.uuu.zip/uuu-sd-d2d4.auto

   # EIG-M 1/8GB
   sudo uuu build/tmp/deploy/images/eigm/orchestraos-image-minimal-eigm.rootfs.uuu.zip/uuu-sd-d1d8.auto

   # EIG-M 2/4GB without bmap
   sudo uuu build/tmp/deploy/images/eigm/orchestraos-image-minimal-eigm.rootfs.uuu.zip/uuu-no-bmap-sd-d2d4.auto

Supported BSP machines also integrate redundant U-Boot boot selection. The
generated U-Boot environment tracks ``BOOT_ORDER`` and per-slot retry counters,
selects a boot slot, decrements the retry count before boot, and falls back to
the other slot when a slot exhausts its attempts.

Secure boot support is controlled by machine features such as
``imx-boot-signature`` and ``linux-imx-signature``. Signing is performed during
the image build: the BSP layer uses the signing recipes and machine-specific
CST/SPSDK data to produce signed bootloader and kernel artifacts. Signed kernel
images replace the unsigned kernel in ``IMAGE_BOOT_FILES`` so the flashed image
and RAUC boot slot use the same signed boot chain.

For production key generation and key placement, see :ref:`os-signing-keys`.

.. warning::

   Signing material committed in this repository is for reference and
   development only. Production images must use project-specific keys, fuse
   policy, and provisioning procedures.