MQTT basics

MQTT is the messaging protocol that IoT Parrot speaks to your hardware. This primer explains the handful of concepts behind it — no app-specific setup, just the ideas — so the rest of the docs make sense.

What is MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol designed for the Internet of Things. It's built to run on small, cheap, sometimes flaky devices over unreliable networks, which is exactly why it's the standard for hobbyist hardware like the ESP32 and Arduino. Messages are small, connections are long-lived, and the overhead is tiny compared with polling a web API.

The broker

At the center of every MQTT system is a broker — the server that routes messages. Every client (your ESP32, your phone, IoT Parrot) opens a connection to the broker and never directly to another client. When one client sends a message, the broker is responsible for delivering it to everyone who asked for it.

The broker is the one piece you always need. You can run your own (Mosquitto, EMQX, HiveMQ, and others), or use the IoT Parrot managed broker so there's nothing to install. Either way, see Brokers for how to connect one.

Topics and wildcards

Messages aren't addressed to a client — they're published to a topic. A topic is a hierarchical string with levels separated by forward slashes:

home/livingroom/light
home/greenhouse/temp
sensors/garage/door

The hierarchy is just a naming convention — the broker doesn't require it — but a consistent structure like location/room/thing keeps a growing setup organized. Topics are case-sensitive and are created implicitly the moment something publishes to them; there's no "create topic" step.

When you subscribe, you can use two wildcard characters to match many topics at once:

+ (single level)

Matches exactly one level. home/+/light matches home/livingroom/light and home/kitchen/light, but not home/livingroom/ceiling/light.

# (multi level)

Matches every remaining level, and must come last. home/# matches home/livingroom/light, home/greenhouse/temp, and anything else under home/.

Publish and subscribe

MQTT has exactly two verbs:

• Publish — a client sends a message to a topic. "Fan controller, publish ON to home/greenhouse/fan."
• Subscribe — a client tells the broker "send me every message on these topics." From then on, whenever anyone publishes there, the broker pushes the message to that subscriber.

The key idea is decoupling: publishers and subscribers never talk to each other directly and don't even need to know the other exists. A sensor publishes readings without knowing who (if anyone) is listening; a dashboard subscribes without knowing which device produces the data. You can add, remove, or restart either side independently.

In a typical IoT Parrot flow both directions happen at once: your firmware subscribes to a command topic and publishes its status to another, while a dashboard widget publishes commands and subscribes to that status.

Payloads

The payload is the body of the message — the actual content published to a topic. MQTT treats it as raw bytes and doesn't care what's inside, so payloads are whatever you decide. They're usually small:

• A short string command: ON, OFF, PRESS
• A single number: 42, 23.5
• A small JSON object: {"temp":23.5,"humidity":61}

Because there's no enforced format, the publisher and subscriber just have to agree on the convention. In IoT Parrot you decide the payload a toggle sends for on and off, the fixed string a button publishes, and how a Get Data widget parses a response (raw, JSON, or CSV).

QoS, retained messages & last will

Three broker features are worth knowing about, even briefly:

QoS (Quality of Service)

A per-message delivery guarantee, one of three levels. 0 — "at most once": fire-and-forget, no acknowledgement. 1 — "at least once": guaranteed to arrive, but may be delivered more than once. 2 — "exactly once": guaranteed to arrive exactly one time, at the cost of more handshaking. Higher levels are more reliable but slower.

Retained messages

When a message is published with the retain flag, the broker stores it as the last-known value on that topic. Any client that subscribes later immediately receives that stored message instead of waiting for the next publish. This is why a dashboard gauge can show a value the instant it loads rather than sitting blank — the last reading was retained.

Last will and testament (LWT)

A message a client registers with the broker when it connects. If that client drops off ungracefully (loses power or network), the broker publishes the will message on its behalf — a handy way to announce a device went offline.

TLS & security

TLS encrypts the connection between a client and the broker so credentials and payloads can't be read or tampered with in transit. Plain, unencrypted MQTT commonly uses port 1883; TLS-secured MQTT typically uses port 8883.

How this maps to IoT Parrot

Now that the concepts are in place, here's how they line up with what you'll configure in the app:

• A broker is the MQTT server IoT Parrot connects to — managed or your own.
• A device groups the topics that one piece of hardware uses; it's a named endpoint on a broker.
• A widget publishes to a topic (a toggle sends ON/OFF) or subscribes to one (a gauge shows live values) — that's publish/subscribe in the UI.
• Payloads are the on/off strings, numbers, and JSON you define per widget and per device action.

Ready to connect the real thing? Head to Brokers to add your MQTT server, then Devices to describe your hardware's topics.