MQTT AT command set
==================================================

This chapter introduces the driver MQTT command set. This command set will be adapted differently for different modules. For specific differences, please move to：:doc:`../instruction/other/firmware_differences`。

 - :ref:`AT+MQTT <cmd-MQTT>`：MQTT configuration and connection
 - :ref:`AT+MQTTPUB <cmd-MQTTPUB>`：publish MQTT message
 - :ref:`AT+MQTTPUBRAW <cmd-MQTTPUBRAW>`：publish MQTT messages of specified length
 - :ref:`AT+MQTTSUB <cmd-MQTTSUB>`：subscribe to MQTT messages
 - :ref:`AT+MQTTUNSUB <cmd-MQTTUNSUB>`：unsubscribe from MQTT messages

.. _cmd-MQTT:

AT+MQTT configuration and connection
------------------------------------------


Configuration command
^^^^^^^^

**Command：**

::

    //Configuration parameters
    AT+MQTT=<key>,<data>

**Response：**

::

    OK

Parameters
^^^^

-  **<key>**：MQTT parameter. 
     -  1：Set the domain name or IP of the connection
     -  2：Set the server port number
     -  3：Set the connection method
            - reserved, temporarily default 1: use tcp connection
     -  4：Set Client ID
     -  5：Set User Name
            - Maximum length 63 bytes
     -  6：Set Login Password
            - Maximum length 63 bytes
     -  7：set the testament message in the format AT+MQTT=7,<LWT_topic>,<LWT_qos>,<LWT_Retained>,<LWTpayload>
            -  LWT_topic：testament subject(No testament required here set to"")
            -  LWT_qos：testament QOS(0/1/2)
            -  LWT_Retained：testament retained(0/1)
            -  LWTpayload：testament message content
-  **<data>**：set parameters.

Description
^^^^

- Configure MQTT connection parameters. 


Execute command
^^^^^^^^

**Command：**

::

    //Enable connection
    AT+MQTT

**Response：**

::

    OK


Example
^^^^

::

    //Set domain name
    AT+MQTT=1,192.168.202.10 
    OK

    //Set port number
    AT+MQTT=2,1883
    OK
    
    //Set the connection method
    AT+MQTT=3,1
    OK
    
    // Set user ID
    AT+MQTT=4,client_id 
    OK

    // Set MQTT User Name
    AT+MQTT=5,admin
    OK

    //Set MQTT password
    AT+MQTT=6,public
    OK

    //Set Testament Theme LWTTOPIC，qos0，open retained，the load message is  123456；Note: The message to cancel the testament is set to AT+MQTT=7,"",0,0,""
    AT+MQTT=7,"LWTTOPIC",0,1,"123456"
    OK

    //Query MQTT connection and configuration
    AT+MQTT? 
    +MQTT:0,192.168.202.10,1883,1,client_id,admin,public
    OK

    //Connect MQTT
    AT+MQTT 
    OK

    //MQTT connection successful
    +EVENT:MQTT_CONNECT


Query command
^^^^^^^^

**Command：**

::

    AT+MQTT? 

**Response：**

::

    +MQTT:<MQTT_status>,<Host_name>,<Port>,<scheme>,<client_id>,<username>,<password>,<LWT_topic>,<LWT_qos>,<LWT_Retained>,<LWTpayload>
    OK

Parameters
^^^^

-   **<MQTT_status>**：MQTT connection status. 
        - 0：Initial State
        - 1：Connecting
        - 2：Subscribing to Messages
        - 3：Connection Successfully
-   **<Host_name>**：server domain name.
-   **<Port>**：the port number of the server. 
-   **<scheme>**：connection method
        - 1：TCP connection
-   **<client_id>**：MQTT user ID.
-   **<username>**：MQTT username. 
-   **<password>**：MQTT password. 
-   **<LWT_topic>**：subject of testament. 
-   **<LWT_qos>**：testament QOS。
-   **<LWT_Retained>**：testament retained。
-   **<LWTpayload>**：testament message content


Description
^^^^

- Note: MQTT parameters need to be set before performing the connection. If the current MQTT task has been started and executed again, it will be reconnected (if the server is changed, it is recommended to delete all subscriptions before reconnecting)
- Note: This is an asynchronous connection. The display OK only means that the MQTT task is started. The connection status needs to be through AT + MQTT? Query or wait for URC data“+EVENT:MQTT_CONNECT


Example
^^^^

::

    AT+MQTT? //Query MQTT Connection and Configuration
    +MQTT:0,192.168.202.10,1883,1,client_id,admin,public,LWTTOPIC,0,1,123456
    OK


.. _cmd-MQTTPUB:

AT+MQTTPUB releases MQTT messages
------------------------------------------

Execute command
^^^^^^^^

**Command：**

::

    AT+MQTTPUB=<topic>,<qos>,<Retained>,<payload>

**Response：**

::

    OK

Parameters
^^^^

-  **<topic>**：the topic to be published. 
-  **<qos>**：qos grade(0,1,2)。
-  **<Retained>**：
    - 0：General message
    - 1：Retained message
-  **<payload>**：data content


Description
^^^^

- Publish MQTT messages. 


Example
^^^^

::
    
    AT+MQTTPUB=testtopic,1,0,456
    OK
 
.. _cmd-MQTTPUBRAW:

AT+MQTTPUBRAW publishes MQTT messages of specified length
------------------------------------------

Execute command
^^^^^^^^

**Command：**

::

    AT+MQTTPUBRAW=<topic>,<qos>,<Retained>,<length>

**Response：**

::

    OK

Parameters
^^^^

-  **<topic>**：the topic to be published. 
-  **<qos>**：qos grade(0,1,2)。
-  **<Retained>**：
    - 0：General message
    - 1：Retained message
-  **<length>**：Data length


Description
^^^^

- Publish MQTT messages of specified length.


Example
^^^^

::


    AT+MQTTPUBRAW=testtopic,1,0,10 //Send 10 bytes of data to testtopic
    > //After receiving this character, start entering the data to be sent
    
    OK //After receiving 10 bytes of data, data (which can be any data) will be sent, and OK will be displayed after sending.

.. _cmd-MQTTSUB:

AT+MQTTSUB Subscribe to MQTT Messages
------------------------------------------


Execute command
^^^^^^^^

**Command：**

::

    AT+MQTTSUB=<topic>,<qos>

**Response：**

::

    OK

Parameters
^^^^

-  **<topic>**：topic to subscribe.
-  **<qos>**：qos grade(0,1,2)。

Description
^^^^

- Configure MQTT subscription topics.


Example
^^^^

::

    AT+MQTTSUB=testtopic0,0
    OK


Query command
^^^^^^^^

**Command：**

::

    AT+MQTTSUB?

**Response：**

::

    <status>,<Topic>
    ... 
    OK

Parameters
^^^^

-   **<status>**：Subscription status. 
        - 0：Initialization Status
        - 1：Subscription (first subscription)
        - 2：Subscribe (re-subscribe after disconnection and reconnection)
        - 3：Subscription Successful
-   **<Topic>**：Subscribed topics.


Description
^^^^

- Query MQTT subscription topics that have been configured. 

Example
^^^^

::

    AT+MQTTSUB?
    3,testtopic0
    3,testtopic1
    OK

.. _cmd-MQTTUNSUB:

AT+MQTTUNSUB unsubscribe from MQTT messages
------------------------------------------

Execute command
^^^^^^^^

**Command：**

::

    AT+MQTTUNSUB=<topic>

**Response：**

::

    OK

Parameters
^^^^

-  **<topic>**：unsubscribed topics. 

Description
^^^^

- unsubscribe from MQTT messages. 


Example
^^^^

::

    AT+MQTTSUB=testtopic0

    OK