OrchestraOS Quickstart

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

Prerequisites

  • Linux build host (recommended)

  • kas installed

Install kas

python3 -m pip install --upgrade kas

Set Up Layer Access

Configure Git identity before building:

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:

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

Store the token in a local credentials file:

touch ~/.git-credentials

Add the credential entry:

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

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

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:

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

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

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:

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:

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:

# 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 Signing Keys Generation.

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.