.. _MQTT-AT: MQTT AT Commands ================ :link_to_translation:`en:[English]` - :ref:`AT+MQTTUSERCFG `：设置 MQTT 用户属性 - :ref:`AT+MQTTLONGCLIENTID `：设置 MQTT 客户端 ID - :ref:`AT+MQTTLONGUSERNAME `：设置 MQTT 登陆用户名 - :ref:`AT+MQTTLONGPASSWORD `：设置 MQTT 登陆密码 - :ref:`AT+MQTTCONNCFG `：设置 MQTT 连接属性 - :ref:`AT+MQTTCONN `：连接 MQTT Broker - :ref:`AT+MQTTPUB `：发布 MQTT 消息（字符串） - :ref:`AT+MQTTPUBRAW `：发布 MQTT 消息（二进制） - :ref:`AT+MQTTSUB `：订阅 MQTT Topic - :ref:`AT+MQTTUNSUB `：取消订阅 MQTT Topic - :ref:`AT+MQTTCLEAN `：断开 MQTT 连接 - :ref:`MQTT AT 错误码 ` - :ref:`MQTT AT 说明 ` .. _cmd-MQTTUSERCFG: :ref:`AT+MQTTUSERCFG `：设置 MQTT 用户属性 ------------------------------------------------------------- 设置命令 ^^^^^^^^ **功能：** 配置 MQTT 用户属性 **命令：** :: AT+MQTTUSERCFG=,,<"client_id">,<"username">,<"password">,,,<"path"> **响应：** :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：由于 ESP8266 内存限制，不支持 MQTT over TLS，即 ```` 只能取 1 或 6。 - 1: MQTT over TCP； - 2: MQTT over TLS（不校验证书）； - 3: MQTT over TLS（校验 server 证书）； - 4: MQTT over TLS（提供 client 证书）； - 5: MQTT over TLS（校验 server 证书并且提供 client 证书）； - 6: MQTT over WebSocket（基于 TCP）； - 7: MQTT over WebSocket Secure（基于 TLS，不校验证书）； - 8: MQTT over WebSocket Secure（基于 TLS，校验 server 证书）； - 9: MQTT over WebSocket Secure（基于 TLS，提供 client 证书）； - 10: MQTT over WebSocket Secure（基于 TLS，校验 server 证书并且提供 client 证书）。 - ****：MQTT 客户端 ID，最大长度：256 字节。 - ****：用户名，用于登陆 MQTT broker，最大长度：64 字节。 - ****：密码，用于登陆 MQTT broker，最大长度：64 字节。 - ****：证书 ID，目前 ESP-AT 仅支持一套 cert 证书，参数为 0。 - ****：CA ID，目前 ESP-AT 仅支持一套 CA 证书，参数为 0。 - ****：资源路径，最大长度：32 字节。 说明 ^^^^ - 每条 AT 命令的总长度不能超过 256 字节。 .. _cmd-MQTTLONGCLIENTID: :ref:`AT+MQTTLONGCLIENTID `：设置 MQTT 客户端 ID ------------------------------------------------------------ 设置命令 ^^^^^^^^ **功能：** 设置 MQTT 客户端 ID **命令：** :: AT+MQTTLONGCLIENTID=, **响应：** :: OK > 上述响应表示 AT 已准备好接收 MQTT 客户端 ID，此时您可以输入客户端 ID，当 AT 接收到的客户端 ID 长度达到 ```` 后，返回： :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT 客户端 ID 长度。范围：[1,1024]。 说明 ^^^^ - :ref:`AT+MQTTUSERCFG ` 命令也可以设置 MQTT 客户端 ID，二者之间的差别包括： - ``AT+MQTTLONGCLIENTID`` 命令可以用来设置相对较长的客户端 ID，因为 ``AT+MQTTUSERCFG`` 命令的长度受限； - 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTLONGCLIENTID``。 .. _cmd-MQTTLONGUSERNAME: :ref:`AT+MQTTLONGUSERNAME `：设置 MQTT 登陆用户名 ---------------------------------------------------------- 设置命令 ^^^^^^^^ **功能：** 设置 MQTT 用户名 **命令：** :: AT+MQTTLONGUSERNAME=, **响应：** :: OK > 上述响应表示 AT 已准备好接收 MQTT 用户名，此时您可以输入 MQTT 用户名，当 AT 接收到的 MQTT 用户名长度达到 ```` 后，返回： :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT 用户名长度。范围：[1,1024]。 说明 ^^^^ - :ref:`AT+MQTTUSERCFG ` 命令也可以设置 MQTT 用户名，二者之间的差别包括： - ``AT+MQTTLONGUSERNAME`` 命令可以用来设置相对较长的用户名，因为 ``AT+MQTTUSERCFG`` 命令的长度受限。 - 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTLONGUSERNAME``。 .. _cmd-MQTTLONGPASSWORD: :ref:`AT+MQTTLONGPASSWORD `：设置 MQTT 登陆密码 ------------------------------------------------------------ 设置命令 ^^^^^^^^ **功能：** 设置 MQTT 密码 **命令：** :: AT+MQTTLONGPASSWORD=, **响应：** :: OK > 上述响应表示 AT 已准备好接收 MQTT 密码，此时您可以输入 MQTT 密码，当 AT 接收到的 MQTT 密码长度达到 ```` 后，返回： :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT 密码长度。范围：[1,1024]。 说明 ^^^^ - :ref:`AT+MQTTUSERCFG ` 命令也可以设置 MQTT 密码，二者之间的差别包括： - ``AT+MQTTLONGPASSWORD`` 可以用来设置相对较长的密码，因为 ``AT+MQTTUSERCFG`` 命令的长度受限； - 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTLONGPASSWORD``。 .. _cmd-MQTTCONNCFG: :ref:`AT+MQTTCONNCFG `：设置 MQTT 连接属性 ------------------------------------------------------------------------- 设置命令 ^^^^^^^^ **功能：** 设置 MQTT 连接属性 **命令：** :: AT+MQTTCONNCFG=,,,<"lwt_topic">,<"lwt_msg">,, **响应：** :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT ping 超时时间，单位：秒。范围：[0,7200]。默认值：0，会被强制改为 120 秒。 - ****：设置 MQTT 清理会话标志，有关该参数的更多信息请参考 MQTT 3.1.1 协议中的 `Clean Session `_ 章节。 - 0: 使能清理会话 - 1: 禁用清理会话 - ****：遗嘱 topic，最大长度：128 字节。 - ****：遗嘱 message，最大长度：64 字节。 - ****：遗嘱 QoS，参数可选 0、1、2，默认值：0。 - ****：遗嘱 retain，参数可选 0 或 1，默认值：0。 .. _cmd-MQTTCONN: :ref:`AT+MQTTCONN `：连接 MQTT Broker -------------------------------------------------------- 查询命令 ^^^^^^^^ **功能：** 查询 ESP 设备已连接的 MQTT broker **命令：** :: AT+MQTTCONN? **响应：** :: +MQTTCONN:,,<"host">,,<"path">, OK 设置命令 ^^^^^^^^ **功能：** 连接 MQTT Broker **命令：** :: AT+MQTTCONN=,<"host">,, **响应：** :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT broker 域名，最大长度：128 字节。 - ****：MQTT broker 端口，最大端口：65535。 - ****：资源路径，最大长度：32 字节。 - ****： - 0: MQTT 不自动重连； - 1: MQTT 自动重连，会消耗较多的内存资源。 - ****：MQTT 状态： - 0: MQTT 未初始化； - 1: 已设置 ``AT+MQTTUSERCFG``； - 2: 已设置 ``AT+MQTTCONNCFG``； - 3: 连接已断开； - 4: 已建立连接； - 5: 已连接，但未订阅 topic； - 6: 已连接，已订阅过 topic。 - ****： - 1: MQTT over TCP； - 2: MQTT over TLS（不校验证书）； - 3: MQTT over TLS（校验 server 证书）； - 4: MQTT over TLS（提供 client 证书）； - 5: MQTT over TLS（校验 server 证书并且提供 client 证书）； - 6: MQTT over WebSocket（基于 TCP）； - 7: MQTT over WebSocket Secure（基于 TLS，不校验证书）； - 8: MQTT over WebSocket Secure（基于 TLS，校验 server 证书）； - 9: MQTT over WebSocket Secure（基于 TLS，提供 client 证书）； - 10: MQTT over WebSocket Secure（基于 TLS，校验 server 证书并且提供 client 证书）。 .. _cmd-MQTTPUB: :ref:`AT+MQTTPUB `：发布 MQTT 消息（字符串） --------------------------------------------------------------- 设置命令 ^^^^^^^^ **功能：** 通过 topic 发布 MQTT **字符串** 消息，若要发布 **二进制** 消息，请使用 :ref:`AT+MQTTPUBRAW ` 命令。 **命令：** :: AT+MQTTPUB=,<"topic">,<"data">,, **响应：** :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT topic，最大长度：128 字节。 - ****：MQTT 字符串消息。 - ****：发布消息的 QoS，参数可选 0、1、或 2，默认值：0。 - ****：发布 retain。 说明 ^^^^ - 每条 AT 命令的总长度不能超过 256 字节。 - 本命令不能发送数据 ``\0``，若需要发送该数据，请使用 :ref:`AT+MQTTPUBRAW ` 命令。 .. _cmd-MQTTPUBRAW: :ref:`AT+MQTTPUBRAW `：发布 MQTT 消息（二进制） ------------------------------------------------------------------ 设置命令 ^^^^^^^^ **功能：** 通过 topic 发布 MQTT **二进制** 消息 **命令：** :: AT+MQTTPUBRAW=,<"topic">,,, **响应：** :: OK > 符号 ``>`` 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 ```` 的值时，数据传输开始。 若传输成功，则 AT 返回： :: +MQTTPUB:OK 若传输失败，则 AT 返回： :: +MQTTPUB:FAIL 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT topic，最大长度：128 字节。 - ****：MQTT 消息长度，不同 ESP 设备的最大长度不同： - 对于 ESP32 设备：最大长度受到可利用内存的限制； - 对于 ESP8266 设备，最大长度受到可利用内存和 ``MQTT_BUFFER_SIZE_BYTE`` 宏的限制。该宏的默认值为 ``512``，可在 ``build.py menuconfig`` 中设置它的值，以此更改对最大长度的限制。该宏的值 = 消息的最大长度 + MQTT 报头长度（取决于 topic 名称的长度）。 - ****：发布消息的 QoS，参数可选 0、1、或 2，默认值：0。 - ****：发布 retain。 .. _cmd-MQTTSUB: :ref:`AT+MQTTSUB `：订阅 MQTT Topic -------------------------------------------------------- 查询命令 ^^^^^^^^ **功能：** 查询已订阅的 topic **命令：** :: AT+MQTTSUB? **响应：** :: +MQTTSUB:,,<"topic1">, +MQTTSUB:,,<"topic2">, +MQTTSUB:,,<"topic3">, ... OK 设置命令 ^^^^^^^^ **功能：** 订阅指定 MQTT topic 的指定 QoS，支持订阅多个 topic **命令：** :: AT+MQTTSUB=,<"topic">, **响应：** :: OK 当 AT 接收到已订阅的 topic 的 MQTT 消息时，返回： :: +MQTTSUBRECV:,<"topic">,,data 若已订阅过该 topic，则返回： :: ALREADY SUBSCRIBE 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT 状态： - 0: MQTT 未初始化； - 1: 已设置 ``AT+MQTTUSERCFG``； - 2: 已设置 ``AT+MQTTCONNCFG``； - 3: 连接已断开； - 4: 已建立连接； - 5: 已连接，但未订阅 topic； - 6: 已连接，已订阅过 MQTT topic。 - ****：订阅的 topic。 - ****：订阅的 QoS。 .. _cmd-MQTTUNSUB: :ref:`AT+MQTTUNSUB `：取消订阅 MQTT Topic -------------------------------------------------------------- 设置命令 ^^^^^^^^ **功能：** 客户端取消订阅指定 topic，可多次调用本命令，以取消订阅不同的 topic。 **命令：** :: AT+MQTTUNSUB=,<"topic"> **响应：** :: OK 若未订阅过该 topic，则返回： :: NO UNSUBSCRIBE OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 - ****：MQTT topic，最大长度：128 字节。 .. _cmd-MQTTCLEAN: :ref:`AT+MQTTCLEAN `：断开 MQTT 连接 ------------------------------------------------------------ 设置命令 ^^^^^^^^ **功能：** 断开 MQTT 连接，释放资源。 **命令：** :: AT+MQTTCLEAN= **响应：** :: OK 参数 ^^^^ - ****：当前仅支持 link ID 0。 .. _MQTTErrCod: :ref:`MQTT AT 错误码 ` ------------------------------------- MQTT 错误码以 ``ERR CODE:0x<%08x>`` 形式打印。 .. list-table:: :header-rows: 1 :widths: 15 5 * - 错误类型 - 错误码 * - 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_MQTT_URI_PARSE_FAILED - 0x6050 * - AT_MQTT_IN_DISCONNECTED_STATE - 0x6051 * - AT_MQTT_HOSTNAME_VERIFY_FAILED - 0x6052 .. _MQTTNote: :ref:`MQTT AT 说明 ` ------------------------------- - 一般来说，AT MQTT 命令都会在 10 秒内响应，但 ``AT+MQTTCONN`` 命令除外。例如，如果路由器不能上网，命令 ``AT+MQTTPUB`` 会在 10 秒内响应，但 ``AT+MQTTCONN`` 命令在网络环境不好的情况下，可能需要更多的时间用来重传数据包。 - 如果 ``AT+MQTTCONN`` 是基于 TLS 连接，每个数据包的超时时间为 10 秒，则总超时时间会根据握手数据包的数量而变得更长。 - 当 MQTT 连接断开时，会提示 ``+MQTTDISCONNECTED:`` 消息。 - 当 MQTT 连接建立时，会提示 ``+MQTTCONNECTED:,,<"host">,port,<"path">,`` 消息。