Eclipse hawkBit + Hara

レイヤー: IoTレイヤー

目的

Eclipse hawkBitはFlexGalaxy.AIのOTA（Over-The-Air）アップデートおよびアーティファクト配信エンジンであり、マルチテナントアーティファクト管理、CI/CD統合、およびロールアウト管理のためにOTAForgeによってラップされています。hawkBitはソフトウェア、ファームウェア、およびその他のファイルをエッジデバイスに配布する管理を行います — 段階的ロールアウト、安全閾値、およびキャンペーン管理を備えています。

Eclipse HaraはhawkBitのDDI（Device Domain Interface）APIを実装するデバイス側のクライアントライブラリであり、JVMベースのデバイスでのアーティファクトのダウンロード、検証、およびインストールを処理します。

hawkBitを選定した理由

基準	hawkBit
ライセンス	Eclipse Public License 2.0
アーティファクトタイプ	ドメイン非依存 — 任意のバイナリブロブ
ロールアウト制御	設定可能な失敗閾値を備えた段階的ロールアウト
デバイスAPI	DDI — HTTPポーリング、永続的な接続は不要
マルチテナンシー	組み込みのテナント分離
成熟度	Eclipse Foundationプロジェクト、自動車グレードの実績

hawkBitが提供する機能

hawkBitはすべてのアーティファクトを不透明なバイナリブロブとして扱います。ファイルの内容を解釈せず、各アーティファクトタイプの処理方法はデバイスクライアントが決定します。

ソフトウェアモジュールタイプ

タイプキー	アーティファクトの内容	デバイスハンドラー
os	オペレーティングシステムイメージ	システムアップデートエージェント
firmware	ファームウェアバイナリ（MCU、センサー）	ファームウェアフラッシャー
application	アプリケーションパッケージ	アプリインストーラー
mapdata	ナビゲーションマップ、フロアプラン	マップローダー（Equator経由）
mlmodel	ML/AIモデルの重み	MLランタイム（モデルホットスワップ）
config	設定ファイル、ポリシーバンドル	設定マネージャー
certificate	TLS証明書、デバイスID証明書	証明書ストア

カスタムソフトウェアモジュールタイプはhawkBit Management APIを通じて定義されます。ディストリビューションセットは複数のモジュールタイプを単一のデプロイ可能なユニットにバンドルします — 例えば、ファームウェアアップデート + 新しいナビゲーションマップ + 更新されたMLモデルをまとめてロールアウトできます。

ディストリビューションセットの例

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

ロールアウト管理

hawkBitは安全制御付きの段階的ロールアウトをサポートします：

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

ロールアウト機能	説明
ターゲットフィルタリング	タイプ、テナント、タグ、またはカスタム属性によるデバイスの選択
段階的グループ	設定可能なサイズの順次デプロイメントグループ
成功閾値	次のフェーズに進む前の最低成功率
自動一時停止	失敗率が閾値を超えた場合にロールアウトを停止
強制アップデート	重要なセキュリティパッチの確認をスキップ
メンテナンスウィンドウ	オフピーク時間帯にロールアウトをスケジュール

DDI API（Device Domain Interface）

DDI APIはhawkBitのデバイス向けインターフェースです。HTTPポーリングを使用し、デバイスが定期的に保留中のアップデートを確認します。FlexGalaxy.AIでは、デバイスはhawkBitに直接ではなく、OTAForgeのプロキシされたDDIエンドポイントをポーリングします。

ポーリングフロー（OTAForge DDIプロキシ経由）

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)      │                         │
     │                            │                         │

ポーリング間隔

hawkBitサーバーは、コントローラーベースレスポンスのconfig.polling.sleepフィールドを通じてポーリング間隔を制御します。一般的な値：

環境	間隔	根拠
本番環境	5–15分	応答性とサーバー負荷のバランス
ロールアウト中	1–2分	アクティブなデプロイメント中のより迅速なフィードバック
開発環境	30秒	テスト中の迅速な反復

Eclipse Hara — デバイスクライアント

HaraはDDIポーリングAPIを実装するJVM/Kotlinライブラリです。デバイス上で動作し、アップデートのライフサイクルを処理します。

Haraの機能

機能	説明
DDIポーリング	設定可能な間隔、サーバー指示によるオーバーライド
アーティファクトのダウンロード	ハッシュ検証（MD5、SHA1、SHA256）付きのレジューム可能なダウンロード
インストールコールバック	実際のインストールをデバイス固有のハンドラーに委譲
フィードバック報告	進捗、成功、または失敗をhawkBitに報告
設定管理	hawkBitからの設定更新を適用

