From 9330f59ea347aed91e080c279f1138f779a15938 Mon Sep 17 00:00:00 2001 From: Chen Wu Date: Fri, 5 Jul 2024 17:07:44 +0800 Subject: [PATCH] docs(ESPAT-2032): Added instance, protocol, txt parameters to AT+MDNS command - Moved AT+MDNS doc from wifi_at_commands.rst to tcp_ip_at_commands.rst - Added instance, protocol, txt parameters to AT+MDNS command - Added AT+MDNS examples --- .../TCP-IP_AT_Examples.rst | 152 ++++++++++++++++++ docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst | 53 ++++++ docs/en/AT_Command_Set/Wi-Fi_AT_Commands.rst | 44 ----- .../TCP-IP_AT_Examples.rst | 152 ++++++++++++++++++ .../AT_Command_Set/TCP-IP_AT_Commands.rst | 53 ++++++ .../AT_Command_Set/Wi-Fi_AT_Commands.rst | 44 ----- 6 files changed, 410 insertions(+), 88 deletions(-) diff --git a/docs/en/AT_Command_Examples/TCP-IP_AT_Examples.rst b/docs/en/AT_Command_Examples/TCP-IP_AT_Examples.rst index e6a9ccab..c0165d69 100644 --- a/docs/en/AT_Command_Examples/TCP-IP_AT_Examples.rst +++ b/docs/en/AT_Command_Examples/TCP-IP_AT_Examples.rst @@ -1861,3 +1861,155 @@ When a large amount of network data is expected to be received and the MCU canno +CIPRECVDATA:4,test OK + +.. _example-mdns: + +{IDF_TARGET_NAME} enables mDNS function, PC connects to the device's TCP server using a domain name +----------------------------------------------------------------------------------------------------- + +#. Set the Wi-Fi mode to station. + + Command: + + .. code-block:: none + + AT+CWMODE=1 + + Response: + + .. code-block:: none + + OK + +#. Connect to the router. + + Command: + + .. code-block:: none + + AT+CWJAP="espressif","1234567890" + + Response: + + .. code-block:: none + + WIFI CONNECTED + WIFI GOT IP + + OK + + Note: + + - The SSID and password you entered may be different from those in the above command. Please replace the SSID and password with those of your router settings. + +#. Connect the PC to the same router which {IDF_TARGET_NAME} is connected to. + + PC can discover the {IDF_TARGET_NAME} device only when they are in the same LAN. + +#. Use an mDNS tool on the PC to enable service discovery. For example, use `avahi-browse `_ on linux (use `Bonjour `_ on macOS or Windows). + + Command: + + .. code-block:: none + + sudo avahi-browse -a -r + +#. {IDF_TARGET_NAME} device enables mDNS function. + + Command: + + .. code-block:: none + + AT+MDNS=1,"espressif","_printer",35,"my_instance","_tcp",2,"product","my_printer","firmware_version","AT-V3.4.1.0" + + Response: + + .. code-block:: none + + OK + + Note: + + - This command enables mDNS function and specifies the device instance name as ``my_instance``, service type as ``_printer``, port as ``35``, product as ``my_printer``, and firmware version as ``AT-V3.4.1.0``. + +#. (Optional) PC discovers the {IDF_TARGET_NAME} device. + + The PC's ``avahi-browse`` tool will display: + + .. code-block:: none + + ... + + enx000ec6dd4ebf IPv4 my_instance UNIX Printer local + = enx000ec6dd4ebf IPv4 my_instance UNIX Printer local + hostname = [espressif.local] + address = [192.168.200.90] + port = [35] + txt = ["product=my_printer" "firmware_version=AT-V3.4.1.0"] + + Note: + + - This step is not necessary, it is just to verify the mDNS function of the {IDF_TARGET_NAME} device. + +#. {IDF_TARGET_NAME} device enables multiple connections. + + Command: + + .. code-block:: none + + AT+CIPMUX=1 + + Response: + + .. code-block:: none + + OK + +#. {IDF_TARGET_NAME} device runs a TCP server on port ``35``. + + Command: + + .. code-block:: none + + AT+CIPSERVER=1,35 + + Response: + + .. code-block:: none + + OK + +#. Use a TCP tool (For example, use `nc `_ on Linux or macOS, use `ncat `_ on Windows) on the PC to connect to {IDF_TARGET_NAME} device's TCP server using the domain name. + + Command: + + .. code-block:: none + + nc espressif.local 35 + + {IDF_TARGET_NAME} device responds: + + .. code-block:: none + + 0,CONNECT + + Note: + + - After the connection is established, data transmission can immediately take place between PC and {IDF_TARGET_NAME} device. + +#. {IDF_TARGET_NAME} device disables mDNS function. + + Command: + + .. code-block:: none + + AT+MDNS=0 + + Response: + + .. code-block:: none + + OK + + Note: + + - Disabling mDNS function can reduce the device's power consumption to some extent. diff --git a/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst index e7dfc050..7a63f872 100644 --- a/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst +++ b/docs/en/AT_Command_Set/TCP-IP_AT_Commands.rst @@ -43,6 +43,7 @@ TCP/IP AT Commands - :ref:`AT+CIPRECVLEN `: Obtain socket data length in passive receiving mode. - :ref:`AT+PING `: Ping the remote host. - :ref:`AT+CIPDNS `: Query/Set DNS server information. +- :ref:`AT+MDNS `: Configure the mDNS function. - :ref:`AT+CIPTCPOPT `: Query/Set the socket options. .. _cmd-tcpip-intro: @@ -55,6 +56,7 @@ Introduction - Disable OTA commands (:ref:`AT+CIUPDATE ` and :ref:`AT+CIPFWVER `): ``Component config`` -> ``AT`` -> ``AT OTA command support`` - Disable PING commands (:ref:`AT+PING `): ``Component config`` -> ``AT`` -> ``AT ping command support`` + - Disable mDNS commands (:ref:`AT+MDNS `): ``Component config`` -> ``AT`` -> ``AT MDNS command support`` - Disable TCP/IP commands (Not recommended. Once disabled, all TCP/IP functions will be unavailable and you will need to implement these AT commands yourself): ``Component config`` -> ``AT`` -> ``AT net command support`` .. _cmd-IPV6: @@ -2419,6 +2421,57 @@ Example // third DNS Server based on IPv6: main DNS Server based on IPv6 in JiangSu Province, China AT+CIPDNS=1,"240c::6666","2001:4860:4860::8888","240e:5a::6666" +.. _cmd-MDNS: + +:ref:`AT+MDNS `: Configure the mDNS Function +------------------------------------------------------------ + +Set Command +^^^^^^^^^^^ + +**Command:** + +:: + + AT+MDNS=[,<"hostname">,<"service_type">,][,<"instance">][,<"proto">][,][,<"key">,<"value">][...] + +**Response:** + +:: + + OK + +Parameters +^^^^^^^^^^ + +- ****: + + - 1: Enable the mDNS function. The following parameters need to be set. + - 0: Disable the mDNS function. Please do not set the following parameters. + +- **<"hostname">**: mDNS host name. +- **<"service_type">**: mDNS service type. +- ****: mDNS service port. +- **<"instance">**: mDNS instance name. Default: ``<"hostname">``. +- **<"proto">**: mDNS service protocol. Recommended values: ``_tcp`` or ``_udp``. Default: ``_tcp``. +- ****: the number of key-value pairs in the TXT record. Range: [1,10]. +- **<"key">**: key of the TXT record. +- **<"value">**: value of the TXT record. +- **[...]**: repeat the key-value pairs of TXT record according to the ````. + +Example +^^^^^^^^ + +:: + + // Enable mDNS function. Set the hostname to "espressif", service type to "_iot", and port to 8080. + AT+MDNS=1,"espressif","_iot",8080 + + // Disable mDNS function + AT+MDNS=0 + +Detailed examples can be found in: :ref:`mDNS Example `. + .. _cmd-TCPOPT: :ref:`AT+CIPTCPOPT `: Query/Set the Socket Options diff --git a/docs/en/AT_Command_Set/Wi-Fi_AT_Commands.rst b/docs/en/AT_Command_Set/Wi-Fi_AT_Commands.rst index a0e7461e..df4a0041 100644 --- a/docs/en/AT_Command_Set/Wi-Fi_AT_Commands.rst +++ b/docs/en/AT_Command_Set/Wi-Fi_AT_Commands.rst @@ -29,7 +29,6 @@ Wi-Fi AT Commands - :ref:`AT+CWSTARTSMART `: Start SmartConfig. - :ref:`AT+CWSTOPSMART `: Stop SmartConfig. - :ref:`AT+WPS `: Enable the WPS function. -- :ref:`AT+MDNS `: Configure the mDNS function. - :ref:`AT+CWJEAP `: Connect to a WPA2 Enterprise AP. - :ref:`AT+CWHOSTNAME `: Query/Set the host name of an {IDF_TARGET_NAME} station. - :ref:`AT+CWCOUNTRY `: Query/Set the Wi-Fi Country Code. @@ -44,7 +43,6 @@ Introduction - Enable EAP commands (:ref:`AT+CWJEAP `): ``Component config`` -> ``AT`` -> ``AT WPA2 Enterprise command support`` - Disable WPS commands (:ref:`AT+WPS `): ``Component config`` -> ``AT`` -> ``AT WPS command support`` - - Disable mDNS commands (:ref:`AT+MDNS `): ``Component config`` -> ``AT`` -> ``AT MDNS command support`` - Disable smartconfig commands (:ref:`AT+CWSTARTSMART ` and :ref:`AT+CWSTOPSMART `): ``Component config`` -> ``AT`` -> ``AT smartconfig command support`` - Disable all Wi-Fi commands (Not recommended. Once disabled, all Wi-Fi and above functions will be unusable, and you will need to implement these AT commands yourself): ``Component config`` -> ``AT`` -> ``AT wifi command support`` @@ -1633,48 +1631,6 @@ Example AT+CWMODE=1 AT+WPS=1 -.. _cmd-MDNS: - -:ref:`AT+MDNS `: Configure the mDNS Function ------------------------------------------------------------- - -Set Command -^^^^^^^^^^^ - -**Command:** - -:: - - AT+MDNS=[,,,] - -**Response:** - -:: - - OK - -Parameters -^^^^^^^^^^ - -- ****: - - - 1: Enable the mDNS function. The following three parameters need to be set. - - 0: Disable the mDNS function. The following three parameters does not need to be set. - -- ****: mDNS host name. -- ****: mDNS service name. -- ****: mDNS port. - -Example -^^^^^^^^ - -:: - - AT+CWMODE=1 - AT+CWJAP="1234567890","1234567890" - AT+MDNS=1,"espressif","_iot",8080 - AT+MDNS=0 - .. _cmd-JEAP: :ref:`AT+CWJEAP `: Connect to a WPA2 Enterprise AP diff --git a/docs/zh_CN/AT_Command_Examples/TCP-IP_AT_Examples.rst b/docs/zh_CN/AT_Command_Examples/TCP-IP_AT_Examples.rst index f48d8e17..4f0e3ddc 100644 --- a/docs/zh_CN/AT_Command_Examples/TCP-IP_AT_Examples.rst +++ b/docs/zh_CN/AT_Command_Examples/TCP-IP_AT_Examples.rst @@ -1861,3 +1861,155 @@ TCP-IP AT 示例 +CIPRECVDATA:4,test OK + +.. _example-mdns: + +{IDF_TARGET_NAME} 设备开启 mDNS 功能,PC 通过域名连接到设备的 TCP 服务器 +----------------------------------------------------------------------------- + +#. 设置 Wi-Fi 模式为 station。 + + 命令: + + .. code-block:: none + + AT+CWMODE=1 + + 响应: + + .. code-block:: none + + OK + +#. 连接到路由器。 + + 命令: + + .. code-block:: none + + AT+CWJAP="espressif","1234567890" + + 响应: + + .. code-block:: none + + WIFI CONNECTED + WIFI GOT IP + + OK + + 说明: + + - 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。 + +#. PC 与 {IDF_TARGET_NAME} 设备连接同一个路由。 + + 只有在同一个局域网中,PC 才能发现 {IDF_TARGET_NAME} 设备。 + +#. 在 PC 上使用 mDNS 工具开启服务发现。例如 Linux 上使用 `avahi-browse `_ (macOS 或 Windows 上使用 `Bonjour `_)。 + + 命令: + + .. code-block:: none + + sudo avahi-browse -a -r + +#. {IDF_TARGET_NAME} 设备开启 mDNS 功能。 + + 命令: + + .. code-block:: none + + AT+MDNS=1,"espressif","_printer",35,"my_instance","_tcp",2,"product","my_printer","firmware_version","AT-V3.4.1.0" + + 响应: + + .. code-block:: none + + OK + + 说明: + + - 此命令开启 mDNS 功能,表明了设备实例名称为 ``my_instance``,服务类型为 ``_printer``,端口为 ``35``,产品为 ``my_printer``,固件版本为 ``AT-V3.4.1.0``。 + +#. (可选步骤)PC 端发现 {IDF_TARGET_NAME} 设备。 + + PC 端的 ``avahi-browse`` 工具会提示: + + .. code-block:: none + + ... + + enx000ec6dd4ebf IPv4 my_instance UNIX Printer local + = enx000ec6dd4ebf IPv4 my_instance UNIX Printer local + hostname = [espressif.local] + address = [192.168.200.90] + port = [35] + txt = ["product=my_printer" "firmware_version=AT-V3.4.1.0"] + + 说明: + + - 此步骤不是必须的,只是为了验证 {IDF_TARGET_NAME} 设备的 mDNS 功能是否正常。 + +#. {IDF_TARGET_NAME} 设备使能多连接。 + + 命令: + + .. code-block:: none + + AT+CIPMUX=1 + + 响应: + + .. code-block:: none + + OK + +#. {IDF_TARGET_NAME} 设备作为 TCP 服务器,端口为 ``35``。 + + 命令: + + .. code-block:: none + + AT+CIPSERVER=1,35 + + 响应: + + .. code-block:: none + + OK + +#. 在 PC 上使用 TCP 工具(例如,Linux 或 macOS 上使用 `nc `_,Windows 上使用 `ncat `_),通过域名连接到 {IDF_TARGET_NAME} 设备的 TCP 服务器。 + + 命令: + + .. code-block:: none + + nc espressif.local 35 + + {IDF_TARGET_NAME} 设备响应: + + .. code-block:: none + + 0,CONNECT + + 说明: + + - 连接建立成功后,PC 和 {IDF_TARGET_NAME} 设备之间立即可以进行数据传输。 + +#. {IDF_TARGET_NAME} 设备关闭 mDNS 功能。 + + 命令: + + .. code-block:: none + + AT+MDNS=0 + + 响应: + + .. code-block:: none + + OK + + 说明: + + - 关闭 mDNS 功能能一定程度上减少设备的功耗。 diff --git a/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst index eaceb9f6..d91adfba 100644 --- a/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/TCP-IP_AT_Commands.rst @@ -43,6 +43,7 @@ TCP/IP AT 命令 - :ref:`AT+CIPRECVLEN `:查询被动接收模式下套接字数据的长度 - :ref:`AT+PING `:ping 对端主机 - :ref:`AT+CIPDNS `:查询/设置 DNS 服务器信息 +- :ref:`AT+MDNS `:设置 mDNS 功能 - :ref:`AT+CIPTCPOPT `:查询/设置套接字选项 .. _cmd-tcpip-intro: @@ -55,6 +56,7 @@ TCP/IP AT 命令 - 禁用 OTA 命令(:ref:`AT+CIUPDATE `、:ref:`AT+CIPFWVER `):``Component config`` -> ``AT`` -> ``AT OTA command support`` - 禁用 PING 命令(:ref:`AT+PING `):``Component config`` -> ``AT`` -> ``AT ping command support`` + - 禁用 mDNS 命令(:ref:`AT+MDNS `):``Component config`` -> ``AT`` -> ``AT MDNS command support`` - 禁用 TCP/IP 命令(不推荐。一旦禁用,所有 TCP/IP 功能将无法使用,您需要自行实现这些 AT 命令): ``Component config`` -> ``AT`` -> ``AT net command support`` .. _cmd-IPV6: @@ -2419,6 +2421,57 @@ ping 对端主机 // 第三个基于 IPv6 的 DNS 服务器:江苏省主 DNS 服务器 AT+CIPDNS=1,"240c::6666","2001:4860:4860::8888","240e:5a::6666" +.. _cmd-MDNS: + +:ref:`AT+MDNS `:设置 mDNS 功能 +------------------------------------------------------------ + +设置命令 +^^^^^^^^ + +**命令:** + +:: + + AT+MDNS=[,<"hostname">,<"service_type">,][,<"instance">][,<"proto">][,][,<"key">,<"value">][...] + +**响应:** + +:: + + OK + +参数 +^^^^ + +- ****: + + - 1:开启 mDNS 功能,后续参数需要填写 + - 0:关闭 mDNS 功能,后续参数无需填写 + +- **<"hostname">**:mDNS 主机名称。 +- **<"service_type">**:mDNS 服务类型。 +- ****:mDNS 服务端口。 +- **<"instance">**:mDNS 实例名称。默认值:``<"hostname">``。 +- **<"proto">**:mDNS 服务协议。建议值:``_tcp`` 或 ``_udp``,默认值:``_tcp``。 +- ****:mDNS TXT 记录的数量。范围:[1,10]。 +- **<"key">**:TXT 记录的键。 +- **<"value">**:TXT 记录的值。 +- **[...]**:根据 ```` 继续填写 TXT 记录的键值对。 + +示例 +^^^^ + +:: + + // 开启 mDNS 功能,主机名为 "espressif",服务类型为 "_iot",端口为 8080 + AT+MDNS=1,"espressif","_iot",8080 + + // 关闭 mDNS 功能 + AT+MDNS=0 + +详细示例参考: :ref:`mDNS 示例 `。 + .. _cmd-TCPOPT: :ref:`AT+CIPTCPOPT `:查询/设置套接字选项 diff --git a/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst index 489979e2..96574226 100644 --- a/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst @@ -29,7 +29,6 @@ Wi-Fi AT 命令集 - :ref:`AT+CWSTARTSMART `:开启 SmartConfig - :ref:`AT+CWSTOPSMART `:停止 SmartConfig - :ref:`AT+WPS `:设置 WPS 功能 -- :ref:`AT+MDNS `:设置 mDNS 功能 - :ref:`AT+CWJEAP `:连接 WPA2 企业版 AP - :ref:`AT+CWHOSTNAME `:查询/设置 {IDF_TARGET_NAME} Station 的主机名称 - :ref:`AT+CWCOUNTRY `:查询/设置 Wi-Fi 国家代码 @@ -44,7 +43,6 @@ Wi-Fi AT 命令集 - 启用 EAP 命令(:ref:`AT+CWJEAP `): ``Component config`` -> ``AT`` -> ``AT WPA2 Enterprise command support`` - 禁用 WPS 命令(:ref:`AT+WPS `):``Component config`` -> ``AT`` -> ``AT WPS command support`` - - 禁用 mDNS 命令(:ref:`AT+MDNS `):``Component config`` -> ``AT`` -> ``AT MDNS command support`` - 禁用 smartconfig 命令(:ref:`AT+CWSTARTSMART `、:ref:`AT+CWSTOPSMART `):``Component config`` -> ``AT`` -> ``AT smartconfig command support`` - 禁用所有 Wi-Fi 命令(不推荐。一旦禁用,所有 Wi-Fi 以及以上的功能将无法使用,您需要自行实现这些 AT 命令): ``Component config`` -> ``AT`` -> ``AT wifi command support`` @@ -1633,48 +1631,6 @@ Wi-Fi AT 命令集 AT+CWMODE=1 AT+WPS=1 -.. _cmd-MDNS: - -:ref:`AT+MDNS `:设置 mDNS 功能 ------------------------------------------------------------- - -设置命令 -^^^^^^^^ - -**命令:** - -:: - - AT+MDNS=[,,,] - -**响应:** - -:: - - OK - -参数 -^^^^ - -- ****: - - - 1: 开启 mDNS 功能,后续参数需要填写 - - 0: 关闭 mDNS 功能,后续参数无需填写 - -- ****:mDNS 主机名称 -- ****:mDNS 服务名称 -- ****:mDNS 端口 - -示例 -^^^^ - -:: - - AT+CWMODE=1 - AT+CWJAP="1234567890","1234567890" - AT+MDNS=1,"espressif","_iot",8080 - AT+MDNS=0 - .. _cmd-JEAP: :ref:`AT+CWJEAP `:连接 WPA2 企业版 AP