MQTT AT Commands

[中文]

Introduction

Important

  • Currently, AT firmware for ESP32-S2 series supports MQTT Version 3.1.1.

  • The default AT firmware supports all the AT commands mentioned on this page. If you don’t need ESP32-S2 to support MQTT commands, you can compile the ESP-AT project by following the steps in Compile ESP-AT Project Locally documentation. In step 5 of the project configuration, make the following selections:

    • Disable Component config > AT > AT MQTT command support

  • For MQTT connection to local Broker examples, see MQTT AT Examples.

  • For MQTT connection to AWS IoT examples, see MQTT Cloud Connection AT Examples.

AT+MQTTUSERCFG: Set MQTT User Configuration

Set Command

Function:

Set MQTT User Configuration.

Command:

AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">

Response:

OK

Parameters

  • <LinkID>: currently only supports link ID 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. Maximum length: 256 bytes.

  • <”username”>: the username to login to the MQTT broker. Maximum length: 64 bytes.

  • <”password”>: the password to login to the MQTT broker. Maximum length: 64 bytes.

  • <cert_key_ID>: certificate ID. Currently, ESP-AT only supports one certificate for ID 0.

  • <CA_ID>: CA ID. Currently, ESP-AT only supports one CA for ID 0.

  • <”path”>: the path of the resource. Maximum length: 32 bytes.

Note

  • The length of the entire AT command should be less than 256 bytes.

  • If you want to use your own certificate at runtime, use the AT+SYSMFG command to update the MQTT certificate (for detailed steps, please refer to AT+SYSMFG command examples, the certificate configuration method is the same as SSL certificates). If you want to pre-burn your own certificate, please refer to How to Update PKI Configuration.

  • If <scheme> is configured to 3, 5, 8, or 10, in order to check the server certificate validity period, please make sure ESP32-S2 has obtained the current time before sending the AT+MQTTCONN command. (You can send AT+CIPSNTPCFG command to configure SNTP and obtain the current time, and send AT+CIPSNPTIME? command to query the current time.)

  • For TLS protocol version configuration, please refer to the modify tls protocol version note.

AT+MQTTLONGCLIENTID: Set MQTT Client ID

Set Command

Function:

Set MQTT Client ID.

Command:

AT+MQTTLONGCLIENTID=<LinkID>,<length>

Response:

OK

>

This response indicates that AT is ready for receiving MQTT Client ID. You should enter the Client ID, and when the Client ID length reaches the <length> value, the system returns:

OK

Parameters

  • <LinkID>: currently only supports link ID 0.

  • <length>: MQTT client ID length. Range: [1,1024].

Notes

AT+MQTTLONGUSERNAME: Set MQTT Username

Set Command

Function:

Set MQTT username.

Command:

AT+MQTTLONGUSERNAME=<LinkID>,<length>

Response:

OK

>

This response indicates that AT is ready for receiving MQTT username. You should enter the MQTT username, and when the MQTT username length reaches the <length> value, the system returns:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <length>: MQTT username length. Range: [1,1024].

Notes

AT+MQTTLONGPASSWORD: Set MQTT Password

Set Command

Function:

Set MQTT password.

Command:

AT+MQTTLONGPASSWORD=<LinkID>,<length>

Response:

OK

>

This response indicates that AT is ready for receiving MQTT password. You should enter the MQTT password, and when the MQTT password length reaches the <length> value, the system returns:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <length>: MQTT password length. Range: [1,1024].

Notes

AT+MQTTCONNCFG: Set Configuration of MQTT Connection

Set Command

Function:

Set configuration of MQTT Connection.

Command:

AT+MQTTCONNCFG=<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>

Response:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <keepalive>: timeout of MQTT ping. Unit: second. Range [0,7200]. The default value is 0, which will be force-changed to 120 s.

  • <disable_clean_session>: set MQTT clean session. For more details about this parameter, please refer to the section Clean Session in MQTT Version 3.1.1.

    • 0: Enable clean session.

    • 1: Disable clean session.

  • <”lwt_topic”>: LWT (Last Will and Testament) message topic. Maximum length: 128 bytes.

  • <”lwt_msg”>: LWT message. Maximum length: 128 bytes.

  • <lwt_qos>: LWT QoS, which can be set to 0, 1, or 2. Default: 0.

  • <lwt_retain>: LWT retain, which can be set to 0 or 1. Default: 0.

Note

AT+MQTTALPN: Set MQTT Application Layer Protocol Negotiation (ALPN)

Set Command

Function:

Set MQTT Application Layer Protocol Negotiation (ALPN).

Command:

AT+MQTTALPN=<LinkID>,<alpn_counts>[,<"alpn">][,<"alpn">][,<"alpn">]

Response:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <alpn_counts>: the number of <”alpn”> parameters. Range: [0,5].

    • 0: Clean the MQTT ALPN configuration.

    • [1,5]: Set the MQTT ALPN configuration.

  • <”alpn”>: you can send more than one ALPN in ClientHello to the server.

Notes

  • The length of the entire AT command should be less than 256 bytes.

  • MQTT ALPN will be effective only if the MQTT connection is based on TLS or WSS.

  • You should set AT+MQTTALPN after setting the command AT+MQTTUSERCFG.

