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. For the credentials file, set chmod 600 ~/.git-credentials.

GitHub Personal Access Token

GitHub credentials can be configured alongside the CTHINGS.CO access above. Create a GitHub personal access token with read access to the repositories you need. For a fine-grained token, grant Contents: Read-only on the selected repositories.

For local builds, add this entry to ~/.netrc, replacing YOUR_GITHUB_PAT with your token and keeping any entries for other hosts:

machine github.com
login x-access-token
password YOUR_GITHUB_PAT

Restrict access to the file:

chmod 600 "$HOME/.netrc"

The netrc file supplies credentials when authentication is requested. Public GitHub sources can succeed anonymously. Configure Git once to send the same PAT on public requests too (run in Bash and enter the token from ~/.netrc):

(
    set +x
    umask 077
    read -rsp 'GitHub PAT: ' github_pat || exit 1
    printf '\n'
    github_basic="$(printf 'x-access-token:%s' "$github_pat" | base64 | tr -d '\n')"
    printf '\n[http "https://github.com/"]\n\textraHeader =\n\textraHeader = Authorization: Basic %s\n' \
        "$github_basic" >> "$HOME/.gitconfig"
    chmod 600 "$HOME/.gitconfig"
)

For local builds, enable forced wget authentication by adding the fragment:

export NETRC_FILE="$HOME/.netrc"
export GITCONFIG_FILE="$HOME/.gitconfig"
kas-container ${REPO_ACCESS} build \
    ci/orcos/orcos-cmdline-rauc-eigm-release.yml:ci/fragments/force-github-pat.yml

For GitLab CI, store the PAT in a masked CI/CD variable named CI_RUNNER_GH_PAT, or override GITHUB_PAT. The shared CI template configures Git and wget authentication in the disposable job container when the token is set. Temporary credential files preserve entries from an existing NETRC_FILE and are removed when the job exits.

kas manages its own GitLab URL rewrites and CI_JOB_TOKEN credentials. The local PAT fragment is only needed for local builds.

Environment Variables Used by Builds

Common variables used across local builds and CI:

  • KAS_CONTAINER_IMAGE_DISTRO – container base (recommended: debian-bookworm)

  • CACHE_MIRROR – optional cache location for downloads and sstate

  • ORCOS_VERSION – version string used as DISTRO_VERSION and the image version suffix

  • GITHUB_PAT – optional GitHub PAT used by the CI image build jobs

  • NETRC_FILE – credentials file shared with kas and BitBake

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 manifest passed to kas-container defines the build. Its public KAS fragments live under ci/fragments/. The directory name is retained in the release because these files define image composition and dependency selection.

Manifest Composition

ci/orcos/orcos-cmdline-rauc-eigm.yml combines the common distribution, RAUC, and EIG-M fragments. Its -release.yml counterpart additionally includes ci/orcos/release/orcos-cmdline-rauc-eigm.yml, which selects the release pins. BSP fragments bring in machine, firmware, signing, and storage configuration from their own layer repositories.

Use the release manifest from the same repository tag as the release you want to reproduce. The unpinned manifest follows development layer branches. DISTRO controls global feature policy, MACHINE controls hardware, and the target image recipe controls installed packages and artifact types.

For project-specific changes, add a local fragment rather than editing shared reference definitions. For example, save this as local-project.yml in the repository root:

header:
  version: 19
  includes:
    - ci/orcos/orcos-cmdline-rauc-eigm-release.yml
local_conf_header:
  project-version: |
    ORCOS_VERSION = "project-development"

Build it with kas-container ${REPO_ACCESS} build local-project.yml. KAS includes and BitBake override operations have different precedence rules; review active :append and :remove policies when changing a feature. For virtual targets, use the manifests in Virtual Platforms.

Repository Access

Obtain access to the participating layer repositories before building. Optional extension layers are available under separate commercial licenses; contact sales@cthings.co for access and licensing information. See Optional Extensions for the available capabilities. The premirror examples above map customer-facing repository addresses; inspect the repos entries of the selected fragments and ensure that each address is reachable with the chosen credentials. A mapping for one host does not rewrite an unrelated SSH host automatically.

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:

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

This path assumes the normal local workspace. If KAS_WORK_DIR is set, use ${KAS_WORK_DIR}/build/tmp/deploy/images/<machine>/ instead. A container mount may present the same workspace under a different path inside the build.

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

  • *.uuu.zip – pre-packaged bundle of rootfs, bootloader, and flashing scripts

  • *.raucb – RAUC update bundle

  • *.wic* – disk images; QEMU adds *.wic.qcow2

  • *.iso – installer media for the QEMU UEFI configuration only

  • *.manifest – installed package inventory

  • *.sha256sum – checksums for the configured output formats

