# MQTT

MQTT broker topics as equipment data right in the chat

Топики брокера MQTT (UNS) через назначенный шлюз, только чтение

## How the agent works with MQTT

An MQTT broker usually sits on the site's network, so the gateway reaches it: a program installed on a computer on the same network. The gateway is added on the Gateways tab and assigned to the connection. The connection takes the broker address (mqtt:// or mqtts://), a login and password if needed, and topic filters. While there is no link outside, the gateway keeps the data on disk and sends it once the link is back.

The gateway subscribes only to the filters you name, never the whole broker, and every topic becomes a tag. A message is read as JSON or as text; JSON Pointers say where its values and its source time are, and an object with several fields gives several tags. A retained message without a time is marked as a value of unknown age. The session is clean: what the broker queued while the gateway was away is not replayed.

The gateway publishes no message at all: it has no publish, no will and no retained message of its own. So subscribe rights in the broker's ACL are enough for its account, and the broker itself holds the read only. The agent reads current values, history and freshness, but sends nothing to topics and does not control any equipment.

The tag catalog grows as messages arrive and is capped by the Max tags setting (10000 by default), so an overly wide filter does not turn a busy broker into hundreds of thousands of tags. A tag's type comes from its first value and changes only when two values in a row arrive in another type. History builds up from the moment of connection: the broker keeps no past values.

## Integration scenarios

### Current values
The agent finds tags by topic or name and shows the latest values with the source time, and calls a stale value stale rather than current.

### Trend over a shift
The agent collects a tag's history for a period in intervals: minimum, maximum, average and last value, with gaps where there was no data.

### Sensors behind bridges
The agent reads JSON messages from Zigbee2MQTT, ChirpStack, Node-RED and HighByte: each field of an object becomes its own tag with its own history.

### Comparing lines
The agent lines up one measurement across topics, such as temperature on several lines, and compares averages and peaks over one period.

### A task on a condition
The agent sets up an On event task that starts when a tag's value crosses a threshold and holds there for the time you set.

### Gateway connectivity
The agent tells whether the gateway and its broker connection are online, and an On event task learns when the gateway drops and when it is back.

## How to connect

**Before you connect**

- An MQTT 5 or 3.1.1 broker reachable from the gateway computer
- A broker account with subscribe rights to the needed topics
- A computer on the site's network for the gateway program
- For mqtts://, a broker certificate the gateway trusts

### Create a broker user
The gateway only subscribes and publishes nothing. Give its account subscribe rights to the needed topics in the broker's ACL; it needs no publish rights.

### Set a Client ID if the broker checks them
If the broker's ACL admits only known client IDs, enter one in the connection's advanced settings. Left empty, the gateway names itself.

### Subscribe with narrow filters
List filters separated by commas, such as line/+/temperature, not #. For Zigbee2MQTT subscribe to zigbee2mqtt/+, not zigbee2mqtt/#.

### For TLS, put certificates on the gateway
An mqtts:// address is verified against the system roots and the PEM files in pki/mqtt/trusted/ of the gateway's data folder. For mTLS: pki/mqtt/own/cert.pem and key.pem.

## FAQ

### How do I connect MQTT?
Install the gateway on a computer on the site's network and add it on the Gateways tab. In the MQTT connection enter the broker address, for example mqtt://10.0.12.5:1883, a login and password if the broker requires them, and topic filters separated by commas.

### What does the agent see in MQTT?
The topics under your filters as tags: values from JSON or text, the source time when the message carries one, history from the moment of connection and the freshness of each value. Fields of a JSON object become separate tags.

### Does the agent send messages to the broker?
No. The gateway only subscribes: it has no publish, no will and no retained message of its own. Subscribe rights are enough for the gateway's account.

### The connection reports access denied. What should I check?
The broker accepted the login but refused a subscription to one of the filters. Check the ACL of the gateway's account for each filter, and if the broker admits only known client IDs, enter a Client ID in the advanced settings.