mDNS: Initial version based on IDF 5.0

.github/workflows/build_and_run_example_test_mdns.yml

@@ -0,0 +1,35 @@
+name: Build mDNS
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        idf_ver: ["latest"]
+        idf_target: ["esp32", "esp32s2", "esp32c3"]
+
+    runs-on: ubuntu-20.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@master
+        with:
+          path: esp-protocols
+      - name: Build ${{ matrix.example }} with IDF-${{ matrix.idf_ver }} for ${{ matrix.idf_target }}
+        env:
+          IDF_TARGET: ${{ matrix.idf_target }}
+        shell: bash
+        run: |
+          . ${IDF_PATH}/export.sh
+          cd $GITHUB_WORKSPACE/esp-protocols/components/mdns/examples/
+          cat sdkconfig.ci.eth_def >> sdkconfig.defaults
+          idf.py build
+          rm sdkconfig.defaults
+          cat sdkconfig.ci.eth_custom_netif >> sdkconfig.defaults
+          idf.py build
+          rm sdkconfig.defaults
+          cat sdkconfig.ci.eth_socket >> sdkconfig.defaults
+          idf.py build
+          cd $GITHUB_WORKSPACE/esp-protocols/components/mdns/tests/test_apps/
+          idf.py build

.github/workflows/publish-docs-component.yml

@@ -21,25 +21,36 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get -y install doxygen clang python3-pip
-          python -m pip install breathe recommonmark esp-docs==0.2.1
+          python -m pip install breathe recommonmark esp-docs
           cd $GITHUB_WORKSPACE/components/esp_modem/docs
           ./generate_docs
           mkdir -p $GITHUB_WORKSPACE/docs/esp_modem
           cp -r html/. $GITHUB_WORKSPACE/docs/esp_modem
+
           cd $GITHUB_WORKSPACE/components/esp_websocket_client/docs
           ./generate_docs
           mkdir -p $GITHUB_WORKSPACE/docs/esp_websocket_client
           cp -r html/. $GITHUB_WORKSPACE/docs/esp_websocket_client
+
+          cd $GITHUB_WORKSPACE/components/mdns/docs
+          ./generate_docs
+          mkdir -p $GITHUB_WORKSPACE/docs/mdns/en
+          mkdir -p $GITHUB_WORKSPACE/docs/mdns/zh_CN
+          cp -r html_en/. $GITHUB_WORKSPACE/docs/mdns/en
+          cp -r html_zh_CN/. $GITHUB_WORKSPACE/docs/mdns/zh_CN
+
           cd $GITHUB_WORKSPACE/docs
           touch .nojekyll
-          echo '<a href="esp_modem/index.html">esp-modem</a>' > index.html
+          echo '<a href="esp_modem/index.html">esp-modem</a><br>' > index.html
-          echo '<a href="esp_websocket_client/index.html">esp-websocket-client</a>' >> index.html
+          echo '<a href="esp_websocket_client/index.html">esp-websocket-client</a><br>' >> index.html
+          echo '<a href="mdns/en/index.html">mDNS_en</a><br>' >> index.html
+          echo '<a href="mdns/zh_CN/index.html">mDNS_zh_CN</a><br>' >> index.html
 
 
       - name: Upload components to component service
         uses: espressif/github-actions/upload_components@master
         with:
-          directories: "components/esp_modem;components/esp_websocket_client"
+          directories: "components/esp_modem;components/esp_websocket_client;components/mdns"
           namespace: "espressif"
           api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}
 

.github/workflows/test_afl_fuzzer.yml

@@ -0,0 +1,30 @@
+name: AFL fuzzer compilation test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        idf_ver: ["latest"]
+        idf_target: ["esp32"]
+
+    runs-on: ubuntu-20.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@master
+        with:
+          path: esp-protocols
+      - name: Install Necessary Libs
+        run: |
+          apt-get update -y
+          apt-get install -y libbsd-dev
+      - name: Build ${{ matrix.example }} with IDF-${{ matrix.idf_ver }} for ${{ matrix.idf_target }}
+        env:
+          IDF_TARGET: ${{ matrix.idf_target }}
+        shell: bash
+        run: |
+          . ${IDF_PATH}/export.sh
+          cd $GITHUB_WORKSPACE/esp-protocols/components/mdns/tests/test_afl_fuzz_host/
+          make INSTR=off

