MQTT AT Commands

[中文]

• Introduction

• AT+MQTTUSERCFG: Set MQTT user configuration

• AT+MQTTLONGCLIENTID: Set MQTT client ID

• AT+MQTTLONGUSERNAME: Set MQTT username

• AT+MQTTLONGPASSWORD: Set MQTT password

• AT+MQTTCONNCFG: Set configuration of MQTT connection

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

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

• AT+MQTTCONN: Connect to MQTT Brokers

• AT+MQTTPUB: Publish MQTT Messages in string

• AT+MQTTPUBRAW: Publish long MQTT messages

• AT+MQTTSUB: Subscribe to MQTT topics

• AT+MQTTUNSUB: Unsubscribe from MQTT topics

• AT+MQTTCLEAN: Close MQTT connections

• MQTT AT Error Codes

• MQTT AT Notes

Introduction

Important

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

• Disable Component config -> AT -> AT MQTT command support

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 <scheme> is configured to 3, 5, 8, or 10, in order to check the server certificate validity period, please make sure ESP32-C3 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.)

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

• The command AT+MQTTUSERCFG can also set MQTT client ID. The differences between the two commands include:

  • You can use AT+MQTTLONGCLIENTID to set a relatively long client ID since there is a limitation on the length of the AT+MQTTUSERCFG command.

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

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

• The command AT+MQTTUSERCFG can also set MQTT username. The differences between the two commands include:

  • You can use AT+MQTTLONGUSERNAME to set a relatively long username since there is a limitation on the length of the AT+MQTTUSERCFG command.

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

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

• The command AT+MQTTUSERCFG can also set MQTT password. The differences between the two commands include:

  • You can use AT+MQTTLONGPASSWORD to set a relatively long password since there is a limitation on the length of the AT+MQTTUSERCFG command.

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

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.

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-C3","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-C3","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-C3 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>

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.

• <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>

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.

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-C3","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>

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.

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. It supports subscribing to multiple topics.

Command:

AT+MQTTSUB=<LinkID>,<"topic">,<qos>

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.

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">

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.

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

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

• In general, AT MQTT commands responds within 10 s, except the command AT+MQTTCONN. For example, if the router fails to access the Internet, the command AT+MQTTPUB will respond within 10 s. But the command AT+MQTTCONN may need more time due to packet retransmission in a bad network environment.

• If the AT+MQTTCONN is based on a TLS connection, the timeout of each packet is 10 s, and the total timeout will be much longer depending on the handshake packets count.

• 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>.

Provide feedback about this document