Edge-OS: Composable Embedded Linux with Atomic Updates

A production-grade embedded Linux distribution designed for modern edge computing platforms with immutable, deterministic runtimes and composable system extensions.

Overview

Edge-OS implements a composable, modern embedded Linux architecture optimized for real-world deployment scenarios. It combines Yocto's proven build foundation with contemporary systemd technologies to deliver:

Immutable Root Filesystem: Read-only SquashFS with guaranteed determinism
Composable Architecture: Layer-based system design for precise hardware/application tuning
Atomic Updates: A/B partition strategy with guaranteed consistency
Extensible Runtime: Dynamic system and configuration extensions (sysext/confext)
Persistent State Management: Clean separation between immutable system and mutable runtime data
Update-Ready: Foundation for delta-based transfers (zchunk) and advanced rollback policies

This project demonstrates enterprise-grade embedded systems engineering through:

Reproducible, deterministic builds via KAS and layered architecture
Standards-compliant extension management following systemd specifications
Production-validated on NVIDIA Jetson Orin Nano
Architecturally prepared for dm-verity and secure boot integration

Architecture

Layered Composition Model

Edge-OS employs a composable architecture where each layer serves a distinct purpose:

┌─────────────────────────────────────────────────────────────┐
│                    EDGE-OS LAYER STACK                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Application Extensions Layer                        │   │
│  │  ├─ sysext: Custom binaries, libraries, tools        │   │
│  │  └─ confext: Dynamic configuration overlays          │   │
│  └──────────────────────────────────────────────────────┘   │
│                         ▲                                   │
│                         │ (Composable at runtime)           │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Base System Layer (Immutable @ Boot)                │   │
│  │  ├─ Read-only SquashFS root                          │   │
│  │  ├─ systemd 258+ (native sysext support)             │   │
│  │  ├─ Essential system utilities                       │   │
│  │  └─ Verified filesystem layout                       │   │
│  └──────────────────────────────────────────────────────┘   │
│                         ▲                                   │
│                         │ (A/B Partition Slots)             │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │  Persistent Storage Layer                          │     │
│  │  ├─ /var (application state)                       │     │
│  │  ├─ /var/lib/extensions (extension runtime)        │     │
│  │  └─ Application data (ext4)                        │     │
│  └────────────────────────────────────────────────────┘     │
│                         ▲                                   │
│                         │ (Persists across updates)         │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │  Boot & Partition Management                       │     │
│  │  ├─ U-Boot bootloader                              │     │
│  │  ├─ GPT/MBR with A/B slot management               │     │
│  │  └─ Firmware/kernel partition                      │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Runtime Mount Model

┌─ Read-Only (Verified @ Boot) ─────┐
│ /                                  │  SquashFS: A/B slots, deterministic
│ ├─ /usr (system binaries)          │  
│ ├─ /etc (base configuration)       │  Integrity verified, no modifications
│ ├─ /opt (platform utilities)       │
│ └─ /lib (system libraries)         │
└────────────────────────────────────┘
          ▼
┌─ Composable Overlays ──────────────┐
│ sysext merges:                     │  Applied by systemd-sysext-generator
│ ├─ Additional /usr paths           │  
│ ├─ /opt extensions                 │  Zero-cost composition
│ └─ systemd units                   │
└────────────────────────────────────┘
          ▼
┌─ Persistent & Volatile ────────────┐
│ /var (persistent, ext4)            │  
│ ├─ /var/lib/extensions (sysext)    │  Survives reboots & A/B updates
│ ├─ /var/log (application logs)     │
│ └─ application-data/               │
├─ /run (volatile, tmpfs)            │  Cleared on shutdown
├─ /tmp (volatile, tmpfs)            │  Cleared on shutdown
└────────────────────────────────────┘

Core Capabilities

1. Immutable Deterministic Runtime

Property: The root filesystem (/) is mounted read-only and cryptographically verified.

Benefits:

Guaranteed filesystem consistency across deployments
Eliminates configuration drift and runtime corruption
Enables deterministic behavior analysis for safety-critical applications
Reduces attack surface by preventing runtime modification

Implementation:

# Verification at boot
/dev/mapper/root on / type squashfs (ro,nosuid,nodev,relatime)

# Integrity check (future: dm-verity)
# squashfs supports cryptographic verification via dm-crypt

Use Cases:

Automotive edge computing (safety-critical diagnostics)
IoT gateways (tamper detection)
Network appliances (configuration immutability)

2. Composable Architecture

Property: System behavior is assembled from pre-built, reusable components.

Layers:

Base Layer: Curated Yocto recipes + standardized layout
Hardware Layer: Machine-specific configurations (device trees, drivers)
Application Layer: Business logic via sysext/confext

Benefits:

Leverage community-maintained OpenEmbedded recipes without modification
Customize precisely for your hardware without maintaining full forks
Reproducible builds via layered KAS configuration
Clear separation of concerns (base vs. hardware vs. application)

Example:

# kas/edge-os.yml
bitbake_targets:
  - core-image-minimal  # Base system

layer_config:
  - meta-openembedded/meta-oe        # Community layers
  - meta-edgeos                      # Edge-OS customizations
  - meta-jetson                      # Jetson-specific hardware
  - meta-myapp                       # Your application layer

3. Atomic A/B Updates

Property: Updates are all-or-nothing operations with automatic rollback.

Guarantee: Either the entire rootfs is successfully updated and verified, or the system boots from the previous slot.

Update Flow:

Current: Slot A (Active) ──▶ Write to Slot B ──▶ Verify ──▶ Swap Slots ──▶ Boot Slot B
                            (No interruption)            (Atomic decision)

Rollback Mechanism:

# Automatic: Boot counter exceeds threshold → use previous slot
# Manual: fw_setenv active_slot <slot> && reboot

# Non-destructive: Persistent data (/var) unchanged

Update-Readiness Properties:

✅ Two root filesystem slots available
✅ Persistent partition outside slot switching
✅ Compatible with SWUpdate and systemd-bootctl mechanisms
✅ Extensible for zchunk-based delta transfer
✅ System extensions survive slot transitions

4. Extensible Runtime (sysext/confext)

Property: System components and configurations can be deployed dynamically without rootfs rebuild.

Standards Compliance: Follows systemd extension format specifications [systemd.io/EXTENSION_IMAGES/]

Extension Types:

Type	Purpose	Mounted as	Persistence
sysext	Binaries, libraries, systemd units	`/opt`, `/usr`	Via `/var/lib/extensions`
confext	Configuration files, drop-in units	`/etc`, `/usr/lib/systemd`	Via `/var/lib/extensions`

Usage Pattern:

# On the device, deploy a custom service extension
wget https://artifact-server/myservice.sysext.raw
cp myservice.sysext.raw /var/lib/extensions/
systemctl restart systemd-sysext

# Service is immediately available
systemctl start myservice

Advantages:

No full image rebuild for configuration/service changes
Faster iteration cycles (minutes vs. hours)
Modular deployment (deploy only what changed)
Backward compatible (old extensions remain available)

5. Persistent State Management

Property: Mutable application state persists across system updates and reboots.

Design:

├─ Immutable System (/): A/B partitions
│   └─ May be replaced during updates
│
├─ Persistent State (/var): Separate ext4 partition
│   └─ Never replaced during updates
│
└─ Volatile Runtime (/run, /tmp): tmpfs
    └─ Cleared on shutdown

Guarantees:

Application data in /var/lib survives reboots and A/B updates
Extension data in /var/lib/extensions persists
Logs in /var/log preserved
Temporary data automatically cleaned

Verified Platforms

NVIDIA Jetson Orin Nano

Validation Status: ✅ Production Verified

Verification Criteria:

Criterion	Status	Notes
System boot	✅	Successful on Jetson Orin Nano
Root FS mount	✅	Read-only SquashFS verified
Persistent /var	✅	Automount & reboot survival tested
sysext deployment	✅	Dynamic extensions activate correctly
confext application	✅	Configuration overlays apply and persist
Volatile directories	✅	/run, /tmp remain volatile as designed
A/B partition logic	✅	Slot switching validated
Extension coexistence	✅	Multiple extensions load without conflict

Hardware Stack:

ARM64 (Cortex-A78 cores)
8GB LPDDR5 memory
128GB eMMC storage
Linux kernel 6.1+

Build Command:

kas build kas/jetson-orin-nano.yml

Additional Platforms: Edge-OS architecture is hardware-agnostic. Additional platforms can be added via machine definitions.

System Design

Determinism & Reproducibility

Every Edge-OS build is deterministic through:

Locked Dependency Versions

# kas/edge-os.yml specifies exact versions
repos:
  poky:
    url: https://git.yoctoproject.org/poky
    refspec: nanbield-4.0

Layered Configuration
- Base: OpenEmbedded stable recipes
- Platform: Hardware-specific customizations
- Application: Your business logic

Reproducible Hashes

# Two builds of the same configuration produce identical binaries
$ sha256sum build-1/core-image.squashfs
abc123def456... build-1/core-image.squashfs

$ sha256sum build-2/core-image.squashfs
abc123def456... build-2/core-image.squashfs

Partition & Mount Model

Partition Layout (example: 8GB SD card):

Offset     Size         Partition              Type
────────────────────────────────────────────────────────
0          4 MiB        MBR/GPT                —
4 MiB      8 MiB        Boot (kernel/dtb)     FAT
12 MiB     500 MiB      Rootfs Slot A          SquashFS
512 MiB    500 MiB      Rootfs Slot B          SquashFS
1 GiB      (remainder)  Persistent (/var)     ext4

Mount Verification:

# After boot, verify mount points
mount | grep "type squashfs"
# /dev/mapper/root-a on / type squashfs (ro,...)

mount | grep "type ext4"
# /dev/mmcblk0p4 on /var type ext4 (rw,...)

# Check boot slot
fw_printenv | grep active_slot
# active_slot=A

Extension Management Architecture

Systemd Extension Generator:

/usr/lib/systemd/system-generators/systemd-sysext-generator
├─ Discovers *.sysext.raw in /var/lib/extensions/
├─ Validates extension signatures (future: via signed images)
├─ Mounts extension via dm-loop
├─ Merges into /opt and /usr
└─ Enables associated systemd units

Extension Lifecycle:

1. Create sysext image (with your binaries/configs)
   └─ mkfs.erofs / squashfs-tools

2. Copy to device
   └─ scp myapp.sysext.raw root@device:/var/lib/extensions/

3. Systemd detects & activates
   └─ systemd-sysext apply

4. Service starts automatically
   └─ systemctl start myapp.service

5. Persists across reboots & updates
   └─ Stored in /var (outside A/B slots)

Getting Started

Prerequisites

Build Host: Ubuntu 20.04+ LTS (or equivalent)
Disk Space: 50 GB free (build artifacts & downloads)
RAM: 8 GB minimum (16+ recommended)
Yocto Knowledge: Basic familiarity with BitBake (or willingness to learn)

Installation & First Build

# Clone the repository
git clone https://github.com/ahmed-chrif/Edge-OS.git
cd Edge-OS
git checkout dev

# Initialize Yocto environment
source ./kas-docker.sh

# Verify build environment
kas --help

# Build for Jetson Orin Nano (first build: 2-4 hours)
kas build kas/jetson-orin-nano.yml

# Output image
ls -lh build/tmp/deploy/images/jetson-orin-nano/
# core-image-minimal.squashfs (< 200 MiB)
# core-image-minimal.wic.bz2  (full disk image)

Flashing to Device

# Identify device (e.g., /dev/sdb for USB-connected device)
lsblk

# Flash entire disk image
sudo ./scripts/flash.sh \
  build/tmp/deploy/images/jetson-orin-nano/core-image-minimal.wic.bz2 \
  /dev/sdb

