Reference Manual

The FoundriesFactory™ Platform Reference Manual provides technical details, command options, and API calls, as well as instructions for some advanced use cases. See the User Guide or Tutorial sections for instructional focused content.

Tip

See the sidebar for a full list of topics covered in this Reference Manual.

Docker covers topics related to Factory containers and Compose Apps. This includes an architecture overview, how third party registries such as those from Amazon, Google, and Azure are configured, and Restorable Apps.

FoundriesFactory provides details on the tools and services that you have access to for working with and customizing your Factory.

Linux microPlatform (LmP) covers supported machines, OpenEmbedded/Yocto Project layers and tools such as building a Yocto Project Software Development Kit (SDK), and working with the kernel.

Over the Air Updates: OTA Update related topics including: tools, production Targets, device tags, and clients.

Remote Access Details WireGuard® VPN.

Security goes over a wide spectrum of security related topics including device boot, connecting to cloud services, and secure updates.

Testing provides an overview of the testing done for the FoundriesFactory Platform.

• Docker
  • Architecture Overview
  • Using Secret Credentials When Building Containers
    • Overview of CI Secrets
    • Defining Factory Secrets
    • Passing Secrets to Docker’s Build Context
  • Using Third-Party Private Container Registries
    • Configuring for CI Azure Container Registry (ACR)
      • Configuring Devices for ACR
    • Configuring CI for AWS ECR
      • Configuring Devices for AWS ECR
    • Configuring for CI Google Artifact Registry (GAR)
      • Configuring Devices for GAR
  • Restorable Apps
    • Employment of Restorable Apps
  • Caching
    • Cache Invalidation
• FoundriesFactory
  • Factory Sources
    • Triggering Builds
    • Configuring the CI to Build New Branches
      • Platform Branches
      • Container Branches
  • Factory Definition
    • notify
    • tuf
    • lmp
      • Variables
    • containers
    • container_registries
    • ci_scripts
      • Variables
  • Software Bill of Materials
    • SBOMs and Builds
      • Yocto Project Artifacts
      • Syft Artifacts
    • Working With SBOMs
    • Going Further
  • API Access
    • Common Scopes
    • Token Scopes
      • Source
      • Containers
      • CI
      • Devices
      • Targets
  • CI Webhooks
    • Prerequisites
    • Configuring Webhooks
    • Configuring the Factory
    • Example
      • Prepare the App
      • Create the Secret
      • Launch the App
      • Push a Change
  • Event Queues
    • Implementation Details
    • Creating a Pull Queue
    • Creating a Push Queue
      • Quick Start Example
      • Push Queue Payloads
      • Push Queue Security
    • Event Types
      • DEVICE_FIRST_SEEN
      • DEVICE_LAST_SEEN
      • DEVICE_CONFIG_APPLIED
      • DEVICE_OTA_STARTED
      • DEVICE_OTA_COMPLETED
      • DEVICE_OTA_APPS_STATE_CHANGED
      • DEVICE_PUBKEY_CHANGE
  • Data Retention Policies
    • Customer Data
      • source.foundries.io
      • ci.foundries.io
      • CI Workers
      • api.foundries.io
      • app.foundries.io
    • Device Data
      • hub.foundries.io
      • ota-lite.foundries.io
      • ostree.foundries.io
• Linux microPlatform
  • Board Machine Names
  • Repo Source Control Tool
  • Understanding FIO Development Tags
  • Linux Kernel
    • LmP Kernel Configuration Fragments
    • LmP With Real-Time Linux Kernel
      • Building LmP with linux-lmp-rt
      • Building LmP With linux-lmp-fslc-imx-rt
    • LmP With Linux Upstream
      • Building LmP With linux-lmp-dev
      • Specifying Linux Git Tree, Branch, and Commit Revision
  • LmP File Structure
    • OSTree File System Structure
    • Persistent Storage
    • Important Files and Folders
    • Tips and Suggestions
  • OpenEmbedded / Yocto Project Layers
    • LmP Base Layers
    • LmP BSP Layers
    • The meta-lmp Base Layer
    • The meta-lmp-bsp Layer
    • Customizing the LmP BSP Layers List
  • LmP Distros
    • lmp
    • lmp-base
    • lmp-mfgtool
    • lmp-wayland/lmp-xwayland
  • WIC Image Installer
    • Testing WIC Image Installer With QEMU (x86)
  • Persistent Log Support
    • Disable OpenEmbedded VOLATILE_LOG_DIR
    • Add systemd-journald-persistent to Your Image
    • Optional: Customize systemd-journald Options
  • Network Debugging
    • Using tcpdump
      • Capturing Bluetooth 6lo Network Traffic
      • Capturing LAN Network Traffic
      • Other Network Interfaces
      • Capturing to a File
    • External References
  • Disk Encryption Support
    • Prerequisites
    • Enabling Support for Disk Encryption
      • Implementation Details for OP-TEE PKCS#11 Support
      • Testing TPM 2.0 Support With Qemu (x86) and swtpm
    • Implementation Details for OP-TEE PKCS#11 Support
      • Testing PKCS#11 Support With Qemu (arm64)
  • Updating the Linux microPlatform Core
    • Updating Your Factory
      • lmp-manifest
        • Common Pitfalls
      • meta-subscriber-overrides
    • Verifying Your Work
    • Merging Back to Development
    • Common Errors and Tips
  • LmP Root File-System Over NFS
    • Introduction
    • NFS Use Case: Validation of eMMC Card
    • Enabling NFS Support on initramfs
    • Preparing the NFS Server
    • Preparing the TFTP Server
    • Using U-boot to Boot the NFS
  • Development Mode
  • OSS Compliance With FoundriesFactory
    • Providing Source Code and License Manifest
    • How to Avoid Using Packages Depending on the License
      • INCOMPATIBLE_LICENSE
      • IMAGE_LICENSE_CHECKER_ROOTFS_DENYLIST
    • How to Remove Packages Under GPLv3 Family License
  • Factory Reset
    • Full Factory Reset
    • Partial Factory Reset
      • Keep SOTA
      • Keep SOTA and Docker
      • RPMB
  • Building The Yocto Project Standard SDK
    • Installation
  • Toolchain
    • Changing the Toolchain
    • Customizing the Default Toolchain
