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

initial commit of the hawkBit documentation (#343)

Browse Source 
Signed-off-by: Michael Hirsch <michael.hirsch@bosch-si.com>
This commit is contained in:
Michael Hirsch
2016-11-14 15:21:29 +01:00
committed by GitHub
parent d536ec054a
commit 998ebd7c4e
88 changed files with 6422 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
docs/src/main/resources/documentation/interfaces/ddi-api.md Normal file
View File

@@ -0,0 +1,167 @@
---
layout: documentation
title: DDI-API
---
{% include base.html %}
This API is based on HTTP standards and based on a polling mechanism.
The _hawkbit_ [update server](https://github.com/eclipse/hawkbit) provides REST resources which are consumed by the device to retrieve software update tasks.
Note: in DDI the target is identified using a **controllerId**. Controller is used as a term for the actual service/client on the device. That allows users to have in some cases even multiple clients on the same target for different tasks, e.g. Firmware update and App management.
# State Machine Mapping
For historical reasons the DDI has a different state machine and status messages than the [Target State Machine](https://github.com/eclipse/hawkbit/wiki/Target-State-Machine) of the _hawkBit_ update server.
This is kept in order to ensure that _DDI_ stays compatible for devices out there in the field. A future version "2" of _DDI_ might change that. _DDI_ also defines more states than the update server, e.g. multiple DDI states are currently mapped by the _DDI_ implementation to _RUNNING_ state. It is possible that in the future _hawkBit_ will fully leverage these additional states.
The _DDI_ API allows the device to provide the following feedback messages:
DDI `status.execution` type | handling by update server | Mapped ActionStatus type
--------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -----------------------------------------------------
CANCELED | This is send by the target as confirmation of a cancelation request by the update server. | CANCELED
REJECTED | This is send by the target in case an update of a cancelation is rejected, i.e. cannot be fulfilled at this point in time. Note: the target should send a CLOSED->ERROR if it believes it will not be able to proceed the action at all. | WARNING
CLOSED | Target completes the action either with `status.result.finished` SUCCESS or FAILURE as result. Note: DDI defines also a status NONE which will not be interpreted by the update server and handled like SUCCESS. | ERROR (DDI FAILURE) or FINISHED (DDI SUCCESS or NONE)
PROCEEDING | This can be used by the target to inform that it is working on the action. | RUNNING
SCHEDULED | This can be used by the target to inform that it scheduled on the action. | RUNNING
RESUMED | This can be used by the target to inform that it continued to work on the action. | RUNNING
# Resource Overview
The following chapters provide basic examples for the most important resources but we provide also a [detailed resource documentation](https://docs.bosch-iot-rollouts.com/documentation/rest-api/rootcontroller-api-guide.html).
## Base Poll Resource
```
GET /{tenant}/controller/v1/{controllerId}
```
In the answer to the baseUrl polling the backend can send action links. A possible action is a deploy command. The client makes a GET request on the given link:
_Example Response_
```
{
"config": {
"polling": {
"sleep": "00:05:00"
}
},
"_links": {
"deploymentBase": {
"href": "http://localhost:8080/default/controller/v1/example/deploymentBase/1?c=644088541"
},
"configData": {
"href": "http://localhost:8080/default/controller/v1/example/configData"
}
}
}
```
## Deployment Base Resource
```
GET /{tenant}/controller/v1/{controllerId}/deploymentBase/{id}
```
_Example Response_
```
{
"deployment": {
"download": "forced",
"update": "forced",
"chunks": [
{
"part": "os",
"version": "1.0.0",
"name": "Linux",
"artifacts": [
{
"filename": "linux.zip",
"hashes": {
"sha1": "46fc56de883ec027759d8513458fe1010aa7e793",
"md5": "5813e9655bd6871d0c25b8d510fd8605"
},
"size": 52167,
"_links": {
"download": {
"href": "http://localhost:8080/default/controller/v1/example/softwaremodules/1/artifacts/linux.zip"
},
"md5sum": {
"href": "http://localhost:8080/default/controller/v1/example/softwaremodules/1/artifacts/linux.zip.MD5SUM"
}
}
}
]
}
]
},
"id": "1"
}
```
## Deployment Feedback Resource
To every deployment the client can post feedback back to the update-server about the deployment status.
```
POST /{tenant}/controller/v1/{controllerId}/deploymentBase/{id}/feedback
Content-Type: application/json
```
_Example Body Deployment Success_
```
{
"id": 1,
"time": "20140511T121314",
"status": {
"execution": "closed",
"result": {
"finished": "success",
"progress": {}
}
}
}
```
_Example Body Deployment Proceeding_
```
{
"id": "1",
"time": "20140511T121314",
"status": {
"execution": "proceeding",
"result": {
"finished": "none",
"progress": {
"cnt": 2,
"of": 5
}
},
"details": [
"checking hash sums"
]
}
}
```
_Example Body Deployment Error_
```
{
"id": 1,
"time": "20140511T121314",
"status": {
"execution": "rejected",
"result": {
"finished": "failure",
"progress": {}
},
"details": [
"something bad happend"
]
}
}
```

243
docs/src/main/resources/documentation/interfaces/dmf-api.md Normal file
View File

@@ -0,0 +1,243 @@
---
layout: documentation
title: DMF-API
---
{% include base.html %}
Currently bodies of messages are based on JSON. The DMF API provides java classes which allows that the message body can be deserialized at runtime into a java object. Also java classes can be used to serialize java objects into JSON bodies to send a message to _hawkBit_.
## Basics
There are three basic concepts of AMQP:
- Exchanges - what you publish to.
- Queues - what you consume from.
- Bindings - configuration that maps an exchange to a queue.
**Queues** are just a place for receiving messages.
Bindings determine how messages get put in this place
Queues can also be bound to multiple exchanges.
**Exchanges** are just publish messages.
The user decides who can produce on an exchange and who can create bindings on that exchange for delivery to a specific queue.
_hawkBit_ will create all necessary queues, exchanges and bindings for the user, making it easy to get started.
The exchange name for outgoing messages is **dmf.exchange**.
The queue name for incoming messages is **sp_direct_queue**. Unless a ``reply_to`` header is set, _hawkBit_ will reply on the **sp.direct.exchange** which is bound to the **sp_direct_queue**.
The user can set a ``reply_to`` header (see chapter below), to change the default sender exchange.
The following chapter describes the message body, header and properties.
Note: the DMF protocol was intended to be open for other non update use cases by design (e.g. [Eclipse Hono](https://github.com/eclipse/hono). As a result, DMF uses the term **thing** and not **target** but they are actually synonyms in this case.
## Messages sent to _hawkBit_
All messages have to be sent to the exchange **dmf.exchange**.
### Message to register a thing
| Message Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "THING_CREATED " | true
| thingId | The ID of the registered thing | String | true
| sender | Name of the message sender | String | false
| tenant | The tenant this thing belongs to | String | false
| Message Properties | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| content_type | The content type of the payload | String | true
| reply_to | Exchange to reply to. The default is sp.direct.exchange which is bound to the sp_direct_queue | String | false
**Example Header**
| Headers | MessageProperties |
|---------------------------------------|---------------------------------|
| type=THING\_CREATED <br /> tenant=tenant123 <br /> thingId=abc <br /> sender=Lwm2m | content\_type=application/json <br /> reply_to (optional) =sp.connector.replyTo
### Message to send an action status event to _hawkBit_
The Java representation is ActionUpdateStatus:
| Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|--------------
| type | Type of the message | Fixed string "EVENT" | true
| topic | Topic to handle events different | Fixed string "UPDATE_ACTION_STATUS" | true
| tenant | The tenant this thing belongs to | String | false
| Message Properties | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| content_type | The content type of the payload | String | true
Payload Template
```json
{
"actionId": long,
"softwareModuleId": long,
"actionStatus":"String",
"message":["String"]
}
```
Possible actionStatus
| Header | Description |
|-----------------|------------------------------------|
| DOWNLOAD | Device is downloading |
| RETRIEVED | Device management service has retrieved something |
| RUNNING | Update is running |
| FINISHED | Update process finished successful |
| ERROR | Error during update process |
| WARNING | Warning during update process |
| CANCELED | Cancel update process successful |
| CANCEL_REJECTED | Cancel update process has been rejected |
**Example Header and Payload**
| Headers | MessageProperties |
|---------------------------------------|---------------------------------|
| type=EVENT <br /> tenant=tenant123 <br /> topic=UPDATE\_ACTION\_STATUS | content_type=application/json
```json
{
"actionId":137,
"softwareModuleId":17,
"actionStatus":"DOWNLOAD",
"message":["The download has started"]
}
```
### Message to cancel an update task
| Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "Event" | true
| thingId | The ID of the registered thing | String | true
| topic | Topic to handle events different | Fixed string "CANCEL_DOWNLOAD" | true
| tenant | The tenant this thing belongs to | String | false
| Message Properties | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| content_type | The content type of the payload | String | true
**Example Header**
| Headers | MessageProperties |
|---------------------------------------|---------------------------------|
| type=EVENT <br /> tenant=tenant123 <br /> thingId=abc <br /> topic=CANCEL\_DOWNLOAD | content_type=application/json
After this message has been sent, an action status event with either actionStatus=CANCELED or actionStatus=CANCEL_REJECTED has to be returned.
**Example Header and Payload when cancellation is successful**
| Headers | MessageProperties |
|---------------------------------------|---------------------------------|
| type=EVENT <br /> tenant=tenant123 <br /> topic=UPDATE\_ACTION\_STATUS | content_type=application/json
```json
{
"actionId":137,
"softwareModuleId":17,
"actionStatus":"CANCELED",
"message":["The update was canceled."]
}
```
**Example Header and Payload when cancellation was rejected**
| Headers | MessageProperties |
|---------------------------------------|---------------------------------|
| type=EVENT <br /> tenant=tenant123 <br /> topic=UPDATE\_ACTION\_STATUS | content_type=application/json
```json
{
"actionId":137,
"softwareModuleId":17,
"actionStatus":"CANCEL_REJECTED",
"message":["The cancellation was not possible since the target sent an unexpected response."]
}
```
## Messages sent by _hawkBit_
All messages from _hawkBit_ will be sent to the **sp_direct_queue** or the one specified in the ``reply_to`` property.
### Message sent by _hawkBit_ to initialize an update task
| Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "EVENT" | true
| thingId | The ID of the registered thing | String | true
| topic | Topic to handle events different | Fixed string "DOWNLOAD_AND_INSTALL" | true
| tenant | The tenant this thing belongs to | String | false
| Message Properties | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| content_type | The content type of the payload | String | true
The Java representation is DownloadAndUpdateRequest:
Payload Template
```json
{
"actionId": long,
"targetSecurityToken": "String",
"softwareModules":[
{
"moduleId": long,
"moduleType":"String",
"moduleVersion":"String",
"artifacts":[
{
"filename":"String",
"urls":{
"HTTP":"String",
"HTTPS":"String"
},
"hashes":{
"md5":"String",
"sha1":"String"
},
"size":long
}]
}]
}
```
**Example Header and Payload**
| Headers | MessageProperties |
|---------------------------------------|---------------------------------|
| type=EVENT <br /> tenant=tenant123 <br /> thingId=abc <br /> topic=DOWNLOAD\_AND\_INSTALL | content_type=application/json
```json
{
"actionId":137,
"targetSecurityToken":"bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY",
"softwareModules":[
{
"moduleId":7,
"moduleType":"firmware",
"moduleVersion":"7.7.7",
"artifacts":[
{
"filename":"artifact.zip",
"urls":{
"HTTP":"http://download-from-url.com",
"HTTPS":"https://download-from-url.com"
},
"hashes":{
"md5":"md5hash",
"sha1":"sha1hash"
},
"size":512
}]
}]
}
```

29
docs/src/main/resources/documentation/interfaces/interfaces.md Normal file
View File

@@ -0,0 +1,29 @@
---
layout: documentation
title: Interfaces
---
{% include base.html %}
![](../images/interfaces.png){:width="100%"}
# Graphical User Interface
To get started _hawkBit_ offers a [Management UI](https://github.com/eclipse/hawkbit/wiki/Management-UI) that allows operators to manage the repository and trigger provisioning operations.
In addition Eclipse _hawkBit_ offers developers multiple options to integrate.
# Application Integration
The _hawkBit_ [Management API](https://github.com/eclipse/hawkbit/wiki/Management-API) allows applications to manage the repository and trigger provisioning operations. It is in general feature compliant with the _Management UI_. However, small differences may occur here and there. The authentication and authorization structure is identical, i.e. a user can login both at Management API and UI with the same credentials and has the same permissions available.
# Device Integration
For device integration two options exist.
The [Direct Device Integration API](https://github.com/eclipse/hawkbit/wiki/Direct-Device-Integration-API) allows direct integration from the device to the _hawkBit_ server. It has been designed with simplicity in mind as its is fully focused on software update. It allows device integrators to separate concerns by means of having distinguished channels for business data and general device management tasks on one side and software update on the other. As a result it is possible to keep the _lifesaving_ provisioning process controller on the device separate from the more complex business functionality. A benefit of such an architecture should not be underestimated.
As result of such a simple HTTP/REST/JSON based API even a major back-end migration or disaster can be covered with simple web server hosting a text file that contains only the command to update one more time to execute a migration on the device. The API was designed on purpose in way to have that last resort even if the plan is that this will never be necessary.
The [Device Management Federation API](https://github.com/eclipse/hawkbit/wiki/Device-Management-Federation-API) however allows to combine the business data and _hawkBit_ connectivity. This is especially usefull if a constrained device cannot handle a TLS/HTTP connection, is supporting a standard device management protocol that covers also the software update part (e.g. TR-069, OMA-DM, LWM2M) or the device is already connected and _hawkBit_ is introduced later on.
The decision for the right device integration path is up to the integration party.

77
docs/src/main/resources/documentation/interfaces/management-api.md Normal file
View File

@@ -0,0 +1,77 @@
---
layout: documentation
title: Management-API
---
{% include base.html %}
# Management API
## Overview
The Management API is a RESTful API that enables to perform Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software). Based on the Management API you can manage and monitor software update operations via HTTP/HTTPS. The _Management API_ supports JSON payload with hypermedia as well as filtering, sorting and paging. Furthermore the Management API provides permission based access control and standard roles as well as custom role creation.
The API is protected and needs authentication and authorization based on the security concept.
## API Version
_hawkBit_ provides an consistent Management API interface that guarantees backwards compatibility for future releases by version control.
The current version of the Management API is `version 1 (v1)` with the URI http://localhost:8080/rest/v1/
## API Resources
Supported HTTP-methods are:
- GET
- POST
- PUT
- DELETE
Available Management APIs resources are:
* [Targets](https://docs.bosch-iot-rollouts.com/documentation/rest-api/targets-api-guide.html)
* [Distribution Sets](https://docs.bosch-iot-rollouts.com/documentation/rest-api/distributionsets-api-guide.html)
* [Distribution Set Types](https://docs.bosch-iot-rollouts.com/documentation/rest-api/distributionsettypes-api-guide.html)
* [Software Modules](https://docs.bosch-iot-rollouts.com/documentation/rest-api/softwaremodules-api-guide.html)
* [Software Module Types](https://docs.bosch-iot-rollouts.com/documentation/rest-api/softwaremoduletypes-api-guide.html)
* [Target Tag](https://docs.bosch-iot-rollouts.com/documentation/rest-api/targettag-api-guide.html)
* [Distribution Set Tag](https://docs.bosch-iot-rollouts.com/documentation/rest-api/distributionsettag-api-guide.html)
* [Rollouts](http://https://docs.bosch-iot-rollouts.com/documentation/developerguide/apispecifications/managementapi/rollouts.html)
## Headers
For all requests an `Authorization` header has to be set.
* Username: `Tenant\username`
* Password: `password`
Also have a look to the [Security](https://github.com/eclipse/hawkbit/wiki/Security) chapter.
In addition, for POST and PUT requests the `Content-Type` header has to be set. Accepted content-types are.
* `application/json`
* `application/hal+json`
## Request Body
Besides the relevant data (name, description, createdBy etc.) of a resource entity, a resource entity also has URIs (`_links`) to linked resource entities.
A _Distribution Set_ entity may have for example URIs to artifacts, _Software Modules_, _Software Module Types_ and metadata.
{% highlight json %}
"_links": {
"artifacts": {
"href": "http://localhost:8080/rest/v1/softwaremodules/83/artifacts"
},
"self": {
"href": "http://localhost:8080/rest/v1/softwaremodules/83"
},
"type": {
"href": "http://localhost:8080/rest/v1/softwaremoduletypes/43"
},
"metadata": {
"href": "http://localhost:8080/rest/v1/softwaremodules/83/metadata?offset=0&limit=50"
}
{% endhighlight %}

143
docs/src/main/resources/documentation/interfaces/management-ui.md Normal file
View File

@@ -0,0 +1,143 @@
---
layout: documentation
title: Management-UI
---
{% include base.html %}
The _hawkBit_ Management UI provides several views for the different use cases:
- _Deployment Management_ view for target administration and manual deployment.
- _Distribution Management_ view software repository metadata management.
- _Artifact Management_ view to manage the artifacts.
- _Target Filter Management_ view to manage target filters that can be used both in Deployment and Rollout Management views.
- _Rollout Management_ for large scale rollout orchestration.
# Deployment Management
## Purpose
Target status overview, target management and manual deployments.
## Feature explained
- Target Status: check status of all targets.
- Target list allows filters based on:
- Assigned/installed _DistributionSet_ (drag and drop a set on the filter icon on the top of the list)
- Target update status: click 1-X status to reduce the list of targets that have one of them.
- Target tag: click 1-X tags to reduce the list to targets that have one of them.
- Name, description: use search button on the top of the list.
- _DistributionSet_ list allows filters based on:
- _DistributionSet_ tag: click 1-X tags to reduce the list of sets that have one of them.
- Name, description: use search button on the top of the list.
- Start roll out by drag and drop targets on a DS.
- Target list supports CTRL-A for "select all".
- Delete sets, tags or targets by dragging them on delete icon.
- Select _Target_ to see _Action_ History.
- Bulk target upload: create bulk targets by upload.
Hints for bulk upload:
- Expected file type : csv.
- Expected file format : Each line with two values (ControllerID,Target Name). ControllerID is mandatory.
- Example:
```
Controller_id_1,targetName1
Controller_id_2,targetName2
```
![Deployment Management view](../images/ui/deployment_mgmt.png){:width="100%"}
# Distribution Management
## Purpose
Distribution Set view to manage software repository metadata, i.e. Distribution Sets, their Software Modules and the respective types.
## Features explained
- Browse, create, delete and update Distribution Sets.
- Browse, create, delete and update Distribution Set Types.
- Browse, create, delete and update Software Modules.
- Browse, create, delete and update Software Module Types.
- Assign Software Modules to Distribution Sets.
![Distribution Management view](../images/ui/distribution_mgmt.png){:width="100%"}
# Artifact Management
## Purpose
Software artifact management, both metadata (i.e. Software Modules) and artifacts themselves.
## Features explained
Allows to:
- Browse, create, delete and update Software Modules.
- Browse, create, delete and update Software Module Types.
- Upload and delete software artifacts for a module.
![Artifact Management view](../images/ui/artifact_mgmt.png){:width="100%"}
# Rollout Management
## Purpose
Software rollout in large scale, rollout status overview and rollout management.
## Features explained
- Create, update and start of rollouts.
- Pause and resume of rollouts.
- Progress monitoring for the entire rollout and the individual groups.
- Drill down to see the groups in a rollout and targets in each group.
- Rollout attributes:
- Selection of targets as input for the rollout based on _target filter_
- Selection of _distribution set_
- Auto-splitting of the input target list based on _group number_ defined
- _Trigger threshold_ to define the percentage of installation to be completed , to trigger the start of next group
- _Error threshold_ defines the percentage of error tolerance of a group before calling for a emergency shutdown of a rollout
![Rollout Management view](../images/ui/rollout_mgmt.png){:width="100%"}
![Rollout Management view](../images/ui/rollout_groups.png){:width="100%"}
## Note
- Deletion of targets which are in a rollout, changes the rollout statistics.
# Target Filter Management
## Purpose
Custom target filter overview and filter management.
## Features explained
- Custom target filter allows user to filter targets by defining custom query.
- Displays custom target filter list and user can search any particular filter.
- Create, update and delete features are supported for target filters.
## How to Filter
The basic syntax to filter is: `field<basic_operator>value <composite_operator> field<basic_operator>value <...>`
- `field`: is the name of the resource field.
- `value`: is the value of the target field
- `<basic_operator>`: Are operators to do simple queries. Supported basic operators are:
- `==` : equal
- `!=` : not equal
- Use `=IN=` for 'in' parameter.(Example: name=IN=(target1,target2).
- `<composite_operator>`: Are operators to join simple queries: Supported composite operators are:
- `and`
- `or`
- Use `=IN=` for 'in' parameter.(Example: name=IN=(target1,target2).
- Use `*` for wildcard matches.
## Examples
Custom query | Description
------------------------------------------------------------------------------------------ | -----------------------------------------------------------------------------------------------------------------------------------------------------
updatestatus==error | Gives all targets in ‘error’ state.
controllerId!=192.168.2.42 | Gives all targets that don't have the controllerId 192.168.2.42.
name==\*CCU\* | Gives all targets which contain the term ‘CCU’ in there name.
name==\*CCU\* or description==\*CCU\* | Gives all targets that either have the term ‘CCU’ in their name or their description.
name==\*SHC\* and description==\*SHC\* | Gives all targets that have the term SHC in their name and their description.
name==CCU* and updatestatus==pending | Gives all targets with their name starting with ‘CCU’ and which are in ‘pending’ state.
(assignedds.name==‘ECU-DS’ and description==test) or updatestatus!=error | Gives all targets which are either assigned to ‘ECU-DS’ and have description equals to ‘test’ or which are not in error status.
(updatestatus!=In\_sync or updatestatus!=error) and name==\*SHC1\* | Gives all targets that don't have the updatestatus In\_sync or error and that contains the term SHC1 in their name.
(updatestatus!=error or updatestatus!=pending) and (name==\*CCU\* or description==\*CCU\*) | Gives all targets that either have the term ‘CCU’ in their name or their description and that either have the _update status_ not in state error or pending.
![Target Filter Management view](../images/ui/target_filter.png){:width="100%"}