lingwei.kong/hawkbit
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

Fix Guides in hawkBit Documentation. (#2826)

Browse Source 
* Fix Guides in hawkBit Documentation.

Signed-off-by: strailov <Stanislav.Trailov@bosch.io>

* small fixes to clustering page

Signed-off-by: strailov <Stanislav.Trailov@bosch.io>

---------

Signed-off-by: strailov <Stanislav.Trailov@bosch.io>
This commit is contained in:
Stanislav Trailov
2025-11-26 11:49:50 +02:00
committed by GitHub
parent a7b851778e
commit 40e92be32b
10 changed files with 428 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/hawkbit-sdk.md Normal file
View File

@@ -0,0 +1,108 @@
# hawkBit SDK
In this guide we describe what is hawkBit SDK, how can it be configured and used.
---
### Overview
hawkBit provides a Client-Side Software Development Kit which allows you to:
- Connect a device or a Gateway to hawkBit
- Fetch assignments / update campaigns
- Download firmware or software packages
- Report progress and status
- Interact with Management, DDI, and DMF APIs through one client
[hawkBit SDK](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-sdk) has support for DDI, DMF and Mgmt APIs. In other words it allows you to simulate (only simulate?) the behaviour of a DDI/DMF gateway/target or interact with hawkBit through MgmtAPI.
---
### Configuration
Add the desired modules :
```xml
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-sdk-device</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-sdk-dmf</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-sdk-mgmt</artifactId>
</dependency>
```
Of course if you will not be using DMF there is no need to add `hawkbit-sdk-dmf` or vise versa for DDI case.
The default configuration comes already built-in with the SDK.
But it can be changed in ```application.properties``` of your service/application:
```properties
hawkbit.tenant.tenant-id=DEFAULT
hawkbit.tenant.username=user
hawkbit.tenant.password=pass
hawkbit.tenant.gateway-token=gateway_token
# DMF case
hawkbit.tenant.dmf.username=dmf_user
hawkbit.tenant.dmf.password=dmf_password
hawkbit.tenant.dmf.virtual-host=dmf_vhost
```
And also you can configure the endpoints of HawkBit and DDI (if used separately as microservices) :
```properties
# Hawkbit Server config
hawkbit.server.mgmt-url=http://localhost:8080
hawkbit.server.ddi-url=http://localhost:8085
```
Many other configuration options are possible, you can check [HawkbitServer](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/HawkbitServer.java) and [Tenant](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/Tenant.java) classes for more possible configuration properties.
---
### Example applications
If you have applied the configurations from the steps above then you can start building your application. Since we have defined `hawkbit.server` and `hawkbit.tenant` properties then you can add the `HawkbitClient` bean into your application :
```java
@Bean
HawkbitClient hawkbitClient(final HawkbitServer hawkBitServer, final Encoder encoder, final Decoder decoder, final Contract contract) {
return new HawkbitClient(hawkBitServer, encoder, decoder, contract);
}
```
Then you can define the authentication setup helper, which offers helper methods for setting up your authentication method(s) :
```java
@Bean
AuthenticationSetupHelper mgmtApi(final Tenant tenant, final HawkbitClient hawkbitClient) {
return new AuthenticationSetupHelper(tenant, hawkbitClient);
}
```
And finally you can define a Bean instance of `DdiTenant` which offers you interaction with DDI API :
```java
@Bean
DdiTenant ddiTenant(final Tenant defaultTenant, final HawkbitClient hawkbitClient) {
return new DdiTenant(defaultTenant, hawkbitClient);
}
```
Hawkbit Mgmt API can be now also reached via `HawkbitClient` instance :
```java
final MgmtTargetRestApi mgmtTargetRestApi = hawkbitClient.mgmtService(MgmtTargetRestApi.class, tenant);
// directly use MGMT REST API methods
PagedList<MgmtTarget> pagedList = mgmtTargetRestApi.getTargets("controllerid==*",0, 100,
null).getBody();
```
You can check out the example applications located in [hawkbit-sdk-demo](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-sdk/hawkbit-sdk-demo) module.
There you can find example usage for [DDI](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/device/DeviceApp.java) and [DMF](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/dmf/DmfApp.java) via the hawkbit SDK.