Eclipse hawkBit + Hara¶

Layer: IoT Layer

Purpose¶

Eclipse hawkBit is the OTA (Over-The-Air) update and artifact delivery engine for FlexGalaxy.AI, wrapped by OTAForge for multi-tenant artifact management, CI/CD integration, and rollout administration. hawkBit manages the distribution of software, firmware, and any other files to edge devices — with phased rollouts, safety thresholds, and campaign management.

Eclipse Hara is the device-side client library that implements hawkBit’s DDI (Device Domain Interface) API, handling artifact download, verification, and installation on JVM-based devices.

Why hawkBit¶

Criterion	hawkBit
License	Eclipse Public License 2.0
Artifact types	Domain-independent — any binary blob
Rollout control	Phased rollouts with configurable failure thresholds
Device API	DDI — HTTP polling, no persistent connection required
Multi-tenancy	Built-in tenant isolation
Maturity	Eclipse Foundation project, automotive-grade heritage

What hawkBit Delivers¶

hawkBit treats all artifacts as opaque binary blobs. It does not interpret file contents — the device client decides how to handle each artifact type.

Software Module Types¶

Type Key	Artifact Content	Device Handler
`os`	Operating system images	System update agent
`firmware`	Firmware binaries (MCU, sensors)	Firmware flasher
`application`	Application packages	App installer
`mapdata`	Navigation maps, floor plans	Map loader (from Equator)
`mlmodel`	ML/AI model weights	ML runtime (model hot-swap)
`config`	Configuration files, policy bundles	Config manager
`certificate`	TLS certs, device identity certs	Certificate store

Custom Software Module Types are defined via the hawkBit Management API. A Distribution Set bundles multiple module types into a single deployable unit — for example, a firmware update + new navigation map + updated ML model can be rolled out together.

Distribution Set Example¶

Distribution Set: "AMR v2.5.0 + Map Update Q1"
├── Software Module: firmware v2.5.0 (type: firmware)
│   └── artifact: amr-firmware-2.5.0.bin
├── 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

Rollout Management¶

hawkBit supports phased rollouts with safety controls:

Rollout: "Firmware v2.5.0 to Building A AMRs"
├── Phase 1: 10% of targets (canary group)
│   └── Success threshold: 100% (all must succeed before proceeding)
├── Phase 2: 50% of targets
│   └── Success threshold: 90%
└── Phase 3: remaining targets
    └── Automatic rollback trigger: > 5% failure rate

Rollout Feature	Description
Target filtering	Select devices by type, tenant, tags, or custom attributes
Phased groups	Sequential deployment groups with configurable sizes
Success thresholds	Minimum success rate before proceeding to next phase
Auto-pause	Stop rollout if failure rate exceeds threshold
Forced updates	Skip confirmation for critical security patches
Maintenance windows	Schedule rollouts during off-peak hours

DDI API (Device Domain Interface)¶

The DDI API is hawkBit’s device-facing interface. It uses HTTP polling — the device periodically checks for pending updates. In FlexGalaxy.AI, devices poll OTAForge’s proxied DDI endpoint, not hawkBit directly.

Polling Flow (via OTAForge DDI Proxy)¶

Device (Hara)               OTAForge DDI Proxy           hawkBit
     │                            │                         │
     │  GET /ddi/v1/{tenant}/     │                         │
     │  controller/{id}           │                         │
     │───────────────────────────►│  validate tenant        │
     │                            │  + audit log            │
     │                            │                         │
     │                            │  GET /controller/v1/... │
     │                            │────────────────────────►│
     │                            │                         │
     │                            │◄────────────────────────│
     │  200: {deployment actions} │                         │
     │◄───────────────────────────│                         │
     │                            │                         │
     │  (download artifacts,      │                         │
     │   report feedback          │                         │
     │   — all via OTAForge)      │                         │
     │                            │                         │

Polling Interval¶

The hawkBit server controls the polling interval via the config.polling.sleep field in the controller base response. Typical values:

Environment	Interval	Rationale
Production	5–15 min	Balance between responsiveness and server load
During rollout	1–2 min	Faster feedback during active deployments
Development	30 sec	Quick iteration during testing

Eclipse Hara — Device Client¶

Hara is a JVM/Kotlin library that implements the DDI polling API. It runs on the device and handles the update lifecycle.

Hara Capabilities¶

Feature	Description
DDI polling	Configurable interval, server-directed override
Artifact download	Resumable downloads with hash verification (MD5, SHA1, SHA256)
Installation callback	Delegates actual installation to device-specific handlers
Feedback reporting	Reports progress, success, or failure back to hawkBit
Configuration management	Applies configuration updates from hawkBit

