MQTT Topic Listener
MQTTTopicListenerTask subscribes to MQTT topics through a configured MQTT connector and fires Banalytics events when messages arrive. Use it when external IoT devices, industrial gateways, cloud services, or automation hubs should drive Banalytics rules.
Turn incoming MQTT messages into Banalytics events
The task subscribes to a topic filter on an MQTT connector. Each received message becomes an MQTTTopicMessageEvent containing topic, payload, QoS, retained flag, and payload type metadata.
Subscribe
The task uses an MQTT v3 or v5 connector to subscribe to one topic filter.
Fire events
Every matching message can trigger Event Manager rules inside Banalytics.
Payload handling
Payloads can be delivered as UTF-8 text for easier rule processing.
Adding an MQTT topic listener
Select the connector
Choose an MQTT v3 or v5 connector that is connected to the broker where the topics are published.
Choose a topic filter
Start narrow whenever possible, for example site/line1/+/state or building/floor1/sensor/temperature.
Set QoS
Use QoS 1 for most state-change topics, QoS 0 for high-frequency telemetry, and QoS 2 only when duplicate processing is more dangerous than protocol overhead.
Decide payload mode
Keep stringPayload=true for JSON, plain text, numeric values, and home-automation style topics.
Design filters that keep events manageable
Diagnostics
Use # only during commissioning or troubleshooting when you need to observe all reachable broker traffic.
Subsystem filter
Use one-level wildcards such as site/line1/+/state to capture a family of related devices.
Single signal
Use exact topics for critical automations where the Event Manager rule should be easy to reason about.
QoS, retained messages, and event timing
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
MQTT Connector | Yes | Reference to an MQTT connector. It can be MQTTV3Connector or MQTTV5Connector. | None |
Topic Filter | Yes | MQTT topic filter pattern. Supports MQTT wildcards: + for one level and # for multiple levels. | # |
QoS | Yes | Requested subscription quality of service: 0, 1, or 2. | 1 |
String message | Yes | Converts the received payload to a UTF-8 string before event delivery. | true |
MQTTTopicMessageEvent fields
| Field | Type | Description | Use |
|---|---|---|---|
topic | String | MQTT topic on which the message was received. | Route rules by source |
stringPayload | boolean | Shows whether payload is represented as a String. | Branch processing |
payload | Object | Message payload. Usually a String when string payload mode is enabled. | Rule conditions |
qos | int | QoS level of the received message. | Diagnostics |
retained | boolean | Whether the message was delivered from broker retention. | Ignore stale commands |
Operational notes
Connector must be running
The listener can subscribe only when the selected connector is running and connected.
Restart on configuration changes
Changing connector, topic filter, QoS, or payload mode requires restarting the task.
Disconnected connector
Message delivery pauses while the connector is disconnected and resumes according to connector and task restart behavior.