feat(mosq): Update brokerless example to work with esp-peer

* Relax CI criteria to build on v5.2+ (for the brokerless due to
  esp-peer dependency)

Author: david-cermak

.github/workflows/mosq__build.yml

@@ -14,10 +14,15 @@ jobs:
     strategy:
       matrix:
         idf_ver: ["latest", "release-v5.5", "release-v5.4", "release-v5.3", "release-v5.2", "release-v5.1"]
+        example: ["broker", "serverless_mqtt"]
+        exclude:
+          - idf_ver: "release-v5.1"
+            example: "serverless_mqtt"  # serverless_mqtt is not supported due to esp-peer
+
     runs-on: ubuntu-22.04
     container: espressif/idf:${{ matrix.idf_ver }}
     env:
-      TEST_DIR: components/mosquitto/examples
+      TEST_DIR: components/mosquitto/examples/${{ matrix.example }}
       TARGET_TEST: broker
       TARGET_TEST_DIR: build_esp32_default
     steps:
@@ -31,14 +36,17 @@ jobs:
           . ${IDF_PATH}/export.sh
           pip install idf-component-manager idf-build-apps --upgrade
           python ci/build_apps.py -c ${TEST_DIR} -m components/mosquitto/.build-test-rules.yml
-          # upload only the target test artifacts
-          cd ${TEST_DIR}/${TARGET_TEST}
-          ${GITHUB_WORKSPACE}/ci/clean_build_artifacts.sh `pwd`/${TARGET_TEST_DIR}
-          zip -qur artifacts.zip ${TARGET_TEST_DIR}
+          if [ "${{ matrix.example }}" == "${TARGET_TEST}" ]; then
+            # upload only the target test artifacts
+            cd ${TEST_DIR}
+            ${GITHUB_WORKSPACE}/ci/clean_build_artifacts.sh `pwd`/${TARGET_TEST_DIR}
+            zip -qur artifacts.zip ${TARGET_TEST_DIR}
+          fi
       - uses: actions/upload-artifact@v4
+        if: ${{ matrix.example == 'broker' }}
         with:
           name: mosq_target_esp32_${{ matrix.idf_ver }}
-          path: ${{ env.TEST_DIR }}/${{ env.TARGET_TEST }}/artifacts.zip
+          path: ${{ env.TEST_DIR }}/artifacts.zip
           if-no-files-found: error
 
   test_mosq:

components/mosquitto/examples/serverless_mqtt/CMakeLists.txt

@@ -3,4 +3,21 @@
 cmake_minimum_required(VERSION 3.16)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# Setup ESP-PEER from GitHub repo (but it's supported only on certain targets)
+set(ESP_PEER_COMPATIBLE_TARGETS "esp32s2" "esp32s3" "esp32p4" "esp32")
+if(IDF_TARGET IN_LIST ESP_PEER_COMPATIBLE_TARGETS)
+execute_process(COMMAND ${CMAKE_BINARY_DIR}/../esp_peer_setup/install.sh
+                ${CMAKE_BINARY_DIR}
+                WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+                RESULT_VARIABLE script_result)
+
+if(script_result)
+    message(FATAL_ERROR "Script esp_peer_setup.sh failed with exit code ${script_result}")
+endif()
+list(APPEND EXTRA_COMPONENT_DIRS "${CMAKE_BINARY_DIR}/esp-peer/components/")
+else()
+    message(STATUS "ESP-PEER is not compatible with this target")
+endif()
+
 project(serverless_mqtt)

components/mosquitto/examples/serverless_mqtt/README.md

@@ -3,14 +3,19 @@
 MQTT served by (two) mosquitto's running on two ESP chips.
 
 * Leverages MQTT connectivity between two private networks without cloud premisses.
