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

Introduce new, Hugo templates based, website (#713)

Browse Source 
* Add new hugo-based website for hawkBit

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Fix broken links + wordings
- , i.e. -> i.e,
- , e.g. -> e.g.,
- hawkbit -> hawkBit
- don't -> do not
- isn't -> is not

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Remove old documentation and add maven integration

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Add Intellij files to ignore

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Update README

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Update Copyright header
* exclude website artifacts

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Harmonize usage of i.e. and e.g.

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Add remark for windows user

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Fix indention

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Introduce review findings

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>

* Change image in 'run hawkbit' guide

Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>
This commit is contained in:
Jeroen Laverman
2018-08-01 11:01:02 +02:00
committed by Dominic Schabel
parent fa751c397b
commit f96876afe0
145 changed files with 1543 additions and 5832 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/content/apis/ddi_api.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Direct Device Integration API
parent: APIs
weight: 82
---
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.
{{% /note %}}
## State Machine Mapping
For historical reasons the DDI has a different state machine and status messages than the [Target State Machine](../../concepts/targetstate/) 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 cancellation request by the update server. | CANCELED
REJECTED | This is send by the target in case an update of a cancellation 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
<iframe width="100%" height="800px" frameborder="0" src="../../rest-api/rootcontroller-api-guide/"></iframe>

301
docs/content/apis/dmf_api.md Normal file
View File

@@ -0,0 +1,301 @@
---
title: Device Management Federation API
parent: API
weight: 83
---
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.
<!--more-->
## 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 update target attributes
| Message Header | Description | Type | Mandatory
|-----------------------------|----------------------------------|-------------------------------------|----------------
| type | Type of the message | Fixed string "EVENT" | true
| topic | Topic to handle events different | Fixed string "UPDATE_ATTRIBUTES" | true
| thingId | The ID of the registered thing | String | 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 and Payload**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <br /> thingId=abc <br /> topic=UPDATE\_ATTRIBUTES | content\_type=application/json <br />
Payload Template
```json
{
"attributes": {
"exampleKey1" : "exampleValue1",
"exampleKey2" : "exampleValue2"
}
}
```
### 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
Payload Template
```json
{
"actionId": long
}
```
**Example Header and payload**
| Headers | MessageProperties
|---------------------------------------|---------------------------------
| type=EVENT <br /> tenant=tenant123 <br /> thingId=abc <br /> topic=CANCEL\_DOWNLOAD | content_type=application/json
```json
{
"actionId":137
}
```
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
}],
"metadata":[
{
"key":"String",
"value":"String"
}
]
}]
}
```
**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
}],
"metadata":[
{
"key":"installationType",
"value":"5784K#"
}
]
}]
}
```

78
docs/content/apis/management_api.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: Management API
parent: API
weight: 81
---
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).
<!--more-->
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](/hawkbit/apis/mgmt/targets/)
- [Distribution sets](/hawkbit/apis/mgmt/distributionsets/)
- [Distribution set types](/hawkbit/apis/mgmt/distributionsettypes/)
- [Software modules](/hawkbit/apis/mgmt/softwaremodules/)
- [Software module types](/hawkbit/apis/mgmt/softwaremoduletypes/)
- [Target tag](/hawkbit/apis/mgmt/targettag/)
- [Distribution set tag](/hawkbit/apis/mgmt/distributionsettag/)
- [Rollouts](/hawkbit/apis/mgmt/rollouts/)
- [Target filters](/hawkbit/apis/mgmt/targetfilters/)
- [System configuration](/hawkbit/apis/mgmt/tenant/)
## Headers
For all requests an `Authorization` header has to be set.
* Username: `Tenant\username`
* Password: `password`
Also have a look to the [Security](../../concepts/authentication/) 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.
```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"
}
```

0
docs/content/apis/mgmt/_index.md Normal file
View File

7
docs/content/apis/mgmt/distributionsets.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Distribution Sets API
parent: Management API
weight: -101
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsets-api-guide/"></iframe>

7
docs/content/apis/mgmt/distributionsettag.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Distribution Set Tag API
parent: Management API
weight: -105
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsettag-api-guide/"></iframe>

7
docs/content/apis/mgmt/distributionsettypes.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Distribution Set Types API
parent: Management API
weight: -102
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsettypes-api-guide/"></iframe>

7
docs/content/apis/mgmt/rollouts.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Rollouts API
parent: Management API
weight: -106
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/rollout-api-guide/"></iframe>

7
docs/content/apis/mgmt/softwaremodules.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Software Modules API
parent: Management API
weight: -103
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/softwaremodules-api-guide/"></iframe>

7
docs/content/apis/mgmt/softwaremoduletypes.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Software Module Types API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/softwaremoduletypes-api-guide/"></iframe>

7
docs/content/apis/mgmt/targetfilters.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Target Filters API
parent: Management API
weight: -107
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targetfilters-api-guide/"></iframe>

7
docs/content/apis/mgmt/targets.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Targets API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targets-api-guide/"></iframe>

7
docs/content/apis/mgmt/targettag.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Target Tag API
parent: Management API
weight: -104
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targettag-api-guide/"></iframe>

7
docs/content/apis/mgmt/tenant.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: System Configuration API
parent: Management API
weight: -108
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/tenant-api-guide/"></iframe>