DeviceAdmin¶

Plane: Data Plane

Purpose¶

Device enrollment, lifecycle management, alert monitoring, and OTA status visibility. DeviceAdmin is the platform’s unified device management interface for developers and operators. It wraps ThingsBoard for device connectivity and telemetry, and reads from hawkBit for OTA update status — without exposing either system’s native UI directly.

DeviceAdmin answers three questions for device owners:

What devices do I have? — enrollment, metadata, fleet overview
Are my devices healthy? — alerts, connectivity status, battery levels
Are my devices up to date? — firmware version, pending updates, upgrade eligibility

Responsibilities¶

Enroll and deregister devices (delegates to Provisioning Service)
Maintain device metadata (type, model, firmware version, capabilities)
Track device lease status and ownership chain
Transfer devices between accounts (delegates to Provisioning Service)
Issue and rotate device credentials (delegates to Provisioning Service)
Surface ThingsBoard alerts (battery low, offline, threshold violations)
Provide OTA status visibility (current version, pending updates, upgrade history)
Expose device catalog for other services to query

What DeviceAdmin Is Not¶

DeviceAdmin deliberately does not provide:

Complex data processing or analytics — that is ThingIO
Dashboard visualization — that is ThingIO
OTA artifact management or rollout administration — that is OTAForge
Direct ThingsBoard UI access — ThingsBoard dashboards are never exposed to users

Key Entities¶

Entity	Description
Device	A registered IoT device with a unique platform ID
DeviceType	Classification (AMR, cleaning robot, MHE, PDA, sensor)
Firmware	Version tracking and update eligibility
Lease	Ownership and lease chain (owner → operator → site)
Alert	A device health event surfaced from ThingsBoard (battery, connectivity, threshold)
UpdateStatus	OTA update state for a device (current version, pending, history)

Relationship with Provisioning Service¶

DeviceAdmin is the single entry point for device management. When devices are enrolled, transferred, or decommissioned, DeviceAdmin delegates the cross-system orchestration to the Provisioning Service — a separate microservice that coordinates ThingsBoard, hawkBit, and DotID.

Developer / Operator
     │
     │  POST /devices/v1/enroll
     │  (device identity + metadata)
     │
     ▼
┌──────────────┐           ┌──────────────────────┐
│  DeviceAdmin  │──────────►│  Provisioning Service │
│               │  delegate │  /provisioning/v1/    │
│  Device mgmt  │◄──────────│                      │
│  Alerts       │  result   │  ├── ThingsBoard      │
│  OTA status   │           │  ├── hawkBit          │
└──────────────┘           │  └── DotID            │
                            └──────────────────────┘

Developers never interact with ThingsBoard, hawkBit, or the Provisioning Service directly. DeviceAdmin is the only device management API they see.

The Provisioning Service handles multiple provisioning scenarios (factory, assembly, field) as described in the Device Provisioning pattern. DeviceAdmin exposes a simplified enrollment API that maps to the appropriate scenario.

Alert Monitoring¶

DeviceAdmin surfaces basic device health alerts from ThingsBoard’s rule engine. These are operational alerts that device owners need to act on:

Alert Type	Source	Example
Battery low	ThingsBoard rule engine	“AMR-001 battery at 12%”
Device offline	ThingsBoard connectivity	“Sensor-042 disconnected for 15 min”
Threshold violation	ThingsBoard rule engine	“Temperature sensor-007 above 45°C”
Enrollment failure	Provisioning Service	“Device rejected: unknown manufacturer CA”

For complex pattern detection (battery degradation trends, zone congestion, multi-device correlation), see ThingIO.

OTA Status Visibility¶

DeviceAdmin provides a read-only view of OTA update status by querying hawkBit’s Management API. Device owners can see:

Information	Source	Description
Current version	hawkBit target attributes	What software/firmware is installed
Pending updates	hawkBit deployment actions	Updates waiting to be downloaded/installed
Update history	hawkBit action status	Past deployments with success/failure status
Upgrade eligibility	DeviceAdmin logic	Whether the device should be upgraded (based on type, lease, policy)

DeviceAdmin does not create artifacts, distribution sets, or rollouts — that is OTAForge’s responsibility. DeviceAdmin is the consumer-facing view (“is my device up to date?”), while OTAForge is the publisher-facing admin (“push this firmware to these targets”).

API Surface¶

Device Management¶

Operation	Description
`POST /devices/enroll`	Enroll a new device (triggers provisioning)
`GET /devices/{id}`	Get device details and current status
`GET /devices?type=&account=`	List devices with filtering
`PATCH /devices/{id}`	Update device metadata
`DELETE /devices/{id}`	Decommission a device (triggers deprovisioning)
`POST /devices/{id}/credentials/rotate`	Rotate device credentials across all systems
`POST /devices/{id}/transfer`	Transfer a device to another account
`POST /devices/{id}/suspend`	Suspend a device
`POST /devices/{id}/reactivate`	Reactivate a suspended device

Alerts¶

Operation	Description
`GET /devices/{id}/alerts`	Get active alerts for a device
`GET /alerts?account=&severity=`	List alerts with filtering
`POST /devices/{id}/alerts/{alertId}/acknowledge`	Acknowledge an alert

OTA Status¶

Operation	Description
`GET /devices/{id}/software`	Current software/firmware versions
`GET /devices/{id}/updates`	Pending and historical OTA updates
`GET /devices/{id}/updates/{actionId}`	Detailed update status
`GET /devices/updates?account=&status=`	Fleet-wide update status

Implementation¶

DeviceAdmin is a custom FlexGalaxy service (not an off-the-shelf component):

Aspect	Technology
Framework	Java 21 (Spring Boot)
Database	PostgreSQL (device metadata, lease chain, alert state)
ThingsBoard integration	REST API (device CRUD, alert subscription)
hawkBit integration	REST API (read-only: target status, deployment actions)
DotID integration	Keycloak Admin API (M2M client lifecycle)

Dependencies¶

Service	Relationship
ThingsBoard	Device registry, connectivity, alerts (via REST API)
hawkBit	OTA update status (read-only via Management API)
DotID	Authenticates API calls; issues device M2M credentials
Org Service	Resolves account/tenant context for device ownership
Provisioning Service	Orchestrates cross-system device enrollment, transfer, and decommission

Consumed By¶

Consumer	Usage
ThingIO	Resolves device identity for telemetry processing
OTAForge	References device fleet for rollout targeting
Scheduler	Queries device capabilities and availability
Execution Manager	Resolves device capabilities before pushing contracts
Applications	Query and manage their device fleet
Operators	Fleet overview, alert monitoring, OTA status