> For the complete documentation index, see [llms.txt](https://help.aranet.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aranet.com/gateway/gateway-pro/integrations-and-3rd-party-systems/mqtt.md). # MQTT MQTT is a lightweight publish/subscribe protocol. Gateway Pro can use it to forward sensor data to an MQTT broker. ### MQTT basics (Gateway Pro) Gateway Pro acts as an **MQTT client**. It publishes sensor measurements to a broker. MQTT uses: * a **broker** (server) that receives messages, and * **topics** (strings) that subscribers use to filter messages. Publishers send messages to topics. Subscribers receive messages for topics they subscribe to. #### MQTT protocol details MQTT topics and subscriptions: * Topics are **case-sensitive strings**. `/` is commonly used as a hierarchy separator. * Subscribers can use **wildcards**: * `+` matches a single topic level. * `#` matches all remaining levels (must be the last character). * For discovery, subscribe using your **root topic** prefix (for example, `/#`). MQTT message handling: * **QoS** controls delivery guarantees (0/1/2). Higher QoS adds overhead. * **Retained messages** are stored by the broker per topic. New subscribers immediately receive the last retained value. * **LWT (Last Will and Testament)** is a broker-published message sent when the client disconnects unexpectedly.\ The **LWT retain** setting controls whether that LWT message is retained on the broker. Connection liveness: * **Keep alive** is negotiated between client and broker.\ The client sends periodic keep-alive traffic (MQTT `PINGREQ` / `PINGRESP`) when idle. * Too low keep-alive values can increase traffic. Too high values can delay disconnect detection. Common broker ports (broker-dependent): * `1883`: MQTT over TCP (plaintext) * `8883`: MQTT over TLS ### Data model (topics and payloads) Gateway Pro publishes under a **root topic**. Think of it as a prefix for all published topics. Use the root topic to: * separate multiple gateways on the same broker, and * avoid topic collisions with other systems. Gateway Pro publishes multiple measurements per sensor over time. The sensor **measurement interval** controls how often sensors report to the gateway. That interval influences publish frequency. Payload structure depends on **Sensor measurement format**: * **Raw**: compact payload optimized for low overhead. * **JSON**: structured payload that is easier to parse in generic systems. {% hint style="info" %} Topic structure and payload fields may change between firmware versions and measurement formats. Use the latest Gateway Pro firmware for predictable behavior and the newest fixes. See [Updating the Firmware](/gateway/gateway-pro/gateway-pro-configuration/updating-the-firmware.md). Use a generic MQTT client to inspect live topics on your broker. {% endhint %} ### Prerequisites * You have an **Aranet Cloud** account. * Your Gateway Pro is connected to Aranet Cloud. See [Connecting to Aranet Cloud](/gateway/gateway-pro/gateway-pro-configuration/connecting-to-aranet-cloud.md). ### Enable MQTT integration 1. On Gateway Pro, open **Settings**. 2. Press **Integrations**. 3. Verify that the Gateway Pro is connected to Aranet Cloud. If the Gateway Pro is not connected, you’ll see the following screen:
Press **Connect to Aranet Cloud**. Scan the QR code to add the Gateway Pro to a workspace. In Aranet Cloud: 1. Open the Gateway Pro. 2. Click **MANAGE**. 3. Open **Integration configuration**. When Cloud connects to the Gateway Pro, you’ll see MQTT configuration settings. Set the **Host address** (broker address). Other settings use defaults unless you need custom values.
Click **Save**. {% hint style="info" %} Close the Cloud management tab when you’re done. The Gateway Pro UI may be unresponsive while the remote management session is open. {% endhint %} ### Integration status {% tabs %} {% tab title="Green icon (Active)" %}
Green icon + status text **Active**: All statuses with `_INFO_` except `_INFO_DISABLED_BY_USER`. * MQTT\_INFO\_NO\_ERR * MQTT\_INFO\_SELF\_INIT\_DISCONN {% endtab %} {% tab title="Yellow icon (Warning)" %}
Yellow icon + status text **Warning**: All statuses with `_WARNING_`. * MQTT\_WARNING\_CONNECTING * MQTT\_WARNING\_RELOADING\_CONFIG {% endtab %} {% tab title="Red icon (Error / Expired)" %}
Red icon + status text **Error**: All statuses with `_ERROR_` except `_ERROR_DISABLED_BY_LICENCE`. * MQTT\_ERROR\_UNEXP\_DISCONN * MQTT\_ERROR\_CONN\_REFUSED * MQTT\_ERROR\_HOST\_UNREACHABLE * MQTT\_ERROR\_AUTH\_FAILED * MQTT\_ERROR\_SETTINGS\_CONFIG\_FAILED * MQTT\_ERROR\_INST\_ALLOC\_FAILED * MQTT\_ERROR\_UNKNOWN\_ERROR Red icon + status text **Expired**: * MQTT\_ERROR\_DISABLED\_BY\_LICENCE {% endtab %} {% tab title="Grey icon" %}
Grey icon Is being shown when integration was Disabled by the user, and the license is either Available or Active. {% endtab %} {% endtabs %} You can also see the status in Aranet Cloud:
### MQTT details shown on Gateway Pro On the Gateway Pro display, MQTT details include: * **Status (message)**: current MQTT client state. * **Updated**: timestamp of the last status refresh. * **Host**: broker host/address configured in Cloud. * **Authentication**: indicates whether broker authentication is enabled. * **Root topic**: topic prefix used for all publishes. * **Protocol version**: MQTT protocol version used by the client. * **Keep alive (seconds)**: keep-alive interval for broker liveness checks. * **Sensor measurement format**: payload format (raw / JSON / Azure IoT). * **QoS level (0 / 1 / 2)**: delivery guarantee for publishes. * **0**: at most once (no ack). * **1**: at least once (may be duplicated). * **2**: exactly once (highest overhead). * **LWT retain**: whether the broker retains the Last Will and Testament message. * **Host CA cert FP**: fingerprint of the broker CA certificate used for TLS validation. * **Client cert FP**: fingerprint of the client certificate (for mTLS brokers). * **Client key FP**: fingerprint of the client private key. ### Transport and security notes MQTT can run in plaintext or over TLS. Use TLS whenever the broker is reachable over untrusted networks. If your broker requires client certificates (mTLS), the **Client cert FP** and **Client key FP** must match the configured credentials. If TLS validation fails, you’ll typically see connection errors (for example, host unreachable or unexpected disconnects). ### Status troubleshooting (common causes) Use the status code to narrow down the failure. * `MQTT_WARNING_CONNECTING`: broker is not reachable yet, or DNS/TLS negotiation is still in progress. * `MQTT_ERROR_CONN_REFUSED`: broker rejected the connection (port closed, protocol mismatch, or broker-side policy). * `MQTT_ERROR_AUTH_FAILED`: username/password or client certificate is not accepted by the broker. * `MQTT_ERROR_HOST_UNREACHABLE`: routing, firewall, DNS, or wrong host/port. * `MQTT_ERROR_UNEXP_DISCONN`: broker dropped the connection (keep-alive timeout, TLS issue, or broker restart). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.aranet.com/gateway/gateway-pro/integrations-and-3rd-party-systems/mqtt.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.