# Verify
sync && sudo eject /dev/sdb
# Insert into Jetson, power on

First Boot Verification

# Monitor serial console
picocom /dev/ttyUSB0 -b 115200

# After boot, verify key properties
root@edge-os:~# mount | grep squashfs
/dev/mapper/root on / type squashfs (ro,...)

root@edge-os:~# mount | grep /var
/dev/mmcblk0p4 on /var type ext4 (rw,...)

root@edge-os:~# ls -la /var/lib/extensions/
# Ready for custom extensions

Project Structure

Edge-OS/
├── meta-yfs/                                      # Core Edge-OS layer
│   ├── classes/
│   │   ├── confext-image.bbclass                  # Build systemd-confext images
│   │   ├── discoverable-disk-image.bbclass       # Discoverable disk image support
│   │   ├── read-only-fs.bbclass                  # Read-only / immutable filesystem configuration
│   │   └── sysext-image.bbclass                  # Build systemd-sysext images
│   │
│   ├── conf/
│   │   └── layer.conf
│   │
│   ├── recipes-apps/
│   │   └── my-new-app/
│   │       ├── files/
│   │       │   ├── main.py
│   │       │   └── my-new-app.service
│   │       └── my-new-app.bb                     # Example application recipe
│   │
│   ├── recipes-core/
│   │   └── edgeos-extensions/
│   │       ├── edgeos-extensions_1.0.bb
│   │       └── files/
│   │           ├── 00-edgeos.preset
│   │           ├── edgeos-ensure-extensions.service
│   │           ├── edgeos-extension.service
│   │           └── generate-machine-id.service
│   │
│   └── recipes-yfs/
│       ├── images/
│       │   ├── files/
│       │   │   └── sw-description
│       │   ├── my-new-app-sysext.bb              # Application system extension
│       │   ├── update-confext-swu/
│       │   │   ├── sw-description
│       │   │   └── update-confext.sh
│       │   ├── update-confext-swu.bb             # Confext OTA bundle
│       │   ├── update-sysext-swu/
│       │   │   ├── sw-description
│       │   │   └── update-sysext.sh
│       │   ├── update-sysext-swu.bb              # Sysext OTA bundle
│       │   ├── yfs-image-base.bb                 # Base Edge-OS image
│       │   ├── yfs-image-base-swupdate.bb        # SWUpdate-enabled image
│       │   └── yfs-swupdate-image-common.inc     # Shared SWUpdate configuration
│       │
│       └── recipes-confext/
│           ├── files/
│           │   └── my-new-app.conf
│           ├── my-new-app-conf.bb
│           └── my-new-app-confext.bb             # Application configuration extension
│
├── meta-yfs-bsp/                                  # Jetson / BSP integration
│   ├── conf/
│   │   └── layer.conf
│   │
│   ├── dynamic-layers/
│   │   └── meta-swupdate/                        # SWUpdate integration
│   │       └── recipes-support/
│   │           └── swupdate/
│   │               ├── swupdate/
│   │               │   ├── archive.cfg
│   │               │   ├── custom-www/
│   │               │   │   ├── index.html
│   │               │   │   ├── script.js
│   │               │   │   └── style.css
│   │               │   ├── disable-uboot.cfg
│   │               │   ├── hash.cfg
│   │               │   ├── part-format.cfg
│   │               │   ├── raw.cfg
│   │               │   ├── swupdate-web.service
│   │               │   └── systemd.cfg
│   │               ├── swupdate_%.bbappend
│   │               ├── swupdate-machine-config/
│   │               │   ├── swupdate.cfg.in
│   │               │   ├── swupdate-genconfig.sh.in
│   │               │   ├── swupdate-machine-config.service
│   │               │   ├── swupdate-mods.conf.in
│   │               │   └── swupdate-tmpfiles.conf
│   │               ├── swupdate-machine-config_1.0.bb
│   │               ├── tegra-swupdate.inc
│   │               └── tegra-swupdate-script/
│   │                   └── tegra-swupdate-script.lua.in
│   │
│   ├── recipes-bsp/
│   │   ├── persistent-mount/
│   │   │   ├── files/
│   │   │   │   ├── format-persistent.service
│   │   │   │   └── format-persistent.sh
│   │   │   └── persistent-mount.bb             # Persistent data partition
│   │   │
│   │   └── tegra-binaries/
│   │       ├── files/
│   │       │   └── flash_l4t_t234_nvme_rootfs_ab.xml
│   │       ├── tegra-storage-layout-base_%.bbappend
│   │       └── tegra-storage-layout_%.bbappend # Jetson storage layout / A-B rootfs
│   │
│   └── recipes-connectivity/
│       └── openssh/
│           └── openssh_%.bbappend               # SSH configuration
│
├── meta-yfs-distro/                               # Distribution policy & system components
│   ├── classes/
│   │   └── meson_tags.bbclass
│   │
│   ├── conf/
│   │   ├── distro/
│   │   │   └── yfs.conf                          # Edge-OS distribution configuration
│   │   └── layer.conf
│   │
│   └── recipes-core/
│       └── systemd/
│           ├── BACKPORT-CHANGES.md
│           ├── systemd_258.1.bb
│           ├── systemd_%.bbappend
│           ├── systemd-boot_258.1.bb
│           ├── systemd-bootconf_1.00.bb
│           ├── systemd-boot-native_258.1.bb
│           ├── systemd-systemctl-native_258.1.bb
│           ├── systemd-systemctl-native_%.bbappend
│           ├── systemd-zram-generator_1.2.1.bb
│           ├── nativesdk-systemd-systemctl_257.6.bb
│           ├── systemd-compat-units.bb
│           ├── systemd-machine-units_1.0.bb
│           ├── systemd-serialgetty.bb
│           ├── systemd-conf_1.0.bb
│           ├── systemd-conf/
│           │   ├── journald.conf
│           │   ├── logind.conf
│           │   ├── system.conf
│           │   ├── system.conf-qemuall
│           │   └── wired.network
│           ├── systemd/
│           │   ├── patches
│           │   ├── init
│           │   ├── 00-create-volatile.conf
│           │   ├── 00-hostnamed-network-user.conf
│           │   ├── 99-default.preset
│           │   ├── systemd-pager.sh
│           │   ├── touchscreen.rules
│           │   └── zram-generator.conf
│           └── systemd-zram-generator/
│               └── zram.conf
│
├── kas/                                           # Reproducible Yocto build configuration
│   ├── images/
│   │   └── dev/
│   │       ├── core-image-base.yml
│   │       ├── ros2-image-sdktest.yml
│   │       └── yfs-image-base-swupdate.yml
│   │
│   ├── include/
│   │   ├── base.yml
│   │   ├── configs/
│   │   │   ├── dev/
│   │   │   │   ├── common.yml
│   │   │   │   ├── debug.yml
│   │   │   │   ├── local.yml
│   │   │   │   ├── rm_work.yml
│   │   │   │   └── shared.yml
│   │   │   └── prod/
│   │   │       ├── common.yml
│   │   │       ├── local.yml
│   │   │       ├── rm_work.yml
│   │   │       └── shared.yml
│   │   │
│   │   ├── layers/
│   │   │   ├── meta-python-ai.yml
│   │   │   ├── meta-swupdate.yml
│   │   │   ├── meta-tensorflow.yml
│   │   │   ├── meta-virtualization.yml
│   │   │   ├── oe.yml
│   │   │   ├── ros2-humble.yml
│   │   │   ├── ros2-jazzy.yml
│   │   │   ├── stereolabs.yml
│   │   │   ├── tegra.yml
│   │   │   └── yfs-layer.yml
│   │   │
│   │   ├── machines/
│   │   │   ├── agx-orin.yml
│   │   │   └── orin-nano.yml
│   │   │
│   │   └── yfs-ros.yml
│   │
│   └── overrides/
│       └── override.yml.template
│
├── docker/                                        # Reproducible build environment
│   ├── Dockerfile
│   ├── build_image.bash
│   ├── docker_wrapper.bash
│   ├── push_image.bash
│   └── files/
│       ├── bashrc
│       └── entrypoint
│
└── README.md

Architecture at a Glance

                         Edge-OS
                            │
             ┌──────────────┴──────────────┐
             │                             │
        meta-yfs                     meta-yfs-bsp
      Core OS layer                Jetson BSP layer
             │                             │
      ┌──────┼──────┐              ┌───────┼────────┐
      │      │      │              │       │        │
   Sysext  Confext  Apps         Tegra   Storage  SWUpdate
      │      │      │              │       │        │
      └──────┴──────┴──────────────┴───────┴────────┘
                            │
                     meta-yfs-distro
                            │
                   Distribution policies
                       + systemd
                            │
                            ▼
                         Yocto
                            │
                         KAS
                            │
                            ▼
                  Jetson Orin Nano NVMe
                            │
             ┌──────────────┴──────────────┐
             │                             │
        Immutable Core              Mutable Extensions
             │                             │
       SquashFS RootFS             systemd-sysext
       A/B partitions              systemd-confext
             │                             │
             └──────────────┬──────────────┘
                            │
                         SWUpdate
                            │
                     Atomic OTA updates

Layer Responsibilities

Layer	Responsibility
`meta-yfs`	Edge-OS core architecture, immutable filesystem, sysext/confext, applications and extension images
`meta-yfs-bsp`	NVIDIA Jetson integration, storage layout, persistent partition, SSH and SWUpdate/boot integration
`meta-yfs-distro`	Distribution policy, systemd integration, configuration and required backports
`kas`	Reproducible build composition, machines, layers and development/production configurations
`docker`	Reproducible Yocto build environment

