> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/function-blocks/blocks-reference/input-output/communication/mqtt-subscribe.md).

# MQTT Subscribe

This function block listens to an MQTT topic and outputs incoming messages for use elsewhere in your scenario. It keeps track of whether a message is new so you can trigger actions only when fresh data arrives.

## 📥 Inputs <a href="#inputs" id="inputs"></a>

* `Enable` Input socket — Enable or disable the subscription. When active, the block connects to the broker and listens for messages.

## 📤 Outputs <a href="#outputs" id="outputs"></a>

* `Data` Output socket — Latest received message payload (text) from the subscribed topic.
* `New Data` Output socket — Boolean output socket that becomes true for one run when a new message arrives.

## 🕹️ Controls <a href="#controls" id="controls"></a>

* `Broker Address` Hostname or IP of the MQTT broker to connect to.
* `Port` Broker TCP port (commonly 1883 or 8883 for TLS).
* `Topic` Topic string to subscribe to (supports exact topic matching).
* `Client ID` Optional identifier for the MQTT client.
* `Username` Optional username for broker authentication.
* `Password` Optional password for broker authentication.
* `Keep Alive` Interval used to maintain the broker connection.
* `Use TLS` Toggle to enable TLS-secured connection (if supported by broker).
* `Reconnect / Connect` Button or automatic logic in the UI to (re)establish connection when settings change.

(how these controls appear in the UI may vary; provide valid connection parameters and enable the block to start receiving messages)

## 🎯 Features <a href="#features" id="features"></a>

* Persistent subscription while `Enable` is true — messages are received in real time.
* Provides both the raw `Data` and a one-run `New Data` flag so downstream blocks can respond only to new messages.
* Automatically reconnects if connection parameters change.
* Basic connection status and informational messages appear in the block UI to help diagnose connection events.

## ⚙️ Running mechanism <a href="#running-mechanism" id="running-mechanism"></a>

* When `Enable` is active, the block uses the configured connection settings to connect to the MQTT broker and subscribe to the chosen `Topic`.
* Incoming messages are stored internally and exposed on the `Data` output.
* The block sets `New Data` to true only for the run immediately after a new message arrives; on subsequent runs it resets to false until another message is received.
* Changing connection settings causes the block to reconnect so the new parameters take effect.

## 📝 Usage instructions <a href="#usage" id="usage"></a>

1. Fill in connection parameters: `Broker Address`, `Port`, and `Topic` (add credentials if broker requires them).
2. Enable the block via the `Enable` input.
3. Use the `Data` output to pass received payloads to other blocks. Use the `New Data` output to trigger downstream processing only when a new message arrives.
4. If you change connection settings, allow a short moment for the block to reconnect.

## 💡 Tips and Tricks <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* To forward received messages to a server or service, connect `Data` to `REST API - Post`.
* To re-publish or echo messages, combine this block with `MQTT Publish` or `MQTT Publish (TLS-Beta)`.
* Use `Data to JSON` to structure multiple fields from incoming text before logging or exporting.
* Save incoming messages for later review by connecting `Data` to `CSV Export` or to `SQL-DB Operations` (via `Data to JSON` or appropriate formatting).
* Add a `Debug Input` block to quickly inspect message contents in the log window during development.
* When dealing with changing formats, use `Replace None` or `Is None` blocks to handle missing or malformed messages gracefully.

(hints above use only the function blocks available in the system)

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* No messages received: verify `Broker Address`, `Port` and `Topic` are correct and that the broker is reachable from the machine running the scenario.
* Authentication errors: double-check `Username` and `Password` and whether your broker requires TLS.
* Intermittent connection: check network/firewall settings and try enabling TLS or adjusting `Keep Alive`.
* Messages arrive but are not forwarded: ensure downstream blocks are enabled and use the `New Data` flag if they should only run on new payloads.
* If you change parameters, wait briefly after re-enabling for the block to reconnect before expecting messages.