3.3. MQTT client

Introduction

ebusd supports MQTT handling by using the mosquitto library connecting to an MQTT broker. In order to use it, a running mosquitto instance (see mosquitto.org) or any other MQTT 3.1 compliant broker is necessary.

To enable MQTT support, a corresponding MQTT-enabled build is necessary and the MQTT port needs to be enabled (see --mqttport).

MQTT topics

The MQTT topic published to (and also subscribed to) can be adjusted by using the --mqtttopic, --mqttglobaltopic, and --mqttint options and the defaults are:

• "ebusd/%circuit/%name" for the decoded bus messages
  with "%circuit" being replaced by the circuit name and "%name" with the message name
• "ebusd/global/%name" for some global infos (with "%name" being replaced as follows):
  • ebusd/global/version: the version string of ebusd (retained)
  • ebusd/global/running: true as long as ebusd is running (retained and set to false as last will)
  • ebusd/global/uptime: the up time in seconds
  • ebusd/global/signal: true or false depending on the signal state (retained and set to false when ebusd is stopped)
  • ebusd/global/scan: "OK", "running", or "finished" scan status (retained)
  • ebusd/global/updatecheck: the result of the update check (retained)

When MQTT is activated and the broker connection was established successfully, ebusd publishes all messages that match the default access level or that of the user "mqtt" (see --aclfile). The format is either strings comparable to the read command output, or JSON when --mqttjson is enabled.

Due to the subscription to the topic, ebusd also allows actively sending messages on the eBUS. This is supported by using a specific suffix to the topic:

• /get: initiates an active refresh of a read message from the eBUS.
  When the message was read, ebusd sends the corresponding topic to MQTT.
• /set: allows to send a write message to the eBUS (if the access level allows it, see above).
• /list: publishes all messages known so far (according to access level, see above).

For /get and /set suffixes, the optional message payload can be used to transfer additional input data, e.g. the values to be set for a write message or the needed input for a read message, separated by semicolon.

In addition to that, appending a question mark and a poll priority digit allows adjusting the poll priority for read messages and enables automatic polling. For example, using mosquitto_pub -m '?3' -t 'ebusd/uih/YieldSum/get' would set the uih/YieldSum message to be polled with priority 3 and is equivalent to issuing ebusctl -c uih -p 3 YieldSum.

For the /list suffix, a non-empty message payload leads to publishing only those messages that were already sent or received before (by any instance). If the message payload is null or has a length of zero, messages not yet seen before will be sent with a zero message payload.

Furthermore, the topic may also be incomplete, i.e. contain less parts for addressing all messages or all messages of a certain device only.

Please note that the global topic prefix is not published again by the /list suffix.

MQTT integration

In order to support discovery features of MQTT tools such as Home Assistant, an MQTT integration configuration can be activated with the --mqttint option. See MQTT integration for details on available integrations.

User contributed pages

Bridging to a remote MQTT broker