单片机与物联网 / 系统课时
连接 MQTT 服务
连接 MQTT 服务
这一课把已经联网的 ESP32 接入 MQTT Broker:配置 Broker 地址、客户端身份与认证信息,启动 ESP-MQTT 客户端,并用连接事件确认设备确实进入可通信状态。
学习目标
- 能配置 Broker URI、Client ID、用户名和密码
- 能启动 MQTT 客户端并识别连接成功事件
- 能按连接错误类型检查地址、认证和传输安全配置
连接前准备
先确保 ESP32 已获得 IP 地址,再建立 MQTT 连接。Broker 侧至少要准备主机名、端口和设备凭据;Client ID 用来区分客户端,同一时刻不应让两台在线设备使用同一个身份。
如果工程尚未加入 MQTT 组件,可在项目根目录执行:
idf.py add-dependency espressif/mqtt预期结果:
项目依赖清单中新增 espressif/mqtt;实际终端提示和解析出的版本号可能不同。示例使用 mqtt:// 展示最小连接链路,便于在受控实验环境中观察过程。生产设备应优先使用 mqtts://,并正确配置 Broker 证书校验,避免凭据和业务数据以明文传输。
看懂连接链路
MQTT 客户端不是直接“发布数据”就结束,它会先通过网络连接到 Broker,再发送包含客户端身份和会话参数的 CONNECT 报文;Broker 接受后,ESP-MQTT 才会产生连接成功事件。

配置并启动客户端
下面是片段示例,依赖上下文是 Wi-Fi 已连接;把函数放入现有 ESP-IDF 工程,并将占位参数替换为自己的 Broker 配置后调用 mqtt_start_after_wifi_connected()。
#include "esp_event.h"
#include "esp_log.h"
#include "mqtt_client.h"
static const char *TAG = "mqtt";
static void mqtt_event_handler(void *handler_args,
esp_event_base_t base,
int32_t event_id,
void *event_data)
{
if (event_id == MQTT_EVENT_CONNECTED) {
ESP_LOGI(TAG, "connected to broker");
} else if (event_id == MQTT_EVENT_DISCONNECTED) {
ESP_LOGW(TAG, "disconnected from broker");
} else if (event_id == MQTT_EVENT_ERROR) {
ESP_LOGE(TAG, "mqtt connection error");
}
}
esp_mqtt_client_handle_t mqtt_start_after_wifi_connected(void)
{
const esp_mqtt_client_config_t config = {
.broker.address.uri = "mqtt://<BROKER_HOST>:<PORT>",
.credentials = {
.client_id = "<DEVICE_ID>",
.username = "<MQTT_USER>",
.authentication.password = "<MQTT_PASSWORD>",
},
.session.keepalive = 60,
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&config);
if (client == NULL) {
ESP_LOGE(TAG, "failed to create mqtt client");
return NULL;
}
ESP_ERROR_CHECK(esp_mqtt_client_register_event(
client, ESP_EVENT_ANY_ID, mqtt_event_handler, NULL));
ESP_ERROR_CHECK(esp_mqtt_client_start(client));
return client;
}预期输出:
I (<TIME>) mqtt: connected to broker<BROKER_HOST>、<PORT>、<DEVICE_ID>、<MQTT_USER>、<MQTT_PASSWORD> 和日志时间都要按实际环境替换;连接成功日志只有在 Broker 接受连接后才会出现。
连接失败时怎么查
如果始终收到断开或错误事件,按“网络可达性 → Broker 地址与端口 → Client ID → 用户名密码 → TLS 校验”的顺序检查。这样能先排除最底层的问题,避免一开始就修改业务代码。
能稳定收到 MQTT_EVENT_CONNECTED 后,才说明设备与 Broker 的控制连接已经建立;后续订阅和发布都应基于这个连接状态进行。