302 lines
11 KiB
Markdown
302 lines
11 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 user has to 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 compatible to other use cases by design. 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 |
|
|
| tenant | The tenant this thing belongs to | String | true |
|
|
|
|
| Message Properties | Description | Type | Mandatory |
|
|
| ------------------ | --------------------- | ------ | --------- |
|
|
| reply_to | Exchange to reply to. | String | true |
|
|
|
|
**Example Header**
|
|
|
|
| Headers | MessageProperties |
|
|
| ------------------------------------------------------------- | -------------------------- |
|
|
| type=THING_CREATED <br /> tenant=tenant123 <br /> thingId=abc | reply_to=dmfclient.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 | true |
|
|
|
|
| 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 |
|
|
|
|
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 | true |
|
|
|
|
| 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 | true |
|
|
|
|
| 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 specified exchange 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 | true |
|
|
|
|
| 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#"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|