diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 8a14accca..835cdcb3e 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -6,7 +6,8 @@
- [Architecture](architecture.md)
- Guides
- - [Run hawkBit](run-hawkbit.md)
+ - [Base Setup](base-setup.md)
+ - [SDK](hawkbit-sdk.md)
- [Feign Client](feign-client.md)
- [Clustering](clustering.md)
diff --git a/docs/run-hawkbit.md b/docs/base-setup.md
similarity index 50%
rename from docs/run-hawkbit.md
rename to docs/base-setup.md
index ff1be5bea..56c9fd7ef 100644
--- a/docs/run-hawkbit.md
+++ b/docs/base-setup.md
@@ -1,7 +1,7 @@
-# Run hawkBit
+# Base hawkBit setup
-In this guide we describe how to run a full featured hawkBit setup based on a production ready infrastructure.
-It is based on the hawkBit example modules and update server.
+In this guide we describe how to setup a full featured hawkBit based on a production ready infrastructure.
+It is based on the hawkBit update server.
The update server can in fact be run stand alone. However, only with an embedded H2, no Device Management Federation API and no artifact storage.
@@ -13,23 +13,15 @@ This guide describes a target architecture that is more like one that you will e
- [hawkBit](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server) Update Server
- [MariaDB](https://mariadb.org/) for the repository
-- [RabbitMQ](https://www.rabbitmq.com/) for DMF communication
-
-For testing and demonstration purposes we will also use:
-
-- hawkBit [Device Simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator)
-- hawkBit [Management API example client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client)
+- [RabbitMQ](https://www.rabbitmq.com/) for DMF communication
---
### Prerequisites
- You have a working hawkBit [core build](https://github.com/eclipse-hawkbit/hawkbit).
-- You have a working hawkBit [examples build](https://github.com/eclipse-hawkbit/hawkbit-examples).
-- Adapt hawkBit Update Server and Device Simulator to your environment.
-As mentioned you can create your own application with hawkBit inside or adapt the existing example app.
-The second option will be shown here.
+As mentioned you can create your own application with hawkBit inside.
---
@@ -53,7 +45,6 @@ spring.datasource.driverClassName: org.mariadb.jdbc.Driver
### Configure RabbitMQ (optional)
-For update server and device simulator.
Defaults are already provided for a standard Rabbit installation. Otherwise configure the following in `application.properties` of the two services:
```properties
@@ -66,37 +57,11 @@ spring.rabbitmq.port: 5672
---
-### Adapt hostname of example scenario [creation script](https://github.com/eclipse-hawkbit/hawkbit-examples/blob/master/hawkbit-example-mgmt-simulator/src/main/resources/application.properties)
-
-Should only be necessary if your system does not run on `localhost` or uses a different port than the example app.
-
-Adapt `application.properties` in this case:
-
-```properties
-hawkbit.url: localhost:8080
-```
-
-or provide the parameter on command line:
-
-```properties
-hawkbit-example-mgmt-simulator-##VERSION##.jar --hawkbit.url=YOUR_HOST:PORT
-```
-
----
-
### Compile & Run
-#### Compile & Run your “production ready” app
+#### Compile & Run your app
See [update server](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server)
-#### Compile & Run example scenario creation script (optional)
-This has to be done before the device simulator is started. hawkBit creates the mandatory tenant metadata with first login into either Management API (which is done by this client).
-
-However, this is not done by DMF which is in fact used by the device simulator, i.e. without calling Management API first hawkBit would drop all DMF messages as the tenant is unknown.
-
-#### Compile & Run device simulator (optional)
-See [device simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator)
-
---
Enjoy hawkBit with a real database, artifact storage and all interfaces available.
diff --git a/docs/clustering.md b/docs/clustering.md
index e5bcf7c3b..fe6d1b9fb 100644
--- a/docs/clustering.md
+++ b/docs/clustering.md
@@ -7,25 +7,65 @@ concepts and how to setup your own cluster. You can find additional information
### Big picture
- 
+ 
---
### Events
-Event communication between nodes is based on [Spring Cloud Bus](https://cloud.spring.io/spring-cloud-bus/) and [Spring Cloud Stream](http://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/).
-There are different binder implementations available. The hawkBit Update Server uses the **RabbitMQ binder**.
-Every node gets its own queue to receive cluster events, the default payload is JSON. If an event is thrown locally at one node, it will be automatically delivered to all other available nodes via the Spring Cloud Bus’s topic exchange.
+Event communication between nodes is based on [Spring Cloud Stream](http://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/).
+There are different [binder implementations](https://docs.spring.io/spring-cloud-stream/docs/current/reference/html/#_binders) available. The hawkbit Update Server uses **RabbitMQ binder**.
+Every node gets its own queue to receive cluster events, the default payload is JSON.
-Via the `ServiceMatcher` you can check whether an event happened locally at one node or on a different node:
-```java
-serviceMatcher.isFromSelf(event)
+#### Event Channel Types in Spring Cloud Stream
+
+Remote events in hawkBit are distributed through two distinct types of channels:
+
+##### Fanout Event Channel
+ - Every service instance listening to fanoutEventChannel receives a copy of every message, regardless of instance count.
+ - Common for events that should be processed by each consumer independently
+ - In-memory cache updates
+ - Internal state propagation
+ - Logging or auditing
+ - Not recommended for scenarios where only one consumer should process an event (see serviceEventChannel for that).
+
+**Note**: Every instance bound to this channel will get its own copy of the message.
+
+##### Service Event Channel
+The `serviceEventChannel` is used to ensure exclusive consumption of events across service instances. Only one instance per consumer group receives and processes each message, which is critical for non-idempotent or resource-sensitive operations.
+ - Only one instance in a consumer group receives each message.
+ - Ideal for external integrations, third-party API calls, or any task that must not be duplicated.
+ - Load-balanced across instances within the same group.
+
+##### Optional Protostuff for Spring cloud stream
+
+The micro-service instances are configured to communicate via Spring Cloud Stream. Optionally, you could use [Protostuff](https://github.com/protostuff/protostuff) based message payload serialization for improved performance.
+
+**Note:** If Protostuff is enabled it shall be enabled on all microservices!
+
+Add/Uncomment to/in your `application.properties` :
+
+```properties
+spring.cloud.stream.default.content-type=application/binary+protostuff
+```
+
+Add to your `pom.xml` :
+
+```xml
+
+ io.protostuff
+ protostuff-core
+
+
+ io.protostuff
+ protostuff-runtime
+
```
---
diff --git a/docs/feign-client.md b/docs/feign-client.md
index 4975320b3..536a2ab98 100644
--- a/docs/feign-client.md
+++ b/docs/feign-client.md
@@ -38,32 +38,3 @@ public class CreateStartedRolloutExample {
}
}
```
-
-Example projects:
-- [hawkbit-example-mgmt-feign-client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client)
-- [hawkbit-example-ddi-feign-client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-ddi-feign-client)
-- [hawkbit-example-mgmt-simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator)
-
----
-
-### Feign Client Configuration
-
-At [`hawkbit-example-core-feign-client`](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-core-feign-client) there is a Spring configuration to auto configure some beans, which can be reused for your own Feign client:
-
-```java
-@Configuration
-@ConditionalOnClass(Feign.class)
-@Import(FeignClientsConfiguration.class)
-public class FeignClientConfiguration {
-
- @Bean
- public ApplicationJsonRequestHeaderInterceptor jsonHeaderInterceptor() {
- return new ApplicationJsonRequestHeaderInterceptor();
- }
-
- @Bean
- public Contract feignContract() {
- return new IgnoreMultipleConsumersProducersSpringMvcContract();
- }
-}
-```
diff --git a/docs/graphics-source/clustering_overview.drawio b/docs/graphics-source/clustering_overview.drawio
new file mode 100644
index 000000000..157d6947b
--- /dev/null
+++ b/docs/graphics-source/clustering_overview.drawio
@@ -0,0 +1,161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/graphics-source/eventing-within-cluster.drawio b/docs/graphics-source/eventing-within-cluster.drawio
new file mode 100644
index 000000000..cff404e3a
--- /dev/null
+++ b/docs/graphics-source/eventing-within-cluster.drawio
@@ -0,0 +1,104 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/hawkbit-sdk.md b/docs/hawkbit-sdk.md
new file mode 100644
index 000000000..e09907a94
--- /dev/null
+++ b/docs/hawkbit-sdk.md
@@ -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
+
+ org.eclipse.hawkbit
+ hawkbit-sdk-device
+
+
+ org.eclipse.hawkbit
+ hawkbit-sdk-dmf
+
+
+ org.eclipse.hawkbit
+ hawkbit-sdk-mgmt
+
+```
+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 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.
+
+
diff --git a/docs/images/clustering_overview.png b/docs/images/clustering_overview.png
new file mode 100644
index 000000000..782deee1d
Binary files /dev/null and b/docs/images/clustering_overview.png differ
diff --git a/docs/images/eventing-within-cluster.png b/docs/images/eventing-within-cluster.png
index 1baa538d1..1c3867424 100644
Binary files a/docs/images/eventing-within-cluster.png and b/docs/images/eventing-within-cluster.png differ
diff --git a/docs/images/overall_cluster.png b/docs/images/overall_cluster.png
deleted file mode 100644
index b18b8ee21..000000000
Binary files a/docs/images/overall_cluster.png and /dev/null differ