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 build is necessary and the MQTT port needs to be enabled (see --mqttport). The MQTT topic published to (and also subscribed to) can be adjusted by using the --mqtttopic option and defaults to "ebusd/%circuit/%name" where "%circuit" is replaced by the circuit name and "%name" by the message name. You can use --mqttuser and --mqttpass for MQTT authentication.

When MQTT is activated and the broker connection was established successfully, ebusd publishes to the topic 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.

In addition to the message specific topics, ebusd also feeds the following general topics (where the "ebusd" prefix depends on how the topic is configured):

• 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/updatecheck: the result of the update check (retained)

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 send 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. 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, an non-empty message payload leads to publishing only those messages that were already sent or received before (by any instance). If 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.