.. _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]@.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://:@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//' 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//' 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: .. code-block:: text machine github.com login x-access-token password YOUR_GITHUB_PAT Restrict access to the file: .. code-block:: bash 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``): .. code-block:: bash ( 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: yaml 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 :ref:`os-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 :ref:`os-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: .. code-block:: text build/tmp/deploy/images// This path assumes the normal local workspace. If ``KAS_WORK_DIR`` is set, use ``${KAS_WORK_DIR}/build/tmp/deploy/images//`` 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 :ref:`os-sbom` 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-.auto`` – standard flashing flow. - ``uuu-no-bmap-.auto`` – flashing flow that does not use a bmap file. - ``uuu-fuse-.auto`` – programs the signing-key hash. .. _os-eigm-flashing: 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. .. list-table:: EIG-M RAM and flashing-script selection :header-rows: 1 * - 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-.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. .. tab-set:: :sync-group: flashing-host :class: flashing-host-tabs .. tab-item:: Linux :sync: linux :selected: 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. .. code-block:: sh cd ~/Desktop/artifacts/eigm chmod +x ./uuu sudo ./uuu -lsusb Confirm that the gateway is listed, then flash the 2 GB variant: .. code-block:: sh sudo ./uuu uuu-sd-d2.auto For the same variant without a block map: .. code-block:: sh sudo ./uuu uuu-no-bmap-sd-d2.auto .. tab-item:: macOS (ARM) :sync: macos 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: .. code-block:: sh 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: .. code-block:: sh xattr -d com.apple.quarantine ./uuu_mac_arm ./uuu_mac_arm -lsusb Confirm that the gateway is listed, then flash the 2 GB variant: .. code-block:: sh sudo ./uuu_mac_arm uuu-sd-d2.auto For the same variant without a block map: .. code-block:: sh sudo ./uuu_mac_arm uuu-no-bmap-sd-d2.auto .. tab-item:: Windows :sync: windows Download ``uuu.exe`` from the current NXP release and put it in the extracted bundle directory. Open **Command Prompt** and list the connected devices: .. code-block:: bat cd /d "%USERPROFILE%\Desktop\artifacts\eigm" uuu.exe -lsusb Confirm that the gateway is listed, then flash the 2 GB variant: .. code-block:: bat uuu.exe uuu-sd-d2.auto For the same variant without a block map: .. code-block:: bat 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 :ref:`os-first-boot` 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 :ref:`os-signing-keys` 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.