ESP-AT 系列: AT+MQTT 使用

MQTT AT 指令说明

AT 工程: https://github.com/espressif/esp-at
AT 文档: https://github.com/espressif/esp-at/tree/master/docs

commit: 8ebdee924 之后, ESP-AT 支持 MQTT 系列 AT 指令, 基于 AT 开发的客户可以直接参考本文下述命令, 快速使用 AT+MQTT 连接对应的 Broker.

使用 AT+MQTT 前, 请先开启 AT+MQTT 功能:
make menuconfig -> Component config -> AT -> AT MQTT command support

命令列表

  • AT+MQTTUSERCFG - 配置 MQTT 用户属性
  • AT+MQTTCONNCFG - 配置 MQTT 连接属性
  • AT+MQTTCONN - 连接/查询 MQTT Broker
  • AT+MQTTPUB - 发布字符串消息
  • AT+MQTTPUBRAW - 发布二进制消息
  • AT+MQTTSUB - 订阅/查询主题
  • AT+MQTTUNSUB - 取消订阅主题
  • AT+MQTTCLEAN - 关闭连接, 释放资源

AT+MQTTUSERCFG - 配置 MQTT 用户属性

设置指令:

AT+MQTTUSERCFG=,,<"client_id">,<"username">,<"password">,,,<"path">

功能:
设置 MQTT 用户配置

响应:

OK

ERROR

参数说明:

  • LinkID: 当前只支持 0
  • scheme:
    • 1: MQTT over TCP
    • 2: MQTT over TLS(no certificate verify)
    • 3: MQTT over TLS(verify server certificate)
    • 4: MQTT over TLS(provide client certificate)
    • 5: MQTT over TLS(verify server certificate and provide client certificate)
    • 6: MQTT over WebSocket(based on TCP)
    • 7: MQTT over WebSocket Secure(based on TLS, no certificate verify)
    • 8: MQTT over WebSocket Secure(based on TLS, verify server certificate)
    • 9: MQTT over WebSocket Secure(based on TLS, provide client certificate)
    • 10: MQTT over WebSocket Secure(based on TLS, verify server certificate and provide client certificate)
  • client_id: 对应 MQTT client ID, 用于标志 client 身份, 最长 256 字节
  • username: 用于登录 MQTT brokerusername, 最长 64 字节
  • password: 用于登录 MQTT brokerpassword, 最长 64 字节
  • cert_key_ID: 证书 ID, 目前支持一套 cert 证书, 参数为 0
  • CA_ID: CA ID, 目前支持一套 CA 证书, 参数为 0
  • path: 资源路径, 最长 32 字节

AT+MQTTCONNCFG - 配置 MQTT 连接属性


设置指令:

AT+MQTTCONNCFG=,,,<"lwt_topic">,<"lwt_msg">,,

功能:
设置 MQTT 连接配置

响应:

OK

ERROR

参数说明:

  • LinkID: 当前只支持 0
  • keepalive: MQTT PING 超时时间,范围为 [60, 7200], 单位为秒. 默认 120
  • disable_clean_session: MQTT 清理会话标志, 参数为 0 或 1, 默认为 0
  • lwt_topic: 遗嘱 topic, 最长 64 字节
  • lwt_msg: 遗嘱 message, 最长 64 字节
  • lwt_qos: 遗嘱 QoS, 参数可选 0, 1, 2, 默认为 0
  • lwt_retain: 遗嘱 retain, 参数可选 0, 1, 默认为 0

AT+MQTTCONN


设置指令:

AT+MQTTCONN=,<"host">,,

功能:
连接指定 MQTT broker

响应:

OK

ERROR

查询指令:

AT+MQTTCONN?

功能:
查询 AT 已连接的 MQTT broker

响应:

+MQTTCONN:,,<"host">,,<"path">,
OK

