ea7d85a15c
* Fix Typos and remove unchanged theme files Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Add Sandbox to getting started section * fix glitch in UI description Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>
302 lines
13 KiB
Markdown
302 lines
13 KiB
Markdown
---
|
|
title: Device Management Federation API
|
|
parent: API
|
|
weight: 83
|
|
---
|
|
|
|
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.
|
|
Currently, bodies of messages are based on JSON.
|
|
<!--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#"
|
|
}
|
|
]
|
|
}]
|
|
}
|
|
``` |