MQTT Basics

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol ideal for IoT devices.

Why MQTT?

• Lightweight - Minimal overhead, perfect for constrained devices
• Reliable - Quality of Service levels ensure message delivery
• Bi-directional - Devices can send and receive messages
• Low bandwidth - Works well on slow 2G/GPRS connections

Core Concepts

Broker

The MQTT broker is the central server that receives and routes all messages. SiliconWit.IO provides a managed broker at:

mqtt.siliconwit.io

Client

Any device or application that connects to the broker. Each client has a unique Client ID (your Device ID in SiliconWit.IO).

Topics

Topics are hierarchical strings that categorize messages:

d/abc123/t
d/abc123/c
sensors/temperature/office

Publish/Subscribe

• Publish - Send a message to a topic
• Subscribe - Receive messages from a topic

Connection Details

Secure Connection (TLS) — Required

Setting	Value
Broker	mqtt.siliconwit.io
Port	8883
TLS	Required
Username	Your Device ID
Password	Your Access Token
Client ID	Your Device ID

WebSocket Connection

For browser-based clients:

Setting	Value
URL	wss://mqtt.siliconwit.io:8084/mqtt
Username	Your Device ID
Password	Your Access Token

Other Protocols

For constrained devices, we also support MQTT-SN (UDP port 1884) and CoAP (UDP port 5683). See the MQTT-SN page for a full protocol comparison.

Note

SiliconWit.IO requires TLS encryption for all MQTT connections. Plain-text MQTT (port 1883) is not supported.

Quality of Service (QoS)

MQTT offers three QoS levels:

QoS	Name	Description	Use Case
0	At most once	Fire and forget	Frequent sensor data
1	At least once	Guaranteed delivery, may duplicate	Important data
2	Exactly once	Guaranteed single delivery	Critical commands

Tip

For most IoT telemetry, QoS 0 is sufficient. Use QoS 1 for important alerts.

Keep Alive

The keep-alive interval tells the broker how often to expect a heartbeat:

client.setKeepAlive(60); // 60 seconds

If the broker doesn’t receive a message or ping within 1.5x the keep-alive time, it marks the device as offline.

Last Will and Testament (LWT)

LWT lets you specify a message to publish if your device disconnects unexpectedly:

client.connect(
  device_id,
  device_id,
  access_token,
  "d/abc123/status",        // LWT topic
  0,                         // LWT QoS
  true,                      // LWT retain
  "{\"status\":\"offline\"}" // LWT message
);

Retained Messages

Retained messages are stored by the broker and sent to new subscribers immediately:

client.publish(topic, payload, true); // true = retained

Use for:

• Device status
• Configuration
• Last known values

Clean Session

• Clean session = true - Start fresh, no stored subscriptions
• Clean session = false - Resume previous session, receive missed messages

client.connect(device_id, user, pass, NULL, 0, false, NULL, false);
//                                                          ^ clean session

Example: Complete Connection

#include <WiFiClientSecure.h>
#include <PubSubClient.h>

WiFiClientSecure secureClient;
PubSubClient client(secureClient);

void setup() {
  secureClient.setInsecure(); // For testing; use setCACert() in production
  client.setServer("mqtt.siliconwit.io", 8883);
  client.setKeepAlive(60);
  client.setCallback(messageReceived);

  // Connect with LWT
  client.connect(
    "device123",           // Client ID
    "device123",           // Username
    "access_token_here",   // Password
    "d/device123/status",       // LWT topic
    1,                     // LWT QoS
    true,                  // LWT retain
    "{\"online\":false}"   // LWT payload
  );

  // Publish online status
  client.publish("d/device123/status", "{\"online\":true}", true);

  // Subscribe to commands
  client.subscribe("d/device123/c");
}

void messageReceived(char* topic, byte* payload, unsigned int length) {
  // Handle incoming messages
}

Next Steps

• Topics & Payloads - Message format guide
• MQTT Authentication - Security details