-* Creates two local MQTT servers (on ESP32x's) which are being synchronized over peer to peer connection (established via ICE protocol, by [libjuice](https://github.com/paullouisageneau/libjuice)).
+* Creates two local MQTT servers (on ESP32x's) which are being synchronized over peer to peer connection (established via ICE/WebRTC protocol)
+
+## Peer to peer connection
+
+Could be established either by [libjuice](https://github.com/paullouisageneau/libjuice) or [esp-webRTC](https://github.com/espressif/esp-webrtc-solution). While `juice` is just a low level implementation of ICE-UDP, we need to provide some signalling and synchronization, the `WebRTC` is full-fledged solution to establish a peer connection using standardized signalling, security and transfer protocols.
+
 
 ## How it works
 
 This example needs two ESP32 chipsets, that will create two separate Wi-Fi networks (IoT networks) used for IoT devices.
 Each IoT network is served by an MQTT server (using mosquitto component).
 This example will also synchronize these two MQTT brokers, as if there was only one IoT network with one broker.
-This example creates a peer to peer connection between two chipsets to keep them synchronize. This connection utilizes libjuice (which implements a simplified ICE-UDP) to traverse NATs, which enabling direct connection between two private networks behind NATs.
+This example creates a peer to peer connection between two chipsets to keep them synchronize. This connection utilizes libjuice (which implements a simplified ICE-UDP) or esp-webRTC (which implements WebRTC) to traverse NATs, which enabling direct connection between two private networks behind NATs.
 
 * Diagram
 
@@ -19,12 +24,16 @@ This example creates a peer to peer connection between two chipsets to keep them
 Here's a step-by-step procedure of establishing this remote connection:
 1) Initialize and start Wi-Fi AP (for IoT networks) and Wi-Fi station (for internet connection)
 2) Start mosquitto broker on IoT network
-3) Start libjuice to gather connection candidates
-4) Synchronize using a public MQTT broker and exchange ICE descriptors
-5) Establish ICE UDP connection between the two ESP32 chipsets
+3) Start peer to peer connection
+  - In case of `libjuice`
+      - gather connection candidates
+      - synchronize using a public MQTT broker and exchange ICE descriptors
+      - establish ICE UDP connection between the two ESP32 chipsets
+  - In case of `webRTC` simply start the connection.
 6) Start forwarding mqtt messages
    - Each remote datagram (received from ICE-UDP channel) is re-published to the local MQTT server
-   - Each local MQTT message (received from mosquitto on_message callback) is sent in ICE-UDP datagram
+   - Each local MQTT message (received from mosquitto on_message callback) is sent in a peer message
+
 
 ## How to use this example
 
@@ -33,7 +42,9 @@ You need two ESP32 devices that support Wi-Fi station and Wi-Fi software access
 * Configure Wi-Fi credentials for both devices on both interfaces
   * These devices would be deployed in distinct Wi-Fi environments, so the Wi-Fi station credentials would likely be different.
   * They also create their own IoT network (on the soft-AP interface) Wi-Fi, so the AP credentials would likely be the same, suggesting the IoT networks will be keep synchronized (even though these are two distict Wi-Fi networks).
-* Choose `CONFIG_EXAMPLE_SERVERLESS_ROLE_PEER1` for one device and `CONFIG_EXAMPLE_SERVERLESS_ROLE_PEER2` for another. It's not important which device is PEER1, since the code is symmetric, but these two devices need to have different role.
+* Choose the peer library
+* Only for `libjuice`:
+  - Choose `CONFIG_EXAMPLE_SERVERLESS_ROLE_PEER1` for one device and `CONFIG_EXAMPLE_SERVERLESS_ROLE_PEER2` for another. It's not important which device is PEER1, since the code is symmetric, but these two devices need to have different role.
 * Optionally: You can use `idf.py` `-D` and `-B` flag to keep separate build directories and sdkconfigs for these two roles
 ```
 idf.py -B build1 -DSDKCONFIG=build1/sdkconfig menuconfig build flash monitor
@@ -44,9 +55,64 @@ idf.py -B build1 -DSDKCONFIG=build1/sdkconfig menuconfig build flash monitor
   * Join PEER2 device's AP and connect to the MQTT broker with one or more clients, subscribing to one or more topics.
   * Whenever you publish to a topic, all subscribed clients should receive the message, no matter which Wi-Fi network they're connected to.
 
+## Example output
+
+### With esp-peer
+```
+5: mosquitto version v2.0.20~3 starting
+5: Using default config.
+5: Opening ipv4 listen socket on port 1883.
+5: mosquitto version v2.0.20~3 running
+I (6523) esp-x509-crt-bundle: Certificate validated
+I (7723) APPRTC_SIG: result SUCCESS
+Initials set to 1
+I (7733) HTTPS_CLIENT: HTTP POST Status = 200, content_length = 909
+I (8383) esp-x509-crt-bundle: Certificate validated
+Got url:stun:webrtc.espressif.com:3478 user_name: 1752826470:ninefingers psw:VF/56yvzv6gPnk+Vu2G6fG49rCQ=
+I (9563) HTTPS_CLIENT: HTTP POST Status = 200, content_length = 173
+I (9573) APPRTC_SIG: Registering signaling channel.
+I (9573) APPRTC_SIG: Connecting to wss://webrtc.espressif.com:8089/ws...
+I (9583) websocket_client: Started
+I (10223) esp-x509-crt-bundle: Certificate validated
+I (11403) APPRTC_SIG: WEBSOCKET_EVENT_CONNECTED
+I (11403) APPRTC_SIG: send to remote : {"cmd":"register","roomid":"12345","clientid":"22071010"}
+I (99583) serverless_mqtt: local client event id:7
+99: New connection from 192.168.4.1:56451 on port 1883.
+99: New client connected from 192.168.4.1:56451 as local_mqtt (p2, c1, k120).
+```
+
+## With libjuice
+
+```
+I (4746) esp_netif_handlers: sta ip: 192.168.0.40, mask: 255.255.255.0, gw: 192.168.0.1
+4: mosquitto version v2.0.20~3 starting
+4: Using default config.
+4: Opening ipv4 listen socket on port 1883.
+4: mosquitto version v2.0.20~3 running
+I (4756) serverless_mqtt1: desc: a=ice-ufrag:sGdl
+a=ice-pwd:R4IPGsFctITbT1dCZbfQTL
+a=ice-options:ice2,trickle
+
+00:00:04 INFO    agent.c:1100: Changing state to gathering
+I (4776) serverless_mqtt1: JUICE state change: gathering
+00:00:04 INFO    agent.c:1100: Changing state to connecting
+I (4786) serverless_mqtt1: JUICE state change: connecting
+00:00:04 INFO    agent.c:422: Using STUN server stun.l.google.com:19302
+00:00:04 INFO    agent.c:1378: STUN server binding successful
+00:00:04 INFO    agent.c:1397: Got STUN mapped address 185.194.44.31:62703 from server
+00:00:04 INFO    agent.c:2428: Candidate gathering done
+I (5066) serverless_mqtt1: Gathering done
+I (5066) serverless_mqtt1: desc: {
+        "desc": "a=ice-ufrag:sGdl\r\na=ice-pwd:R4IPGsFctITbT1dCZbfQTL\r\na=ice-options:ice2,trickle\r\n",
+        "cand0":        "a=candidate:1 1 UDP 2122317823 192.168.0.40 62703 typ host",
+        "cand1":        "a=candidate:2 1 UDP 1686109951 185.194.44.31 62703 typ srflx raddr 0.0.0.0 rport 0"
+}
+I (5096) serverless_mqtt1: Other event id:7
+```
+
 ## Warning
 
-This example uses libjuice as a dependency:
+This example uses `libjuice` as a dependency:
 
 * libjuice (UDP Interactive Connectivity Establishment): https://github.com/paullouisageneau/libjuice
 

components/mosquitto/examples/serverless_mqtt/esp_peer_setup/Remove-deprecated-freeRTOS-header.patch

@@ -0,0 +1,28 @@
+From cdc43a56f5ea1ab1935f55f47f8644f5dd30825e Mon Sep 17 00:00:00 2001
+From: David Cermak <[email protected]>
+Date: Thu, 10 Jul 2025 11:09:57 +0200
+Subject: [PATCH] fix(media_lib): Remove deprecated freeRTOS header
+
+---
+ components/media_lib_sal/port/media_lib_os_freertos.c | 4 ++++
+ 1 file changed, 4 insertions(+)
+
+diff --git a/components/media_lib_sal/port/media_lib_os_freertos.c b/components/media_lib_sal/port/media_lib_os_freertos.c
+index d248d59..aea0527 100644
+--- a/components/media_lib_sal/port/media_lib_os_freertos.c
++++ b/components/media_lib_sal/port/media_lib_os_freertos.c
+@@ -40,8 +40,12 @@
+ #include "esp_idf_version.h"
+
+ #if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
++#if (ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 2, 0))
++#include "esp_private/freertos_debug.h"
++#else
+ #include "freertos/task_snapshot.h"
+ #endif
++#endif
+
+ #ifdef __XTENSA__
+ #include "esp_debug_helpers.h"
+--
+2.43.0

components/mosquitto/examples/serverless_mqtt/esp_peer_setup/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -e
+echo "bin_dir: $1"
+
+bin_dir="$1"
+THIS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ESP_PEER_VERSION="ccff3bd65cea750bf6c0abcf9d95b931ba9329f0"
+
+ESP_PEER_URL="https://github.com/espressif/esp-webrtc-solution/archive/${ESP_PEER_VERSION}.zip"
+ESP_PEER_DIR="${bin_dir}/esp-peer"
+ZIP_PATH="${bin_dir}/esp-peer.zip"
+EXTRACTED_DIR="${ESP_PEER_DIR}/esp-webrtc-solution-${ESP_PEER_VERSION}"
+COMPONENTS_SRC="${EXTRACTED_DIR}/components"
+COMPONENTS_DST="${ESP_PEER_DIR}/components"
+PATCH_FILE_1="${THIS_DIR}/Remove-deprecated-freeRTOS-header.patch"
+PATCH_FILE_2="${THIS_DIR}/libpeer-Add-direct-dependency-to-libsrtp.patch"
+
+# Download if not exists
+if [ ! -d "$EXTRACTED_DIR" ]; then
+    echo "Downloading esp-peer ${ESP_PEER_VERSION}..."
+    wget -O "$ZIP_PATH" "$ESP_PEER_URL"
+    unzip -o "$ZIP_PATH" -d "$ESP_PEER_DIR"
+    patch -p1 -d "$EXTRACTED_DIR" < "$PATCH_FILE_1"
+    patch -p1 -d "$EXTRACTED_DIR" < "$PATCH_FILE_2"
+    mv ${EXTRACTED_DIR}/components ${ESP_PEER_DIR}
+    mv ${ESP_PEER_DIR}/components/esp_webrtc/impl/peer_default ${ESP_PEER_DIR}/components
+fi

components/mosquitto/examples/serverless_mqtt/esp_peer_setup/libpeer-Add-direct-dependency-to-libsrtp.patch

@@ -0,0 +1,23 @@
+From 695e057000698f4897b6c5802851499842e2fe31 Mon Sep 17 00:00:00 2001
+From: David Cermak <[email protected]>
+Date: Fri, 11 Jul 2025 16:59:21 +0200
+Subject: [PATCH] fix(libpeer): Add direct dependency to libsrtp
+
+---
+ components/esp_webrtc/impl/peer_default/CMakeLists.txt | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/components/esp_webrtc/impl/peer_default/CMakeLists.txt b/components/esp_webrtc/impl/peer_default/CMakeLists.txt
+index 2af35cf..3fb4615 100644
+--- a/components/esp_webrtc/impl/peer_default/CMakeLists.txt
++++ b/components/esp_webrtc/impl/peer_default/CMakeLists.txt
+@@ -2,6 +2,6 @@ idf_component_register(INCLUDE_DIRS ./include)
+
+ get_filename_component(BASE_DIR ${CMAKE_CURRENT_SOURCE_DIR} NAME)
+ add_prebuilt_library(${BASE_DIR} "${CMAKE_CURRENT_SOURCE_DIR}/libs/${IDF_TARGET}/libpeer_default.a"
+-                     PRIV_REQUIRES ${BASE_DIR} esp_timer)
++                     PRIV_REQUIRES ${BASE_DIR} esp_timer espressif__esp_libsrtp)
+ target_link_libraries(${COMPONENT_LIB}  INTERFACE "-L ${CMAKE_CURRENT_SOURCE_DIR}/libs/${IDF_TARGET}")
+ target_link_libraries(${COMPONENT_LIB}  INTERFACE peer_default)
+--
+2.43.0

components/mosquitto/examples/serverless_mqtt/main/CMakeLists.txt

@@ -1,4 +1,14 @@
+if(CONFIG_EXAMPLE_PEER_LIB_ESP_PEER)
+    set(PEER_BACKEND_SRC "peer_impl_webrtc.c")
+else()
+    set(PEER_BACKEND_SRC "peer_impl_juice.c")
+endif()
+
 idf_component_register(SRCS "serverless_mqtt.c"
                             "wifi_connect.c"
+                            "${PEER_BACKEND_SRC}"
                     INCLUDE_DIRS "."
                     REQUIRES libjuice nvs_flash mqtt json esp_wifi)
+if(CONFIG_EXAMPLE_PEER_LIB_ESP_PEER)
+    idf_component_optional_requires(PUBLIC media_lib_sal esp_webrtc peer_default)
+endif()

components/mosquitto/examples/serverless_mqtt/main/Kconfig.projbuild

@@ -33,21 +33,55 @@ menu "Example Configuration"
                 WiFi station password for the example to use.
     endmenu
 
+    choice EXAMPLE_PEER_LIB
+        prompt "Choose peer library"
+        default EXAMPLE_PEER_LIB_LIBJUICE
+        help
+            Choose the peer library to use for WebRTC communication.
+            libjuice: Use libjuice library for ICE/STUN/TURN (Performs manual signalling)
+            esp_peer: Use ESP-IDF specific peer library
+
+        config EXAMPLE_PEER_LIB_ESP_PEER
+            bool "esp_peer"
+
+        config EXAMPLE_PEER_LIB_LIBJUICE
+            bool "libjuice"
+    endchoice
+
+    config EXAMPLE_WEBRTC_URL
+        string "WebRTC server URL"
+        depends on EXAMPLE_PEER_LIB_ESP_PEER
+        default "https://webrtc.espressif.com/join/"
+        help
+            URL of WebRTC remote endpoint.
+
+    config EXAMPLE_WEBRTC_ROOM_ID
+        string "WebRTC room ID"
+        depends on EXAMPLE_PEER_LIB_ESP_PEER
+        default "12345"
+        help
+            Room ID for WebRTC synchronisation.
+            Could be a random number, but the same for both peers.
+
+
     config EXAMPLE_MQTT_BROKER_URI
         string "MQTT Broker URL"
+        depends on EXAMPLE_PEER_LIB_LIBJUICE
         default "mqtt://mqtt.eclipseprojects.io"
         help
             URL of the mqtt broker use for synchronisation and exchanging
             ICE connect info (description and candidates).
 
     config EXAMPLE_MQTT_SYNC_TOPIC
         string "MQTT topic for synchronisation"
+        depends on EXAMPLE_PEER_LIB_LIBJUICE
         default "/topic/serverless_mqtt"
         help
             MQTT topic used fo synchronisation.
 
     config EXAMPLE_STUN_SERVER
         string "Hostname of STUN server"
+        depends on EXAMPLE_PEER_LIB_LIBJUICE
         default "stun.l.google.com"
         help
             STUN server hostname.
@@ -67,6 +101,7 @@ menu "Example Configuration"
 
     choice EXAMPLE_SERVERLESS_ROLE
         prompt "Choose your role"
+        depends on EXAMPLE_PEER_LIB_LIBJUICE
         default EXAMPLE_SERVERLESS_ROLE_PEER1
         help
             Choose either peer1 or peer2.

components/mosquitto/examples/serverless_mqtt/main/peer_impl.h

@@ -0,0 +1,18 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+#include <stdio.h>
+#include "esp_random.h"
+#include "esp_sleep.h"
+#include "mosq_broker.h"
+
+typedef void (*on_peer_recv_t)(const char *data, size_t size);
+
+esp_err_t peer_init(on_peer_recv_t cb);
+
+void peer_get_buffer(char ** buffer, size_t *buffer_len);
+
+void peer_send(char* data, size_t size);