OTAForge

Plane: Data Plane

Purpose

OTA artifact management, distribution, and policy-driven rollout automation. OTAForge is the platform service for publishing software artifacts and automatically distributing them to devices based on policies. It wraps Eclipse hawkBit with a multi-tenant administration layer, CI/CD integration via access keys, and proxied device polling.

OTAForge answers two questions:

• For distributors (developers, build systems): “How do I publish artifacts to the platform?”

• For operators: “What policies govern which devices get updated, when, and in what order?”

Responsibilities

• Create and manage software artifacts (firmware, maps, configs, ML models, certificates)

• Organize artifacts into distribution sets (bundled deployable units)

• Automatically create rollout campaigns based on policy evaluation

• Poll DeviceAdmin for device state (firmware version, type, status)

• Provide access keys (AK/SK) for CI/CD integration (Jenkins, GitHub Actions, etc.)

• Proxy the DDI endpoint — devices poll OTAForge, not hawkBit directly

• Provide administration UI for artifact publishing and rollout monitoring

• Expose distributor portal for external parties to manage their artifacts

How OTAForge Relates to Other Services

Distributors                    OTAForge                      Devices
(developers,                                                  (via proxied DDI)
 CI/CD)
                         ┌──────────────────┐
Jenkins ──AK/SK─────────►│                  │
                         │  Artifact Mgmt   │
GitHub Actions ──AK/SK──►│  Policy Engine   │◄──── Policy Service
                         │  DDI Proxy       │       (rollout policies)
Web UI ─────────────────►│  Access Keys     │
                         │                  │◄──── DeviceAdmin
                         └───────┬──────────┘       (device state polling)
                                 │
                           DDI proxy
                                 │
                                 ▼
                          Edge Devices
                          (Hara client polls
                           OTAForge DDI endpoint)

Policy-Driven Rollouts

Rollouts are never created manually or triggered by CI/CD pipelines. OTAForge evaluates policies continuously and creates rollouts automatically when conditions are met.

How It Works

┌──────────────┐     poll device state    ┌──────────────┐
│  DeviceAdmin  │◄─────────────────────────│   OTAForge   │
│               │                          │              │
│  Device fleet │  firmware versions,      │  Compare     │
│  state        │  device types,           │  device state│
│               │  enrollment status       │  vs policies │
└──────────────┘                          └──────┬───────┘
                                                  │
                   ┌──────────────┐               │ evaluate
                   │Policy Service│◄──────────────┘
                   │              │
                   │ Rollout      │  "AMRs below v2.5 in
                   │ policies     │   Zone B should be
                   │              │   updated during
                   │              │   maintenance windows"
                   └──────────────┘
                          │
                          │ match
                          ▼
                   ┌──────────────┐
                   │  Auto-create  │
                   │  rollout in   │
                   │  hawkBit      │
                   └──────────────┘

1. OTAForge periodically polls DeviceAdmin for device state (firmware version, type, capabilities, enrollment status)

2. OTAForge evaluates Policy Service rollout policies against the current device fleet and available distribution sets

3. When a policy matches (e.g., “all AMRs with firmware < v2.5 should receive distribution set v2.5.0”), OTAForge auto-creates a rollout campaign in hawkBit

4. The rollout proceeds according to phased deployment rules defined in the policy

Why Policy-Driven Only

Approach	Why Not
Manual rollout creation	Error-prone, doesn’t scale, bypasses safety policies
CI/CD-triggered rollouts	Couples deployment pipeline to device fleet state; CI knows about artifacts, not about which devices need them
Policy-driven (chosen)	Decouples artifact publishing from rollout execution; policies encode organizational intent; OTAForge handles the “when” and “which devices” automatically

CI/CD pipelines publish artifacts. Policies decide when and where those artifacts get deployed. These are separate concerns.

Rollout Policies

The Policy Service provides rollout constraints that OTAForge evaluates:

Policy	Effect
Target selection	Which devices should receive an update (by type, version, zone, OU)
Maintenance window	Only deploy during off-peak hours
Battery threshold	Skip devices below minimum battery level
Active task check	Defer update if device is executing a contract
Concurrent limit	Maximum simultaneous updates per zone
Phased deployment	Canary → percentage ramp → full deployment
Success threshold	Auto-pause if failure rate exceeds threshold

Rollout Scoping

Rollouts target devices based on account hierarchy and policy expressions:

Scope Level	Target	Example
Account	All devices in an account	“Update all robots in Account A”
Organization	All devices across org member accounts	“Update all Syrius devices company-wide”
OU	Devices in a specific organizational unit	“Update Building A robots”
Device type	Devices matching a type filter	“Update all AMRs”
Policy expression	Devices matching a compound filter	“AMRs with firmware < v2.4 in Zone B”

Phased Rollouts

OTAForge wraps hawkBit’s phased rollout with policy-defined phases:

Auto-created Rollout: "Firmware v2.5.0 to Building A AMRs"
├── Phase 1: 10% of targets (canary)
│   ├── Success threshold: 100%
│   └── Wait: 30 min observation
├── Phase 2: 50% of targets
│   ├── Success threshold: 90%
│   └── Wait: 1 hour observation
└── Phase 3: remaining targets
    └── Auto-pause on > 5% failure rate

Proxied DDI Endpoint

Devices poll OTAForge’s DDI (Device Domain Interface) endpoint, not hawkBit’s DDI directly. OTAForge proxies DDI requests to hawkBit with additional account scoping and audit logging.

Edge Device                OTAForge              hawkBit
(Hara client)              (DDI proxy)
    │                          │                    │
    │  GET /ddi/v1/{tenant}/   │                    │
    │  controller/{id}         │                    │
    │─────────────────────────►│                    │
    │                          │  Validate tenant   │
    │                          │  + audit log       │
    │                          │                    │
    │                          │  GET /ddi/v1/...   │
    │                          │───────────────────►│
    │                          │                    │
    │                          │◄───────────────────│
    │  200 OK                  │                    │
    │  (deployment actions)    │                    │
    │◄─────────────────────────│                    │

Benefits of proxied DDI:

• Tenant validation — OTAForge verifies the device belongs to the claimed account before forwarding

• Audit logging — all DDI interactions are logged for compliance

• Rate limiting — protect hawkBit from misconfigured polling intervals

• Abstraction — devices never know about hawkBit; the DDI endpoint URL can change without device-side updates

Access Key Model

OTAForge provides access keys (AK/SK pairs) for programmatic artifact publishing. This enables CI/CD pipelines to push artifacts automatically.

Use Case: Jenkins Integration

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│   Jenkins    │     │   OTAForge   │     │   hawkBit    │
│   Pipeline   │     │              │     │              │
│              │     │              │     │              │
│ Build ───────┤     │              │     │              │
│ Test  ───────┤     │              │     │              │
│ Package ─────┤     │              │     │              │
│              │     │              │     │              │
│ Push artifact│     │              │     │              │
│ (AK/SK auth) │────►│ Validate key │     │              │
│              │     │ Store artifact├───►│ Software     │
│              │     │              │     │ module       │
│              │     │              │     │              │
│ Create dist  │     │              │     │              │
│ set (AK/SK)  │────►│ Create set   ├───►│ Distribution │
│              │     │              │     │ set          │
└─────────────┘     └──────────────┘     └──────────────┘
                                          (rollout created
                                           later by policy
                                           evaluation)

CI/CD pipelines publish artifacts and create distribution sets. They do not create rollouts — that is handled automatically by policy evaluation.

Access Key Scoping

Key Type	Scope	Permissions
Publisher key	Account	Create artifacts, software modules, distribution sets
Read-only key	Account	Query artifact and distribution set status

Access keys are scoped to the issuing account. A publisher key for Account A can only create artifacts visible to Account A’s devices.

Artifact Management

Artifact Types

OTAForge supports any file type via hawkBit’s custom Software Module Types:

Type Key	Content	Example
os	Operating system images	Ubuntu 22.04 for AMR compute module
firmware	Firmware binaries	Motor controller v3.2
application	Application packages	WES edge agent v1.5
mapdata	Navigation maps, floor plans	Building A, Floor 1, v3
mlmodel	ML/AI model weights	Obstacle detector YOLO v1.2
config	Configuration files	Network config, policy bundles
certificate	TLS certs, identity certs	Device CA rotation

