Device Connection API Specification

The Device Connection API is used by Protocol Adapters to set and retrieve information about the connections from devices or gateways to the protocol adapters.

The Device Connection API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to the Device Connection service component using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.

Preconditions for invoking the Device Connection API

1. Client has established an AMQP connection with the Device Connection service.
2. Client has established an AMQP link in role sender on the connection using target address device_con/${tenant_id}. This link is used by the client to send commands concerning device connections to Hono.
3. Client has established an AMQP link in role receiver on the connection using source address device_con/${tenant_id}/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Device Connection service. This link’s source address is also referred to as the reply-to address for the request messages.

Set last known Gateway for Device

Clients use this command to set the gateway that last acted on behalf of a given device.

As this operation is invoked frequently by Hono’s components, implementors may choose to keep this information in memory. This API doesn’t mandate checks on the validity of the given device or gateway IDs in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.

Message Flow

Request Message Format

The following table provides an overview of the properties a client needs to set on a message to set the last known gateway for a device in addition to the Standard Request Properties.

The body of the message SHOULD be empty and will be ignored if it is not.

Response Message Format

A response to a set last known gateway for device request contains the Standard Response Properties.

The response message’s status property may contain the following codes:

Implementors of this API may return a 404 status code in order to indicate that no device and/or gateway with the given identifier exists for the given tenant. However, performing such a check is optional.

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.

Get last known Gateway for Device

Clients use this command to retrieve the gateway that last acted on behalf of a given device.

Message Flow

Request Message Format

The following table provides an overview of the properties a client needs to set on a message to retrieve the last known gateway for a device in addition to the Standard Request Properties.

The body of the message SHOULD be empty and will be ignored if it is not.

Response Message Format

A response to a get last known gateway for device request contains the Standard Response Properties as well as the properties shown in the following table:

The result of a successful invocation is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.

The response message JSON object has the following properties:

The response message’s status property may contain the following codes:

Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.

Set command-handling protocol adapter instance for device

Clients use this command to set the protocol adapter instance that currently handles command & control messages for a given device.

Clients can provide an optional lifespan parameter to make the protocol adapter instance entry expire after the given number of seconds. Note that implementations of this API have to support this feature, otherwise protocol adapters, as the clients of this API, might fail to correctly route command messages.

This API doesn’t mandate checks on the validity of the given device in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.

Message Flow

Request Message Format

The following table provides an overview of the properties a client needs to set on a message to set the command-handling protocol adapter instance for a device in addition to the Standard Request Properties.

The body of the message SHOULD be empty and will be ignored if it is not.

Response Message Format

A response to a set command-handling adapter instance for device request contains the Standard Response Properties.

The response message’s status property may contain the following codes:

Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.

Remove command-handling protocol adapter instance for device

Clients use this command to remove the information, which protocol adapter instance is currently handling command & control messages for the given device. The mapping information is only removed, if the currently associated adapter instance matches the one given in the request.

This API doesn’t mandate checks on the validity of the given device in order not to introduce a dependency on the Device Registration API. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.

Message Flow

Request Message Format

The following table provides an overview of the properties a client needs to set on a message to remove the mapping information regarding the command-handling protocol adapter instance for a device in addition to the Standard Request Properties.

The body of the message SHOULD be empty and will be ignored if it is not.

Response Message Format

A response to a remove command-handling adapter instance for device request contains the Standard Response Properties.

The response message’s status property may contain the following codes:

Implementors of this API may return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.

Get command-handling protocol adapter instances for device

Clients use this command to get information about the adapter instances that can handle command & control messages for the given device.

As part of the request message, the client is supposed to provide the list of gateways that may act on behalf of the given device. The client may get this list via the Device Registration API’s assert Device Registration operation.

This API doesn’t mandate checks on the validity of the given device and the gateway list in order not to introduce a dependency on the Device Registration API.

The command implementation MUST determine the adapter instances by applying the following rules (in the given order):

1. If an adapter instance is associated with the given device, this adapter instance is returned as the single returned list entry.
2. Otherwise, if there is an adapter instance registered for the last known gateway associated with the given device, this adapter instance is returned as the single returned list entry. The last known gateway has to be contained in the given list of gateways for this case.
3. Otherwise, all adapter instances associated with any of the given gateway identifiers are returned.

That means that for a device communicating via a gateway, the result is reduced to a single element list if an adapter instance for the device itself or its last known gateway is found. The adapter instance registered for the device itself is given precedence in order to ensure that a gateway having subscribed to commands for that particular device is chosen over a gateway that has subscribed to commands for all devices of a tenant.

Message Flow

Request Message Format

The following table provides an overview of the properties a client needs to set on a message to retrieve the command-handling adapter instances for a device in addition to the Standard Request Properties.

The body of the message MUST consist of a single AMQP Data section containing a UTF-8 encoded string representation of a single JSON object. The JSON object has the following properties:

Example of a request payload:

{
  "gateway-ids": ["gw-1", "gw-2", "gw-3"]
}

Response Message Format

A response to a get command-handling adapter instances for device request contains the Standard Response Properties as well as the properties shown in the following table:

The result of a successful invocation is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.

The response message JSON object has the following properties:

Each entry in the adapter-instances array has the following properties:

An example of a response message with a single adapter instance result, returned for example if an adapter instance is registered for the given device:

{
  "adapter-instances": [
    {
      "adapter-instance-id": "adapter-1",
      "device-id": "4711"
    }
  ]
}

An example of a response message with multiple contained adapter instances, returned for example if no adapter instance is registered for the given device or its last used gateway, and therefore a list of all adapter instances for the gateways of the device is returned:

{
  "adapter-instances": [
    {
      "adapter-instance-id": "adapter-1",
      "device-id": "gw-1"
    },
    {
      "adapter-instance-id": "adapter-1",
      "device-id": "gw-2"
    }
  ]
}

The response message’s status property may contain the following codes:

Implementors of this API may also return a 404 status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred.

Standard Message Properties

Due to the nature of the request/response message pattern of the operations of the Device Connection API, there are some standard properties shared by all of the request and response messages exchanged as part of the operations.

Standard Request Properties

The following table provides an overview of the properties shared by all request messages regardless of the particular operation being invoked.

Standard Response Properties

The following table provides an overview of the properties shared by all response messages regardless of the particular operation being invoked.

Delivery States

Hono uses the following AMQP message delivery states when receiving request messages from clients: