initial commit of the hawkBit documentation (#343)
Signed-off-by: Michael Hirsch <michael.hirsch@bosch-si.com>
This commit is contained in:
Michael Hirsch
243
docs/src/main/resources/documentation/interfaces/dmf-api.md
Normal file
243
docs/src/main/resources/documentation/interfaces/dmf-api.md
Normal 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
|
||||
}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user