Distribution Sets

A distribution set bundles multiple artifacts for atomic deployment:

Distribution Set: "AMR v2.5.0 + Map Update Q1"
├── Software Module: firmware v2.5.0 (type: firmware)
│   └── artifact: amr-firmware-2.5.0.bin (sha256: a1b2c3...)
├── Software Module: nav-map-building-a-v3 (type: mapdata)
│   └── artifact: building-a-floor1.pbstream
│   └── artifact: building-a-floor2.pbstream
└── Software Module: obstacle-detector v1.2 (type: mlmodel)
    └── artifact: yolo-obstacle-v1.2.onnx

Administration UI

OTAForge provides two web interfaces:

Operator UI

For platform operators and application administrators:

• Artifact browser and version history

• Distribution set composition

• Rollout monitoring and status dashboards (rollouts are auto-created by policies)

• Fleet update status overview

• Policy configuration for rollout automation

Distributor Portal

A separate web application for external distributors (device manufacturers, software vendors) who publish artifacts via web UI instead of CI/CD:

• Artifact upload and metadata management

• Access key generation and rotation

• Distribution set creation

• Publishing status and download analytics

Both UIs follow the IBM Carbon Design System and are built with React + TypeScript, consistent with StarGate.

API Surface

Artifacts

Operation	Description
POST /artifacts	Upload an artifact (AK/SK or token auth)
GET /artifacts?account=&type=	List artifacts with filtering
GET /artifacts/{id}	Get artifact details and metadata
DELETE /artifacts/{id}	Delete an artifact

Software Modules

Operation	Description
POST /modules	Create a software module
GET /modules?account=&type=	List modules
POST /modules/{id}/artifacts	Add artifact to module

Distribution Sets

Operation	Description
POST /distribution-sets	Create a distribution set
GET /distribution-sets?account=	List distribution sets
GET /distribution-sets/{id}	Get distribution set details
POST /distribution-sets/{id}/modules	Add module to distribution set

Rollouts (read-only — created by policy engine)

Operation	Description
GET /rollouts?account=&status=	List rollouts
GET /rollouts/{id}	Get rollout status and progress
POST /rollouts/{id}/pause	Pause a rollout (emergency override)
POST /rollouts/{id}/resume	Resume a paused rollout

Access Keys

Operation	Description
POST /access-keys	Generate an access key pair
GET /access-keys?account=	List access keys
DELETE /access-keys/{id}	Revoke an access key
POST /access-keys/{id}/rotate	Rotate an access key

DDI Proxy

Operation	Description
GET /ddi/v1/{tenant}/controller/{id}	Proxied DDI: device polls for pending actions
GET /ddi/v1/{tenant}/controller/{id}/deploymentBase/{actionId}	Proxied DDI: get deployment details
POST /ddi/v1/{tenant}/controller/{id}/deploymentBase/{actionId}/feedback	Proxied DDI: device reports installation status

Implementation

Aspect	Technology
Framework	Java 21 (Spring Boot)
OTA engine	Eclipse hawkBit (Management API + DDI)
DDI proxy	Reverse proxy layer in front of hawkBit DDI
Artifact storage	S3 (via hawkBit’s artifact repository)
Database	PostgreSQL (access keys, policy evaluation state, account scoping)
UI	React + TypeScript + IBM Carbon Design System
Build tool	Vite

Dependencies

Service	Relationship
hawkBit	Underlying OTA engine (artifact storage, DDI, rollout execution)
DeviceAdmin	Device fleet state for policy evaluation (polled periodically)
Org Service	Account and organization hierarchy for rollout scoping
Policy Service	Rollout policies (target selection, maintenance windows, thresholds)
DotID	Authenticates API calls, access key validation

Consumed By

Consumer	Usage
DeviceAdmin	Reads OTA status for device fleet view
CI/CD pipelines	Publish artifacts and distribution sets via access keys
Distributors	Publish and manage artifacts via portal
Operators	Monitor rollout progress, configure rollout policies
Edge devices	Poll DDI proxy for pending updates
Applications	Query update status for application-specific views