• Over the Air Updates
  • Architecture Overview
    • How A Device Uses Security Hardware
    • How A Device Finds Updates
  • Fioconfig
    • Configuration Storage
    • Implementation
    • Diagram
  • Aktualizr-Lite
    • Daemon Mode (Default)
    • Configuration
      • Configuration Update Methods
      • Parameters
  • Device Tags
    • Managing Tags
  • Advanced Tagging
    • Terminology
    • Scenario 1: A New Platform Build That Re-Uses Containers
    • Scenario 2: Multiple Container Builds Using the Same Platform
    • Scenario 3: Multiple Teams, Different Cadences
  • Configuring Devices
    • Fleet-Wide Configuration
    • Device Group Specific Configuration
    • Device Specific Configuration
    • “Raw” Configuration
  • Targets Overview
    • Visualizing a Factory
  • CI Targets
    • Condensed Targets
    • Target Pruning
  • Production Targets
    • Performing a Production OTA
    • Advanced Usage
      • Releasing to Canary Devices
      • Releasing to Large Device Fleets
      • Integration with External Device Management Systems
      • Going Beyond Limits
  • OSTree Static Deltas
    • Generating Static Deltas
      • Understanding Why Static Deltas are Needed
      • Creating Static Deltas
  • Update Rollback
    • Rollback Driven by Rootfs Update Failure
      • Rollback Driven by a Bootloader Update Failure
    • Rollback Driven by Compose Apps Update Failure
      • Apps Driven Rollback in the Case of a Composite Update
      • Apps Driven Rollback in the Case of a Just Apps Update
    • Rollback Driven by User (Experimental)
• Remote Access
  • WireGuard VPN
    • Actions on VPN Server
    • Enabling Remote Access to a Device
    • Changing Wireguard Server Address
    • Troubleshooting
      • Method 1
      • Method 2
      • Further Debug