参数说明:

  • LinkID: 当前只支持 0
  • host: 连接 MQTT broker 域名, 最大 128 字节
  • port: 连接 MQTT broker 端口, 最大 65535
  • path: 资源路径, 最长 32 字节
  • reconnect: 是否重连 MQTT, 若设置为 1, 需要消耗较多内存资源
  • state: MQTT 当前状态, 状态说明如下:
    • 0: 连接未初始化
    • 1: 已设置 MQTTUSERCFG
    • 2: 已设置 MQTTCONNCFG
    • 3: 连接已断开
    • 4: 已建立连接
    • 5: 已连接, 但未订阅 topic
    • 6: 已连接, 已订阅过 topic
  • scheme:
    • 1: MQTT over TCP
    • 2: MQTT over TLS(no certificate verify)
    • 3: MQTT over TLS(verify server certificate)
    • 4: MQTT over TLS(provide client certificate)
    • 5: MQTT over TLS(verify server certificate and provide client certificate)
    • 6: MQTT over WebSocket(based on TCP)
    • 7: MQTT over WebSocket Secure(based on TLS, no certificate verify)
    • 8: MQTT over WebSocket Secure(based on TLS, verify server certificate)
    • 9: MQTT over WebSocket Secure(based on TLS, provide client certificate)
    • 10: MQTT over WebSocket Secure(based on TLS, verify server certificate and provide client certificate)

AT+MQTTPUB

设置指令:

AT+MQTTPUB=,<"topic">,<"data">,,

功能:
LinkID上通过 topic 发布数据 data, 其中 data 为字符串消息, 若要发布二进制,请使用 AT+MQTTPUBRAW

响应:

OK

ERROR

参数说明:

  • LinkID: 当前只支持 0
  • topic: 发布主题, 最长 64 字节
  • data: 发布消息, data 不能包含 \0, 请确保整条 AT+MQTTPUB 不超过 AT 指令的最大长度限制
  • qos: 发布服务质量, 参数可选 0,1,2, 默认为 0
  • retain: 发布 retain

AT+MQTTPUBRAW

设置指令:

AT+MQTTPUBRAW=,<"topic">,,,

功能:
LinkID 上通过 topic 发布数据 data, 其中 data 为二进制数据

响应:

OK
> 

ERROR

等待用户输入 length 大小数据, 之后响应如下:

+MQTTPUB:FAIL

+MQTTPUB:OK

参数说明:

  • LinkID: 当前只支持 0
  • topic: 发布主题, 最长 64 字节
  • length: 要发布消息长度, 默认最长为 1024, 可通过 make menuconfigMQTT_BUFFER_SIZE_BYTE 配置
  • qos: 发布服务质量, 参数可选 0,1,2, 默认为 0
  • retain: 发布 retain

AT port 未收到指定 length 长度的数据, 将一直等待, 在此期间接收到的数据都会当成普通数据

AT+MQTTSUB


设置指令:

AT+MQTTSUB=,<"topic">,

功能:
订阅指定连接的 MQTT 主题, 可重复多次订阅不同 topic

响应:

OK

ERROR

当收到对应主题订阅的 MQTT 消息时, 将按照如下格式打印消息内容

+MQTTSUBRECV:,<"topic">,,data

如果订阅已订阅过的主题, 仍无条件向 MQTT broker 订阅, Log 口打印 ALREADY SUBSCRIBE


查询指令:

AT+MQTTSUB?

功能:
查询 MQTT 所有连接上已订阅的 topic

响应:

+MQTTSUB:,,<"topic1">,
+MQTTSUB:,,<"topic2">,
+MQTTSUB:,,<"topic3">,
...
OK

ERROR

参数说明:

  • LinkID: 当前只支持 0
  • state: MQTT 当前状态, 状态说明如下:
    • 0: 连接未初始化
    • 1: 已设置 MQTTUSERCFG
    • 2: 已设置 MQTTCONNCFG
    • 3: 连接已断开
    • 4: 已建立连接
    • 5: 已连接, 但未订阅 topic
    • 6: 已连接, 已订阅过 topic
  • topic*: 订阅过的主题
  • qos: 订阅过的 QoS

AT+MQTTUNSUB

设置指令:

AT+MQTTUNSUB=,<"topic">

功能:
取消订阅指定连接的 MQTT 主题, 可多次取消不同订阅 topic

响应:

OK

ERROR

参数说明:

  • LinkID: 当前只支持 0
  • topic: 取消订阅主题, 最长 64 字节

如果取消未订阅的主题, 仍无条件向 MQTT broker 取消订阅, Log 口打印 NO UNSUBSCRIBE

AT+MQTTCLEAN

设置指令:

AT+MQTTCLEAN=

功能:
关闭 MQTT ClientLinkID 的连接, 并释放内部占用的资源

响应:

OK

ERROR

参数说明:

  • LinkID: 当前只支持 0

MQTT 状态码说明

MQTT 配置交互等过程中, 若出现 ERR CODE:0x<%08x>, 请查阅如下 MQTT 状态码.

    AT_MQTT_NO_CONFIGURED,                              // 0x6001
    AT_MQTT_NOT_IN_CONFIGURED_STATE,                    // 0x6002
    AT_MQTT_UNINITIATED_OR_ALREADY_CLEAN,               // 0x6003
    AT_MQTT_ALREADY_CONNECTED,                          // 0x6004
    AT_MQTT_MALLOC_FAILED,                              // 0x6005
    AT_MQTT_NULL_LINK,                                  // 0x6006
    AT_MQTT_NULL_PARAMTER,                              // 0x6007
    AT_MQTT_PARAMETER_COUNTS_IS_WRONG,                  // 0x6008
    AT_MQTT_TLS_CONFIG_ERROR,                           // 0x6009
    AT_MQTT_PARAM_PREPARE_ERROR,                        // 0x600A
    AT_MQTT_CLIENT_START_FAILED,                        // 0x600B
    AT_MQTT_CLIENT_PUBLISH_FAILED,                      // 0x600C
    AT_MQTT_CLIENT_SUBSCRIBE_FAILED,                    // 0x600D
    AT_MQTT_CLIENT_UNSUBSCRIBE_FAILED,                  // 0x600E
    AT_MQTT_CLIENT_DISCONNECT_FAILED,                   // 0x600F
    AT_MQTT_LINK_ID_READ_FAILED,                        // 0x6010
    AT_MQTT_LINK_ID_VALUE_IS_WRONG,                     // 0x6011
    AT_MQTT_SCHEME_READ_FAILED,                         // 0x6012
    AT_MQTT_SCHEME_VALUE_IS_WRONG,                      // 0x6013
    AT_MQTT_CLIENT_ID_READ_FAILED,                      // 0x6014
    AT_MQTT_CLIENT_ID_IS_NULL,                          // 0x6015
    AT_MQTT_CLIENT_ID_IS_OVERLENGTH,                    // 0x6016
    AT_MQTT_USERNAME_READ_FAILED,                       // 0x6017
    AT_MQTT_USERNAME_IS_NULL,                           // 0x6018
    AT_MQTT_USERNAME_IS_OVERLENGTH,                     // 0x6019
    AT_MQTT_PASSWORD_READ_FAILED,                       // 0x601A
    AT_MQTT_PASSWORD_IS_NULL,                           // 0x601B
    AT_MQTT_PASSWORD_IS_OVERLENGTH,                     // 0x601C
    AT_MQTT_CERT_KEY_ID_READ_FAILED,                    // 0x601D
    AT_MQTT_CERT_KEY_ID_VALUE_IS_WRONG,                 // 0x601E
    AT_MQTT_CA_ID_READ_FAILED,                          // 0x601F
    AT_MQTT_CA_ID_VALUE_IS_WRONG,                       // 0x6020
    AT_MQTT_CA_LENGTH_ERROR,                            // 0x6021
    AT_MQTT_CA_READ_FAILED,                             // 0x6022
    AT_MQTT_CERT_LENGTH_ERROR,                          // 0x6023
    AT_MQTT_CERT_READ_FAILED,                           // 0x6024
    AT_MQTT_KEY_LENGTH_ERROR,                           // 0x6025
    AT_MQTT_KEY_READ_FAILED,                            // 0x6026
    AT_MQTT_PATH_READ_FAILED,                           // 0x6027
    AT_MQTT_PATH_IS_NULL,                               // 0x6028
    AT_MQTT_PATH_IS_OVERLENGTH,                         // 0x6029
    AT_MQTT_VERSION_READ_FAILED,                        // 0x602A
    AT_MQTT_KEEPALIVE_READ_FAILED,                      // 0x602B
    AT_MQTT_KEEPALIVE_IS_NULL,                          // 0x602C
    AT_MQTT_KEEPALIVE_VALUE_IS_WRONG,                   // 0x602D
    AT_MQTT_DISABLE_CLEAN_SESSION_READ_FAILED,          // 0x602E
    AT_MQTT_DISABLE_CLEAN_SESSION_VALUE_IS_WRONG,       // 0x602F
    AT_MQTT_LWT_TOPIC_READ_FAILED,                      // 0x6030
    AT_MQTT_LWT_TOPIC_IS_NULL,                          // 0x6031
    AT_MQTT_LWT_TOPIC_IS_OVERLENGTH,                    // 0x6032
    AT_MQTT_LWT_MSG_READ_FAILED,                        // 0x6033
    AT_MQTT_LWT_MSG_IS_NULL,                            // 0x6034
    AT_MQTT_LWT_MSG_IS_OVERLENGTH,                      // 0x6035
    AT_MQTT_LWT_QOS_READ_FAILED,                        // 0x6036
    AT_MQTT_LWT_QOS_VALUE_IS_WRONG,                     // 0x6037
    AT_MQTT_LWT_RETAIN_READ_FAILED,                     // 0x6038
    AT_MQTT_LWT_RETAIN_VALUE_IS_WRONG,                  // 0x6039
    AT_MQTT_HOST_READ_FAILED,                           // 0x603A
    AT_MQTT_HOST_IS_NULL,                               // 0x603B
    AT_MQTT_HOST_IS_OVERLENGTH,                         // 0x603C
    AT_MQTT_PORT_READ_FAILED,                           // 0x603D
    AT_MQTT_PORT_VALUE_IS_WRONG,                        // 0x603E
    AT_MQTT_RECONNECT_READ_FAILED,                      // 0x603F
    AT_MQTT_RECONNECT_VALUE_IS_WRONG,                   // 0x6040
    AT_MQTT_TOPIC_READ_FAILED,                          // 0x6041
    AT_MQTT_TOPIC_IS_NULL,                              // 0x6042
    AT_MQTT_TOPIC_IS_OVERLENGTH,                        // 0x6043
    AT_MQTT_DATA_READ_FAILED,                           // 0x6044
    AT_MQTT_DATA_IS_NULL,                               // 0x6045
    AT_MQTT_DATA_IS_OVERLENGTH,                         // 0x6046
    AT_MQTT_QOS_READ_FAILED,                            // 0x6047
    AT_MQTT_QOS_VALUE_IS_WRONG,                         // 0x6048
    AT_MQTT_RETAIN_READ_FAILED,                         // 0x6049
    AT_MQTT_RETAIN_VALUE_IS_WRONG,                      // 0x604A
    AT_MQTT_PUBLISH_LENGTH_READ_FAILED,                 // 0x604B
    AT_MQTT_PUBLISH_LENGTH_VALUE_IS_WRONG,              // 0x604C
    AT_MQTT_RECV_LENGTH_IS_WRONG,                       // 0x604D
    AT_MQTT_CREATE_SEMA_FAILED,                         // 0x604E
    AT_MQTT_CREATE_EVENT_GROUP_FAILED,                  // 0x604F

其他说明

  • AT+MQTTCONN 之外, MQTT 相关命令最长会在 10s 内返回, 例如路由已无法连接因特网, AT+MQTTPUB 将在 10s 内返回.
  • 如果 AT+MQTTCONN 是基于 TLS 连接的, 每个步骤的超时时间为 10s, 总的超时时间取决于服务器的交互步骤.
  • 一旦 MQTT 连接断开, 将打印 +MQTTDISCONNECTED:
  • 一旦 MQTT 连接成功, 将打印 +MQTTCONNECTED:,,<"host">,port,<"path">,

测试命令一: MQTT over TCP (需要本地创建 MQTT Broker)

使用 MQTT over TCP 连接 MQTT broker, 假设 MQTT broker IP 为 192.168.31.113, 端口为 1883, 则订阅和发布 topic 参考步骤如下:

AT+MQTTUSERCFG=0,1,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.31.113",1883,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0

测试命令二: MQTT over TLS (需要本地创建 MQTT Broker)

使用 MQTT over TLS 连接 MQTT broker, 假设 MQTT broker IP 为 192.168.31.113, 端口为 1883, 则订阅和发布 topic 参考步骤如下:

AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
AT+CIPSNTPTIME?
AT+MQTTUSERCFG=0,3,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONNCFG=0,0,0,"lwtt","lwtm",0,0
AT+MQTTCONN=0,"192.168.31.113",1883,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0

测试命令三: MQTT over WSS

使用 MQTT over WSS 连接 MQTT broker: iot.eclipse.org(当前 iot.eclipse.org 开放测试端口为 443),则订阅和发布 topic 参考步骤如下:

AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
AT+CIPSNTPTIME?
AT+MQTTUSERCFG=0,7,"ESP32","espressif","1234567890",0,0,"wss"
AT+MQTTCONN=0,"iot.eclipse.org",443,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0

你可能感兴趣的:(ESP-AT)