---
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#"
        }
      ]
    }
  ]
}
```