MQTT

MQTT (Message Queuing Telemetry Transport) is the protocol used to exchange messages between a sensor, an MQTT broker, and Visamic.

For protocol background, see the official MQTT website.

How the connection works

The sensor publishes a message to a topic on a broker. Visamic subscribes to that topic, reads the payload, and exposes the configured attributes to Things and panels.

The same broker, topic, authentication, and TLS settings must be configured on both sides.

Publishing and subscribing

There are two independent connections:

• The sensor publishes messages.
• Visamic subscribes to the topic and consumes those messages.

You can test both sides with the Mosquitto clients:

mosquitto_sub -h <broker> -p <port> -t <topic> -u <username> -P <password>
mosquitto_pub -h <broker> -p <port> -t <topic> -u <username> -P <password> -m '<json-payload>'

Add the TLS options required by the broker, such as --cafile, before running these commands.

Connection settings

The connection usually requires:

• Broker hostname
• Port
• Topic
• Client ID, when required by the broker
• Username and password, when authentication is enabled
• TLS and certificate settings, when encryption is enabled

Broker hosts, ports, credentials, and certificates can vary by environment. Use the values shown by the current Visamic configuration instead of relying on an old example.

Client ID

The client ID identifies an MQTT connection. Many brokers require it to be unique among active clients. If the publisher and subscriber disconnect each other, try using different client IDs.

Topics

Topics route messages through the broker. The publisher and subscriber must use the same topic, including its case and slash-separated segments.

Topics are commonly hierarchical, for example factory/line-1/temperature. Choose a topic convention that makes it clear which device owns each message.

For topic syntax, see the Mosquitto MQTT manual.

Quality of Service

MQTT provides three Quality of Service (QoS) levels:

• QoS 0: at most once; no delivery confirmation.
• QoS 1: at least once; a message may be delivered more than once.
• QoS 2: exactly once; uses the most extensive handshake.

Choose the QoS level supported by both the broker and the client. Higher levels add delivery guarantees and protocol overhead.

Retained messages

When the retain flag is enabled, the broker stores the latest message for a topic and sends it to a new subscriber. This can be useful when sensors publish infrequently, but retained values should be kept current and meaningful.

Example payload

This valid payload contains two named measurements with a timestamp:

[
  {
    "temperature": [{ "t": "2023-05-23T17:11:13+02:00", "u": "°C", "v": 27 }]
  },
  {
    "humidity": [{ "t": "2023-05-23T17:11:13+02:00", "u": "%", "v": 60 }]
  }
]

See the JSON data format reference for more payload shapes, including map coordinates.