MQTT Binding

Configuration reference for the MQTT message bus binding.

Overview

The MQTT binding connects a Rumi microservice to an MQTT 5 broker. It is registered under the provider name mqtt, so a descriptor of the form mqtt://host:1883 resolves to it with no additional configuration.

For conceptual information about the MQTT binding, see MQTT Binding.

The binding requires an MQTT 5 broker. It does not fall back to MQTT 3.1.1.

Bus Descriptor Format

MQTT buses can be configured using a descriptor string or decomposed DDL format.

Descriptor String

mqtt://<address>:<port>&prop1=val1&propN=valN

Example:

mqtt://broker.example.com:1883&clean_start=false&session_expiry_interval=3600

The address portion carries the broker host and port together. When the port is omitted it defaults to 1883, or 8883 when use_tls is set.

Decomposed DDL Format

<buses>
  <bus name="my-bus">
    <provider>mqtt</provider>
    <address>broker.example.com</address>
    <port>1883</port>
    <properties>
      <clean_start>false</clean_start>
      <session_expiry_interval>3600</session_expiry_interval>
    </properties>
    <channels>
      <!-- channel configuration -->
    </channels>
  </bus>
</buses>

As Descriptor (Substitution Support)

<buses>
  <bus name="my-bus" descriptor="mqtt://${mqtt.host}:${mqtt.port}">
    <channels>
      <!-- channel configuration -->
    </channels>
  </bus>
</buses>

The descriptor form is useful when the descriptor is supplied as an external configuration property:

<buses>
  <bus name="my-bus" descriptor="${myBusDescriptor::loopback://mybus}">
    <channels>
      <!-- channel configuration -->
    </channels>
  </bus>
</buses>

MQTT Binding Properties

The following properties can be set in the descriptor used to create an MQTT bus binding.

The most important setting for external integration is raw_mode. It is a general bus-connection property (see Configuring Bus Connections) rather than MQTT-specific, but it is decisive for MQTT: set raw_mode=true to connect to a non-Rumi source or sink so the binding sends and receives plain payloads with no Rumi metadata. See Connecting to External Systems. Without it, metadata-less messages from an external publisher are rejected as corrupt.

Property

Default

Description

client_id

X-SMA-<busname>-<bususer>

The MQTT client identifier presented to the broker. When unset it is derived from the bus name and the bus user. An MQTT broker permits only one connection per client identifier, so if a bus is shared between multiple microservices the client id must be different for each, but the same for primary and backup instances of the same microservice.

clean_start

true

Whether the broker should start a clean MQTT session rather than resuming one. Set to false, together with a stable client_id and a non-zero session_expiry_interval, to ask the broker to retain subscriptions and undelivered messages across a disconnect.

session_expiry_interval

The MQTT 5 session expiry interval, in seconds. Only meaningful when clean_start is false.

keep_alive

The MQTT keep alive interval, in seconds.

retain

false

Whether published messages are marked retained on the broker.

receive_maximum

65535

The maximum number of QoS 1 and QoS 2 publishes that may be in flight before the binding applies back pressure.

use_tls