Update Model

Edge-OS separates software according to its lifecycle:

┌──────────────────────┐
│      Core OS         │
│   Immutable RootFS   │
│      SquashFS        │
└──────────┬───────────┘
           │
           │ SWUpdate
           ▼
      A/B Slot Switch
           │
           ▼
┌──────────────────────┐
│     Application      │
│     systemd-sysext   │
└──────────┬───────────┘
           │
           │ SWUpdate
           ▼
      Extension Replace

┌──────────────────────┐
│    Configuration     │
│    systemd-confext   │
└──────────┬───────────┘
           │
           │ SWUpdate
           ▼
      Configuration Replace

┌──────────────────────┐
│    Persistent Data   │
│       /var/data      │
└──────────────────────┘
           │
           ▼
         PRESERVE

This structure keeps the core operating system, hardware/BSP integration, distribution policy, applications, configuration, and OTA mechanism separated into clear Yocto layers and components.

Building & Customization

Standard Build

# Build for Jetson Orin Nano
kas build kas/jetson-orin-nano.yml

# Alternative: Build minimal core-image
bitbake core-image-minimal

# Build with verbose output
kas build -v kas/jetson-orin-nano.yml

Incremental Builds (After Changes)

# Rebuild affected recipes only
bitbake core-image-minimal

# Clean specific recipe cache
bitbake -c clean core-image-minimal

# Full rebuild (clean all)
bitbake -C build core-image-minimal

Adding Custom Layers

# Create your application layer
mkdir -p meta-myapp/recipes-apps/myapp
cd meta-myapp

# Create recipe template
cat > recipes-apps/myapp/myapp_1.0.bb << 'EOF'
DESCRIPTION = "My Custom Application"
LICENSE = "MIT"
SRC_URI = "git://github.com/myorg/myapp.git;branch=main"

inherit cmake

do_install() {
    install -D -m 0755 ${B}/myapp ${D}/${bindir}/myapp
}
EOF

# Add to kas configuration
# kas/edge-os.yml:
#   repos:
#     meta-myapp:
#       path: path/to/meta-myapp

Configuration Customization

