Merge pull request #502 from espressif-abhikroy/component/console_cmd_mqtt

feat(console): Added component with mqtt command

.github/workflows/clang-tidy.yml

@@ -35,7 +35,7 @@ jobs:
         working-directory: test_app
         run: |
           . ${IDF_PATH}/export.sh
-          idf.py clang-check --include-paths $GITHUB_WORKSPACE --exclude-paths $PWD --run-clang-tidy-py run-clang-tidy
+          idf.py clang-check --include-paths $GITHUB_WORKSPACE --exclude-paths $PWD --run-clang-tidy-py run-clang-tidy --run-clang-tidy-options "-checks=-clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling"
           cp warnings.txt ../
       - name: Convert clang-tidy results into SARIF output
         run: |

.github/workflows/console_cmd_mqtt__build.yml

@@ -0,0 +1,32 @@
+name: "console_cmd_mqtt: build-tests"
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+
+jobs:
+  build_console_cmd_mqtt:
+    if: contains(github.event.pull_request.labels.*.name, 'console') || github.event_name == 'push'
+    name: Build
+    strategy:
+      matrix:
+        idf_ver: ["latest", "release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3"]
+        idf_target: ["esp32"]
+        test: [ { app: mqtt_ssl_auth_console, path: "components/console_cmd_mqtt/examples" }]
+    runs-on: ubuntu-22.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build ${{ matrix.test.app }} with IDF-${{ matrix.idf_ver }} for ${{ matrix.idf_target }}
+        shell: bash
+        working-directory: ${{matrix.test.path}}
+        run: |
+          . ${IDF_PATH}/export.sh
+          pip install idf-component-manager idf-build-apps --upgrade
+          python ../../../ci/build_apps.py ./${{ matrix.test.app }} --target ${{ matrix.idf_target }} -vv --preserve-all --pytest-app

.github/workflows/modem__build-host-tests.yml

@@ -13,11 +13,8 @@ jobs:
     name: Build examples
     strategy:
       matrix:
-        idf_ver: ["latest", "release-v4.4", "release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3"]
+        idf_ver: ["latest", "release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4"]
         example: ["pppos_client", "modem_console", "modem_tcp_client", "ap_to_pppos", "simple_cmux_client"]
-        exclude:
-          - idf_ver: "release-v4.4"
-            example: modem_tcp_client
         include:
           - idf_ver: "release-v5.0"
             example: "simple_cmux_client"
@@ -26,13 +23,7 @@ jobs:
     runs-on: ubuntu-22.04
     container: espressif/idf:${{ matrix.idf_ver }}
     steps:
-      - name: Check out code (v3) # @v4 failed due to Node 20's requirement, incompatible with older IDF versions
-        if: matrix.idf_ver != 'latest' && matrix.idf_ver < 'release-v5.0'
-        uses: actions/checkout@v3
-        with:
-          path: protocols
-      - name: Check out code (v4)
-        if: matrix.idf_ver == 'latest' || matrix.idf_ver >= 'release-v5.0'
+      - name: Check out code
         uses: actions/checkout@v4
         with:
           path: protocols
@@ -53,7 +44,7 @@ jobs:
     name: Build tests
     strategy:
       matrix:
-        idf_ver: ["release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3", "latest"]
+        idf_ver: ["release-v5.0", "release-v5.1", "release-v5.2", "release-v5.3", "release-v5.4", "latest"]
         test: ["target", "target_ota", "target_iperf"]
 
     runs-on: ubuntu-22.04

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

@@ -98,7 +98,9 @@ jobs:
             components/console_cmd_ping;
             components/console_cmd_ifconfig;
             components/console_cmd_wifi;
+            components/console_cmd_mqtt;
             components/mbedtls_cxx;
             components/mosquitto;
+            components/sock_utils;
           namespace: "espressif"
           api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}

.github/workflows/sockutls_build.yml

