Introduce new, Hugo templates based, website (#713)
* 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
committed by
Dominic Schabel
Dominic Schabel
parent
fa751c397b
commit
f96876afe0
301
docs/content/apis/dmf_api.md
Normal file
301
docs/content/apis/dmf_api.md
Normal 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#"
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user