doc/help/MQTT-Integration.md
MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol designed for constrained devices and unreliable networks. Serial Studio Pro integrates an MQTT client that can subscribe to broker topics to receive telemetry or publish incoming frame data to a broker for consumption by other applications. This is a Pro feature.
The following diagram shows how Serial Studio integrates with an MQTT broker in both subscriber and publisher modes.
flowchart LR
IoT["IoT Device"] -- publish --> Broker["MQTT Broker"]
Broker -- subscribe --> SS["Serial Studio"]
SS --> Dash["Dashboard"]
Device["Serial Device"] --> SS2["Serial Studio"]
SS2 -- publish --> Broker
MQTT communication revolves around three concepts:
sensors/room1/temperature) that organizes messages. Publishers send to a topic; subscribers filter by topic.Typical flow:
mydevice/sensors on the broker.mydevice/sensors.Click the MQTT button in the toolbar. The MQTT Configuration Dialog opens with all connection and protocol settings.
| Setting | Description | Default |
|---|---|---|
| Hostname | Broker address (IP or hostname) | 127.0.0.1 |
| Port | Broker port | 1883 |
| Username | Authentication username (optional) | Empty |
| Password | Authentication password (optional) | Empty |
| Client ID | Unique identifier for this client | Auto-generated (16 characters) |
| Clean Session | Discard previous session state on connect | Enabled |
Select the protocol version from the dropdown:
Serial Studio operates in one of two modes:
Enter the topic in the Topic Filter field.
Subscriber examples:
sensors/temperature — Receive messages on this exact topic.sensors/+/temperature — Single-level wildcard. Matches sensors/room1/temperature, sensors/room2/temperature, etc.sensors/# — Multi-level wildcard. Matches everything under sensors/.Publisher examples:
mydevice/data — All frames are published to this single topic.After configuring the settings, click Connect. The button label changes to indicate the connection state. To disconnect, click the button again (or use toggleConnection).
In subscriber mode, Serial Studio subscribes to the configured topic filter as soon as the connection is established. Each message received from the broker is treated as a raw frame — the same binary or text payload your device would send over serial or network.
Data format expectations:
23.5,48.2,1013.25).Example: If your ESP32 publishes 23.5,48.2,1013.25 to weather/data, and Serial Studio subscribes to weather/data in Quick Plot mode, the dashboard will display three datasets.
In publisher mode, Serial Studio publishes every frame received from the currently connected data source (serial port, network socket, BLE, etc.) to the configured topic. The published payload is the raw frame content between the start and end delimiters.
Example: If a serial device sends /*1023,512,850*/ and the publish topic is mydevice/sensors, the broker receives 1023,512,850 on that topic.
This mode is useful for bridging a local serial device to a remote MQTT infrastructure without modifying device firmware.
For encrypted connections (strongly recommended for production and any broker exposed to the internet):
| Setting | Description |
|---|---|
| SSL Enabled | Master toggle for TLS encryption |
| SSL Protocol | TLS version: TLS 1.0, 1.1, 1.2, 1.3, or auto-negotiation |
| Peer Verify Mode | None (no verification), Query (query without failing), Verify (require valid certificate), Auto (platform default) |
| Peer Verify Depth | Maximum certificate chain depth to verify |
| CA Certificates | Load additional CA certificates from a PEM file or directory |
Common TLS configuration:
8883 (standard MQTT-over-TLS port).Verify for production, None for testing with self-signed certificates.To load certificates, click the certificate button in the SSL section and select the PEM file(s) or directory containing your CA chain.
The MQTT will message is a message the broker stores and publishes on behalf of the client if the client disconnects unexpectedly (network failure, crash, etc.). It notifies other subscribers that the client is offline.
| Setting | Description |
|---|---|
| Will Topic | Topic the will message is published to |
| Will Message | Payload of the will message |
| Will QoS | Quality of Service: 0 (at most once), 1 (at least once), 2 (exactly once) |
| Will Retain | If enabled, the broker retains the will message for future subscribers |
Example: Set Will Topic to mydevice/status, Will Message to offline, and Will Retain to enabled. When Serial Studio disconnects unexpectedly, any subscriber to mydevice/status receives offline.
The keep-alive mechanism sends periodic PING packets to the broker to maintain the connection and detect network failures.
| Setting | Description |
|---|---|
| Keep Alive | Interval in seconds between PING packets |
| Auto Keep Alive | Let Serial Studio manage the keep-alive interval automatically |
If the broker does not receive a PING within 1.5 times the keep-alive interval, it considers the client disconnected and publishes the will message (if configured).
Every MQTT client on a broker must have a unique client ID. Serial Studio auto-generates a 16-character random string on first launch. Click the Regenerate button to create a new ID at any time.
If two clients connect to the same broker with the same client ID, the broker disconnects the older connection. Always use unique IDs when running multiple Serial Studio instances.
MQTT defines three QoS levels for message delivery:
| QoS | Name | Guarantee | Use Case |
|---|---|---|---|
| 0 | At most once | Fire-and-forget. No acknowledgment. | High-frequency sensor data where occasional loss is acceptable. |
| 1 | At least once | Broker acknowledges receipt. Message may be delivered more than once. | Most telemetry applications. |
| 2 | Exactly once | Four-step handshake ensures single delivery. Highest overhead. | Critical commands or configuration updates. |
The QoS setting in Serial Studio applies to the will message. The subscription QoS is determined by the broker's configuration and the publishing client's QoS.
ping <broker-address> or a standalone MQTT client (mosquitto_sub -h broker -t '#').Sensors/Temperature is not the same as sensors/temperature.# as the topic filter temporarily to receive all messages and confirm data is flowing.mosquitto_sub to monitor independently.Public test brokers (for development and testing only):
test.mosquitto.org — Port 1883 (plaintext), 8883 (TLS), 8080 (WebSocket)broker.hivemq.com — Port 1883 (plaintext)Self-hosted:
Cloud services: