Arduino MQTT客户端库PubSubClient快速入门

目的

MQTT是比较常用在物联网设备中的通讯协议，这篇文章将使用 Arudino ESP32 作为MQTT客户端进行通讯使用演示。目前Arduino的MQTT客户端库中最常使用的是 PubSubClient ，所以本文也将以此进行说明。

主页：https://pubsubclient.knolleary.net/
项目地址：https://github.com/knolleary/pubsubclient
目前 PubSubClient 库版本为 v2.8 ，主要基于 MQTT 3.1.1 ，不支持 MQTT 5.0 的新增特性，订阅主题只支持 Qos 0 和 1。

This library provides a client for doing simple publish/subscribe messaging with a server that supports MQTT.

基础说明

MQTT的一些基础内容可以参考下面文章：
《MQTT基础入门与资料收集》
因为测试需要有 MQTT Broker（服务器） ，可以参考上面文章进行启动，或者也可以申请一个免费的在线的云服务使用。

PubSubClient 库使用很简单，主要就是分为下面几步：

1. 声明 PubSubClient 对象；
2. 因为MQTT需要在TCP之上工作，所以需要给 PubSubClient 对象一个TCP对象；
3. 使用 setServer 方法设置MQTT服务器的地址和端口号；
4. 使用 setCallback 方法设置通讯消息回调函数 void callback(char *topic, byte *payload, unsigned int length)（如果不需要订阅消息则无需此步骤）；
5. 使用 connect 方法启动连接；
6. 使用 subscribe 方法订阅主题或使用 publish 方法向某个主题发布消息；

上面步骤中 2、3、4 步顺序并无要求，并且可以在第一步声明对象的构造函数中直接传入。

在使用 connect 方法进行连接时可以选择填入 Will Qos Will Retain Will Message cleanSession 信息（默认为 0 0 0 1 ）。发送消息时可以选择填入 retained （默认为 false ）。

默认情况下发送和接收数据都会依赖buffer，当发送或者接收的消息比buffer可容纳的空间（默认256字节）大的时候将会忽略这条消息。可以使用 setBufferSize 方法来设置buffer大小。

上面的 publish 方法发送消息时会先将消息拷贝到缓存，这在大数据发送时效率并不好，可以先使用 beginPublish 方法启动传输，然后单次或多次使用 write 方法写数据（也可以使用 print 等方法），最后使用 endPublish 完成本次消息发送，减少一次拷贝，效率上会高很多。

可以使用 setKeepAlive 方法来设置 Keep Alive 时间（默认为15s）。

使用 disconnect 方法可以关闭连接，使用 connected 方法可以检查是否连接。使用 unsubscribe 方法可以取消订阅消息。

使用 state 方法可以获得 PubSubClient 对象当前的状态，状态定义如下：

// Possible values for client.state()
#define MQTT_CONNECTION_TIMEOUT     -4
#define MQTT_CONNECTION_LOST        -3
#define MQTT_CONNECT_FAILED         -2
#define MQTT_DISCONNECTED           -1
#define MQTT_CONNECTED               0
#define MQTT_CONNECT_BAD_PROTOCOL    1
#define MQTT_CONNECT_BAD_CLIENT_ID   2
#define MQTT_CONNECT_UNAVAILABLE     3
#define MQTT_CONNECT_BAD_CREDENTIALS 4
#define MQTT_CONNECT_UNAUTHORIZED    5

示例代码

#include 
#include 

// WiFi相关配置信息
const char *wifi_ssid = "********";
const char *wifi_password = "********";

// MQTT相关配置信息
const char *mqtt_broker_addr = "********"; // 服务器地址
const uint16_t mqtt_broker_port = 1883; // 服务端口号            
const char *mqtt_username = "********"; // 账号（非必须）
const char *mqtt_password = "********"; // 密码（非必须）
const uint16_t mqtt_client_buff_size = 4096; // 客户端缓存大小（非必须）
String mqtt_client_id = "esp32_client"; // 客户端ID
const char *mqtt_topic_pub = "esp32/test"; // 需要发布到的主题
const char *mqtt_topic_sub = "esp32/test"; // 需要订阅的主题

WiFiClient tcpClient;
PubSubClient mqttClient;

// MQTT消息回调函数，该函数会在PubSubClient对象的loop方法中被调用
void mqtt_callback(char *topic, byte *payload, unsigned int length)
{
    Serial.printf("Message arrived in topic %s, length %d\n", topic, length);
    Serial.print("Message:");
    for (int i = 0; i < length; i++)
    {
        Serial.print((char)payload[i]);
    }
    Serial.println("\n----------------END----------------");
}

void setup()
{
    Serial.begin(115200);
    Serial.println();

    // 连接网络
    Serial.printf("\nConnecting to %s", wifi_ssid);
    WiFi.begin(wifi_ssid, wifi_password);
    while (WiFi.status() != WL_CONNECTED)
    {
        delay(500);
        Serial.print(".");
    }
    Serial.println("ok.");
    Serial.print("IP address: ");
    Serial.println(WiFi.localIP());

    // 设置MQTT客户端
    mqttClient.setClient(tcpClient);
    mqttClient.setServer(mqtt_broker_addr, mqtt_broker_port);
    mqttClient.setBufferSize(mqtt_client_buff_size);
    mqttClient.setCallback(mqtt_callback);
}

unsigned long previousConnectMillis = 0; // 毫秒时间记录
const long intervalConnectMillis = 5000; // 时间间隔
unsigned long previousPublishMillis = 0; // 毫秒时间记录
const long intervalPublishMillis = 5000; // 时间间隔

void loop()
{
    unsigned long currentMillis = millis(); // 读取当前时间

    // 连接MQTT服务器
    if (!mqttClient.connected()) // 如果未连接
    {
        if (currentMillis - previousConnectMillis > intervalConnectMillis)
        {
            previousConnectMillis = currentMillis;
            mqtt_client_id += String(WiFi.macAddress()); // 每个客户端需要有唯一的ID，不然上线时会把其他相同ID的客户端踢下线
            if (mqttClient.connect(mqtt_client_id.c_str())) // 尝试连接服务器
            // if (mqttClient.connect(mqtt_client_id.c_str(), mqtt_username, mqtt_password))
            {
                mqttClient.publish(mqtt_topic_pub, "hello mqtt!"); // 连接成功后可以发送消息
                mqttClient.subscribe(mqtt_topic_sub); // 连接成功后可以订阅主题
            }
        }
    }

    // 定期发送消息
    if (mqttClient.connected())
    {
        if (currentMillis - previousPublishMillis >= intervalPublishMillis) // 如果和前次时间大于等于时间间隔
        {
            previousPublishMillis = currentMillis;
            mqttClient.publish(mqtt_topic_pub, "naisu 233~~~");
        }
    }

    // 处理MQTT事务
    mqttClient.loop();
}

上面代码示例演示的是非加密的mqtt，实际业务中更多的可能会使用加密的mqtts，这个时候TCP客户端就需要使用 #include 库中的 WiFiClientSecure 对象了。TCP客户端需要使用 setCACert 或者 getFingerprintSHA256 等方法设置证书或者指纹，另外可能需要从NTP服务器获取时间。（ WiFiClientSecure对象可以使用 setInsecure 方法，可以不用管证书这些，测试使用没问题，实际使用中可能会有安全风险）

总结

MQTT作为客户端使用本身比较简单，PubSubClient用起来也非常简单，基本上一般的使用有上面内容就够了。