Quick Start

Quick Start

Get up and running in minutes with these minimal examples.

---

Start a Broker (3 lines)

use mqtt5::broker::MqttBroker;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut broker = MqttBroker::bind("0.0.0.0:1883").await?;
    println!("MQTT broker running on port 1883");
    broker.run().await?;
    Ok(())
}

Or via CLI (the broker uses secure-first auth, so pick an auth mode):

mqttv5 broker --allow-anonymous

---

Connect a Client (10 lines)

use mqtt5::{MqttClient, QoS};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = MqttClient::new("my-device");
    client.connect("mqtt://localhost:1883").await?;

    // Subscribe with callback
    client.subscribe("sensors/#", |msg| {
        println!("{}: {}", msg.topic, String::from_utf8_lossy(&msg.payload));
    }).await?;

    // Publish a message
    client.publish("sensors/temp", b"25.5").await?;

    tokio::time::sleep(tokio::time::Duration::from_secs(5)).await;
    Ok(())
}

The callback receives a Message with fields topic: String, payload: Vec<u8>, qos, retain, and properties.

---

CLI Pub/Sub

Terminal 1 - Subscribe:

mqttv5 sub -t "sensors/#" -v

Terminal 2 - Publish:

mqttv5 pub -t "sensors/temperature" -m "23.5"

Output in Terminal 1:

sensors/temperature: 23.5

---

Connection URLs

The client supports multiple transport protocols:

URL Scheme	Transport	Default Port
mqtt://	TCP	1883
mqtts://	TLS	8883
ws://	WebSocket	80
wss://	WebSocket TLS	443
quic://	QUIC (no cert verification)	14567
quics://	QUIC (verified TLS)	14567

// TCP
client.connect("mqtt://broker.example.com:1883").await?;

// TLS
client.connect("mqtts://broker.example.com:8883").await?;

// WebSocket
client.connect("ws://broker.example.com:8080/mqtt").await?;

// QUIC
client.connect("quic://broker.example.com:14567").await?;

---

QoS Levels

use mqtt5::QoS;

// QoS 0 - At most once (fire and forget)
client.publish("data/telemetry", b"value").await?;

// QoS 1 - At least once (acknowledged)
client.publish_qos1("data/important", b"value").await?;

// QoS 2 - Exactly once (guaranteed)
client.publish_qos2("data/critical", b"value").await?;

┌─────────────────────────────────────────────────────────────────┐
│ QoS 0: Publisher ──PUBLISH──> Broker ──PUBLISH──> Subscriber    │
│        (No acknowledgment)                                      │
├─────────────────────────────────────────────────────────────────┤
│ QoS 1: Publisher ──PUBLISH──> Broker ──PUBACK──> Publisher      │
│        (Acknowledged delivery)                                  │
├─────────────────────────────────────────────────────────────────┤
│ QoS 2: Publisher ──PUBLISH──> Broker                            │
│        Publisher <──PUBREC─── Broker                            │
│        Publisher ──PUBREL──> Broker                             │
│        Publisher <──PUBCOMP── Broker                            │
│        (Exactly once with 4-way handshake)                      │
└─────────────────────────────────────────────────────────────────┘

---

Topic Wildcards

Pattern	Matches	Does Not Match
sensors/+/temperature	sensors/room1/temperature	sensors/building/room1/temperature
sensors/#	sensors/room1/temperature, sensors/a/b/c	other/topic
+/+/data	a/b/data, sensors/room/data	a/b/c/data

// Single-level wildcard (+)
client.subscribe("sensors/+/temperature", |msg| { /* ... */ }).await?;

// Multi-level wildcard (#)
client.subscribe("sensors/#", |msg| { /* ... */ }).await?;

---

Next Steps

• Broker Guide - Configure TLS, WebSocket, authentication
• Client Guide - Auto-reconnect, TLS, advanced features
• CLI Reference - All command options