MQTT AT Examples

[中文]

This document provides detailed command examples to illustrate how to utilize MQTT AT Commands on ESP32-C2.

Important

  • The examples described in this document are based on the situation that Wi-Fi has been connected.

MQTT over TCP (with a local MQTT broker)(suitable for a small amount of data)

Below is an example of using two ESP32-C2 development boards, one as a MQTT publisher (only as MQTT publisher role), the other one as a MQTT subscriber (only as MQTT subscriber role).

The example shows how to establish MQTT connections over TCP. You need to first create a local MQTT broker. For example, the MQTT broker’s IP address is 192.168.3.102, and the port is 8883.

Important

In the step, the operations starting with ESP32-C2 MQTT publisher only need to be executed at ESP32-C2 MQTT publisher, and the operations starting with ESP32-C2 MQTT subscriber only need to be executed at ESP32-C2 MQTT subscriber. If the operation is not specified on which side it is executed, it needs to be executed on both the publisher side and the subscriber side.

  1. Set MQTT user configuration.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTUSERCFG=0,1,"publisher","espressif","123456789",0,0,""
    

    Response:

    OK
    

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTUSERCFG=0,1,"subscriber","espressif","123456789",0,0,""
    

    Response:

    OK
    
  2. Connect to MQTT brokers.

    Command:

    AT+MQTTCONN=0,"192.168.3.102",8883,1
    

    Response:

    +MQTTCONNECTED:0,1,"192.168.3.102","8883","",1
    
    OK
    

    Note:

    • The MQTT broker domain or MQTT broker IP address you enter may be different from those in the above command.

  3. Subscribe to MQTT topics.

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTSUB=0,"topic",1
    

    Response:

    OK
    
  4. Publish MQTT messages in string.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTPUB=0,"topic","test",1,0
    

    Response:

    OK
    

    Note:

    • If the ESP32-C2 MQTT publisher successfully publishes the message, following message will be prompted on the ESP32-C2 MQTT subscriber.

      +MQTTSUBRECV:0,"topic",4,test
      
  5. Close MQTT connections.

    Command:

    AT+MQTTCLEAN=0
    

    Response:

    OK
    

MQTT over TCP (with a local MQTT broker)(suitable for large amounts of data)

Below is an example of using two ESP32-C2 development boards, one as a MQTT publisher (only as MQTT publisher role), the other one as a MQTT subscriber (only as MQTT subscriber role).

The example shows how to establish MQTT connections over TCP. You need to first create a local MQTT broker. For example, the MQTT broker’s IP address is 192.168.3.102, and the port is 8883.

If the amount of data you publish is relatively large, and the length of a single AT command has exceeded the threshold of 256, it is recommended that you use the AT+MQTTPUBRAW command.

Important

In the step, the operations starting with ESP32-C2 MQTT publisher only need to be executed at ESP32-C2 MQTT publisher, and the operations starting with ESP32-C2 MQTT subscriber only need to be executed at ESP32-C2 MQTT subscriber. If the operation is not specified on which side it is executed, it needs to be executed on both the publisher side and the subscriber side.

  1. Set MQTT user configuration.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTUSERCFG=0,1,"publisher","espressif","123456789",0,0,""
    

    Response:

    OK
    

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTUSERCFG=0,1,"subscriber","espressif","123456789",0,0,""
    

    Response:

    OK
    
  2. Connect to MQTT brokers.

    Command:

    AT+MQTTCONN=0,"192.168.3.102",8883,1
    

    Response:

    +MQTTCONNECTED:0,1,"192.168.3.102","8883","",1
    
    OK
    

    Note:

    • The MQTT broker domain or MQTT broker IP address you enter may be different from those in the above command.

  3. Subscribe to MQTT topics.

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTSUB=0,"topic",1
    

    Response:

    OK
    
  4. Publish MQTT messages in string.

    Assume the data you want to publish is as follows, length is 427 bytes.

    {"headers": {"Accept": "application/json","Accept-Encoding": "gzip, deflate","Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7","Content-Length": "0","Host": "httpbin.org","Origin": "http://httpbin.org","Referer": "http://httpbin.org/","User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36","X-Amzn-Trace-Id": "Root=1-6150581e-1ad4bd5254b4bf5218070413"}}
    

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTPUBRAW=0,"topic",427,0,0
    

    Response:

    OK
    
    >
    

    This response indicates that AT is ready for receiving serial data. You should enter the data, and when the data length reaches the <length> value, the transmission of data starts.

    +MQTTPUB:OK
    

    Note:

    • After AT outputs the > character, the special characters in the data does not need to be escaped through the escape character, and it does not need to end with a new line(CR-LF).

    • If the ESP32-C2 MQTT publisher successfully publishes the message, following message will be prompted on the ESP32-C2 MQTT subscriber.

      +MQTTSUBRECV:0,"topic",427,{"headers": {"Accept": "application/json","Accept-Encoding": "gzip, deflate","Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7","Content-Length": "0","Host": "httpbin.org","Origin": "http://httpbin.org","Referer": "http://httpbin.org/","User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36","X-Amzn-Trace-Id": "Root=1-6150581e-1ad4bd5254b4bf5218070413"}}
      
  5. Close MQTT connections.

    Command:

    AT+MQTTCLEAN=0
    

    Response:

    OK
    

MQTT over TLS (with a local MQTT broker)

Below is an example of using two ESP32-C2 development boards, one as a MQTT publisher (only as MQTT publisher role), the other one as a MQTT subscriber (only as MQTT subscriber role).

The example shows how to establish MQTT connections over TLS. You need to first create a local MQTT broker. For example, the MQTT broker’s IP address is 192.168.3.102, and port is 8883.

Important

In the step, the operations starting with ESP32-C2 MQTT publisher only need to be executed at ESP32-C2 MQTT publisher, and the operations starting with ESP32-C2 MQTT subscriber only need to be executed at ESP32-C2 MQTT subscriber. If the operation is not specified on which side it is executed, it needs to be executed on both the publisher side and the subscriber side.

  1. Set the time zone and the SNTP server.

    Command:

    AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
    

    Response:

    OK
    
  2. Query the SNTP time.

    Command:

    AT+CIPSNTPTIME?
    

    Response:

    +CIPSNTPTIME:Thu Sep  2 18:57:03 2021
    OK
    

    Note:

    • The time you obtained may be different from that in the above response.

    • Please make sure that the SNTP time must be a real and valid time and cannot be the time in 1970 or before.

    • The purpose of setting the time is to verify the validity period of the certificates during TLS authentication.

  3. Set MQTT user configuration.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTUSERCFG=0,4,"publisher","espressif","123456789",0,0,""
    

    Response:

    OK
    

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTUSERCFG=0,4,"subscriber","espressif","123456789",0,0,""
    

    Response:

    OK
    
  4. Set configuration of MQTT connection.

    Command:

    AT+MQTTCONNCFG=0,0,0,"lwtt","lwtm",0,0
    

    Response:

    OK
    
  5. Connect to MQTT brokers.

    Command:

    AT+MQTTCONN=0,"192.168.3.102",8883,1
    

    Response:

    +MQTTCONNECTED:0,4,"192.168.3.102","8883","",1
    
    OK
    

    Note:

    • The MQTT broker domain or MQTT broker IP address you enter may be different from those in the above command.

  6. Subscribe to MQTT topics.

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTSUB=0,"topic",1
    

    Response:

    OK
    
  7. Publish MQTT messages in string.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTPUB=0,"topic","test",1,0
    

    Response:

    OK
    

    Note:

    • If the ESP32-C2 MQTT publisher successfully publishes the message, following message will be prompted on the ESP32-C2 MQTT subscriber.

      +MQTTSUBRECV:0,"topic",4,test
      
  8. Close MQTT connections.

    Command:

    AT+MQTTCLEAN=0
    

    Response:

    OK
    

MQTT over WSS

Below is an example of using two ESP32-C2 development boards, one as a MQTT publisher (only as MQTT publisher role), the other one as a MQTT subscriber (only as MQTT subscriber role).

The example shows how to establish MQTT connections over WSS and how to communicate with a MQTT broker. For example, the MQTT broker’s domain name is mqtt.eclipseprojects.io, the path is mqtt, and the port is 443.

Important

In the step, the operations starting with ESP32-C2 MQTT publisher only need to be executed at ESP32-C2 MQTT publisher, and the operations starting with ESP32-C2 MQTT subscriber only need to be executed at ESP32-C2 MQTT subscriber. If the operation is not specified on which side it is executed, it needs to be executed on both the publisher side and the subscriber side.

  1. Set the time zone and the SNTP server.

    Command:

    AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
    

    Response:

    OK
    
  2. Query the SNTP time.

    Command:

    AT+CIPSNTPTIME?
    

    Response:

    +CIPSNTPTIME:Thu Sep  2 18:57:03 2021
    OK
    

    Note:

    • The time you obtained may be different from that in the above response.

    • Please make sure that the SNTP time must be a real and valid time and cannot be the time in 1970 or before.

    • The purpose of setting the time is to verify the validity period of the certificates during TLS authentication.

  3. Set MQTT user configuration.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTUSERCFG=0,7,"publisher","espressif","1234567890",0,0,"mqtt"
    

    Response:

    OK
    

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTUSERCFG=0,7,"subscriber","espressif","1234567890",0,0,"mqtt"
    

    Response:

    OK
    
  4. Connect to MQTT brokers.

    Command:

    AT+MQTTCONN=0,"mqtt.eclipseprojects.io",443,1
    

    Response:

    +MQTTCONNECTED:0,7,"mqtt.eclipseprojects.io","443","/mqtt",1
    
    OK
    

    Note:

    • The MQTT broker domain or MQTT broker IP address you enter may be different from those in the above command.

  5. Subscribe to MQTT topics.

    ESP32-C2 MQTT subscriber:

    Command:

    AT+MQTTSUB=0,"topic",1
    

    Response:

    OK
    
  6. Publish MQTT messages in string.

    ESP32-C2 MQTT publisher:

    Command:

    AT+MQTTPUB=0,"topic","test",1,0
    

    Response:

    OK
    

    Note:

    • If the ESP32-C2 MQTT publisher successfully publishes the message, following message will be prompted on the ESP32-C2 MQTT subscriber.

      +MQTTSUBRECV:0,"topic",4,test
      
  7. Close MQTT connections.

    Command:

    AT+MQTTCLEAN=0
    

    Response:

    OK