hawkbit/docs/content/apis/dmf_api.md

title, parent, weight

title	parent	weight
Device Management Federation API	API	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.

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. 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 tenant=tenant123 thingId=abc sender=Lwm2m	content_type=application/json 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 tenant=tenant123 thingId=abc topic=UPDATE_ATTRIBUTES	content_type=application/json

Payload Template

{
	"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

{
   "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 tenant=tenant123 topic=UPDATE_ACTION_STATUS	content_type=application/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

{
   "actionId": long
}

Example Header and payload

Headers	MessageProperties
type=EVENT tenant=tenant123 thingId=abc topic=CANCEL_DOWNLOAD	content_type=application/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 tenant=tenant123 topic=UPDATE_ACTION_STATUS	content_type=application/json

{
   "actionId":137,
   "softwareModuleId":17,
   "actionStatus":"CANCELED",
   "message":["The update was canceled."]
}

Example Header and Payload when cancellation was rejected

Headers	MessageProperties
type=EVENT tenant=tenant123 topic=UPDATE_ACTION_STATUS	content_type=application/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

{
   "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 tenant=tenant123 thingId=abc topic=DOWNLOAD_AND_INSTALL	content_type=application/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#"
           }
       ]
    }]
}