Merge branch 'docs/update_mdns_docs' into 'master'

docs(ESPAT-2032): Added instance, protocol, txt parameters to AT+MDNS command See merge request application/esp-at!1580
espressif · Jul 5, 2024 · 84b0258 · 84b0258
2 parents 8b01b67 + 9330f59
commit 84b0258
Show file tree

Hide file tree

Showing 6 changed files with 410 additions and 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
@@ -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 <https://linux.die.net/man/1/avahi-browse>`_ on linux (use `Bonjour <https://developer.apple.com/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 <https://netcat.sourceforge.net/>`_ on Linux or macOS, use `ncat <https://nmap.org/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
@@ -43,6 +43,7 @@ TCP/IP AT Commands
 -  :ref:`AT+CIPRECVLEN <cmd-CIPRECVLEN>`: Obtain socket data length in passive receiving mode.
 -  :ref:`AT+PING <cmd-CIPPING>`: Ping the remote host.
 -  :ref:`AT+CIPDNS <cmd-DNS>`: Query/Set DNS server information.
+-  :ref:`AT+MDNS <cmd-MDNS>`: Configure the mDNS function.
 -  :ref:`AT+CIPTCPOPT <cmd-TCPOPT>`: Query/Set the socket options.
 
 .. _cmd-tcpip-intro:
@@ -55,6 +56,7 @@ Introduction
 
   - Disable OTA commands (:ref:`AT+CIUPDATE <cmd-UPDATE>` and :ref:`AT+CIPFWVER <cmd-FWVER>`): ``Component config`` -> ``AT`` -> ``AT OTA command support``
   - Disable PING commands (:ref:`AT+PING <cmd-CIPPING>`): ``Component config`` -> ``AT`` -> ``AT ping command support``
+  - Disable mDNS commands (:ref:`AT+MDNS <cmd-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 <WiFi-AT>`: Configure the mDNS Function
+------------------------------------------------------------
+
+Set Command
+^^^^^^^^^^^
+
+**Command:**
+
+::
+
+    AT+MDNS=<enable>[,<"hostname">,<"service_type">,<port>][,<"instance">][,<"proto">][,<txt_number>][,<"key">,<"value">][...]
+
+**Response:**
+
+::
+
+    OK
+
+Parameters
+^^^^^^^^^^
+
+-  **<enable>**:
+
+   -  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.
+- **<port>**: mDNS service port.
+- **<"instance">**: mDNS instance name. Default: ``<"hostname">``.
+- **<"proto">**: mDNS service protocol. Recommended values: ``_tcp`` or ``_udp``. Default: ``_tcp``.
+- **<txt_number>**: 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 ``<txt_number>``.
+
+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 <example-mdns>`.
+
 .. _cmd-TCPOPT:
 
 :ref:`AT+CIPTCPOPT <TCPIP-AT>`: 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
@@ -29,7 +29,6 @@ Wi-Fi AT Commands
 -  :ref:`AT+CWSTARTSMART <cmd-STARTS>`: Start SmartConfig.
 -  :ref:`AT+CWSTOPSMART <cmd-STOPS>`: Stop SmartConfig.
 -  :ref:`AT+WPS <cmd-WPS>`: Enable the WPS function.
--  :ref:`AT+MDNS <cmd-MDNS>`: Configure the mDNS function.
 -  :ref:`AT+CWJEAP <cmd-JEAP>`: Connect to a WPA2 Enterprise AP.
 -  :ref:`AT+CWHOSTNAME <cmd-HOSTNAME>`: Query/Set the host name of an {IDF_TARGET_NAME} station.
 -  :ref:`AT+CWCOUNTRY <cmd-COUNTRY>`: Query/Set the Wi-Fi Country Code.
@@ -44,7 +43,6 @@ Introduction
 
   - Enable EAP commands (:ref:`AT+CWJEAP <cmd-JEAP>`): ``Component config`` -> ``AT`` -> ``AT WPA2 Enterprise command support``
   - Disable WPS commands (:ref:`AT+WPS <cmd-WPS>`): ``Component config`` -> ``AT`` -> ``AT WPS command support``
-  - Disable mDNS commands (:ref:`AT+MDNS <cmd-MDNS>`): ``Component config`` -> ``AT`` -> ``AT MDNS command support``
   - Disable smartconfig commands (:ref:`AT+CWSTARTSMART <cmd-STARTS>` and :ref:`AT+CWSTOPSMART <cmd-STOPS>`): ``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 <WiFi-AT>`: Configure the mDNS Function
-------------------------------------------------------------
-
-Set Command
-^^^^^^^^^^^
-
-**Command:**
-
-::
-
-    AT+MDNS=<enable>[,<hostname>,<service_name>,<port>]
-
-**Response:**
-
-::
-
-    OK 
-
-Parameters
-^^^^^^^^^^
-
--  **<enable>**:
-
-   -  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.
-
--  **<hostname>**: mDNS host name.
--  **<service_name>**: mDNS service name.
--  **<port>**: mDNS port.
-
-Example
-^^^^^^^^
-
-::
-
-    AT+CWMODE=1
-    AT+CWJAP="1234567890","1234567890"
-    AT+MDNS=1,"espressif","_iot",8080  
-    AT+MDNS=0
-
 .. _cmd-JEAP:
 
 :ref:`AT+CWJEAP <WiFi-AT>`: Connect to a WPA2 Enterprise AP