Firmware files and report outputs depend on the platform and enabled features. See Software Inventory and Vulnerability Reports for SPDX, CycloneDX SBOM, VEX, and CVE report locations.

BSP Flashing and Provisioning

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 – programs the signing-key hash.

Example Flashing Commands for EIG-M

Obtain the OrchestraOS *.uuu.zip release bundle for the exact gateway model, or build it using the matching manifest above. eigm identifies EIG-M; eigmdin identifies EIG-M-DIN. Keep each gateway’s image, bootloader, block map, and scripts together from the same bundle.

Extract the EIG-M archive into a working directory, for example Desktop/artifacts/eigm. Download the host tool from the NXP mfgtools releases and put the executable alongside the extracted scripts and image files. Choose the binary for the host operating system and CPU architecture, rather than for the gateway’s CPU. The generated scripts declare their minimum UUU version in the first line; the reference scripts require 1.5.243 or newer.

EIG-M RAM and flashing-script selection

Gateway RAM

Script in the extracted bundle

1 GB (D1)

uuu-sd-d1.auto

2 GB (D2)

uuu-sd-d2.auto

4 GB (D4)

uuu-sd-d4.auto

8 GB (D8)

uuu-sd-d8.auto

Use the script matching the gateway’s actual RAM. For a flow without a block map, choose the corresponding uuu-no-bmap-sd-<variant>.auto script.

Prepare the gateway before running the selected host commands:

  1. Switch the gateway off and disconnect its power supply.

  2. Move the USB data cable from CONSOLE to the EIG-M programming connector labelled SIM (PROG). Use a cable that carries USB data.

  3. Select the board’s USB serial-download/programming mode, then reconnect power. The connector and boot-mode controls must match the gateway model.

The commands below assume the bundle and executable are in the example working directory and show flashing a 2 GB EIG-M. Replace uuu-sd-d2.auto with the script selected from the RAM table for another variant. The normal script writes the OS disk image and bootloader to eMMC.

Download uuu for a Linux x86-64 host and put it in the extracted bundle directory. For a Linux AArch64 host, use uuu_aarch64 and its filename in the commands instead.

cd ~/Desktop/artifacts/eigm
chmod +x ./uuu
sudo ./uuu -lsusb

Confirm that the gateway is listed, then flash the 2 GB variant:

sudo ./uuu uuu-sd-d2.auto

For the same variant without a block map:

sudo ./uuu uuu-no-bmap-sd-d2.auto

These commands apply to ARM-based macOS hosts (Apple Silicon). Download uuu_mac_arm from the current NXP release and place it in the extracted bundle directory. Make it executable before listing the connected devices:

cd ~/Desktop/artifacts/eigm
chmod +x ./uuu_mac_arm
./uuu_mac_arm -lsusb

If macOS blocks this downloaded binary because of its quarantine attribute, remove that attribute from the trusted NXP executable and repeat the device check:

xattr -d com.apple.quarantine ./uuu_mac_arm
./uuu_mac_arm -lsusb

Confirm that the gateway is listed, then flash the 2 GB variant:

sudo ./uuu_mac_arm uuu-sd-d2.auto

For the same variant without a block map:

sudo ./uuu_mac_arm uuu-no-bmap-sd-d2.auto

Download uuu.exe from the current NXP release and put it in the extracted bundle directory. Open Command Prompt and list the connected devices:

cd /d "%USERPROFILE%\Desktop\artifacts\eigm"
uuu.exe -lsusb

Confirm that the gateway is listed, then flash the 2 GB variant:

uuu.exe uuu-sd-d2.auto

For the same variant without a block map:

uuu.exe uuu-no-bmap-sd-d2.auto

In PowerShell, invoke the executable in the current directory with .\uuu.exe, for example .\uuu.exe uuu-sd-d2.auto. See NXP’s Windows UUU guide for host USB setup and troubleshooting.

For EIG-M in ROM download mode, the device listing can show MX865 with protocol SDPS. This is a UUU chip identifier; it is not the gateway’s model name. Bus and device addresses vary between hosts. If there is no matching entry, check power, the data cable, the programming connector, and USB download mode before starting the flash.

Wait for UUU to complete successfully with no failures. Then switch the gateway off, move the USB cable back to CONSOLE for serial access, restore normal boot mode if it was changed, and power the gateway on. First boot performs the storage provisioning described in First-Boot Provisioning and can reboot before normal login is available.

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.

Flashing an image, programming the key hash, and closing a device are distinct operations. Follow Signing Keys Generation for key placement, platform support, and the order of provisioning steps.

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.