• Security
  • Overview
  • FoundriesFactory Security Summary
    • Summary of Crypto Keys Used by FoundriesFactory
      • Secure Connection to Cloud Services
      • Secure Boot (Hardware Root of Trust)
      • Secure Online Keys for Boot Stack
      • Secure Over the Air Updates
  • Secure Connection to Cloud Services
    • Factory PKI
      • Managing Your Factory PKI
        • Setting Up Your PKI
        • Rotating Server TLS Certificate
        • Adding Device CA
        • Revoking Device CA
      • Terminology
        • Root of Trust: factory_ca.key / factory_ca.pem
        • Server TLS Certificate: tls-crt
        • Device Client Certificate
        • Online Device CA: online-ca
        • Local Device CA: local-ca
        • EST Server TLS Certificate: est-tls-crt
      • Related Topics
    • Manufacturing Process for Device Registration
      • Fully Detached
      • Registering Production Device by Default
        • lmp-device-auto-register Configuration
        • Registration Reference Configuration
      • Partially Detached
        • Partially Detached lmp-device-auto-register Configuration
        • Partially Detached Registration Reference Configuration
    • Device Network Access
    • Device Certificate Rotation
      • How It Works
      • Tracking Progress
      • Next Steps
  • Secure Boot (Hardware Root of Trust)
    • Secure Boot on i.MX 6/8M Using HABv4
      • Our Implementation
      • HABv4 Architecture Overview
      • How to Secure the Platform
        • i.MX 8MM Fusing
      • How to Sign an SPL Image
        • How to Sign an SPL Image for SDP
        • Booting Signed Images With the Universal Update Utility
      • Booting a Closed System With a CAAM Device
    • Secure Boot on i.MX 8/8X Families Using AHAB Including 8QM
      • AHAB Architecture Overview
      • How to Secure the Platform
      • i.MX 8QM Fusing
      • How to Sign an i.MX Boot Image
      • How to Close the Board
      • How to Close the Board Using UUU Script
    • Unified Extensible Firmware Interface (UEFI) Secure Boot
      • Our Implementation
      • Keys and Roles
      • Vendor Operating Modes for UEFI Secure Boot
      • Creating UEFI Secure Boot Keys
      • Enabling UEFI Secure Boot Usage in LmP
      • UEFI Secure Boot Provisioning
      • UEFI Secure Boot Key Revocation
      • Testing UEFI Secure Boot Provisioning With QEMU
      • Backup Current UEFI Secure Boot Certificates
      • Enrolling Custom UEFI Secure Boot Certificates
      • Verifying the UEFI Secure Boot State
      • Additional Documentation and References
    • Machines with Secure Aspects Enabled by FoundriesFactory
      • Supported Machines
      • Enabling
      • Using the Secure Machine
      • Using Custom Keys
        • Creating the Keys
        • Generate the MfgTools Scripts
      • Accessing Secure Storage
        • Writing to Secure Storage
        • Reading From Secure Storage
    • Revoke Secure Boot Keys on i.MX
      • Revocation of a Key: Overview
      • How to Sign the Boot Image for Revoking a Key
      • How to Revoke a Key
      • How to Revoke a Key for Devices in a Fleet
  • Secure Online Keys for Boot Stack
    • Crypto Keys Used by FoundriesFactory at Build Time
      • Secure Boot Flow
        • i.MX Secure Boot Flow
        • UEFI Secure Boot Flow
      • FoundriesFactory Keys
        • How to Rotate the FoundriesFactory Keys
          • U-Boot Keys
          • OP-TEE Keys
          • TrustedFirmware-A Keys
          • Linux Kernel Modules Keys
  • Secure Over the Air Updates
    • Offline Factory TUF Keys
      • How to Rotate Offline TUF Root Key
      • How to Rotate Offline TUF Targets Key
      • How to View Offline TUF Keys
      • How to Backup Offline TUF Keys
      • Expert Mode
        • How to Add More Than 1 Offline TUF Keys
        • How to Increase the TUF Signature Threshold
        • Recommended Offline TUF Keys Schema
    • Secure Boot Firmware Updates
      • Boot Software Updates on iMX
        • Boot Artifacts
          • SPL
          • U-Boot FIT Image
        • MMC Boot Image Layout
        • Boot Flow
          • SPL
          • ATF (ARMv8)
          • OP-TEE
          • U-Boot
        • Update Procedure
          • Primary vs Secondary Boot Paths
          • libaktualizr and aktualizr-lite
          • U-Boot boot.cmd Script
        • Add a New Board
          • TF-A/OP-TEE
          • U-Boot
            • SPL: FIT Image Offset Calculation
            • Fastboot: Support of Secondary Boot Image Offsets
            • Secondary Image Table Generation
            • Watchdog
          • meta-lmp
            • MfgTool Scripts
            • lmp.cfg Files
            • Pre-Load boot.cmd by SPL
          • Test Basic API
          • boot.cmd
          • Sysroot and Signed Boot Artifacts
      • Boot Software Updates on iMX8QM
        • Boot Artifacts
          • imx-boot Image
          • U-Boot FIT Image
        • MMC Boot Image Layout
        • Update Procedure
          • Primary vs Secondary Boot Paths
          • Libaktualizr and Aktualizr-Lite
          • U-Boot boot.cmd Script
        • Add a New Board
          • meta-lmp
            • mfgtool Scripts
            • lmp.cfg Files
            • Pre-Load boot.cmd by SPL
          • Test Basic API
          • boot.cmd
          • Sysroot and Signed Boot Artifacts
      • Anti-Rollback Protection
        • Introduction
        • Store Boot Firmware Version in Boot Firmware Artifacts
        • Enable U-Boot Access to Boot Firmware Metadata
        • Enable Anti-Rollback Protection
  • Secure Element as Secrets Storage
    • EdgeLock™ SE05x: Plug & Trust Secure Element
      • NXP SE05x Plug & Trust MW
      • NXP SE05x Plug & Trust TEE Integration
      • OP-TEE Integration
      • Serial Communications to the SE05x
      • Secure Communication Protocol 03
      • SE05x Non Volatile Memory
      • Importing Secure Objects to PKCS#11 Tokens
    • Enabling SE05X
    • Trusted Platform Module
      • TPM 2 Software Stack
      • TPM 2 PKCS#11 Support
      • Validating TPM 2 PKCS#11
      • Registering LmP Devices With TPM 2 PKCS#11
• Testing
  • Test Plan
    • What to Test
      • LmP Test Plan
      • OS Features
        • Boot Test and Smoke Test
        • OSTree
        • Docker
        • Networking on Host
        • Interface Testing (Optional)
      • Device Update
        • Aktualizr (OTA API)
        • Device Config (Fioconfig)
    • How To Test
      • LmP Tests
        • Boot Testing
        • Basic Tests
    • When to Test
  • Architecture Overview
    • Workflow
  • Fiotest
    • The Model
    • The API
      • POST /tests/
      • PUT /tests/<test id>
    • Creating Custom Tests