From 9b4fc629f1f2beec951d1228d332b4c73ad5d723 Mon Sep 17 00:00:00 2001 From: Chen Wu Date: Mon, 11 Dec 2023 21:04:09 +0800 Subject: [PATCH] docs: Added AT+MQTTSNI docs --- docs/en/AT_Command_Set/MQTT_AT_Commands.rst | 78 +++++++++++++++---- .../zh_CN/AT_Command_Set/MQTT_AT_Commands.rst | 76 ++++++++++++++---- 2 files changed, 127 insertions(+), 27 deletions(-) diff --git a/docs/en/AT_Command_Set/MQTT_AT_Commands.rst b/docs/en/AT_Command_Set/MQTT_AT_Commands.rst index 65349049..c7998799 100644 --- a/docs/en/AT_Command_Set/MQTT_AT_Commands.rst +++ b/docs/en/AT_Command_Set/MQTT_AT_Commands.rst @@ -12,6 +12,7 @@ MQTT AT Commands - :ref:`AT+MQTTLONGPASSWORD `: Set MQTT password - :ref:`AT+MQTTCONNCFG `: Set configuration of MQTT connection - :ref:`AT+MQTTALPN `: Set MQTT Application Layer Protocol Negotiation (ALPN) +- :ref:`AT+MQTTSNI `: Set MQTT Server Name Indication (SNI) - :ref:`AT+MQTTCONN `: Connect to MQTT Brokers - :ref:`AT+MQTTPUB `: Publish MQTT Messages in string - :ref:`AT+MQTTPUBRAW `: Publish long MQTT messages @@ -128,8 +129,8 @@ Notes - The command :ref:`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. + - You can use :ref:`AT+MQTTLONGCLIENTID ` to set a relatively long client ID since there is a limitation on the length of the :ref:`AT+MQTTUSERCFG ` command. + - You should set :ref:`AT+MQTTLONGCLIENTID ` after setting the :ref:`AT+MQTTUSERCFG ` command. .. _cmd-MQTTLONGUSERNAME: @@ -174,8 +175,8 @@ Notes - The command :ref:`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``. + - You can use :ref:`AT+MQTTLONGUSERNAME ` to set a relatively long username since there is a limitation on the length of the :ref:`AT+MQTTUSERCFG ` command. + - You should set :ref:`AT+MQTTLONGUSERNAME ` after setting the command :ref:`AT+MQTTUSERCFG `. .. _cmd-MQTTLONGPASSWORD: @@ -220,8 +221,8 @@ Notes - The command :ref:`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``. + - You can use :ref:`AT+MQTTLONGPASSWORD ` to set a relatively long password since there is a limitation on the length of the :ref:`AT+MQTTUSERCFG ` command. + - You should set :ref:`AT+MQTTLONGPASSWORD ` after setting the command :ref:`AT+MQTTUSERCFG `. .. _cmd-MQTTCONNCFG: @@ -301,8 +302,8 @@ Notes ^^^^^ - The length of the entire AT command should be less than 256 bytes. -- MQTT ALPN will only be effective if the MQTT connection is based on TLS or WSS. -- You should set ``AT+MQTTALPN`` after setting the command ``AT+MQTTUSERCFG``. +- MQTT ALPN will be effective only if the MQTT connection is based on TLS or WSS. +- You should set :ref:`AT+MQTTALPN ` after setting the command :ref:`AT+MQTTUSERCFG `. Example ^^^^^^^^ @@ -316,6 +317,55 @@ Example AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us" AT+MQTTCONN=0,"192.168.200.2",8883,1 +.. _cmd-MQTTSNI: + +:ref:`AT+MQTTSNI `: Set MQTT Server Name Indication (SNI) +------------------------------------------------------------------------------------- + +Set Command +^^^^^^^^^^^ + +**Function:** + +Set MQTT Server Name Indication (SNI). + +**Command:** + +:: + + AT+MQTTSNI=,<"sni"> + +**Response:** + +:: + + OK + +Parameters +^^^^^^^^^^ + +- ****: 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 :ref:`AT+MQTTSNI ` after setting the command :ref:`AT+MQTTUSERCFG `. + +Example +^^^^^^^^ + +:: + + AT+CWMODE=1 + AT+CWJAP="ssid","password" + AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com" + AT+MQTTUSERCFG=0,5,"{IDF_TARGET_NAME}","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 + .. _cmd-MQTTCONN: :ref:`AT+MQTTCONN `: Connect to MQTT Brokers @@ -375,8 +425,8 @@ Parameters - ****: MQTT state. - 0: MQTT uninitialized. - - 1: already set ``AT+MQTTUSERCFG``. - - 2: already set ``AT+MQTTCONNCFG``. + - 1: already set :ref:`AT+MQTTUSERCFG `. + - 2: already set :ref:`AT+MQTTCONNCFG `. - 3: connection disconnected. - 4: connection established. - 5: connected, but did not subscribe to any topic. @@ -561,8 +611,8 @@ Parameters - ****: MQTT state. - 0: MQTT uninitialized. - - 1: already set ``AT+MQTTUSERCFG``. - - 2: already set ``AT+MQTTCONNCFG``. + - 1: already set :ref:`AT+MQTTUSERCFG `. + - 2: already set :ref:`AT+MQTTCONNCFG `. - 3: connection disconnected. - 4: connection established. - 5: connected, but subscribe to no topic. @@ -822,7 +872,7 @@ The MQTT Error code will be prompted as ``ERR CODE:0x<%08x>``. :ref:`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. +- In general, AT MQTT commands responds within 10 s, except the command :ref:`AT+MQTTCONN `. For example, if the router fails to access the Internet, the command :ref:`AT+MQTTPUB ` will respond within 10 s. But the command :ref:`AT+MQTTCONN ` may need more time due to packet retransmission in a bad network environment. +- If the :ref:`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:``. - When the MQTT connection established, it will prompt the message ``+MQTTCONNECTED:,,<"host">,port,<"path">,``. diff --git a/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst index 974430cc..4c211c0d 100644 --- a/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst @@ -12,6 +12,7 @@ MQTT AT 命令集 - :ref:`AT+MQTTLONGPASSWORD `：设置 MQTT 登陆密码 - :ref:`AT+MQTTCONNCFG `：设置 MQTT 连接属性 - :ref:`AT+MQTTALPN `：设置 MQTT 应用层协议协商（ALPN） +- :ref:`AT+MQTTSNI `：设置 MQTT 服务器名称指示（SNI） - :ref:`AT+MQTTCONN `：连接 MQTT Broker - :ref:`AT+MQTTPUB `：发布 MQTT 消息（字符串） - :ref:`AT+MQTTPUBRAW `：发布长 MQTT 消息 @@ -128,8 +129,8 @@ MQTT AT 命令集 - :ref:`AT+MQTTUSERCFG ` 命令也可以设置 MQTT 客户端 ID，二者之间的差别包括： - - ``AT+MQTTLONGCLIENTID`` 命令可以用来设置相对较长的客户端 ID，因为 ``AT+MQTTUSERCFG`` 命令的长度受限； - - 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTLONGCLIENTID``。 + - :ref:`AT+MQTTLONGCLIENTID ` 命令可以用来设置相对较长的客户端 ID，因为 :ref:`AT+MQTTUSERCFG ` 命令的长度受限； + - 应在设置 :ref:`AT+MQTTUSERCFG ` 后再使用 :ref:`AT+MQTTLONGCLIENTID `。 .. _cmd-MQTTLONGUSERNAME: @@ -174,8 +175,8 @@ MQTT AT 命令集 - :ref:`AT+MQTTUSERCFG ` 命令也可以设置 MQTT 用户名，二者之间的差别包括： - - ``AT+MQTTLONGUSERNAME`` 命令可以用来设置相对较长的用户名，因为 ``AT+MQTTUSERCFG`` 命令的长度受限。 - - 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTLONGUSERNAME``。 + - :ref:`AT+MQTTLONGUSERNAME ` 命令可以用来设置相对较长的用户名，因为 :ref:`AT+MQTTUSERCFG ` 命令的长度受限。 + - 应在设置 :ref:`AT+MQTTUSERCFG ` 后再使用 :ref:`AT+MQTTLONGUSERNAME `。 .. _cmd-MQTTLONGPASSWORD: @@ -220,8 +221,8 @@ MQTT AT 命令集 - :ref:`AT+MQTTUSERCFG ` 命令也可以设置 MQTT 密码，二者之间的差别包括： - - ``AT+MQTTLONGPASSWORD`` 可以用来设置相对较长的密码，因为 ``AT+MQTTUSERCFG`` 命令的长度受限； - - 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTLONGPASSWORD``。 + - :ref:`AT+MQTTLONGPASSWORD ` 可以用来设置相对较长的密码，因为 :ref:`AT+MQTTUSERCFG ` 命令的长度受限； + - 应在设置 :ref:`AT+MQTTUSERCFG ` 后再使用 :ref:`AT+MQTTLONGPASSWORD `。 .. _cmd-MQTTCONNCFG: @@ -302,7 +303,7 @@ MQTT AT 命令集 - 整条 AT 命令长度应小于 256 字节。 - 只有在 MQTT 基于 TLS 或 WSS 时，MQTT ALPN 字段才会生效。 -- 应在设置 ``AT+MQTTUSERCFG`` 后再使用 ``AT+MQTTALPN``。 +- 应在设置 :ref:`AT+MQTTUSERCFG ` 后再使用 :ref:`AT+MQTTALPN `。 示例 ^^^^ @@ -316,6 +317,55 @@ MQTT AT 命令集 AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us" AT+MQTTCONN=0,"192.168.200.2",8883,1 +.. _cmd-MQTTSNI: + +:ref:`AT+MQTTSNI `：设置 MQTT 服务器名称指示（SNI） +------------------------------------------------------------------------- + +设置命令 +^^^^^^^^ + +**功能：** + +设置 MQTT 服务器名称指示（SNI） + +**命令：** + +:: + + AT+MQTTSNI=,<"sni"> + +**响应：** + +:: + + OK + +参数 +^^^^ + +- ****：当前仅支持 link ID 0。 +- **<"sni">**：MQTT 服务器名称指示。您可以在 ClientHello 中将其发送到服务器。 + +说明 +^^^^ + +- 整条 AT 命令长度应小于 256 字节。 +- 只有在 MQTT 基于 TLS 或 WSS 时，MQTT SNI 字段才会生效。 +- 应在设置 :ref:`AT+MQTTUSERCFG ` 后再使用 :ref:`AT+MQTTSNI `。 + +示例 +^^^^ + +:: + + AT+CWMODE=1 + AT+CWJAP="ssid","password" + AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com" + AT+MQTTUSERCFG=0,5,"{IDF_TARGET_NAME}","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 + .. _cmd-MQTTCONN: :ref:`AT+MQTTCONN `：连接 MQTT Broker @@ -375,8 +425,8 @@ MQTT AT 命令集 - ****：MQTT 状态： - 0: MQTT 未初始化； - - 1: 已设置 ``AT+MQTTUSERCFG``； - - 2: 已设置 ``AT+MQTTCONNCFG``； + - 1: 已设置 :ref:`AT+MQTTUSERCFG `； + - 2: 已设置 :ref:`AT+MQTTCONNCFG `； - 3: 连接已断开； - 4: 已建立连接； - 5: 已连接，但未订阅 topic； @@ -561,8 +611,8 @@ MQTT AT 命令集 - ****：MQTT 状态： - 0: MQTT 未初始化； - - 1: 已设置 ``AT+MQTTUSERCFG``； - - 2: 已设置 ``AT+MQTTCONNCFG``； + - 1: 已设置 :ref:`AT+MQTTUSERCFG `； + - 2: 已设置 :ref:`AT+MQTTCONNCFG `； - 3: 连接已断开； - 4: 已建立连接； - 5: 已连接，但未订阅 topic； @@ -822,7 +872,7 @@ MQTT 错误码以 ``ERR CODE:0x<%08x>`` 形式打印。 :ref:`MQTT AT 说明 ` ------------------------------- -- 一般来说，AT MQTT 命令都会在 10 秒内响应，但 ``AT+MQTTCONN`` 命令除外。例如，如果路由器不能上网，命令 ``AT+MQTTPUB`` 会在 10 秒内响应，但 ``AT+MQTTCONN`` 命令在网络环境不好的情况下，可能需要更多的时间用来重传数据包。 -- 如果 ``AT+MQTTCONN`` 是基于 TLS 连接，每个数据包的超时时间为 10 秒，则总超时时间会根据握手数据包的数量而变得更长。 +- 一般来说，AT MQTT 命令都会在 10 秒内响应，但 :ref:`AT+MQTTCONN ` 命令除外。例如，如果路由器不能上网，命令 :ref:`AT+MQTTPUB ` 会在 10 秒内响应，但 :ref:`AT+MQTTCONN ` 命令在网络环境不好的情况下，可能需要更多的时间用来重传数据包。 +- 如果 :ref:`AT+MQTTCONN ` 是基于 TLS 连接，每个数据包的超时时间为 10 秒，则总超时时间会根据握手数据包的数量而变得更长。 - 当 MQTT 连接断开时，会提示 ``+MQTTDISCONNECTED:`` 消息。 - 当 MQTT 连接建立时，会提示 ``+MQTTCONNECTED:,,<"host">,port,<"path">,`` 消息。