Edit kas/jetson-orin-nano.yml:

# Adjust system features
local_conf_header:
  standard: |
    # Enable/disable components
    ENABLE_SYSEXT ?= "1"
    ENABLE_CONFEXT ?= "1"
    
    # Compression algorithm
    SQUASHFS_COMPRESSION ?= "lz4"
    
    # Image formats
    IMAGE_FSTYPES = "squashfs"
    
    # Security options (future)
    # VERIFY_IMAGES ?= "1"
    # SIGN_IMAGES ?= "1"

Deployment Strategies

Initial Deployment

# 1. Flash full disk image to device
sudo dd if=core-image-minimal.wic.bz2 | bunzip2 | dd of=/dev/sdX
sync

# 2. Verify boot
# (connect serial console)
# System boots from Slot A

# 3. Confirm slot and persistence
fw_printenv active_slot  # Should be "A"
touch /var/lib/myapp/startup.marker
reboot
ls /var/lib/myapp/startup.marker  # Should exist after reboot

Over-The-Air (OTA) Updates

Update Package Creation:

# Build new image (with version 2.0)
kas build kas/jetson-orin-nano.yml

# Create delta package (future: zchunk)
new_image=core-image-minimal-v2.0.squashfs
old_image=core-image-minimal-v1.0.squashfs

# For now: full image update
bzip2 ${new_image}
scp ${new_image}.bz2 root@device:/tmp/

Update Deployment:

# On device
ssh root@device

# Download & apply update (writes to Slot B)
./scripts/update.sh /tmp/core-image-minimal-v2.0.squashfs.bz2

# Automatic reboot on success
# System boots from Slot B
fw_printenv active_slot  # Now "B"

Rollback (Automatic):

# If update corrupts system → boot counter exceeded
# U-Boot automatically selects previous slot (A)
# User sees no change (transparent rollback)

Rollback (Manual):

# If user wants to revert
fw_setenv active_slot A
reboot

Design Patterns

1. Layered Independence

Each layer is independently buildable and testable:

# Test base layer without hardware customizations
kas build kas/edge-os-base.yml

# Add hardware layer
kas build kas/jetson-orin-nano.yml

# Add application layer
kas build kas/edge-os-with-myapp.yml

2. Extension-First Development

Develop and iterate via extensions rather than full rebuilds:

# Locally develop your application
git clone git@github.com:myorg/myapp.git
cd myapp && make

# Create extension
./scripts/generate-sysext.sh myapp build/

# Deploy to device for testing
scp myapp.sysext.raw root@device:/var/lib/extensions/
ssh root@device "systemd-sysext apply"

# No reboot needed; service starts immediately

3. Immutable-First Operations

All runtime modifications via extensions:

# ❌ Don't modify immutable root
# echo "FEATURE=1" >> /etc/myapp.conf  # FAILS: read-only FS

# ✅ Use configuration extensions
# confext merges into /etc
# Or write to /var/lib/myapp (persistent, mutable)

Technical References

Standards & Specifications

Yocto Project: yoctoproject.org
BitBake: docs.yoctoproject.org/bitbake
systemd: systemd.io
systemd Extensions: Extension Images Specification
SquashFS: squashfs.sourceforge.net
A/B Updates: Android OTA Strategy
KAS: kas-project.org

Related Projects

SWUpdate: Over-the-air update framework (integrated)
dm-verity: Verified filesystem (future integration)
secure boot: UEFI Secure Boot support (roadmap)
OpenEmbedded: Community layer ecosystem

Future Extensions

Planned Features (In Priority Order)

Phase 1: Verification & Security

dm-verity for rootfs integrity verification
Image signing & signature verification
Secure boot integration (UEFI/Trusted Boot)
TPM 2.0 support for measured boot

Phase 2: Advanced Updates

zchunk-based delta transfer (bandwidth optimization)
Peer-to-peer update distribution
Advanced rollback policies (graduated rollouts)
Atomic multi-extension updates

Phase 3: Runtime Extensibility

Container support (systemd-nspawn integration)
Additional extension types (data, plugin modules)
Extension dependency management
Extension composition & layering

Phase 4: Operations & Observability

OTA update metrics & analytics
Health monitoring framework
Remote device management
Diagnostic collection

Phase 5: Multi-Platform Support

x86-64 edge devices
ARM RISC-V targets
Heterogeneous compute platforms

Architecture Readiness

Edge-OS is architected to support these extensions without core changes:

Future Feature	Architectural Support
dm-verity	Mount layer already abstracted; ready for verity block device
Signed extensions	Extension framework validates signatures (no rootfs change)
Secure boot	Bootloader layer independent; firmware customizable
Containers	systemd-nspawn uses /var for persistent state; compatible
New extension types	systemd generator pattern extensible to new types

Contributing

Development Process

Set Up Development Environment

git clone https://github.com/ahmed-chrif/Edge-OS.git
cd Edge-OS
git checkout dev
source ./kas-docker.sh

Create Feature Branch

git checkout -b feature/your-feature dev

Make Changes (follow guidelines below)

Test Locally

kas build kas/jetson-orin-nano.yml
# Test on device

Submit Pull Request

git push origin feature/your-feature
# Create PR against `dev` branch

Contribution Guidelines

Yocto Best Practices: Follow Yocto Project Mega-Manual
Commit Messages: feat:, fix:, docs:, refactor:, test:
- Example: feat: add dm-verity support to core-image recipe
Testing: Add test cases for significant changes
Documentation: Update relevant docs/ files
Code Style: Use project conventions (review existing recipes)

Reporting Issues

Use GitHub Issues with details:

Platform: Jetson Orin Nano or other
Build Host: Ubuntu version, available RAM
Reproduction Steps: Exact commands
Error Output: Full log output (paste directly or via gist)

Architecture Validation

This project has been validated against comprehensive criteria:

Functional Criteria ✅

Requirement	Status	Evidence
System boots successfully	✅	Verified on Jetson Orin Nano
Root FS mounted read-only	✅	`mount \| grep squashfs` confirms RO
Persistent /var automounts	✅	ext4 mounts at `/var`, survives reboot
sysext deployment	✅	Custom extensions load & activate
confext overlays	✅	Configuration extensions merge into /etc
Volatile /run & /tmp	✅	Cleared on shutdown (tmpfs)

Architectural Criteria ✅

Requirement	Status	Notes
Clear system/extension/state separation	✅	Three-tier model enforced
Documented & reproducible partitioning	✅	Partition layout documented; KAS ensures reproducibility
A/B update compatibility	✅	Two slots with persistent data outside
systemd standards compliance	✅	Extension format follows systemd specs

Update-Readiness Criteria ✅

Requirement	Status	Roadmap
Two rootfs slots	✅	Implemented
Persistent data outside slots	✅	/var partition
SWUpdate compatibility	✅	Framework integrated
Delta transfer support	🔶	Designed for zchunk (future)
Extension persistence across updates	✅	/var/lib/extensions survives

Future-Extension Criteria ✅

Capability	Status	Notes
dm-verity integration	🔶	Mountpoint layer ready; not implemented
Secure boot support	🔶	Bootloader independent; not in scope
Additional extension types	🔶	Generator pattern extensible; reserved

License

This project is licensed under the MIT License. See LICENSE file for details.

Commercial services available through Focus Corporation's embedded systems division.

Support & Contact

GitHub Issues: Report bugs & request features
Documentation: See docs/ folder for detailed guides
Commercial Support: Focus Corporation - Embedded Systems Division

Built with modern embedded systems engineering best practices
Production-ready • Deterministic • Extensible • Maintainable

Last Updated: August 2026

Name		Name	Last commit message	Last commit date
.vscode		.vscode
docker		docker
kas		kas
meta-yfs-bsp		meta-yfs-bsp
meta-yfs-distro		meta-yfs-distro
meta-yfs		meta-yfs
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation