Edit this page

Consume messages from Eclipse Hono through Apache Kafka brokers and send messages to Eclipse Hono the same manner as Kafka connection does.

This connection type is implemented just for convenience - to avoid the need the user to be aware of the specific header mappings, address formats and Kafka specificConfig, which are required to connect to Eclipse Hono. These specifics are applied automatically at runtime for the connections of type Hono.

Hono connection is based on Kafka connection and uses it behind the scenes, so most of the Kafka connection documentation is valid for Hono connection too, but with some exceptions, described bellow.

Important note

During the creation of hono connection, the connection ID must be provided to be the same as Hono-tenantId. This is needed to match the Kafka topics (aka connection addresses) to the topics on which Hono will send and listen to. See bellow sections Source addresses, Source reply target and Target Address

Specific Hono connection configuration

Connection URI

In Hono connection definition, property uri should not be specified (any specified value will be ignored). The connection URI and credentials are common for all Hono connections and are derived from the configuration of the connectivity service. uri will be automatically generated, based on values of 3 configuration properties of connectivity service - ditto.connectivity.hono.base-uri, ditto.connectivity.hono.username and ditto.connectivity.hono.password. Property base-uri must specify protocol, host and port number (see the example below). In order to connect to Kafka brokers, at runtime username and password values will be inserted between protocol identifier and the host name of base-uri to form the connection URI like this tcp://username:password@host.name:port

Note: If any of these parameters has to be changed, the service must be restarted to apply the new values.

Source format

Source addresses

For a Hono connection source “addresses” are specified as aliases, which are resolved at runtime to Kafka topics to subscribe to. Valid source addresses (aliases) are event, telemetry and command_response. Runtime, these are resolved as following:

  • event -> hono.event.{{connection:id}}
  • telemetry -> hono.telemetry.{{connection:id}}
  • command_response -> hono.command_response.{{connection:id}}

Note: The {{connection:id}} will be replaced by the value of connectionId

Source reply target

Similar to source addresses, the reply target address is an alias as well. The single valid value for it is command. It is resolved to Kafka topic/key like this:

  • command -> hono.command.{{connection:id}}/<thingId> (<thingId> is substituted by thing ID value).

Note: The {{connection:id}} will be replaced by the value of connectionId

The needed header mappings for the replyTarget are also populated automatically at runtime and there is no need to specify them in the connection definition. Any of the following specified value will be substituted (i.e. ignored). Actually the headerMapping subsection is not required and could be omitted at all (in the context of replyTarget).

For addresses telemetry and event, the following header mappings will be automatically applied:

  • device_id: {{ thing:id }}
  • subject: {{ header:subject \| fn:default(topic:action-subject) \| fn:default(topic:criterion) }}-response
  • correlation-id: {{ header:correlation-id }}

For address command_response, the following header mappings will be automatically applied:

  • correlation-id: {{ header:correlation-id }}
  • status: {{ header:status }}

Note: Any other header mappings defined manually will be merged with the auto-generated ones.

The following example shows a valid Hono-connection source:

{
  "addresses": ["event"],
  "consumerCount": 1,
  "qos": 1,
  "authorizationContext": ["ditto:inbound-auth-subject"],
  "enforcement": {
    "input": "{{ header:device_id }}",
    "filters": ["{{ entity:id }}"]
  },
  "headerMapping": {},
  "payloadMapping": ["Ditto"],
  "replyTarget": {
    "enabled": true,
    "address": "command",
    "expectedResponseTypes": ["response", "error", "nack"]
  },
  "acknowledgementRequests": {
    "includes": []
  },
  "declaredAcks": []
}

Source header mapping

Hono connection does not need any header mapping for sources. Anyway, the header mappings documented for Kafka connection are still available. See Source header mapping in Kafka protocol bindings and Header mapping for connections.

Target format

Target address

The target address is specified as an alias and the only valid alias is command. It is automatically resolved at runtime to the following Kafka topic/key:

  • command -> hono.command.{{connection:id}}/<thingId> (<thingId> is substituted by thing ID value).

Note: The {{connection:id}} will be replaced by the value of connectionId

Target header mapping

The target headerMapping section is also populated automatically at runtime and there is no need to specify it the connection definitionm i.e. could be omitted.
If any of the following keys are specified in the connection will be ignored and automatically substituted as follows:

  • device_id: {{ thing:id }}
  • subject: {{ header:subject \| fn:default(topic:action-subject) }}
  • response-required: {{ header:response-required }}
  • correlation-id: {{ header:correlation-id }}

Note: Any other header mappings defined manually will be merged with the auto-generated ones.

The following example shows a valid Hono-connection target:

{
  "address": "command",
  "topics": [
    "_/_/things/twin/events",
    "_/_/things/live/messages"
  ],
  "authorizationContext": ["ditto:outbound-auth-subject"]
}

Specific configuration properties

The properties needed by Kafka server in section specificConfig with the following keys will be automatically added at runtime to the connection. Any manually specified definition of bootstrapServers and saslMechanism will be ignored, but groupId will not.

  • bootstrapServers The value will be taken from configuration property ditto.connectivity.hono.bootstrap-servers of connectivity service. It must contain a comma separated list of Kafka bootstrap servers to use for connecting to (in addition to automatically added connection uri).
  • saslMechanism The value will be taken from configuration property ditto.connectivity.hono.sasl-mechanism. The value must be one of SaslMechanism enum values to select the SASL mechanisms to use for authentication at Kafka:
    • PLAIN
    • SCRAM-SHA-256
    • SCRAM-SHA-512
  • groupId: could be specified by the user, but not required. If omitted, the value of the connection ID will be automatically used.

Hono connection still allows to manually specify additional properties (like debugEnabled), which will be merged with auto-generated ones. If no additional properties are needed, the whole section specificConfig could be omitted.

Certificate validation

The connection property validateCertificates is also set automatically. The value is taken from ditto.connectivity.hono.validate-certificates property. For more details see Connection configuration.

Examples

Example of Hono connection

{
  "connection": {
    "id": "hono-example-connection-123",
    "connectionType": "hono",
    "connectionStatus": "open",
    "failoverEnabled": true,
    "sources": [
      {
        "addresses": ["event"],
        "consumerCount": 1,
        "qos": 1,
        "authorizationContext": ["ditto:inbound-auth-subject"],
        "enforcement": {
          "input": "{{ header:device_id }}",
          "filters": ["{{ entity:id }}"]
        },
        "headerMapping": {},
        "payloadMapping": ["Ditto"],
        "replyTarget": {
          "enabled": true,
          "address": "command",
          "expectedResponseTypes": ["response", "error", "nack"]
        },
        "acknowledgementRequests": {
          "includes": []
        },
        "declaredAcks": []
      }
    ],
    "targets": [
      {
        "address": "command",
        "topics": [
          "_/_/things/twin/events",
          "_/_/things/live/messages"
        ],
        "authorizationContext": ["ditto:outbound-auth-subject"]
      }
    ]
  }
}

Configuration example

Here is an example with all the configurations of connectivity, service which are needed by Hono connections:

ditto {
  connection {
    hono {
      base-uri = "tcp://localhost:9092"
      username = "honoUsername"
      password = "honoPassword"
      sasl-mechanism = "PLAIN"
      bootstrap-servers = "localhost:9092"
      validate-certificates = false
    }
  }
}

Troubleshooting Hono connection configuration

To help the troubleshooting, a separate Piggyback command retrieveHonoConnection is implemented. It is valid only for Hono connections. It returns the “real” Hono connection after all its properties being resolved or auto-generated. The returned value could be used for inspection, but not for example to create a new Hono connection using it.

Tags: connectivity