MQTT is a small, publish-and-subscribe messaging protocol. It was designed for devices on slow or unreliable links, and it has become the default way for sensors, controllers and gateways to send data to an IoT platform. This guide covers what you need to know to connect industrial devices with MQTT, and the mistakes worth avoiding.
How MQTT works
MQTT has three roles.
- Publishers send messages. A temperature sensor publishes its readings.
- Subscribers receive messages. A platform subscribes to the readings it needs.
- The broker sits in the middle. It receives every message and passes it to the subscribers that asked for it.
Devices never talk to each other directly. Each one keeps a single connection open to the broker. That makes MQTT friendly to firewalls and mobile networks: the device opens an outgoing connection, and nothing needs to reach into the site.
Topics
Every message is published to a topic, a text path such as site-a/line-2/filler/temperature. Subscribers can use wildcards to receive many topics at once. Topic design matters more than it first seems.
- Keep a fixed order, for example site, area, device, measurement.
- Avoid spaces and special characters.
- Do not put values or timestamps in the topic; they belong in the payload.
- When a platform defines the topics for you, use them. Hermetry tells each device which topics to use, so data lands on the right device without custom mapping.
Quality of service
MQTT offers three delivery levels, called QoS.
- QoS 0, at most once. The message is sent once with no confirmation. Fine for frequent readings where losing one does not matter.
- QoS 1, at least once. The message is repeated until the broker confirms it. It may arrive twice, so the receiver should tolerate duplicates. This is the usual choice for telemetry.
- QoS 2, exactly once. A four-step handshake makes sure the message arrives once. It costs more traffic and is rarely needed for readings.
A practical rule: use QoS 1 for measurements and events, and include a timestamp in the payload so duplicates can be recognised.
Retained messages and last will
A retained message is stored by the broker and delivered to anyone who subscribes later. It is useful for slow-changing state, such as a configuration or the last known position of a valve. Do not retain fast readings; a new subscriber would get a stale value with no warning.
The last will is a message the broker publishes for a device when its connection drops unexpectedly. It is a simple way to mark a device offline. Combined with a keep-alive interval, it tells you within seconds or minutes that a device has gone quiet, depending on the interval you choose.
Payloads
MQTT does not care what is inside a message. JSON is the most common choice because it is easy to read and debug. A good payload carries:
- a timestamp from the device, in UTC;
- named values with clear units, such as temperature_c rather than t;
- only what changed or what is needed, to keep messages small on metered links.
Binary formats save bandwidth on very constrained links, but cost you readability. Start with JSON unless you have a measured reason not to.
Security
An MQTT connection is a door into your platform. Treat it that way.
- Always use TLS. Credentials and data should never cross a network in plain text.
- Give each device its own credentials. A shared username for a whole fleet means one leaked device exposes all of them.
- Limit what each device may publish and subscribe to. A sensor should only be able to write its own topics.
- Rotate credentials when a device is replaced or a technician leaves.
- Use certificates where devices need them. Some devices and some customers require certificate-based identity in addition to passwords.
On Hermetry, MQTT devices connect with a username and password per device over an encrypted connection, and the platform's certificate service issues certificates where devices need them.
Gateways and devices that do not speak MQTT
Plenty of industrial equipment speaks Modbus, SNMP or a vendor protocol instead. The usual answer is a gateway on site: it reads the local devices and publishes their data over one MQTT or HTTP connection. That also helps where only one machine on the site is allowed to reach the internet.
A checklist before you go live
- Topics follow a fixed pattern and are documented.
- QoS 1 for telemetry, with timestamps in every payload.
- TLS on, one credential per device, and a plan to rotate them.
- Keep-alive and last will set, so offline devices are noticed.
- Device profiles define what each device type sends, so a hundred devices are set up the same way as one.
Read how device profiles and provisioning work on the devices page, or see the full protocol list in the docs.