You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/README.md
+92-18Lines changed: 92 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,43 +3,48 @@
3
3
Eclipse hawkBit™ is a domain independent back-end framework for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP based networking infrastructure.
4
4
5
5
<palign="center">
6
-
<imgsrc="images/hawkBit_overview.png"alt="eclipse foundation logo"width="1200">
hawkBit offers a direct device integration via HTTP or a device management federation API which allows to connect devices with different protocol adapter. Users can make use of the graphical user interface and other service can interact with hawkBit through the RESTful management API.
13
+
Eclipse hawkBit™ provides three APIs, each designed to support specific integration requirements for device connectivity, device management, and external service federation.
14
14
15
-
---
15
+
### Management API
16
16
17
-
## Rollout
17
+
The Management API is a RESTful interface that allows Create, Read, Update, and Delete (CRUD) operations for provisioning targets (e.g., devices) and repository content (e.g., software). Using the Management API, you can manage and monitor software update processes. It supports JSON payloads with Hypermedia and offers filtering, sorting, and pagination capabilities
The following sections provide a high-level overview. For in-depth information, including request flows and examples, see the [Management API documentation](#management-api)
20
20
21
-
<divstyle="flex: 1; padding-right: 20px;">
21
+
### Direct Device Integration (DDI) API
22
22
23
-
hawkBit supports an easy and flexible rollout management which allows you to update a large amount of devices in separated groups.
23
+
The Direct Device Integration (DDI) API is built on HTTP standards and uses a polling-based approach.
24
24
25
-
- Cascading start of the deployment groups based on installation status of the previous group.
26
-
- Emergency shutdown of the rollout in case a group exceeds the defined error threshold.
27
-
- Rollout progress monitoring for the entire rollout and the individual groups.
25
+
Eclipse hawkBit™ exposes RESTful resources that devices consume to retrieve software update tasks, including artifact partial and resume downloads (RFC7233), and to report back status and feedback.
28
26
29
-
</div>
27
+
The DDI API supports ETag-based traffic optimization, allowing devices to efficiently check for updates without unnecessary data transfer.
30
28
31
-
<divstyle="flex: 1;">
29
+
Learn more in the [DDI API documentation](direct-device-integration-api.md)
The Device Management Federation (DMF) API enables indirect device integration via a device management service into hawkBit. It is a message-based, asynchronous API optimized for high-throughput cloud service-to-service communication. The DMF API leverages RabbitMQ messaging and provides strong tenant isolation through dedicated AMQP virtual hosts per tenant.
36
34
37
-
</div>
35
+
For a detailed description and usage examples, see the [Device Management Federation (DMF) API documentation](device-management-federation-api.md)
38
36
39
37
---
40
38
41
-
## Package Model
39
+
## Device Repository
42
40
41
+
-**Device State Storage**: The Device Repository manages connected devices (targets) and their state. It allows you to retrieve device details and attributes, maintain descriptions, metadata, tags, and track assigned and installed software versions, including software update status.
42
+
-**Tagging**: hawkBit™ allows creating and managing arbitrary tags that can be assigned to devices. These tags become part of the target metadata and can be used as a simple, flexible way to filter and group devices in both the UI and API
43
+
-**Filtering and Grouping**: Advanced device management is enabled through Target Filters, which group devices based on query criteria. These filters not only simplify device organization but also support automatic update assignments - for example, newly registered devices that match a filter are automatically assigned the corresponding software update.
44
+
45
+
## Software Repository
46
+
#### Distribution Sets and Software Modules
47
+
The software repository organizes and manages software updates. A software update, called a Distribution Set, is composed of one or more Software Modules, each containing multiple artifacts.
Metadata can be assigned to both Software Modules and Distribution Sets.
77
+
78
+
#### Tagging and Filtering
79
+
hawkBit™ lets you assign user‑defined tags to Distribution Sets and then filter Distribution Sets using those tags, making it easier to organize and locate updates based on custom criteria.
80
+
81
+
#### Locking After Assignment
82
+
83
+
To ensure consistency and prevent unintended changes, hawkBit™ supports locking of Distribution Sets after they have been assigned to a target (device or group). When a distribution set is locked, all its software modules are automatically locked, and they cannot be modified until they are unlocked. This provides stability for ongoing deployments, ensuring that the software being rolled out remains consistent throughout the deployment process.
84
+
85
+
86
+
#### Required Migration Step Flag
87
+
88
+
When creating a Distribution Set, you can set a flag to indicate that applying this update requires a migration step on the device. This is useful for ensuring data migration, configuration changes, or other necessary steps are performed during the update process to ensure a successful transition.
89
+
90
+
## Artifact Content Delivery
91
+
92
+
The Artifact Content Delivery component manages the storage and delivery of software artifacts to devices. It supports partial and resumable downloads using RFC7233 range requests, allowing devices to efficiently retrieve large files even in unreliable network conditions. The content management is accessible via RESTful APIs and the UI, with authorization based on software assignment to ensure that devices can only download artifacts they are authorized for.
93
+
94
+
## Rollout Management
95
+
96
+
Rollout Management in Eclipse hawkBit™ is a core feature designed to orchestrate and control the deployment of software updates to large fleets of devices in a safe, flexible, and automated way.
97
+
98
+
It enables group-based deployments with configurable success and error thresholds. Groups can cascade based on the status of previous groups.
The traditional “big bang” approach updates all devices at once, creating a sharp load spike and risking infrastructure overload, while hawkBit’s phased rollout spreads updates across smaller groups over time, smoothing load and maintaining system stability.
Rollouts can be started, paused, resumed, stopped, or retried, with real-time monitoring and emergency stop features.
107
+
Devices can be added dynamically, and detailed status tracking is available for each rollout stage.
108
+
109
+
To explore software update in greater detail, visit [Rollout Management documentation](rollout-management.md)
110
+
111
+
## Reporting and Monitoring
112
+
113
+
Eclipse hawkBit™ provides real-time visibility and historical insight into how software updates are rolled out, executed, and completed across large device fleets. Reporting and monitoring are tightly coupled to its rollout and device management model.
114
+
115
+
#### Monitoring Features
116
+
-**Rollout Progress Tracking**: Monitor deployment stages, group completion, and cascading group triggers
-**Action History**: Monitor the status of every device via its action history. This action history makes transparent which action happened at which particular time and with its result.
119
+
-**Success/Error Thresholds**: Configure and monitor threshold violations that can pause or stop rollouts
120
+
-**Device Connectivity**: Track device polling activity, last seen timestamps, and overdue detection
121
+
-**Download Progress**: Monitor artifact download status and completion rates
122
+
123
+
#### Reporting Channels
124
+
-**Management API**: RESTful endpoints for querying device status, action history, and rollout metrics
125
+
-**Event System**: Publish events for entity changes, action status updates, target polling, and download progress
126
+
-**RabbitMQ Events**: Remote events for distributed monitoring and integration with external tools
127
+
128
+
## Authentication & Security
129
+
130
+
Eclipse hawkBit™ provides comprehensive authentication and security features to protect devices, management interfaces, and data. All communication is protected using TLS/HTTPS, and update delivery is restricted to authenticated devices. hawkBit also records deployment and action history for traceability and auditing. While it keeps built-in security mechanisms focused and lightweight, hawkBit is designed to integrate easily with external identity, logging, and security systems for production use.
131
+
132
+
If you’d like to explore security controls in more detail, check out the [Authentication](authentication.md) and [Authorization](authorization.md) documentation.
0 commit comments