Skip to content

Commit bed9f66

Browse files
xcguangxcguang
committed
Merge branch 'docs/update_at_docs' into 'master'
docs: Updated a series of AT docs Closes ESPAT-2485 See merge request application/esp-at!1935
2 parents 9abae64 + 09f84eb commit bed9f66

14 files changed

+910
-270
lines changed

‎docs/en/AT_Command_Set/Basic_AT_Commands.rst‎

Lines changed: 86 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Basic AT Commands
1717
- :ref:`AT+GSLP <cmd-GSLP>`: Enter Deep-sleep mode.
1818
- :ref:`ATE <cmd-ATE>`: Configure AT commands echoing.
1919
- :ref:`AT+RESTORE <cmd-RESTORE>`: Restore factory default settings of the module.
20-
- :ref:`AT+SAVETRANSLINK <cmd-SAVET>`: Set whether to enter :term:`Passthrough Mode` on power-up.
20+
- :ref:`AT+SAVETRANSLINK <cmd-SAVET>`: Set whether to enter Network/Bluetooth :term:`Passthrough Mode` on power-up.
2121
- :ref:`AT+TRANSINTVL <cmd-TRANSINTVL>`: Set the data transmission interval in the :term:`Passthrough Mode`.
2222
- :ref:`AT+UART_CUR <cmd-UARTC>`: Current UART configuration, not saved in flash.
2323
- :ref:`AT+UART_DEF <cmd-UARTD>`: Default UART configuration, saved in flash.
@@ -298,19 +298,20 @@ Notes
298298

299299
.. _cmd-SAVET:
300300

301-
:ref:`AT+SAVETRANSLINK <Basic-AT>`: Set Whether to Enter Wi-Fi/Bluetooth LE :term:`Passthrough Mode` on Power-up
302-
----------------------------------------------------------------------------------------------------------------
301+
:ref:`AT+SAVETRANSLINK <Basic-AT>`: Set Whether to Enter Network/Bluetooth LE :term:`Passthrough Mode` on Power-up
302+
------------------------------------------------------------------------------------------------------------------
303303

304304
.. list::
305305

306-
* :ref:`savetrans-tcpssl`
306+
* :ref:`savetrans-tcpssl-client`
307+
* :ref:`savetrans-tcpssl-server`
307308
* :ref:`savetrans-udp`
308309
:not esp32s2: * :ref:`savetrans-ble`
309310

310-
.. _savetrans-tcpssl:
311+
.. _savetrans-tcpssl-client:
311312

312-
Set Whether to Enter TCP/SSL :term:`Passthrough Mode` on Power-up
313-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
313+
Set Whether to Enter TCP/SSL Client :term:`Passthrough Mode` on Power-up
314+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
314315

315316
Set Command
316317
""""""""""""""
@@ -332,8 +333,8 @@ Parameters
332333

333334
- **<mode>**:
334335

335-
- 0: {IDF_TARGET_NAME} will NOT enter Wi-Fi :term:`Passthrough Mode` on power-up.
336-
- 1: {IDF_TARGET_NAME} will enter Wi-Fi :term:`Passthrough Mode` on power-up.
336+
- 0: {IDF_TARGET_NAME} will NOT enter TCP/SSL client :term:`Passthrough Mode` on power-up.
337+
- 1: {IDF_TARGET_NAME} will enter TCP/SSL client :term:`Passthrough Mode` on power-up.
337338

338339
- **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes.
339340
- **<remote port>**: the remote port number.
@@ -350,7 +351,7 @@ Parameters
350351
Notes
351352
"""""""
352353

353-
- This command will save the Wi-Fi :term:`Passthrough Mode` configuration in the NVS partition. If ``<mode>`` is set to 1, {IDF_TARGET_NAME} will enter the Wi-Fi :term:`Passthrough Mode` in the next power on. The configuration will take effect after {IDF_TARGET_NAME} reboots.
354+
- This command will save the :term:`Passthrough Mode` configuration in the NVS partition. If ``<mode>`` is set to 1, {IDF_TARGET_NAME} will enter the :term:`Passthrough Mode` in the next power on. The configuration will take effect after {IDF_TARGET_NAME} reboots.
354355

355356
Example
356357
""""""""
@@ -362,6 +363,75 @@ Example
362363
AT+SAVETRANSLINK=1,"240e:3a1:2070:11c0:55ce:4e19:9649:b75",8080,"TCPv6"
363364
AT+SAVETRANSLINK=1,"240e:3a1:2070:11c0:55ce:4e19:9649:b75",8080,"SSLv6"
364365

366+
.. _savetrans-tcpssl-server:
367+
368+
Set Whether to Enter TCP/SSL Server :term:`Passthrough Mode` on Power-up
369+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
370+
371+
Set Command
372+
""""""""""""""
373+
374+
**Command:**
375+
376+
::
377+
378+
AT+SAVETRANSLINK=<mode>[,<port>][,<"type">][,<CA enable>][,<netif>]
379+
380+
**Response:**
381+
382+
::
383+
384+
OK
385+
386+
Parameters
387+
""""""""""""""
388+
389+
- **<mode>**:
390+
391+
- 0: {IDF_TARGET_NAME} will NOT enter TCP/SSL server :term:`Passthrough Mode` on power-up.
392+
- 3: {IDF_TARGET_NAME} will enter TCP/SSL server :term:`Passthrough Mode` on power-up.
393+
394+
- **[<port>]**: The port that the server listens to. Default: 333.
395+
- **<"type">**: Server type: "TCP", "TCPv6", "SSL", or "SSLv6". Default: "TCP".
396+
- **<CA enable>**: This parameter is only valid when ``<type>`` is "SSL" or "SSLv6".
397+
398+
- 0: Do not use CA certificate.
399+
- 1: Use CA certificate.
400+
401+
- **<netif>**: Specifies the network interface for the server to listen on. Default: 0.
402+
403+
.. list::
404+
405+
- 0: All network interfaces
406+
- 1: Wi-Fi Station interface
407+
- 2: Wi-Fi SoftAP interface
408+
:esp32: - 3: Ethernet interface
409+
410+
Notes
411+
"""""""
412+
413+
- This command will save the :term:`Passthrough Mode` configuration in the NVS partition. If ``<mode>`` is set to 1, {IDF_TARGET_NAME} will enter the :term:`Passthrough Mode` in the next power on. The configuration will take effect after {IDF_TARGET_NAME} reboots.
414+
- When {IDF_TARGET_NAME} works as a Wi-Fi Station, please configure the Wi-Fi connection information in advance and enable the reconnection mechanism; when it works as a SoftAP, please configure the SoftAP parameters in advance to ensure it can work normally after power-on.
415+
- In the TCP/SSL server passthrough mode, only a single passthrough connection is supported: once a client establishes a passthrough connection, the server will enter passthrough mode and reject subsequent passthrough connection requests.
416+
- When the underlying network interface (netif) is stopped or disconnected, existing connections will be closed, and the server will return to listening state, ready to accept new normal connections.
417+
- After exiting passthrough mode, the TCP/SSL server will continue running, but in normal (non-passthrough) mode with a maximum of 1 concurrent connection.
418+
419+
Example
420+
"""""""""
421+
422+
::
423+
424+
// Set Wi-Fi SoftAP information, SSID is esp-ap-001, no password, channel 11, open encryption, maximum 3 connections
425+
AT+CWSAP="esp-ap-001","",11,0,3
426+
427+
// Set to enter TCP server passthrough mode on power-up, listening on port 1002
428+
AT+SAVETRANSLINK=3,1002,"TCP",2
429+
430+
// PC connects to esp-ap-001 and uses a TCP client tool to connect to {IDF_TARGET_NAME}'s port 1002
431+
nc 192.168.4.1 1002
432+
433+
// Transmit data in passthrough mode
434+
365435
.. _savetrans-udp:
366436

367437
Set Whether to Enter UDP :term:`Passthrough Mode` on Power-up
@@ -387,18 +457,18 @@ Parameters
387457

388458
- **<mode>**:
389459

390-
- 0: {IDF_TARGET_NAME} will NOT enter Wi-Fi :term:`Passthrough Mode` on power-up.
391-
- 1: {IDF_TARGET_NAME} will enter Wi-Fi :term:`Passthrough Mode` on power-up.
460+
- 0: {IDF_TARGET_NAME} will NOT enter UDP :term:`Passthrough Mode` on power-up.
461+
- 1: {IDF_TARGET_NAME} will enter UDP :term:`Passthrough Mode` on power-up.
392462

393463
- **<"remote host">**: IPv4 address, IPv6 address, or domain name of remote host. The maximum length is 64 bytes.
394464
- **<remote port>**: the remote port number.
395465
- **<"type">**: string parameter showing the type of transmission: "UDP" or "UDPv6". Default: "TCP".
396-
- **<local port>**: local port when UDP Wi-Fi passthrough is enabled on power-up.
466+
- **<local port>**: local port when UDP passthrough is enabled on power-up.
397467

398468
Notes
399469
"""""""
400470

401-
- This command will save the Wi-Fi :term:`Passthrough Mode` configuration in the NVS partition. If ``<mode>`` is set to 1, {IDF_TARGET_NAME} will enter the Wi-Fi :term:`Passthrough Mode` in the next power on. The configuration will take effect after {IDF_TARGET_NAME} reboots.
471+
- This command will save the :term:`Passthrough Mode` configuration in the NVS partition. If ``<mode>`` is set to 1, {IDF_TARGET_NAME} will enter the :term:`Passthrough Mode` in the next power on. The configuration will take effect after {IDF_TARGET_NAME} reboots.
402472

403473
- To establish an UDP transmission based on an IPv6 network, do as follows:
404474

@@ -2115,6 +2185,8 @@ Note
21152185

21162186
- :ref:`AT+SYSMSG <cmd-SYSMSG>`
21172187
- :ref:`AT+CWMODE <cmd-MODE>`
2188+
:esp32c5: - :ref:`AT+CWBANDMODE <cmd-CWBANDMODE>`
2189+
- :ref:`AT+CWBANDWIDTH <cmd-CWBANDWIDTH>`
21182190
- :ref:`AT+CIPV6 <cmd-IPV6>`
21192191
- :ref:`AT+CWCONFIG <cmd-CWCONFIG>`
21202192
- :ref:`AT+CWJAP <cmd-JAP>`

‎docs/en/AT_Command_Set/MQTT_AT_Commands.rst‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,12 @@ Introduction
2828
------------
2929

3030
.. important::
31-
The default AT firmware supports all the AT commands mentioned on this page. If you don't need {IDF_TARGET_NAME} to support MQTT commands, you can compile the ESP-AT project by following the steps in :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation. In the project configuration during the fifth step, make the following selections:
31+
- The default AT firmware supports all the AT commands mentioned on this page. If you don't need {IDF_TARGET_NAME} to support MQTT commands, you can compile the ESP-AT project by following the steps in :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>` documentation. In the project configuration during the fifth step, make the following selections:
3232

33-
- Disable ``Component config`` -> ``AT`` -> ``AT MQTT command support``
33+
- Disable ``Component config`` -> ``AT`` -> ``AT MQTT command support``
34+
35+
- For MQTT connection to local Broker examples, see :doc:`MQTT AT Examples <../AT_Command_Examples/MQTT_AT_Examples>`.
36+
- For MQTT connection to AWS IoT examples, see :doc:`MQTT Cloud Connection AT Examples <../AT_Command_Examples/mqtt-at-examples-for-cloud>`.
3437

3538
.. _cmd-MQTTUSERCFG:
3639

@@ -408,7 +411,7 @@ Connect to an MQTT broker.
408411

409412
::
410413

411-
AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>
414+
AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>[,<timeout_ms>]
412415

413416
**Response:**
414417

@@ -428,6 +431,7 @@ Parameters
428431
- 0: MQTT will not reconnect automatically. If MQTT connection established and then disconnected, you cannot use this command to reestablish MQTT connection. Please send :ref:`AT+MQTTCLEAN=0 <cmd-MQTTCLEAN>` command to clean MQTT connection first, reconfigure the connection parameters, and then establish a new MQTT connection.
429432
- 1: MQTT will reconnect automatically. It takes more resources.
430433

434+
- **<timeout_ms>**: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.
431435
- **<state>**: MQTT state.
432436

433437
- 0: MQTT uninitialized.
@@ -467,7 +471,7 @@ Publish MQTT messages in string to a defined topic. If the amount of data you pu
467471

468472
::
469473

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

472476
**Response:**
473477

@@ -483,6 +487,7 @@ Parameters
483487
- **<data>**: MQTT message in string.
484488
- **<qos>**: QoS of message, which can be set to 0, 1, or 2. Default: 0.
485489
- **<retain>**: retain flag.
490+
- **<timeout_ms>**: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.
486491

487492
Notes
488493
^^^^^
@@ -517,7 +522,7 @@ Publish long MQTT messages to a defined topic. If the amount of data you publish
517522

518523
::
519524

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

522527
**Response:**
523528

@@ -548,6 +553,7 @@ Parameters
548553
- **<length>**: length of MQTT message. The maximum length is limited by available memory.
549554
- **<qos>**: QoS of the published message, which can be set to 0, 1, or 2. Default is 0.
550555
- **<retain>**: retain flag.
556+
- **<timeout_ms>**: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.
551557

552558
.. _cmd-MQTTSUB:
553559

@@ -565,7 +571,7 @@ List all MQTT topics that have been already subscribed.
565571

566572
::
567573

568-
AT+MQTTSUB?
574+
AT+MQTTSUB?
569575

570576

571577
**Response:**
@@ -589,7 +595,7 @@ Subscribe to defined MQTT topics with defined QoS. Multiple topics are available
589595

590596
::
591597

592-
AT+MQTTSUB=<LinkID>,<"topic">,<qos>
598+
AT+MQTTSUB=<LinkID>,<"topic">,<qos>[,<timeout_ms>]
593599

594600

595601
**Response:**
@@ -626,6 +632,7 @@ Parameters
626632

627633
- **<"topic">**: the topic that is subscribed to.
628634
- **<qos>**: the QoS that is subscribed to.
635+
- **<timeout_ms>**: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.
629636

630637
Note
631638
^^^^
@@ -652,7 +659,7 @@ Unsubscribe the client from defined topics. This command can be called multiple
652659

653660
::
654661

655-
AT+MQTTUNSUB=<LinkID>,<"topic">
662+
AT+MQTTUNSUB=<LinkID>,<"topic">[,<timeout_ms>]
656663

657664

658665
**Response:**
@@ -674,6 +681,7 @@ Parameters
674681

675682
- **<LinkID>**: only supports link ID 0 currently.
676683
- **<"topic">**: MQTT topic. Maximum length: 128 bytes.
684+
- **<timeout_ms>**: timeout for the command. Unit: milliseconds. Range: [3000,60000]. Default: 15000 milliseconds.
677685

678686
.. _cmd-MQTTCLEAN:
679687

@@ -691,7 +699,7 @@ Close the MQTT connection and release the resource.
691699

692700
::
693701

694-
AT+MQTTCLEAN=<LinkID>
702+
AT+MQTTCLEAN=<LinkID>
695703

696704
**Response:**
697705

@@ -887,7 +895,5 @@ The MQTT Error code will be prompted as ``ERR CODE:0x<%08x>``.
887895
:ref:`MQTT AT Notes <MQTT-AT>`
888896
-------------------------------
889897

890-
- In general, AT MQTT commands responds within 10 s, except the command :ref:`AT+MQTTCONN <cmd-MQTTCONN>`. For example, if the router fails to access the Internet, the command :ref:`AT+MQTTPUB <cmd-MQTTPUB>` will respond within 10 s. But the command :ref:`AT+MQTTCONN <cmd-MQTTCONN>` may need more time due to packet retransmission in a bad network environment.
891-
- If the :ref:`AT+MQTTCONN <cmd-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.
892898
- When the MQTT connection ends, it will prompt the message ``+MQTTDISCONNECTED:<LinkID>``.
893899
- When the MQTT connection established, it will prompt the message ``+MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect>``.

0 commit comments

Comments
 (0)