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, <root-topic>/#).

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.

• Azure IoT: payload formatted for Azure IoT ingestion patterns.

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.

Use a generic MQTT client to inspect live topics on your broker.

Prerequisites

• You have an Aranet Cloud account.

• Your Gateway Pro is connected to Aranet Cloud. See Connecting to Aranet Cloud.

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.

Close the Cloud management tab when you’re done.

The Gateway Pro UI may be unresponsive while the remote management session is open.

Integration status

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

Yellow icon (Warning)

Red icon (Error / Expired)

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).