ASIO: Initial version based on IDF 5.0 with history

.github/workflows/build_and_run_example_test_mdns.yml

@@ -13,8 +13,9 @@ jobs:
     container: espressif/idf:${{ matrix.idf_ver }}
     steps:
       - name: Checkout esp-protocols
-        uses: actions/checkout@master
+        uses: actions/checkout@v3
         with:
+          submodules: recursive
           path: esp-protocols
       - name: Build ${{ matrix.example }} with IDF-${{ matrix.idf_ver }} for ${{ matrix.idf_target }}
         env:
@@ -23,6 +24,7 @@ jobs:
         run: |
           . ${IDF_PATH}/export.sh
           cd $GITHUB_WORKSPACE/esp-protocols/components/mdns/examples/
+          idf.py set-target ${{ matrix.idf_target }} 
           cat sdkconfig.ci.eth_def >> sdkconfig.defaults
           idf.py build
           rm sdkconfig.defaults
@@ -32,4 +34,5 @@ jobs:
           cat sdkconfig.ci.eth_socket >> sdkconfig.defaults
           idf.py build
           cd $GITHUB_WORKSPACE/esp-protocols/components/mdns/tests/test_apps/
+          idf.py set-target ${{ matrix.idf_target }} 
           idf.py build

.github/workflows/build_and_run_example_test_websocket.yml

@@ -13,7 +13,9 @@ jobs:
     container: espressif/idf:${{ matrix.idf_ver }}
     steps:
       - name: Checkout esp-protocols
-        uses: actions/checkout@v1
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
       - name: Build ${{ matrix.example }} with IDF-${{ matrix.idf_ver }} for ${{ matrix.idf_target }}
         env:
           IDF_TARGET: ${{ matrix.idf_target }}

.github/workflows/build_asio.yml

@@ -0,0 +1,28 @@
+name: Build ASIO
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        idf_ver: ["latest"]
+        idf_target: ["esp32", "esp32s2"]
+        example: ["asio_chat", "async_request", "socks4", "ssl_client_server", "tcp_echo_server", "udp_echo_server"]
+
+    runs-on: ubuntu-20.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@v3
+        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/asio/examples/${{ matrix.example }}
+          idf.py set-target ${{ matrix.idf_target }}
+          idf.py build

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

@@ -39,10 +39,16 @@ jobs:
           cp -r html_en/. $GITHUB_WORKSPACE/docs/mdns/en
           cp -r html_zh_CN/. $GITHUB_WORKSPACE/docs/mdns/zh_CN
 
+          cd $GITHUB_WORKSPACE/components/asio/docs
+          ./generate_docs
+          mkdir -p $GITHUB_WORKSPACE/docs/asio
+          cp -r html/. $GITHUB_WORKSPACE/docs/asio
+
           cd $GITHUB_WORKSPACE/docs
           touch .nojekyll
           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><br>' >> index.html
+          echo '<a href="asio/index.html">ASIO</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
 
@@ -50,7 +56,7 @@ jobs:
       - name: Upload components to component service
         uses: espressif/github-actions/upload_components@master
         with:
-          directories: "components/esp_modem;components/esp_websocket_client;components/mdns"
+          directories: "components/esp_modem;components/esp_websocket_client;components/mdns;components/asio"
           namespace: "espressif"
           api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}
 

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "components/asio/asio"]
+	path = components/asio/asio
+	url = https://github.com/espressif/asio

README.md

@@ -19,3 +19,8 @@
 
 * Brief introduction [README](components/esp_websocket_client/README.md)
 * Full html [documentation](https://espressif.github.io/esp-protocols/esp_websocket_client/index.html)
+
+### ASIO port
+
+* Brief introduction [README](components/asio/README.md)
+* Full html [documentation](https://espressif.github.io/esp-protocols/asio/index.html)

components/asio/README.md

@@ -0,0 +1,11 @@
+# ASIO port
+
+Asio is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach.
+
+## Examples
+
+Get started with example test :example:`examples <examples/..>`:
+
+## Documentation
+
+* View the full [html documentation](https://espressif.github.io/esp-protocols/asio/index.html)

components/asio/docs/Doxyfile

@@ -0,0 +1,73 @@
+# 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
+
+
+## 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/asio/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/asio/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/asio/docs/en/index.rst

@@ -32,11 +32,11 @@ Internal asio settings for ESP include
 
 Application Example
 -------------------
-ESP examples are based on standard asio :example:`protocols/asio`:
+ESP examples are based on standard asio :example:`examples <../examples>`:
 
-- :example:`protocols/asio/udp_echo_server`
-- :example:`protocols/asio/tcp_echo_server`
-- :example:`protocols/asio/asio_chat`
-- :example:`protocols/asio/ssl_client_server`
+- :example:`udp_echo_server <../examples/udp_echo_server>`
+- :example:`tcp_echo_server <../examples/tcp_echo_server>`
+- :example:`asio_chat <../examples/asio_chat>`
+- :example:`ssl_client_server <../examples/ssl_client_server>`
 
 Please refer to the specific example README.md for details

components/asio/docs/generate_docs

@@ -0,0 +1,27 @@
+build-docs --target esp32 --language en
+
+cp -rf _build/en/esp32/html .
+rm -rf _build __pycache__
+
+# 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>" >> html/index.html
+

components/asio/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/asio/examples/asio_chat/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.16)
 
 # (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)
 project(asio_chat)

components/asio/examples/async_request/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.16)
 
 # (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)
 project(async_http_request)

components/asio/examples/socks4/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.16)
 
 # (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)
 project(asio_sock4)

components/asio/examples/ssl_client_server/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.16)
 
 # (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)
 set(EXCLUDE_COMPONENTS openssl)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)

components/asio/examples/tcp_echo_server/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.16)
 
 # (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)
 project(asio_tcp_echo_server)

components/asio/examples/udp_echo_server/CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.16)
 
 # (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)
 project(asio_udp_echo_server)

components/asio/idf_component.yml

@@ -0,0 +1,5 @@
+version: "1.0.1"
+description: ASIO
+dependencies:
+  idf:
+    version: ">=5.0"