Arduino Client for MQTT是一个用于Arduino平台的MQTT客户端库。MQTT（Message Queuing Telemetry Transport）是一种轻量级的消息传输协议，通常用于物联网（IoT）应用程序中，用于在设备之间进行通信。这个库允许您在Arduino板上轻松实现MQTT通信，将您的物联网项目连接到MQTT代理（broker）并与其他设备进行通信。

GitHub - knolleary/pubsubclient：Arduino Ethernet Shield 的客户端库，支持 MQTT。

版本号: 2.8
构造函数

1.PubSubClient ()

  • 描述：创建一个未初始化的客户端实例。
  • 示例： EthernetClient ethClient; PubSubClient client; void setup() { client.setClient(ethClient); client.setServer("broker.example.com", 1883); // 客户端现在已经配置好了 }

2.PubSubClient (client)

  • 描述：创建一个部分初始化的客户端实例。
  • 示例： EthernetClient ethClient; PubSubClient client(ethClient); void setup() { client.setServer("broker.example.com", 1883); // 客户端现在已经准备好了 }

3.PubSubClient (server, port, [callback], client, [stream])

  • 描述：创建一个完全配置好的客户端实例。
  • 参数：
    • server：服务器地址（IPAddress、uint8_t[] 或 const char[]）
    • port：连接的端口
    • callback：消息回调函数的指针（可选，用于处理订阅消息）
    • client：用于网络连接的客户端（例如 WiFiClient）
    • stream：用于写入接收到的消息的流（可选）
  • 示例： EthernetClient ethClient; PubSubClient client(ethClient); void setup() { client.setServer("broker.example.com", 1883); // 客户端现在已经准备好了 }

函数

  1. boolean connect (clientID, [username, password], [willTopic, willQoS, willRetain, willMessage], [cleanSession])
  • 描述：连接客户端到服务器。
  • 参数：
    • clientID：连接到服务器时使用的客户端ID
    • username：用户名（可选，如果不需要用户名和密码则为NULL）
    • password：密码（可选，如果不需要用户名和密码则为NULL）
    • willTopic：遗嘱消息的主题（可选）
    • willQoS：遗嘱消息的QoS等级（0、1 或 2，可选）
    • willRetain：遗嘱消息是否应保留（可选）
    • willMessage：遗嘱消息的内容（可选）
    • cleanSession：是否连接时清除会话（可选）
  • 返回值：
    • false：连接失败
    • true：连接成功

2.void disconnect ()

  • 描述：断开客户端连接。

3.boolean publish (topic, payload, [length], [retained])

  • 描述：发布消息到指定主题。
  • 参数：
    • topic：要发布到的主题
    • payload：要发布的消息内容
    • length：消息内容的长度（可选，如果消息内容是byte[]类型则必须提供）
    • retained：消息是否应被保留
  • 返回值：
    • false：发布失败，可能是连接断开或消息太大
    • true：发布成功

4.boolean publish_P (topic, payload, [length], [retained])

  • 描述：发布存储在 PROGMEM 中的消息到指定主题。
  • 参数与publish函数类似，但用于处理存储在程序存储器中的消息。

5.boolean beginPublish (topic, length, retained)

  • 描述：开始发送一个发布消息。消息的内容需要通过一次或多次的write调用设置，最后使用endPublish完成消息的发送。
  • 参数：
    • topic：要发布到的主题
    • length：要发送的消息内容的长度
    • retained：消息是否应被保留
  • 返回值：
    • false：开始发布失败，可能是连接断开或消息太大
    • true：开始发布成功

6.int write (byte)

  • 描述：将一个字节添加到使用beginPublish开始的发布消息中。
  • 参数：
    • byte：要写入发布消息的字节
  • 返回值：
    • 写入的字节数

7.int write (payload, length)

  • 描述：将一个字节数组添加到使用beginPublish开始的发布消息中。
  • 参数：
    • payload：要写入发布消息的字节数组
    • length：要写入的字节数组的长度
  • 返回值：
    • 写入的字节数

8.boolean endPublish ()

  • 描述：完成使用beginPublish开始的发布消息的发送。
  • 返回值：
    • false：发布失败，可能是连接断开或消息太大
    • true：发布成功

9.boolean subscribe (topic, [qos])

  • 描述：订阅指定主题的消息。
  • 参数：
    • topic：要订阅的主题
    • qos：订阅的QoS等级（0或1，可选）
  • 返回值：
    • false：发送订阅失败，可能是连接断开或消息太大
    • true：发送订阅成功

10.boolean unsubscribe (topic)

  • 描述：取消订阅指定主题的消息。
  • 参数：
  • topic：要取消订阅的主题
  • 返回值：
  • false：发送取消订阅失败，可能是连接断开或消息太大
  • true：发送取消订阅成功

11.boolean loop ()

  • 描述：应该定期调用此函数，以允许客户端处理传入的消息并维持与服务器的连接。
  • 返回值：
  • false：客户端已断开连接
  • true：客户端仍然连接

12.boolean connected ()

  • 描述：检查客户端是否连接到服务器。
  • - 返回值：
  • - false：客户端未连接
  • - true：客户端已连接
  1. int state ()
    • 描述：返回客户端的当前状态。如果连接尝试失败，可以使用此状态获取有关失败的更多信息。
    • 返回值：
    • -4：MQTT_CONNECTION_TIMEOUT - 服务器未在保持连接时间内响应
    • -3：MQTT_CONNECTION_LOST - 网络连接已断开
    • -2：MQTT_CONNECT_FAILED - 网络连接失败
    • -1：MQTT_DISCONNECTED - 客户端已断开连接
    • 0：MQTT_CONNECTED - 客户端已连接
    • 1：MQTT_CONNECT_BAD_PROTOCOL - 服务器不支持所请求的MQTT协议版本
    • 2：MQTT_CONNECT_BAD_CLIENT_ID - 服务器拒绝客户端标识符
    • 3：MQTT_CONNECT_UNAVAILABLE - 服务器无法接受连接
    • 4：MQTT_CONNECT_BAD_CREDENTIALS - 用户名/密码被拒绝
    • 5：MQTT_CONNECT_UNAUTHORIZED - 客户端未被授权连接
  2. PubSubClient* setCallback (callback)
    • 描述：设置消息回调函数。
    • 参数：
    • callback：消息到达订阅的主题时调用的消息回调函数的指针
    • 返回值：PubSubClient* - 允许链式调用的客户端实例
  3. PubSubClient* setClient (client)
    • 描述：设置要使用的网络客户端实例。
    • 参数：
    • client：要使用的网络客户端，例如WiFiClient
    • 返回值：PubSubClient* - 允许链式调用的客户端实例
  4. PubSubClient* setServer (server, port)
    • 描述：设置服务器的详细信息。
    • 参数：
    • server：服务器地址（IPAddress、uint8_t[] 或 const char[]）
    • port：要连接的端口
    • 返回值：PubSubClient* - 允许链式调用的客户端实例
  5. PubSubClient* setStream (stream)
    • 描述：设置用于写入接收到的消息的流。
    • 参数：
    • stream：要写入接收到的消息的流
    • 返回值：PubSubClient* - 允许链式调用的客户端实例
  6. uint16_t getBufferSize ()
    • 描述：获取内部缓冲区的当前大小。
    • 返回值：内部缓冲区的大小
  7. boolean setBufferSize (size)
    • 描述：设置内部发送/接收缓冲区的大小，以字节为单位。这必须足够大，以容纳完整的MQTT数据包。
    • 参数：
    • size：内部缓冲区的大小（以字节为单位）
    • 返回值：
    • false：无法重新分配内存以更改缓冲区大小
    • true：已更改缓冲区大小
  8. PubSubClient* setKeepAlive (keepAlive)
    • 描述：设置客户端使用的保持连接间隔。只有在客户端未连接时才能更改此值。
    • 参数：
    • keepAlive：保持连接的间隔时间，以秒为单位
    • 返回值：PubSubClient* - 允许链式调用的客户端实例
  9. PubSubClient* setSocketTimeout (timeout)
    • 描述：设置客户端使用的套接字超时。这确定了客户端在期望数据到达时将等待多长时间，例如，在读取MQTT数据包时。
    • 参数：
    • timeout：套接字超时时间，以秒为单位
    • 返回值：PubSubClient* - 允许链式调用的客户端实例

其他
配置选项
以下是用于配置库的一些配置选项，它们包含在PubSubClient.h文件中：

  • MQTT_MAX_PACKET_SIZE：设置客户端将处理的最大数据包大小（以字节为单位）。将忽略任何超过此大小的接收到的数据包。
  • 默认值：128字节
  • MQTT_KEEPALIVE：设置客户端将使用的保持连接间隔，以秒为单位。用于在未发送或接收任何其他数据包时维护连接。
  • 默认值：15秒
  • MQTT_VERSION：设置要使用的MQTT协议版本。
  • 默认值：MQTT 3.1.1
  • MQTT_MAX_TRANSFER_SIZE：设置在每次写入调用中传递给网络客户端的最大字节数。某些硬件有一次传递给它们的数据量限制，例如Arduino Wifi Shield。
  • 默认值：未定义（每次写入调用中传递完整数据包）
  • MQTT_SOCKET_TIMEOUT：设置读取网络时的超时时间。这也适用于对connect的调用的超时。
  • 默认值：15秒

订阅回调
如果客户端用于订阅主题，必须在构造函数中提供一个回调函数。当新消息到达客户端时，将调用此函数。

回调函数具有以下签名：

void callback(const char[] topic, byte* payload, unsigned int length)

参数：

  • topic：消息到达的主题
  • payload：消息负载
  • length：消息负载的长度

请注意，客户端在内部使用相同的缓冲区来处理传入和传出的消息。在回调函数返回后，或者如果在回调函数内部调用publish或subscribe，函数传递给回调函数的topic和payload值将被覆盖。如果需要在回调返回后使用这些值，应用程序应创建它们的副本。

打赏微海报分享