Example

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com"
AT+MQTTUSERCFG=0,5,"ESP32-S2","espressif","1234567890",0,0,""
AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us"
AT+MQTTCONN=0,"192.168.200.2",8883,1

AT+MQTTSNI: Set MQTT Server Name Indication (SNI)

Set Command

Function:

Set MQTT Server Name Indication (SNI).

Command:

AT+MQTTSNI=<LinkID>,<"sni">

Response:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <”sni”>: MQTT Server Name Indication. You can send it in ClientHello to the server.

Notes

  • The length of the entire AT command should be less than 256 bytes.

  • MQTT SNI will be effective only if the MQTT connection is based on TLS or WSS.

  • You should set AT+MQTTSNI after setting the command AT+MQTTUSERCFG.

Example

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com"
AT+MQTTUSERCFG=0,5,"ESP32-S2","espressif","1234567890",0,0,""
AT+MQTTSNI=0,"my_specific_prefix.iot.my_aws_region.amazonaws.com"
AT+MQTTCONN=0,"my_specific_prefix.iot.my_aws_region.amazonaws.com",8883,1

AT+MQTTCONN: Connect to MQTT Brokers

Query Command

Function:

Query the MQTT broker that ESP32-S2 are connected to.

Command:

AT+MQTTCONN?

Response:

+MQTTCONN:<LinkID>,<state>,<scheme>,<"host">,<port>,<"path">,<reconnect>
OK

Set Command

Function:

Connect to an MQTT broker.

Command:

AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>[,<timeout_ms>]

Response:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <”host”>: MQTT broker domain. Maximum length: 128 bytes.

  • <port>: MQTT broker port. Maximum: port 65535.

  • <”path”>: path. Maximum length: 32 bytes.

  • <reconnect>:

    • 0: MQTT will not reconnect automatically. If MQTT connection established and then disconnected, you cannot use this command to reestablish MQTT connection. Please send AT+MQTTCLEAN=0 command to clean MQTT connection first, reconfigure the connection parameters, and then establish a new MQTT connection.

    • 1: MQTT will reconnect automatically. It takes more resources.

  • <timeout_ms>: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.

  • <state>: MQTT state.

    • 0: MQTT uninitialized.

    • 1: Already set AT+MQTTUSERCFG.

    • 2: Already set AT+MQTTCONNCFG.

    • 3: Connection disconnected.

    • 4: Connection established.

    • 5: Connected, but did not subscribe to any topic.

    • 6: Connected, and subscribed to MQTT topics.

  • <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, verify no certificate).

    • 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: Publish MQTT Messages in String

Set Command

Function:

Publish MQTT messages in string to a defined topic. If the amount of data you publish is relatively large, and the length of a single AT command has exceeded the threshold of 256, please use the AT+MQTTPUBRAW command.

Command:

AT+MQTTPUB=<LinkID>,<"topic">,<"data">,<qos>,<retain>[,<timeout_ms>]

Response:

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <”topic”>: MQTT topic. Maximum length: 128 bytes.

  • <data>: MQTT message in string.

  • <qos>: QoS of message, which can be set to 0, 1, or 2. Default: 0.

  • <retain>: retain flag.

  • <timeout_ms>: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.

Notes

  • The length of the entire AT command should be less than 256 bytes.

  • This command cannot send data \0. If you need to send \0, please use the command AT+MQTTPUBRAW instead.

Example

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+MQTTUSERCFG=0,1,"ESP32-S2","espressif","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.10.234",1883,0
AT+MQTTPUB=0,"topic","\"{\"timestamp\":\"20201121085253\"}\"",0,0  // When sending this command, please pay attention to whether special characters need to be escaped.

AT+MQTTPUBRAW: Publish Long MQTT Messages

Set Command

Function:

Publish long MQTT messages to a defined topic. If the amount of data you publish is relatively small, and the length of a single AT command is not greater than the threshold of 256, you also can use the AT+MQTTPUB command.

Command:

AT+MQTTPUBRAW=<LinkID>,<"topic">,<length>,<qos>,<retain>[,<timeout_ms>]

Response:

OK
>

The symbol > indicates that AT is ready for receiving serial data, and you can enter the data now. When the requirement of message length determined by the parameter <length> is met, the transmission starts.

If the transmission is successful, AT returns:

+MQTTPUB:OK

Otherwise, it returns:

+MQTTPUB:FAIL

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <”topic”>: MQTT topic. Maximum length: 128 bytes.

  • <length>: length of MQTT message. The maximum length is limited by available memory.

  • <qos>: QoS of the published message, which can be set to 0, 1, or 2. Default is 0.

  • <retain>: retain flag.

  • <timeout_ms>: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.

AT+MQTTSUB: Subscribe to MQTT Topics

Query Command

Function:

List all MQTT topics that have been already subscribed.

Command:

AT+MQTTSUB?

Response:

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

Set Command

Function:

Subscribe to defined MQTT topics with defined QoS. Multiple topics are available for subscription (up to 10 topics can be subscribed).

