esp32-mqtt-protocol

name: ESP32 MQTT Protocol description: MQTT protocol implementation for ESP32 IoT devices. Covers MQTT client, subscriptions, publish, QoS, and push notifications. Use when working with MQTT communication, server connections, or push notifications. triggers: - mqtt - protocol - subscribe - publish - notification - push - mqtt_protocol - topic

ESP32 MQTT Protocol Skill

Overview

MQTT (Message Queuing Telemetry Transport) implementation for ESP32 using esp-mqtt component.

ESP-MQTT Client

Configuration

#include "mqtt_client.h"

esp_mqtt_client_config_t config = {
    .broker = {
        .address = {
            .uri = "mqtt://server.com:1883",
        },
    },
    .credentials = {
        .username = "user",
        .authentication = {
            .password = "pass",
        },
    },
    .session = {
        .keepalive = 60,
    },
    .buffer = {
        .size = 4096,
        .out_size = 512,
    },
};

esp_mqtt_client_handle_t client = esp_mqtt_client_init(&config);

Event Handler

static void mqtt_event_handler(void *args, esp_event_base_t base, int32_t event_id, void *event_data) {
    esp_mqtt_event_handle_t event = (esp_mqtt_event_handle_t)event_data;
    
    switch (event_id) {
    case MQTT_EVENT_CONNECTED:
        ESP_LOGI(TAG, "MQTT Connected");
        esp_mqtt_client_subscribe(client, "device/+/commands", 1);
        break;
        
    case MQTT_EVENT_DISCONNECTED:
        ESP_LOGW(TAG, "MQTT Disconnected");
        break;
        
    case MQTT_EVENT_DATA:
        // Handle incoming message
        std::string topic(event->topic, event->topic_len);
        std::string data(event->data, event->data_len);
        HandleMessage(topic, data);
        break;
        
    case MQTT_EVENT_ERROR:
        ESP_LOGE(TAG, "MQTT Error");
        break;
    }
}

// Register handler
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, NULL);
esp_mqtt_client_start(client);

Publish

// QoS 0 - Fire and forget
esp_mqtt_client_publish(client, "device/status", "online", 0, 0, 0);

// QoS 1 - At least once
esp_mqtt_client_publish(client, "device/data", json_str, 0, 1, 0);

// Retained message
esp_mqtt_client_publish(client, "device/status", "online", 0, 1, 1);

Subscribe

// Single topic
esp_mqtt_client_subscribe(client, "device/commands", 1);

// Wildcard subscription
esp_mqtt_client_subscribe(client, "device/+/status", 1);  // Single level
esp_mqtt_client_subscribe(client, "device/#", 1);          // Multi level

Xiaozhi MQTT Protocol Pattern

Topic Structure

device/{mac_address}/           # Device base topic
device/{mac_address}/server     # Server to device messages
device/{mac_address}/client     # Device to server messages

Message Types

// Notification message
{
    "type": "notification",    // or "reminder", "info", "warning", "alert"
    "title": "Title",
    "content": "Message content",
    "useTTS": true            // Enable TTS playback
}

// TTS control
{
    "type": "tts",
    "state": "start"          // or "stop", "sentence_start", "sentence_end"
}

// Goodbye (close session)
{
    "type": "goodbye"
}

MqttNotification Class

class MqttNotification {
public:
    void Start(const std::string& broker_url, 
               const std::string& device_mac,
               const std::string& username = "",
               const std::string& password = "");
    void Stop();
    void SetOnNotificationCallback(OnNotificationCallback callback);
    
private:
    void HandleMessage(const char* topic, const char* data, int len);
    void ParseNotification(const cJSON* root, MqttNotificationData& notification);
};

Notification Data Structure

struct MqttNotificationData {
    std::string type;      // notification, reminder, info, warning, alert
    std::string title;
    std::string content;
    bool useLLM;           // Enable TTS
    std::string extra;     // Additional JSON data
};

UDP Audio Protocol

Bind Packet (Register UDP address)

// After UDP connect, send bind packet
std::string bind_packet;
bind_packet.push_back(0x00);  // Packet type: bind
bind_packet.append(session_id);
udp_->Send(bind_packet);

Audio Packet Format

[1 byte: type] [N bytes: payload]

Types:
0x00 - Bind (session_id string)
0x01 - Audio data (Opus frames)

Best Practices

1. Connection Management

// Auto-reconnect is built-in
// But handle disconnect event for cleanup
case MQTT_EVENT_DISCONNECTED:
    connected_ = false;
    // Clear any pending state
    break;

2. Thread Safety

// Use mutex for shared state
std::lock_guard<std::mutex> lock(mutex_);
callback = on_notification_;

3. Large Messages

// Increase buffer size for large messages
config.buffer.size = 8192;

4. QoS Selection

• QoS 0: Status updates, frequent data
• QoS 1: Commands, important notifications
• QoS 2: Critical operations (rarely needed)

References

• ESP-MQTT: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/mqtt.html
• MQTT Spec: https://mqtt.org/mqtt-specification/