@@ -0,0 +1,95 @@
+name: "sock_utils: build-tests"
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+
+jobs:
+  build_sock_utils:
+    if: contains(github.event.pull_request.labels.*.name, 'sock_utils') || github.event_name == 'push'
+    name: Socket helpers build
+    strategy:
+      matrix:
+        idf_ver: ["latest", "release-v5.3"]
+    runs-on: ubuntu-22.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    env:
+      TEST_DIR: components/sock_utils/examples/simple
+      TARGET_TEST_DIR: build_esp32_default
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build with IDF-${{ matrix.idf_ver }}
+        shell: bash
+        run: |
+          . ${IDF_PATH}/export.sh
+          pip install idf-component-manager idf-build-apps --upgrade
+          python ci/build_apps.py ${TEST_DIR}
+          cd ${TEST_DIR}
+          ${GITHUB_WORKSPACE}/ci/clean_build_artifacts.sh `pwd`/${TARGET_TEST_DIR}
+          zip -qur artifacts.zip ${TARGET_TEST_DIR}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sock_utils_target_esp32_${{ matrix.idf_ver }}
+          path: ${{ env.TEST_DIR }}/artifacts.zip
+          if-no-files-found: error
+  host_test_sock_utils:
+    if: contains(github.event.pull_request.labels.*.name, 'sock_utils') || github.event_name == 'push'
+    name: Socket helpers host test
+    strategy:
+      matrix:
+        idf_ver: ["latest", "release-v5.3"]
+    runs-on: ubuntu-22.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    env:
+      TEST_DIR: components/sock_utils/test/host
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build with IDF-${{ matrix.idf_ver }}
+        shell: bash
+        run: |
+          . ${IDF_PATH}/export.sh
+          pip install idf-component-manager idf-build-apps --upgrade
+          cd ${TEST_DIR}
+          idf.py build
+          ./build/sock_utils_host_test.elf
+
+  test_sock_utils:
+    # Skip running on forks since it won't have access to secrets
+    if: |
+      github.repository == 'espressif/esp-protocols' &&
+      ( contains(github.event.pull_request.labels.*.name, 'sock_utils') || github.event_name == 'push' )
+    name: Socket helpers target test
+    needs: build_sock_utils
+    strategy:
+      matrix:
+        idf_ver: ["latest", "release-v5.3"]
+    runs-on:
+      - self-hosted
+      - ESP32-ETHERNET-KIT
+    env:
+      TEST_DIR: components/sock_utils/examples/simple
+      TARGET_TEST_DIR: build_esp32_default
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: sock_utils_target_esp32_${{ matrix.idf_ver }}
+          path: ${{ env.TEST_DIR }}/ci/
+      - name: Run Test
+        working-directory: ${{ env.TEST_DIR }}
+        run: |
+          unzip ci/artifacts.zip -d ci
+          for dir in `ls -d ci/build_*`; do
+          rm -rf build sdkconfig.defaults
+          mv $dir build
+          python -m pytest --log-cli-level DEBUG --junit-xml=./results_esp32_${{ matrix.idf_ver }}_${dir#"ci/build_"}.xml --target=esp32
+          done

.pre-commit-config.yaml

@@ -61,8 +61,8 @@ repos:
   - repo: local
     hooks:
       - id: commit message scopes
-        name: "commit message must be scoped with: mdns, modem, websocket, asio, mqtt_cxx, console, common, eppp, tls_cxx, mosq"
-        entry: '\A(?!(feat|fix|ci|bump|test|docs|chore)\((mdns|modem|common|console|websocket|asio|mqtt_cxx|examples|eppp|tls_cxx|mosq)\)\:)'
+        name: "commit message must be scoped with: mdns, modem, websocket, asio, mqtt_cxx, console, common, eppp, tls_cxx, mosq, sockutls"
+        entry: '\A(?!(feat|fix|ci|bump|test|docs|chore)\((mdns|modem|common|console|websocket|asio|mqtt_cxx|examples|eppp|tls_cxx|mosq|sockutls)\)\:)'
         language: pygrep
         args: [--multiline]
         stages: [commit-msg]

README.md

@@ -62,3 +62,7 @@ Please refer to instructions in [ESP-IDF](https://github.com/espressif/esp-idf)
 
 * Brief introduction [README](components/mosquitto/README.md)
 * API documentation [api.md](components/mosquitto/api.md)
+
+### Socket helpers (sock-utils)
+
+* Brief introduction [README](components/sock_utils/README.md)

components/console_cmd_mqtt/.cz.yaml

@@ -0,0 +1,8 @@
+---
+commitizen:
+  bump_message: 'bump(console): $current_version -> $new_version'
+  pre_bump_hooks: python ../../ci/changelog.py console_cmd_mqtt
+  tag_format: console_cmd_mqtt-v$version
+  version: 1.0.0
+  version_files:
+  - idf_component.yml

components/console_cmd_mqtt/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [1.0.0](https://github.com/espressif/esp-protocols/commits/console_cmd_mqtt-v1.0.0)
+
+### Features
+
+- Added component with mqtt command ([1fcc5b1d](https://github.com/espressif/esp-protocols/commit/1fcc5b1d))

components/console_cmd_mqtt/CMakeLists.txt

@@ -0,0 +1,7 @@
+idf_component_register(SRCS "console_mqtt.c"
+                    INCLUDE_DIRS "."
+                    PRIV_REQUIRES esp_netif console mqtt)
+
+if(CONFIG_MQTT_CMD_AUTO_REGISTRATION)
+    target_link_libraries(${COMPONENT_LIB} PRIVATE "-u console_cmd_mqtt_register")
+endif()

components/console_cmd_mqtt/Kconfig.projbuild

@@ -0,0 +1,15 @@
+menu "MQTT Configuration"
+
+    config MQTT_CMD_AUTO_REGISTRATION
+        bool "Enable Console command mqtt Auto-registration"
+        default y
+        help
+            Enabling this allows for the autoregistration of the wifi command.
+
+    config MQTT_BROKER_URL
+        string "Broker URL or IP address"
+        default "mqtt://mqtt.eclipseprojects.io"
+        help
+            URL or IP address of the broker to connect to
+
+endmenu

components/console_cmd_mqtt/README.md

@@ -0,0 +1,87 @@
+# Console command mqtt
+The component provides a console where mqtt commands can be executed.
+
+
+## MQTT Configuration:
+1. Broker: Use menuconfig **"MQTT Configuration"** to configure the broker url.
+
+
+## API
+
+### Steps to enable console in an example code:
+1. Add this component to your project using ```idf.py add-dependency``` command.
+2. In the main file of the example, add the following line:
+    ```c
+    #include "console_mqtt.h"
+    ```
+3. Ensure esp-netif is initialized and default event loop is created in your app_main():
+    ```c
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    ```
+4. In your app_main() function, add the following line as the last line:
+    ```c
+    ESP_ERROR_CHECK(console_cmd_init());     // Initialize console
+
+    // Register all plugin command added to your project
+    ESP_ERROR_CHECK(console_cmd_all_register());
+
+    // To register only mqtt command skip calling console_cmd_all_register()
+    ESP_ERROR_CHECK(console_cmd_mqtt_register());
+
+    ESP_ERROR_CHECK(console_cmd_start());    // Start console
+    ```
+
+Note: Auto-registration of a specific plugin command can be disabled from menuconfig.
+
+### Certificate Integration for Mutual Authentication
+To enhance security and enable secure communication over MQTT, three functions have been added to the API, allowing users to set client certificates, client keys, and broker certificates separately.
+
+Setting the client certificate:
+```c
+set_mqtt_client_cert(client_cert_pem_start, client_cert_pem_end);
+```
+Setting the client key:
+```c
+set_mqtt_client_key(client_key_pem_start, client_key_pem_end);
+```
+Setting the broker certificate:
+```c
+set_mqtt_broker_certs(broker_cert_pem_start, broker_cert_pem_end);
+```
+Each function takes pointers to the start and end of the respective PEM-encoded data, allowing users to specify the necessary certificate and key information independently. For a complete secure MQTT setup, users should call all three functions in their application code.
+
+To utilize these certificates, users need to include additional arguments when establishing MQTT connections using the library. Specifically, users should provide the `--cert`, `--key`, and `--cafile` options along with the MQTT connection command.
+
+### Adding a plugin command or component:
+To add a plugin command or any component from IDF component manager into your project, simply include an entry within the `idf_component.yml` file.
+
+For more details refer [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html)
+
+## Suported command:
+
+### mqtt:
+```
+mqtt  [-CsD] [-h <host>] [-u <username>] [-P <password>] [--cert] [--key] [--cafile]
+  mqtt command
+  -C, --connect  Connect to a broker (flag, no argument)
+  -h, --host=<host>  Specify the host uri to connect to
+  -s, --status  Displays the status of the mqtt client (flag, no argument)
+  -u, --username=<username>  Provide a username to be used for authenticating with the broker
+  -P, --password=<password>  Provide a password to be used for authenticating with the broker
+      --cert  Define the PEM encoded certificate for this client, if required by the broker (flag, no argument)
+      --key  Define the PEM encoded private key for this client, if required by the broker (flag, no argument)
+      --cafile  Define the PEM encoded CA certificates that are trusted (flag, no argument)
+      --use-internal-bundle  Use the internal certificate bundle for TLS (flag, no argument)
+  -D, --disconnect  Disconnect from the broker (flag, no argument)
+
+mqtt_pub  [-t <topic>] [-m <message>]
+  mqtt publish command
+  -t, --topic=<topic>  Topic to Subscribe/Publish
+  -m, --message=<message>  Message to Publish
+
+mqtt_sub  [-U] [-t <topic>]
+  mqtt subscribe command
+  -t, --topic=<topic>  Topic to Subscribe/Publish
+  -U, --unsubscribe  Unsubscribe from a topic
+```

components/console_cmd_mqtt/console_mqtt.c

@@ -0,0 +1,475 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <stdio.h>
+#include <string.h>
+#include "sdkconfig.h"
+#include "esp_console.h"
+#include "esp_event.h"
+#include "esp_log.h"
+#include "argtable3/argtable3.h"
+#include "console_mqtt.h"
+#include "mqtt_client.h"
+#if defined(CONFIG_MBEDTLS_CERTIFICATE_BUNDLE)
+#include "esp_crt_bundle.h"
+#endif
+
+static const char *TAG = "console_mqtt";
+
+#define CONNECT_HELP_MSG "mqtt -C -h <host uri> -u <username> -P <password> --cert --key --cafile\n"
+#define PUBLISH_HELP_MSG "Usage: mqtt -P -t <topic> -d <data>\n"
+#define SUBSCRIBE_HELP_MSG "Usage: mqtt -S -t <topic>\n"
+#define UNSUBSCRIBE_HELP_MSG "Usage: mqtt -U\n"
+#define DISCONNECT_HELP_MSG "Usage: mqtt -D\n"
+
+#if CONFIG_MQTT_CMD_AUTO_REGISTRATION
+/**
+ * Static registration of this plugin is achieved by defining the plugin description
+ * structure and placing it into .console_cmd_desc section.
+ * The name of the section and its placement is determined by linker.lf file in 'plugins' component.
+ */
+static const console_cmd_plugin_desc_t __attribute__((section(".console_cmd_desc"), used)) PLUGIN = {
+    .name = "console_cmd_mqtt",
+    .plugin_regd_fn = &console_cmd_mqtt_register
+};
+#endif
+
+static struct {
+    struct arg_lit *connect;
+    struct arg_str *uri;
+    struct arg_lit *status;
+    struct arg_str *username;
+    struct arg_str *password;
+    struct arg_lit *cert;
+    struct arg_lit *key;
+    struct arg_lit *cafile;
+#if defined(CONFIG_MBEDTLS_CERTIFICATE_BUNDLE)
+    struct arg_lit *use_internal_bundle;
+#endif
+    struct arg_lit *disconnect;
+
+    struct arg_end *end;
+} mqtt_args;
+
+static struct {
+    struct arg_str *topic;
+    struct arg_lit *unsubscribe;
+
+    struct arg_end *end;
+} mqtt_sub_args;
+
+static struct {
+    struct arg_str *topic;
+    struct arg_str *message;
+
+    struct arg_end *end;
+} mqtt_pub_args;
+
+typedef enum {
+    MQTT_STATE_INIT = 0,
+    MQTT_STATE_DISCONNECTED,
+    MQTT_STATE_CONNECTED,
+    MQTT_STATE_ERROR,
+    MQTT_STATE_STOPPED,
+} mqtt_client_state_t;
+
+mqtt_client_state_t client_status = MQTT_STATE_INIT;
+
+static esp_mqtt_client_handle_t client_handle = NULL;
+
+static const uint8_t *s_own_cert_pem_start = NULL;
+static const uint8_t *s_own_cert_pem_end = NULL;
+static const uint8_t *s_own_key_pem_start = NULL;
+static const uint8_t *s_own_key_pem_end = NULL;
+static const uint8_t *s_ca_cert_pem_start = NULL;
+static const uint8_t *s_ca_cert_pem_end = NULL;
+
+static void log_error_if_nonzero(const char *message, int error_code)
+{
+    if (error_code != 0) {
+        ESP_LOGE(TAG, "Last error %s: 0x%x", message, error_code);
+    }
+}
+
+/*
+ * @brief Event handler registered to receive MQTT events
+ *
+ *  This function is called by the MQTT client event loop.
+ *
+ * @param handler_args user data registered to the event.
+ * @param base Event base for the handler(always MQTT Base in this example).
+ * @param event_id The id for the received event.
+ * @param event_data The data for the event, esp_mqtt_event_handle_t.
+ */
+static void mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id, void *event_data)
+{
+    ESP_LOGD(TAG, "Event dispatched from event loop base=%s, event_id=%" PRIi32, base, event_id);
+    esp_mqtt_event_handle_t event = event_data;
+    switch ((esp_mqtt_event_id_t)event_id) {
+    case MQTT_EVENT_BEFORE_CONNECT:
+        ESP_LOGI(TAG, "MQTT_EVENT_BEFORE_CONNECT");
+        break;
+    case MQTT_EVENT_CONNECTED:
+        client_status = MQTT_STATE_CONNECTED;
+        ESP_LOGI(TAG, "MQTT_EVENT_CONNECTED");
+        break;
+    case MQTT_EVENT_DISCONNECTED:
+        client_status = MQTT_STATE_DISCONNECTED;
+        ESP_LOGI(TAG, "MQTT_EVENT_DISCONNECTED");
+        break;
+    case MQTT_EVENT_SUBSCRIBED:
+        ESP_LOGI(TAG, "MQTT_EVENT_SUBSCRIBED, msg_id=%d", event->msg_id);
+        break;
+    case MQTT_EVENT_UNSUBSCRIBED:
+        ESP_LOGI(TAG, "MQTT_EVENT_UNSUBSCRIBED, msg_id=%d", event->msg_id);
+        break;
+    case MQTT_EVENT_PUBLISHED:
+        ESP_LOGI(TAG, "MQTT_EVENT_PUBLISHED, msg_id=%d", event->msg_id);
+        break;
+    case MQTT_EVENT_DATA:
+        ESP_LOGI(TAG, "MQTT_EVENT_DATA");
+        ESP_LOGI(TAG, "TOPIC=%.*s\r\n", event->topic_len, event->topic);
+        ESP_LOGI(TAG, "DATA=%.*s\r\n", event->data_len, event->data);
+        break;
+    case MQTT_EVENT_ERROR:
+        client_status = MQTT_STATE_ERROR;
+        ESP_LOGI(TAG, "MQTT_EVENT_ERROR");
+        if (event->error_handle->error_type == MQTT_ERROR_TYPE_TCP_TRANSPORT) {
+            log_error_if_nonzero("reported from esp-tls", event->error_handle->esp_tls_last_esp_err);
+            log_error_if_nonzero("reported from tls stack", event->error_handle->esp_tls_stack_err);
+            log_error_if_nonzero("captured as transport's socket errno",  event->error_handle->esp_transport_sock_errno);
+            ESP_LOGI(TAG, "Last errno string (%s)", strerror(event->error_handle->esp_transport_sock_errno));
+        }
+        break;
+    default:
+        ESP_LOGI(TAG, "Other event id:%d", event->event_id);
+        break;
+    }
+}
+
+
+static const char *mqtt_state_to_string(mqtt_client_state_t state)
+{
+    switch (state) {
+    case MQTT_STATE_INIT:
+        return "Initializing";
+    case MQTT_STATE_DISCONNECTED:
+        return "Disconnected";
+    case MQTT_STATE_CONNECTED:
+        return "Connected";
+    case MQTT_STATE_ERROR:
+        return "Error";
+    case MQTT_STATE_STOPPED:
+        return "Disconnected and Stopped";
+    default:
+        return "Unknown State";
+    }
+}
+
+
+static int do_mqtt_cmd(int argc, char **argv)
+{
+    int nerrors = arg_parse(argc, argv, (void **)&mqtt_args);
+    if (nerrors != 0) {
+        arg_print_errors(stderr, mqtt_args.end, argv[0]);
+        return 1;
+    }
+
+    if (mqtt_args.status->count > 0) {
+        ESP_LOGI(TAG, "MQTT Client Status: %s\n", mqtt_state_to_string(client_status));
+        return 0;
+    }
+
+    if (mqtt_args.connect->count > 0) {
+
+        if (client_handle != NULL) {
+            ESP_LOGW(TAG, "mqtt client already connected");
+            ESP_LOGI(TAG, "Try: %s", DISCONNECT_HELP_MSG);
+            return 0;
+        }
+
+        char *uri = CONFIG_MQTT_BROKER_URL;
+        if (mqtt_args.uri->count > 0) {
+            uri = (char *)mqtt_args.uri->sval[0];
+        }
+
+        esp_mqtt_client_config_t mqtt_cfg = {
+            .broker.address.uri = uri,
+        };
+
+        if ((mqtt_args.username->count > 0) && (mqtt_args.password->count > 0)) {
+            mqtt_cfg.credentials.username = mqtt_args.username->sval[0];
+            mqtt_cfg.credentials.authentication.password = mqtt_args.password->sval[0];
+        }
+
+        ESP_LOGI(TAG, "broker: %s", mqtt_cfg.broker.address.uri);
+
+#if defined(CONFIG_MBEDTLS_CERTIFICATE_BUNDLE)
+        /* Ensure --use_internal_bundle and --cafile are mutually exclusive */
+        if ((mqtt_args.use_internal_bundle->count > 0) && (mqtt_args.cafile->count > 0)) {
+            ESP_LOGE(TAG, "Error: Options can't be used together. Use either --use-internal-bundle or --cafile.  \n");
+            return 1;
+        }
+
+        if (mqtt_args.use_internal_bundle->count > 0) {
+            mqtt_cfg.broker.verification.crt_bundle_attach = esp_crt_bundle_attach;
+        }
+#endif
+
+        if (mqtt_args.cafile->count > 0) {
+            if (s_ca_cert_pem_start && s_ca_cert_pem_end) {
+                mqtt_cfg.broker.verification.certificate = (const char *)s_ca_cert_pem_start;
+            } else {
+                ESP_LOGW(TAG, "cafile not provided");
+            }
+        }
+
+        if (mqtt_args.cert->count > 0) {
+            if (s_own_cert_pem_start && s_own_cert_pem_end) {
+                mqtt_cfg.credentials.authentication.certificate = (const char *)s_own_cert_pem_start;
+            } else {
+                ESP_LOGW(TAG, "cert not provided");
+            }
+
+            if (mqtt_args.key->count > 0) {
+                if (s_own_key_pem_start && s_own_key_pem_end) {
+                    mqtt_cfg.credentials.authentication.key = (const char *)s_own_key_pem_start;
+                } else {
+                    ESP_LOGW(TAG, "key not provided");
+                }
+            } else {
+                mqtt_cfg.credentials.authentication.key = NULL;
+            }
+        }
+
+        client_handle = esp_mqtt_client_init(&mqtt_cfg);
+        if (client_handle == NULL) {
+            ESP_LOGE(TAG, "ERROR: Client init");
+            ESP_LOGI(TAG, "Try: %s", DISCONNECT_HELP_MSG);
+            ESP_LOGE(TAG, CONNECT_HELP_MSG);
+            return 1;
+        }
+
+        /* The last argument may be used to pass data to the event handler, in this example mqtt_event_handler */
+        esp_mqtt_client_register_event(client_handle, ESP_EVENT_ANY_ID, mqtt_event_handler, NULL);
+        esp_mqtt_client_start(client_handle);
+
+    } else if (mqtt_args.disconnect->count > 0) {
+        ESP_LOGD(TAG, "Disconnect command received:");
+
+        if (client_handle == NULL) {
+            ESP_LOGE(TAG, "mqtt client not connected");
+            return 0;
+        }
+
+        if (esp_mqtt_client_stop(client_handle) != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to stop mqtt client task");
+            return 1;
+        }
+
+        client_handle = NULL;
+        client_status = MQTT_STATE_STOPPED;
+        ESP_LOGI(TAG, "mqtt client disconnected and stopped");
+    }
+
+    return 0;
+}
+
+
+esp_err_t set_mqtt_client_cert(const uint8_t *client_cert_pem_start_i, const uint8_t *client_cert_pem_end_i)
+{
+    if (!client_cert_pem_start_i || !client_cert_pem_end_i ||
+            (client_cert_pem_start_i > client_cert_pem_end_i)) {
+        ESP_LOGE(TAG, "Invalid mqtt Client certs(%d)\n", __LINE__);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    s_own_cert_pem_start = client_cert_pem_start_i;
+    s_own_cert_pem_end = client_cert_pem_end_i;
+
+    return ESP_OK;
+}
+
+
+esp_err_t set_mqtt_client_key(const uint8_t *client_key_pem_start_i, const uint8_t *client_key_pem_end_i)
+{
+    if (client_key_pem_start_i && client_key_pem_end_i &&
+            (client_key_pem_start_i >= client_key_pem_end_i)) {
+        ESP_LOGE(TAG, "Invalid mqtt Client key(%d)\n", __LINE__);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    s_own_key_pem_start = client_key_pem_start_i;
+    s_own_key_pem_end = client_key_pem_end_i;
+
+    return ESP_OK;
+}
+
+
+esp_err_t set_mqtt_broker_certs(const uint8_t *ca_cert_pem_start_i, const uint8_t *ca_cert_pem_end_i)
+{
+    if (!ca_cert_pem_start_i || !ca_cert_pem_end_i ||
+            (ca_cert_pem_start_i > ca_cert_pem_end_i)) {
+        ESP_LOGE(TAG, "Invalid mqtt ca cert(%d)\n", __LINE__);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    s_ca_cert_pem_start = ca_cert_pem_start_i;
+    s_ca_cert_pem_end = ca_cert_pem_end_i;
+
+    return ESP_OK;
+}
+
+
+static int do_mqtt_sub_cmd(int argc, char **argv)
+{
+    int msg_id;
+    int nerrors = arg_parse(argc, argv, (void **)&mqtt_sub_args);
+    if (nerrors != 0) {
+        arg_print_errors(stderr, mqtt_sub_args.end, argv[0]);
+        return 1;
+    }
+
+    if (client_handle == NULL) {
+        ESP_LOGE(TAG, "mqtt client not connected");
+        return 0;
+    }
+
+    if (mqtt_sub_args.unsubscribe->count > 0) {
+        if (mqtt_sub_args.topic->count <= 0) {
+            ESP_LOGE(TAG, UNSUBSCRIBE_HELP_MSG);
+            return 0;
+        }
+        char *topic = (char *)mqtt_sub_args.topic->sval[0];
+
+        msg_id = esp_mqtt_client_unsubscribe(client_handle, mqtt_sub_args.topic->sval[0]);
+        ESP_LOGI(TAG, "Unsubscribe successful, msg_id=%d, topic=%s", msg_id, topic);
+
+    } else {
+        if (mqtt_sub_args.topic->count <= 0) {
+            ESP_LOGE(TAG, SUBSCRIBE_HELP_MSG);
+            return 0;
+        }
+        char *topic = (char *)mqtt_sub_args.topic->sval[0];
+
+        msg_id = esp_mqtt_client_subscribe(client_handle, topic, 0);
+        ESP_LOGI(TAG, "Subscribe successful, msg_id=%d, topic=%s", msg_id, topic);
+
+    }
+
+    return 0;
+}
+
+
+static int do_mqtt_pub_cmd(int argc, char **argv)
+{
+    int msg_id;
+    int nerrors = arg_parse(argc, argv, (void **)&mqtt_pub_args);
+    if (nerrors != 0) {
+        arg_print_errors(stderr, mqtt_pub_args.end, argv[0]);
+        return 1;
+    }
+
+    if (client_handle == NULL) {
+        ESP_LOGE(TAG, "mqtt client not connected");
+        return 0;
+    }
+
+    if ((mqtt_pub_args.topic->count <= 0) || (mqtt_pub_args.message->count <= 0)) {
+        ESP_LOGE(TAG, PUBLISH_HELP_MSG);
+    }
+
+    msg_id = esp_mqtt_client_publish(client_handle,
+                                     mqtt_pub_args.topic->sval[0],
+                                     mqtt_pub_args.message->sval[0],
+                                     0, 1, 0);
+    if (msg_id == -1) {
+        ESP_LOGE(TAG, "mqtt client not connected");
+        return 0;
+    }
+    ESP_LOGI(TAG, "Publish successful, msg_id=%d, topic=%s, data=%s",
+             msg_id, mqtt_pub_args.topic->sval[0], mqtt_pub_args.message->sval[0]);
+
+    return 0;
+}
+
+/**
+ * @brief Registers the mqtt commands.
+ *
+ * @return
+ *          - esp_err_t
+ */
+esp_err_t console_cmd_mqtt_register(void)
+{
+    esp_err_t ret = ESP_OK;
+
+    /* Register mqtt */
+    mqtt_args.connect = arg_lit0("C", "connect", "Connect to a broker (flag, no argument)");
+    mqtt_args.uri = arg_str0("h", "host", "<host>", "Specify the host uri to connect to");
+    mqtt_args.status = arg_lit0("s", "status", "Displays the status of the mqtt client (flag, no argument)");
+    mqtt_args.username = arg_str0("u", "username", "<username>", "Provide a username to be used for authenticating with the broker");
+    mqtt_args.password = arg_str0("P", "password", "<password>", "Provide a password to be used for authenticating with the broker");
+    mqtt_args.cert = arg_lit0(NULL, "cert", "Define the PEM encoded certificate for this client, if required by the broker (flag, no argument)");
+    mqtt_args.key = arg_lit0(NULL, "key", "Define the PEM encoded private key for this client, if required by the broker (flag, no argument)");
+    mqtt_args.cafile = arg_lit0(NULL, "cafile", "Define the PEM encoded CA certificates that are trusted (flag, no argument)");
+#if defined(CONFIG_MBEDTLS_CERTIFICATE_BUNDLE)
+    mqtt_args.use_internal_bundle = arg_lit0(NULL, "use-internal-bundle", "Use the internal certificate bundle for TLS (flag, no argument)");
+#endif
+    mqtt_args.disconnect = arg_lit0("D", "disconnect", "Disconnect from the broker (flag, no argument)");
+    mqtt_args.end = arg_end(1);
+
+    const esp_console_cmd_t mqtt_cmd = {
+        .command = "mqtt",
+        .help = "mqtt command",
+        .hint = NULL,
+        .func = &do_mqtt_cmd,
+        .argtable = &mqtt_args
+    };
+
+    ret = esp_console_cmd_register(&mqtt_cmd);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Unable to register mqtt");
+        return ret;
+    }
+
+    /* Register mqtt_pub */
+    mqtt_pub_args.topic = arg_str0("t", "topic", "<topic>", "Topic to Subscribe/Publish");
+    mqtt_pub_args.message = arg_str0("m", "message", "<message>", "Message to Publish");
+    mqtt_pub_args.end = arg_end(1);
+
+    const esp_console_cmd_t mqtt_pub_cmd = {
+        .command = "mqtt_pub",
+        .help = "mqtt publish command",
+        .hint = NULL,
+        .func = &do_mqtt_pub_cmd,
+        .argtable = &mqtt_pub_args
+    };
+
+    ret = esp_console_cmd_register(&mqtt_pub_cmd);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Unable to register mqtt_pub");
+        return ret;
+    }
+
+    /* Register mqtt_sub */
+    mqtt_sub_args.topic = arg_str0("t", "topic", "<topic>", "Topic to Subscribe/Publish");
+    mqtt_sub_args.unsubscribe = arg_lit0("U", "unsubscribe", "Unsubscribe from a topic");
+    mqtt_sub_args.end = arg_end(1);
+
+    const esp_console_cmd_t mqtt_sub_cmd = {
+        .command = "mqtt_sub",
+        .help = "mqtt subscribe command",
+        .hint = NULL,
+        .func = &do_mqtt_sub_cmd,
+        .argtable = &mqtt_sub_args
+    };
+
+    ret = esp_console_cmd_register(&mqtt_sub_cmd);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Unable to register mqtt_sub");
+    }
+
+    return ret;
+}

components/console_cmd_mqtt/console_mqtt.h

@@ -0,0 +1,73 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "console_simple_init.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Registers the mqtt command.
+ *
+ * @return
+ *          - esp_err_t
+ */
+esp_err_t console_cmd_mqtt_register(void);
+
+
+/**
+ * @brief Set MQTT client certificate
+ *
+ *  This function sets the MQTT client certificate for secure communication.
+ *  The function takes the PEM(Privacy Enhanced Mail) encoded certificate arguments.
+ *
+ * @param client_cert_pem_start_i Pointer to the beginning of the client certificate PEM data.
+ * @param client_cert_pem_end_i Pointer to the end of the client certificate PEM data.
+ *
+ * @return
+ *      ESP_OK on success
+ *      ESP_ERR_INVALID_ARG on invalid arguments
+ */
+esp_err_t set_mqtt_client_cert(const uint8_t *client_cert_pem_start_i, const uint8_t *client_cert_pem_end_i);
+
+
+/**
+ * @brief Set MQTT client key
+ *
+ *  This function sets the MQTT client key for secure communication.
+ *  The function takes the PEM(Privacy Enhanced Mail) encoded key arguments.
+ *
+ * @param client_key_pem_start_i Pointer to the beginning of the client key PEM data.
+ * @param client_key_pem_end_i Pointer to the end of the client key PEM data.
+ *
+ * @return
+ *      ESP_OK on success
+ *      ESP_ERR_INVALID_ARG on invalid arguments
+ */
+esp_err_t set_mqtt_client_key(const uint8_t *client_key_pem_start_i, const uint8_t *client_key_pem_end_i);
+
+
+/**
+ * @brief Set MQTT broker certificate
+ *
+ *  This function sets the MQTT broker certificate for secure communication.
+ *  The function takes the PEM(Privacy Enhanced Mail) encoded broker certificate arguments.
+ *
+ * @param broker_cert_pem_start_i Pointer to the beginning of the broker certificate PEM data.
+ * @param broker_cert_pem_end_i Pointer to the end of the broker certificate PEM data.
+ *
+ * @return
+ *      ESP_OK on success
+ *      ESP_ERR_INVALID_ARG on invalid arguments
+ */
+esp_err_t set_mqtt_broker_certs(const uint8_t *broker_cert_pem_start_i, const uint8_t *broker_cert_pem_end_i);
+
+#ifdef __cplusplus
+}
+#endif

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/CMakeLists.txt

@@ -0,0 +1,11 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mqtt_ssl_auth_console)
+
+# Certs for mqtts://test.mosquitto.org:8884
+target_add_binary_data(${CMAKE_PROJECT_NAME}.elf "certs/client.crt" TEXT)
+target_add_binary_data(${CMAKE_PROJECT_NAME}.elf "certs/client.key" TEXT)
+target_add_binary_data(${CMAKE_PROJECT_NAME}.elf "certs/mosquitto.org.pem" TEXT)

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/README.md

@@ -0,0 +1,174 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
+
+# ESP-MQTT SSL Authentication Console
+
+This example demonstrates the use of the MQTT command-line component to connect to both secured and unsecured MQTT brokers. It provides multiple modes of connection, including:
+
+* Unsecured transport: Connect to a broker without encryption.
+* SSL/TLS transport: Securely connect using SSL/TLS with options for:
+  * Validating the broker using a provided CA certificate.
+  * Validating the broker using the internal certificate bundle.
+  * Performing SSL mutual authentication using client and broker certificates.
+
+Additionally, the example allows subscribing to topics, unsubscribing from topics, and publishing messages to a specified topic through commands. Connections to the broker at test.mosquitto.org are used to demonstrate these features.
+(Please note that the public broker is maintained by the community so may not be always available, for details please visit http://test.mosquitto.org)
+
+It uses ESP-MQTT library which implements mqtt client to connect to mqtt broker.
+
+## How to use example
+
+### Hardware Required
+
+This example can be executed on any ESP32 board, the only required interface is WiFi and connection to internet.
+
+### Configure the project
+
+* 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.
+
+* Generate your client keys and certificate (specific to testing with Mosquitto broker)
+
+Note: The following steps are for testing with the Mosquitto broker. If you're using a different broker, you may need to adapt the steps to meet your broker's certificate and key requirements.
+
+#### Steps for SSL Mutual authentication:
+Navigate to the certs directory
+
+```
+cd certs
+```
+
+Generate a client key and a CSR. When you are generating the CSR, do not use the default values. At a minimum, the CSR must include the Country, Organisation and Common Name fields.
+
+```
+openssl genrsa -out client.key
+openssl req -out client.csr -key client.key -new
+```
+
+Paste the generated CSR in the [Mosquitto test certificate signer](https://test.mosquitto.org/ssl/index.php), click Submit and copy the downloaded `client.crt` in the `main` directory.
+
+Please note, that the supplied files `client.crt` and `client.key` in the `main` directory are only placeholders for your client certificate and key (i.e. the example "as is" would compile but would not connect to the broker)
+
+The broker certificate `mosquitto.org.pem` can be downloaded in pem format from [mosquitto.org.crt](https://test.mosquitto.org/ssl/mosquitto.org.crt). Convert it to `mosquitto.org.pem` simply by renaming it.
+
+Note: If your certificate and key file names differ, update the root `CMakeLists.txt` file and main/`mqtt_ssl_auth_console.c` accordingly.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+Warning: This example might need a bigger app partition size if you're compiling it for debug. To ensere this issue doesn't happen "optimize for size is enabled in menuconfig.
+
+### Command Usage:
+```
+esp> help
+help  [<string>]
+  Print the summary of all registered commands if no arguments are given,
+  otherwise print summary of given command.
+      <string>  Name of command
+
+mqtt  [-CsD] [-h <host>] [-u <username>] [-P <password>] [--cert] [--key] [--cafile]
+  mqtt command
+  -C, --connect  Connect to a broker (flag, no argument)
+  -h, --host=<host>  Specify the host uri to connect to
+  -s, --status  Displays the status of the mqtt client (flag, no argument)
+  -u, --username=<username>  Provide a username to be used for authenticating with the broker
+  -P, --password=<password>  Provide a password to be used for authenticating with the broker
+      --cert  Define the PEM encoded certificate for this client, if required by the broker (flag, no argument)
+      --key  Define the PEM encoded private key for this client, if required by the broker (flag, no argument)
+      --cafile  Define the PEM encoded CA certificates that are trusted (flag, no argument)
+      --use-internal-bundle  Use the internal certificate bundle for TLS (flag, no argument)
+  -D, --disconnect  Disconnect from the broker (flag, no argument)
+
+mqtt_pub  [-t <topic>] [-m <message>]
+  mqtt publish command
+  -t, --topic=<topic>  Topic to Subscribe/Publish
+  -m, --message=<message>  Message to Publish
+
+mqtt_sub  [-U] [-t <topic>]
+  mqtt subscribe command
+  -t, --topic=<topic>  Topic to Subscribe/Publish
+  -U, --unsubscribe  Unsubscribe from a topic
+```
+
+### Connection:
+
+#### Connect without Validating the Broker:
+This option connects to the broker without validating its certificate. It is not secure.
+```
+mqtt -h mqtts://test.mosquitto.org -C
+```
+or
+```
+mqtt -h mqtts://mqtt.eclipseprojects.io -C
+```
+
+#### Validate the Broker using the Internal Certificate Bundle:
+This option uses the ESP-IDF's built-in certificate bundle to verify the broker's identity.
+```
+mqtt -h mqtts://mqtt.eclipseprojects.io -C --use-internal-bundle
+```
+or
+```
+mqtt -h mqtts://test.mosquitto.org -C --use-internal-bundle
+```
+
+#### Validate the Broker using a Provided CA Certificate:
+This option requires you to provide the broker's CA certificate for validation.
+```
+mqtt -h mqtts://test.mosquitto.org -C --cafile
+```
+
+
+#### SSL Mutual Authentication(encrypted, client certificate required):
+This option performs client authentication in addition to broker validation. It requires the client certificate, private key, and broker CA certificate.
+```
+mqtt -h mqtts://test.mosquitto.org:8884 -C --cert --key --cafile
+```
+or
+```
+mqtt -h mqtts://test.mosquitto.org:8884 -C --cert --key --use-internal-bundle
+```
+
+Note: In this example, the broker's certificate is included in the certificate bundle (refer to sdkconfig.default).
+
+### Disconnect:
+```
+esp> mqtt -D
+I (1189949) console_mqtt: mqtt client disconnected
+```
+
+### Subscribe/Unsubscribe:
+```
+esp> mqtt_sub -t test0
+I (897289) console_mqtt: Subscribe successful, msg_id=57425, topic=test0
+esp> I (897799) console_mqtt: MQTT_EVENT_SUBSCRIBED, msg_id=57425
+esp>
+esp> mqtt_sub -U -t test0
+I (902009) console_mqtt: Unsubscribe successful, msg_id=27663, topic=test0
+esp> I (902509) console_mqtt: MQTT_EVENT_UNSUBSCRIBED, msg_id=27663
+```
+
+### Publish:
+```
+esp> mqtt_pub -t test0 -m "Hello, Testing 123"
+I (999469) console_mqtt: Publish successful, msg_id=55776, topic=test0, data=Hello, Testing 123
+I (1000009) console_mqtt: MQTT_EVENT_PUBLISHED, msg_id=55776
+esp>
+```
+
+### Receiving data event:
+```
+esp> I (999999) console_mqtt: MQTT_EVENT_DATA
+I (999999) console_mqtt: TOPIC=test0
+
+I (999999) console_mqtt: DATA=Hello, Testing 123
+```

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/certs/mosquitto.org.pem

@@ -0,0 +1,24 @@
+-----BEGIN CERTIFICATE-----
+MIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL
+BQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG
+A1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU
+BgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv
+by5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE
+BhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES
+MBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp
+dHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ
+KoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg
+UZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW
+Te3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA
+s06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH
+3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo
+E6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT
+MFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV
+6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL
+BQADggEBAGa9kS21N70ThM6/Hj9D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC
+6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf
++pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK
+sMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839
+LdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE
+m/XriWr/Cq4h/JfB7NTsezVslgkBaoU=
+-----END CERTIFICATE-----

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "mqtt_ssl_auth_console.c"
+                    INCLUDE_DIRS ".")

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/main/idf_component.yml

@@ -0,0 +1,8 @@
+dependencies:
+  idf:
+    version: ">=5.0"
+  protocol_examples_common:
+    path: ${IDF_PATH}/examples/common_components/protocol_examples_common
+  console_cmd_mqtt:
+    version: "*"
+    override_path: '../../../'

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/main/mqtt_ssl_auth_console.c

@@ -0,0 +1,51 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include <stdio.h>
+#include "nvs_flash.h"
+#include "esp_netif.h"
+#include "esp_event.h"
+#include <netdb.h>
+#include "console_mqtt.h"
+#include "protocol_examples_common.h"
+
+// Certs for mqtts://test.mosquitto.org:8884
+extern const uint8_t g_client_cert_pem_start[] asm("_binary_client_crt_start");
+extern const uint8_t g_client_cert_pem_end[] asm("_binary_client_crt_end");
+extern const uint8_t g_client_key_pem_start[] asm("_binary_client_key_start");
+extern const uint8_t g_client_key_pem_end[] asm("_binary_client_key_end");
+extern const uint8_t g_broker_cert_pem_start[] asm("_binary_mosquitto_org_pem_start");
+extern const uint8_t g_broker_cert_pem_end[] asm("_binary_mosquitto_org_pem_end");
+
+
+void app_main(void)
+{
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    esp_err_t ret = nvs_flash_init();   //Initialize NVS
+    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        ESP_ERROR_CHECK(nvs_flash_erase());
+        ret = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK(ret);
+
+    /* This helper function configures Wi-Fi or Ethernet, as selected in menuconfig.
+     * Read "Establishing Wi-Fi or Ethernet Connection" section in
+     * ${IDF_PATH}/examples/protocols/README.md for more information about this function.
+     */
+    ESP_ERROR_CHECK(example_connect());
+
+    // Initialize console REPL
+    ESP_ERROR_CHECK(console_cmd_init());
+    ESP_ERROR_CHECK(console_cmd_all_register());
+
+    set_mqtt_client_cert(g_client_cert_pem_start, g_client_cert_pem_end);
+    set_mqtt_client_key(g_client_key_pem_start, g_client_key_pem_end);
+    set_mqtt_broker_certs(g_broker_cert_pem_start, g_broker_cert_pem_end);
+
+    // start console REPL
+    ESP_ERROR_CHECK(console_cmd_start());
+
+}

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/pytest_mqtt_ssl_auth_console.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+
+# -*- coding: utf-8 -*-
+
+import pytest
+
+
+@pytest.mark.esp32
+def test_examples_ifconfig_command(dut):
+    dut.expect('esp>', timeout=30)
+    dut.write('help mqtt')
+    dut.expect(r'mqtt  \[-CsD\] \[-h <host>\] \[-u <username>\] \[-P <password>\] \[--cert\] \[--key\] \[--cafile\]', timeout=30)
+
+    dut.write('help mqtt_pub')
+    dut.expect(r'mqtt_pub  \[-t <topic>\] \[-m <message>\]', timeout=30)
+
+    dut.write('help mqtt_sub')
+    dut.expect(r'mqtt_sub  \[-U\] \[-t <topic>\]', timeout=30)

components/console_cmd_mqtt/examples/mqtt_ssl_auth_console/sdkconfig.defaults

@@ -0,0 +1,7 @@
+# This file was generated using idf.py save-defconfig. It can be edited manually.
+# Espressif IoT Development Framework (ESP-IDF) 5.5.0 Project Minimal Configuration
+#
+CONFIG_COMPILER_OPTIMIZATION_SIZE=y
+CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN=y
+CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE=y
+CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH="certs/mosquitto.org.pem"

components/console_cmd_mqtt/idf_component.yml

@@ -0,0 +1,11 @@
+version: 1.0.0
+url: https://github.com/espressif/esp-protocols/tree/master/components/console_cmd_mqtt
+description: The component provides a console where the 'mqtt' command can be executed.
+license: Apache-2.0
+dependencies:
+  idf:
+    version: '>=5.0'
+  espressif/console_simple_init:
+    version: '>=1.1.0'
+    override_path: '../console_simple_init'
+    public: true

components/esp_modem/.cz.yaml

@@ -3,6 +3,6 @@ commitizen:
   bump_message: 'bump(modem): $current_version -> $new_version'
   pre_bump_hooks: python ../../ci/changelog.py esp_modem
   tag_format: modem-v$version
-  version: 1.1.0
+  version: 1.2.1
   version_files:
   - idf_component.yml

components/esp_modem/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [1.2.1](https://github.com/espressif/esp-protocols/commits/modem-v1.2.1)
+
+### Bug Fixes
+
+- Use higher GPIO range to support new chips ([428fdbbd](https://github.com/espressif/esp-protocols/commit/428fdbbd), [#558](https://github.com/espressif/esp-protocols/issues/558))
+- Remove tests and support for IDFv4.4, added IDFv5.4 ([433a033f](https://github.com/espressif/esp-protocols/commit/433a033f))
+- Fix typo GENETIC -> GENERIC in mode types ([090b1ff8](https://github.com/espressif/esp-protocols/commit/090b1ff8), [#667](https://github.com/espressif/esp-protocols/issues/667))
+- Add support for URC handler into C-API ([295d99df](https://github.com/espressif/esp-protocols/commit/295d99df), [#180](https://github.com/espressif/esp-protocols/issues/180))
+
+## [1.2.0](https://github.com/espressif/esp-protocols/commits/modem-v1.2.0)
+
+### Features
+
+- Add support for guessing mode ([52598e5f](https://github.com/espressif/esp-protocols/commit/52598e5f))
+- Delete CMUX internal implementation even if terminal exit fails ([0e0cbd6b](https://github.com/espressif/esp-protocols/commit/0e0cbd6b))
+- Add support for handling URC ([1b6a3b3b](https://github.com/espressif/esp-protocols/commit/1b6a3b3b), [#180](https://github.com/espressif/esp-protocols/issues/180))
+- add ability to change ESP_MODEM_C_API_STR_MAX from Kconfig ([17909892](https://github.com/espressif/esp-protocols/commit/17909892))
+- Added target test config with CHAP authentication ([f8ae7def](https://github.com/espressif/esp-protocols/commit/f8ae7def))
+- example add esp32p4 usb support ([adafeae5](https://github.com/espressif/esp-protocols/commit/adafeae5))
+- Publish mbedtls component ([0140455f](https://github.com/espressif/esp-protocols/commit/0140455f))
+- host test support of the latest ESP-IDF release ([3f74b4e8](https://github.com/espressif/esp-protocols/commit/3f74b4e8))
+
+### Bug Fixes
+
+- Fix console example to use urc/detect features ([1a9eaf3e](https://github.com/espressif/esp-protocols/commit/1a9eaf3e))
+- Update target test builds to use external Catch2 ([554f022c](https://github.com/espressif/esp-protocols/commit/554f022c))
+- Fix arguments names when spawn esp_modem_xxx declarations ([b6792c52](https://github.com/espressif/esp-protocols/commit/b6792c52))
+- Remove catch dependency ([c3480768](https://github.com/espressif/esp-protocols/commit/c3480768))
+- Examples: use local configs for MQTT topic/data ([f5c13b92](https://github.com/espressif/esp-protocols/commit/f5c13b92))
+- Fixed clang-tidy warnings ([70fa3af7](https://github.com/espressif/esp-protocols/commit/70fa3af7))
+- Fix CI build per IDFv5.3 ([d0c17ef0](https://github.com/espressif/esp-protocols/commit/d0c17ef0))
+- Fixed UART task to check for buffered data periodically ([4bdd90cc](https://github.com/espressif/esp-protocols/commit/4bdd90cc), [#536](https://github.com/espressif/esp-protocols/issues/536))
+- Cleanup unused configs from PPPoS example ([08a62ccc](https://github.com/espressif/esp-protocols/commit/08a62ccc))
+- Update CMUX example with SIM7070_gnss cleaned-up ([56fe5327](https://github.com/espressif/esp-protocols/commit/56fe5327))
+- Update console example with SIM7070_gnss format comments ([5baaf542](https://github.com/espressif/esp-protocols/commit/5baaf542))
+- Fix remaining print format warnings ([3b80181d](https://github.com/espressif/esp-protocols/commit/3b80181d))
+
+### Updated
+
+- docs(modem): Fix esp_modem_at_raw() description (C-API) ([492a6a00](https://github.com/espressif/esp-protocols/commit/492a6a00))
+- ci(common): updated github actions(checkout, upload, download) v3 to 4, Ubuntu 20.04 to v22.04 ([a23a0027](https://github.com/espressif/esp-protocols/commit/a23a0027))
+
 ## [1.1.0](https://github.com/espressif/esp-protocols/commits/modem-v1.1.0)
 
 ### Features

components/esp_modem/examples/ap_to_pppos/README.md

@@ -15,7 +15,3 @@ By default, this example simply connects to the PPP server using a supported dev
 This example however, doesn't rely on sending specific AT commands, just the bare minimum to setup the cellular network.
 Thus, if the `EXAMPLE_USE_MINIMAL_DCE` option is enabled, we directly inherit from the `ModuleIf` and implement only the basic commands.
 Also, to demonstrate the dce_factory functionality, a new `NetDCE_Factory` is implemented for creating the network module and the DCE.
-
-### Supported IDF versions
-
-This example is only supported from `v4.2`, since is uses NAPT feature.

components/esp_modem/examples/linux_modem/README.md

@@ -17,7 +17,3 @@ over PPPoS, i.e. over the modem serial line.
 * Experiment with the network, after getting the IP from the modem device
     - directly in the code
     - in the system (need to set `tun` interface IP, dns servers, and routing the desired traffic over the tun interface)
-
-### Supported IDF versions
-
-This example (using the default CMake IDF build system) is only supported from `v4.4`, since is uses `idf.py`'s linux target.

components/esp_modem/examples/modem_console/README.md

@@ -25,9 +25,3 @@ USB example uses Quactel BG96 modem device. BG96 needs a positive pulse on its P
 This example supports USB modem hot-plugging and reconnection. There is one limitation coming from esp_console component:
 When esp_console REPL is being destroyed (after USB mode disconnection or after `exit` command), it will block on UART read.
 You must send a character to it (via idf.py monitor), so it unblocks and properly exits.
-
-### Supported IDF versions
-
-This example is only supported from `v4.2`, due to support of the console repl mode.
-
-USB example is supported from `v4.4`.

components/esp_modem/examples/modem_console/main/Kconfig.projbuild

@@ -108,28 +108,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
 
@@ -179,7 +179,7 @@ menu "Example Configuration"
     config EXAMPLE_MODEM_PWRKEY_PIN
         int "PWRKEY Pin Number"
         default 18
-        range 0 31
+        range 0 56
         help
             Pin number connected to modem's power key pin.
 endmenu

components/esp_modem/examples/modem_console/main/modem_console_main.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
@@ -89,7 +89,7 @@ void wakeup_modem(void)
     vTaskDelay(pdMS_TO_TICKS(2000));
 }
 
-#ifdef CONFIG_EXAMPLE_MODEM_DEVICE_SHINY
+#ifdef CONFIG_ESP_MODEM_URC_HANDLER
 command_result handle_urc(uint8_t *data, size_t len)
 {
     ESP_LOG_BUFFER_HEXDUMP("on_read", data, len, ESP_LOG_INFO);
@@ -238,7 +238,9 @@ extern "C" void app_main(void)
         if (c->get_count_of(&SetModeArgs::mode)) {
             auto mode = c->get_string_of(&SetModeArgs::mode);
             modem_mode dev_mode;
-            if (mode == "UNDEF") {
+            if (mode == "AUTO") {
+                dev_mode = esp_modem::modem_mode::AUTODETECT;
+            } else if (mode == "UNDEF") {
                 dev_mode = esp_modem::modem_mode::UNDEF;
             } else if (mode == "CMUX1") {
                 dev_mode = esp_modem::modem_mode::CMUX_MANUAL_MODE;
@@ -370,15 +372,15 @@ extern "C" void app_main(void)
         ESP_LOGI(TAG, "Resetting the module...");
         CHECK_ERR(dce->reset(), ESP_LOGI(TAG, "OK"));
     });
-#ifdef CONFIG_EXAMPLE_MODEM_DEVICE_SHINY
+#ifdef CONFIG_ESP_MODEM_URC_HANDLER
     const ConsoleCommand HandleURC("urc", "toggle urc handling", no_args, [&](ConsoleCommand * c) {
         static int cnt = 0;
         if (++cnt % 2) {
             ESP_LOGI(TAG, "Adding URC handler");
-            dce->set_on_read(handle_urc);
+            dce->set_urc(handle_urc);
         } else {
             ESP_LOGI(TAG, "URC removed");
-            dce->set_on_read(nullptr);
+            dce->set_urc(nullptr);
         }
         return 0;
     });

components/esp_modem/examples/modem_psm/main/Kconfig.projbuild

@@ -20,14 +20,14 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 4
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 5
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
@@ -70,14 +70,14 @@ menu "Example Configuration"
     config EXAMPLE_MODEM_PWRKEY_PIN
         int "PWRKEY Pin Number"
         default 18
-        range 0 31
+        range 0 56
         help
             Pin number connected to modem's power key pin.
 
     config EXAMPLE_MODEM_STATUS_PIN
         int "STATUS Pin Number"
         default 19
-        range 0 31
+        range 0 56
         help
             Pin number connected to modem's status pin.
 

components/esp_modem/examples/modem_tcp_client/README.md

@@ -22,7 +22,3 @@ To enable this mode, please set `EXAMPLE_CUSTOM_TCP_TRANSPORT=y`
 This configuration could be used with any network library, which is connecting to a localhost endpoint instead of remote one. This example creates a localhost listener which basically mimics the remote endpoint by forwarding the traffic between the library and the TCP/socket layer of the modem (which is already secure if the TLS is used in the network library)
 
 ![with localhost listener](at_client_localhost.png)
-
-### Supported IDF versions
-
-This example is supported from IDF `v5.0`.

components/esp_modem/examples/modem_tcp_client/main/Kconfig.projbuild

@@ -30,28 +30,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
 

components/esp_modem/examples/pppos_client/README.md

@@ -18,9 +18,3 @@ For USB enabled targets (ESP32-S2, ESP32-S3, or ESP32-P4), it is possible to con
 USB example uses Quactel BG96 modem device. BG96 needs a positive pulse on its PWK pin to boot-up.
 
 This example supports USB modem hot-plugging and reconnection.
-
-### Supported IDF versions
-
-This example is only supported from `v4.1`, as this is the default dependency of `esp-modem` component.
-
-USB example is supported from `v4.4`.

components/esp_modem/examples/pppos_client/main/Kconfig.projbuild

@@ -100,28 +100,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
 

components/esp_modem/examples/simple_cmux_client/README.md

@@ -11,11 +11,3 @@ The example uses the following configuration options to demonstrate basic esp-mo
 * `EXAMPLE_NEED_SIM_PIN`: To unlock the SIM card with a PIN code if needed
 * `EXAMPLE_PERFORM_OTA`: To start simple OTA at the end of the example to exercise basic CMUX/modem networking. Please note that the option `CONFIG_UART_ISR_IN_IRAM` is not enabled automatically, so that buffer overflows are expected and CMUX/PPP and networking should recover.
 * `EXAMPLE_USE_VFS_TERM`: To demonstrate using an abstract file descriptor to talk to the device (instead of the UART driver directly). This option could be used when implementing a custom VFS driver.
-
-## About the esp_modem
-
-Please check the component [README](../../README.md)
-
-### Supported IDF versions
-
-This example is only supported from `v4.3`, since is uses an experimental `esp_event_cxx` component.

components/esp_modem/examples/simple_cmux_client/main/Kconfig.projbuild

@@ -69,28 +69,28 @@ menu "Example Configuration"
         config EXAMPLE_MODEM_UART_TX_PIN
             int "TXD Pin Number"
             default 25
-            range 0 31
+            range 0 56
             help
                 Pin number of UART TX.
 
         config EXAMPLE_MODEM_UART_RX_PIN
             int "RXD Pin Number"
             default 26
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RX.
 
         config EXAMPLE_MODEM_UART_RTS_PIN
             int "RTS Pin Number"
             default 27
-            range 0 31
+            range 0 56
             help
                 Pin number of UART RTS.
 
         config EXAMPLE_MODEM_UART_CTS_PIN
             int "CTS Pin Number"
             default 23
-            range 0 31
+            range 0 56
             help
                 Pin number of UART CTS.
     endmenu

components/esp_modem/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.1.0"
+version: "1.2.1"
 description: Library for communicating with cellular modems in command and data modes
 url: https://github.com/espressif/esp-protocols/tree/master/components/esp_modem
 issues: https://github.com/espressif/esp-protocols/issues

components/esp_modem/include/cxx_include/esp_modem_dce.hpp

@@ -30,9 +30,11 @@ public:
     ~DCE_Mode() = default;
     bool set(DTE *dte, ModuleIf *module, Netif &netif, modem_mode m);
     modem_mode get();
+    modem_mode guess(DTE *dte, bool with_cmux = false);
 
 private:
     bool set_unsafe(DTE *dte, ModuleIf *module, Netif &netif, modem_mode m);
+    modem_mode guess_unsafe(DTE *dte, bool with_cmux);
     modem_mode mode;
 
 };
@@ -79,6 +81,11 @@ public:
         return dte->command(command, std::move(got_line), time_ms);
     }
 
+    modem_mode guess_mode(bool with_cmux = false)
+    {
+        return mode.guess(dte.get(), with_cmux);
+    }
+
     bool set_mode(modem_mode m)
     {
         return mode.set(dte.get(), device.get(), netif, m);

components/esp_modem/include/cxx_include/esp_modem_dte.hpp

@@ -65,6 +65,18 @@ public:
 
     int write(DTE_Command command);
 
+    /**
+     * @brief send data to the selected terminal, by default (without term_id argument)
+     * this API works the same as write: sends data to the secondary terminal, which is
+     * typically used as data terminal (for networking).
+     *
+     * @param data Data pointer to write
+     * @param len Data len to write
+     * @param term_id Terminal id: Primary if id==0, Secondary if id==1
+     * @return number of bytes written
+     */
+    int send(uint8_t *data, size_t len, int term_id = 1);
+
     /**
      * @brief Reading from the underlying terminal
      * @param d Returning the data pointer of the received payload

components/esp_modem/include/cxx_include/esp_modem_types.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -37,6 +37,17 @@ enum class modem_mode {
     CMUX_MANUAL_DATA,    /*!< Sets the primary terminal to DATA mode in manual CMUX */
     CMUX_MANUAL_COMMAND, /*!< Sets the primary terminal to COMMAND mode in manual CMUX */
     CMUX_MANUAL_SWAP,    /*!< Swaps virtual terminals in manual CMUX mode (primary <-> secondary) */
+    RESUME_DATA_MODE,    /*!< This is used when the device is already in DATA mode and we need the modem lib to
+                          * enter the mode without switching. On success, we would end up in DATA-mode, UNDEF otherwise */
+    RESUME_COMMAND_MODE, /*!< This is used when the device is already in COMMAND mode and we want to resume it
+                          * On success, we would end up in DATA-mode, UNDEF otherwise */
+    RESUME_CMUX_MANUAL_MODE, /*!< This is used when the device is already in CMUX mode and we need the modem lib to
+                              * enter it without switching. On success, we would end up in CMUX_MANUAL-mode, UNDEF otherwise */
+    RESUME_CMUX_MANUAL_DATA, /*!< This is used when the device is already in CMUX-DATA mode and we need the modem lib to
+                              * enter it without switching. On success, we would end up in CMUX_MANUAL-DATA mode, UNDEF otherwise */
+    AUTODETECT,              /*!< Auto-detection command: It tries to send a few packets in order to recognize which mode the
+                              * the device currently is and update the modem library mode. On success the modem is updated,
+                              * otherwise it's set to UNDEF */
 };
 
 /**

components/esp_modem/include/esp_modem_c_api_types.h

@@ -13,6 +13,10 @@
 extern "C" {
 #endif
 
+/*  Compatibility macro to be removed in v2.0
+ */
+#define ESP_MODEM_DCE_GENETIC ESP_MODEM_DCE_GENERIC
+
 typedef struct esp_modem_dce_wrap esp_modem_dce_t;
 
 typedef struct esp_modem_PdpContext_t {
@@ -47,7 +51,7 @@ typedef enum esp_modem_dce_mode {
  * @brief DCE devices: Enum list of supported devices
  */
 typedef enum esp_modem_dce_device {
-    ESP_MODEM_DCE_GENETIC,  /**< The most generic device */
+    ESP_MODEM_DCE_GENERIC,  /**< The most generic device */
     ESP_MODEM_DCE_SIM7600,
     ESP_MODEM_DCE_SIM7070,
     ESP_MODEM_DCE_SIM7000,
@@ -141,6 +145,21 @@ esp_err_t esp_modem_command(esp_modem_dce_t *dce, const char *command, esp_err_t
  */
 esp_err_t esp_modem_set_apn(esp_modem_dce_t *dce, const char *apn);
 
+#ifdef CONFIG_ESP_MODEM_URC_HANDLER
+/**
+ * @brief Sets a handler for unsolicited result codes (URCs) from the modem
+ *
+ * This function registers a callback that is triggered whenever an unsolicited
+ * result code (URC) is received from the modem. URCs are typically sent by the
+ * modem without a prior command to notify the host about certain events or status changes.
+ *
+ * @param dce Modem DCE handle
+ * @param got_line_cb Callback function which is called whenever a URC line is received
+ * @return ESP_OK on success, ESP_FAIL on failure
+ */
+esp_err_t esp_modem_set_urc(esp_modem_dce_t *dce, esp_err_t(*got_line_cb)(uint8_t *data, size_t len));
+#endif
+
 /**
  * @}
  */

components/esp_modem/include/esp_private/c_api_wrapper.hpp

@@ -44,7 +44,7 @@ inline dce_factory::ModemType convert_modem_enum(esp_modem_dce_device_t module)
     case ESP_MODEM_DCE_SIM800:
         return esp_modem::dce_factory::ModemType::SIM800;
     default:
-    case ESP_MODEM_DCE_GENETIC:
+    case ESP_MODEM_DCE_GENERIC:
         return esp_modem::dce_factory::ModemType::GenericModule;
     }
 }

components/esp_modem/src/esp_modem_c_api.cpp

@@ -60,7 +60,7 @@ extern "C" esp_modem_dce_t *esp_modem_new_dev(esp_modem_dce_device_t module, con
 
 extern "C" esp_modem_dce_t *esp_modem_new(const esp_modem_dte_config_t *dte_config, const esp_modem_dce_config_t *dce_config, esp_netif_t *netif)
 {
-    return esp_modem_new_dev(ESP_MODEM_DCE_GENETIC, dte_config, dce_config, netif);
+    return esp_modem_new_dev(ESP_MODEM_DCE_GENERIC, dte_config, dce_config, netif);
 }
 
 extern "C" void esp_modem_destroy(esp_modem_dce_t *dce_wrap)
@@ -451,3 +451,27 @@ extern "C" esp_err_t esp_modem_set_apn(esp_modem_dce_t *dce_wrap, const char *ap
     dce_wrap->dce->get_module()->configure_pdp_context(std::move(new_pdp));
     return ESP_OK;
 }
+
+#ifdef CONFIG_ESP_MODEM_URC_HANDLER
+extern "C" esp_err_t esp_modem_set_urc(esp_modem_dce_t *dce_wrap, esp_err_t(*got_line_fn)(uint8_t *data, size_t len))
+{
+    if (dce_wrap == nullptr || dce_wrap->dce == nullptr) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (got_line_fn == nullptr) {
+        dce_wrap->dce->set_urc(nullptr);
+        return ESP_OK;
+    }
+    dce_wrap->dce->set_urc([got_line_fn](uint8_t *data, size_t len) {
+        switch (got_line_fn(data, len)) {
+        case ESP_OK:
+            return command_result::OK;
+        case ESP_FAIL:
+            return command_result::FAIL;
+        default:
+            return command_result::TIMEOUT;
+        }
+    });
+    return ESP_OK;
+}
+#endif

components/esp_modem/src/esp_modem_dce.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -103,6 +103,51 @@ bool DCE_Mode::set_unsafe(DTE *dte, ModuleIf *device, Netif &netif, modem_mode m
         return true;
     case modem_mode::DUAL_MODE: // Only DTE can be in Dual mode
         break;
+    case modem_mode::AUTODETECT: {
+        auto guessed = guess_unsafe(dte, true);
+        if (guessed == modem_mode::UNDEF) {
+            return false;
+        }
+        // prepare the undefined mode before to allow all possible transitions
+        if (!dte->set_mode(modem_mode::UNDEF)) {
+            return false;
+        }
+        mode = modem_mode::UNDEF;
+        ESP_LOGD("DCE mode", "Detected mode: %d", static_cast<int>(guessed));
+        if (guessed == modem_mode::DATA_MODE) {
+            return set_unsafe(dte, device, netif, esp_modem::modem_mode::RESUME_DATA_MODE);
+        } else if (guessed == esp_modem::modem_mode::COMMAND_MODE) {
+            return set_unsafe(dte, device, netif, esp_modem::modem_mode::RESUME_COMMAND_MODE);
+        } else if (guessed == esp_modem::modem_mode::CMUX_MODE) {
+            if (!set_unsafe(dte, device, netif, esp_modem::modem_mode::RESUME_CMUX_MANUAL_MODE)) {
+                return false;
+            }
+            // now we guess the mode for each terminal
+            guessed = guess_unsafe(dte, false);
+            ESP_LOGD("DCE mode", "Detected mode on primary term: %d", static_cast<int>(guessed));
+            // now we need to access the second terminal, so we could simply send a SWAP command
+            // (switching to data mode does the swapping internally, so we only swap if we're in CMD mode)
+            if (guessed == modem_mode::DATA_MODE) {
+                // switch to DATA on the primary terminal and swap terminals
+                if (!set_unsafe(dte, device, netif, esp_modem::modem_mode::RESUME_CMUX_MANUAL_DATA)) {
+                    return false;
+                }
+            } else {
+                // swap terminals
+                if (!set_unsafe(dte, device, netif, esp_modem::modem_mode::CMUX_MANUAL_SWAP)) {
+                    return false;
+                }
+            }
+            guessed = guess_unsafe(dte, false);
+            ESP_LOGD("DCE mode", "Detected mode on secondary term: %d", static_cast<int>(guessed));
+            if (guessed == modem_mode::DATA_MODE) {
+                if (!set_unsafe(dte, device, netif, esp_modem::modem_mode::RESUME_CMUX_MANUAL_DATA)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
     case modem_mode::COMMAND_MODE:
         if (mode == modem_mode::COMMAND_MODE || mode >= modem_mode::CMUX_MANUAL_MODE) {
             return false;
@@ -122,6 +167,32 @@ bool DCE_Mode::set_unsafe(DTE *dte, ModuleIf *device, Netif &netif, modem_mode m
         }
         mode = m;
         return true;
+    case modem_mode::RESUME_DATA_MODE:
+        if (!dte->set_mode(modem_mode::DATA_MODE)) {
+            return false;
+        }
+        netif.start();
+        mode = modem_mode::DATA_MODE;
+        return true;
+    case modem_mode::RESUME_COMMAND_MODE:
+        if (!dte->set_mode(modem_mode::COMMAND_MODE)) {
+            return false;
+        }
+        mode = modem_mode::COMMAND_MODE;
+        return true;
+    case modem_mode::RESUME_CMUX_MANUAL_MODE:
+        if (!dte->set_mode(modem_mode::CMUX_MANUAL_MODE)) {
+            return false;
+        }
+        mode = modem_mode::CMUX_MANUAL_MODE;
+        return true;
+    case modem_mode::RESUME_CMUX_MANUAL_DATA:
+        if (!dte->set_mode(modem_mode::CMUX_MANUAL_SWAP)) {
+            return false;
+        }
+        netif.start();
+        mode = modem_mode::CMUX_MANUAL_MODE;
+        return true;
     case modem_mode::DATA_MODE:
         if (mode == modem_mode::DATA_MODE || mode == modem_mode::CMUX_MODE || mode >= modem_mode::CMUX_MANUAL_MODE) {
             return false;
@@ -191,4 +262,114 @@ modem_mode DCE_Mode::get()
     return mode;
 }
 
+modem_mode DCE_Mode::guess(DTE *dte, bool with_cmux)
+{
+    Scoped<DTE> lock(*dte);
+    return guess_unsafe(dte, with_cmux);
+}
+
+/**
+ * This namespace contains probe packets and expected replies on 3 different protocols,
+ * the modem device could use (as well as timeouts and mode ids for synchronisation)
+ */
+namespace probe {
+
+namespace ppp {
+// Test that we're in the PPP mode by sending an LCP protocol echo request and expecting LCP echo reply
+constexpr std::array<uint8_t, 16> lcp_echo_request = {0x7e, 0xff, 0x03, 0xc0, 0x21, 0x09, 0x01, 0x00, 0x08, 0x99, 0xd1, 0x35, 0xc1, 0x8e, 0x2c, 0x7e };
+constexpr std::array<uint8_t, 5> lcp_echo_reply_head = {0x7e, 0xff, 0x7d, 0x23, 0xc0};
+const size_t mode = 1 << 0;
+const int timeout = 200;
+}
+
+namespace cmd {
+// For command mode, we just send a simple AT command
+const char at[] = "\r\nAT\r\n";
+const size_t max_at_reply = 16; // account for some whitespaces and/or CMUX encapsulation
+const char reply[] = { 'O', 'K' };
+const int mode = 1 << 1;
+const int timeout = 500;
+}
+
+namespace cmux {
+// For CMUX mode, we send an SABM on control terminal (0)
+const uint8_t sabm0_reqest[] = {0xf9, 0x03, 0x3f, 0x01, 0x1c, 0xf9};
+const uint8_t sabm0_reply[] = {0xf9, 0x03, 0x73, 0x01};
+const int mode = 1 << 0;
+const int timeout = 200;
+}
+};
+
+modem_mode DCE_Mode::guess_unsafe(DTE *dte, bool with_cmux)
+{
+    // placeholder for reply and its size, since it could come in pieces, and we have to cache
+    // this is captured by the lambda by reference.
+    // must make sure the lambda is cleared before exiting this function (done by dte->on_read(nullptr))
+    uint8_t reply[std::max(probe::cmd::max_at_reply, std::max(sizeof(probe::ppp::lcp_echo_request), sizeof(probe::cmux::sabm0_reply)))];
+    size_t reply_pos = 0;
+    auto signal = std::make_shared<SignalGroup>();
+    std::weak_ptr<SignalGroup> weak_signal = signal;
+    dte->on_read([weak_signal, with_cmux, &reply, &reply_pos](uint8_t *data, size_t len) {
+        // storing the response in the `reply` array and de-fragmenting
+        if (reply_pos >= sizeof(reply)) {
+            return command_result::TIMEOUT;
+        }
+        auto reply_size = std::min((size_t)sizeof(reply) - reply_pos, len);
+        ::memcpy(reply + reply_pos, data, reply_size);
+        reply_pos += reply_size;
+        ESP_LOG_BUFFER_HEXDUMP("esp-modem: guess mode data:", reply, reply_pos, ESP_LOG_DEBUG);
+
+        // Check whether the response resembles the "golden" reply (for these 3 protocols)
+        if (reply_pos >= sizeof(probe::ppp::lcp_echo_reply_head)) {
+            // check for initial 2 bytes
+            auto *ptr = static_cast<uint8_t *>(memmem(reply, reply_pos, probe::ppp::lcp_echo_reply_head.data(), 2));
+            // and check the other two bytes for protocol ID: LCP
+            if (ptr && ptr[3] == probe::ppp::lcp_echo_reply_head[3] && ptr[4] == probe::ppp::lcp_echo_reply_head[4]) {
+                if (auto signal = weak_signal.lock()) {
+                    signal->set(probe::ppp::mode);
+                }
+            }
+        }
+        if (reply_pos >= 4 && memmem(reply, reply_pos, probe::cmd::reply, sizeof(probe::cmd::reply))) {
+            if (reply[0] != 0xf9) {   // double check that the reply is not wrapped in CMUX headers
+                if (auto signal = weak_signal.lock()) {
+                    signal->set(probe::cmd::mode);
+                }
+            }
+        }
+        if (with_cmux && reply_pos >= sizeof(probe::cmux::sabm0_reply)) {
+            // checking the initial 3 bytes
+            auto *ptr = static_cast<uint8_t *>(memmem(reply, reply_pos, probe::cmux::sabm0_reply, 3));
+            // and checking that DLCI is 0 (control frame)
+            if (ptr && (ptr[3] >> 2) == 0) {
+                if (auto signal = weak_signal.lock()) {
+                    signal->set(probe::cmux::mode);
+                }
+            }
+        }
+        return command_result::TIMEOUT;
+    });
+    auto guessed = modem_mode::UNDEF;
+    // Check the PPP mode fist by sending LCP echo request
+    dte->send((uint8_t *)probe::ppp::lcp_echo_request.data(), sizeof(probe::ppp::lcp_echo_request), 0);
+    if (signal->wait(probe::ppp::mode, probe::ppp::timeout)) {
+        guessed = modem_mode::DATA_MODE;
+    } else {    // LCP echo timeout
+        // now check for AT mode
+        reply_pos = 0;
+        dte->send((uint8_t *)probe::cmd::at, sizeof(probe::cmd::at), 0);
+        if (signal->wait(probe::cmd::mode, probe::cmd::timeout)) {
+            guessed = modem_mode::COMMAND_MODE;
+        } else if (with_cmux) {     // no AT reply, check for CMUX mode (if requested)
+            reply_pos = 0;
+            dte->send((uint8_t *) probe::cmux::sabm0_reqest, sizeof(probe::cmux::sabm0_reqest), 0);
+            if (signal->wait(probe::cmux::mode, probe::cmux::timeout)) {
+                guessed = modem_mode::CMUX_MODE;
+            }
+        }
+    }
+    dte->on_read(nullptr);
+    return guessed;
+}
+
 } // esp_modem

components/esp_modem/src/esp_modem_dte.cpp

@@ -223,13 +223,13 @@ bool DTE::set_mode(modem_mode m)
         }
     }
     // transitions (COMMAND|DUAL|CMUX|UNDEF) -> DATA
-    if (m == modem_mode::DATA_MODE) {
+    if (m == modem_mode::DATA_MODE || m == modem_mode::RESUME_DATA_MODE) {
         if (mode == modem_mode::CMUX_MODE || mode == modem_mode::CMUX_MANUAL_MODE || mode == modem_mode::DUAL_MODE) {
             // mode stays the same, but need to swap terminals (as command has been switched)
             secondary_term.swap(primary_term);
             set_command_callbacks();
         } else {
-            mode = m;
+            mode = modem_mode::DATA_MODE;
         }
         return true;
     }
@@ -316,6 +316,12 @@ int DTE::write(uint8_t *data, size_t len)
     return secondary_term->write(data, len);
 }
 
+int DTE::send(uint8_t *data, size_t len, int term_id)
+{
+    Terminal *term = term_id == 0 ? primary_term.get() : secondary_term.get();
+    return term->write(data, len);
+}
+
 int DTE::write(DTE_Command command)
 {
     return primary_term->write(command.data, command.len);

components/esp_modem/src/esp_modem_netif.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -87,8 +87,10 @@ void Netif::start()
         receive(data, len);
         return true;
     });
-    signal.set(PPP_STARTED);
-    esp_netif_action_start(driver.base.netif, nullptr, 0, nullptr);
+    if (!signal.is_any(PPP_STARTED)) {
+        signal.set(PPP_STARTED);
+        esp_netif_action_start(driver.base.netif, nullptr, 0, nullptr);
+    }
 }
 
 void Netif::stop()

components/esp_modem/src/esp_modem_uart.cpp

@@ -72,6 +72,7 @@ private:
     {
         auto t = static_cast<UartTerminal *>(task_param);
         t->task();
+        t->task_handle.task_handle = nullptr;
         vTaskDelete(nullptr);
     }
 

components/esp_modem/test/target/main/Kconfig.projbuild

@@ -16,14 +16,14 @@ menu "Test App Configuration"
     config TEST_APP_UART_TX_PIN
         int "TXD Pin Number"
         default 6
-        range 0 31
+        range 0 56
         help
             Pin number of UART TX.
 
     config TEST_APP_UART_RX_PIN
         int "RXD Pin Number"
         default 7
-        range 0 31
+        range 0 56
         help
             Pin number of UART RX.
 

components/esp_websocket_client/examples/target/main/websocket_example.c

@@ -222,6 +222,7 @@ static void websocket_app_start(void)
     char *long_data = malloc(size);
     memset(long_data, 'a', size);
     esp_websocket_client_send_text(client, long_data, size, portMAX_DELAY);
+    free(long_data);
 
     xSemaphoreTake(shutdown_sema, portMAX_DELAY);
     esp_websocket_client_close(client, portMAX_DELAY);

components/mdns/.cz.yaml

@@ -3,6 +3,6 @@ commitizen:
   bump_message: 'bump(mdns): $current_version -> $new_version'
   pre_bump_hooks: python ../../ci/changelog.py mdns
   tag_format: mdns-v$version
-  version: 1.4.0
+  version: 1.4.2
   version_files:
   - idf_component.yml

components/mdns/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.4.2](https://github.com/espressif/esp-protocols/commits/mdns-v1.4.2)
+
+### Features
+
+- support update subtype ([062b8dca](https://github.com/espressif/esp-protocols/commit/062b8dca))
+
+### Updated
+
+- chore(mdns): Add more info to idf_component.yml ([4a1cb65c](https://github.com/espressif/esp-protocols/commit/4a1cb65c))
+
+## [1.4.1](https://github.com/espressif/esp-protocols/commits/mdns-v1.4.1)
+
+### Features
+
+- Send PTR query for mdns browse when interface is ready ([010a404a](https://github.com/espressif/esp-protocols/commit/010a404a))
+
+### Bug Fixes
+
+- Prevent deadlock when deleting a browse request ([3f48f9ea](https://github.com/espressif/esp-protocols/commit/3f48f9ea))
+- Fix use after free reported by coverity ([25b3d5fd](https://github.com/espressif/esp-protocols/commit/25b3d5fd))
+- Fixed dead-code reported by coverity ([11846c7d](https://github.com/espressif/esp-protocols/commit/11846c7d))
+
 ## [1.4.0](https://github.com/espressif/esp-protocols/commits/mdns-v1.4.0)
 
 ### Major changes

components/mdns/idf_component.yml

@@ -1,6 +1,9 @@
-version: "1.4.0"
-description: mDNS
-url: https://github.com/espressif/esp-protocols/tree/master/components/mdns
+version: "1.4.2"
+description: "Multicast UDP service used to provide local network service and host discovery."
+url: "https://github.com/espressif/esp-protocols/tree/master/components/mdns"
+issues: "https://github.com/espressif/esp-protocols/issues"
+documentation: "https://docs.espressif.com/projects/esp-protocols/mdns/docs/latest/en/index.html"
+repository: "https://github.com/espressif/esp-protocols.git"
 dependencies:
   idf:
     version: ">=5.0"

components/mdns/include/mdns.h

@@ -60,6 +60,14 @@ typedef struct {
     const char *value;                      /*!< item value string */
 } mdns_txt_item_t;
 
+/**
+ * @brief   mDNS basic subtype item structure
+ *          Used in mdns_service_subtype_xxx() APIs
+ */
+typedef struct {
+    const char *subtype;                        /*!< subtype name */
+} mdns_subtype_item_t;
+
 /**
  * @brief   mDNS query linked list IP item
  */
@@ -544,7 +552,7 @@ esp_err_t mdns_service_txt_item_remove_for_host(const char *instance, const char
         const char *key);
 
 /**
- * @brief  Add subtype for service.
+ * @brief  Add a subtype for service.
  *
  * @param  instance_name    instance name. If NULL, will find the first service with the same service type and protocol.
  * @param  service_type     service type (_http, _ftp, etc)
@@ -561,6 +569,60 @@ esp_err_t mdns_service_txt_item_remove_for_host(const char *instance, const char
 esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const char *service_type, const char *proto,
         const char *hostname, const char *subtype);
 
+/**
+ * @brief  Remove a subtype for service.
+ *
+ * @param  instance_name    instance name. If NULL, will find the first service with the same service type and protocol.
+ * @param  service_type     service type (_http, _ftp, etc)
+ * @param  proto            service protocol (_tcp, _udp)
+ * @param  hostname         service hostname. If NULL, local hostname will be used.
+ * @param  subtype          The subtype to remove.
+ *
+ * @return
+ *     - ESP_OK success
+ *     - ESP_ERR_INVALID_ARG Parameter error
+ *     - ESP_ERR_NOT_FOUND Service not found
+ */
+esp_err_t mdns_service_subtype_remove_for_host(const char *instance_name, const char *service_type, const char *proto,
+        const char *hostname, const char *subtype);
+
+/**
+ * @brief  Add multiple subtypes for service at once.
+ *
+ * @param  instance_name    instance name. If NULL, will find the first service with the same service type and protocol.
+ * @param  service_type     service type (_http, _ftp, etc)
+ * @param  proto            service protocol (_tcp, _udp)
+ * @param  hostname         service hostname. If NULL, local hostname will be used.
+ * @param  subtype          the pointer of subtype array to add.
+ * @param  num_items        number of items in subtype array
+ *
+ * @return
+ *     - ESP_OK success
+ *     - ESP_ERR_INVALID_ARG Parameter error
+ *     - ESP_ERR_NOT_FOUND Service not found
+ *     - ESP_ERR_NO_MEM memory error
+ */
+esp_err_t mdns_service_subtype_add_multiple_items_for_host(const char *instance_name, const char *service_type, const char *proto,
+        const char *hostname, mdns_subtype_item_t subtype[], uint8_t num_items);
+
+/**
+ * @brief  Update subtype for service.
+ *
+ * @param  instance_name    instance name. If NULL, will find the first service with the same service type and protocol.
+ * @param  service_type     service type (_http, _ftp, etc)
+ * @param  proto            service protocol (_tcp, _udp)
+ * @param  hostname         service hostname. If NULL, local hostname will be used.
+ * @param  subtype          the pointer of subtype array to add.
+ * @param  num_items        number of items in subtype array
+ *
+ * @return
+ *     - ESP_OK success
+ *     - ESP_ERR_INVALID_ARG Parameter error
+ *     - ESP_ERR_NOT_FOUND Service not found
+ *     - ESP_ERR_NO_MEM memory error
+ */
+esp_err_t mdns_service_subtype_update_multiple_items_for_host(const char *instance_name, const char *service_type, const char *proto,
+        const char *hostname, mdns_subtype_item_t subtype[], uint8_t num_items);
 /**
  * @brief  Remove and free all services from mDNS server
  *

components/mdns/mdns.c

@@ -2794,6 +2794,16 @@ static void _mdns_remove_scheduled_service_packets(mdns_service_t *service)
     }
 }
 
+static void _mdns_free_service_subtype(mdns_service_t *service)
+{
+    while (service->subtype) {
+        mdns_subtype_t *next = service->subtype->next;
+        free((char *)service->subtype->subtype);
+        free(service->subtype);
+        service->subtype = next;
+    }
+}
+
 /**
  * @brief  free service memory
  *
@@ -2815,12 +2825,7 @@ static void _mdns_free_service(mdns_service_t *service)
         free((char *)s->value);
         free(s);
     }
-    while (service->subtype) {
-        mdns_subtype_t *next = service->subtype->next;
-        free((char *)service->subtype->subtype);
-        free(service->subtype);
-        service->subtype = next;
-    }
+    _mdns_free_service_subtype(service);
     free(service);
 }
 
@@ -6299,7 +6304,36 @@ esp_err_t mdns_service_txt_item_remove(const char *service, const char *proto, c
     return mdns_service_txt_item_remove_for_host(NULL, service, proto, NULL, key);
 }
 
-esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const char *service, const char *proto,
+static esp_err_t _mdns_service_subtype_remove_for_host(mdns_srv_item_t *service, const char *subtype)
+{
+    esp_err_t ret = ESP_ERR_NOT_FOUND;
+    mdns_subtype_t *srv_subtype = service->service->subtype;
+    mdns_subtype_t *pre = service->service->subtype;
+    while (srv_subtype) {
+        if (strcmp(srv_subtype->subtype, subtype) == 0) {
+            // Target subtype is found.
+            if (srv_subtype == service->service->subtype) {
+                // The first node needs to be removed
+                service->service->subtype = service->service->subtype->next;
+            } else {
+                pre->next = srv_subtype->next;
+            }
+            free((char *)srv_subtype->subtype);
+            free(srv_subtype);
+            ret = ESP_OK;
+            break;
+        }
+        pre = srv_subtype;
+        srv_subtype = srv_subtype->next;
+    }
+    if (ret == ESP_ERR_NOT_FOUND) {
+        ESP_LOGE(TAG, "Subtype : %s doesn't exist", subtype);
+    }
+
+    return ret;
+}
+
+esp_err_t mdns_service_subtype_remove_for_host(const char *instance_name, const char *service, const char *proto,
         const char *hostname, const char *subtype)
 {
     MDNS_SERVICE_LOCK();
@@ -6310,30 +6344,125 @@ esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const cha
     mdns_srv_item_t *s = _mdns_get_service_item_instance(instance_name, service, proto, hostname);
     ESP_GOTO_ON_FALSE(s, ESP_ERR_NOT_FOUND, err, TAG, "Service doesn't exist");
 
-    mdns_subtype_t *srv_subtype = s->service->subtype;
+    ret = _mdns_service_subtype_remove_for_host(s, subtype);
+    ESP_GOTO_ON_ERROR(ret, err, TAG, "Failed to remove the subtype: %s", subtype);
+
+    // TODO: Need to transmit a sendbye message for the removed subtype.
+    // TODO: Need to remove this subtype answer from the scheduled answer list.
+err:
+    MDNS_SERVICE_UNLOCK();
+    return ret;
+}
+
+static esp_err_t _mdns_service_subtype_add_for_host(mdns_srv_item_t *service, const char *subtype)
+{
+    esp_err_t ret = ESP_OK;
+    mdns_subtype_t *srv_subtype = service->service->subtype;
     while (srv_subtype) {
-        ESP_GOTO_ON_FALSE(strcmp(srv_subtype->subtype, subtype) != 0, ESP_ERR_INVALID_ARG, err, TAG, "The same subtype has already been added");
+        ESP_GOTO_ON_FALSE(strcmp(srv_subtype->subtype, subtype) != 0, ESP_ERR_INVALID_ARG, err, TAG, "Subtype: %s has already been added", subtype);
         srv_subtype = srv_subtype->next;
     }
 
-    mdns_service_t *srv = s->service;
     mdns_subtype_t *subtype_item = (mdns_subtype_t *)malloc(sizeof(mdns_subtype_t));
     ESP_GOTO_ON_FALSE(subtype_item, ESP_ERR_NO_MEM, out_of_mem, TAG, "Out of memory");
     subtype_item->subtype = strdup(subtype);
     ESP_GOTO_ON_FALSE(subtype_item->subtype, ESP_ERR_NO_MEM, out_of_mem, TAG, "Out of memory");
-    subtype_item->next = srv->subtype;
-    srv->subtype = subtype_item;
+    subtype_item->next = service->service->subtype;
+    service->service->subtype = subtype_item;
 
 err:
-    MDNS_SERVICE_UNLOCK();
     return ret;
 out_of_mem:
-    MDNS_SERVICE_UNLOCK();
     HOOK_MALLOC_FAILED;
     free(subtype_item);
     return ret;
 }
 
+esp_err_t mdns_service_subtype_add_multiple_items_for_host(const char *instance_name, const char *service, const char *proto,
+        const char *hostname, mdns_subtype_item_t subtype[], uint8_t num_items)
+{
+    MDNS_SERVICE_LOCK();
+    esp_err_t ret = ESP_OK;
+    int cur_index = 0;
+    ESP_GOTO_ON_FALSE(_mdns_server && _mdns_server->services && !_str_null_or_empty(service) && !_str_null_or_empty(proto) &&
+                      (num_items > 0), ESP_ERR_INVALID_ARG, err, TAG, "Invalid state or arguments");
+
+    mdns_srv_item_t *s = _mdns_get_service_item_instance(instance_name, service, proto, hostname);
+    ESP_GOTO_ON_FALSE(s, ESP_ERR_NOT_FOUND, err, TAG, "Service doesn't exist");
+
+    for (; cur_index < num_items; cur_index++) {
+        ret = _mdns_service_subtype_add_for_host(s, subtype[cur_index].subtype);
+        if (ret == ESP_OK) {
+            continue;
+        } else if (ret == ESP_ERR_NO_MEM) {
+            ESP_LOGE(TAG, "Out of memory");
+            goto err;
+        } else {
+            ESP_LOGE(TAG, "Failed to add subtype: %s", subtype[cur_index].subtype);
+            goto exit;
+        }
+    }
+
+    _mdns_announce_all_pcbs(&s, 1, false);
+err:
+    if (ret == ESP_ERR_NO_MEM) {
+        for (int idx = 0; idx < cur_index; idx++) {
+            _mdns_service_subtype_remove_for_host(s, subtype[idx].subtype);
+        }
+    }
+exit:
+    MDNS_SERVICE_UNLOCK();
+    return ret;
+}
+
+esp_err_t mdns_service_subtype_add_for_host(const char *instance_name, const char *service_type, const char *proto,
+        const char *hostname, const char *subtype)
+{
+    mdns_subtype_item_t _subtype[1];
+    _subtype[0].subtype = subtype;
+    return mdns_service_subtype_add_multiple_items_for_host(instance_name, service_type, proto, hostname, _subtype, 1);
+}
+
+esp_err_t mdns_service_subtype_update_multiple_items_for_host(const char *instance_name, const char *service_type, const char *proto,
+        const char *hostname, mdns_subtype_item_t subtype[], uint8_t num_items)
+{
+    MDNS_SERVICE_LOCK();
+    esp_err_t ret = ESP_OK;
+    int cur_index = 0;
+    ESP_GOTO_ON_FALSE(_mdns_server && _mdns_server->services && !_str_null_or_empty(service_type) && !_str_null_or_empty(proto) &&
+                      (num_items > 0), ESP_ERR_INVALID_ARG, err, TAG, "Invalid state or arguments");
+
+    mdns_srv_item_t *s = _mdns_get_service_item_instance(instance_name, service_type, proto, hostname);
+    ESP_GOTO_ON_FALSE(s, ESP_ERR_NOT_FOUND, err, TAG, "Service doesn't exist");
+
+    // TODO: find subtype needs to say sendbye
+    _mdns_free_service_subtype(s->service);
+
+    for (; cur_index < num_items; cur_index++) {
+        ret = _mdns_service_subtype_add_for_host(s, subtype[cur_index].subtype);
+        if (ret == ESP_OK) {
+            continue;
+        } else if (ret == ESP_ERR_NO_MEM) {
+            ESP_LOGE(TAG, "Out of memory");
+            goto err;
+        } else {
+            ESP_LOGE(TAG, "Failed to add subtype: %s", subtype[cur_index].subtype);
+            goto exit;
+        }
+    }
+
+    _mdns_announce_all_pcbs(&s, 1, false);
+err:
+    if (ret == ESP_ERR_NO_MEM) {
+        for (int idx = 0; idx < cur_index; idx++) {
+            _mdns_service_subtype_remove_for_host(s, subtype[idx].subtype);
+        }
+    }
+exit:
+    MDNS_SERVICE_UNLOCK();
+    return ret;
+}
+
 esp_err_t mdns_service_instance_name_set_for_host(const char *instance_old, const char *service, const char *proto, const char *host,
         const char *instance)
 {

components/sock_utils/.cz.yaml

@@ -0,0 +1,8 @@
+---
+commitizen:
+  bump_message: 'bump(sockutls): $current_version -> $new_version'
+  pre_bump_hooks: python ../../ci/changelog.py sock_utils
+  tag_format: sock_utils-v$version
+  version: 0.1.0
+  version_files:
+  - idf_component.yml

components/sock_utils/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.1.0](https://github.com/espressif/esp-protocols/commits/sock_utils-v0.1.0)
+
+### Features
+
+- Add initial support for socket helpers ([31f57ad0](https://github.com/espressif/esp-protocols/commit/31f57ad0))

components/sock_utils/CMakeLists.txt

@@ -0,0 +1,6 @@
+idf_component_register(SRCS "src/getnameinfo.c"
+                            "src/ifaddrs.c"
+                            "src/gai_strerror.c"
+                            "src/socketpair.c"
+                       INCLUDE_DIRS "include"
+                       PRIV_REQUIRES lwip esp_netif)

components/sock_utils/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

components/sock_utils/README.md

@@ -0,0 +1,17 @@
+# Socket Utilities
+
+This component provides simplified implementations of common socket-related utilities using `lwIP` and `esp_netif`. It is especially useful for porting Linux-based libraries to ESP32 where performance and memory constraints are secondary considerations.
+
+
+## Supported Functions
+
+
+| API              | Description                                                 | Limitations                                                       |
+|------------------|-------------------------------------------------------------|-------------------------------------------------------------------|
+| `ifaddrs()`      | Retrieves interface addresses using `esp_netif`             | IPv4 addresses only                                               |
+| `socketpair()`   | Creates a pair of connected sockets using `lwIP` loopback stream sockets | IPv4 sockets only                                    |
+| `pipe()`         | Wraps `socketpair()` to provide unidirectional pipe-like functionality | Uses bidirectional sockets in place of true pipes  |
+| `getnameinfo()`  | Converts IP addresses to human-readable form using `lwIP`'s `inet_ntop()` | IPv4 only; supports `NI_NUMERICHOST` and `NI_NUMERICSERV` flags only |
+| `gai_strerror()` | Returns error code as a string                              | Simple numeric string representation only                         |
+
+**Note**: `socketpair()` and `pipe()` are built on top of `lwIP` TCP sockets, inheriting the same characteristics. For instance, the maximum transmit buffer size is based on the `TCP_SND_BUF` setting.

components/sock_utils/examples/simple/CMakeLists.txt

@@ -0,0 +1,8 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sock_utils_example)

components/sock_utils/examples/simple/README.md

@@ -0,0 +1,30 @@
+# Simple example
+
+This example demonstrates using socket helpers on ESP_PLATFORM
+
+The functionality of this example is meant to be very generic, so the application is compilable on linux without any IDF dependencies:
+```bash
+gcc main/app.c -lpthread
+```
+
+## Example output on ESP_PLATFORM
+
+```
+I (8073) esp_netif_handlers: example_netif_sta ip: 192.168.0.32, mask: 255.255.255.0, gw: 192.168.0.1
+I (8073) example_connect: Got IPv4 event: Interface "example_netif_sta" address: 192.168.0.32
+I (8073) example_common: Connected to example_netif_sta
+I (8083) example_common: - IPv4 address: 192.168.0.32,
+I (8093) example_common: - IPv6 address: fe80:0000:0000:0000:XXXX, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (8103) sock_utils_example: Received signal: IP4
+I (8103) sock_utils_example: IPv4 address of interface "sta": 192.168.0.32
+I (8113) main_task: Returned from app_main()
+```
+
+## Example output on linux platform
+
+```
+I[sock_utils_example]: Received signal: IP4
+I[sock_utils_example]: IPv4 address of interface "lo": 127.0.0.1
+I[sock_utils_example]: IPv4 address of interface "en0": 192.168.0.28
+I[sock_utils_example]: IPv4 address of interface "docker0": 172.17.0.1
+```

components/sock_utils/examples/simple/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "app.c"
+                    INCLUDE_DIRS ".")

components/sock_utils/examples/simple/main/app.c

@@ -0,0 +1,123 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include <stdio.h>
+#include <pthread.h>
+#include <sys/socket.h>
+#include <netdb.h>
+#include <unistd.h>
+#include <string.h>
+#include <errno.h>
+#include <net/if.h>
+#include <ifaddrs.h>
+
+#ifdef ESP_PLATFORM
+#include "nvs_flash.h"
+#include "esp_event.h"
+#include "esp_netif.h"
+#include "esp_log.h"
+#include "protocol_examples_common.h"
+#else
+// Provides simplified support for building on linux (whithout official IDF linux target)
+// in order to check with the actual host functionality
+// use `gcc main/app.c -lpthread`
+#define SIMPLE_LOG( lev, tag, format, ... ) do { printf("%s[%s]: ", lev, tag); printf(format, ##__VA_ARGS__); printf("\n"); } while(0)
+#define ESP_LOGE(tag, format, ... ) SIMPLE_LOG("E", tag, format, ##__VA_ARGS__)
+#define ESP_LOGI(tag, format, ... ) SIMPLE_LOG("I", tag, format, ##__VA_ARGS__)
+#define ESP_ERROR_CHECK(action) action
+static void example_connect(void) { }
+#endif
+
+static const char *TAG = "sock_utils_example";
+
+static void *reader_thread(void *arg)
+{
+    int *pipe_fds = (int *)arg;
+    char buffer[64];
+    int len;
+    while ((len = read(pipe_fds[0], buffer, sizeof(buffer))) < 0) {
+        if (errno != EAGAIN) {
+            ESP_LOGE(TAG, "Failed reading from pipe: %d", errno);
+            return NULL;
+        }
+        usleep(100000);
+    }
+    buffer[len] = '\0';
+    ESP_LOGI(TAG, "Received signal: %s", buffer);
+    if (strcmp(buffer, "IP4") != 0) {
+        ESP_LOGE(TAG, "Unknown signal");
+        return NULL;
+    }
+
+    struct ifaddrs *addresses, *addr;
+    if (getifaddrs(&addresses) == -1) {
+        ESP_LOGE(TAG, "getifaddrs() failed");
+        return NULL;
+    }
+    addr = addresses;
+
+    while (addr) {
+        if (addr->ifa_addr && addr->ifa_addr->sa_family == AF_INET) {   // look for IP4 addresses
+            struct sockaddr_in *sock_addr = (struct sockaddr_in *) addr->ifa_addr;
+            if ((addr->ifa_flags & IFF_UP) == 0) {
+                ESP_LOGI(TAG, "Network interface \"%s\" is down", addr->ifa_name);
+            } else {
+                if (getnameinfo((struct sockaddr *)sock_addr, sizeof(*sock_addr),
+                                buffer, sizeof(buffer), NULL, 0, NI_NUMERICHOST) != 0) {
+                    freeifaddrs(addresses);
+                    return NULL;
+                }
+                ESP_LOGI(TAG, "IPv4 address of interface \"%s\": %s", addr->ifa_name, buffer);
+            }
+        }
+        addr = addr->ifa_next;
+    }
+    freeifaddrs(addresses);
+    return NULL;
+}
+
+static void simple_pipe_example(void)
+{
+    int pipe_fds[2];
+    if (pipe(pipe_fds) == -1) {
+        ESP_LOGE(TAG, "Failed to create pipe");
+        return;
+    }
+
+    // creates reader thread to wait for a pipe signal
+    // and print out our IPv4 addresses
+    pthread_t reader;
+    pthread_create(&reader, NULL, reader_thread, pipe_fds);
+
+    /* This helper function configures Wi-Fi or Ethernet, as selected in menuconfig.
+     * Read "Establishing Wi-Fi or Ethernet Connection" section in
+     * examples/protocols/README.md for more information about this function.
+     */
+    ESP_ERROR_CHECK(example_connect());
+
+    // at this point we should have received an IP address -> send signal to the reader thread
+    const char signal[] = "IP4";
+    write(pipe_fds[1], signal, sizeof(signal));
+    pthread_join(reader, NULL);
+
+    // Close pipe file descriptors
+    close(pipe_fds[0]);
+    close(pipe_fds[1]);
+}
+
+#ifdef ESP_PLATFORM
+void app_main(void)
+{
+    ESP_ERROR_CHECK(nvs_flash_init());
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    simple_pipe_example();
+}
+#else
+int main(void)
+{
+    simple_pipe_example();
+}
+#endif

components/sock_utils/examples/simple/main/idf_component.yml

@@ -0,0 +1,8 @@
+dependencies:
+  idf:
+    version: ">=5.0"
+  sock_utils:
+    version: "*"
+    override_path: '../../../'
+  protocol_examples_common:
+    path: ${IDF_PATH}/examples/common_components/protocol_examples_common

components/sock_utils/examples/simple/pytest_sockutls.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+
+def test_sockutls(dut):
+    """
+    steps:
+      1. Start the example
+      2. Check the resultant IPv4 address from station netif
+    """
+    # Signal from the pipe simple implementation
+    dut.expect('Received signal: IP4')
+    # and the IPv4 address of the connected netif
+    dut.expect('IPv4 address of interface "en1"')

components/sock_utils/examples/simple/sdkconfig.ci

@@ -0,0 +1,2 @@
+CONFIG_EXAMPLE_CONNECT_WIFI=n
+CONFIG_EXAMPLE_CONNECT_ETHERNET=y

components/sock_utils/idf_component.yml

@@ -0,0 +1,6 @@
+version: 0.1.0
+description: The component provides helper implementation of common system/socket utilities
+url: https://github.com/espressif/esp-protocols/tree/master/components/sock_utils
+dependencies:
+  idf:
+    version: '>=5.0'

components/sock_utils/include/gai_strerror.h

@@ -0,0 +1,31 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include "lwip/sockets.h"
+#include "netdb_macros.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef CONFIG_IDF_TARGET_LINUX
+// namespace with esp_ on linux to avoid duplication of symbols
+#define gai_strerror esp_gai_strerror
+#endif
+
+/**
+* @brief Returns a numeric string representing of `getaddrinfo()` error code.
+*
+* @param[in] ecode Error code returned by `getaddrinfo()`.
+*
+* @return A pointer to a string describing the error.
+*/
+const char *gai_strerror(int ecode);
+
+#ifdef __cplusplus
+}
+#endif

components/sock_utils/include/getnameinfo.h

@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include "lwip/sockets.h"
+
+#ifdef CONFIG_IDF_TARGET_LINUX
+// namespace with esp_ on linux to avoid conflict of symbols
+#define getnameinfo esp_getnameinfo
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+* @brief Converts a socket address to a corresponding host and service name.
+*
+* @param[in]  addr    Pointer to the socket address structure.
+* @param[in]  addrlen Length of the socket address.
+* @param[out] host    Buffer to store the host name.
+* @param[in]  hostlen Length of the host buffer.
+* @param[out] serv    Buffer to store the service name.
+* @param[in]  servlen Length of the service buffer.
+* @param[in]  flags   Flags to modify the behavior of the function.
+*
+* @return
+*     - 0 on success.
+*     - Non-zero on failure, with `errno` set to indicate the error.
+*/
+int getnameinfo(const struct sockaddr *addr, socklen_t addrlen,
+                char *host, socklen_t hostlen,
+                char *serv, socklen_t servlen, int flags);
+
+#ifdef __cplusplus
+}
+#endif

components/sock_utils/include/ifaddrs.h

@@ -0,0 +1,56 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include "lwip/sockets.h"
+#include "netdb_macros.h"
+// include also other related headers to simplify porting of linux libs
+#include "getnameinfo.h"
+#include "socketpair.h"
+#include "gai_strerror.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef CONFIG_IDF_TARGET_LINUX
+// namespace with esp_ on linux to avoid duplication of symbols
+#define getifaddrs esp_getifaddrs
+#define freeifaddrs esp_freeifaddrs
+#endif
+
+/**
+ * @brief Simplified version of ifaddr struct
+ */
+struct ifaddrs {
+    struct ifaddrs  *ifa_next;    /* Next item in list */
+    char            *ifa_name;    /* Name of interface */
+    struct sockaddr *ifa_addr;    /* Address of interface */
+    unsigned int ifa_flags;
+};
+
+/**
+ * @brief Retrieves a list of network interfaces and their addresses.
+ *
+ * @param[out] ifap Pointer to a linked list of `struct ifaddrs`. On success, `*ifap` will be set
+ *                  to the head of the list.
+ *
+ * @return
+ *     - 0 on success.
+ *     - -1 on failure, with `errno` set to indicate the error.
+ */
+int getifaddrs(struct ifaddrs **ifap);
+
+/**
+ * @brief Frees the memory allocated by `getifaddrs()`.
+ *
+ * @param[in] ifa Pointer to the linked list of network interfaces to be freed.
+ */
+void freeifaddrs(struct ifaddrs *ifa);
+
+#ifdef __cplusplus
+}
+#endif

components/sock_utils/include/netdb_macros.h

@@ -0,0 +1,34 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifndef NI_NUMERICHOST
+#define NI_NUMERICHOST  0x1
+#endif
+
+#ifndef IFF_UP
+#define IFF_UP          0x1
+#endif
+
+#ifndef IFF_LOOPBACK
+#define IFF_LOOPBACK    0x8
+#endif
+
+#ifndef NI_NUMERICSERV
+#define NI_NUMERICSERV  0x8
+#endif
+
+#ifndef NI_DGRAM
+#define NI_DGRAM        0x00000010
+#endif
+
+#ifndef EAI_BADFLAGS
+#define EAI_BADFLAGS    3
+#endif
+
+#ifndef AF_UNIX
+#define AF_UNIX         1
+#endif

components/sock_utils/include/poll.h

@@ -0,0 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// This is a placeholder for poll API
+// Note: some libraries require `poll.h` in public include dirs

components/sock_utils/include/socketpair.h

@@ -0,0 +1,49 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include "lwip/sockets.h"
+#include "netdb_macros.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef CONFIG_IDF_TARGET_LINUX
+// namespace with esp_ on linux to avoid conflict of symbols
+#define socketpair esp_socketpair
+#define pipe esp_pipe
+#endif
+
+/**
+* @brief Creates a pair of connected sockets.
+*
+* @param[in]  domain   Communication domain (e.g., AF_UNIX).
+* @param[in]  type     Socket type (e.g., SOCK_STREAM).
+* @param[in]  protocol Protocol to be used (usually 0).
+* @param[out] sv       Array of two integers to store the file descriptors of the created sockets.
+*
+* @return
+*     - 0 on success.
+*     - -1 on failure, with `errno` set to indicate the error.
+*/
+int socketpair(int domain, int type, int protocol, int sv[2]);
+
+/**
+ * @brief Creates a unidirectional data channel (pipe).
+ *
+ * @param[out] pipefd Array of two integers where the file descriptors for the read and write ends
+ *                    of the pipe will be stored.
+ *
+ * @return
+ *     - 0 on success.
+ *     - -1 on failure, with `errno` set to indicate the error.
+ */
+int pipe(int pipefd[2]);
+
+#ifdef __cplusplus
+}
+#endif

components/sock_utils/src/gai_strerror.c

@@ -0,0 +1,17 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <stdio.h>
+#include "gai_strerror.h"
+
+_Thread_local char gai_strerror_string[32];
+
+const char *gai_strerror(int ecode)
+{
+    if (snprintf(gai_strerror_string, sizeof(gai_strerror_string), "EAI error:%d", ecode) < 0) {
+        return "gai_strerror() failed";
+    }
+    return gai_strerror_string;
+}

components/sock_utils/src/getnameinfo.c

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <fcntl.h>
+#include "lwip/sockets.h"
+#include "lwip/netdb.h"
+#include "ifaddrs.h"
+#include "esp_check.h"
+
+int getnameinfo(const struct sockaddr *addr, socklen_t addrlen,
+                char *host, socklen_t hostlen,
+                char *serv, socklen_t servlen, int flags)
+{
+    // Validate flags to ensure only allowed flags are passed.
+    if (flags & ~(NI_NUMERICHOST | NI_NUMERICSERV | NI_DGRAM)) {
+        return EAI_BADFLAGS;
+    }
+
+    const struct sockaddr_in *sinp = (const struct sockaddr_in *) addr;
+
+    switch (addr->sa_family) {
+    case AF_INET:
+        // Handle numeric host address
+        if (flags & NI_NUMERICHOST) {
+            if (host == NULL || hostlen == 0) {
+                return 0;
+            }
+            if (inet_ntop(AF_INET, &sinp->sin_addr, host, hostlen) == NULL) {
+                return EOVERFLOW;  // Error if address couldn't be converted
+            }
+        }
+
+        // Handle numeric service (port)
+        if (flags & NI_NUMERICSERV) {
+            // Print the port number, but for UDP services (if NI_DGRAM), we treat it the same way
+            int port = ntohs(sinp->sin_port);  // Convert port from network byte order
+            if (serv == NULL || servlen == 0) {
+                return 0;
+            }
+            if (snprintf(serv, servlen, "%d", port) < 0) {
+                return EOVERFLOW;  // Error if snprintf failed
+            }
+        }
+
+        break;
+
+    default:
+        return EAI_FAMILY;  // Unsupported address family
+    }
+
+    return 0;
+}

components/sock_utils/src/ifaddrs.c

@@ -0,0 +1,101 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <string.h>
+#include <sys/socket.h>
+#include "esp_netif.h"
+#include "esp_check.h"
+#include <stdlib.h>
+#include "ifaddrs.h"
+
+static const char *TAG = "sockutls_getifaddr";
+
+
+static esp_err_t getifaddrs_unsafe(void *ctx)
+{
+    struct ifaddrs **ifap = ctx;
+    struct ifaddrs *ifaddr = NULL;
+    struct ifaddrs **next_addr = NULL;
+    struct sockaddr_in *addr_in = NULL;
+    esp_netif_t *netif = NULL;
+    char if_name[5];    // lwip netif name buffer (e.g. `st1`, 2 letters + number)
+    esp_netif_ip_info_t ip;
+    esp_err_t ret = ESP_OK;
+
+    while ((netif = esp_netif_next_unsafe(netif)) != NULL) {
+        ESP_GOTO_ON_FALSE((ifaddr = (struct ifaddrs *)calloc(1, sizeof(struct ifaddrs))),
+                          ESP_ERR_NO_MEM, err, TAG, "Failed to allocate ifaddr");
+        if (next_addr == NULL) {    // the first address -> attach the head
+            *ifap = ifaddr;
+        } else {
+            *next_addr = ifaddr;    // attach next addr
+        }
+        ESP_GOTO_ON_ERROR(esp_netif_get_netif_impl_name(netif, if_name), err, TAG, "Failed to get netif name");
+        ESP_GOTO_ON_FALSE((ifaddr->ifa_name = strdup(if_name)),
+                          ESP_ERR_NO_MEM, err, TAG, "Failed to allocate if name");
+        ESP_GOTO_ON_FALSE((addr_in = (struct sockaddr_in *)calloc(1, sizeof(struct sockaddr_in))),
+                          ESP_ERR_NO_MEM, err, TAG, "Failed to allocate addr_in");
+        ifaddr->ifa_addr = (struct sockaddr *)addr_in;
+        ESP_GOTO_ON_ERROR(esp_netif_get_ip_info(netif, &ip), err, TAG, "Failed to get netif IP");
+        ESP_LOGD(TAG, "IPv4 address: " IPSTR, IP2STR(&ip.ip));
+        addr_in->sin_family = AF_INET;
+        addr_in->sin_addr.s_addr = ip.ip.addr;
+        ifaddr->ifa_flags = esp_netif_is_netif_up(netif) ? IFF_UP : 0;
+        next_addr = &ifaddr->ifa_next;
+    }
+    if (next_addr == NULL) {
+        *ifap = NULL;       // no addresses found
+    } else {
+        *next_addr = NULL;  // terminate the list
+    }
+    return ret;
+
+err:
+    if (next_addr) {
+        *next_addr = NULL;
+        freeifaddrs(*ifap);
+    } else {
+        freeifaddrs(ifaddr);
+    }
+    *ifap = NULL;
+    return ret;
+
+}
+
+int getifaddrs(struct ifaddrs **ifap)
+{
+    if (ifap == NULL) {
+        errno = EINVAL;
+        return -1; // Invalid argument
+    }
+
+    esp_err_t ret = esp_netif_tcpip_exec(getifaddrs_unsafe, ifap);
+    switch (ret) {
+    case ESP_OK:
+        return 0;
+    case ESP_ERR_NO_MEM:
+        errno = ENOMEM;
+        return -1;
+    case ESP_ERR_INVALID_ARG:
+    case ESP_ERR_ESP_NETIF_INVALID_PARAMS:
+        errno = EINVAL;
+        return -1;
+    default:
+    case ESP_FAIL:
+        errno = EIO;    // Generic I/O Error
+        return  -1;
+    }
+}
+
+void freeifaddrs(struct ifaddrs *ifa)
+{
+    while (ifa != NULL) {
+        struct ifaddrs *next = ifa->ifa_next;
+        free(ifa->ifa_name);
+        free(ifa->ifa_addr);
+        free(ifa);
+        ifa = next;
+    }
+}

components/sock_utils/src/socketpair.c

@@ -0,0 +1,76 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <fcntl.h>
+#include "lwip/sockets.h"
+#include "socketpair.h"
+#include "esp_check.h"
+
+#define INVALID_SOCKET (-1)
+
+static const char *TAG = "socket_helpers";
+
+int socketpair(int domain, int type, int protocol, int sv[2])
+{
+    if (protocol != 0 || type != SOCK_STREAM || domain != AF_UNIX) {
+        errno = ENOSYS; // not implemented
+        return -1;
+    }
+    struct sockaddr_storage ss;
+    struct sockaddr_in *sa = (struct sockaddr_in *)&ss;
+    socklen_t ss_len = sizeof(struct sockaddr_in);
+    int fd1 = INVALID_SOCKET;
+    int fd2 = INVALID_SOCKET;
+    int listenfd = INVALID_SOCKET;
+    int ret = 0; // Success
+
+    sa->sin_family = AF_INET;
+    sa->sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    sa->sin_port = 0;
+    listenfd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    ESP_GOTO_ON_FALSE(listenfd != INVALID_SOCKET, -1, err, TAG, "Cannot create listening socket");
+    ESP_GOTO_ON_FALSE(listen(listenfd, 1) == 0, -1, err, TAG, "Failed to listen");
+
+    memset(&ss, 0, sizeof(ss));
+    ss_len = sizeof(ss);
+    ESP_GOTO_ON_FALSE(getsockname(listenfd, (struct sockaddr *)&ss, &ss_len) >= 0, -1, err, TAG, "getsockname failed");
+
+    sa->sin_family = AF_INET;
+    sa->sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+
+    fd1 = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    ESP_GOTO_ON_FALSE(fd1 != INVALID_SOCKET, -1, err, TAG, "Cannot create read side socket");
+    ESP_GOTO_ON_FALSE(connect(fd1, (struct sockaddr *)&ss, ss_len) >= 0, -1, err, TAG, "Failed to connect fd1");
+    fd2 = accept(listenfd, NULL, 0);
+    ESP_GOTO_ON_FALSE(fd2 != INVALID_SOCKET, -1, err, TAG, "Failed to accept fd2");
+
+    close(listenfd);
+    sv[0] = fd1;
+    sv[1] = fd2;
+    return ret;
+
+err:
+    if (listenfd != INVALID_SOCKET) {
+        close(listenfd);
+    }
+    if (fd1 != INVALID_SOCKET) {
+        close(fd1);
+    }
+    return ret;
+}
+
+int pipe(int pipefd[2])
+{
+    if (socketpair(AF_UNIX, SOCK_STREAM, 0, pipefd) == -1) {
+        return -1;
+    }
+    // Close the unwanted ends to make it a unidirectional pipe
+    if (shutdown(pipefd[0], SHUT_WR) == -1 || shutdown(pipefd[1], SHUT_RD) == -1) {
+        close(pipefd[0]);
+        close(pipefd[1]);
+        return -1;
+    }
+    return 0;
+}

components/sock_utils/test/host/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.16)
+
+set(COMPONENTS main)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+project(sock_utils_host_test)

components/sock_utils/test/host/main/CMakeLists.txt

@@ -0,0 +1,6 @@
+idf_component_register(SRCS "test_sock_utils.cpp"
+                        INCLUDE_DIRS "$ENV{IDF_PATH}/tools"
+                        WHOLE_ARCHIVE)
+
+target_compile_options(${COMPONENT_LIB} PUBLIC -fsanitize=address -fconcepts)
+target_link_options(${COMPONENT_LIB} PUBLIC -fsanitize=address)

components/sock_utils/test/host/main/idf_component.yml

@@ -0,0 +1,5 @@
+dependencies:
+  espressif/catch2: "^3.4.0"
+  sock_utils:
+    version: "*"
+    override_path: '../../../'

components/sock_utils/test/host/main/test_sock_utils.cpp

@@ -0,0 +1,167 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "ifaddrs.h"
+#include "esp_netif.h"
+#include "esp_event.h"
+#include "catch2/catch_test_macros.hpp"
+#include "catch2/catch_session.hpp"
+
+#define TEST_PORT_NUMBER 3333
+#define TEST_PORT_STRING "3333"
+
+static char buffer[64];
+
+static esp_err_t dummy_transmit(void *h, void *buffer, size_t len)
+{
+    return ESP_OK;
+}
+
+static esp_err_t dummy_transmit_wrap(void *h, void *buffer, size_t len, void *pbuf)
+{
+    return ESP_OK;
+}
+
+static esp_netif_t *create_test_netif(const char *if_key, uint8_t last_octet)
+{
+    esp_netif_inherent_config_t base_cfg = ESP_NETIF_INHERENT_DEFAULT_WIFI_STA();
+    esp_netif_ip_info_t ip = { };
+    ip.ip.addr = ESP_IP4TOADDR(1, 2, 3, last_octet);
+    base_cfg.ip_info = &ip;
+    base_cfg.if_key = if_key;
+    // create a dummy driver, so the netif could be started and set up
+    base_cfg.flags = ESP_NETIF_FLAG_AUTOUP;
+    esp_netif_driver_ifconfig_t driver_cfg = {};
+    driver_cfg.handle = (esp_netif_iodriver_handle)1;
+    driver_cfg.transmit = dummy_transmit;
+    driver_cfg.transmit_wrap = dummy_transmit_wrap;
+    esp_netif_config_t cfg = { .base = &base_cfg, .driver = &driver_cfg, .stack = ESP_NETIF_NETSTACK_DEFAULT_WIFI_STA };
+    esp_netif_t *netif = esp_netif_new(&cfg);
+    // need to start the netif to be considered in tests
+    esp_netif_action_start(netif, nullptr, 0, nullptr);
+    return netif;
+}
+
+TEST_CASE("esp_getnameinfo() for IPv4", "[sock_utils]")
+{
+    struct sockaddr_in sock_addr = {};
+    sock_addr.sin_family = AF_INET;
+    sock_addr.sin_port = htons(TEST_PORT_NUMBER); // sock_addr fields are in network byte order
+    REQUIRE(esp_getnameinfo((struct sockaddr *)&sock_addr, sizeof(sock_addr), buffer, sizeof(buffer), NULL, 0, NI_NUMERICHOST) == 0);
+    CHECK(strcmp("0.0.0.0", buffer) == 0);
+    CHECK(esp_getnameinfo((struct sockaddr *)&sock_addr, sizeof(sock_addr), NULL, 0, buffer, sizeof(buffer), NI_NUMERICSERV) == 0);
+    CHECK(strcmp(TEST_PORT_STRING, buffer) == 0);
+}
+
+TEST_CASE("esp_getnameinfo() for IPv6", "[sock_utils]")
+{
+    struct sockaddr_in sock_addr = {};
+    sock_addr.sin_family = AF_INET6;
+    // IPv6 not supported for now
+    CHECK(esp_getnameinfo((struct sockaddr *)&sock_addr, sizeof(sock_addr), buffer, sizeof(buffer), NULL, 0, NI_NUMERICHOST) != 0);
+}
+
+static void test_getifaddr(int expected_nr_of_addrs)
+{
+    struct ifaddrs *addresses, *addr;
+    int nr_of_addrs = 0;
+
+    CHECK(esp_getifaddrs(&addresses) != -1);
+    addr = addresses;
+
+    while (addr) {
+        ++nr_of_addrs;
+        if (addr->ifa_addr && addr->ifa_addr->sa_family == AF_INET) {   // look for IP4 addresses
+            struct sockaddr_in *sock_addr = (struct sockaddr_in *) addr->ifa_addr;
+            if (esp_getnameinfo((struct sockaddr *)sock_addr, sizeof(*sock_addr),
+                                buffer, sizeof(buffer), NULL, 0, NI_NUMERICHOST) != 0) {
+                printf("esp_getnameinfo() failed\n");
+            } else {
+                printf("IPv4 address of interface \"%s\": %s\n", addr->ifa_name, buffer);
+                if (strcmp(addr->ifa_name, "st1") == 0) {
+                    CHECK(strcmp("1.2.3.1", buffer) == 0);
+                } else if (strcmp(addr->ifa_name, "st2") == 0) {
+                    CHECK(strcmp("1.2.3.2", buffer) == 0);
+                } else {
+                    FAIL("unexpected network interface");
+                }
+            }
+        }
+        addr = addr->ifa_next;
+    }
+    // check that we got 1 address with exact content
+    CHECK(nr_of_addrs == expected_nr_of_addrs);
+    esp_freeifaddrs(addresses);
+}
+
+TEST_CASE("esp_getifaddrs() with 0, 1, and 2 addresses", "[sock_utils]")
+{
+    test_getifaddr(0);
+    esp_netif_t *esp_netif = create_test_netif("station", 1);   // st1
+    REQUIRE(esp_netif != NULL);
+    test_getifaddr(1);
+    esp_netif_t *esp_netif2 = create_test_netif("station2", 2); // st2
+    REQUIRE(esp_netif2 != NULL);
+    test_getifaddr(2);
+    esp_netif_destroy(esp_netif);
+    esp_netif_destroy(esp_netif2);
+}
+
+static void test_pipe(int read_fd, int write_fd)
+{
+    CHECK(read_fd  >= 0);
+    CHECK(write_fd >= 0);
+    CHECK(write(write_fd, buffer, 1) > 0);
+    CHECK(write(write_fd, buffer, 1) > 0);
+    CHECK(read(read_fd, buffer, 1) == 1);
+    CHECK(read(read_fd, buffer, 1) == 1);
+}
+
+TEST_CASE("socketpair()", "[sock_utils]")
+{
+    int fds[2];
+    CHECK(esp_socketpair(AF_UNIX, SOCK_STREAM, 0, fds) == 0);
+    printf("socketpair created fds: %d, %d\n", fds[0], fds[1]);
+    // check both directions
+    test_pipe(fds[0], fds[1]);
+    test_pipe(fds[1], fds[0]);
+    close(fds[0]);
+    close(fds[1]);
+}
+
+TEST_CASE("pipe()", "[sock_utils]")
+{
+    int fds[2];
+    CHECK(esp_pipe(fds) == 0);
+    printf("pipe created fds: %d, %d\n", fds[0], fds[1]);
+    // check only one direction
+    test_pipe(fds[0], fds[1]);
+    close(fds[0]);
+    close(fds[1]);
+}
+
+TEST_CASE("gai_strerror()", "[sock_utils]")
+{
+    const char *str_error = esp_gai_strerror(EAI_BADFLAGS);
+    CHECK(str_error != NULL);
+}
+
+
+extern "C" void app_main(void)
+{
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+
+    Catch::Session session;
+
+    int failures = session.run();
+    if (failures > 0) {
+        printf("TEST FAILED! number of failures=%d\n", failures);
+        exit(1);
+    } else {
+        printf("Test passed!\n");
+        exit(0);
+    }
+}

components/sock_utils/test/host/sdkconfig.defaults

@@ -0,0 +1,7 @@
+# This file was generated using idf.py save-defconfig. It can be edited manually.
+# Espressif IoT Development Framework (ESP-IDF) 5.4.0 Project Minimal Configuration
+#
+CONFIG_IDF_TARGET="linux"
+CONFIG_COMPILER_CXX_EXCEPTIONS=y
+CONFIG_FREERTOS_HZ=1000
+CONFIG_LWIP_ENABLE=y

docs/asio/en/index.rst

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

docs/asio/generate_docs

@@ -2,7 +2,7 @@
 
 rm -rf docs
 
-build-docs --target esp32 --language en
+build-docs --target esp32 --language en --project-path ../../
 
 mkdir -p docs/generic
 mv _build/en/esp32/html docs/generic

docs/esp_modem/en/README.rst

@@ -197,7 +197,7 @@ we need to timely interrupt to process incoming data. Here'are few suggestions t
 * Increase internal UART rx buffer size
 * Increase UART terminal task priority
 * Use UART flow control
-If none of the above helps, you can check the test ``target_ota``, which performs OTA in two steps -- first read the data, then pass the data to mbedTLS. See the test ``README.md`` for more details.
+If none of the above helps, you can check the test :component:`esp_modem/test/target_ota`, which performs OTA in two steps -- first read the data, then pass the data to mbedTLS. See the test ``README.md`` for more details.
 
 Potential issues when using CMUX mode and these devices:
 
@@ -234,3 +234,35 @@ this patch to adapt the exit sequence https://github.com/espressif/esp-protocols
       if ((frame_header[3] & 1) == 0) {
             if (frame_header_offset + frame.len <= 4) {
                   frame_header_offset += frame.len;
+
+4) Device CAVLI C16QS does not correctly enter CMUX mode with esp_modem.
+The CMUX as defined in 3GPP TS 27.010: SABM response (paragraph 5.4.1)
+should be a UA frame (upon success, DM frame on failure).
+This device however responds with 0x3F, which is neither UA nor DM.
+You can apply the below patch to adapt the entry sequence
+
+::
+
+      diff --git a/components/esp_modem/src/esp_modem_cmux.cpp b/components/esp_modem/src/esp_modem_cmux.cpp
+      index c47e13b..7afbf73 100644
+      --- a/components/esp_modem/src/esp_modem_cmux.cpp
+      +++ b/components/esp_modem/src/esp_modem_cmux.cpp
+      @@ -137,7 +137,8 @@ bool CMux::data_available(uint8_t *data, size_t len)
+            } else {
+                  return false;
+            }
+      -    } else if (data == nullptr && type == (FT_UA | PF) && len == 0) { // notify the initial SABM command
+      +    } else if (data == nullptr && (type == (FT_UA | PF) || type == 0x3f) && len == 0) { // notify the initial SABM command
+            Scoped<Lock> l(lock);
+            sabm_ack = dlci;
+      } else if (data == nullptr && dlci > 0) {
+      @@ -238,8 +239,7 @@ bool CMux::on_header(CMuxFrame &frame)
+      type = frame_header[2];
+      // Sanity check for expected values of DLCI and type,
+      // since CRC could be evaluated after the frame payload gets received
+      -    if (dlci > MAX_TERMINALS_NUM || (frame_header[1] & 0x01) == 0 ||
+      -            (((type & FT_UIH) != FT_UIH) &&  type != (FT_UA | PF) ) ) {
+      +    if (dlci > MAX_TERMINALS_NUM) {
+            recover_protocol(protocol_mismatch_reason::UNEXPECTED_HEADER);
+            return true;
+      }

test_app/CMakeLists.txt

@@ -14,6 +14,7 @@ set(EXTRA_COMPONENT_DIRS
     ../components/console_cmd_wifi
     ../components/console_simple_init
     ../components/mbedtls_cxx
+    ../components/sock_utils
     ../components/mdns)