Command:

AT+MQTTSUB=<LinkID>,<"topic">,<qos>[,<timeout_ms>]

Response:

OK

When AT receives MQTT messages of the subscribed topic, it will prompt:

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

If the topic has been subscribed before, it will prompt:

ALREADY SUBSCRIBE

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <state>: MQTT state.

    • 0: MQTT uninitialized.

    • 1: Already set AT+MQTTUSERCFG.

    • 2: Already set AT+MQTTCONNCFG.

    • 3: Connection disconnected.

    • 4: Connection established.

    • 5: Connected, but subscribe to no topic.

    • 6: Connected, and subscribed to MQTT topics.

  • <”topic”>: the topic that is subscribed to.

  • <qos>: the QoS that is subscribed to.

  • <timeout_ms>: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.

Note

  • Due to MTU limitations or traffic policy management on each WAN routing node, a single message sent by the MQTT broker may eventually be split into multiple messages received by the ESP32-S2 device. Therefore, ESP32-S2 may receive multiple +MQTTSUBRECV messages.

  • If the ESP32-S2 device receives an MQTT message whose length exceeds 1024 bytes (including the MQTT header and MQTT payload), it will also be split into multiple +MQTTSUBRECV messages. In this case, you can increase the MQTT buffer size as follows to avoid this situation.

    • ./build.py menuconfig > Component config > ESP-MQTT Configurations > MQTT Using custom configurations

    • ./build.py menuconfig > Component config > ESP-MQTT Configurations > MQTT Using custom configurations > Default MQTT Buffer Size > 1460

AT+MQTTUNSUB: Unsubscribe from MQTT Topics

Set Command

Function:

Unsubscribe the client from defined topics. This command can be called multiple times to unsubscribe from different topics.

Command:

AT+MQTTUNSUB=<LinkID>,<"topic">[,<timeout_ms>]

Response:

OK

If the topic has not been subscribed, AT will prompt:

NO UNSUBSCRIBE

OK

Parameters

  • <LinkID>: only supports link ID 0 currently.

  • <”topic”>: MQTT topic. Maximum length: 128 bytes.

  • <timeout_ms>: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.

AT+MQTTCLEAN: Close MQTT Connections

Set Command

Function:

Close the MQTT connection and release the resource.

Command:

AT+MQTTCLEAN=<LinkID>

Response:

OK

Parameter

  • <LinkID>: only supports link ID 0 currently.

MQTT AT Error Codes

When AT+SYSLOG=1 is enabled, AT reports MQTT errors in two messages:

  • ERR CODE:0x<%08x>: Returned synchronously when an MQTT command is executed. It means this command failed.

  • +MQTTERR: A URC reported when the MQTT client generates MQTT_EVENT_ERROR. It is generally asynchronous.

During one connection failure, both messages may appear. ERR CODE is the result of this command. +MQTTERR is the transport error or the broker connection refusal in that event.

+MQTTERR

When MQTT_EVENT_ERROR occurs, AT generally outputs:

+MQTTERR:<LinkID>,<error_type>,<connect_return_code>,<esp_tls_err>,<tls_err>,<cert_flags>,<sock_errno>

<LinkID> and <error_type> are decimal. The other parameters are hexadecimal and start with 0x.

Parameters:

  • <LinkID>: MQTT connection ID. Only supports link ID 0 currently.

  • <error_type>: Error source.

  • <connect_return_code>: Connect return code reported by the broker in CONNACK. 0x0 means the connection was accepted.

  • <esp_tls_err>: TLS stack error code. Typically defined in esp_err.h and esp_tls_errors.h. 0x0 means no error at this layer.

  • <tls_err>: TLS error code. Typically defined in mbedtls/ssl.h. 0x0 means no TLS error.

  • <cert_flags>: Certificate verification flags. Typically defined in mbedtls/x509.h. 0x0 means verification succeeded or was not performed.

  • <sock_errno>: Socket errno. Typically defined in errno.h. 0x0 means no socket error.

<error_type> values:

<error_type>

Description

1

Transport error, including TCP, TLS, and socket errors. <connect_return_code> is 0x0

2

The broker refused the connection. <connect_return_code> is 0x1 to 0x5. <esp_tls_err>, <tls_err>, <cert_flags>, and <sock_errno> are 0x0

<connect_return_code> values:

<connect_return_code>

Description

0x0

Connection accepted

0x1

Unacceptable protocol version

0x2

Identifier rejected

0x3

Server unavailable

0x4

Bad user name or password

0x5

Not authorized

ERR CODE

When an MQTT command fails, AT returns this code synchronously. The MQTT Error code will be prompted as ERR CODE:0x<%08x>.

Error Type

Error Code

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

MQTT AT Notes

  • When the MQTT connection ends, it will prompt the message +MQTTDISCONNECTED:<LinkID>.

  • When the MQTT connection established, it will prompt the message +MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect>.

  • When the MQTT client generates MQTT_EVENT_ERROR, it will prompt the +MQTTERR message. This message is generally asynchronous. The error code returned synchronously during MQTT command execution is ERR CODE in the same section.

Provide feedback about this document