Hara統合パターン

// 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の制限事項

制限事項	影響	緩和策
JVMのみ	MCUベースのセンサーでは実行不可	hawkBitのAMQP統合または軽量HTTPクライアントを使用
Kotlin依存関係	デバイスイメージに約2 MBを追加	ロボットクラスのデバイス（AMR、清掃ロボット）では許容範囲
ネイティブC/Rustポートなし	制約のあるデバイスには代替が必要	コミュニティCクライアントまたはカスタムDDI実装

FlexGalaxy.AIでは、Haraは主要なデバイスタイプ（AMR、清掃ロボット、PDA）に適しており、これらはJVM対応です。OTAアップデートが必要な制約のあるセンサーには軽量DDI HTTPクライアントを使用します。

ThingsBoardとの統合

hawkBitとThingsBoardは同じデバイスの異なる側面を管理します：

側面	ThingsBoard	hawkBit
デバイスID	デバイスID + クレデンシャル	コントローラーID + セキュリティトークン
接続方式	MQTT（永続接続）	HTTPポーリング（定期的）
データフロー	テレメトリ（デバイス → クラウド）	アーティファクト（クラウド → デバイス）
状態	現在のデバイス状態	アップデートデプロイメント状態

同期

軽量な統合サービスがデバイスIDを同期させます：

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

デバイスがプロビジョニングされると、ThingsBoardとhawkBitの両方が同じデバイス識別子を受け取ります。これにより、テレメトリデータとアップデートステータスを関連付けることができます — 例えば、ファームウェアアップデート（hawkBit）をトリガーする前にバッテリーレベル（ThingsBoard）を監視することが可能です。

管理インターフェース

hawkBitの組み込みManagement UIは非推奨であり、公式の後継はありません。FlexGalaxy.AIでは、すべてのOTA管理はOTAForgeを通じて行われます。OTAForgeはhawkBitのManagement APIをアカウントスコーピング、CI/CDアクセスキー、およびカスタム管理UIでラップしています。

• OTAForge Operator UI — アーティファクト管理、ロールアウトキャンペーン、フリートアップデートステータス

• OTAForge Distributor Portal — 外部ディストリビューター向けのWebベースアーティファクト公開

• DeviceAdmin — デバイスオーナー向けの読み取り専用OTAステータスビュー

OTAForgeはhawkBitのManagement APIを内部的に使用します：

操作	エンドポイント	説明
POST /rest/v1/distributionsets	ディストリビューションセットの作成
POST /rest/v1/softwaremodules	ソフトウェアモジュールとアーティファクトのアップロード
POST /rest/v1/rolloutgroups	ロールアウトキャンペーンの作成
GET /rest/v1/targets/{id}/actions	ターゲットのデプロイメント履歴の取得
GET /rest/v1/rolloutgroups/{id}/status	ロールアウト進捗のモニタリング

デプロイメント

コンポーネント	目的
hawkBit Update Server	コアAPI、DDIエンドポイント、管理API
MariaDB / MySQL	ディストリビューションセット、ターゲット、ロールアウト状態
RabbitMQ（オプション）	イベント駆動型ターゲット通知

hawkBitはEKS上で単一のSpring Bootアプリケーションとして稼働します。高可用性のために、複数のレプリカが同じデータベースを共有できます。アーティファクトストレージにはS3互換オブジェクトストレージを使用します。

責務の境界

hawkBitが担当する範囲：

• エッジデバイスへのソフトウェアおよびアーティファクトの配布

• 安全閾値付きの段階的ロールアウト

• アーティファクトのバージョニングとディストリビューションセット管理

• デバイスアップデートライフサイクル（保留中、ダウンロード中、インストール済み、失敗）

• あらゆるファイルタイプの配信（ファームウェア、マップ、設定、MLモデル、証明書）

hawkBitが担当しない範囲：

• テレメトリ用デバイス接続 → ThingsBoard（DeviceAdmin経由）

• リアルタイムデバイス監視 → ThingsBoard（DeviceAdminアラート経由）

• デバイスプロビジョニングワークフロー → DeviceAdmin（プロビジョニングサービス経由）

• ポリシー駆動型ロールアウト自動化 → OTAForge（DeviceAdminをポーリングし、ポリシーを評価）

• テレメトリデータの分析 → StreamPipes（ThingIO経由）

• アカウントスコープのアクセス制御 → OTAForge