Hara Integration Pattern¶

// Hara configuration on device
// Points to OTAForge DDI proxy, NOT hawkBit directly
val client = HaraClient.newInstance(
    tenant = "building-a",
    controllerId = "amr-001",
    serverUrl = "https://api.flexgalaxy.com/ddi",
    gatewayToken = "<device-specific-token>"
)

// Register artifact handlers per module type
client.onDeployment { action ->
    action.modules.forEach { module ->
        when (module.type) {
            "firmware"    -> firmwareUpdater.apply(module.artifacts)
            "mapdata"     -> mapLoader.load(module.artifacts)
            "mlmodel"     -> mlRuntime.hotSwap(module.artifacts)
            "config"      -> configManager.apply(module.artifacts)
            "certificate" -> certStore.install(module.artifacts)
        }
    }
    action.reportSuccess()
}

Hara Limitations¶

Limitation	Impact	Mitigation
JVM-only	Cannot run on MCU-based sensors	Use hawkBit’s AMQP integration or a lightweight HTTP client
Kotlin dependency	Adds ~2 MB to device image	Acceptable for robot-class devices (AMRs, cleaning robots)
No native C/Rust port	Constrained devices need alternative	Community C client or custom DDI implementation

For FlexGalaxy.AI, Hara is suitable for the primary device types (AMRs, cleaning robots, PDAs) which are JVM-capable. Constrained sensors that need OTA updates would use a lightweight DDI HTTP client.

Integration with ThingsBoard¶

hawkBit and ThingsBoard manage different aspects of the same devices:

Aspect	ThingsBoard	hawkBit
Device identity	Device ID + credentials	Controller ID + security token
Connectivity	MQTT (persistent)	HTTP polling (periodic)
Data flow	Telemetry (device → cloud)	Artifacts (cloud → device)
State	Current device state	Update deployment state

Synchronization¶

A thin Integration Service keeps device identities in sync:

Provisioning Service
     │
     ├──► ThingsBoard: create device (device ID, credentials)
     │
     └──► hawkBit: create target (controller ID, security token)
            │
            └── controller ID = ThingsBoard device ID (same identifier)

When a device is provisioned, both ThingsBoard and hawkBit receive the same device identifier. This allows correlating telemetry data with update status — for example, monitoring battery level (ThingsBoard) before triggering a firmware update (hawkBit).

Admin Interface¶

hawkBit’s built-in Management UI is deprecated with no official replacement. For FlexGalaxy.AI, all OTA management goes through OTAForge, which wraps hawkBit’s Management API with account scoping, CI/CD access keys, and a custom administration UI.

OTAForge Operator UI — artifact management, rollout campaigns, fleet update status
OTAForge Distributor Portal — web-based artifact publishing for external distributors
DeviceAdmin — read-only OTA status view for device owners

OTAForge uses hawkBit’s Management API internally:

Operation	Endpoint	Description
`POST /rest/v1/distributionsets`	Create a distribution set
`POST /rest/v1/softwaremodules`	Upload software modules and artifacts
`POST /rest/v1/rolloutgroups`	Create a rollout campaign
`GET /rest/v1/targets/{id}/actions`	Get deployment history for a target
`GET /rest/v1/rolloutgroups/{id}/status`	Monitor rollout progress

Deployment¶

Component	Purpose
hawkBit Update Server	Core API, DDI endpoint, management API
MariaDB / MySQL	Distribution sets, targets, rollout state
RabbitMQ (optional)	Event-driven target notifications

hawkBit runs as a single Spring Boot application on EKS. For high availability, multiple replicas can share the same database. Artifact storage uses S3-compatible object storage.

Boundaries¶

hawkBit handles:

Software and artifact distribution to edge devices
Phased rollouts with safety thresholds
Artifact versioning and distribution set management
Device update lifecycle (pending, downloading, installed, failed)
Any file type delivery (firmware, maps, configs, ML models, certs)

hawkBit does not handle:

Device connectivity for telemetry → ThingsBoard (via DeviceAdmin)
Real-time device monitoring → ThingsBoard (via DeviceAdmin alerts)
Device provisioning workflow → DeviceAdmin (via Provisioning Service)
Policy-driven rollout automation → OTAForge (polls DeviceAdmin, evaluates policies)
Analytics on telemetry data → StreamPipes (via ThingIO)
Account-scoped access control → OTAForge