README.md

@@ -9,6 +9,11 @@
 * Brief introduction [README](components/esp_modem/README.md)
 * Full html [documentation](https://espressif.github.io/esp-protocols/esp_modem/index.html)
 
+### mDNS
+
+* Brief introduction [README](components/mdns/README.md)
+* Full html [documentation](https://espressif.github.io/esp-protocols/mdns/index.html)
+
 ### esp_websocket_client
 
 * Brief introduction [README](components/esp_websocket_client/README.md)

components/mdns/README.md

@@ -0,0 +1,11 @@
+# mDNS Service
+
+mDNS is a multicast UDP service that is used to provide local network service and host discovery.
+
+## Examples
+
+Get started with example test [Example](examples/README.md):
+
+## Documentation
+
+* View the full [html documentation](https://espressif.github.io/esp-protocols/mdns/index.html)

components/mdns/docs/Doxyfile

@@ -0,0 +1,75 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow,
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# http://doxygen.nl/manual/config.html
+
+
+PROJECT_NAME = "ESP Protocols Programming Guide"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files heder_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+
+INPUT = \
+   $(PROJECT_PATH)/include/mdns.h
+
+## Get warnings for functions that have no documentation for their parameters or return value
+##
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES) \
+    __DOXYGEN__=1 \
+    __attribute__(x)= \
+	_Static_assert()= \
+    IDF_DEPRECATED(X)= \
+    IRAM_ATTR= \
+    configSUPPORT_DYNAMIC_ALLOCATION=1 \
+    configSUPPORT_STATIC_ALLOCATION=1 \
+    configQUEUE_REGISTRY_SIZE=1 \
+    configUSE_RECURSIVE_MUTEXES=1 \
+    configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \
+    configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
+    configUSE_APPLICATION_TASK_TAG=1 \
+    configTASKLIST_INCLUDE_COREID=1 \
+    "ESP_EVENT_DECLARE_BASE(x)=extern esp_event_base_t x"
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
+
+## Skip distracting progress messages
+##
+QUIET = YES
+
+## Enable Section Tags for conditional documentation
+##
+ENABLED_SECTIONS += \
+    DOC_EXCLUDE_HEADER_SECTION \   ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.
+    DOC_SINGLE_GROUP        ## To conditionally remove groups from the documentation and create a 'flat' document without affecting documentation in upstream files.

components/mdns/docs/conf_common.py

@@ -0,0 +1,21 @@
+from esp_docs.conf_docs import *  # noqa: F403,F401
+
+extensions += ['sphinx_copybutton',
+               # Needed as a trigger for running doxygen
+               'esp_docs.esp_extensions.dummy_build_system',
+               'esp_docs.esp_extensions.run_doxygen',
+               ]
+
+# link roles config
+github_repo = 'espressif/esp-protocols'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-protocols'
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-idf' # >=5.0
+versions_url = 'https://github.com/espressif/esp-protocols/docs/docs_versions.js'
+
+idf_targets = ['esp32']
+languages = ['en', 'zh_CN']

components/mdns/docs/en/conf.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'ESP-Protocols'
+copyright = u'2016 - 2022, Espressif Systems (Shanghai) Co., Ltd'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

components/mdns/docs/en/index.rst

@@ -7,7 +7,7 @@ Overview
 
 mDNS is a multicast UDP service that is used to provide local network service and host discovery.
 
-mDNS is installed by default on most operating systems or is available as separate package. On ``Mac OS`` it is installed by default and is called ``Bonjour``. Apple releases an installer for ``Windows`` that can be found `on Apple's support page <https://support.apple.com/downloads/bonjour-for-windows>`_. On ``Linux``, mDNS is provided by `avahi <https://github.com/lathiat/avahi>`_ and is usually installed by default.
+mDNS is installed by default on most operating systems or is available as separate package. On ``Mac OS`` it is installed by default and is called ``Bonjour``. Apple releases an installer for ``Windows`` that can be found `on Apple's support page <https://support.apple.com/downloads/bonjour%2520for%2520windows>`_. On ``Linux``, mDNS is provided by `avahi <https://github.com/lathiat/avahi>`_ and is usually installed by default.
 
 mDNS Properties
 ^^^^^^^^^^^^^^^
@@ -176,10 +176,26 @@ Example of using the methods above::
         find_mdns_service("_ipp", "_tcp");
     }
 
+
+Performance Optimization
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Execution Speed
+^^^^^^^^^^^^^^^
+
+ - mDNS creates a task with default low priority 1 ``CONFIG_MDNS_TASK_PRIORITY`` (If ``CONFIG_FREERTOS_UNICORE`` enabeled it pinned to CPU0 (``CONFIG_MDNS_TASK_AFFINITY``).
+ Please check `Maximizing Execution Speed <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/performance/speed.html>`_ for more details.
+
+Minimizing RAM Usage
+^^^^^^^^^^^^^^^^^^^^
+
+- mDNS creates a tasks with stack sizes configured by ``CONFIG_MDNS_TASK_STACK_SIZE``.
+Please check `Minimizing RAM Usage <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/performance/ram-usage.html>`_ for more details.
+
 Application Example
 -------------------
 
-mDNS server/scanner example: :example:`protocols/mdns`.
+mDNS server/scanner example: :example:`<../examples>`.
 
 API Reference
 -------------

components/mdns/docs/generate_docs

@@ -0,0 +1,28 @@
+build-docs --target esp32 --language en
+build-docs --target esp32 --language zh_CN
+
+cp -rf _build/en/esp32/html html_en
+cp -rf _build/zh_CN/esp32/html html_zh_CN
+rm -rf _build __pycache__ tee
+
+# Modifes some version and target fields of index.html
+echo "<script type="text/javascript">
+window.onload =(function() {
+    var myAnchor = document.getElementById('version-select');
+    var mySpan = document.createElement('input');
+    mySpan.setAttribute('type', 'text');
+    mySpan.setAttribute('maxLength', '10');
+    mySpan.value = 'latest';
+    mySpan.setAttribute('disabled', true);
+    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+ 
+    var myAnchor = document.getElementById('target-select');
+    var mySpan = document.createElement('input');
+    mySpan.setAttribute('type', 'text');
+    mySpan.setAttribute('maxLength', '10');
+    mySpan.value = 'all targets';
+    mySpan.setAttribute('disabled', true);
+    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+
+})();
+</script>" | tee -a html_en/index.html html_zh_CN/index.html > /dev/null

components/mdns/docs/zh_CN/conf.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('..'))
+    from conf_common import *  # noqa: F403,F401
+
+import datetime
+
+current_year = datetime.datetime.now().year
+
+# General information about the project.
+project = u'ESP-IDF 编程指南'
+copyright = u'2016 - {} 乐鑫信息科技（上海）股份有限公司'.format(current_year)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'zh_CN'

components/mdns/docs/zh_CN/index.rst

@@ -7,7 +7,7 @@ mDNS 服务
 
 mDNS 是一种组播 UDP 服务，用来提供本地网络服务和主机发现。
 
-绝大多数的操作系统默认都会安装 mDNS 服务，或者提供单独的安装包。``Mac OS`` 默认会安装名为 ``Bonjour`` 的服务（该服务基于 mDNS），此外 Apple 还发布了适用于 Windows 系统的安装程序，可以在 `官方支持 <https://support.apple.com/downloads/bonjour-for-windows>`_ 找到。在 ``Linux`` 上，mDNS 服务由 `avahi <https://github.com/lathiat/avahi>`_ 提供，通常也会被默认安装。
+绝大多数的操作系统默认都会安装 mDNS 服务，或者提供单独的安装包。``Mac OS`` 默认会安装名为 ``Bonjour`` 的服务（该服务基于 mDNS），此外 Apple 还发布了适用于 Windows 系统的安装程序，可以在 `官方支持 <https://support.apple.com/downloads/bonjour%2520for%2520windows>`_ 找到。在 ``Linux`` 上，mDNS 服务由 `avahi <https://github.com/lathiat/avahi>`_ 提供，通常也会被默认安装。
 
 mDNS 属性
 ^^^^^^^^^
@@ -179,7 +179,7 @@ mDNS 提供查询服务和解析主机 IP/IPv6 地址的方法。
 应用示例
 --------
 
-有关 mDNS 服务器和查询器的应用示例请参考 :example:`protocols/mdns`。
+有关 mDNS 服务器和查询器的应用示例请参考 :example:`<../examples>`。
 
 API 参考
 --------

components/mdns/examples/CMakeLists.txt

@@ -2,9 +2,9 @@
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
-# (Not part of the boilerplate)
+set(EXTRA_COMPONENT_DIRS "../..")
 # This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
-set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/common_components/protocol_examples_common)
+list(APPEND EXTRA_COMPONENT_DIRS "../../../common_components/protocol_examples_common")
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(mdns_test)

components/mdns/examples/README.md

@@ -15,7 +15,7 @@ Shows how to use mDNS to advertise lookup services and hosts
 
 * Open the project configuration menu (`idf.py menuconfig`)
 
-* Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details.
+* Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu
 * Set `mDNS Hostname` as host name prefix for the device and its instance name in `mDNS Instance Name`
 * Disable `Resolve test services` to prevent the example from querying defined names/services on startup (cause warnings in example logs, as illustrated below)
 
@@ -89,5 +89,3 @@ I (29396) mdns-test: Query PTR: _printer._tcp.local
 2: Interface: STA, Type: V4
   PTR : HP Color LaserJet MFP M277dw (7C2E10)
 ```
-
-See the README.md file in the upper level 'examples' directory for more information about examples.

components/mdns/tests/test_afl_fuzz_host/Makefile

@@ -1,10 +1,10 @@
 TEST_NAME=test
 FUZZ=afl-fuzz
-COMPONENTS_DIR=../..
+COMPONENTS_DIR=$(IDF_PATH)/components
 COMPILER_ICLUDE_DIR=$(shell echo `which xtensa-esp32-elf-gcc | xargs dirname | xargs dirname`/xtensa-esp32-elf)
 
 CFLAGS=-g -Wno-unused-value -Wno-missing-declarations -Wno-pointer-bool-conversion -Wno-macro-redefined -Wno-int-to-void-pointer-cast -DHOOK_MALLOC_FAILED -DESP_EVENT_H_ -D__ESP_LOG_H__ \
-                 -I. -I.. -I../include -I../private_include -I ./build/config  \
+                 -I. -I../.. -I../../include -I../../private_include -I ./build/config  \
                  -I$(COMPONENTS_DIR) \
                  -I$(COMPONENTS_DIR)/driver/include \
                  -I$(COMPONENTS_DIR)/esp_common/include \
@@ -68,7 +68,7 @@ all: $(TEST_NAME)
 	@echo "[CC] $<"
 	@$(CC) $(CFLAGS) -c $< -o $@
 
-mdns.o: ../mdns.c
+mdns.o: ../../mdns.c
 	@echo "[CC] $<"
 	@$(CC) $(CFLAGS) -include mdns_mock.h $(MDNS_C_DEPENDENCY_INJECTION) -c $< -o $@
 

components/mdns/tests/test_apps/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.5)
 
 # (Not part of the boilerplate)
 # This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
-set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/common_components/protocol_examples_common)
+set(EXTRA_COMPONENT_DIRS "../../../../common_components/protocol_examples_common")
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 

components/mdns/tests/test_apps/README.md

@@ -23,7 +23,8 @@ In order to run both of them just needed to set up the project and run by 'pytho
 
 * Open the project configuration menu (`idf.py menuconfig`)
 
-* Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](README.md) for more details.
+* Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu.
+
 * Set `mDNS Hostname` as host name prefix for the device and its instance name in `mDNS Instance Name`
 
 ### Build and Flash