From c64da254c91bf8a168033b3c4de2d5fadd3fa271 Mon Sep 17 00:00:00 2001 From: Me No Dev Date: Thu, 6 Nov 2025 16:38:12 +0200 Subject: [PATCH 01/23] feat(net): Add ETH handle to events and data to lost_ip (#11986) --- libraries/Ethernet/src/ETH.cpp | 3 +++ libraries/Network/src/NetworkEvents.h | 4 ++++ libraries/Network/src/NetworkInterface.cpp | 1 + 3 files changed, 8 insertions(+) diff --git a/libraries/Ethernet/src/ETH.cpp b/libraries/Ethernet/src/ETH.cpp index e1223ea446f..8d1e459030c 100644 --- a/libraries/Ethernet/src/ETH.cpp +++ b/libraries/Ethernet/src/ETH.cpp @@ -107,14 +107,17 @@ void ETHClass::_onEthEvent(int32_t event_id, void *event_data) { } else if (event_id == ETHERNET_EVENT_DISCONNECTED) { log_v("%s Disconnected", desc()); arduino_event.event_id = ARDUINO_EVENT_ETH_DISCONNECTED; + arduino_event.event_info.eth_disconnected = handle(); clearStatusBits(ESP_NETIF_CONNECTED_BIT | ESP_NETIF_HAS_IP_BIT | ESP_NETIF_HAS_LOCAL_IP6_BIT | ESP_NETIF_HAS_GLOBAL_IP6_BIT); } else if (event_id == ETHERNET_EVENT_START) { log_v("%s Started", desc()); arduino_event.event_id = ARDUINO_EVENT_ETH_START; + arduino_event.event_info.eth_started = handle(); setStatusBits(ESP_NETIF_STARTED_BIT); } else if (event_id == ETHERNET_EVENT_STOP) { log_v("%s Stopped", desc()); arduino_event.event_id = ARDUINO_EVENT_ETH_STOP; + arduino_event.event_info.eth_stopped = handle(); clearStatusBits( ESP_NETIF_STARTED_BIT | ESP_NETIF_CONNECTED_BIT | ESP_NETIF_HAS_IP_BIT | ESP_NETIF_HAS_LOCAL_IP6_BIT | ESP_NETIF_HAS_GLOBAL_IP6_BIT | ESP_NETIF_HAS_STATIC_IP_BIT diff --git a/libraries/Network/src/NetworkEvents.h b/libraries/Network/src/NetworkEvents.h index 34a54cab092..e82d6a5dfb4 100644 --- a/libraries/Network/src/NetworkEvents.h +++ b/libraries/Network/src/NetworkEvents.h @@ -99,9 +99,13 @@ typedef enum { typedef union { ip_event_ap_staipassigned_t wifi_ap_staipassigned; ip_event_got_ip_t got_ip; + ip_event_got_ip_t lost_ip; ip_event_got_ip6_t got_ip6; #if CONFIG_ETH_ENABLED + esp_eth_handle_t eth_started; + esp_eth_handle_t eth_stopped; esp_eth_handle_t eth_connected; + esp_eth_handle_t eth_disconnected; #endif #if SOC_WIFI_SUPPORTED || CONFIG_ESP_WIFI_REMOTE_ENABLED wifi_event_sta_scan_done_t wifi_scan_done; diff --git a/libraries/Network/src/NetworkInterface.cpp b/libraries/Network/src/NetworkInterface.cpp index 969ec77b907..94675e65e12 100644 --- a/libraries/Network/src/NetworkInterface.cpp +++ b/libraries/Network/src/NetworkInterface.cpp @@ -97,6 +97,7 @@ void NetworkInterface::_onIpEvent(int32_t event_id, void *event_data) { #if ARDUHAL_LOG_LEVEL >= ARDUHAL_LOG_LEVEL_VERBOSE log_v("%s Lost IP", desc()); #endif + memcpy(&arduino_event.event_info.lost_ip, event_data, sizeof(ip_event_got_ip_t)); #if SOC_WIFI_SUPPORTED || CONFIG_ESP_WIFI_REMOTE_ENABLED if (_interface_id == ESP_NETIF_ID_STA) { arduino_event.event_id = ARDUINO_EVENT_WIFI_STA_LOST_IP; From 513507d3e770ebb89db8fb1f4d5bd47701032a44 Mon Sep 17 00:00:00 2001 From: Me No Dev Date: Thu, 6 Nov 2025 16:38:38 +0200 Subject: [PATCH 02/23] fix(ppp): Fix PPP.end() causing exception (#11987) * fix(ppp): Fix PPP.end() causing exception * fix(periman): Return NULL if deinit callback is cleared --- cores/esp32/esp32-hal-periman.c | 19 +++++++++++++++++++ cores/esp32/esp32-hal-periman.h | 3 +++ libraries/PPP/src/PPP.cpp | 18 ++++++++++++++---- 3 files changed, 36 insertions(+), 4 deletions(-) diff --git a/cores/esp32/esp32-hal-periman.c b/cores/esp32/esp32-hal-periman.c index 2ba8ffde5f7..bec88b0fdeb 100644 --- a/cores/esp32/esp32-hal-periman.c +++ b/cores/esp32/esp32-hal-periman.c @@ -236,11 +236,30 @@ bool perimanSetBusDeinit(peripheral_bus_type_t type, peripheral_bus_deinit_cb_t return true; } +// This no-op callback is used by perimanClearBusDeinit() to effectively disable bus deinit functionality +// without setting the callback to NULL, which would cause errors in perimanSetPinBus() at line 146. +static bool empty_bus_deinit_cb(void *bus) { + return true; +} + +bool perimanClearBusDeinit(peripheral_bus_type_t type) { + if (type >= ESP32_BUS_TYPE_MAX || type == ESP32_BUS_TYPE_INIT) { + log_e("Invalid type: %s (%u)", perimanGetTypeName(type), (unsigned int)type); + return false; + } + deinit_functions[type] = empty_bus_deinit_cb; + log_v("Deinit function for type %s (%u) cleared", perimanGetTypeName(type), (unsigned int)type); + return true; +} + peripheral_bus_deinit_cb_t perimanGetBusDeinit(peripheral_bus_type_t type) { if (type >= ESP32_BUS_TYPE_MAX || type == ESP32_BUS_TYPE_INIT) { log_e("Invalid type: %s (%u)", perimanGetTypeName(type), (unsigned int)type); return NULL; } + if (deinit_functions[type] == empty_bus_deinit_cb) { + return NULL; + } return deinit_functions[type]; } diff --git a/cores/esp32/esp32-hal-periman.h b/cores/esp32/esp32-hal-periman.h index 08b8c791ea7..12563718e19 100644 --- a/cores/esp32/esp32-hal-periman.h +++ b/cores/esp32/esp32-hal-periman.h @@ -134,6 +134,9 @@ int8_t perimanGetPinBusChannel(uint8_t pin); // Sets the peripheral destructor callback. Used to destroy bus when pin is assigned another function bool perimanSetBusDeinit(peripheral_bus_type_t type, peripheral_bus_deinit_cb_t cb); +// Clears the peripheral destructor callback +bool perimanClearBusDeinit(peripheral_bus_type_t type); + // Get the peripheral destructor callback. It allows changing/restoring the peripheral pin function detaching, if necessary // returns NULL if none is set peripheral_bus_deinit_cb_t perimanGetBusDeinit(peripheral_bus_type_t type); diff --git a/libraries/PPP/src/PPP.cpp b/libraries/PPP/src/PPP.cpp index 5e713bc84b0..76c5fad0d78 100644 --- a/libraries/PPP/src/PPP.cpp +++ b/libraries/PPP/src/PPP.cpp @@ -394,6 +394,11 @@ void PPPClass::end(void) { Network.postEvent(&arduino_event); } + if (_dce != NULL) { + esp_modem_destroy(_dce); + _dce = NULL; + } + destroyNetif(); if (_ppp_ev_instance != NULL) { @@ -406,10 +411,10 @@ void PPPClass::end(void) { Network.removeEvent(_ppp_event_handle); _ppp_event_handle = 0; - if (_dce != NULL) { - esp_modem_destroy(_dce); - _dce = NULL; - } + perimanClearBusDeinit(ESP32_BUS_TYPE_PPP_TX); + perimanClearBusDeinit(ESP32_BUS_TYPE_PPP_RX); + perimanClearBusDeinit(ESP32_BUS_TYPE_PPP_RTS); + perimanClearBusDeinit(ESP32_BUS_TYPE_PPP_CTS); int8_t pin = -1; if (_pin_tx != -1) { @@ -438,6 +443,11 @@ void PPPClass::end(void) { perimanClearPinBus(pin); } + perimanSetBusDeinit(ESP32_BUS_TYPE_PPP_TX, PPPClass::pppDetachBus); + perimanSetBusDeinit(ESP32_BUS_TYPE_PPP_RX, PPPClass::pppDetachBus); + perimanSetBusDeinit(ESP32_BUS_TYPE_PPP_RTS, PPPClass::pppDetachBus); + perimanSetBusDeinit(ESP32_BUS_TYPE_PPP_CTS, PPPClass::pppDetachBus); + _mode = ESP_MODEM_MODE_COMMAND; } From ef3a7f4870ed9e05448f0336e81c7dc0dd232a54 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Thu, 6 Nov 2025 11:39:05 -0300 Subject: [PATCH 03/23] fix(matter): IDF 5.4 CI error with ESP_OpenThread Include (#11988) * fix(matter): IDF 5.4 CI error with ESP_OpenThread Include * fix(matter): CMakeLists.txt simplification * fix(matter): minimum Arduino Core version to 3.1.0 * fix(matter): forcing openthread disabled - testing Added configuration to disable Matter over Thread. * fix(matter): enforces ESP Matter 1.3 * fix(matter): roll back change * fix(matter): adjust matter version * fix(matter): reverses changes * fix(matter): reverse changes * fix(matter): fixing versions * fix(matter): fixes matter and arduino versions Removed idf dependency version from YAML. * fix(matter): esp_matter version to 1.3.1 * fix(matter): guards secondary network interface creation * fix(matter): adds public requirement for esp_matter * fix(matter): set esp_matter dependency version to 1.3.0 * feat(matter): removes very old esp_matter_light example This examples is outdated. * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- .../esp_matter_light/CMakeLists.txt | 28 -- .../esp_matter_light/README.md | 124 ------ .../esp_matter_light/ci.yml | 8 - .../esp_matter_light/main/CMakeLists.txt | 5 - .../esp_matter_light/main/Kconfig.projbuild | 42 -- .../esp_matter_light/main/builtinLED.cpp | 237 ----------- .../esp_matter_light/main/builtinLED.h | 74 ---- .../esp_matter_light/main/idf_component.yml | 12 - .../main/matter_accessory_driver.cpp | 89 ---- .../main/matter_accessory_driver.h | 47 --- .../esp_matter_light/main/matter_light.cpp | 384 ------------------ .../esp_matter_light/partitions.csv | 10 - .../esp_matter_light/sdkconfig.defaults | 67 --- .../sdkconfig.defaults.c6_thread | 79 ---- .../sdkconfig.defaults.esp32c6 | 16 - libraries/Matter/src/MatterEndPoint.cpp | 7 + 16 files changed, 7 insertions(+), 1222 deletions(-) delete mode 100644 idf_component_examples/esp_matter_light/CMakeLists.txt delete mode 100644 idf_component_examples/esp_matter_light/README.md delete mode 100644 idf_component_examples/esp_matter_light/ci.yml delete mode 100644 idf_component_examples/esp_matter_light/main/CMakeLists.txt delete mode 100644 idf_component_examples/esp_matter_light/main/Kconfig.projbuild delete mode 100644 idf_component_examples/esp_matter_light/main/builtinLED.cpp delete mode 100644 idf_component_examples/esp_matter_light/main/builtinLED.h delete mode 100644 idf_component_examples/esp_matter_light/main/idf_component.yml delete mode 100644 idf_component_examples/esp_matter_light/main/matter_accessory_driver.cpp delete mode 100644 idf_component_examples/esp_matter_light/main/matter_accessory_driver.h delete mode 100644 idf_component_examples/esp_matter_light/main/matter_light.cpp delete mode 100644 idf_component_examples/esp_matter_light/partitions.csv delete mode 100644 idf_component_examples/esp_matter_light/sdkconfig.defaults delete mode 100644 idf_component_examples/esp_matter_light/sdkconfig.defaults.c6_thread delete mode 100644 idf_component_examples/esp_matter_light/sdkconfig.defaults.esp32c6 diff --git a/idf_component_examples/esp_matter_light/CMakeLists.txt b/idf_component_examples/esp_matter_light/CMakeLists.txt deleted file mode 100644 index 1430df8ff78..00000000000 --- a/idf_component_examples/esp_matter_light/CMakeLists.txt +++ /dev/null @@ -1,28 +0,0 @@ -# The following 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.5) - -set(PROJECT_VER "1.0") -set(PROJECT_VER_NUMBER 1) - -# This should be done before using the IDF_TARGET variable. -include($ENV{IDF_PATH}/tools/cmake/project.cmake) - -idf_build_set_property(MINIMAL_BUILD ON) -project(arduino_managed_component_light) - -# WARNING: This is just an example for using key for decrypting the encrypted OTA image -# Please do not use it as is. -if(CONFIG_ENABLE_ENCRYPTED_OTA) - target_add_binary_data(light.elf "esp_image_encryption_key.pem" TEXT) -endif() - -if(CONFIG_IDF_TARGET_ESP32C2) - include(relinker) -endif() - -idf_build_set_property(CXX_COMPILE_OPTIONS "-std=gnu++2a;-Os;-DCHIP_HAVE_CONFIG_H" APPEND) -idf_build_set_property(C_COMPILE_OPTIONS "-Os" APPEND) -# For RISCV chips, project_include.cmake sets -Wno-format, but does not clear various -# flags that depend on -Wformat -idf_build_set_property(COMPILE_OPTIONS "-Wno-format-nonliteral;-Wno-format-security" APPEND) diff --git a/idf_component_examples/esp_matter_light/README.md b/idf_component_examples/esp_matter_light/README.md deleted file mode 100644 index b0173f6a437..00000000000 --- a/idf_component_examples/esp_matter_light/README.md +++ /dev/null @@ -1,124 +0,0 @@ -| Supported Targets | ESP32-S3 | ESP32-C3 | ESP32-C6 | -| ----------------- | -------- | -------- | -------- | - - -# Managed Component Light - -This example sets automatically the RGB LED GPIO and BOOT Button GPIO based on the default pin used by the selected Devkit Board. - -This example creates a Color Temperature Light device using the esp_matter component downloaded from the [Espressif Component Registry](https://components.espressif.com/) instead of an extra component locally, so the example can work without setting up the esp-matter environment. - -Read the [documentation](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) for more information about building and flashing the firmware. - -The code is based on the Arduino API and uses Arduino as an IDF Component. - -## How to use it - -Once the device runs for the first time, it must be commissioned to the Matter Fabric of the available Matter Environment. -Possible Matter Environments are: -- Amazon Alexa -- Google Home Assistant (*) -- Apple Home -- Open Source Home Assistant - -(*) Google Home Assistant requires the user to set up a Matter Light using the [Google Home Developer Console](https://developers.home.google.com/codelabs/matter-device#2). It is necessary to create a Matter Light device with VID = 0xFFF1 and PID = 0x8000. Otherwise, the Light won't show up in the GHA APP. This action is necessary because the Firmware uses Testing credentials and Google requires the user to create the testing device before using it. - -**There is no QR Code** to be used when the Smartphone APP wants to add the Matter Device. -Please enter the code manually: `34970112332` - -Each Devkit Board has a built-in LED that will be used as the Matter Light. -The default setting for ESP32-S3 is pin 48, for ESP32-C3 and ESP32-C6, it is pin 8. -The BOOT Button pin of ESP32-S3 is GPIO 0, by toher hand, the ESP32-C3 and ESP32-C6 use GPIO 9. -Please change it in using the MenuConfig executing `idf.py menuconfig` and selecting `Menu->Light Matter Accessory` options. - -## LED Status and Factory Mode - -The WS2812b built-in LED will turn purple as soon as the device is flashed and runs for the first time. -The purple color indicates that the Matter Accessory has not been commissioned yet. -After using a Matter provider Smartphone APP to add a Matter device to your Home Application, it may turn orange to indicate that it has no Wi-Fi connection. - -Once it connects to the Wi-Fi network, the LED will turn white to indicate that Matter is working and the device is connected to the Matter Environment. -Please note that Matter over Wi-Fi using an ESP32 device will connect to a 2.4 GHz Wi-Fi SSID, therefore the Commissioner APP Smartphone shall be connected to this SSID. - -The Matter and Wi-Fi configuration will be stored in NVS to ensure that it will connect to the Matter Fabric and Wi-Fi Network again once it is reset. - -The Matter Smartphone APP will control the light state (ON/OFF), temperature (Warm/Cold White), and brightness. - -## On Board Light toggle button - -The built-in BOOT button will toggle On/Off and replicate the new state to the Matter Environment, making it visible in the Matter Smartphone APP as well. - -## Returning to the Factory State - -Holding the BOOT button pressed for more than 10 seconds and then releasing it will erase all Matter and Wi-Fi configuration, forcing it to reset to factory state. After that, the device needs to be commissioned again. -Previous setups done in the Smartphone APP won't work again; therefore, the virtual device shall be removed from the APP. - -## Building the Application using Wi-Fi and Matter - -Use ESP-IDF 5.1.4 from https://github.com/espressif/esp-idf/tree/release/v5.1 -This example has been tested with Arduino Core 3.0.4 - -The project will download all necessary components, including the Arduino Core. -Execute this sequence: - ` using linux rm command or Windows rmdir command` - `idf.py set-target ` - `idf.py -D SDKCONFIG_DEFAULTS="sdkconfig_file1;sdkconfig_file2;sdkconfig_fileX" -p flash monitor` - -Example for ESP32-S3/Linux | macOS: -``` -rm -rf build -idf.py set-target esp32s3 -idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults" -p /dev/ttyACM0 flash monitor -``` -Example for ESP32-C3/Windows: -``` -rmdir /s/q build -idf.py set-target esp32c3 -idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults" -p com3 flash monitor -``` - -It may be necessary to delete some folders and files before running `idf.py` -- Linux/macOS: - ``` - rm -rf build managed_components sdkconfig dependencies.lock - ``` -- Windows: - ``` - rmdir /s/q build managed_components && del sdkconfig dependencies.lock - ``` - -There is a configuration file for these SoC: esp32s3, esp32c3, esp32c6. -Those are the tested devices that have a WS2812 RGB LED and can run BLE, Wi-Fi and Matter. - -In case it is necessary to change the Button Pin or the REG LED Pin, please use the `menuconfig` -`idf.py menuconfig` and change the Menu Option `Light Matter Accessory` - -## Building the Application using OpenThread and Matter - -This is possible with the ESP32-C6. -It is necessary to have a Thread Border Router in the Matter Environment. -Check your Matter hardware provider. -In order to build the application that will use Thread Networking instead of Wi-Fi, please execute: - -Example for ESP32-C6/Linux | macOS: -``` -rm -rf build -idf.py set-target esp32c6 -idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.c6_thread" -p /dev/ttyACM0 flash monitor -``` -Example for ESP32-C6/Windows: -``` -rmdir /s/q build -idf.py set-targt esp32c6 -idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.c6_thread" -p com3 flash monitor -``` - -It may be necessary to delete some folders and files before running `idf.py` -- Linux/macOS - ``` - rm -rf build managed_components sdkconfig dependencies.lock - ``` -- Windows - ``` - rmdir /s/q build managed_components && del sdkconfig dependencies.lock - ``` diff --git a/idf_component_examples/esp_matter_light/ci.yml b/idf_component_examples/esp_matter_light/ci.yml deleted file mode 100644 index 4eee72b8c3b..00000000000 --- a/idf_component_examples/esp_matter_light/ci.yml +++ /dev/null @@ -1,8 +0,0 @@ -targets: - esp32c2: false - esp32s2: false - -requires: - - CONFIG_SOC_WIFI_SUPPORTED=y - - CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y - - CONFIG_MBEDTLS_HKDF_C=y diff --git a/idf_component_examples/esp_matter_light/main/CMakeLists.txt b/idf_component_examples/esp_matter_light/main/CMakeLists.txt deleted file mode 100644 index 6b91a8cf510..00000000000 --- a/idf_component_examples/esp_matter_light/main/CMakeLists.txt +++ /dev/null @@ -1,5 +0,0 @@ -idf_component_register(SRC_DIRS "." - INCLUDE_DIRS ".") - -set_property(TARGET ${COMPONENT_LIB} PROPERTY CXX_STANDARD 17) -target_compile_options(${COMPONENT_LIB} PRIVATE "-DCHIP_HAVE_CONFIG_H") diff --git a/idf_component_examples/esp_matter_light/main/Kconfig.projbuild b/idf_component_examples/esp_matter_light/main/Kconfig.projbuild deleted file mode 100644 index 3e0a35c5e15..00000000000 --- a/idf_component_examples/esp_matter_light/main/Kconfig.projbuild +++ /dev/null @@ -1,42 +0,0 @@ -menu "Light Matter Accessory" - menu "On Board Light ON/OFF Button" - config BUTTON_PIN - int - prompt "Button 1 GPIO" - default 9 if IDF_TARGET_ESP32C3 || IDF_TARGET_ESP32C6 - default 0 - range -1 ENV_GPIO_IN_RANGE_MAX - help - The GPIO pin for button that will be used to turn on/off the Matter Light. It shall be connected to a push button. It can use the BOOT button of the development board. - endmenu - - menu "LEDs" - config WS2812_PIN - int - prompt "WS2812 RGB LED GPIO" - default 8 if IDF_TARGET_ESP32C3 || IDF_TARGET_ESP32C6 - default 48 - range -1 ENV_GPIO_OUT_RANGE_MAX - help - The GPIO pin for the Matter Light that will be driven by RMT. It shall be connected to one single WS2812 RGB LED. - endmenu - - config ENV_GPIO_RANGE_MIN - int - default 0 - - config ENV_GPIO_RANGE_MAX - int - default 19 if IDF_TARGET_ESP32C3 - default 30 if IDF_TARGET_ESP32C6 - default 48 - - config ENV_GPIO_IN_RANGE_MAX - int - default ENV_GPIO_RANGE_MAX - - config ENV_GPIO_OUT_RANGE_MAX - int - default ENV_GPIO_RANGE_MAX - -endmenu diff --git a/idf_component_examples/esp_matter_light/main/builtinLED.cpp b/idf_component_examples/esp_matter_light/main/builtinLED.cpp deleted file mode 100644 index 8795dde2756..00000000000 --- a/idf_component_examples/esp_matter_light/main/builtinLED.cpp +++ /dev/null @@ -1,237 +0,0 @@ -/* - This example code is in the Public Domain (or CC0 licensed, at your option.) - Unless required by applicable law or agreed to in writing, this - software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR - CONDITIONS OF ANY KIND, either express or implied. - This will implement the onboard WS2812b LED as a LED indicator - It can be used to indicate some state or status of the device - The LED can be controlled using RGB, HSV or color temperature, brightness - - In this example, the LED Indicator class is used as the Matter light accessory -*/ - -#include "builtinLED.h" - -typedef struct { - uint16_t hue; - uint8_t saturation; -} HS_color_t; - -static const HS_color_t temperatureTable[] = { - {4, 100}, {8, 100}, {11, 100}, {14, 100}, {16, 100}, {18, 100}, {20, 100}, {22, 100}, {24, 100}, {25, 100}, {27, 100}, {28, 100}, {30, 100}, {31, 100}, - {31, 95}, {30, 89}, {30, 85}, {29, 80}, {29, 76}, {29, 73}, {29, 69}, {28, 66}, {28, 63}, {28, 60}, {28, 57}, {28, 54}, {28, 52}, {27, 49}, - {27, 47}, {27, 45}, {27, 43}, {27, 41}, {27, 39}, {27, 37}, {27, 35}, {27, 33}, {27, 31}, {27, 30}, {27, 28}, {27, 26}, {27, 25}, {27, 23}, - {27, 22}, {27, 21}, {27, 19}, {27, 18}, {27, 17}, {27, 15}, {28, 14}, {28, 13}, {28, 12}, {29, 10}, {29, 9}, {30, 8}, {31, 7}, {32, 6}, - {34, 5}, {36, 4}, {41, 3}, {49, 2}, {0, 0}, {294, 2}, {265, 3}, {251, 4}, {242, 5}, {237, 6}, {233, 7}, {231, 8}, {229, 9}, {228, 10}, - {227, 11}, {226, 11}, {226, 12}, {225, 13}, {225, 13}, {224, 14}, {224, 14}, {224, 15}, {224, 15}, {223, 16}, {223, 16}, {223, 17}, {223, 17}, {223, 17}, - {222, 18}, {222, 18}, {222, 19}, {222, 19}, {222, 19}, {222, 19}, {222, 20}, {222, 20}, {222, 20}, {222, 21}, {222, 21} -}; - -/* step brightness table: gamma = 2.3 */ -static const uint8_t gamma_table[MAX_PROGRESS] = { - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, - 1, 1, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 4, 4, 4, 4, 4, 5, 5, 5, 6, 6, 6, 6, 7, 7, 7, 8, - 8, 8, 9, 9, 9, 10, 10, 10, 11, 11, 12, 12, 13, 13, 13, 14, 14, 15, 15, 16, 16, 17, 17, 18, 18, 19, 19, 20, 20, - 21, 22, 22, 23, 23, 24, 25, 25, 26, 26, 27, 28, 28, 29, 30, 30, 31, 32, 33, 33, 34, 35, 36, 36, 37, 38, 39, 40, 40, - 41, 42, 43, 44, 45, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, - 69, 70, 71, 72, 74, 75, 76, 77, 78, 79, 81, 82, 83, 84, 86, 87, 88, 89, 91, 92, 93, 95, 96, 97, 99, 100, 101, 103, 104, - 105, 107, 108, 110, 111, 112, 114, 115, 117, 118, 120, 121, 123, 124, 126, 128, 129, 131, 132, 134, 135, 137, 139, 140, 142, 144, 145, 147, 149, - 150, 152, 154, 156, 157, 159, 161, 163, 164, 166, 168, 170, 172, 174, 175, 177, 179, 181, 183, 185, 187, 189, 191, 193, 195, 197, 199, 201, 203, - 205, 207, 209, 211, 213, 215, 217, 219, 221, 223, 226, 228, 230, 232, 234, 236, 239, 241, 243, 245, 248, 250, 252, 255, -}; - -BuiltInLED::BuiltInLED() { - pin_number = (uint8_t)-1; // no pin number - state = false; // LED is off - hsv_color.value = 0; // black color -} - -BuiltInLED::~BuiltInLED() { - end(); -} - -led_indicator_color_hsv_t BuiltInLED::rgb2hsv(led_indicator_color_rgb_t rgb) { - led_indicator_color_hsv_t hsv; - uint8_t minRGB, maxRGB; - uint8_t delta; - - minRGB = rgb.r < rgb.g ? (rgb.r < rgb.b ? rgb.r : rgb.b) : (rgb.g < rgb.b ? rgb.g : rgb.b); - maxRGB = rgb.r > rgb.g ? (rgb.r > rgb.b ? rgb.r : rgb.b) : (rgb.g > rgb.b ? rgb.g : rgb.b); - hsv.value = 0; - hsv.v = maxRGB; - delta = maxRGB - minRGB; - - if (delta == 0) { - hsv.h = 0; - hsv.s = 0; - } else { - hsv.s = delta * 255 / maxRGB; - - if (rgb.r == maxRGB) { - hsv.h = (60 * (rgb.g - rgb.b) / delta + 360) % 360; - } else if (rgb.g == maxRGB) { - hsv.h = (60 * (rgb.b - rgb.r) / delta + 120); - } else { - hsv.h = (60 * (rgb.r - rgb.g) / delta + 240); - } - } - return hsv; -} - -led_indicator_color_rgb_t BuiltInLED::hsv2rgb(led_indicator_color_hsv_t hsv) { - led_indicator_color_rgb_t rgb; - uint8_t rgb_max = hsv.v; - uint8_t rgb_min = rgb_max * (255 - hsv.s) / 255.0f; - - uint8_t i = hsv.h / 60; - uint8_t diff = hsv.h % 60; - - // RGB adjustment amount by hue - uint8_t rgb_adj = (rgb_max - rgb_min) * diff / 60; - rgb.value = 0; - switch (i) { - case 0: - rgb.r = rgb_max; - rgb.g = rgb_min + rgb_adj; - rgb.b = rgb_min; - break; - case 1: - rgb.r = rgb_max - rgb_adj; - rgb.g = rgb_max; - rgb.b = rgb_min; - break; - case 2: - rgb.r = rgb_min; - rgb.g = rgb_max; - rgb.b = rgb_min + rgb_adj; - break; - case 3: - rgb.r = rgb_min; - rgb.g = rgb_max - rgb_adj; - rgb.b = rgb_max; - break; - case 4: - rgb.r = rgb_min + rgb_adj; - rgb.g = rgb_min; - rgb.b = rgb_max; - break; - default: - rgb.r = rgb_max; - rgb.g = rgb_min; - rgb.b = rgb_max - rgb_adj; - break; - } - - // gamma correction - rgb.r = gamma_table[rgb.r]; - rgb.g = gamma_table[rgb.g]; - rgb.b = gamma_table[rgb.b]; - return rgb; -} - -void BuiltInLED::begin(uint8_t pin) { - if (pin < NUM_DIGITAL_PINS) { - pin_number = pin; - log_i("Initializing pin %d", pin); - } else { - log_e("Invalid pin (%d) number", pin); - } -} -void BuiltInLED::end() { - state = false; - write(); // turn off the LED - if (pin_number < NUM_DIGITAL_PINS) { - if (!rmtDeinit(pin_number)) { - log_e("Failed to deinitialize RMT"); - } - } -} - -void BuiltInLED::on() { - state = true; -} - -void BuiltInLED::off() { - state = false; -} - -void BuiltInLED::toggle() { - state = !state; -} - -bool BuiltInLED::getState() { - return state; -} - -bool BuiltInLED::write() { - led_indicator_color_rgb_t rgb_color = getRGB(); - log_d("Writing to pin %d with state = %s", pin_number, state ? "ON" : "OFF"); - log_d("HSV: %d, %d, %d", hsv_color.h, hsv_color.s, hsv_color.v); - log_d("RGB: %d, %d, %d", rgb_color.r, rgb_color.g, rgb_color.b); - if (pin_number < NUM_DIGITAL_PINS) { - if (state) { - rgbLedWrite(pin_number, rgb_color.r, rgb_color.g, rgb_color.b); - } else { - rgbLedWrite(pin_number, 0, 0, 0); - } - return true; - } else { - log_e("Invalid pin (%d) number", pin_number); - return false; - } -} - -void BuiltInLED::setBrightness(uint8_t brightness) { - hsv_color.v = brightness; -} - -uint8_t BuiltInLED::getBrightness() { - return hsv_color.v; -} - -void BuiltInLED::setHSV(led_indicator_color_hsv_t hsv) { - if (hsv.h > MAX_HUE) { - hsv.h = MAX_HUE; - } - hsv_color.value = hsv.value; -} - -led_indicator_color_hsv_t BuiltInLED::getHSV() { - return hsv_color; -} - -void BuiltInLED::setRGB(led_indicator_color_rgb_t rgb_color) { - hsv_color = rgb2hsv(rgb_color); -} - -led_indicator_color_rgb_t BuiltInLED::getRGB() { - return hsv2rgb(hsv_color); -} - -void BuiltInLED::setTemperature(uint32_t temperature) { - uint16_t hue; - uint8_t saturation; - - log_d("Requested Temperature: %ld", temperature); - //hsv_color.v = gamma_table[((temperature >> 25) & 0x7F)]; - temperature &= 0xFFFFFF; - if (temperature < 600) { - hue = 0; - saturation = 100; - } else { - if (temperature > 10000) { - hue = 222; - saturation = 21 + (temperature - 10000) * 41 / 990000; - } else { - temperature -= 600; - temperature /= 100; - hue = temperatureTable[temperature].hue; - saturation = temperatureTable[temperature].saturation; - } - } - saturation = (saturation * 255) / 100; - // brightness is not changed - hsv_color.h = hue; - hsv_color.s = saturation; - log_d("Calculated Temperature: %ld, Hue: %d, Saturation: %d, Brightness: %d", temperature, hue, saturation, hsv_color.v); -} diff --git a/idf_component_examples/esp_matter_light/main/builtinLED.h b/idf_component_examples/esp_matter_light/main/builtinLED.h deleted file mode 100644 index 1ca8c935569..00000000000 --- a/idf_component_examples/esp_matter_light/main/builtinLED.h +++ /dev/null @@ -1,74 +0,0 @@ -/* - This example code is in the Public Domain (or CC0 licensed, at your option.) - Unless required by applicable law or agreed to in writing, this - software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR - CONDITIONS OF ANY KIND, either express or implied. - This will implement the onboard WS2812b LED as a LED indicator - It can be used to indicate some state or status of the device - The LED can be controlled using RGB, HSV or color temperature, brightness - - In this example, the BuiltInLED class is used as the Matter light accessory -*/ - -#pragma once - -#include - -#define MAX_HUE 360 -#define MAX_SATURATION 255 -#define MAX_BRIGHTNESS 255 -#define MAX_PROGRESS 256 - -typedef struct { - union { - struct { - uint32_t v : 8; /*!< Brightness/Value of the LED. 0-255 */ - uint32_t s : 8; /*!< Saturation of the LED. 0-255 */ - uint32_t h : 9; /*!< Hue of the LED. 0-360 */ - }; - uint32_t value; /*!< IHSV value of the LED. */ - }; -} led_indicator_color_hsv_t; - -typedef struct { - union { - struct { - uint32_t r : 8; /*!< Red component of the LED color. Range: 0-255. */ - uint32_t g : 8; /*!< Green component of the LED color. Range: 0-255. */ - uint32_t b : 8; /*!< Blue component of the LED color. Range: 0-255. */ - }; - uint32_t value; /*!< Combined RGB value of the LED color. */ - }; -} led_indicator_color_rgb_t; - -class BuiltInLED { -private: - uint8_t pin_number; - bool state; - led_indicator_color_hsv_t hsv_color; - -public: - BuiltInLED(); - ~BuiltInLED(); - - static led_indicator_color_hsv_t rgb2hsv(led_indicator_color_rgb_t rgb_value); - static led_indicator_color_rgb_t hsv2rgb(led_indicator_color_hsv_t hsv); - - void begin(uint8_t pin); - void end(); - - void on(); - void off(); - void toggle(); - bool getState(); - - bool write(); - - void setBrightness(uint8_t brightness); - uint8_t getBrightness(); - void setHSV(led_indicator_color_hsv_t hsv); - led_indicator_color_hsv_t getHSV(); - void setRGB(led_indicator_color_rgb_t color); - led_indicator_color_rgb_t getRGB(); - void setTemperature(uint32_t temperature); -}; diff --git a/idf_component_examples/esp_matter_light/main/idf_component.yml b/idf_component_examples/esp_matter_light/main/idf_component.yml deleted file mode 100644 index e0286324591..00000000000 --- a/idf_component_examples/esp_matter_light/main/idf_component.yml +++ /dev/null @@ -1,12 +0,0 @@ -dependencies: - espressif/esp_matter: - version: ">=1.3.0" - # Adds Arduino Core from GitHub repository using main branch - espressif/arduino-esp32: - version: ">=3.0.5" - override_path: "../../../" - pre_release: true - - # testing - using Arduino from the repository - # version: "master" # branch or commit - # git: https://github.com/espressif/arduino-esp32.git diff --git a/idf_component_examples/esp_matter_light/main/matter_accessory_driver.cpp b/idf_component_examples/esp_matter_light/main/matter_accessory_driver.cpp deleted file mode 100644 index 523c38e6855..00000000000 --- a/idf_component_examples/esp_matter_light/main/matter_accessory_driver.cpp +++ /dev/null @@ -1,89 +0,0 @@ -/* - This example code is in the Public Domain (or CC0 licensed, at your option.) - Unless required by applicable law or agreed to in writing, this - software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR - CONDITIONS OF ANY KIND, either express or implied. -*/ -#include -#include -#include -#include "builtinLED.h" -#include "matter_accessory_driver.h" - -/* Do any conversions/remapping for the actual value here */ -esp_err_t light_accessory_set_power(void *led, uint8_t val) { - BuiltInLED *builtinLED = (BuiltInLED *)led; - esp_err_t err = ESP_OK; - if (val) { - builtinLED->on(); - } else { - builtinLED->off(); - } - if (!builtinLED->write()) { - err = ESP_FAIL; - } - log_i("LED set power: %d", val); - return err; -} - -esp_err_t light_accessory_set_brightness(void *led, uint8_t val) { - esp_err_t err = ESP_OK; - BuiltInLED *builtinLED = (BuiltInLED *)led; - int value = REMAP_TO_RANGE(val, MATTER_BRIGHTNESS, STANDARD_BRIGHTNESS); - - builtinLED->setBrightness(value); - if (!builtinLED->write()) { - err = ESP_FAIL; - } - log_i("LED set brightness: %d", value); - return err; -} - -esp_err_t light_accessory_set_hue(void *led, uint8_t val) { - esp_err_t err = ESP_OK; - BuiltInLED *builtinLED = (BuiltInLED *)led; - int value = REMAP_TO_RANGE(val, MATTER_HUE, STANDARD_HUE); - led_indicator_color_hsv_t hsv = builtinLED->getHSV(); - hsv.h = value; - builtinLED->setHSV(hsv); - if (!builtinLED->write()) { - err = ESP_FAIL; - } - log_i("LED set hue: %d", value); - return err; -} - -esp_err_t light_accessory_set_saturation(void *led, uint8_t val) { - esp_err_t err = ESP_OK; - BuiltInLED *builtinLED = (BuiltInLED *)led; - int value = REMAP_TO_RANGE(val, MATTER_SATURATION, STANDARD_SATURATION); - led_indicator_color_hsv_t hsv = builtinLED->getHSV(); - hsv.s = value; - builtinLED->setHSV(hsv); - if (!builtinLED->write()) { - err = ESP_FAIL; - } - log_i("LED set saturation: %d", value); - return err; -} - -esp_err_t light_accessory_set_temperature(void *led, uint16_t val) { - esp_err_t err = ESP_OK; - BuiltInLED *builtinLED = (BuiltInLED *)led; - uint32_t value = REMAP_TO_RANGE_INVERSE(val, STANDARD_TEMPERATURE_FACTOR); - builtinLED->setTemperature(value); - if (!builtinLED->write()) { - err = ESP_FAIL; - } - log_i("LED set temperature: %ld", value); - return err; -} - -app_driver_handle_t light_accessory_init() { - /* Initialize led */ - static BuiltInLED builtinLED; - - const uint8_t pin = WS2812_PIN; // set your board WS2812b pin here - builtinLED.begin(pin); - return (app_driver_handle_t)&builtinLED; -} diff --git a/idf_component_examples/esp_matter_light/main/matter_accessory_driver.h b/idf_component_examples/esp_matter_light/main/matter_accessory_driver.h deleted file mode 100644 index 3bf6655ab16..00000000000 --- a/idf_component_examples/esp_matter_light/main/matter_accessory_driver.h +++ /dev/null @@ -1,47 +0,0 @@ -#include -#include - -// set your board WS2812b pin here (e.g. 48 is the default pin for the ESP32-S3 devkit) -#ifndef CONFIG_WS2812_PIN -#define WS2812_PIN 48 // ESP32-S3 DevKitC built-in LED -#else -#define WS2812_PIN CONFIG_WS2812_PIN // From sdkconfig.defaults. -#endif - -#ifndef RGB_BUILTIN -#define RGB_BUILTIN WS2812_PIN -#endif - -// Set your board button pin here (e.g. 0 is the default pin for the ESP32-S3 devkit) -#ifndef CONFIG_BUTTON_PIN -#define BUTTON_PIN 0 // ESP32-S3 DevKitC built-in button -#else -#define BUTTON_PIN CONFIG_BUTTON_PIN // From sdkconfig.defaults. -#endif - -/** Standard max values (used for remapping attributes) */ -#define STANDARD_BRIGHTNESS 255 -#define STANDARD_HUE 360 -#define STANDARD_SATURATION 255 -#define STANDARD_TEMPERATURE_FACTOR 1000000 - -/** Matter max values (used for remapping attributes) */ -#define MATTER_BRIGHTNESS 254 -#define MATTER_HUE 254 -#define MATTER_SATURATION 254 -#define MATTER_TEMPERATURE_FACTOR 1000000 - -/** Default attribute values used during initialization */ -#define DEFAULT_POWER true -#define DEFAULT_BRIGHTNESS 64 -#define DEFAULT_HUE 128 -#define DEFAULT_SATURATION 254 - -typedef void *app_driver_handle_t; - -esp_err_t light_accessory_set_power(void *led, uint8_t val); -esp_err_t light_accessory_set_brightness(void *led, uint8_t val); -esp_err_t light_accessory_set_hue(void *led, uint8_t val); -esp_err_t light_accessory_set_saturation(void *led, uint8_t val); -esp_err_t light_accessory_set_temperature(void *led, uint16_t val); -app_driver_handle_t light_accessory_init(); diff --git a/idf_component_examples/esp_matter_light/main/matter_light.cpp b/idf_component_examples/esp_matter_light/main/matter_light.cpp deleted file mode 100644 index 6079ce46add..00000000000 --- a/idf_component_examples/esp_matter_light/main/matter_light.cpp +++ /dev/null @@ -1,384 +0,0 @@ -/* - This example code is in the Public Domain (or CC0 licensed, at your option.) - Unless required by applicable law or agreed to in writing, this - software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR - CONDITIONS OF ANY KIND, either express or implied. -*/ -#include -#include "matter_accessory_driver.h" - -#include - -#include -#include -#include - -#include -#include - -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD -#include -#include "esp_openthread_types.h" - -#define ESP_OPENTHREAD_DEFAULT_RADIO_CONFIG() \ - { .radio_mode = RADIO_MODE_NATIVE, } - -#define ESP_OPENTHREAD_DEFAULT_HOST_CONFIG() \ - { .host_connection_mode = HOST_CONNECTION_MODE_NONE, } - -#define ESP_OPENTHREAD_DEFAULT_PORT_CONFIG() \ - { .storage_partition_name = "nvs", .netif_queue_size = 10, .task_queue_size = 10, } -#endif - -// set your board button pin here -const uint8_t button_gpio = BUTTON_PIN; // GPIO BOOT Button - -uint16_t light_endpoint_id = 0; - -using namespace esp_matter; -using namespace esp_matter::attribute; -using namespace esp_matter::endpoint; -using namespace chip::app::Clusters; - -constexpr auto k_timeout_seconds = 300; - -#if CONFIG_ENABLE_ENCRYPTED_OTA -extern const char decryption_key_start[] asm("_binary_esp_image_encryption_key_pem_start"); -extern const char decryption_key_end[] asm("_binary_esp_image_encryption_key_pem_end"); - -static const char *s_decryption_key = decryption_key_start; -static const uint16_t s_decryption_key_len = decryption_key_end - decryption_key_start; -#endif // CONFIG_ENABLE_ENCRYPTED_OTA - -bool isAccessoryCommissioned() { - return chip::Server::GetInstance().GetFabricTable().FabricCount() > 0; -} - -#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION -bool isWifiConnected() { - return chip::DeviceLayer::ConnectivityMgr().IsWiFiStationConnected(); -} -#endif - -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD -bool isThreadConnected() { - return chip::DeviceLayer::ConnectivityMgr().IsThreadAttached(); -} -#endif - -static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg) { - switch (event->Type) { - case chip::DeviceLayer::DeviceEventType::kInterfaceIpAddressChanged: - log_i( - "Interface %s Address changed", event->InterfaceIpAddressChanged.Type == chip::DeviceLayer::InterfaceIpChangeType::kIpV4_Assigned ? "IPv4" : "IPV6" - ); - break; - - case chip::DeviceLayer::DeviceEventType::kCommissioningComplete: log_i("Commissioning complete"); break; - - case chip::DeviceLayer::DeviceEventType::kFailSafeTimerExpired: log_i("Commissioning failed, fail safe timer expired"); break; - - case chip::DeviceLayer::DeviceEventType::kCommissioningSessionStarted: log_i("Commissioning session started"); break; - - case chip::DeviceLayer::DeviceEventType::kCommissioningSessionStopped: log_i("Commissioning session stopped"); break; - - case chip::DeviceLayer::DeviceEventType::kCommissioningWindowOpened: log_i("Commissioning window opened"); break; - - case chip::DeviceLayer::DeviceEventType::kCommissioningWindowClosed: log_i("Commissioning window closed"); break; - - case chip::DeviceLayer::DeviceEventType::kFabricRemoved: - { - log_i("Fabric removed successfully"); - if (chip::Server::GetInstance().GetFabricTable().FabricCount() == 0) { - chip::CommissioningWindowManager &commissionMgr = chip::Server::GetInstance().GetCommissioningWindowManager(); - constexpr auto kTimeoutSeconds = chip::System::Clock::Seconds16(k_timeout_seconds); - if (!commissionMgr.IsCommissioningWindowOpen()) { - /* After removing last fabric, this example does not remove the Wi-Fi credentials - * and still has IP connectivity so, only advertising on DNS-SD. - */ - CHIP_ERROR err = commissionMgr.OpenBasicCommissioningWindow(kTimeoutSeconds, chip::CommissioningWindowAdvertisement::kDnssdOnly); - if (err != CHIP_NO_ERROR) { - log_e("Failed to open commissioning window, err:%" CHIP_ERROR_FORMAT, err.Format()); - } - } - } - break; - } - - case chip::DeviceLayer::DeviceEventType::kFabricWillBeRemoved: log_i("Fabric will be removed"); break; - - case chip::DeviceLayer::DeviceEventType::kFabricUpdated: log_i("Fabric is updated"); break; - - case chip::DeviceLayer::DeviceEventType::kFabricCommitted: log_i("Fabric is committed"); break; - - case chip::DeviceLayer::DeviceEventType::kBLEDeinitialized: log_i("BLE deinitialized and memory reclaimed"); break; - - default: break; - } -} - -esp_err_t matter_light_attribute_update( - app_driver_handle_t driver_handle, uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *val -) { - esp_err_t err = ESP_OK; - if (endpoint_id == light_endpoint_id) { - void *led = (void *)driver_handle; - if (cluster_id == OnOff::Id) { - if (attribute_id == OnOff::Attributes::OnOff::Id) { - err = light_accessory_set_power(led, val->val.b); - } - } else if (cluster_id == LevelControl::Id) { - if (attribute_id == LevelControl::Attributes::CurrentLevel::Id) { - err = light_accessory_set_brightness(led, val->val.u8); - } - } else if (cluster_id == ColorControl::Id) { - if (attribute_id == ColorControl::Attributes::CurrentHue::Id) { - err = light_accessory_set_hue(led, val->val.u8); - } else if (attribute_id == ColorControl::Attributes::CurrentSaturation::Id) { - err = light_accessory_set_saturation(led, val->val.u8); - } else if (attribute_id == ColorControl::Attributes::ColorTemperatureMireds::Id) { - err = light_accessory_set_temperature(led, val->val.u16); - } - } - } - return err; -} - -esp_err_t matter_light_set_defaults(uint16_t endpoint_id) { - esp_err_t err = ESP_OK; - - void *led = endpoint::get_priv_data(endpoint_id); - node_t *node = node::get(); - endpoint_t *endpoint = endpoint::get(node, endpoint_id); - cluster_t *cluster = NULL; - attribute_t *attribute = NULL; - esp_matter_attr_val_t val = esp_matter_invalid(NULL); - - /* Setting brightness */ - cluster = cluster::get(endpoint, LevelControl::Id); - attribute = attribute::get(cluster, LevelControl::Attributes::CurrentLevel::Id); - attribute::get_val(attribute, &val); - err |= light_accessory_set_brightness(led, val.val.u8); - - /* Setting color */ - cluster = cluster::get(endpoint, ColorControl::Id); - attribute = attribute::get(cluster, ColorControl::Attributes::ColorMode::Id); - attribute::get_val(attribute, &val); - if (val.val.u8 == (uint8_t)ColorControl::ColorMode::kCurrentHueAndCurrentSaturation) { - /* Setting hue */ - attribute = attribute::get(cluster, ColorControl::Attributes::CurrentHue::Id); - attribute::get_val(attribute, &val); - err |= light_accessory_set_hue(led, val.val.u8); - /* Setting saturation */ - attribute = attribute::get(cluster, ColorControl::Attributes::CurrentSaturation::Id); - attribute::get_val(attribute, &val); - err |= light_accessory_set_saturation(led, val.val.u8); - } else if (val.val.u8 == (uint8_t)ColorControl::ColorMode::kColorTemperature) { - /* Setting temperature */ - attribute = attribute::get(cluster, ColorControl::Attributes::ColorTemperatureMireds::Id); - attribute::get_val(attribute, &val); - err |= light_accessory_set_temperature(led, val.val.u16); - } else { - log_e("Color mode not supported"); - } - - /* Setting power */ - cluster = cluster::get(endpoint, OnOff::Id); - attribute = attribute::get(cluster, OnOff::Attributes::OnOff::Id); - attribute::get_val(attribute, &val); - err |= light_accessory_set_power(led, val.val.b); - - return err; -} - -void button_driver_init() { - /* Initialize button */ - pinMode(button_gpio, INPUT_PULLUP); -} - -// This callback is called for every attribute update. The callback implementation shall -// handle the desired attributes and return an appropriate error code. If the attribute -// is not of your interest, please do not return an error code and strictly return ESP_OK. -static esp_err_t app_attribute_update_cb( - attribute::callback_type_t type, uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *val, void *priv_data -) { - esp_err_t err = ESP_OK; - - if (type == PRE_UPDATE) { - /* Driver update */ - app_driver_handle_t driver_handle = (app_driver_handle_t)priv_data; - err = matter_light_attribute_update(driver_handle, endpoint_id, cluster_id, attribute_id, val); - } - - return err; -} - -// This callback is invoked when clients interact with the Identify Cluster. -// In the callback implementation, an endpoint can identify itself. (e.g., by flashing an LED or light). -static esp_err_t app_identification_cb(identification::callback_type_t type, uint16_t endpoint_id, uint8_t effect_id, uint8_t effect_variant, void *priv_data) { - log_i("Identification callback: type: %u, effect: %u, variant: %u", type, effect_id, effect_variant); - return ESP_OK; -} - -void setup() { - esp_err_t err = ESP_OK; - - /* Initialize driver */ - app_driver_handle_t light_handle = light_accessory_init(); - button_driver_init(); - - /* Create a Matter node and add the mandatory Root Node device type on endpoint 0 */ - node::config_t node_config; - - // node handle can be used to add/modify other endpoints. - node_t *node = node::create(&node_config, app_attribute_update_cb, app_identification_cb); - if (node == nullptr) { - log_e("Failed to create Matter node"); - abort(); - } - - extended_color_light::config_t light_config; - light_config.on_off.on_off = DEFAULT_POWER; - light_config.on_off.lighting.start_up_on_off = nullptr; - light_config.level_control.current_level = DEFAULT_BRIGHTNESS; - light_config.level_control.lighting.start_up_current_level = DEFAULT_BRIGHTNESS; - light_config.color_control.color_mode = (uint8_t)ColorControl::ColorMode::kColorTemperature; - light_config.color_control.enhanced_color_mode = (uint8_t)ColorControl::ColorMode::kColorTemperature; - light_config.color_control.color_temperature.startup_color_temperature_mireds = nullptr; - - // endpoint handles can be used to add/modify clusters. - endpoint_t *endpoint = extended_color_light::create(node, &light_config, ENDPOINT_FLAG_NONE, light_handle); - if (endpoint == nullptr) { - log_e("Failed to create extended color light endpoint"); - abort(); - } - - light_endpoint_id = endpoint::get_id(endpoint); - log_i("Light created with endpoint_id %d", light_endpoint_id); - - /* Mark deferred persistence for some attributes that might be changed rapidly */ - cluster_t *level_control_cluster = cluster::get(endpoint, LevelControl::Id); - attribute_t *current_level_attribute = attribute::get(level_control_cluster, LevelControl::Attributes::CurrentLevel::Id); - attribute::set_deferred_persistence(current_level_attribute); - - cluster_t *color_control_cluster = cluster::get(endpoint, ColorControl::Id); - attribute_t *current_x_attribute = attribute::get(color_control_cluster, ColorControl::Attributes::CurrentX::Id); - attribute::set_deferred_persistence(current_x_attribute); - attribute_t *current_y_attribute = attribute::get(color_control_cluster, ColorControl::Attributes::CurrentY::Id); // codespell:ignore - attribute::set_deferred_persistence(current_y_attribute); - attribute_t *color_temp_attribute = attribute::get(color_control_cluster, ColorControl::Attributes::ColorTemperatureMireds::Id); - attribute::set_deferred_persistence(color_temp_attribute); - -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD - /* Set OpenThread platform config */ - esp_openthread_platform_config_t config = { - .radio_config = ESP_OPENTHREAD_DEFAULT_RADIO_CONFIG(), - .host_config = ESP_OPENTHREAD_DEFAULT_HOST_CONFIG(), - .port_config = ESP_OPENTHREAD_DEFAULT_PORT_CONFIG(), - }; - set_openthread_platform_config(&config); -#endif - - /* Matter start */ - err = esp_matter::start(app_event_cb); - if (err != ESP_OK) { - log_e("Failed to start Matter, err:%d", err); - abort(); - } - -#if CONFIG_ENABLE_ENCRYPTED_OTA - err = esp_matter_ota_requestor_encrypted_init(s_decryption_key, s_decryption_key_len); - if (err != ESP_OK) { - log_e("Failed to initialized the encrypted OTA, err: %d", err); - abort(); - } -#endif // CONFIG_ENABLE_ENCRYPTED_OTA - -#if CONFIG_ENABLE_CHIP_SHELL - esp_matter::console::diagnostics_register_commands(); - esp_matter::console::wifi_register_commands(); -#if CONFIG_OPENTHREAD_CLI - esp_matter::console::otcli_register_commands(); -#endif - esp_matter::console::init(); -#endif -} - -void loop() { - static uint32_t button_time_stamp = 0; - static bool button_state = false; - static bool started = false; - - if (!isAccessoryCommissioned()) { - log_w("Accessory not commissioned yet. Waiting for commissioning."); -#ifdef RGB_BUILTIN - rgbLedWrite(RGB_BUILTIN, 48, 0, 20); // Purple indicates accessory not commissioned -#endif - delay(5000); - return; - } - -#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION - if (!isWifiConnected()) { - log_w("Wi-Fi not connected yet. Waiting for connection."); -#ifdef RGB_BUILTIN - rgbLedWrite(RGB_BUILTIN, 48, 20, 0); // Orange indicates accessory not connected to Wi-Fi -#endif - delay(5000); - return; - } -#endif - -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD - if (!isThreadConnected()) { - log_w("Thread not connected yet. Waiting for connection."); -#ifdef RGB_BUILTIN - rgbLedWrite(RGB_BUILTIN, 0, 20, 48); // Blue indicates accessory not connected to Trhead -#endif - delay(5000); - return; - } -#endif - - // Once all network connections are established, the accessory is ready for use - // Run it only once - if (!started) { - log_i("Accessory is commissioned and connected to Wi-Fi. Ready for use."); - started = true; - // Starting driver with default values - matter_light_set_defaults(light_endpoint_id); - } - - // Check if the button is pressed and toggle the light right away - if (digitalRead(button_gpio) == LOW && !button_state) { - // deals with button debounce - button_time_stamp = millis(); // record the time while the button is pressed. - button_state = true; // pressed. - - // Toggle button is pressed - toggle the light - log_i("Toggle button pressed"); - - endpoint_t *endpoint = endpoint::get(node::get(), light_endpoint_id); - cluster_t *cluster = cluster::get(endpoint, OnOff::Id); - attribute_t *attribute = attribute::get(cluster, OnOff::Attributes::OnOff::Id); - - esp_matter_attr_val_t val = esp_matter_invalid(NULL); - attribute::get_val(attribute, &val); - val.val.b = !val.val.b; - attribute::update(light_endpoint_id, OnOff::Id, OnOff::Attributes::OnOff::Id, &val); - } - - // Check if the button is released and handle the factory reset - uint32_t time_diff = millis() - button_time_stamp; - if (button_state && time_diff > 100 && digitalRead(button_gpio) == HIGH) { - button_state = false; // released. It can be pressed again after 100ms debounce. - - // Factory reset is triggered if the button is pressed for more than 10 seconds - if (time_diff > 10000) { - log_i("Factory reset triggered. Light will restored to factory settings."); - esp_matter::factory_reset(); - } - } - - delay(50); // WDT is happier with a delay -} diff --git a/idf_component_examples/esp_matter_light/partitions.csv b/idf_component_examples/esp_matter_light/partitions.csv deleted file mode 100644 index ffe5f242e76..00000000000 --- a/idf_component_examples/esp_matter_light/partitions.csv +++ /dev/null @@ -1,10 +0,0 @@ -# Name, Type, SubType, Offset, Size, Flags -# Note: Firmware partition offset needs to be 64K aligned, initial 36K (9 sectors) are reserved for bootloader and partition table -esp_secure_cert, 0x3F, ,0xd000, 0x2000, encrypted -nvs, data, nvs, 0x10000, 0xC000, -nvs_keys, data, nvs_keys,, 0x1000, encrypted -otadata, data, ota, , 0x2000 -phy_init, data, phy, , 0x1000, -ota_0, app, ota_0, 0x20000, 0x1E0000, -ota_1, app, ota_1, 0x200000, 0x1E0000, -fctry, data, nvs, 0x3E0000, 0x6000 diff --git a/idf_component_examples/esp_matter_light/sdkconfig.defaults b/idf_component_examples/esp_matter_light/sdkconfig.defaults deleted file mode 100644 index 8688318fa36..00000000000 --- a/idf_component_examples/esp_matter_light/sdkconfig.defaults +++ /dev/null @@ -1,67 +0,0 @@ -# Arduino Settings -CONFIG_FREERTOS_HZ=1000 -CONFIG_AUTOSTART_ARDUINO=y - -# Log Levels -# Boot Messages - Log level -CONFIG_BOOTLOADER_LOG_LEVEL_ERROR=y -# Arduino Log Level -CONFIG_ARDUHAL_LOG_DEFAULT_LEVEL_INFO=y -# IDF Log Level -CONFIG_LOG_DEFAULT_LEVEL_ERROR=y - -# Default to 921600 baud when flashing and monitoring device -CONFIG_ESPTOOLPY_BAUD_921600B=y -CONFIG_ESPTOOLPY_BAUD=921600 -CONFIG_ESPTOOLPY_COMPRESSED=y -CONFIG_ESPTOOLPY_MONITOR_BAUD_115200B=y -CONFIG_ESPTOOLPY_MONITOR_BAUD=115200 -CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y - -#enable BT -CONFIG_BT_ENABLED=y -CONFIG_BT_NIMBLE_ENABLED=y - -#disable BT connection reattempt -CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT=n - -#enable lwip ipv6 autoconfig -CONFIG_LWIP_IPV6_AUTOCONFIG=y - -# Use a custom partition table -CONFIG_PARTITION_TABLE_CUSTOM=y -CONFIG_PARTITION_TABLE_FILENAME="partitions.csv" -CONFIG_PARTITION_TABLE_OFFSET=0xC000 - -# Disable chip shell -CONFIG_ENABLE_CHIP_SHELL=n - -# Enable OTA Requester -CONFIG_ENABLE_OTA_REQUESTOR=n - -#enable lwIP route hooks -CONFIG_LWIP_HOOK_IP6_ROUTE_DEFAULT=y -CONFIG_LWIP_HOOK_ND6_GET_GW_DEFAULT=y - -# disable softap by default -CONFIG_ESP_WIFI_SOFTAP_SUPPORT=n -CONFIG_ENABLE_WIFI_STATION=y -CONFIG_ENABLE_WIFI_AP=n - -# Disable DS Peripheral -CONFIG_ESP_SECURE_CERT_DS_PERIPHERAL=n - -# Use compact attribute storage mode -CONFIG_ESP_MATTER_NVS_USE_COMPACT_ATTR_STORAGE=y - -# Enable HKDF in mbedtls -CONFIG_MBEDTLS_HKDF_C=y - -# Increase LwIP IPv6 address number to 6 (MAX_FABRIC + 1) -# unique local addresses for fabrics(MAX_FABRIC), a link local address(1) -CONFIG_LWIP_IPV6_NUM_ADDRESSES=6 - -# -# DIAGNOSTICS -# -CONFIG_DIAG_USE_EXTERNAL_LOG_WRAP=y diff --git a/idf_component_examples/esp_matter_light/sdkconfig.defaults.c6_thread b/idf_component_examples/esp_matter_light/sdkconfig.defaults.c6_thread deleted file mode 100644 index 502480f94b1..00000000000 --- a/idf_component_examples/esp_matter_light/sdkconfig.defaults.c6_thread +++ /dev/null @@ -1,79 +0,0 @@ -CONFIG_IDF_TARGET="esp32c6" - -# Arduino Settings -CONFIG_FREERTOS_HZ=1000 -CONFIG_AUTOSTART_ARDUINO=y - -# Log Levels -# Boot Messages - Log level -CONFIG_BOOTLOADER_LOG_LEVEL_ERROR=y -# Arduino Log Level -CONFIG_ARDUHAL_LOG_DEFAULT_LEVEL_INFO=y -# IDF Log Level -CONFIG_LOG_DEFAULT_LEVEL_ERROR=y - -# Default to 921600 baud when flashing and monitoring device -CONFIG_ESPTOOLPY_BAUD_921600B=y -CONFIG_ESPTOOLPY_BAUD=921600 -CONFIG_ESPTOOLPY_COMPRESSED=y -CONFIG_ESPTOOLPY_MONITOR_BAUD_115200B=y -CONFIG_ESPTOOLPY_MONITOR_BAUD=115200 -CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y - -# libsodium -CONFIG_LIBSODIUM_USE_MBEDTLS_SHA=y - -# NIMBLE -CONFIG_BT_ENABLED=y -CONFIG_BT_NIMBLE_ENABLED=y -CONFIG_BT_NIMBLE_EXT_ADV=n -CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE=70 -CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING=n - -# FreeRTOS should use legacy API -CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY=y - -# Enable OpenThread -CONFIG_OPENTHREAD_ENABLED=y -CONFIG_OPENTHREAD_SRP_CLIENT=y -CONFIG_OPENTHREAD_DNS_CLIENT=y -CONFIG_OPENTHREAD_LOG_LEVEL_DYNAMIC=n -CONFIG_OPENTHREAD_LOG_LEVEL_NOTE=y -CONFIG_OPENTHREAD_CLI=n - -# Disable lwip ipv6 autoconfig -CONFIG_LWIP_IPV6_AUTOCONFIG=n - -# Use a custom partition table -CONFIG_PARTITION_TABLE_CUSTOM=y -CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" - -# LwIP config for OpenThread -CONFIG_LWIP_IPV6_NUM_ADDRESSES=8 -CONFIG_LWIP_MULTICAST_PING=y - -# MDNS platform -CONFIG_USE_MINIMAL_MDNS=n -CONFIG_ENABLE_EXTENDED_DISCOVERY=y - -# Enable OTA Requester -CONFIG_ENABLE_OTA_REQUESTOR=n - -# Disable STA and AP for ESP32C6 -CONFIG_ENABLE_WIFI_STATION=n -CONFIG_ENABLE_WIFI_AP=n - -# Enable chip shell -CONFIG_ENABLE_CHIP_SHELL=n - -# Disable persist subscriptions -CONFIG_ENABLE_PERSIST_SUBSCRIPTIONS=n - -# MRP configs -CONFIG_MRP_LOCAL_ACTIVE_RETRY_INTERVAL_FOR_THREAD=5000 -CONFIG_MRP_LOCAL_IDLE_RETRY_INTERVAL_FOR_THREAD=5000 -CONFIG_MRP_RETRY_INTERVAL_SENDER_BOOST_FOR_THREAD=5000 -CONFIG_MRP_MAX_RETRANS=3 - -# Enable HKDF in mbedtls -CONFIG_MBEDTLS_HKDF_C=y diff --git a/idf_component_examples/esp_matter_light/sdkconfig.defaults.esp32c6 b/idf_component_examples/esp_matter_light/sdkconfig.defaults.esp32c6 deleted file mode 100644 index 9fe589613ef..00000000000 --- a/idf_component_examples/esp_matter_light/sdkconfig.defaults.esp32c6 +++ /dev/null @@ -1,16 +0,0 @@ -CONFIG_IDF_TARGET="esp32c6" - -# libsodium -CONFIG_LIBSODIUM_USE_MBEDTLS_SHA=y - -# NIMBLE -CONFIG_BT_NIMBLE_EXT_ADV=n -CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE=70 -CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING=y - -# FreeRTOS should use legacy API -CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY=y - -# Use minimal mDNS -CONFIG_USE_MINIMAL_MDNS=y -CONFIG_ENABLE_EXTENDED_DISCOVERY=y diff --git a/libraries/Matter/src/MatterEndPoint.cpp b/libraries/Matter/src/MatterEndPoint.cpp index ecf1acff579..8ef1c5d63ba 100644 --- a/libraries/Matter/src/MatterEndPoint.cpp +++ b/libraries/Matter/src/MatterEndPoint.cpp @@ -27,6 +27,8 @@ bool MatterEndPoint::createSecondaryNetworkInterface() { log_v("Secondary network interface endpoint already exists with ID %d", secondary_network_endpoint_id); return false; } + +#if CHIP_DEVICE_CONFIG_ENABLE_THREAD && CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION // Create a secondary network interface endpoint endpoint::secondary_network_interface::config_t secondary_network_interface_config; secondary_network_interface_config.network_commissioning.feature_map = chip::to_underlying( @@ -40,6 +42,11 @@ bool MatterEndPoint::createSecondaryNetworkInterface() { } secondary_network_endpoint_id = endpoint::get_id(endpoint); log_i("Secondary Network Interface created with endpoint_id %d", secondary_network_endpoint_id); +#else + log_i("Secondary Network Interface not supported"); + return false; +#endif + return true; } From 731aee27927442ad3b591ee31e6fcfbfa0a10971 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Thu, 6 Nov 2025 11:39:34 -0300 Subject: [PATCH 04/23] fix(matter): Update ESP Border to ESP Thread in diagram (#11989) --- docs/en/matter/matter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/matter/matter.rst b/docs/en/matter/matter.rst index 7ed1afaeac6..7fd3cc9ee2e 100644 --- a/docs/en/matter/matter.rst +++ b/docs/en/matter/matter.rst @@ -35,7 +35,7 @@ Matter Network Topology .. code-block:: text ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ - │ Matter Hub │◄─────►│ Wi-Fi Router │◄─────►│ ESP Border │ + │ Matter Hub │◄─────►│ Wi-Fi Router │◄─────►│ ESP Thread │ │ (HomePod etc) │ │ │ │ Border Router │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ │ │ From 167fb6c43c3a9c1c5a51af57d3e28e9e3729f392 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Proch=C3=A1zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Fri, 7 Nov 2025 10:45:47 +0100 Subject: [PATCH 05/23] feat(zibgee): Add IASZone enroll request and restore + error check fixes (#11990) * feat(zibgee): Add requestIASZoneEnroll + error check fixes * fix: Spelling Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(zigbee): Remove transaction sequence logging * feat(zigbee): Add restoreIASZone from flash method * docs(zigbee): Add docs for new methods * feat(zigbee): Update checking logic * fix: Fix memcpy and update docs * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- docs/en/zigbee/ep_contact_switch.rst | 43 ++++++++++-- docs/en/zigbee/ep_door_window_handle.rst | 43 ++++++++++-- docs/en/zigbee/ep_vibration_sensor.rst | 37 +++++++++- .../Zigbee_Contact_Switch.ino | 40 ++++++++++- .../Zigbee_Vibration_Sensor.ino | 40 ++++++++++- libraries/Zigbee/keywords.txt | 3 + .../Zigbee/src/ep/ZigbeeContactSwitch.cpp | 70 +++++++++++++++---- libraries/Zigbee/src/ep/ZigbeeContactSwitch.h | 12 ++++ .../Zigbee/src/ep/ZigbeeDoorWindowHandle.cpp | 53 +++++++++++++- .../Zigbee/src/ep/ZigbeeDoorWindowHandle.h | 12 ++++ .../Zigbee/src/ep/ZigbeeVibrationSensor.cpp | 58 +++++++++++++-- .../Zigbee/src/ep/ZigbeeVibrationSensor.h | 14 +++- 12 files changed, 390 insertions(+), 35 deletions(-) diff --git a/docs/en/zigbee/ep_contact_switch.rst b/docs/en/zigbee/ep_contact_switch.rst index f7f6dc15c66..50844cdd180 100644 --- a/docs/en/zigbee/ep_contact_switch.rst +++ b/docs/en/zigbee/ep_contact_switch.rst @@ -63,6 +63,17 @@ Sets the contact switch to open state. This function will return ``true`` if successful, ``false`` otherwise. +report +^^^^^^ + +Manually reports the current contact state. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + setIASClientEndpoint ^^^^^^^^^^^^^^^^^^^^ @@ -74,16 +85,38 @@ Sets the IAS Client endpoint number (default is 1). * ``ep_number`` - IAS Client endpoint number -report -^^^^^^ +requestIASZoneEnroll +^^^^^^^^^^^^^^^^^^^^ -Manually reports the current contact state. +Requests a new IAS Zone enrollment. Can be called to enroll a new device or to re-enroll an already enrolled device. .. code-block:: arduino - bool report(); + bool requestIASZoneEnroll(); -This function will return ``true`` if successful, ``false`` otherwise. +This function will return ``true`` if the enrollment request was sent successfully, ``false`` otherwise. The actual enrollment status should be checked using the ``enrolled()`` method after waiting for the enrollment response. + +restoreIASZoneEnroll +^^^^^^^^^^^^^^^^^^^^ + +Restores IAS Zone enrollment from stored attributes. This method should be called after rebooting an already enrolled device. It restores the enrollment information from flash memory, which is faster for sleepy devices compared to requesting a new enrollment. + +.. code-block:: arduino + + bool restoreIASZoneEnroll(); + +This function will return ``true`` if the enrollment was successfully restored, ``false`` otherwise. The enrollment information (zone ID and IAS CIE address) must be available in the device's stored attributes for this to succeed. + +enrolled +^^^^^^^^ + +Checks if the device is currently enrolled in the IAS Zone. + +.. code-block:: arduino + + bool enrolled(); + +This function returns ``true`` if the device is enrolled, ``false`` otherwise. Use this method to check the enrollment status after calling ``requestIASZoneEnroll()`` or ``restoreIASZoneEnroll()``. Example ------- diff --git a/docs/en/zigbee/ep_door_window_handle.rst b/docs/en/zigbee/ep_door_window_handle.rst index 53203f463dd..b2339d681a5 100644 --- a/docs/en/zigbee/ep_door_window_handle.rst +++ b/docs/en/zigbee/ep_door_window_handle.rst @@ -67,6 +67,17 @@ Sets the door/window handle to tilted position. This function will return ``true`` if successful, ``false`` otherwise. +report +^^^^^^ + +Manually reports the current handle position. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + setIASClientEndpoint ^^^^^^^^^^^^^^^^^^^^ @@ -78,16 +89,38 @@ Sets the IAS Client endpoint number (default is 1). * ``ep_number`` - IAS Client endpoint number -report -^^^^^^ +requestIASZoneEnroll +^^^^^^^^^^^^^^^^^^^^ -Manually reports the current handle position. +Requests a new IAS Zone enrollment. Can be called to enroll a new device or to re-enroll an already enrolled device. .. code-block:: arduino - bool report(); + bool requestIASZoneEnroll(); -This function will return ``true`` if successful, ``false`` otherwise. +This function will return ``true`` if the enrollment request was sent successfully, ``false`` otherwise. The actual enrollment status should be checked using the ``enrolled()`` method after waiting for the enrollment response. + +restoreIASZoneEnroll +^^^^^^^^^^^^^^^^^^^^ + +Restores IAS Zone enrollment from stored attributes. This method should be called after rebooting an already enrolled device. It restores the enrollment information from flash memory, which is faster for sleepy devices compared to requesting a new enrollment. + +.. code-block:: arduino + + bool restoreIASZoneEnroll(); + +This function will return ``true`` if the enrollment was successfully restored, ``false`` otherwise. The enrollment information (zone ID and IAS CIE address) must be available in the device's stored attributes for this to succeed. + +enrolled +^^^^^^^^ + +Checks if the device is currently enrolled in the IAS Zone. + +.. code-block:: arduino + + bool enrolled(); + +This function returns ``true`` if the device is enrolled, ``false`` otherwise. Use this method to check the enrollment status after calling ``requestIASZoneEnroll()`` or ``restoreIASZoneEnroll()``. Example ------- diff --git a/docs/en/zigbee/ep_vibration_sensor.rst b/docs/en/zigbee/ep_vibration_sensor.rst index 896c4672c6d..d8ca3fdd5f4 100644 --- a/docs/en/zigbee/ep_vibration_sensor.rst +++ b/docs/en/zigbee/ep_vibration_sensor.rst @@ -73,9 +73,42 @@ Manually reports the current vibration state. .. code-block:: arduino - void report(); + bool report(); -This function does not return a value. +This function will return ``true`` if successful, ``false`` otherwise. + +requestIASZoneEnroll +^^^^^^^^^^^^^^^^^^^^ + +Requests a new IAS Zone enrollment. Can be called to enroll a new device or to re-enroll an already enrolled device. + +.. code-block:: arduino + + bool requestIASZoneEnroll(); + +This function will return ``true`` if the enrollment request was sent successfully, ``false`` otherwise. The actual enrollment status should be checked using the ``enrolled()`` method after waiting for the enrollment response. + +restoreIASZoneEnroll +^^^^^^^^^^^^^^^^^^^^ + +Restores IAS Zone enrollment from stored attributes. This method should be called after rebooting an already enrolled device. It restores the enrollment information from flash memory, which is faster for sleepy devices compared to requesting a new enrollment. + +.. code-block:: arduino + + bool restoreIASZoneEnroll(); + +This function will return ``true`` if the enrollment was successfully restored, ``false`` otherwise. The enrollment information (zone ID and IAS CIE address) must be available in the device's stored attributes for this to succeed. + +enrolled +^^^^^^^^ + +Checks if the device is currently enrolled in the IAS Zone. + +.. code-block:: arduino + + bool enrolled(); + +This function returns ``true`` if the device is enrolled, ``false`` otherwise. Use this method to check the enrollment status after calling ``requestIASZoneEnroll()`` or ``restoreIASZoneEnroll()``. Example ------- diff --git a/libraries/Zigbee/examples/Zigbee_Contact_Switch/Zigbee_Contact_Switch.ino b/libraries/Zigbee/examples/Zigbee_Contact_Switch/Zigbee_Contact_Switch.ino index ce9eedb683d..1a84c4d7471 100644 --- a/libraries/Zigbee/examples/Zigbee_Contact_Switch/Zigbee_Contact_Switch.ino +++ b/libraries/Zigbee/examples/Zigbee_Contact_Switch/Zigbee_Contact_Switch.ino @@ -31,17 +31,25 @@ #endif #include "Zigbee.h" +#include /* Zigbee contact sensor configuration */ -#define CONTACT_SWITCH_ENDPOINT_NUMBER 10 +#define CONTACT_SWITCH_ENDPOINT_NUMBER 1 uint8_t button = BOOT_PIN; uint8_t sensor_pin = 4; ZigbeeContactSwitch zbContactSwitch = ZigbeeContactSwitch(CONTACT_SWITCH_ENDPOINT_NUMBER); +/* Preferences for storing ENROLLED flag to persist across reboots */ +Preferences preferences; + void setup() { Serial.begin(115200); + preferences.begin("Zigbee", false); // Save ENROLLED flag in flash so it persists across reboots + bool enrolled = preferences.getBool("ENROLLED"); // Get ENROLLED flag from preferences + preferences.end(); + // Init button + switch pinMode(button, INPUT_PULLUP); pinMode(sensor_pin, INPUT_PULLUP); @@ -67,6 +75,31 @@ void setup() { delay(100); } Serial.println(); + + // Check if device has been enrolled before restarting - if so, restore IAS Zone enroll, otherwise request new IAS Zone enroll + if (enrolled) { + Serial.println("Device has been enrolled before - restoring IAS Zone enrollment"); + zbContactSwitch.restoreIASZoneEnroll(); + } else { + Serial.println("Device is factory new - first time joining network - requesting new IAS Zone enrollment"); + zbContactSwitch.requestIASZoneEnroll(); + } + + while (!zbContactSwitch.enrolled()) { + Serial.print("."); + delay(100); + } + Serial.println(); + Serial.println("Zigbee enrolled successfully!"); + + // Store ENROLLED flag only if this was a new enrollment (previous flag was false) + // Skip writing if we just restored enrollment (flag was already true) + if (!enrolled) { + preferences.begin("Zigbee", false); + preferences.putBool("ENROLLED", true); // set ENROLLED flag to true + preferences.end(); + Serial.println("ENROLLED flag saved to preferences"); + } } void loop() { @@ -91,6 +124,11 @@ void loop() { if ((millis() - startTime) > 3000) { // If key pressed for more than 3secs, factory reset Zigbee and reboot Serial.println("Resetting Zigbee to factory and rebooting in 1s."); + // Clear the ENROLLED flag from preferences + preferences.begin("Zigbee", false); + preferences.putBool("ENROLLED", false); // set ENROLLED flag to false + preferences.end(); + Serial.println("ENROLLED flag cleared from preferences"); delay(1000); Zigbee.factoryReset(); } diff --git a/libraries/Zigbee/examples/Zigbee_Vibration_Sensor/Zigbee_Vibration_Sensor.ino b/libraries/Zigbee/examples/Zigbee_Vibration_Sensor/Zigbee_Vibration_Sensor.ino index d9ac7b6e241..b3fc6b9d18b 100644 --- a/libraries/Zigbee/examples/Zigbee_Vibration_Sensor/Zigbee_Vibration_Sensor.ino +++ b/libraries/Zigbee/examples/Zigbee_Vibration_Sensor/Zigbee_Vibration_Sensor.ino @@ -31,17 +31,25 @@ #endif #include "Zigbee.h" +#include /* Zigbee vibration sensor configuration */ -#define VIBRATION_SENSOR_ENDPOINT_NUMBER 10 +#define VIBRATION_SENSOR_ENDPOINT_NUMBER 1 uint8_t button = BOOT_PIN; uint8_t sensor_pin = 4; ZigbeeVibrationSensor zbVibrationSensor = ZigbeeVibrationSensor(VIBRATION_SENSOR_ENDPOINT_NUMBER); +/* Preferences for storing ENROLLED flag to persist across reboots */ +Preferences preferences; + void setup() { Serial.begin(115200); + preferences.begin("Zigbee", false); // Save ENROLLED flag in flash so it persists across reboots + bool enrolled = preferences.getBool("ENROLLED"); // Get ENROLLED flag from preferences + preferences.end(); + // Init button + sensor pinMode(button, INPUT_PULLUP); pinMode(sensor_pin, INPUT); @@ -67,6 +75,31 @@ void setup() { delay(100); } Serial.println(); + + // Check if device has been enrolled before restarting - if so, restore IAS Zone enroll, otherwise request new IAS Zone enroll + if (enrolled) { + Serial.println("Device has been enrolled before - restoring IAS Zone enrollment"); + zbVibrationSensor.restoreIASZoneEnroll(); + } else { + Serial.println("Device is factory new - first time joining network - requesting new IAS Zone enrollment"); + zbVibrationSensor.requestIASZoneEnroll(); + } + + while (!zbVibrationSensor.enrolled()) { + Serial.print("."); + delay(100); + } + Serial.println(); + Serial.println("Zigbee enrolled successfully!"); + + // Store ENROLLED flag only if this was a new enrollment (previous flag was false) + // Skip writing if we just restored enrollment (flag was already true) + if (!enrolled) { + preferences.begin("Zigbee", false); + preferences.putBool("ENROLLED", true); // set ENROLLED flag to true + preferences.end(); + Serial.println("ENROLLED flag saved to preferences"); + } } void loop() { @@ -95,6 +128,11 @@ void loop() { if ((millis() - startTime) > 3000) { // If key pressed for more than 3secs, factory reset Zigbee and reboot Serial.println("Resetting Zigbee to factory and rebooting in 1s."); + // Clear the ENROLLED flag from preferences + preferences.begin("Zigbee", false); + preferences.putBool("ENROLLED", false); // set ENROLLED flag to false + preferences.end(); + Serial.println("ENROLLED flag cleared from preferences"); delay(1000); Zigbee.factoryReset(); } diff --git a/libraries/Zigbee/keywords.txt b/libraries/Zigbee/keywords.txt index 44067fc4886..c940d85d4d1 100644 --- a/libraries/Zigbee/keywords.txt +++ b/libraries/Zigbee/keywords.txt @@ -209,6 +209,9 @@ setIASClientEndpoint KEYWORD2 setClosed KEYWORD2 setOpen KEYWORD2 setTilted KEYWORD2 +requestIASZoneEnroll KEYWORD2 +restoreIASZoneEnroll KEYWORD2 +enrolled KEYWORD2 # ZigbeeVibrationSensor setVibration KEYWORD2 diff --git a/libraries/Zigbee/src/ep/ZigbeeContactSwitch.cpp b/libraries/Zigbee/src/ep/ZigbeeContactSwitch.cpp index 4142f87fe16..35e05afb290 100644 --- a/libraries/Zigbee/src/ep/ZigbeeContactSwitch.cpp +++ b/libraries/Zigbee/src/ep/ZigbeeContactSwitch.cpp @@ -31,6 +31,7 @@ ZigbeeContactSwitch::ZigbeeContactSwitch(uint8_t endpoint) : ZigbeeEP(endpoint) _zone_status = 0; _zone_id = 0xff; _ias_cie_endpoint = 1; + _enrolled = false; //Create custom contact switch configuration zigbee_contact_switch_cfg_t contact_switch_cfg = ZIGBEE_DEFAULT_CONTACT_SWITCH_CONFIG(); @@ -44,15 +45,16 @@ void ZigbeeContactSwitch::setIASClientEndpoint(uint8_t ep_number) { } bool ZigbeeContactSwitch::setClosed() { + esp_zb_zcl_status_t ret = ESP_ZB_ZCL_STATUS_SUCCESS; log_v("Setting Contact switch to closed"); uint8_t closed = 0; // ALARM1 = 0, ALARM2 = 0 esp_zb_lock_acquire(portMAX_DELAY); - esp_err_t ret = esp_zb_zcl_set_attribute_val( + ret = esp_zb_zcl_set_attribute_val( _endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_ZONESTATUS_ID, &closed, false ); esp_zb_lock_release(); - if (ret != ESP_OK) { - log_e("Failed to set contact switch to closed: 0x%x: %s", ret, esp_err_to_name(ret)); + if (ret != ESP_ZB_ZCL_STATUS_SUCCESS) { + log_e("Failed to set contact switch to closed: 0x%x: %s", ret, esp_zb_zcl_status_to_name(ret)); return false; } _zone_status = closed; @@ -60,15 +62,16 @@ bool ZigbeeContactSwitch::setClosed() { } bool ZigbeeContactSwitch::setOpen() { + esp_zb_zcl_status_t ret = ESP_ZB_ZCL_STATUS_SUCCESS; log_v("Setting Contact switch to open"); uint8_t open = ESP_ZB_ZCL_IAS_ZONE_ZONE_STATUS_ALARM1 | ESP_ZB_ZCL_IAS_ZONE_ZONE_STATUS_ALARM2; // ALARM1 = 1, ALARM2 = 1 esp_zb_lock_acquire(portMAX_DELAY); - esp_err_t ret = esp_zb_zcl_set_attribute_val( + ret = esp_zb_zcl_set_attribute_val( _endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_ZONESTATUS_ID, &open, false ); esp_zb_lock_release(); - if (ret != ESP_OK) { - log_e("Failed to set contact switch to open: 0x%x: %s", ret, esp_err_to_name(ret)); + if (ret != ESP_ZB_ZCL_STATUS_SUCCESS) { + log_e("Failed to set contact switch to open: 0x%x: %s", ret, esp_zb_zcl_status_to_name(ret)); return false; } _zone_status = open; @@ -90,12 +93,8 @@ bool ZigbeeContactSwitch::report() { status_change_notif_cmd.delay = 0; esp_zb_lock_acquire(portMAX_DELAY); - esp_err_t ret = esp_zb_zcl_ias_zone_status_change_notif_cmd_req(&status_change_notif_cmd); + esp_zb_zcl_ias_zone_status_change_notif_cmd_req(&status_change_notif_cmd); //return transaction sequence number, ignore it esp_zb_lock_release(); - if (ret != ESP_OK) { - log_e("Failed to send IAS Zone status changed notification: 0x%x: %s", ret, esp_err_to_name(ret)); - return false; - } log_v("IAS Zone status changed notification sent"); return true; } @@ -115,11 +114,58 @@ void ZigbeeContactSwitch::zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_enro ); esp_zb_lock_release(); _zone_id = message->zone_id; + _enrolled = true; } - } else { log_w("Received message ignored. Cluster ID: %d not supported for On/Off Light", message->info.cluster); } } +bool ZigbeeContactSwitch::requestIASZoneEnroll() { + esp_zb_zcl_ias_zone_enroll_request_cmd_t enroll_request; + enroll_request.zcl_basic_cmd.src_endpoint = _endpoint; + enroll_request.address_mode = ESP_ZB_APS_ADDR_MODE_DST_ADDR_ENDP_NOT_PRESENT; + enroll_request.zone_type = ESP_ZB_ZCL_IAS_ZONE_ZONETYPE_CONTACT_SWITCH; + enroll_request.manuf_code = 0; + + esp_zb_lock_acquire(portMAX_DELAY); + esp_zb_zcl_ias_zone_enroll_cmd_req(&enroll_request); //return transaction sequence number, ignore it + esp_zb_lock_release(); + log_v("IAS Zone enroll request sent"); + return true; +} + +bool ZigbeeContactSwitch::restoreIASZoneEnroll() { + esp_zb_lock_acquire(portMAX_DELAY); + esp_zb_zcl_attr_t *ias_cie_attr = + esp_zb_zcl_get_attribute(_endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_IAS_CIE_ADDRESS_ID); + esp_zb_zcl_attr_t *zone_id_attr = + esp_zb_zcl_get_attribute(_endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_ZONEID_ID); + esp_zb_lock_release(); + + if (ias_cie_attr == NULL || ias_cie_attr->data_p == NULL) { + log_e("Failed to restore IAS Zone enroll: ias cie address attribute not found"); + return false; + } + if (zone_id_attr == NULL || zone_id_attr->data_p == NULL) { + log_e("Failed to restore IAS Zone enroll: zone id attribute not found"); + return false; + } + + memcpy(_ias_cie_addr, (esp_zb_ieee_addr_t *)ias_cie_attr->data_p, sizeof(esp_zb_ieee_addr_t)); + _zone_id = (*(uint8_t *)zone_id_attr->data_p); + + log_d( + "Restored IAS Zone enroll: zone id(%d), ias cie address(%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X)", _zone_id, _ias_cie_addr[0], _ias_cie_addr[1], + _ias_cie_addr[2], _ias_cie_addr[3], _ias_cie_addr[4], _ias_cie_addr[5], _ias_cie_addr[6], _ias_cie_addr[7] + ); + + if (_zone_id == 0xFF) { + log_e("Failed to restore IAS Zone enroll: zone id not valid"); + return false; + } + _enrolled = true; + return true; +} + #endif // CONFIG_ZB_ENABLED diff --git a/libraries/Zigbee/src/ep/ZigbeeContactSwitch.h b/libraries/Zigbee/src/ep/ZigbeeContactSwitch.h index b3be38c3eb4..002ed722d78 100644 --- a/libraries/Zigbee/src/ep/ZigbeeContactSwitch.h +++ b/libraries/Zigbee/src/ep/ZigbeeContactSwitch.h @@ -70,12 +70,24 @@ class ZigbeeContactSwitch : public ZigbeeEP { // Report the contact switch value, done automatically after setting the position bool report(); + // Request a new IAS zone enroll, can be called to enroll a new device or to re-enroll an already enrolled device + bool requestIASZoneEnroll(); + + // Restore IAS Zone enroll, needed to be called after rebooting already enrolled device - restored from flash memory (faster for sleepy devices) + bool restoreIASZoneEnroll(); + + // Check if the device is enrolled in the IAS Zone + bool enrolled() { + return _enrolled; + } + private: void zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_enroll_response_message_t *message) override; uint8_t _zone_status; uint8_t _zone_id; esp_zb_ieee_addr_t _ias_cie_addr; uint8_t _ias_cie_endpoint; + bool _enrolled; }; #endif // CONFIG_ZB_ENABLED diff --git a/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.cpp b/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.cpp index 2ca032b01e5..2a3a5c80498 100644 --- a/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.cpp +++ b/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.cpp @@ -31,6 +31,7 @@ ZigbeeDoorWindowHandle::ZigbeeDoorWindowHandle(uint8_t endpoint) : ZigbeeEP(endp _zone_status = 0; _zone_id = 0xff; _ias_cie_endpoint = 1; + _enrolled = false; //Create custom door window handle configuration zigbee_door_window_handle_cfg_t door_window_handle_cfg = ZIGBEE_DEFAULT_DOOR_WINDOW_HANDLE_CONFIG(); @@ -108,9 +109,8 @@ bool ZigbeeDoorWindowHandle::report() { status_change_notif_cmd.zone_id = _zone_id; status_change_notif_cmd.delay = 0; - //NOTE: Check result of esp_zb_zcl_ias_zone_status_change_notif_cmd_req() and return true if success, false if failure esp_zb_lock_acquire(portMAX_DELAY); - esp_zb_zcl_ias_zone_status_change_notif_cmd_req(&status_change_notif_cmd); + esp_zb_zcl_ias_zone_status_change_notif_cmd_req(&status_change_notif_cmd); //return transaction sequence number, ignore it esp_zb_lock_release(); log_v("IAS Zone status changed notification sent"); return true; @@ -131,11 +131,58 @@ void ZigbeeDoorWindowHandle::zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_e ); esp_zb_lock_release(); _zone_id = message->zone_id; + _enrolled = true; } - } else { log_w("Received message ignored. Cluster ID: %d not supported for On/Off Light", message->info.cluster); } } +bool ZigbeeDoorWindowHandle::requestIASZoneEnroll() { + esp_zb_zcl_ias_zone_enroll_request_cmd_t enroll_request; + enroll_request.zcl_basic_cmd.src_endpoint = _endpoint; + enroll_request.address_mode = ESP_ZB_APS_ADDR_MODE_DST_ADDR_ENDP_NOT_PRESENT; + enroll_request.zone_type = ESP_ZB_ZCL_IAS_ZONE_ZONETYPE_DOOR_WINDOW_HANDLE; + enroll_request.manuf_code = 0; + + esp_zb_lock_acquire(portMAX_DELAY); + esp_zb_zcl_ias_zone_enroll_cmd_req(&enroll_request); //return transaction sequence number, ignore it + esp_zb_lock_release(); + log_v("IAS Zone enroll request sent"); + return true; +} + +bool ZigbeeDoorWindowHandle::restoreIASZoneEnroll() { + esp_zb_lock_acquire(portMAX_DELAY); + esp_zb_zcl_attr_t *ias_cie_attr = + esp_zb_zcl_get_attribute(_endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_IAS_CIE_ADDRESS_ID); + esp_zb_zcl_attr_t *zone_id_attr = + esp_zb_zcl_get_attribute(_endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_ZONEID_ID); + esp_zb_lock_release(); + + if (ias_cie_attr == NULL || ias_cie_attr->data_p == NULL) { + log_e("Failed to restore IAS Zone enroll: ias cie address attribute not found"); + return false; + } + if (zone_id_attr == NULL || zone_id_attr->data_p == NULL) { + log_e("Failed to restore IAS Zone enroll: zone id attribute not found"); + return false; + } + + memcpy(_ias_cie_addr, (esp_zb_ieee_addr_t *)ias_cie_attr->data_p, sizeof(esp_zb_ieee_addr_t)); + _zone_id = (*(uint8_t *)zone_id_attr->data_p); + + log_d( + "Restored IAS Zone enroll: zone id(%d), ias cie address(%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X)", _zone_id, _ias_cie_addr[0], _ias_cie_addr[1], + _ias_cie_addr[2], _ias_cie_addr[3], _ias_cie_addr[4], _ias_cie_addr[5], _ias_cie_addr[6], _ias_cie_addr[7] + ); + + if (_zone_id == 0xFF) { + log_e("Failed to restore IAS Zone enroll: zone id not valid"); + return false; + } + _enrolled = true; + return true; +} + #endif // CONFIG_ZB_ENABLED diff --git a/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.h b/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.h index d4a2d81eb39..cfaf7e772a0 100644 --- a/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.h +++ b/libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.h @@ -74,12 +74,24 @@ class ZigbeeDoorWindowHandle : public ZigbeeEP { // Report the door/window handle value, done automatically after setting the position bool report(); + // Request a new IAS zone enroll, can be called to enroll a new device or to re-enroll an already enrolled device + bool requestIASZoneEnroll(); + + // Restore IAS Zone enroll, needed to be called after rebooting already enrolled device - restored from flash memory (faster for sleepy devices) + bool restoreIASZoneEnroll(); + + // Check if the device is enrolled in the IAS Zone + bool enrolled() { + return _enrolled; + } + private: void zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_enroll_response_message_t *message) override; uint8_t _zone_status; uint8_t _zone_id; esp_zb_ieee_addr_t _ias_cie_addr; uint8_t _ias_cie_endpoint; + bool _enrolled; }; #endif // CONFIG_ZB_ENABLED diff --git a/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.cpp b/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.cpp index 218638ed3cb..a9fd437a2c6 100644 --- a/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.cpp +++ b/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.cpp @@ -31,6 +31,7 @@ ZigbeeVibrationSensor::ZigbeeVibrationSensor(uint8_t endpoint) : ZigbeeEP(endpoi _zone_status = 0; _zone_id = 0xff; _ias_cie_endpoint = 1; + _enrolled = false; //Create custom vibration sensor configuration zigbee_vibration_sensor_cfg_t vibration_sensor_cfg = ZIGBEE_DEFAULT_VIBRATION_SENSOR_CONFIG(); @@ -57,11 +58,10 @@ bool ZigbeeVibrationSensor::setVibration(bool sensed) { return false; } _zone_status = vibration; - report(); - return true; + return report(); } -void ZigbeeVibrationSensor::report() { +bool ZigbeeVibrationSensor::report() { /* Send IAS Zone status changed notification command */ esp_zb_zcl_ias_zone_status_change_notif_cmd_t status_change_notif_cmd; @@ -75,9 +75,10 @@ void ZigbeeVibrationSensor::report() { status_change_notif_cmd.delay = 0; esp_zb_lock_acquire(portMAX_DELAY); - esp_zb_zcl_ias_zone_status_change_notif_cmd_req(&status_change_notif_cmd); + esp_zb_zcl_ias_zone_status_change_notif_cmd_req(&status_change_notif_cmd); //return transaction sequence number, ignore it esp_zb_lock_release(); log_v("IAS Zone status changed notification sent"); + return true; } void ZigbeeVibrationSensor::zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_enroll_response_message_t *message) { @@ -95,11 +96,58 @@ void ZigbeeVibrationSensor::zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_en ); esp_zb_lock_release(); _zone_id = message->zone_id; + _enrolled = true; } - } else { log_w("Received message ignored. Cluster ID: %d not supported for On/Off Light", message->info.cluster); } } +bool ZigbeeVibrationSensor::requestIASZoneEnroll() { + esp_zb_zcl_ias_zone_enroll_request_cmd_t enroll_request; + enroll_request.zcl_basic_cmd.src_endpoint = _endpoint; + enroll_request.address_mode = ESP_ZB_APS_ADDR_MODE_DST_ADDR_ENDP_NOT_PRESENT; + enroll_request.zone_type = ESP_ZB_ZCL_IAS_ZONE_ZONETYPE_VIBRATION_MOVEMENT; + enroll_request.manuf_code = 0; + + esp_zb_lock_acquire(portMAX_DELAY); + esp_zb_zcl_ias_zone_enroll_cmd_req(&enroll_request); //return transaction sequence number, ignore it + esp_zb_lock_release(); + log_v("IAS Zone enroll request sent"); + return true; +} + +bool ZigbeeVibrationSensor::restoreIASZoneEnroll() { + esp_zb_lock_acquire(portMAX_DELAY); + esp_zb_zcl_attr_t *ias_cie_attr = + esp_zb_zcl_get_attribute(_endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_IAS_CIE_ADDRESS_ID); + esp_zb_zcl_attr_t *zone_id_attr = + esp_zb_zcl_get_attribute(_endpoint, ESP_ZB_ZCL_CLUSTER_ID_IAS_ZONE, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_IAS_ZONE_ZONEID_ID); + esp_zb_lock_release(); + + if (ias_cie_attr == NULL || ias_cie_attr->data_p == NULL) { + log_e("Failed to restore IAS Zone enroll: ias cie address attribute not found"); + return false; + } + if (zone_id_attr == NULL || zone_id_attr->data_p == NULL) { + log_e("Failed to restore IAS Zone enroll: zone id attribute not found"); + return false; + } + + memcpy(_ias_cie_addr, (esp_zb_ieee_addr_t *)ias_cie_attr->data_p, sizeof(esp_zb_ieee_addr_t)); + _zone_id = (*(uint8_t *)zone_id_attr->data_p); + + log_d( + "Restored IAS Zone enroll: zone id(%d), ias cie address(%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X)", _zone_id, _ias_cie_addr[0], _ias_cie_addr[1], + _ias_cie_addr[2], _ias_cie_addr[3], _ias_cie_addr[4], _ias_cie_addr[5], _ias_cie_addr[6], _ias_cie_addr[7] + ); + + if (_zone_id == 0xFF) { + log_e("Failed to restore IAS Zone enroll: zone id not valid"); + return false; + } + _enrolled = true; + return true; +} + #endif // CONFIG_ZB_ENABLED diff --git a/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.h b/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.h index 9757257b5c1..a819be0ba8f 100644 --- a/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.h +++ b/libraries/Zigbee/src/ep/ZigbeeVibrationSensor.h @@ -65,7 +65,18 @@ class ZigbeeVibrationSensor : public ZigbeeEP { bool setVibration(bool sensed); // Report the vibration sensor value, done automatically after setting the sensed value - void report(); + bool report(); + + // Request a new IAS zone enroll, can be called to enroll a new device or to re-enroll an already enrolled device + bool requestIASZoneEnroll(); + + // Restore IAS Zone enroll, needed to be called after rebooting already enrolled device - restored from flash memory (faster for sleepy devices) + bool restoreIASZoneEnroll(); + + // Check if the device is enrolled in the IAS Zone + bool enrolled() { + return _enrolled; + } private: void zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_enroll_response_message_t *message) override; @@ -73,6 +84,7 @@ class ZigbeeVibrationSensor : public ZigbeeEP { uint8_t _zone_id; esp_zb_ieee_addr_t _ias_cie_addr; uint8_t _ias_cie_endpoint; + bool _enrolled; }; #endif // CONFIG_ZB_ENABLED From 420adcec15824be02b610b9f5eb0643852496efc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Proch=C3=A1zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Fri, 7 Nov 2025 10:48:00 +0100 Subject: [PATCH 06/23] fix(sdmmc): Fix iomux pin initialization (#11998) --- libraries/SD_MMC/src/SD_MMC.cpp | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/libraries/SD_MMC/src/SD_MMC.cpp b/libraries/SD_MMC/src/SD_MMC.cpp index 2d840556c3e..12ab2b565eb 100644 --- a/libraries/SD_MMC/src/SD_MMC.cpp +++ b/libraries/SD_MMC/src/SD_MMC.cpp @@ -228,17 +228,19 @@ bool SDMMCFS::begin(const char *mountpoint, bool mode1bit, bool format_if_mount_ #if defined(CONFIG_IDF_TARGET_ESP32P4) && defined(BOARD_SDMMC_SLOT) && (BOARD_SDMMC_SLOT == 0) host.slot = SDMMC_HOST_SLOT_0; // reconfigure slot_config to remove all pins in order to use IO_MUX + // Use 0 instead of GPIO_NUM_NC (-1) because ESP-IDF's s_check_pin_not_set() + // function uses !pin which doesn't work correctly with -1 (GPIO_NUM_NC) slot_config = sdmmc_slot_config_t{ - .clk = GPIO_NUM_NC, - .cmd = GPIO_NUM_NC, - .d0 = GPIO_NUM_NC, - .d1 = GPIO_NUM_NC, - .d2 = GPIO_NUM_NC, - .d3 = GPIO_NUM_NC, - .d4 = GPIO_NUM_NC, - .d5 = GPIO_NUM_NC, - .d6 = GPIO_NUM_NC, - .d7 = GPIO_NUM_NC, + .clk = GPIO_NUM_0, + .cmd = GPIO_NUM_0, + .d0 = GPIO_NUM_0, + .d1 = GPIO_NUM_0, + .d2 = GPIO_NUM_0, + .d3 = GPIO_NUM_0, + .d4 = GPIO_NUM_0, + .d5 = GPIO_NUM_0, + .d6 = GPIO_NUM_0, + .d7 = GPIO_NUM_0, .cd = SDMMC_SLOT_NO_CD, .wp = SDMMC_SLOT_NO_WP, .width = 4, From 0ae08381ecc72aab3df07b0426fa0cb9f5b5132b Mon Sep 17 00:00:00 2001 From: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> Date: Fri, 7 Nov 2025 11:53:20 -0300 Subject: [PATCH 07/23] fix(ci): Fix IDF examples compilation when changing source files --- .github/scripts/get_affected.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.github/scripts/get_affected.py b/.github/scripts/get_affected.py index a7d993c4be3..136b4dc044b 100755 --- a/.github/scripts/get_affected.py +++ b/.github/scripts/get_affected.py @@ -790,6 +790,19 @@ def find_affected_sketches(changed_files: list[str]) -> None: print(f"Total affected sketches: {len(affected_sketches)}", file=sys.stderr) return + # For component mode: if any *source code* file (not example or documentation) changed, recompile all examples + if component_mode: + for file in changed_files: + if (is_source_file(file) or is_header_file(file)) and not file.endswith(".ino"): + if file.startswith("cores/") or file.startswith("libraries/"): + print("Component mode: file changed in cores/ or libraries/ - recompiling all IDF component examples", file=sys.stderr) + all_examples = list_idf_component_examples() + for example in all_examples: + if example not in affected_sketches: + affected_sketches.append(example) + print(f"Total affected IDF component examples: {len(affected_sketches)}", file=sys.stderr) + return + preprocess_changed_files(changed_files) # Normal dependency-based analysis for non-critical changes From 5521e02627fa6909818d7d12657b59814a506198 Mon Sep 17 00:00:00 2001 From: Me No Dev Date: Sun, 9 Nov 2025 16:56:25 +0200 Subject: [PATCH 08/23] feat(net): Add method Network.isOnline() (#12000) * feat(net): Add method Network.isOnline() * fix(net): Fix typo * feat(net): Check connection status in isOnline method --- libraries/Network/src/NetworkManager.cpp | 12 ++++++++++++ libraries/Network/src/NetworkManager.h | 3 +++ 2 files changed, 15 insertions(+) diff --git a/libraries/Network/src/NetworkManager.cpp b/libraries/Network/src/NetworkManager.cpp index 12276b2e242..a19cf52dd87 100644 --- a/libraries/Network/src/NetworkManager.cpp +++ b/libraries/Network/src/NetworkManager.cpp @@ -185,6 +185,18 @@ NetworkInterface *NetworkManager::getDefaultInterface() { return NULL; } +bool NetworkManager::isOnline() { + for (int i = 0; i < ESP_NETIF_ID_MAX; ++i) { + if (i != ESP_NETIF_ID_AP) { + NetworkInterface *iface = getNetifByID((Network_Interface_ID)i); + if (iface != NULL && iface->connected() && (iface->hasIP() || iface->hasGlobalIPv6())) { + return true; + } + } + } + return false; +} + size_t NetworkManager::printTo(Print &out) const { size_t bytes = 0; diff --git a/libraries/Network/src/NetworkManager.h b/libraries/Network/src/NetworkManager.h index 6b9d5e16cfc..063de721792 100644 --- a/libraries/Network/src/NetworkManager.h +++ b/libraries/Network/src/NetworkManager.h @@ -22,6 +22,9 @@ class NetworkManager : public NetworkEvents, public Printable { bool setDefaultInterface(NetworkInterface &ifc); NetworkInterface *getDefaultInterface(); + // Returns true if any interface (except AP) has assigned IPv4 or global IPv6 + bool isOnline(); + size_t printTo(Print &out) const; static const char *getHostname(); From 46302559b2bf09297850aa0e7e2364bf9e49ef47 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Mon, 10 Nov 2025 07:25:31 -0300 Subject: [PATCH 09/23] feat(matter): Adds doc URL ref to examples README.md files (#11997) --- .../examples/MatterColorLight/README.md | 6 + .../examples/MatterCommissionTest/README.md | 4 + .../examples/MatterComposedLights/README.md | 8 + .../examples/MatterContactSensor/README.md | 6 + .../examples/MatterDimmableLight/README.md | 6 + .../MatterEnhancedColorLight/README.md | 6 + .../Matter/examples/MatterEvents/README.md | 4 + libraries/Matter/examples/MatterFan/README.md | 6 + .../examples/MatterHumiditySensor/README.md | 6 + .../README.md | 5 + .../Matter/examples/MatterMinimum/README.md | 5 + .../examples/MatterOccupancySensor/README.md | 6 + .../examples/MatterOnIdentify/README.md | 6 + .../examples/MatterOnOffLight/README.md | 6 + .../examples/MatterOnOffPlugin/README.md | 6 + .../examples/MatterPressureSensor/README.md | 6 + .../examples/MatterSmartButton/README.md | 6 + .../examples/MatterTemperatureLight/README.md | 6 + .../MatterTemperatureSensor/README.md | 6 + .../examples/MatterThermostat/README.md | 6 + .../examples/MatterThreadLight/README.md | 242 ------------------ 21 files changed, 116 insertions(+), 242 deletions(-) delete mode 100644 libraries/Matter/examples/MatterThreadLight/README.md diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md index 03a5928cd27..4d9e39e4f75 100644 --- a/libraries/Matter/examples/MatterColorLight/README.md +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -159,6 +159,12 @@ The MatterColorLight example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Color Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_color_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md index 52b2b1eb8e6..db5d0e158ea 100644 --- a/libraries/Matter/examples/MatterCommissionTest/README.md +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -146,6 +146,10 @@ The MatterCommissionTest example consists of the following main components: - **No serial output**: Check baudrate (115200) and USB connection - **Device keeps decommissioning**: This is expected behavior - the device automatically decommissions after 30 seconds to allow continuous testing +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterComposedLights/README.md b/libraries/Matter/examples/MatterComposedLights/README.md index cea56d0151a..96446810f9f 100644 --- a/libraries/Matter/examples/MatterComposedLights/README.md +++ b/libraries/Matter/examples/MatterComposedLights/README.md @@ -170,6 +170,14 @@ The MatterComposedLights example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter On/Off Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_on_off_light.html) +- [Matter Dimmable Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_dimmable_light.html) +- [Matter Color Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_color_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterContactSensor/README.md b/libraries/Matter/examples/MatterContactSensor/README.md index 3f7e73b4788..0f54a8f0010 100644 --- a/libraries/Matter/examples/MatterContactSensor/README.md +++ b/libraries/Matter/examples/MatterContactSensor/README.md @@ -167,6 +167,12 @@ The MatterContactSensor example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Contact Sensor Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_contact_sensor.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterDimmableLight/README.md b/libraries/Matter/examples/MatterDimmableLight/README.md index 0879ae2171d..f1381b2641c 100644 --- a/libraries/Matter/examples/MatterDimmableLight/README.md +++ b/libraries/Matter/examples/MatterDimmableLight/README.md @@ -165,6 +165,12 @@ The MatterDimmableLight example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Dimmable Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_dimmable_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterEnhancedColorLight/README.md b/libraries/Matter/examples/MatterEnhancedColorLight/README.md index 59ddc3a2166..100c216cedf 100644 --- a/libraries/Matter/examples/MatterEnhancedColorLight/README.md +++ b/libraries/Matter/examples/MatterEnhancedColorLight/README.md @@ -172,6 +172,12 @@ The MatterEnhancedColorLight example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Enhanced Color Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_enhanced_color_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterEvents/README.md b/libraries/Matter/examples/MatterEvents/README.md index 724e3e73cdb..985fb8748e5 100644 --- a/libraries/Matter/examples/MatterEvents/README.md +++ b/libraries/Matter/examples/MatterEvents/README.md @@ -176,6 +176,10 @@ The MatterEvents example consists of the following main components: - **No serial output**: Check baudrate (115200) and USB connection - **Device keeps decommissioning**: This is expected behavior - the device automatically decommissions after 60 seconds to allow continuous testing and event monitoring +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterFan/README.md b/libraries/Matter/examples/MatterFan/README.md index 89889ace3d6..cae9e15ba5f 100644 --- a/libraries/Matter/examples/MatterFan/README.md +++ b/libraries/Matter/examples/MatterFan/README.md @@ -189,6 +189,12 @@ The MatterFan example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Fan Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_fan.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterHumiditySensor/README.md b/libraries/Matter/examples/MatterHumiditySensor/README.md index 940516a2194..838073093cf 100644 --- a/libraries/Matter/examples/MatterHumiditySensor/README.md +++ b/libraries/Matter/examples/MatterHumiditySensor/README.md @@ -186,6 +186,12 @@ The MatterHumiditySensor example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Humidity Sensor Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_humidity_sensor.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md index f31732d66d6..62c923e3655 100644 --- a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md +++ b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md @@ -200,6 +200,11 @@ The MatterLambdaSingleCallbackManyEPs example consists of the following main com - **No serial output**: Check baudrate (115200) and USB connection - **Compilation errors with lambda functions**: Ensure you're using a C++11 compatible compiler (ESP32 Arduino Core 2.0+ supports this) +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterMinimum/README.md b/libraries/Matter/examples/MatterMinimum/README.md index a91fa651954..b3687718543 100644 --- a/libraries/Matter/examples/MatterMinimum/README.md +++ b/libraries/Matter/examples/MatterMinimum/README.md @@ -166,6 +166,11 @@ This minimal example can be extended with additional features: - **No serial output**: Check baudrate (115200) and USB connection - **LED not turning on/off**: Ensure the device is commissioned and you're controlling it via a Matter app. The minimal example only responds to Matter controller commands, not local button presses +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterOccupancySensor/README.md b/libraries/Matter/examples/MatterOccupancySensor/README.md index f83dafc4c4f..cb38c63ac6a 100644 --- a/libraries/Matter/examples/MatterOccupancySensor/README.md +++ b/libraries/Matter/examples/MatterOccupancySensor/README.md @@ -262,6 +262,12 @@ The MatterOccupancySensor example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Occupancy Sensor Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_occupancy_sensor.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterOnIdentify/README.md b/libraries/Matter/examples/MatterOnIdentify/README.md index 06d6732466f..ce873f9397f 100644 --- a/libraries/Matter/examples/MatterOnIdentify/README.md +++ b/libraries/Matter/examples/MatterOnIdentify/README.md @@ -208,6 +208,12 @@ The MatterOnIdentify example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter On/Off Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_on_off_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterOnOffLight/README.md b/libraries/Matter/examples/MatterOnOffLight/README.md index 2a2138ca2c7..b973302129a 100644 --- a/libraries/Matter/examples/MatterOnOffLight/README.md +++ b/libraries/Matter/examples/MatterOnOffLight/README.md @@ -176,6 +176,12 @@ The MatterOnOffLight example consists of the following main components: - **Button not toggling light**: Ensure the button is properly connected and the debounce time is appropriate. Check Serial Monitor for "User button released" messages - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter On/Off Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_on_off_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterOnOffPlugin/README.md b/libraries/Matter/examples/MatterOnOffPlugin/README.md index 70db06ff0fb..2603961353c 100644 --- a/libraries/Matter/examples/MatterOnOffPlugin/README.md +++ b/libraries/Matter/examples/MatterOnOffPlugin/README.md @@ -193,6 +193,12 @@ The MatterOnOffPlugin example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter On/Off Plugin Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_on_off_plugin.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterPressureSensor/README.md b/libraries/Matter/examples/MatterPressureSensor/README.md index d18ab9d5198..2f0665067ac 100644 --- a/libraries/Matter/examples/MatterPressureSensor/README.md +++ b/libraries/Matter/examples/MatterPressureSensor/README.md @@ -186,6 +186,12 @@ The MatterPressureSensor example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Pressure Sensor Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_pressure_sensor.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterSmartButton/README.md b/libraries/Matter/examples/MatterSmartButton/README.md index 2928897503f..e7290ba40b3 100644 --- a/libraries/Matter/examples/MatterSmartButton/README.md +++ b/libraries/Matter/examples/MatterSmartButton/README.md @@ -170,6 +170,12 @@ The MatterSmartButton example consists of the following main components: - **No serial output**: Check baudrate (115200) and USB connection - **Multiple clicks registered for single press**: Increase the debounce time in the code if needed +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Generic Switch Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_generic_switch.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterTemperatureLight/README.md b/libraries/Matter/examples/MatterTemperatureLight/README.md index 68a05632192..4eb9432400b 100644 --- a/libraries/Matter/examples/MatterTemperatureLight/README.md +++ b/libraries/Matter/examples/MatterTemperatureLight/README.md @@ -202,6 +202,12 @@ The MatterTemperatureLight example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Color Temperature Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_color_temperature_light.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterTemperatureSensor/README.md b/libraries/Matter/examples/MatterTemperatureSensor/README.md index 017f3ee9abc..9a494aec932 100644 --- a/libraries/Matter/examples/MatterTemperatureSensor/README.md +++ b/libraries/Matter/examples/MatterTemperatureSensor/README.md @@ -201,6 +201,12 @@ The MatterTemperatureSensor example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Temperature Sensor Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_temperature_sensor.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterThermostat/README.md b/libraries/Matter/examples/MatterThermostat/README.md index 8f0a69abe08..2a87f4d93af 100644 --- a/libraries/Matter/examples/MatterThermostat/README.md +++ b/libraries/Matter/examples/MatterThermostat/README.md @@ -225,6 +225,12 @@ The MatterThermostat example consists of the following main components: - **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection +## Related Documentation + +- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html) +- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html) +- [Matter Thermostat Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_thermostat.html) + ## License This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterThreadLight/README.md b/libraries/Matter/examples/MatterThreadLight/README.md deleted file mode 100644 index 3a971b279b5..00000000000 --- a/libraries/Matter/examples/MatterThreadLight/README.md +++ /dev/null @@ -1,242 +0,0 @@ -# Matter Thread Light Example - -This example demonstrates a Matter Light device that uses Thread network commissioning exclusively. Thread is a low-power, mesh networking protocol that's ideal for Matter smart home devices. - -## Features - -- **Thread-only commissioning**: Device can only be commissioned over Thread network -- **On/Off Light control**: Simple light that can be controlled via Matter -- **Automatic fallback**: On non-Thread capable devices, falls back to Wi-Fi -- **Status monitoring**: Displays network and commissioning status -- **Decommissioning support**: Long-press boot button to decommission - -## Hardware Requirements - -### Thread-Capable ESP32 Variants -- **ESP32-H2**: Native Thread support -- **ESP32-C6**: Native Thread support -- **ESP32-C5**: Native Thread support - -### Other ESP32 Variants -- **ESP32, ESP32-S2, ESP32-S3, ESP32-C3**: Will automatically fall back to Wi-Fi commissioning - -## Hardware Setup - -### Basic Setup -``` -ESP32-H2/C6/C5 Board -├── LED (GPIO 2 or LED_BUILTIN) - Visual feedback -└── Boot Button (GPIO 0) - Decommissioning -``` - -### Pin Configuration -- **LED Pin**: Uses `LED_BUILTIN` if available, otherwise GPIO 2 -- **Button Pin**: Uses `BOOT_PIN` (typically GPIO 0) - -## Network Requirements - -### Thread Border Router -To use Thread commissioning, you need a Thread Border Router in your network: - -**Apple HomePod/Apple TV (tvOS 15+)** -``` -- Supports Thread Border Router functionality -- Automatically discovered by Matter controllers -``` - -**Google Nest Hub Max (2nd gen)** -``` -- Built-in Thread Border Router -- Works with Google Home ecosystem -``` - -**OpenThread Border Router** -``` -- Raspberry Pi with Thread radio -- Custom Thread Border Router setup -``` - -## Usage - -### 1. Upload and Monitor -```bash -# Upload the sketch to your ESP32-H2/C6 -# Open Serial Monitor at 115200 baud -``` - -### 2. Check Thread Status -The device will display: -``` -=== Matter Thread Light Status === -Device commissioned: No -Device connected: No -Thread connected: No -Thread commissioning: Enabled -Wi-Fi commissioning: Disabled -Light state: OFF -================================ -``` - -### 3. Commission the Device -Use a Matter controller that supports Thread: - -**Apple Home** -1. Open Home app on iPhone/iPad -2. Tap "Add Accessory" -3. Scan QR code or enter manual pairing code -4. Follow commissioning steps - -**Google Home** -1. Open Google Home app -2. Tap "Add" → "Set up device" -3. Choose "Works with Google" -4. Scan QR code or enter pairing code - -### 4. Control the Light -Once commissioned, you can: -- Turn the light on/off from your Matter controller -- Monitor status in Serial Monitor -- See LED respond to commands - -### 5. Decommission (if needed) -1. Hold the boot button for 5+ seconds -2. Device will reset and become available for commissioning again - -## Serial Output - -### Successful Thread Commissioning -``` -Starting Thread-only Matter Light... -✓ Thread-only commissioning mode enabled -Matter Node is not commissioned yet. -Manual pairing code: 12345678901 -QR code URL: https://... - -This device is configured for Thread commissioning only. -Make sure your Matter controller supports Thread commissioning. - -Waiting for Matter commissioning... -Looking for Thread Border Router... -Thread connected: Yes -Device commissioned: Yes -Light ON -``` - -### Non-Thread Device Fallback -``` -Starting Thread-only Matter Light... -⚠ Thread support not compiled in, using Wi-Fi commissioning -Matter Node is not commissioned yet. -Wi-Fi commissioning: Enabled -``` - -## Troubleshooting - -### Device Not Commissioning -**Problem**: Device stuck on "Waiting for Matter commissioning..." - -**Solutions**: -1. **Check Thread Border Router**: - - Ensure Thread Border Router is online - - Verify controller supports Thread commissioning - -2. **Verify Network**: - - Check Thread network is operational - - Ensure Matter controller is on same network as Border Router - -3. **Reset and Retry**: - - Hold boot button for 5+ seconds to decommission - - Try commissioning again - -### Thread Connection Issues -**Problem**: "Thread connected: No" in status - -**Solutions**: -1. **Border Router Setup**: - - Verify Thread Border Router is functioning - - Check Border Router connectivity - -2. **Device Placement**: - - Move device closer to Thread Border Router - - Ensure no interference with Thread radio - -3. **Thread Network**: - - Verify Thread network credentials - - Check Thread network topology - -### Compilation Issues -**Problem**: Compilation errors related to Thread - -**Solutions**: -1. **ESP-IDF Version**: - ```bash - # Ensure ESP-IDF supports Thread for your board - # Update to latest ESP-IDF if needed - ``` - -2. **Board Configuration**: - ```bash - # Make sure you've selected the correct board - # ESP32-H2/C6/C5 for Thread support - ``` - -## API Reference - -### Network Commissioning Control -```cpp -// Enable Thread-only commissioning -Matter.setNetworkCommissioningMode(false, true); - -// Check Thread commissioning status -bool enabled = Matter.isThreadNetworkCommissioningEnabled(); - -// Check Thread connection -bool connected = Matter.isThreadConnected(); -``` - -### Device Status -```cpp -// Check if device is commissioned -bool commissioned = Matter.isDeviceCommissioned(); - -// Check if device has network connectivity -bool connected = Matter.isDeviceConnected(); -``` - -### Light Control -```cpp -// Set light state -OnOffLight.setOnOff(true); // Turn on -OnOffLight.setOnOff(false); // Turn off - -// Get current state -bool isOn = OnOffLight.getOnOff(); - -// Toggle light -OnOffLight.toggle(); -``` - -## Thread vs Wi-Fi Comparison - -| Feature | Thread | Wi-Fi | -|---------|--------|------| -| **Power Consumption** | Low | Higher | -| **Range** | Mesh network, self-healing | Single point to router | -| **Setup** | Requires Border Router | Direct to Wi-Fi router | -| **Reliability** | High (mesh redundancy) | Depends on Wi-Fi quality | -| **Device Limit** | 250+ devices per network | Limited by router | -| **Security** | Built-in mesh security | WPA2/WPA3 | - -## Related Examples - -- **[SimpleNetworkCommissioning](../SimpleNetworkCommissioning/)**: Basic Wi-Fi/Thread selection -- **[MatterNetworkCommissioning](../MatterNetworkCommissioning/)**: Interactive commissioning control -- **[MatterMinimum](../MatterMinimum/)**: Simplest Wi-Fi-only setup -- **[MatterOnOffLight](../MatterOnOffLight/)**: Wi-Fi-based light with persistence - -## Further Reading - -- [Thread Group Specification](https://www.threadgroup.org/) -- [OpenThread Documentation](https://openthread.io/) -- [Matter Thread Integration Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/thread_primer.md) -- [ESP32 Thread Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/thread.html) From af4dbf94f46405e79816dc69d909237d016ac874 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Proch=C3=A1zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Mon, 10 Nov 2025 11:25:57 +0100 Subject: [PATCH 10/23] feat(docs): Add AI chatbot (#12002) * feat(docs): Add chatbot * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- docs/_static/chatbot_widget.css | 9 +++++++++ docs/_static/chatbot_widget_en.js | 30 ++++++++++++++++++++++++++++++ docs/conf_common.py | 3 +++ 3 files changed, 42 insertions(+) create mode 100644 docs/_static/chatbot_widget.css create mode 100644 docs/_static/chatbot_widget_en.js diff --git a/docs/_static/chatbot_widget.css b/docs/_static/chatbot_widget.css new file mode 100644 index 00000000000..c6585b0588d --- /dev/null +++ b/docs/_static/chatbot_widget.css @@ -0,0 +1,9 @@ +#kapa-widget-container { + z-index: 10000 !important; + position: absolute !important; + } + + .mantine-Modal-root { + z-index: 10000; + position: absolute; + } diff --git a/docs/_static/chatbot_widget_en.js b/docs/_static/chatbot_widget_en.js new file mode 100644 index 00000000000..2b083966803 --- /dev/null +++ b/docs/_static/chatbot_widget_en.js @@ -0,0 +1,30 @@ +document.addEventListener("DOMContentLoaded", function () { + var script = document.createElement("script"); + script.src = "https://widget.kapa.ai/kapa-widget.bundle.js"; + script.setAttribute("data-bot-protection-mechanism", "hcaptcha"); + script.setAttribute("data-website-id", "f67ff377-ba84-4009-aceb-5e582755abad"); + script.setAttribute("data-project-name", "ESP32 Arduino Core Documentation"); + script.setAttribute("data-project-color", "#C62817"); + script.setAttribute("data-project-logo", "https://dl.espressif.com/public/logo.png"); + script.setAttribute("data-button-image", "https://dl.espressif.com/chatbot/Chatbot.png"); + script.setAttribute("data-button-text-font-size", "0px"); + script.setAttribute("data-button-border-radius", "50%"); + script.setAttribute("data-button-bg-color", "#38393a"); + script.setAttribute("data-button-border", "#38393a"); + script.setAttribute("data-button-height", "45px"); + script.setAttribute("data-button-width", "45px"); + script.setAttribute("data-button-animation-enabled", "false"); + script.setAttribute("data-button-image-height", "100%"); + script.setAttribute("data-button-image-width", "100%"); + script.setAttribute("data-button-padding", "0"); + script.setAttribute("data-button-hover-animation-enabled", "false"); + script.setAttribute("data-button-position-top", "50px"); + script.setAttribute("data-button-position-left", "305px"); + script.setAttribute("data-button-box-shadow", "0px 6px 12px 1px rgba(0,0,0,0.16)"); + script.setAttribute("data-modal-override-open-class", "test-ai"); + script.setAttribute("data-user-analytics-fingerprint-enabled", "true"); + script.setAttribute("data-modal-disclaimer", "This custom large language model (LLM), trained on official documentation from espressif.com, is designed to provide technical support and answers related to Espressif’s products and services. Give it a try, share your thoughts, and let us know your feedback—we truly appreciate it! \n\n**Note**: AI-generated information may be incomplete or inaccurate. Always verify critical information with official sources."); + script.setAttribute("data-modal-example-questions", "What is the ESP32 Arduino Core?,How do I get started with the ESP32 Arduino Core?"); + script.async = true; + document.head.appendChild(script); + }); diff --git a/docs/conf_common.py b/docs/conf_common.py index 0fb4fb8e306..4e3a3e31f0d 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -28,6 +28,9 @@ html_static_path = ["../_static"] +html_js_files = ["../_static/chatbot_widget_en.js"] +html_css_files = ["../_static/chatbot_widget.css"] + # Conditional content extensions += [ # noqa: F405 From 2bb78a97e270a3382e8c6e91ded0994a7460a03f Mon Sep 17 00:00:00 2001 From: Mathieu Carbou Date: Mon, 10 Nov 2025 12:17:47 +0100 Subject: [PATCH 11/23] feat(udp): Allow to change the async_udp task stack size (#12003) Example: `-D CONFIG_ARDUINO_UDP_TASK_STACK_SIZE=2048` The default is to much conservative since a correctly developed app probably won't allocate too much on stack on the callbacks. I currently see a wast of memory: `I (1222501) MONITOR: async_udp (p=3) 3416 bytes` --- Kconfig.projbuild | 6 ++++++ libraries/AsyncUDP/src/AsyncUDP.cpp | 23 ++++++++++++++++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/Kconfig.projbuild b/Kconfig.projbuild index 705d0e66d5a..a2761749e13 100644 --- a/Kconfig.projbuild +++ b/Kconfig.projbuild @@ -147,6 +147,12 @@ config ARDUINO_UDP_TASK_PRIORITY help Select at what priority you want the UDP task to run. +config ARDUINO_UDP_TASK_STACK_SIZE + int "UDP task stack size" + default 4096 + help + Amount of stack available for the UDP task. + config ARDUINO_ISR_IRAM bool "Run interrupts in IRAM" default "n" diff --git a/libraries/AsyncUDP/src/AsyncUDP.cpp b/libraries/AsyncUDP/src/AsyncUDP.cpp index 91b024999b1..ee4bcc86c30 100644 --- a/libraries/AsyncUDP/src/AsyncUDP.cpp +++ b/libraries/AsyncUDP/src/AsyncUDP.cpp @@ -15,6 +15,27 @@ extern "C" { #include "lwip/priv/tcpip_priv.h" +#ifndef CONFIG_ARDUINO_UDP_TASK_STACK_SIZE +#define CONFIG_ARDUINO_UDP_TASK_STACK_SIZE 4096 +#endif +#ifndef ARDUINO_UDP_TASK_STACK_SIZE +#define ARDUINO_UDP_TASK_STACK_SIZE CONFIG_ARDUINO_UDP_TASK_STACK_SIZE +#endif + +#ifndef CONFIG_ARDUINO_UDP_TASK_PRIORITY +#define CONFIG_ARDUINO_UDP_TASK_PRIORITY 3 +#endif +#ifndef ARDUINO_UDP_TASK_PRIORITY +#define ARDUINO_UDP_TASK_PRIORITY CONFIG_ARDUINO_UDP_TASK_PRIORITY +#endif + +#ifndef CONFIG_ARDUINO_UDP_RUNNING_CORE +#define CONFIG_ARDUINO_UDP_RUNNING_CORE -1 +#endif +#ifndef ARDUINO_UDP_RUNNING_CORE +#define ARDUINO_UDP_RUNNING_CORE CONFIG_ARDUINO_UDP_RUNNING_CORE +#endif + #ifdef CONFIG_LWIP_TCPIP_CORE_LOCKING #define UDP_MUTEX_LOCK() \ if (!sys_thread_tcpip(LWIP_CORE_LOCK_QUERY_HOLDER)) { \ @@ -189,7 +210,7 @@ static bool _udp_task_start() { } if (!_udp_task_handle) { xTaskCreateUniversal( - _udp_task, "async_udp", 4096, NULL, CONFIG_ARDUINO_UDP_TASK_PRIORITY, (TaskHandle_t *)&_udp_task_handle, CONFIG_ARDUINO_UDP_RUNNING_CORE + _udp_task, "async_udp", ARDUINO_UDP_TASK_STACK_SIZE, NULL, ARDUINO_UDP_TASK_PRIORITY, (TaskHandle_t *)&_udp_task_handle, ARDUINO_UDP_RUNNING_CORE ); if (!_udp_task_handle) { return false; From a58b6c6dfcde094685acc6e625b7ccce6c961a8b Mon Sep 17 00:00:00 2001 From: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> Date: Mon, 10 Nov 2025 08:59:45 -0300 Subject: [PATCH 12/23] fix(ble): Fix getPower return value --- libraries/BLE/src/BLEDevice.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/BLE/src/BLEDevice.cpp b/libraries/BLE/src/BLEDevice.cpp index 8b809abdaf3..8cf8dca0e5a 100644 --- a/libraries/BLE/src/BLEDevice.cpp +++ b/libraries/BLE/src/BLEDevice.cpp @@ -464,7 +464,7 @@ int BLEDevice::getPower(esp_ble_power_type_t powerType) { case ESP_PWR_LVL_N12: return -12; case ESP_PWR_LVL_N9: return -9; case ESP_PWR_LVL_N6: return -6; - case ESP_PWR_LVL_N3: return -6; + case ESP_PWR_LVL_N3: return -3; case ESP_PWR_LVL_N0: return 0; case ESP_PWR_LVL_P3: return 3; case ESP_PWR_LVL_P6: return 6; From 9cb8e227eb301c1bebb28c53ab225f0c173f0d74 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Mon, 10 Nov 2025 09:07:23 -0300 Subject: [PATCH 13/23] feat(network): Adds Network Library documentation (#11999) * feat(network): Adds Network Library documentation * fix(network): formatting in network API documentation * fix(doc): Use proper WiFi interfaces * feat(doc): Document isOnline() function in network API Added documentation for the isOnline() function to check network status. * fix(doc): Update docs/en/api/network.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(doc): Update docs/en/api/network.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: Me No Dev Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- docs/en/api/network.rst | 1093 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 1093 insertions(+) create mode 100644 docs/en/api/network.rst diff --git a/docs/en/api/network.rst b/docs/en/api/network.rst new file mode 100644 index 00000000000..214a2f73da4 --- /dev/null +++ b/docs/en/api/network.rst @@ -0,0 +1,1093 @@ +########### +Network API +########### + +About +----- + +The Network API provides a unified, object-oriented interface for managing multiple network interfaces on ESP32 devices. +The Network Manager acts as a central coordinator that manages Wi-Fi (Station and Access Point modes), Ethernet, and PPP interfaces, +providing a consistent API regardless of the underlying network technology. + +**Key Features:** + +* **Unified Interface Management**: Single API for all network types (Wi-Fi, Ethernet, PPP) +* **Event-Driven Architecture**: Centralized event handling through NetworkEvents +* **Multiple Interface Support**: Simultaneous operation of multiple network interfaces +* **Default Interface Selection**: Automatic or manual selection of the default network interface +* **IPv4 and IPv6 Support**: Full support for both IP protocol versions +* **Network Communication Classes**: Unified Client, Server, and UDP classes that work with any interface + +Architecture +------------ + +The Network library follows a tree-like hierarchical structure: + +.. code-block:: text + + NetworkManager (NetworkEvents) + │ + ├── NetworkInterface (Base Class) + │ │ + │ ├── Wi-Fi + │ │ ├── STAClass WiFi.STA (Station Mode) + │ │ └── APClass WiFi.AP (Access Point Mode) + │ │ + │ ├── Ethernet + │ │ └── ETHClass ETH + │ │ + │ └── PPP + │ └── PPPClass PPP + │ + └── Network Communication + ├── NetworkClient + ├── NetworkServer + └── NetworkUdp + +**Class Hierarchy:** + +* **NetworkManager**: Extends ``NetworkEvents`` and ``Printable``. Manages all network interfaces and provides global network functions. +* **NetworkEvents**: Provides event callback registration and handling for all network events. +* **NetworkInterface**: Base class that all network interfaces extend. Provides common functionality for IP configuration, status checking, and network information. +* **Interface Implementations**: + * ``STAClass``: Wi-Fi Station (client) mode + * ``APClass``: Wi-Fi Access Point mode + * ``ETHClass``: Ethernet interface + * ``PPPClass``: Point-to-Point Protocol (modem/cellular) + +Network Manager +--------------- + +The ``NetworkManager`` class (global instance: ``Network``) is the central coordinator for all network interfaces. +It extends ``NetworkEvents`` to provide event handling capabilities and implements ``Printable`` for status output. + +Initialization +************** + +.. code-block:: arduino + + bool begin(); + +Initializes the Network Manager and the underlying ESP-IDF network interface system. +This must be called before using any network interfaces. Returns ``true`` on success, ``false`` on failure. + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + + void setup() { + Serial.begin(115200); + Network.begin(); // Initialize Network Manager + } + +Check if Online +*************** + +.. code-block:: arduino + + bool isOnline(); + +Check if the device is online by verifying if any network interface (except AP) has an assigned IPv4 or global IPv6 address. +Returns ``true`` if such interface has been found, ``false`` if no interface has assigned IP. + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + + void setup() { + Serial.begin(115200); + Network.begin(); // Initialize Network Manager + + // Connect to WiFi AP + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + + // Wait for WiFi to connect + while (!WiFi.STA.hasIP()) { + delay(500); + } + + if (Network.isOnline()) { + Serial.println("Network is Online"); + } + } + +Default Interface Management +**************************** + +.. code-block:: arduino + + bool setDefaultInterface(NetworkInterface &ifc); + NetworkInterface *getDefaultInterface(); + +Sets or gets the default network interface. The default interface is used for network operations when no specific interface is specified. + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + + void setup() { + Network.begin(); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + + // Wait for WiFi to connect + while (!WiFi.STA.hasIP()) { + delay(500); + } + + // Set WiFi as default interface + Network.setDefaultInterface(WiFi.STA); + + // Get current default interface + NetworkInterface *defaultIf = Network.getDefaultInterface(); + Serial.print("Default interface: "); + Serial.println(defaultIf->impl_name()); + } + +Hostname Management +******************* + +.. code-block:: arduino + + static const char *getHostname(); + static bool setHostname(const char *hostname); + static bool hostname(const String &aHostname); + +Gets or sets the system hostname. The hostname is used for network identification and mDNS. + +**Example:** + +.. code-block:: arduino + + // Set hostname + Network.setHostname("my-esp32-device"); + + // Get hostname + const char *hostname = Network.getHostname(); + Serial.println(hostname); + +DNS Resolution +************** + +.. code-block:: arduino + + int hostByName(const char *aHostname, IPAddress &aResult); + +Resolves a hostname to an IP address using DNS. Returns ``1`` on success, error code on failure. + +**Example:** + +.. code-block:: arduino + + IPAddress ip; + if (Network.hostByName("www.example.com", ip) == 1) { + Serial.print("Resolved IP: "); + Serial.println(ip); + } + +MAC Address +*********** + +.. code-block:: arduino + + uint8_t *macAddress(uint8_t *mac); + String macAddress(); + +Gets the MAC address of the default network interface. + +**Example:** + +.. code-block:: arduino + + uint8_t mac[6]; + Network.macAddress(mac); + Serial.print("MAC: "); + for (int i = 0; i < 6; i++) { + if (i > 0) Serial.print(":"); + Serial.print(mac[i], HEX); + } + Serial.println(); + + // Or as String + String macStr = Network.macAddress(); + Serial.println(macStr); + +Network Events +-------------- + +The ``NetworkEvents`` class provides a centralized event handling system for all network-related events. +``NetworkManager`` extends ``NetworkEvents``, so you can register event callbacks directly on the ``Network`` object. + +Event Types +*********** + +Network events are defined in ``arduino_event_id_t`` enum: + +**Ethernet Events:** +* ``ARDUINO_EVENT_ETH_START`` +* ``ARDUINO_EVENT_ETH_STOP`` +* ``ARDUINO_EVENT_ETH_CONNECTED`` +* ``ARDUINO_EVENT_ETH_DISCONNECTED`` +* ``ARDUINO_EVENT_ETH_GOT_IP`` +* ``ARDUINO_EVENT_ETH_LOST_IP`` +* ``ARDUINO_EVENT_ETH_GOT_IP6`` + +**Wi-Fi Station Events:** +* ``ARDUINO_EVENT_WIFI_STA_START`` +* ``ARDUINO_EVENT_WIFI_STA_STOP`` +* ``ARDUINO_EVENT_WIFI_STA_CONNECTED`` +* ``ARDUINO_EVENT_WIFI_STA_DISCONNECTED`` +* ``ARDUINO_EVENT_WIFI_STA_GOT_IP`` +* ``ARDUINO_EVENT_WIFI_STA_LOST_IP`` +* ``ARDUINO_EVENT_WIFI_STA_GOT_IP6`` + +**Wi-Fi AP Events:** +* ``ARDUINO_EVENT_WIFI_AP_START`` +* ``ARDUINO_EVENT_WIFI_AP_STOP`` +* ``ARDUINO_EVENT_WIFI_AP_STACONNECTED`` +* ``ARDUINO_EVENT_WIFI_AP_STADISCONNECTED`` +* ``ARDUINO_EVENT_WIFI_AP_STAIPASSIGNED`` +* ``ARDUINO_EVENT_WIFI_AP_GOT_IP6`` + +**PPP Events:** +* ``ARDUINO_EVENT_PPP_START`` +* ``ARDUINO_EVENT_PPP_STOP`` +* ``ARDUINO_EVENT_PPP_CONNECTED`` +* ``ARDUINO_EVENT_PPP_DISCONNECTED`` +* ``ARDUINO_EVENT_PPP_GOT_IP`` +* ``ARDUINO_EVENT_PPP_LOST_IP`` +* ``ARDUINO_EVENT_PPP_GOT_IP6`` + +Registering Event Callbacks +**************************** + +Three types of callback functions are supported: + +**1. Simple Event Callback (Event ID only):** + +.. code-block:: arduino + + typedef void (*NetworkEventCb)(arduino_event_id_t event); + network_event_handle_t onEvent(NetworkEventCb cbEvent, arduino_event_id_t event = ARDUINO_EVENT_MAX); + +**2. Functional Callback (Event ID and Info):** + +.. code-block:: arduino + + typedef std::function NetworkEventFuncCb; + network_event_handle_t onEvent(NetworkEventFuncCb cbEvent, arduino_event_id_t event = ARDUINO_EVENT_MAX); + +**3. System Callback (Event Structure):** + +.. code-block:: arduino + + typedef void (*NetworkEventSysCb)(arduino_event_t *event); + network_event_handle_t onEvent(NetworkEventSysCb cbEvent, arduino_event_id_t event = ARDUINO_EVENT_MAX); + +**Example - Simple Callback:** + +.. code-block:: arduino + + void onNetworkEvent(arduino_event_id_t event) { + Serial.print("Network event: "); + Serial.println(NetworkEvents::eventName(event)); + + if (event == ARDUINO_EVENT_WIFI_STA_GOT_IP) { + Serial.println("WiFi connected!"); + } + } + + void setup() { + Network.begin(); + Network.onEvent(onNetworkEvent); + } + +**Example - Functional Callback with Event Info:** + +.. code-block:: arduino + + void setup() { + Network.begin(); + + Network.onEvent([](arduino_event_id_t event, arduino_event_info_t info) { + if (event == ARDUINO_EVENT_WIFI_STA_GOT_IP) { + Serial.print("IP Address: "); + Serial.println(IPAddress(info.got_ip.ip_info.ip.addr)); + Serial.print("Gateway: "); + Serial.println(IPAddress(info.got_ip.ip_info.gw.addr)); + } + }); + } + +**Example - System Callback:** + +.. code-block:: arduino + + void onNetworkEventSys(arduino_event_t *event) { + Serial.print("Event: "); + Serial.println(NetworkEvents::eventName(event->event_id)); + + if (event->event_id == ARDUINO_EVENT_WIFI_STA_GOT_IP) { + IPAddress ip = IPAddress(event->event_info.got_ip.ip_info.ip.addr); + Serial.print("Got IP: "); + Serial.println(ip); + } + } + + void setup() { + Network.begin(); + Network.onEvent(onNetworkEventSys); + } + +Removing Event Callbacks +************************ + +.. code-block:: arduino + + void removeEvent(NetworkEventCb cbEvent, arduino_event_id_t event = ARDUINO_EVENT_MAX); + void removeEvent(NetworkEventFuncCb cbEvent, arduino_event_id_t event = ARDUINO_EVENT_MAX); + void removeEvent(NetworkEventSysCb cbEvent, arduino_event_id_t event = ARDUINO_EVENT_MAX); + void removeEvent(network_event_handle_t event_handle); + +Remove event callbacks by function pointer or by handle (recommended). + +**Example:** + +.. code-block:: arduino + + network_event_handle_t eventHandle; + + void setup() { + Network.begin(); + // Register and save handle + eventHandle = Network.onEvent(onNetworkEvent); + } + + void loop() { + // Later, remove by handle + Network.removeEvent(eventHandle); + } + +Event Information +***************** + +.. code-block:: arduino + + static const char *eventName(arduino_event_id_t id); + +Returns a human-readable name for an event ID. + +**Example:** + +.. code-block:: arduino + + Serial.println(NetworkEvents::eventName(ARDUINO_EVENT_WIFI_STA_GOT_IP)); + // Output: "WIFI_STA_GOT_IP" + +Network Interface Base Class +----------------------------- + +The ``NetworkInterface`` class is the base class for all network interfaces (Wi-Fi STA, Wi-Fi AP, Ethernet, PPP). +It provides common functionality for IP configuration, status checking, and network information retrieval. + +All network interfaces inherit from ``NetworkInterface`` and can be used polymorphically. + +IP Configuration +**************** + +.. code-block:: arduino + + bool config( + IPAddress local_ip = (uint32_t)0x00000000, + IPAddress gateway = (uint32_t)0x00000000, + IPAddress subnet = (uint32_t)0x00000000, + IPAddress dns1 = (uint32_t)0x00000000, + IPAddress dns2 = (uint32_t)0x00000000, + IPAddress dns3 = (uint32_t)0x00000000 + ); + bool dnsIP(uint8_t dns_no, IPAddress ip); + +Configures static IP address, gateway, subnet mask, and DNS servers. +For server interfaces (Wi-Fi AP), ``dns1`` is the DHCP lease range start and ``dns2`` is the DNS server. + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + + void setup() { + Network.begin(); + + // Configure static IP + IPAddress local_ip(192, 168, 1, 100); + IPAddress gateway(192, 168, 1, 1); + IPAddress subnet(255, 255, 255, 0); + IPAddress dns1(8, 8, 8, 8); + IPAddress dns2(8, 8, 4, 4); + + WiFi.STA.begin(); + WiFi.STA.config(local_ip, gateway, subnet, dns1, dns2); + WiFi.STA.connect("ssid", "password"); + } + +Hostname +******** + +.. code-block:: arduino + + const char *getHostname() const; + bool setHostname(const char *hostname) const; + +Gets or sets the hostname for the specific interface. + +**Example:** + +.. code-block:: arduino + + WiFi.STA.setHostname("my-wifi-device"); + Serial.println(WiFi.STA.getHostname()); + +Status Checking +*************** + +.. code-block:: arduino + + bool started() const; + bool connected() const; + bool hasIP() const; + bool hasLinkLocalIPv6() const; + bool hasGlobalIPv6() const; + bool linkUp() const; + +Check the status of the network interface. + +**Example:** + +.. code-block:: arduino + + if (WiFi.STA.started()) { + Serial.println("WiFi interface started"); + } + + if (WiFi.STA.connected()) { + Serial.println("WiFi connected"); + } + + if (WiFi.STA.hasIP()) { + Serial.println("WiFi has IP address"); + } + +IPv6 Support +************ + +.. code-block:: arduino + + bool enableIPv6(bool en = true); + +Enables or disables IPv6 support on the interface. + +**Example:** + +.. code-block:: arduino + + WiFi.STA.enableIPv6(true); + + if (WiFi.STA.hasGlobalIPv6()) { + IPAddress ipv6 = WiFi.STA.globalIPv6(); + Serial.print("Global IPv6: "); + Serial.println(ipv6); + } + +IP Address Information +********************** + +.. code-block:: arduino + + IPAddress localIP() const; + IPAddress subnetMask() const; + IPAddress gatewayIP() const; + IPAddress dnsIP(uint8_t dns_no = 0) const; + IPAddress broadcastIP() const; + IPAddress networkID() const; + uint8_t subnetCIDR() const; + IPAddress linkLocalIPv6() const; // IPv6 only + IPAddress globalIPv6() const; // IPv6 only + +Get IP address information from the interface. + +**Example:** + +.. code-block:: arduino + + Serial.print("Local IP: "); + Serial.println(WiFi.STA.localIP()); + + Serial.print("Subnet Mask: "); + Serial.println(WiFi.STA.subnetMask()); + + Serial.print("Gateway: "); + Serial.println(WiFi.STA.gatewayIP()); + + Serial.print("DNS: "); + Serial.println(WiFi.STA.dnsIP()); + + Serial.print("Broadcast: "); + Serial.println(WiFi.STA.broadcastIP()); + + Serial.print("Network ID: "); + Serial.println(WiFi.STA.networkID()); + + Serial.print("Subnet CIDR: /"); + Serial.println(WiFi.STA.subnetCIDR()); + +MAC Address +*********** + +.. code-block:: arduino + + uint8_t *macAddress(uint8_t *mac) const; + String macAddress() const; + +Get the MAC address of the interface. + +**Example:** + +.. code-block:: arduino + + uint8_t mac[6]; + WiFi.STA.macAddress(mac); + Serial.print("MAC: "); + for (int i = 0; i < 6; i++) { + if (i > 0) Serial.print(":"); + Serial.print(mac[i], HEX); + } + Serial.println(); + + // Or as String + Serial.println(WiFi.STA.macAddress()); + +Default Interface +***************** + +.. code-block:: arduino + + bool setDefault(); + bool isDefault() const; + +Set this interface as the default network interface, or check if it is the default. + +**Example:** + +.. code-block:: arduino + + // Set WiFi STA as default + WiFi.STA.setDefault(); + + // Check if it's default + if (WiFi.STA.isDefault()) { + Serial.println("WiFi STA is the default interface"); + } + +Route Priority +*************** + +.. code-block:: arduino + + int getRoutePrio() const; + int setRoutePrio(int prio); // ESP-IDF 5.5+ + +Gets or sets the route priority for the interface. Higher priority interfaces are preferred for routing. + +**Example:** + +.. code-block:: arduino + + #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 5, 0) + // Set higher priority for Ethernet + ETH.setRoutePrio(100); + WiFi.STA.setRoutePrio(50); + #endif + +Status Bits and Waiting +*********************** + +.. code-block:: arduino + + int getStatusBits() const; + int waitStatusBits(int bits, uint32_t timeout_ms) const; + +Get current status bits or wait for specific status bits to be set. + +**Status Bits:** +* ``ESP_NETIF_STARTED_BIT``: Interface has been started +* ``ESP_NETIF_CONNECTED_BIT``: Interface is connected +* ``ESP_NETIF_HAS_IP_BIT``: Interface has an IP address +* ``ESP_NETIF_HAS_LOCAL_IP6_BIT``: Interface has link-local IPv6 +* ``ESP_NETIF_HAS_GLOBAL_IP6_BIT``: Interface has global IPv6 +* ``ESP_NETIF_WANT_IP6_BIT``: Interface wants IPv6 +* ``ESP_NETIF_HAS_STATIC_IP_BIT``: Interface has static IP configuration + +**Example:** + +.. code-block:: arduino + + // Wait for WiFi STA to get IP address (with 10 second timeout) + if (WiFi.STA.waitStatusBits(ESP_NETIF_HAS_IP_BIT, 10000) & ESP_NETIF_HAS_IP_BIT) { + Serial.println("WiFi STA got IP address!"); + } else { + Serial.println("Timeout waiting for IP address"); + } + +Interface Information +********************* + +.. code-block:: arduino + + const char *ifkey() const; + const char *desc() const; + String impl_name() const; + int impl_index() const; + esp_netif_t *netif(); + +Get interface identification and description information. + +**Example:** + +.. code-block:: arduino + + Serial.print("Interface key: "); + Serial.println(WiFi.STA.ifkey()); + + Serial.print("Description: "); + Serial.println(WiFi.STA.desc()); + + Serial.print("Implementation name: "); + Serial.println(WiFi.STA.impl_name()); + + Serial.print("Implementation index: "); + Serial.println(WiFi.STA.impl_index()); + +Network Interface Implementations +---------------------------------- + +Wi-Fi Station (STA) +******************** + +The ``STAClass`` (accessed via ``WiFi.STA`` object) extends ``NetworkInterface`` and provides Wi-Fi Station (client) mode functionality. + +**Key Features:** +* Connect to Wi-Fi access points +* Automatic reconnection +* WPA2/WPA3 security support +* Enterprise Wi-Fi support (WPA2-Enterprise) +* Scanning for available networks + +**Example:** + +.. code-block:: arduino + + #include "WiFi.h" + + void setup() { + Network.begin(); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + + while (WiFi.STA.status() != WL_CONNECTED) { + delay(500); + Serial.print("."); + } + + Serial.println(); + Serial.print("Connected! IP: "); + Serial.println(WiFi.STA.localIP()); + } + +For detailed Wi-Fi Station API documentation, see :doc:`wifi`. + +Wi-Fi Access Point (AP) +*********************** + +The ``APClass`` (accessed via ``WiFi.AP`` object) extends ``NetworkInterface`` and provides Wi-Fi Access Point mode functionality. + +**Key Features:** +* Create Wi-Fi access points +* DHCP server for connected stations +* Network Address Translation (NAT) +* Captive portal support + +**Example:** + +.. code-block:: arduino + + #include "WiFi.h" + + void setup() { + Network.begin(); + WiFi.AP.begin(); + WiFi.AP.create("MyESP32AP", "password123"); + + Serial.print("AP IP: "); + Serial.println(WiFi.AP.localIP()); + } + +For detailed Wi-Fi AP API documentation, see :doc:`wifi`. + +Ethernet +******** + +The ``ETHClass`` (accessed via ``ETH`` object) extends ``NetworkInterface`` and provides Ethernet connectivity. + +**Key Features:** +* Support for multiple Ethernet PHY types +* SPI-based and EMAC-based Ethernet controllers +* Automatic link detection +* Full-duplex operation + +**Example:** + +.. code-block:: arduino + + #include "ETH.h" + + void setup() { + Network.begin(); + ETH.begin(ETH_PHY_TYPE, ETH_PHY_ADDR, ETH_PHY_MDC, ETH_PHY_MDIO, ETH_PHY_POWER, ETH_CLK_MODE); + + while (!ETH.hasIP()) { + delay(500); + } + + Serial.print("Ethernet IP: "); + Serial.println(ETH.localIP()); + } + +For detailed Ethernet API documentation, see :doc:`ethernet`. + +PPP (Point-to-Point Protocol) +******************************* + +The ``PPPClass`` (accessed via ``PPP`` object) extends ``NetworkInterface`` and provides PPP connectivity, typically used with cellular modems. + +**Key Features:** +* Cellular modem support (SIM7000, SIM7600, BG96, etc.) +* APN configuration +* PIN code support +* Hardware flow control + +**Example:** + +.. code-block:: arduino + + #include "PPP.h" + + void setup() { + Network.begin(); + PPP.begin(PPP_MODEM_SIM7600, 1, 115200); + PPP.setApn("your.apn.here"); + + while (!PPP.hasIP()) { + delay(500); + } + + Serial.print("PPP IP: "); + Serial.println(PPP.localIP()); + } + +For detailed PPP API documentation, see the PPP library documentation. + +Network Communication Classes +------------------------------ + +The Network library provides unified communication classes that work with any network interface: +``NetworkClient``, ``NetworkServer``, and ``NetworkUdp``. + +NetworkClient +************* + +The ``NetworkClient`` class provides TCP client functionality that works with any network interface. + +**Key Features:** +* Connect to TCP servers +* Read/write data +* Timeout configuration +* Socket options + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + + NetworkClient client; + + void setup() { + Network.begin(); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + while (WiFi.STA.status() != WL_CONNECTED) delay(500); + + if (client.connect("www.example.com", 80)) { + client.println("GET / HTTP/1.1"); + client.println("Host: www.example.com"); + client.println(); + + while (client.available()) { + char c = client.read(); + Serial.print(c); + } + + client.stop(); + } + } + +NetworkServer +************* + +The ``NetworkServer`` class provides TCP server functionality that works with any network interface. + +**Key Features:** +* Accept incoming TCP connections +* Multiple client support +* Timeout configuration + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + + NetworkServer server(80); + + void setup() { + Network.begin(); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + while (WiFi.STA.status() != WL_CONNECTED) delay(500); + + server.begin(); + Serial.print("Server started on: "); + Serial.println(WiFi.STA.localIP()); + } + + void loop() { + NetworkClient client = server.accept(); + if (client) { + Serial.println("New client connected"); + client.println("Hello from ESP32!"); + client.stop(); + } + } + +NetworkUdp +********** + +The ``NetworkUdp`` class provides UDP communication that works with any network interface. + +**Key Features:** +* Send/receive UDP packets +* Multicast support +* Remote IP and port information + +**Example:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + + NetworkUDP udp; + + void setup() { + Network.begin(); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + while (WiFi.STA.status() != WL_CONNECTED) delay(500); + + udp.begin(1234); + } + + void loop() { + int packetSize = udp.parsePacket(); + if (packetSize) { + Serial.print("Received packet from: "); + Serial.print(udp.remoteIP()); + Serial.print(":"); + Serial.println(udp.remotePort()); + + char buffer[255]; + int len = udp.read(buffer, 255); + if (len > 0) { + buffer[len] = 0; + Serial.println(buffer); + } + } + } + +Multiple Interface Management +----------------------------- + +The Network Manager allows you to manage multiple network interfaces simultaneously and switch between them as needed. + +**Example - Multiple Interfaces:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + #include "ETH.h" + + void setup() { + Network.begin(); + + // Start Ethernet + ETH.begin(ETH_PHY_TYPE, ETH_PHY_ADDR, ETH_PHY_MDC, ETH_PHY_MDIO, ETH_PHY_POWER, ETH_CLK_MODE); + + // Start WiFi as backup + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + + // Wait for either interface to connect + while (!ETH.connected() && WiFi.STA.status() != WL_CONNECTED) { + delay(500); + } + + // Set the connected interface as default + if (ETH.connected()) { + Network.setDefaultInterface(ETH); + Serial.println("Using Ethernet"); + } else if (WiFi.STA.status() == WL_CONNECTED) { + Network.setDefaultInterface(WiFi.STA); + Serial.println("Using WiFi"); + } + } + +**Example - Interface Priority:** + +.. code-block:: arduino + + void setup() { + Network.begin(); + + // Start both interfaces + ETH.begin(...); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + + // Set route priorities (ESP-IDF 5.5+) + #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 5, 0) + ETH.setRoutePrio(100); // Higher priority + WiFi.STA.setRoutePrio(50); // Lower priority + #endif + + // Ethernet will be preferred for routing when both are connected + } + +Event Handling Examples +----------------------- + +**Example - Monitor All Network Events:** + +.. code-block:: arduino + + #include "Network.h" + + void onNetworkEvent(arduino_event_id_t event) { + Serial.print("[Network Event] "); + Serial.println(NetworkEvents::eventName(event)); + + switch (event) { + case ARDUINO_EVENT_WIFI_STA_GOT_IP: + Serial.println("WiFi Station got IP!"); + break; + case ARDUINO_EVENT_ETH_GOT_IP: + Serial.println("Ethernet got IP!"); + break; + case ARDUINO_EVENT_PPP_GOT_IP: + Serial.println("PPP got IP!"); + break; + default: + break; + } + } + + void setup() { + Serial.begin(115200); + Network.begin(); + Network.onEvent(onNetworkEvent); + } + +**Example - Interface-Specific Event Handling:** + +.. code-block:: arduino + + #include "Network.h" + #include "WiFi.h" + + void onWiFiEvent(arduino_event_id_t event, arduino_event_info_t info) { + if (event == ARDUINO_EVENT_WIFI_STA_GOT_IP) { + IPAddress ip = IPAddress(info.got_ip.ip_info.ip.addr); + IPAddress gateway = IPAddress(info.got_ip.ip_info.gw.addr); + IPAddress subnet = IPAddress(info.got_ip.ip_info.netmask.addr); + + Serial.println("WiFi Connected!"); + Serial.print("IP: "); + Serial.println(ip); + Serial.print("Gateway: "); + Serial.println(gateway); + Serial.print("Subnet: "); + Serial.println(subnet); + } + } + + void setup() { + Network.begin(); + Network.onEvent(onWiFiEvent, ARDUINO_EVENT_WIFI_STA_GOT_IP); + WiFi.STA.begin(); + WiFi.STA.connect("ssid", "password"); + } + +Troubleshooting +--------------- + +**Interface Not Starting:** +* Ensure ``Network.begin()`` is called before using any interface +* Check that the interface-specific initialization is correct +* Verify hardware connections (for Ethernet/PPP) + +**Default Interface Not Working:** +* Explicitly set the default interface using ``Network.setDefaultInterface()`` +* Check interface status using ``started()``, ``connected()``, and ``hasIP()`` +* Verify route priorities if using multiple interfaces + +**Events Not Firing:** +* Ensure ``Network.begin()`` is called to initialize the event system +* Check that callbacks are registered before the events occur +* Use ``NetworkEvents::eventName()`` to verify event IDs + +**IP Configuration Issues:** +* For static IP, ensure all parameters (IP, gateway, subnet) are provided +* Check that the IP address is not already in use on the network +* Verify DNS server addresses are correct + +**Multiple Interface Conflicts:** +* Set appropriate route priorities to control which interface is used +* Use ``setDefaultInterface()`` to explicitly select the default +* Monitor events to see which interface gets IP addresses first + +Related Documentation +--------------------- + +* `ESP-IDF Network Interface Documentation `_ From 3500d3e129a126cbacef511cc9487f2181dc8144 Mon Sep 17 00:00:00 2001 From: Me No Dev Date: Mon, 10 Nov 2025 14:32:48 +0200 Subject: [PATCH 14/23] fix(wifi): Fix WiFi.disconnect(true, true) not working (#12004) --- libraries/WiFi/src/STA.cpp | 33 ++++++++++++++------------------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/libraries/WiFi/src/STA.cpp b/libraries/WiFi/src/STA.cpp index 84258589b28..36577a38b83 100644 --- a/libraries/WiFi/src/STA.cpp +++ b/libraries/WiFi/src/STA.cpp @@ -525,25 +525,6 @@ bool STAClass::connect( #endif /* CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT */ bool STAClass::disconnect(bool eraseap, unsigned long timeout) { - if (eraseap) { - if (!started()) { - log_e("STA not started! You must call begin first."); - return false; - } - wifi_config_t conf; - memset(&conf, 0, sizeof(wifi_config_t)); - esp_err_t err = esp_wifi_set_config(WIFI_IF_STA, &conf); - if (err != ESP_OK) { - log_e("STA clear config failed! 0x%x: %s", err, esp_err_to_name(err)); - return false; - } - } - - if (!connected()) { - log_w("STA already disconnected."); - return true; - } - esp_err_t err = esp_wifi_disconnect(); if (err != ESP_OK) { log_e("STA disconnect failed! 0x%x: %s", err, esp_err_to_name(err)); @@ -560,6 +541,20 @@ bool STAClass::disconnect(bool eraseap, unsigned long timeout) { } } + if (eraseap) { + if (!started()) { + log_e("STA not started! You must call begin first."); + return false; + } + wifi_config_t conf; + memset(&conf, 0, sizeof(wifi_config_t)); + esp_err_t err = esp_wifi_set_config(WIFI_IF_STA, &conf); + if (err != ESP_OK) { + log_e("STA clear config failed! 0x%x: %s", err, esp_err_to_name(err)); + return false; + } + } + return true; } From 6cec5f867a89597c044e9656f81634df0805eadc Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Mon, 10 Nov 2025 09:33:12 -0300 Subject: [PATCH 15/23] feat(openthread): adds examples README.md files (#11996) * feat(openthread): adds examples README.md files * fix(openthread): code and readme typo * ci(pre-commit): Apply automatic fixes * fix(openthread): Fix formatting of CLI time units --------- Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- .../examples/CLI/COAP/coap_lamp/README.md | 165 ++++++++++++++++ .../examples/CLI/COAP/coap_switch/README.md | 176 +++++++++++++++++ .../examples/CLI/SimpleCLI/README.md | 166 ++++++++++++++++ .../examples/CLI/SimpleNode/README.md | 131 +++++++++++++ .../ExtendedRouterNode/ExtendedRouterNode.ino | 6 +- .../ExtendedRouterNode/README.md | 163 ++++++++++++++++ .../LeaderNode/LeaderNode.ino | 6 +- .../SimpleThreadNetwork/LeaderNode/README.md | 150 ++++++++++++++ .../SimpleThreadNetwork/RouterNode/README.md | 162 ++++++++++++++++ .../RouterNode/RouterNode.ino | 6 +- .../examples/CLI/ThreadScan/README.md | 137 +++++++++++++ .../examples/CLI/onReceive/README.md | 130 +++++++++++++ .../SimpleThreadNetwork/LeaderNode/README.md | 183 ++++++++++++++++++ .../SimpleThreadNetwork/RouterNode/README.md | 174 +++++++++++++++++ 14 files changed, 1746 insertions(+), 9 deletions(-) create mode 100644 libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md create mode 100644 libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleCLI/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/ThreadScan/README.md create mode 100644 libraries/OpenThread/examples/CLI/onReceive/README.md create mode 100644 libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md create mode 100644 libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md diff --git a/libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md b/libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md new file mode 100644 index 00000000000..2efd04d30cd --- /dev/null +++ b/libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md @@ -0,0 +1,165 @@ +# OpenThread CoAP Lamp Example + +This example demonstrates how to create a CoAP (Constrained Application Protocol) server on a Thread network that controls an RGB LED lamp.\ +The application acts as a CoAP resource server that receives PUT requests to turn the lamp on or off, demonstrating Thread-based IoT device communication. + +## Supported Targets + +| SoC | Thread | RGB LED | Status | +| --- | ------ | ------- | ------ | +| ESP32-H2 | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | Required | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example requires a companion CoAP Switch device (coap_switch example) to control the lamp. +- The lamp device acts as a Leader node and CoAP server. + +## Features + +- CoAP server implementation on Thread network +- RGB LED control with smooth fade in/out transitions +- Leader node configuration using CLI Helper Functions API +- CoAP resource creation and management +- Multicast IPv6 address for CoAP communication +- Automatic network setup with retry mechanism +- Visual status indication using RGB LED (Red = failed, Green = ready) + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- RGB LED (built-in RGB LED or external RGB LED) +- USB cable for Serial communication +- A CoAP Switch device (coap_switch example) to control the lamp + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network and CoAP configuration: + +```cpp +#define OT_CHANNEL "24" +#define OT_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define OT_MCAST_ADDR "ff05::abcd" +#define OT_COAP_RESOURCE_NAME "Lamp" +``` + +**Important:** +- The network key and channel must match the Switch device configuration +- The multicast address and resource name must match the Switch device +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) + +## Building and Flashing + +1. Open the `coap_lamp.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Starting OpenThread. +Running as Lamp (RGB LED) - use the other C6/H2 as a Switch +OpenThread started. +Waiting for activating correct Device Role. +........ +Device is Leader. +OpenThread setup done. Node is ready. +``` + +The RGB LED will turn **green** when the device is ready to receive CoAP commands. + +## Using the Device + +### Lamp Device Setup + +The lamp device automatically: +1. Configures itself as a Thread Leader node +2. Creates a CoAP server +3. Registers a CoAP resource named "Lamp" +4. Sets up a multicast IPv6 address for CoAP communication +5. Waits for CoAP PUT requests from the Switch device + +### CoAP Resource + +The lamp exposes a CoAP resource that accepts: +- **PUT with payload "0"**: Turns the lamp OFF (fades to black) +- **PUT with payload "1"**: Turns the lamp ON (fades to white) + +### Visual Status Indication + +The RGB LED provides visual feedback: +- **Red**: Setup failed or error occurred +- **Green**: Device is ready and waiting for CoAP commands +- **White/Black**: Lamp state (controlled by CoAP commands) + +### Working with Switch Device + +1. Start the Lamp device first (this example) +2. Start the Switch device (coap_switch example) with matching network key and channel +3. Press the button on the Switch device to toggle the lamp +4. The lamp will fade in/out smoothly when toggled + +## Code Structure + +The coap_lamp example consists of the following main components: + +1. **`otDeviceSetup()` function**: + - Configures the device as a Leader node using CLI Helper Functions + - Sets up CoAP server and resource + - Waits for device to become Leader + - Returns success/failure status + +2. **`setupNode()` function**: + - Retries setup until successful + - Calls `otDeviceSetup()` with Leader role configuration + +3. **`otCOAPListen()` function**: + - Listens for CoAP requests from the Switch device + - Parses CoAP PUT requests + - Controls RGB LED based on payload (0 = OFF, 1 = ON) + - Implements smooth fade transitions + +4. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Initializes OpenThread CLI + - Sets CLI timeout + - Calls `setupNode()` to configure the device + +5. **`loop()`**: + - Continuously calls `otCOAPListen()` to process incoming CoAP requests + - Small delay for responsiveness + +## Troubleshooting + +- **LED stays red**: Setup failed. Check Serial Monitor for error messages. Verify network configuration. +- **Lamp not responding to switch**: Ensure both devices use the same network key, channel, multicast address, and resource name. Check that Switch device is running. +- **Device not becoming Leader**: Clear NVS or ensure this is the first device started. Check network configuration. +- **CoAP requests not received**: Verify multicast address matches between Lamp and Switch devices. Check Thread network connectivity. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) +- [CoAP Protocol](https://coap.technology/) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md b/libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md new file mode 100644 index 00000000000..9f8aae20539 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md @@ -0,0 +1,176 @@ +# OpenThread CoAP Switch Example + +This example demonstrates how to create a CoAP (Constrained Application Protocol) client on a Thread network that controls a remote CoAP server (lamp).\ +The application acts as a CoAP client that sends PUT requests to a lamp device, demonstrating Thread-based IoT device control. + +## Supported Targets + +| SoC | Thread | Button | Status | +| --- | ------ | ------ | ------ | +| ESP32-H2 | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | Required | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example requires a companion CoAP Lamp device (coap_lamp example) to control. +- The switch device joins the network as a Router or Child node and acts as a CoAP client. + +## Features + +- CoAP client implementation on Thread network +- Button-based control of remote lamp device +- Router/Child node configuration using CLI Helper Functions API +- CoAP PUT request sending with confirmation +- Automatic network join with retry mechanism +- Visual status indication using RGB LED (Red = failed, Blue = ready) +- Button debouncing for reliable input + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- User button (BOOT button or external button) +- RGB LED for status indication (optional, but recommended) +- USB cable for Serial communication +- A CoAP Lamp device (coap_lamp example) must be running first + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network and CoAP configuration: + +```cpp +#define USER_BUTTON 9 // C6/H2 Boot button (change if needed) +#define OT_CHANNEL "24" +#define OT_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define OT_MCAST_ADDR "ff05::abcd" +#define OT_COAP_RESOURCE_NAME "Lamp" +``` + +**Important:** +- The network key and channel **must match** the Lamp device configuration +- The multicast address and resource name **must match** the Lamp device +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) +- **Start the Lamp device first** before starting this Switch device + +## Building and Flashing + +1. **First, start the Lamp device** using the coap_lamp example +2. Open the `coap_switch.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Starting OpenThread. +Running as Switch - use the BOOT button to toggle the other C6/H2 as a Lamp +OpenThread started. +Waiting for activating correct Device Role. +........ +Device is Router. +OpenThread setup done. Node is ready. +``` + +The RGB LED will turn **blue** when the device is ready to send CoAP commands. + +## Using the Device + +### Switch Device Setup + +The switch device automatically: +1. Joins the existing Thread network (created by the Lamp Leader) +2. Configures itself as a Router or Child node +3. Creates a CoAP client +4. Waits for button presses to send CoAP commands + +### Button Control + +- **Press the button**: Toggles the lamp state (ON/OFF) +- The switch sends CoAP PUT requests to the lamp: + - Payload "1" = Turn lamp ON + - Payload "0" = Turn lamp OFF + +### Visual Status Indication + +The RGB LED provides visual feedback: +- **Red**: Setup failed or CoAP request failed +- **Blue**: Device is ready and can send CoAP commands +- **Red (after button press)**: CoAP request failed, device will restart setup + +### Working with Lamp Device + +1. Start the Lamp device first (coap_lamp example) +2. Start this Switch device with matching network key and channel +3. Wait for Switch device to join the network (LED turns blue) +4. Press the button on the Switch device +5. The lamp on the other device should toggle ON/OFF + +## Code Structure + +The coap_switch example consists of the following main components: + +1. **`otDeviceSetup()` function**: + - Configures the device to join an existing network using CLI Helper Functions + - Sets up CoAP client + - Waits for device to become Router or Child + - Returns success/failure status + +2. **`setupNode()` function**: + - Retries setup until successful + - Calls `otDeviceSetup()` with Router/Child role configuration + +3. **`otCoapPUT()` function**: + - Sends CoAP PUT request to the lamp device + - Waits for CoAP confirmation response + - Returns success/failure status + - Uses CLI Helper Functions to send commands and read responses + +4. **`checkUserButton()` function**: + - Monitors button state with debouncing + - Toggles lamp state on button press + - Calls `otCoapPUT()` to send commands + - Restarts setup if CoAP request fails + +5. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Initializes OpenThread CLI + - Sets CLI timeout + - Calls `setupNode()` to configure the device + +6. **`loop()`**: + - Continuously calls `checkUserButton()` to monitor button input + - Small delay for responsiveness + +## Troubleshooting + +- **LED stays red**: Setup failed. Check Serial Monitor for error messages. Verify network configuration matches Lamp device. +- **Button press doesn't toggle lamp**: Ensure Lamp device is running and both devices are on the same Thread network. Check that network key, channel, multicast address, and resource name match. +- **Device not joining network**: Ensure Lamp device (Leader) is running first. Verify network key and channel match exactly. +- **CoAP request timeout**: Check Thread network connectivity. Verify multicast address and resource name match the Lamp device. Ensure Lamp device is responding. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) +- [CoAP Protocol](https://coap.technology/) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/SimpleCLI/README.md b/libraries/OpenThread/examples/CLI/SimpleCLI/README.md new file mode 100644 index 00000000000..463d7ed5ab2 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleCLI/README.md @@ -0,0 +1,166 @@ +# OpenThread Simple CLI Example + +This example demonstrates how to use the OpenThread CLI (Command-Line Interface) for interactive control of a Thread network node using an ESP32 SoC microcontroller.\ +The application provides an interactive console where you can manually configure and control the Thread network using OpenThread CLI commands. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing you to manually configure it using CLI commands. + +## Features + +- Interactive OpenThread CLI console via Serial Monitor +- Manual Thread network configuration using CLI commands +- Full control over Thread network parameters (network name, channel, PAN ID, network key, etc.) +- Support for all OpenThread CLI commands +- Useful for learning OpenThread CLI and debugging Thread networks + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example starts with a fresh Thread stack that is not automatically started, allowing you to configure it manually using CLI commands. + +## Building and Flashing + +1. Open the `SimpleCLI.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +OpenThread CLI started - type 'help' for a list of commands. +ot> +``` + +The `ot> ` prompt indicates that the OpenThread CLI console is ready. You can now type OpenThread CLI commands directly. + +## Using the Device + +### Interactive CLI Commands + +Type OpenThread CLI commands in the Serial Monitor. Some useful commands to get started: + +**Get help:** +``` +help +``` + +**Initialize a new dataset:** +``` +dataset init new +``` + +**Set network parameters:** +``` +dataset networkname MyThreadNetwork +dataset channel 15 +dataset networkkey 00112233445566778899aabbccddeeff +``` + +**Commit and start the network:** +``` +dataset commit active +ifconfig up +thread start +``` + +**Check device state:** +``` +state +``` + +**View network information:** +``` +networkname +channel +panid +ipaddr +``` + +**For a complete list of OpenThread CLI commands, refer to the** [OpenThread CLI Reference](https://openthread.io/reference/cli). + +### Example Workflow + +1. **Initialize a new Thread network (Leader):** + ``` + dataset init new + dataset networkname MyNetwork + dataset channel 15 + dataset networkkey 00112233445566778899aabbccddeeff + dataset commit active + ifconfig up + thread start + ``` + +2. **Join an existing network (Router/Child):** + ``` + dataset clear + dataset networkkey 00112233445566778899aabbccddeeff + dataset channel 15 + dataset commit active + ifconfig up + thread start + ``` + +3. **Check network status:** + ``` + state + networkname + ipaddr + ``` + +## Code Structure + +The SimpleCLI example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Starts the interactive CLI console on Serial + +2. **`loop()`**: + - Empty - all interaction happens through the CLI console + +## Troubleshooting + +- **CLI not responding**: Ensure Serial Monitor is set to 115200 baud and "Both NL & CR" line ending +- **Commands not working**: Make sure OpenThread stack is initialized (check for "OpenThread CLI started" message) +- **Network not starting**: Verify that you've committed the dataset and started the interface before starting Thread +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/SimpleNode/README.md b/libraries/OpenThread/examples/CLI/SimpleNode/README.md new file mode 100644 index 00000000000..c882be09046 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleNode/README.md @@ -0,0 +1,131 @@ +# OpenThread Simple Node Example + +This example demonstrates how to create a simple OpenThread node that automatically starts in a Thread network using default settings.\ +The application automatically initializes a Thread network with default parameters and displays the current device role and network information. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin()` which automatically starts a Thread network using default settings or previously stored NVS dataset information. + +## Features + +- Automatic Thread network initialization with default settings +- Automatic device role assignment (first device becomes Leader, subsequent devices become Router or Child) +- Network information display using CLI Helper Functions API +- Periodic device role monitoring +- Support for persistent network configuration via NVS + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example uses default Thread network parameters: + +- **Network Name**: "OpenThread-ESP" +- **Mesh Local Prefix**: "fd00:db8:a0:0::/64" +- **Channel**: 15 +- **PAN ID**: 0x1234 +- **Extended PAN ID**: "dead00beef00cafe" +- **Network Key**: "00112233445566778899aabbccddeeff" +- **PSKc**: "104810e2315100afd6bc9215a6bfac53" + +**Note:** If NVS (Non-Volatile Storage) already contains dataset information, it will be loaded from there instead of using defaults. + +## Building and Flashing + +1. Open the `SimpleNode.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +OpenThread Network Information: +Role: Leader +RLOC16: 0x0000 +Network Name: OpenThread-ESP +Channel: 15 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:0 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:0 + +Thread Node State: Leader +Thread Node State: Leader +... +``` + +The first device to start will become the **Leader**. Subsequent devices will automatically join as **Router** or **Child** nodes. + +## Using the Device + +### Network Behavior + +- **First device**: Automatically becomes the Leader and creates a new Thread network +- **Subsequent devices**: Automatically join the existing network as Router or Child nodes +- **Device role**: Displayed every 5 seconds in the Serial Monitor + +### Multiple Devices + +To create a multi-device Thread network: + +1. Flash the first device - it will become the Leader +2. Flash additional devices - they will automatically join the network +3. All devices must use the same network key and channel (defaults are used if NVS is empty) + +## Code Structure + +The SimpleNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin()` (auto-start with default settings) + - Initializes OpenThread CLI + - Prints current Thread network information using `OpenThread.otPrintNetworkInformation()` + +2. **`loop()`**: + - Periodically displays the current device role using `OpenThread.otGetStringDeviceRole()` + - Updates every 5 seconds + +## Troubleshooting + +- **Device not joining network**: Ensure all devices use the same network key and channel. Check that the Leader node is running first. +- **Role stuck as "Detached"**: Wait a few seconds for the device to join the network. Verify network key and channel match the Leader. +- **No network information displayed**: Check that OpenThread stack initialized successfully (look for network information in setup) +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/ExtendedRouterNode.ino b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/ExtendedRouterNode.ino index 40f046aeab5..0fb66a5dfb3 100644 --- a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/ExtendedRouterNode.ino +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/ExtendedRouterNode.ino @@ -16,8 +16,8 @@ #include "OThreadCLI_Util.h" // Leader node shall use the same Network Key and channel -#define CLI_NETWORK_KEY "00112233445566778899aabbccddeeff" -#define CLI_NETWORK_CHANEL "24" +#define CLI_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANNEL "24" bool otStatus = true; void setup() { @@ -29,7 +29,7 @@ void setup() { otStatus &= otExecCommand("dataset", "clear"); otStatus &= otExecCommand("dataset networkkey", CLI_NETWORK_KEY); - otStatus &= otExecCommand("dataset channel", CLI_NETWORK_CHANEL); + otStatus &= otExecCommand("dataset channel", CLI_NETWORK_CHANNEL); otStatus &= otExecCommand("dataset", "commit active"); otStatus &= otExecCommand("ifconfig", "up"); otStatus &= otExecCommand("thread", "start"); diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md new file mode 100644 index 00000000000..3091b65259a --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md @@ -0,0 +1,163 @@ +# OpenThread Extended Router Node Example (CLI) + +This example demonstrates how to create an OpenThread Router or Child node that joins an existing Thread network, with extended functionality showing both CLI Helper Functions API and native OpenThread API usage.\ +The example shows how to retrieve network information using both methods and demonstrates error handling. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing manual configuration. +- **Important:** A Leader node must be running before starting this Router/Child node. + +## Features + +- Manual Router/Child node configuration using CLI Helper Functions API +- Joins an existing Thread network created by a Leader node +- Demonstrates both CLI Helper Functions API (`otGetRespCmd()`) and native OpenThread API (`otLinkGetPanId()`) usage +- Network information display using both API methods +- Error handling and timeout management +- Comprehensive network status monitoring + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication +- A Leader node must be running on the same network + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, configure the network parameters to match the Leader node: + +```cpp +#define CLI_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANNEL "24" +``` + +**Important:** +- The network key **must match** the Leader node's network key +- The channel **must match** the Leader node's channel +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) + +## Building and Flashing + +1. **First, start the Leader node** using the LeaderNode example +2. Open the `ExtendedRouterNode.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Setting up OpenThread Node as Router/Child +Make sure the Leader Node is already running + +PanID[using CLI]: 0x1234 + +PanID[using OT API]: 0x1234 + +Thread NetworkInformation: +--------------------------- +Role: Router +RLOC16: 0xfc00 +Network Name: OpenThread-ESP +Channel: 24 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:fc00 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:fc00 +--------------------------- +``` + +## Using the Device + +### Extended Router/Child Node Setup + +The Extended Router/Child node is automatically configured in `setup()` using the following sequence: + +1. **Clear dataset**: Clears any existing dataset +2. **Set network key**: Configures the network security key (must match Leader) +3. **Set channel**: Configures the IEEE 802.15.4 channel (must match Leader) +4. **Commit dataset**: Applies the dataset to the active configuration +5. **Start interface**: Brings up the network interface +6. **Start Thread**: Starts the Thread network and joins the existing network +7. **Wait for role**: Waits up to 90 seconds for the device to become Router or Child + +### Dual API Demonstration + +This example demonstrates two ways to access OpenThread information: + +1. **CLI Helper Functions API**: Uses `otGetRespCmd("panid", resp)` to get PAN ID via CLI +2. **Native OpenThread API**: Uses `otLinkGetPanId(esp_openthread_get_instance())` to get PAN ID directly + +Both methods should return the same value, demonstrating API equivalence. + +### Network Information + +Once the device joins the network, the `loop()` function displays comprehensive network information using `OpenThread.otPrintNetworkInformation()`, including: +- Device role +- RLOC16 +- Network name +- Channel +- PAN ID and Extended PAN ID +- Network key +- IPv6 addresses (Mesh Local EID, Leader RLOC, Node RLOC) + +## Code Structure + +The ExtendedRouterNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Configures the device to join an existing network using CLI Helper Functions: + - `otExecCommand()` - Executes CLI commands with error handling + - Commands: "dataset clear", "dataset networkkey", "dataset channel", "dataset commit active", "ifconfig up", "thread start" + - Waits for device to become Router or Child (with 90-second timeout) + - Demonstrates dual API usage for getting PAN ID + +2. **`loop()`**: + - Displays comprehensive network information using `OpenThread.otPrintNetworkInformation()` + - Updates every 10 seconds + - Shows error message if setup failed + +## Troubleshooting + +- **Device not joining network**: Ensure the Leader node is running first. Verify network key and channel match the Leader exactly. +- **Timeout error**: The device waits 90 seconds to join. If timeout occurs, check network key and channel match the Leader. +- **Network key/channel mismatch**: Double-check that both Leader and Router/Child nodes use identical network key and channel values. +- **Setup failed message**: Check Serial Monitor for specific error messages. Verify Leader node is running and within range. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/LeaderNode.ino b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/LeaderNode.ino index a945a5c8f77..b2a1330b93e 100644 --- a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/LeaderNode.ino +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/LeaderNode.ino @@ -28,8 +28,8 @@ #include "OThreadCLI.h" #include "OThreadCLI_Util.h" -#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" -#define CLI_NETWORK_CHANEL "dataset channel 24" +#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANNEL "dataset channel 24" otInstance *aInstance = NULL; @@ -43,7 +43,7 @@ void setup() { OThreadCLI.println("dataset init new"); OThreadCLI.println(CLI_NETWORK_KEY); - OThreadCLI.println(CLI_NETWORK_CHANEL); + OThreadCLI.println(CLI_NETWORK_CHANNEL); OThreadCLI.println("dataset commit active"); OThreadCLI.println("ifconfig up"); OThreadCLI.println("thread start"); diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md new file mode 100644 index 00000000000..6874ab2fde0 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md @@ -0,0 +1,150 @@ +# OpenThread Leader Node Example (CLI) + +This example demonstrates how to create an OpenThread Leader node using the CLI Helper Functions API.\ +The Leader node is the first device in a Thread network that manages the network and assigns router IDs. This example shows how to configure a Leader node manually using OpenThread CLI commands. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing manual configuration. + +## Features + +- Manual Leader node configuration using CLI Helper Functions API +- Complete dataset initialization with network key and channel +- Network information display using native OpenThread API calls +- Demonstrates both CLI Helper Functions and native OpenThread API usage +- IPv6 address listing (unicast and multicast) + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network configuration: + +```cpp +#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANNEL "dataset channel 24" +``` + +**Important:** +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) +- All devices in the same network must use the same network key and channel + +## Building and Flashing + +1. Open the `LeaderNode.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Setting up OpenThread Node as Leader +============================================= +Thread Node State: Leader +Network Name: OpenThread-ESP +Channel: 24 +PanID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +IP Address: fd00:db8:a0:0:0:ff:fe00:0 +Multicast IP Address: ff02::1 +Multicast IP Address: ff03::1 +... +``` + +## Using the Device + +### Leader Node Setup + +The Leader node is automatically configured in `setup()` using the following sequence: + +1. **Initialize new dataset**: Creates a complete dataset with random values +2. **Set network key**: Configures the network security key +3. **Set channel**: Configures the IEEE 802.15.4 channel +4. **Commit dataset**: Applies the dataset to the active configuration +5. **Start interface**: Brings up the network interface +6. **Start Thread**: Starts the Thread network + +### Network Information + +Once the device becomes a Leader, the `loop()` function displays: +- Device role (Leader) +- Network name +- Channel +- PAN ID and Extended PAN ID +- Network key +- All IPv6 addresses (unicast and multicast) + +### Joining Other Devices + +To join other devices to this network: +1. Use the same network key and channel in the Router/Child node examples +2. Start the Leader node first +3. Then start the Router/Child nodes + +## Code Structure + +The LeaderNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Configures the device as a Leader using CLI Helper Functions: + - `OThreadCLI.println()` - Sends CLI commands + - Commands: "dataset init new", "dataset networkkey", "dataset channel", "dataset commit active", "ifconfig up", "thread start" + +2. **`loop()`**: + - Checks if device role is Leader using `OpenThread.otGetDeviceRole()` + - Displays network information using native OpenThread API calls: + - `otThreadGetNetworkName()` - Network name + - `otLinkGetChannel()` - Channel + - `otLinkGetPanId()` - PAN ID + - `otThreadGetExtendedPanId()` - Extended PAN ID + - `otThreadGetNetworkKey()` - Network key + - `otIp6GetUnicastAddresses()` - Unicast IPv6 addresses + - `otIp6GetMulticastAddresses()` - Multicast IPv6 addresses + - Updates every 5 seconds + +## Troubleshooting + +- **Device not becoming Leader**: Ensure this is the first device started, or clear NVS to start fresh +- **Network key/channel mismatch**: Verify all devices use the same network key and channel +- **No network information**: Wait for the device to become Leader (may take a few seconds) +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md new file mode 100644 index 00000000000..c9940fb7abc --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md @@ -0,0 +1,162 @@ +# OpenThread Router/Child Node Example (CLI) + +This example demonstrates how to create an OpenThread Router or Child node that joins an existing Thread network using the CLI Helper Functions API.\ +The Router/Child node joins a network created by a Leader node and can route messages or operate as an end device. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing manual configuration. +- **Important:** A Leader node must be running before starting this Router/Child node. + +## Features + +- Manual Router/Child node configuration using CLI Helper Functions API +- Joins an existing Thread network created by a Leader node +- Network information display using native OpenThread API calls +- Demonstrates both CLI Helper Functions and native OpenThread API usage +- IPv6 address listing (unicast and multicast) +- Automatic role assignment (Router or Child based on network conditions) + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication +- A Leader node must be running on the same network + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, configure the network parameters to match the Leader node: + +```cpp +#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANNEL "dataset channel 24" +``` + +**Important:** +- The network key **must match** the Leader node's network key +- The channel **must match** the Leader node's channel +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) + +## Building and Flashing + +1. **First, start the Leader node** using the LeaderNode example +2. Open the `RouterNode.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Setting up OpenThread Node as Router/Child +Make sure the Leader Node is already running +============================================= +Thread Node State: Router +Network Name: OpenThread-ESP +Channel: 24 +PanID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +IP Address: fd00:db8:a0:0:0:ff:fe00:fc00 +Multicast IP Address: ff02::1 +Multicast IP Address: ff03::1 +... +``` + +The device will join as either a **Router** (if network needs more routers) or **Child** (end device). + +## Using the Device + +### Router/Child Node Setup + +The Router/Child node is automatically configured in `setup()` using the following sequence: + +1. **Clear dataset**: Clears any existing dataset +2. **Set network key**: Configures the network security key (must match Leader) +3. **Set channel**: Configures the IEEE 802.15.4 channel (must match Leader) +4. **Commit dataset**: Applies the dataset to the active configuration +5. **Start interface**: Brings up the network interface +6. **Start Thread**: Starts the Thread network and joins the existing network + +### Network Information + +Once the device joins the network (as Router or Child), the `loop()` function displays: +- Device role (Router or Child) +- Network name (from the Leader) +- Channel +- PAN ID and Extended PAN ID +- Network key +- All IPv6 addresses (unicast and multicast) + +### Multi-Device Network + +To create a multi-device Thread network: + +1. Start the Leader node first (using LeaderNode example) +2. Start Router/Child nodes (using this example) +3. All devices will form a mesh network +4. Routers extend network range and route messages +5. Children are end devices that can sleep + +## Code Structure + +The RouterNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Configures the device to join an existing network using CLI Helper Functions: + - `OThreadCLI.println()` - Sends CLI commands + - Commands: "dataset clear", "dataset networkkey", "dataset channel", "dataset commit active", "ifconfig up", "thread start" + +2. **`loop()`**: + - Checks if device role is Router or Child using `OpenThread.otGetDeviceRole()` + - Displays network information using native OpenThread API calls: + - `otThreadGetNetworkName()` - Network name + - `otLinkGetChannel()` - Channel + - `otLinkGetPanId()` - PAN ID + - `otThreadGetExtendedPanId()` - Extended PAN ID + - `otThreadGetNetworkKey()` - Network key + - `otIp6GetUnicastAddresses()` - Unicast IPv6 addresses + - `otIp6GetMulticastAddresses()` - Multicast IPv6 addresses + - Updates every 5 seconds + +## Troubleshooting + +- **Device not joining network**: Ensure the Leader node is running first. Verify network key and channel match the Leader exactly. +- **Role stuck as "Detached"**: Wait a few seconds for the device to join. Check that network key and channel match the Leader. +- **Network key/channel mismatch**: Double-check that both Leader and Router/Child nodes use identical network key and channel values. +- **No network information**: Wait for the device to join the network (may take 10-30 seconds) +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/RouterNode.ino b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/RouterNode.ino index f802bd7ef01..e06832a5cfc 100644 --- a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/RouterNode.ino +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/RouterNode.ino @@ -27,8 +27,8 @@ #include "OThreadCLI.h" #include "OThreadCLI_Util.h" -#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" -#define CLI_NETWORK_CHANEL "dataset channel 24" +#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANNEL "dataset channel 24" otInstance *aInstance = NULL; @@ -43,7 +43,7 @@ void setup() { OThreadCLI.println("dataset clear"); OThreadCLI.println(CLI_NETWORK_KEY); - OThreadCLI.println(CLI_NETWORK_CHANEL); + OThreadCLI.println(CLI_NETWORK_CHANNEL); OThreadCLI.println("dataset commit active"); OThreadCLI.println("ifconfig up"); OThreadCLI.println("thread start"); diff --git a/libraries/OpenThread/examples/CLI/ThreadScan/README.md b/libraries/OpenThread/examples/CLI/ThreadScan/README.md new file mode 100644 index 00000000000..def249163bd --- /dev/null +++ b/libraries/OpenThread/examples/CLI/ThreadScan/README.md @@ -0,0 +1,137 @@ +# OpenThread Thread Scan Example + +This example demonstrates how to scan for IEEE 802.15.4 devices and Thread networks using OpenThread CLI commands.\ +The application continuously scans for nearby devices and Thread networks, showing both raw IEEE 802.15.4 scans and Thread-specific discovery scans. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(true)` which automatically starts a Thread network, required for Thread discovery scans. + +## Features + +- IEEE 802.15.4 device scanning (works even when Thread is not started) +- Thread network discovery scanning (requires device to be in Child, Router, or Leader state) +- Continuous scanning with configurable intervals +- Demonstrates CLI Helper Functions API for scanning +- Useful for network discovery and debugging + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example automatically starts a Thread network for discovery scanning. + +## Building and Flashing + +1. Open the `ThreadScan.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +This sketch will continuously scan the Thread Local Network and all devices IEEE 802.15.4 compatible + +Scanning for nearby IEEE 802.15.4 devices: +| J | Network Name | Extended PAN | PAN | MAC Address | Ch | dBm | LQI | ++---+------------------+------------------+------+------------------+----+-----+-----+ +| 0 | OpenThread-ESP | dead00beef00cafe | 1234 | 1234567890abcdef | 24 | -45 | 255 | +Done + +Scanning MLE Discover: +| J | Network Name | Extended PAN | PAN | MAC Address | Ch | dBm | LQI | ++---+------------------+------------------+------+------------------+----+-----+-----+ +| 0 | OpenThread-ESP | dead00beef00cafe | 1234 | 1234567890abcdef | 24 | -45 | 255 | +Done +``` + +## Using the Device + +### Scanning Behavior + +The example performs two types of scans: + +1. **IEEE 802.15.4 Scan**: + - Scans for all IEEE 802.15.4 compatible devices in the area + - Works even when the device is not part of a Thread network + - Shows devices on all channels + +2. **Thread Discovery Scan (MLE Discover)**: + - Scans for Thread networks specifically + - Only works when the device is in Child, Router, or Leader state + - Shows Thread networks with their network names and parameters + +### Scan Results + +The scan results show: +- **J**: Joinable flag (1 = can join, 0 = cannot join) +- **Network Name**: Thread network name +- **Extended PAN**: Extended PAN ID +- **PAN**: PAN ID +- **MAC Address**: Device MAC address +- **Ch**: Channel +- **dBm**: Signal strength in dBm +- **LQI**: Link Quality Indicator + +### Continuous Scanning + +The example continuously scans: +- IEEE 802.15.4 scan every 5 seconds +- Thread discovery scan every 5 seconds (only if device is in Thread network) + +## Code Structure + +The ThreadScan example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(true)` (auto-start required for discovery) + - Initializes OpenThread CLI + - Sets CLI timeout to 100 ms using `OThreadCLI.setTimeout()` + +2. **`loop()`**: + - Performs IEEE 802.15.4 scan using `otPrintRespCLI("scan", Serial, 3000)` + - Checks if device is in Thread network (Child, Router, or Leader) + - If in network, performs Thread discovery scan using `otPrintRespCLI("discover", Serial, 3000)` + - Waits 5 seconds between scan cycles + +## Troubleshooting + +- **No scan results**: Ensure there are Thread devices nearby. Check that other devices are running and on the same channel. +- **Discovery scan not working**: Wait for the device to join a Thread network (should become Child, Router, or Leader) +- **Scan timeout**: Increase the timeout value in `otPrintRespCLI()` if scans are taking longer +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/CLI/onReceive/README.md b/libraries/OpenThread/examples/CLI/onReceive/README.md new file mode 100644 index 00000000000..c2f43729aaf --- /dev/null +++ b/libraries/OpenThread/examples/CLI/onReceive/README.md @@ -0,0 +1,130 @@ +# OpenThread CLI onReceive Callback Example + +This example demonstrates how to use the OpenThread CLI callback mechanism to capture and process CLI responses asynchronously.\ +The application shows how to set up a callback function that processes CLI responses line by line, allowing non-blocking CLI interaction. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin()` which automatically starts a Thread network with default settings. + +## Features + +- CLI response callback using `OpenThreadCLI.onReceive()` +- Asynchronous CLI response processing +- Non-blocking CLI command execution +- Demonstrates callback-based CLI interaction pattern +- Automatic Thread network startup with default settings +- Device role monitoring via CLI + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example automatically starts a Thread network with default settings. + +## Building and Flashing + +1. Open the `onReceive.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +OpenThread CLI RESP===> disabled +OpenThread CLI RESP===> disabled +OpenThread CLI RESP===> detached +OpenThread CLI RESP===> child +OpenThread CLI RESP===> router +OpenThread CLI RESP===> router +... +``` + +The callback function processes each line of CLI response, showing the device state transitions from "disabled" to "detached" to "child" to "router" (or "leader"). + +## Using the Device + +### Callback Mechanism + +The example demonstrates the callback-based CLI interaction pattern: + +1. **Callback Registration**: `OThreadCLI.onReceive(otReceivedLine)` registers a callback function +2. **Command Execution**: `OThreadCLI.println("state")` sends CLI commands +3. **Response Processing**: The callback function `otReceivedLine()` processes responses asynchronously +4. **Non-blocking**: The main loop continues while CLI responses are processed in the callback + +### Device State Monitoring + +The example continuously monitors the device state: +- Sends "state" command every second +- Callback processes the response +- Shows state transitions as the device joins the Thread network + +### Customizing the Callback + +You can modify the `otReceivedLine()` function to: +- Parse specific CLI responses +- Extract data from CLI output +- Trigger actions based on CLI responses +- Filter or process specific response patterns + +## Code Structure + +The onReceive example consists of the following main components: + +1. **`otReceivedLine()` callback function**: + - Reads all available data from OpenThread CLI + - Filters out empty lines (EOL sequences) + - Prints non-empty lines with a prefix + +2. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin()` (auto-start) + - Initializes OpenThread CLI + - Registers the callback function using `OThreadCLI.onReceive(otReceivedLine)` + +3. **`loop()`**: + - Sends "state" CLI command every second using `OThreadCLI.println("state")` + - The callback function processes the response asynchronously + - Non-blocking operation allows other tasks to run + +## Troubleshooting + +- **No callback responses**: Ensure the callback is registered in setup. Check that OpenThread CLI is initialized. +- **Empty lines in output**: The callback filters empty lines, which is normal behavior +- **State not changing**: Wait for the device to join the Thread network. First device becomes Leader, subsequent devices become Router or Child. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md new file mode 100644 index 00000000000..37fbe871033 --- /dev/null +++ b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md @@ -0,0 +1,183 @@ +# OpenThread Leader Node Example (Native API) + +This example demonstrates how to create an OpenThread Leader node using the Classes API (native OpenThread API).\ +The Leader node is the first device in a Thread network that manages the network and assigns router IDs. This example shows how to configure a Leader node using the `OpenThread` and `DataSet` classes. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses the Classes API (`OpenThread` and `DataSet` classes) instead of CLI Helper Functions. +- This example uses `OpenThread.begin(false)` which does not use NVS dataset information, allowing fresh configuration. + +## Features + +- Leader node configuration using Classes API +- Dataset creation and configuration using `DataSet` class +- Network information display using `OpenThread` class methods +- IPv6 address management (unicast and multicast) +- Address cache management on role changes +- Comprehensive network status monitoring + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network configuration: + +```cpp +dataset.setNetworkName("ESP_OpenThread"); +dataset.setChannel(15); +dataset.setPanId(0x1234); +uint8_t networkKey[OT_NETWORK_KEY_SIZE] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; +dataset.setNetworkKey(networkKey); +``` + +**Important:** +- The network key must be a 16-byte array +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) +- All devices in the same network must use the same network key and channel +- Extended PAN ID should be unique for your network + +## Building and Flashing + +1. Open the `LeaderNode.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +============================================== +OpenThread Network Information: +Role: Leader +RLOC16: 0x0000 +Network Name: ESP_OpenThread +Channel: 15 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:0 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:0 + +--- Unicast Addresses (Using Count + Index API) --- + [0]: fd00:db8:a0:0:0:ff:fe00:0 + [1]: fe80:0:0:0:0:ff:fe00:0 + +--- Multicast Addresses (Using std::vector API) --- + [0]: ff02::1 + [1]: ff03::1 + [2]: ff03::fc +... +``` + +## Using the Device + +### Leader Node Setup + +The Leader node is automatically configured in `setup()` using the Classes API: + +1. **Initialize OpenThread**: `threadLeaderNode.begin(false)` - Starts OpenThread stack without using NVS +2. **Create dataset**: `dataset.initNew()` - Creates a new complete dataset +3. **Configure dataset**: Sets network name, extended PAN ID, network key, channel, and PAN ID +4. **Apply dataset**: `threadLeaderNode.commitDataSet(dataset)` - Applies the dataset +5. **Start network**: `threadLeaderNode.networkInterfaceUp()` and `threadLeaderNode.start()` - Starts the Thread network + +### Network Information + +The `loop()` function displays comprehensive network information using Classes API methods: +- Device role and RLOC16 +- Network name, channel, PAN ID +- Extended PAN ID and network key +- IPv6 addresses (Mesh Local EID, Leader RLOC, Node RLOC) +- Unicast addresses (using count + index API) +- Multicast addresses (using std::vector API) + +### Address Cache Management + +The example demonstrates address cache management: +- Clears address cache when device role changes +- Tracks role changes to optimize address resolution + +### Joining Other Devices + +To join other devices to this network: +1. Use the same network key and channel in the Router/Child node examples +2. Start the Leader node first +3. Then start the Router/Child nodes + +## Code Structure + +The LeaderNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Creates and configures a `DataSet` object: + - `dataset.initNew()` - Initialize new dataset + - `dataset.setNetworkName()` - Set network name + - `dataset.setExtendedPanId()` - Set extended PAN ID + - `dataset.setNetworkKey()` - Set network key + - `dataset.setChannel()` - Set channel + - `dataset.setPanId()` - Set PAN ID + - Applies dataset: `threadLeaderNode.commitDataSet(dataset)` + - Starts network: `threadLeaderNode.networkInterfaceUp()` and `threadLeaderNode.start()` + +2. **`loop()`**: + - Gets current device role using `threadLeaderNode.otGetDeviceRole()` + - Displays network information using Classes API methods: + - `threadLeaderNode.otGetStringDeviceRole()` - Device role as string + - `threadLeaderNode.getRloc16()` - RLOC16 + - `threadLeaderNode.getNetworkName()` - Network name + - `threadLeaderNode.getChannel()` - Channel + - `threadLeaderNode.getPanId()` - PAN ID + - `threadLeaderNode.getExtendedPanId()` - Extended PAN ID + - `threadLeaderNode.getNetworkKey()` - Network key + - `threadLeaderNode.getMeshLocalEid()` - Mesh Local EID + - `threadLeaderNode.getLeaderRloc()` - Leader RLOC + - `threadLeaderNode.getRloc()` - Node RLOC + - `threadLeaderNode.getUnicastAddressCount()` and `threadLeaderNode.getUnicastAddress(i)` - Unicast addresses + - `threadLeaderNode.getAllMulticastAddresses()` - Multicast addresses + - Manages address cache on role changes + - Updates every 5 seconds + +## Troubleshooting + +- **Device not becoming Leader**: Ensure this is the first device started, or clear NVS to start fresh +- **Network key/channel mismatch**: Verify all devices use the same network key and channel +- **No network information**: Wait for the device to become Leader (may take a few seconds) +- **Address cache issues**: The example automatically clears cache on role changes +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Dataset API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_dataset.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md new file mode 100644 index 00000000000..90a56db2e69 --- /dev/null +++ b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md @@ -0,0 +1,174 @@ +# OpenThread Router/Child Node Example (Native API) + +This example demonstrates how to create an OpenThread Router or Child node that joins an existing Thread network using the Classes API (native OpenThread API).\ +The Router/Child node joins a network created by a Leader node and can route messages or operate as an end device. This example shows how to configure a Router/Child node using the `OpenThread` and `DataSet` classes. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses the Classes API (`OpenThread` and `DataSet` classes) instead of CLI Helper Functions. +- This example uses `OpenThread.begin(false)` which does not use NVS dataset information, allowing fresh configuration. +- **Important:** A Leader node must be running before starting this Router/Child node. + +## Features + +- Router/Child node configuration using Classes API +- Dataset configuration using `DataSet` class +- Joins an existing Thread network created by a Leader node +- Network information display using `OpenThread` class methods +- Active dataset retrieval and display +- Comprehensive network status monitoring + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication +- A Leader node must be running on the same network + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, configure the network parameters to match the Leader node: + +```cpp +uint8_t networkKey[OT_NETWORK_KEY_SIZE] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; +dataset.setNetworkKey(networkKey); +``` + +**Important:** +- The network key **must match** the Leader node's network key exactly +- The network key must be a 16-byte array +- Only the network key is required to join (other parameters are learned from the Leader) +- **Start the Leader node first** before starting this Router/Child node + +## Building and Flashing + +1. **First, start the Leader node** using the LeaderNode example (Native API) +2. Open the `RouterNode.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +============================================== +OpenThread Network Information (Active Dataset): +Role: Router +RLOC16: 0xfc00 +Network Name: ESP_OpenThread +Channel: 15 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:fc00 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:fc00 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +``` + +The device will join as either a **Router** (if network needs more routers) or **Child** (end device). + +## Using the Device + +### Router/Child Node Setup + +The Router/Child node is automatically configured in `setup()` using the Classes API: + +1. **Initialize OpenThread**: `threadChildNode.begin(false)` - Starts OpenThread stack without using NVS +2. **Clear dataset**: `dataset.clear()` - Clears any existing dataset +3. **Configure dataset**: Sets only the network key (must match Leader) +4. **Apply dataset**: `threadChildNode.commitDataSet(dataset)` - Applies the dataset +5. **Start network**: `threadChildNode.networkInterfaceUp()` and `threadChildNode.start()` - Starts the Thread network and joins existing network + +### Network Information + +The `loop()` function displays network information using Classes API methods: +- Device role and RLOC16 +- Active dataset information (retrieved using `threadChildNode.getCurrentDataSet()`): + - Network name, channel, PAN ID + - Extended PAN ID and network key +- Runtime information: + - Mesh Local EID, Node RLOC, Leader RLOC + +### Active Dataset Retrieval + +This example demonstrates how to retrieve the active dataset: +- Uses `threadChildNode.getCurrentDataSet()` to get the current active dataset +- Displays dataset parameters that were learned from the Leader node +- Shows that only the network key needs to be configured to join + +### Multi-Device Network + +To create a multi-device Thread network: + +1. Start the Leader node first (using Native API LeaderNode example) +2. Start Router/Child nodes (using this example) +3. All devices will form a mesh network +4. Routers extend network range and route messages +5. Children are end devices that can sleep + +## Code Structure + +The RouterNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Creates and configures a `DataSet` object: + - `dataset.clear()` - Clear existing dataset + - `dataset.setNetworkKey()` - Set network key (must match Leader) + - Applies dataset: `threadChildNode.commitDataSet(dataset)` + - Starts network: `threadChildNode.networkInterfaceUp()` and `threadChildNode.start()` + +2. **`loop()`**: + - Gets current device role using `threadChildNode.otGetDeviceRole()` + - Retrieves active dataset using `threadChildNode.getCurrentDataSet()` + - Displays network information using Classes API methods: + - `threadChildNode.otGetStringDeviceRole()` - Device role as string + - `threadChildNode.getRloc16()` - RLOC16 + - `activeDataset.getNetworkName()` - Network name from dataset + - `activeDataset.getChannel()` - Channel from dataset + - `activeDataset.getPanId()` - PAN ID from dataset + - `activeDataset.getExtendedPanId()` - Extended PAN ID from dataset + - `activeDataset.getNetworkKey()` - Network key from dataset + - `threadChildNode.getMeshLocalEid()` - Mesh Local EID + - `threadChildNode.getRloc()` - Node RLOC + - `threadChildNode.getLeaderRloc()` - Leader RLOC + - Updates every 5 seconds + +## Troubleshooting + +- **Device not joining network**: Ensure the Leader node is running first. Verify network key matches the Leader exactly. +- **Role stuck as "Detached"**: Wait a few seconds for the device to join. Check that network key matches the Leader. +- **Network key mismatch**: Double-check that both Leader and Router/Child nodes use identical network key values. +- **No network information**: Wait for the device to join the network (may take 10-30 seconds) +- **Active dataset empty**: Ensure device has successfully joined the network before checking dataset +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Dataset API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_dataset.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. From 6a1bec63d92fda8f0ea44123986f7901bec92bf3 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Mon, 10 Nov 2025 09:33:38 -0300 Subject: [PATCH 16/23] feat(serial_uart): adds Serial (UART) documentation (#11993) * feat(serial_uart): adds main Serial documentation * feat(serial_uart): improves Serial documentation * fix(serial): fixes example session headers Removed redundant section headers for example applications. * fix(serial): docs refer to ESP-IDF instead of IDF * fix(serial): restores necessary example reference * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- docs/en/api/serial.rst | 667 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 667 insertions(+) create mode 100644 docs/en/api/serial.rst diff --git a/docs/en/api/serial.rst b/docs/en/api/serial.rst new file mode 100644 index 00000000000..69f9969196d --- /dev/null +++ b/docs/en/api/serial.rst @@ -0,0 +1,667 @@ +############# +Serial (UART) +############# + +About +----- +The Serial (UART - Universal Asynchronous Receiver-Transmitter) peripheral provides asynchronous serial communication, +allowing the ESP32 to communicate with other devices such as computers, sensors, displays, and other microcontrollers. + +UART is a simple, two-wire communication protocol that uses a TX (transmit) and RX (receive) line for full-duplex communication. +The ESP32 Arduino implementation provides a HardwareSerial class that is compatible with the standard Arduino Serial API, +with additional features for advanced use cases. + +**Key Features:** + +* **Full-duplex communication**: Simultaneous transmission and reception +* **Configurable baud rates**: From 300 to 5,000,000+ baud +* **Multiple data formats**: Configurable data bits, parity, and stop bits +* **Hardware flow control**: Support for RTS/CTS signals +* **RS485 support**: Half-duplex RS485 communication mode +* **Low-power UART**: Some SoCs support LP (Low-Power) UART for ultra-low power applications +* **Baud rate detection**: Automatic baud rate detection (ESP32, ESP32-S2 only) +* **Event callbacks**: Receive and error event callbacks +* **Configurable buffers**: Adjustable RX and TX buffer sizes + +UART Availability +----------------- + +The number of UART peripherals available varies by ESP32 SoC: + +========= ======== ======== +ESP32 SoC HP UARTs LP UARTs +========= ======== ======== +ESP32 3 0 +ESP32-S2 2 0 +ESP32-S3 3 0 +ESP32-C3 2 0 +ESP32-C5 2 1 +ESP32-C6 2 1 +ESP32-H2 2 0 +ESP32-P4 5 1 +========= ======== ======== + +**Note:** +* HP (High-Performance) UARTs are the standard UART peripherals +* LP (Low-Power) UARTs are available on some SoCs for ultra-low power applications +* UART0 is typically used for programming and debug output (Serial Monitor) +* Additional UARTs (Serial1, Serial2, etc.) are available for general-purpose communication, including LP UARTs when available. The ESP32 Arduino Core automatically creates HardwareSerial objects for all available UARTs: + + * ``Serial0`` (or ``Serial``) - UART0 (HP UART, typically used for programming and debug output) + * ``Serial1``, ``Serial2``, etc. - Additional HP UARTs (numbered sequentially) + * Additional Serial objects - LP UARTs, when available (numbered after HP UARTs) + + **Example:** The ESP32-C6 has 2 HP UARTs and 1 LP UART. The Arduino Core creates ``Serial0`` and ``Serial1`` (HP UARTs) plus ``Serial2`` (LP UART) HardwareSerial objects. + + **Important:** LP UARTs can be used as regular UART ports, but they have fixed GPIO pins for RX, TX, CTS, and RTS. It is not possible to change the pins for LP UARTs using ``setPins()``. + +Arduino-ESP32 Serial API +------------------------ + +begin +***** + +Initializes the Serial port with the specified baud rate and configuration. + +.. code-block:: arduino + + void begin(unsigned long baud, uint32_t config = SERIAL_8N1, int8_t rxPin = -1, int8_t txPin = -1, bool invert = false, unsigned long timeout_ms = 20000UL, uint8_t rxfifo_full_thrhd = 120); + +* ``baud`` - Baud rate (bits per second). Common values: 9600, 115200, 230400, etc. + + **Special value:** ``0`` enables baud rate detection (ESP32, ESP32-S2 only). The function will attempt to detect the baud rate for up to ``timeout_ms`` milliseconds. See the :ref:`Baud Rate Detection Example ` for usage details. +* ``config`` - Serial configuration (data bits, parity, stop bits): + + * ``SERIAL_8N1`` - 8 data bits, no parity, 1 stop bit (default) + * ``SERIAL_8N2`` - 8 data bits, no parity, 2 stop bits + * ``SERIAL_8E1`` - 8 data bits, even parity, 1 stop bit + * ``SERIAL_8E2`` - 8 data bits, even parity, 2 stop bits + * ``SERIAL_8O1`` - 8 data bits, odd parity, 1 stop bit + * ``SERIAL_8O2`` - 8 data bits, odd parity, 2 stop bits + * ``SERIAL_7N1``, ``SERIAL_7N2``, ``SERIAL_7E1``, ``SERIAL_7E2``, ``SERIAL_7O1``, ``SERIAL_7O2`` - 7 data bits variants + * ``SERIAL_6N1``, ``SERIAL_6N2``, ``SERIAL_6E1``, ``SERIAL_6E2``, ``SERIAL_6O1``, ``SERIAL_6O2`` - 6 data bits variants + * ``SERIAL_5N1``, ``SERIAL_5N2``, ``SERIAL_5E1``, ``SERIAL_5E2``, ``SERIAL_5O1``, ``SERIAL_5O2`` - 5 data bits variants + +* ``rxPin`` - RX pin number. Use ``-1`` to keep the default pin or current pin assignment. + +* ``txPin`` - TX pin number. Use ``-1`` to keep the default pin or current pin assignment. + +* ``invert`` - If ``true``, inverts the RX and TX signal polarity. + +* ``timeout_ms`` - Timeout in milliseconds for baud rate detection (when ``baud = 0``). Default: 20000 ms (20 seconds). + +* ``rxfifo_full_thrhd`` - RX FIFO full threshold (1-127 bytes). When the FIFO reaches this threshold, data is copied to the RX buffer. Default: 120 bytes. + +**Example:** + +.. code-block:: arduino + + // Basic initialization with default pins + Serial.begin(115200); + + // Initialize with custom pins + Serial1.begin(9600, SERIAL_8N1, 4, 5); + + // Initialize with baud rate detection (ESP32, ESP32-S2 only) + Serial.begin(0, SERIAL_8N1, -1, -1, false, 20000); + +end +*** + +Stops the Serial port and releases all resources. + +.. code-block:: arduino + + void end(void); + +This function disables the UART peripheral and frees all associated resources. + +available +********* + +Returns the number of bytes available for reading from the Serial port. + +.. code-block:: arduino + + int available(void); + +**Returns:** The number of bytes available in the RX buffer, or ``0`` if no data is available. + +**Example:** + +.. code-block:: arduino + + if (Serial.available() > 0) { + char data = Serial.read(); + } + +availableForWrite +***************** + +Returns the number of bytes that can be written to the Serial port without blocking. + +.. code-block:: arduino + + int availableForWrite(void); + +**Returns:** The number of bytes that can be written to the TX buffer without blocking. + +read +**** + +Reads a single byte from the Serial port. + +.. code-block:: arduino + + int read(void); + +**Returns:** The byte read (0-255), or ``-1`` if no data is available. + +**Example:** + +.. code-block:: arduino + + int data = Serial.read(); + if (data != -1) { + Serial.printf("Received: %c\n", data); + } + +read (buffer) +************* + +Reads multiple bytes from the Serial port into a buffer. + +.. code-block:: arduino + + size_t read(uint8_t *buffer, size_t size); + size_t read(char *buffer, size_t size); + +* ``buffer`` - Pointer to the buffer where data will be stored +* ``size`` - Maximum number of bytes to read + +**Returns:** The number of bytes actually read. + +**Example:** + +.. code-block:: arduino + + uint8_t buffer[64]; + size_t bytesRead = Serial.read(buffer, sizeof(buffer)); + Serial.printf("Read %d bytes\n", bytesRead); + +readBytes +********* + +Reads multiple bytes from the Serial port, blocking until the specified number of bytes is received or timeout occurs. + +.. code-block:: arduino + + size_t readBytes(uint8_t *buffer, size_t length); + size_t readBytes(char *buffer, size_t length); + +* ``buffer`` - Pointer to the buffer where data will be stored +* ``length`` - Number of bytes to read + +**Returns:** The number of bytes actually read (may be less than ``length`` if timeout occurs). + +**Note:** This function overrides ``Stream::readBytes()`` for better performance using ESP-IDF functions. + +write +***** + +Writes data to the Serial port. + +.. code-block:: arduino + + size_t write(uint8_t); + size_t write(const uint8_t *buffer, size_t size); + size_t write(const char *buffer, size_t size); + size_t write(const char *s); + size_t write(unsigned long n); + size_t write(long n); + size_t write(unsigned int n); + size_t write(int n); + +* Single byte: ``write(uint8_t)`` - Writes a single byte +* Buffer: ``write(buffer, size)`` - Writes multiple bytes from a buffer +* String: ``write(const char *s)`` - Writes a null-terminated string +* Number: ``write(n)`` - Writes a number as a single byte + +**Returns:** The number of bytes written. + +**Example:** + +.. code-block:: arduino + + Serial.write('A'); + Serial.write("Hello"); + Serial.write(buffer, 10); + Serial.write(65); // Writes byte value 65 + +peek +**** + +Returns the next byte in the RX buffer without removing it. + +.. code-block:: arduino + + int peek(void); + +**Returns:** The next byte (0-255), or ``-1`` if no data is available. + +**Note:** Unlike ``read()``, ``peek()`` does not remove the byte from the buffer. + +flush +***** + +Waits for all data in the TX buffer to be transmitted. + +.. code-block:: arduino + + void flush(void); + void flush(bool txOnly); + +* ``txOnly`` - If ``true``, only flushes the TX buffer. If ``false`` (default), also clears the RX buffer. + +**Note:** This function blocks until all data in the TX buffer has been sent. + +baudRate +******** + +Returns the current baud rate of the Serial port. + +.. code-block:: arduino + + uint32_t baudRate(void); + +**Returns:** The configured baud rate in bits per second. + +**Note:** When using baud rate detection (``begin(0)``), this function returns the detected baud rate, which may be slightly rounded (e.g., 115200 may return 115201). + +updateBaudRate +************** + +Updates the baud rate of an already initialized Serial port. + +.. code-block:: arduino + + void updateBaudRate(unsigned long baud); + +* ``baud`` - New baud rate + +**Note:** This function can be called after ``begin()`` to change the baud rate without reinitializing the port. + +setPins +******* + +Sets or changes the RX, TX, CTS, and RTS pins for the Serial port. + +.. code-block:: arduino + + bool setPins(int8_t rxPin, int8_t txPin, int8_t ctsPin = -1, int8_t rtsPin = -1); + +* ``rxPin`` - RX pin number. Use ``-1`` to keep current pin. +* ``txPin`` - TX pin number. Use ``-1`` to keep current pin. +* ``ctsPin`` - CTS (Clear To Send) pin for hardware flow control. Use ``-1`` to keep current pin or disable. +* ``rtsPin`` - RTS (Request To Send) pin for hardware flow control. Use ``-1`` to keep current pin or disable. + +**Returns:** ``true`` if pins are set successfully, ``false`` otherwise. + +**Note:** This function can be called before or after ``begin()``. When pins are changed, the previous pins are automatically detached. + +setRxBufferSize +*************** + +Sets the size of the RX buffer. + +.. code-block:: arduino + + size_t setRxBufferSize(size_t new_size); + +* ``new_size`` - New RX buffer size in bytes + +**Returns:** The actual buffer size set, or ``0`` on error. + +**Note:** This function must be called **before** ``begin()`` to take effect. Default RX buffer size is 256 bytes. + +setTxBufferSize +*************** + +Sets the size of the TX buffer. + +.. code-block:: arduino + + size_t setTxBufferSize(size_t new_size); + +* ``new_size`` - New TX buffer size in bytes + +**Returns:** The actual buffer size set, or ``0`` on error. + +**Note:** This function must be called **before** ``begin()`` to take effect. Default TX buffer size is 0 (no buffering). + +setRxTimeout +************ + +Sets the RX timeout threshold in UART symbol periods. + +.. code-block:: arduino + + bool setRxTimeout(uint8_t symbols_timeout); + +* ``symbols_timeout`` - Timeout threshold in UART symbol periods. Setting ``0`` disables timeout-based callbacks. + + The timeout is calculated based on the current baud rate and serial configuration. For example: + + * For ``SERIAL_8N1`` (10 bits per symbol), a timeout of 3 symbols at 9600 baud = 3 / (9600 / 10) = 3.125 ms + * Maximum timeout is calculated automatically by ESP-IDF based on the serial configuration + +**Returns:** ``true`` if timeout is set successfully, ``false`` otherwise. + +**Note:** +* When RX timeout occurs, the ``onReceive()`` callback is triggered +* For ESP32 and ESP32-S2, when using REF_TICK clock source (baud rates ≤ 250000), RX timeout is limited to 1 symbol +* To use higher RX timeout values on ESP32/ESP32-S2, set the clock source to APB using ``setClockSource(UART_CLK_SRC_APB)`` before ``begin()`` + +setRxFIFOFull +************* + +Sets the RX FIFO full threshold that triggers data transfer from FIFO to RX buffer. + +.. code-block:: arduino + + bool setRxFIFOFull(uint8_t fifoBytes); + +* ``fifoBytes`` - Number of bytes (1-127) that will trigger the FIFO full interrupt + + When the UART FIFO reaches this threshold, data is copied to the RX buffer and the ``onReceive()`` callback is triggered. + +**Returns:** ``true`` if threshold is set successfully, ``false`` otherwise. + +**Note:** +* Lower values (e.g., 1) provide byte-by-byte reception but consume more CPU time +* Higher values (e.g., 120) provide better performance but introduce latency +* Default value depends on baud rate: 1 byte for ≤ 115200 baud, 120 bytes for > 115200 baud + +onReceive +********* + +Sets a callback function that is called when data is received. + +.. code-block:: arduino + + void onReceive(OnReceiveCb function, bool onlyOnTimeout = false); + +* ``function`` - Callback function to call when data is received. Use ``NULL`` to disable the callback. +* ``onlyOnTimeout`` - If ``true``, callback is only called on RX timeout. If ``false`` (default), callback is called on both FIFO full and RX timeout events. + +**Callback Signature:** + +.. code-block:: arduino + + typedef std::function OnReceiveCb; + +**Note:** +* When ``onlyOnTimeout = false``, the callback is triggered when FIFO reaches the threshold (set by ``setRxFIFOFull()``) or on RX timeout +* When ``onlyOnTimeout = true``, the callback is only triggered on RX timeout, ensuring all data in a stream is available at once +* Using ``onlyOnTimeout = true`` may cause RX overflow if the RX buffer size is too small for the incoming data stream +* The callback is executed in a separate task, allowing non-blocking data processing + +**Example:** + +.. code-block:: arduino + + void onReceiveCallback() { + while (Serial1.available()) { + char c = Serial1.read(); + Serial.print(c); + } + } + + void setup() { + Serial1.begin(115200); + Serial1.onReceive(onReceiveCallback); + } + +onReceiveError +************** + +Sets a callback function that is called when a UART error occurs. + +.. code-block:: arduino + + void onReceiveError(OnReceiveErrorCb function); + +* ``function`` - Callback function to call when an error occurs. Use ``NULL`` to disable the callback. + +**Callback Signature:** + +.. code-block:: arduino + + typedef std::function OnReceiveErrorCb; + +**Error Types:** + +* ``UART_NO_ERROR`` - No error +* ``UART_BREAK_ERROR`` - Break condition detected +* ``UART_BUFFER_FULL_ERROR`` - RX buffer is full +* ``UART_FIFO_OVF_ERROR`` - UART FIFO overflow +* ``UART_FRAME_ERROR`` - Frame error (invalid stop bit) +* ``UART_PARITY_ERROR`` - Parity error + +**Example:** + +.. code-block:: arduino + + void onErrorCallback(hardwareSerial_error_t error) { + Serial.printf("UART Error: %d\n", error); + } + + void setup() { + Serial1.begin(115200); + Serial1.onReceiveError(onErrorCallback); + } + +eventQueueReset +*************** + +Clears all events in the event queue (events that trigger ``onReceive()`` and ``onReceiveError()``). + +.. code-block:: arduino + + void eventQueueReset(void); + +This function can be useful in some use cases where you want to clear pending events. + +setHwFlowCtrlMode +***************** + +Enables or disables hardware flow control using RTS and/or CTS pins. + +.. code-block:: arduino + + bool setHwFlowCtrlMode(SerialHwFlowCtrl mode = UART_HW_FLOWCTRL_CTS_RTS, uint8_t threshold = 64); + +* ``mode`` - Hardware flow control mode: + + * ``UART_HW_FLOWCTRL_DISABLE`` (0x0) - Disable hardware flow control + * ``UART_HW_FLOWCTRL_RTS`` (0x1) - Enable RX hardware flow control (RTS) + * ``UART_HW_FLOWCTRL_CTS`` (0x2) - Enable TX hardware flow control (CTS) + * ``UART_HW_FLOWCTRL_CTS_RTS`` (0x3) - Enable full hardware flow control (default) + +* ``threshold`` - Flow control threshold (default: 64, which is half of the FIFO length) + +**Returns:** ``true`` if flow control mode is set successfully, ``false`` otherwise. + +**Note:** CTS and RTS pins must be set using ``setPins()`` before enabling hardware flow control. + +setMode +******* + +Sets the UART operating mode. + +.. code-block:: arduino + + bool setMode(SerialMode mode); + +* ``mode`` - UART mode: + + * ``UART_MODE_UART`` (0x00) - Regular UART mode (default) + * ``UART_MODE_RS485_HALF_DUPLEX`` (0x01) - Half-duplex RS485 mode (RTS pin controls transceiver) + * ``UART_MODE_IRDA`` (0x02) - IRDA UART mode + * ``UART_MODE_RS485_COLLISION_DETECT`` (0x03) - RS485 collision detection mode (for testing) + * ``UART_MODE_RS485_APP_CTRL`` (0x04) - Application-controlled RS485 mode (for testing) + +**Returns:** ``true`` if mode is set successfully, ``false`` otherwise. + +**Note:** For RS485 half-duplex mode, the RTS pin must be configured using ``setPins()`` to control the transceiver. + +setClockSource +************** + +Sets the UART clock source. Must be called **before** ``begin()`` to take effect. + +.. code-block:: arduino + + bool setClockSource(SerialClkSrc clkSrc); + +* ``clkSrc`` - Clock source: + + * ``UART_CLK_SRC_DEFAULT`` - Default clock source (varies by SoC) + * ``UART_CLK_SRC_APB`` - APB clock (ESP32, ESP32-S2, ESP32-C3, ESP32-S3) + * ``UART_CLK_SRC_PLL`` - PLL clock (ESP32-C2, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4) + * ``UART_CLK_SRC_XTAL`` - XTAL clock (ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-S3, ESP32-P4) + * ``UART_CLK_SRC_RTC`` - RTC clock (ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-S3, ESP32-P4) + * ``UART_CLK_SRC_REF_TICK`` - REF_TICK clock (ESP32, ESP32-S2) + +**Note:** +* Clock source availability varies by SoC. +* PLL frequency varies by SoC: ESP32-C2 (40 MHz), ESP32-H2 (48 MHz), ESP32-C5/C6/C61/P4 (80 MHz). +* ESP32-C5, ESP32-C6, ESP32-C61, and ESP32-P4 have LP UART that uses only RTC_FAST or XTAL/2 as clock source. +* For ESP32 and ESP32-S2, REF_TICK is used by default for baud rates ≤ 250000 to avoid baud rate changes when CPU frequency changes, but this limits RX timeout to 1 symbol. + +**Returns:** ``true`` if clock source is set successfully, ``false`` otherwise. + +setRxInvert +*********** + +Enables or disables RX signal inversion. + +.. code-block:: arduino + + bool setRxInvert(bool invert); + +* ``invert`` - If ``true``, inverts the RX signal polarity + +**Returns:** ``true`` if inversion is set successfully, ``false`` otherwise. + +setTxInvert +*********** + +Enables or disables TX signal inversion. + +.. code-block:: arduino + + bool setTxInvert(bool invert); + +* ``invert`` - If ``true``, inverts the TX signal polarity + +**Returns:** ``true`` if inversion is set successfully, ``false`` otherwise. + +setCtsInvert +************ + +Enables or disables CTS signal inversion. + +.. code-block:: arduino + + bool setCtsInvert(bool invert); + +* ``invert`` - If ``true``, inverts the CTS signal polarity + +**Returns:** ``true`` if inversion is set successfully, ``false`` otherwise. + +setRtsInvert +************ + +Enables or disables RTS signal inversion. + +.. code-block:: arduino + + bool setRtsInvert(bool invert); + +* ``invert`` - If ``true``, inverts the RTS signal polarity + +**Returns:** ``true`` if inversion is set successfully, ``false`` otherwise. + +setDebugOutput +************** + +Enables or disables debug output on this Serial port. + +.. code-block:: arduino + + void setDebugOutput(bool enable); + +* ``enable`` - If ``true``, enables debug output (ESP-IDF log messages will be sent to this Serial port) + +**Note:** By default, debug output is sent to UART0 (Serial0). + +operator bool +************* + +Returns whether the Serial port is initialized and ready. + +.. code-block:: arduino + + operator bool() const; + +**Returns:** ``true`` if the Serial port is initialized, ``false`` otherwise. + +**Example:** + +.. code-block:: arduino + + Serial1.begin(115200); + while (!Serial1) { + delay(10); // Wait for Serial1 to be ready + } + +Serial Configuration Constants +------------------------------ + +The following constants are used for serial configuration in the ``begin()`` function: + +Data Bits, Parity, Stop Bits +**************************** + +* ``SERIAL_5N1``, ``SERIAL_5N2``, ``SERIAL_5E1``, ``SERIAL_5E2``, ``SERIAL_5O1``, ``SERIAL_5O2`` - 5 data bits +* ``SERIAL_6N1``, ``SERIAL_6N2``, ``SERIAL_6E1``, ``SERIAL_6E2``, ``SERIAL_6O1``, ``SERIAL_6O2`` - 6 data bits +* ``SERIAL_7N1``, ``SERIAL_7N2``, ``SERIAL_7E1``, ``SERIAL_7E2``, ``SERIAL_7O1``, ``SERIAL_7O2`` - 7 data bits +* ``SERIAL_8N1``, ``SERIAL_8N2``, ``SERIAL_8E1``, ``SERIAL_8E2``, ``SERIAL_8O1``, ``SERIAL_8O2`` - 8 data bits + +Where: +* First number = data bits (5, 6, 7, or 8) +* Letter = parity: N (None), E (Even), O (Odd) +* Last number = stop bits (1 or 2) + +Example Applications +******************** + +.. _baud-rate-detection-example: + +Baud Rate Detection Example: + +.. literalinclude:: ../../../libraries/ESP32/examples/Serial/BaudRateDetect_Demo/BaudRateDetect_Demo.ino + :language: arduino + +OnReceive Callback Example: + +.. literalinclude:: ../../../libraries/ESP32/examples/Serial/OnReceive_Demo/OnReceive_Demo.ino + :language: arduino + +RS485 Communication Example: + +.. literalinclude:: ../../../libraries/ESP32/examples/Serial/RS485_Echo_Demo/RS485_Echo_Demo.ino + :language: arduino + +Complete list of `Serial examples `_. From c2789c6a126956e0a31f3c48254c4d113bc88224 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Mon, 10 Nov 2025 09:50:02 -0300 Subject: [PATCH 17/23] feat(openthread): adds arduino openthread library documentation (#11991) * feat(openthread): adds arduino openthread library documentation * fix(openthread): Fixes document formatting * fix(op * fix(openthread): gramma fix Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(openthread): gramma fix Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(othread): use esp-idf instead of just idf * ci(pre-commit): Apply automatic fixes * fix(othread):better phrasing Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(openthread): space before time unit * fix(openthread): space before time unit --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- docs/en/libraries.rst | 12 + docs/en/openthread/openthread.rst | 296 +++++++++++ docs/en/openthread/openthread_cli.rst | 580 ++++++++++++++++++++++ docs/en/openthread/openthread_core.rst | 579 +++++++++++++++++++++ docs/en/openthread/openthread_dataset.rst | 461 +++++++++++++++++ 5 files changed, 1928 insertions(+) create mode 100644 docs/en/openthread/openthread.rst create mode 100644 docs/en/openthread/openthread_cli.rst create mode 100644 docs/en/openthread/openthread_core.rst create mode 100644 docs/en/openthread/openthread_dataset.rst diff --git a/docs/en/libraries.rst b/docs/en/libraries.rst index daddca2b1d8..d9961d67b41 100644 --- a/docs/en/libraries.rst +++ b/docs/en/libraries.rst @@ -103,6 +103,18 @@ Matter APIs matter/matter_ep matter/ep_* +OpenThread APIs +--------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + openthread/openthread + openthread/openthread_cli + openthread/openthread_core + openthread/openthread_dataset + Zigbee APIs ----------- diff --git a/docs/en/openthread/openthread.rst b/docs/en/openthread/openthread.rst new file mode 100644 index 00000000000..9a72d035b2e --- /dev/null +++ b/docs/en/openthread/openthread.rst @@ -0,0 +1,296 @@ +########## +OpenThread +########## + +About +----- + +The OpenThread library provides support for creating Thread network devices using ESP32 SoCs with IEEE 802.15.4 radio support. The library offers two different programming interfaces for interacting with the OpenThread stack: + +* **Stream-based CLI enhanced with Helper Functions API**: Command-line interface helper functions that send OpenThread CLI commands and parse responses +* **Classes API**: Object-oriented classes that directly call OpenThread API functions + +The OpenThread library is built on top of `ESP OpenThread `_ and provides a high-level Arduino-style interface for creating Thread devices. + +Thread Protocol Overview +************************ + +Thread is an IPv6-based, low-power wireless mesh networking protocol designed for smart home and IoT applications. It provides secure, reliable, and scalable connectivity for battery-powered devices. + +**Key Features:** + +* **IPv6-based**: Native IPv6 addressing and routing +* **Mesh Networking**: Self-healing mesh topology with automatic routing +* **Low Power**: Optimized for battery-operated devices +* **Security**: Built-in security features including encryption and authentication +* **Scalability**: Supports up to 250+ devices per network +* **Reliability**: Automatic route discovery and self-healing capabilities + +Thread Network Topology +*********************** + +.. code-block:: text + + ┌─────────────────┐ + │ Internet │ + └─────────────────┘ + ▲ + │ + │ + ┌─────────────────┐ + │ Wi-Fi Router │ + │ │ + └─────────────────┘ + │ + ┌───────────────┴───────────────┐ + │ │ + ▼ ▼ + ┌───────────────────────┐ ┌──────────────────┐ + │ Other Wi-Fi Devices │ │ Thread Border │ + │ │ │ Router │ + └───────────────────────┘ └──────────────────┘ + │ + │ Thread Network + │ + ┌─────────────────────────┼─────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ + │ Thread Leader │◄─────►│ Thread Router │◄─────►│ Thread Child │ + │ │ │ │ │ │ + └─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + └──────────────────────────┴──────────────────────────┘ + Other Thread Nodes + + +**Thread Device Roles:** + +* **Leader**: Manages the Thread network, assigns router IDs, and maintains network state. This device should be powered by a wall adapter. +* **Router**: Extends network range, routes messages, maintains network topology. This device should be powered by a wall adapter. +* **Child**: End device that can sleep for extended periods (battery-powered devices). It can be powered by a battery or a wall adapter. +* **Detached**: Device not currently participating in a Thread network. +* **Disabled**: The Thread stack and interface are disabled. + +**Other Thread Network Devices:** + +* **Thread Border Router**: A device that connects a Thread network to other IP-based networks in the external world. The Thread Border Router is connected to both the Thread network and external IP networks (like a Wi-Fi router), enabling Thread devices to communicate with devices on other networks and the Internet. A Border Router can be implemented on a device with any Thread device role (Leader, Router, or Child). It can also act as a gateway to other protocols such as MQTT or Zigbee. + +OpenThread Library Structure +---------------------------- + +**The library provides two main programming interfaces:** + +* **CLI Helper Functions API**: Functions that interact with OpenThread through the CLI interface + * ``otGetRespCmd()``: Execute CLI command and get response + * ``otExecCommand()``: Execute CLI command with arguments + * ``otPrintRespCLI()``: Execute CLI command and print response to Stream + * ``OpenThreadCLI``: Stream-based CLI interface class + +* **Classes API**: Object-oriented classes that directly call OpenThread API functions + * ``OpenThread``: Main class for managing Thread network operations + * ``DataSet``: Class for managing Thread operational datasets + +OpenThread Class +**************** + +The ``OpenThread`` class is the main entry point for Thread operations using the Classes API. It provides direct access to OpenThread API functions for managing the Thread network. + +* **Network Management**: Starting, stopping, and managing the Thread network +* **Device Role Management**: Getting and monitoring device role (Leader, Router, Child, Detached, Disabled) +* **Dataset Management**: Setting and getting operational dataset parameters +* **Address Management**: Getting mesh-local addresses, RLOC, and multicast addresses +* **Network Information**: Getting network name, channel, PAN ID, and other network parameters + +The ``OpenThread`` class is implemented as a singleton, meaning there's only one instance available globally. You access it directly as ``OThread`` without creating an instance. + +.. toctree:: + :maxdepth: 2 + + openthread_core + +DataSet Class +************* + +The ``DataSet`` class provides a convenient way to manage Thread operational datasets. It allows you to create, configure, and apply operational datasets to the Thread network. + +* **Dataset Creation**: Create new operational datasets +* **Parameter Configuration**: Set network name, channel, PAN ID, network key, and extended PAN ID +* **Dataset Application**: Apply datasets to the Thread network +* **Dataset Retrieval**: Get current dataset parameters + +.. toctree:: + :maxdepth: 2 + + openthread_dataset + +OpenThreadCLI +************* + +The ``OpenThreadCLI`` class provides a Stream-based interface for interacting with the OpenThread CLI. It allows you to send CLI commands and receive responses programmatically. + +* **CLI Interface**: Stream-based interface for sending commands and receiving responses +* **Command Execution**: Execute OpenThread CLI commands programmatically +* **Response Handling**: Parse and handle CLI command responses +* **Console Mode**: Interactive console mode for debugging and testing + +.. toctree:: + :maxdepth: 2 + + openthread_cli + +CLI Helper Functions API +************************* + +The CLI Helper Functions API provides utility functions for executing OpenThread CLI commands and parsing responses. This API is useful when you need to interact with OpenThread through the CLI interface. + +* **Command Execution**: Execute CLI commands with arguments +* **Response Parsing**: Get and parse CLI command responses +* **Error Handling**: Handle CLI command errors and return codes + +**Key Functions:** + +* ``otGetRespCmd()``: Execute CLI command and get response string +* ``otExecCommand()``: Execute CLI command with arguments and error handling +* ``otPrintRespCLI()``: Execute CLI command and print response to Stream + +For detailed documentation on the CLI Helper Functions API, see the :doc:`openthread_cli` documentation. + +Supported Hardware +------------------ + +The OpenThread library requires ESP32 SoCs with IEEE 802.15.4 radio support: + +* **ESP32-H2**: Native Thread support with IEEE 802.15.4 radio +* **ESP32-C6**: Thread support with IEEE 802.15.4 radio (when Thread is enabled) +* **ESP32-C5**: Thread support with IEEE 802.15.4 radio (when Thread is enabled) + +**Note:** Thread support must be enabled in the ESP-IDF configuration (``CONFIG_OPENTHREAD_ENABLED``). This is done automatically when using the ESP32 Arduino OpenThread library. + +Common Problems and Issues +-------------------------- + +Troubleshooting +--------------- + +Common Issues +************* + +**Thread network not starting** + * Ensure the device has IEEE 802.15.4 radio support (ESP32-H2, ESP32-C6, ESP32-C5) + * Check that Thread is enabled in ESP-IDF configuration (``CONFIG_OPENTHREAD_ENABLED``) + * Verify that ``OpenThread::begin()`` is called before using Thread functions + * Check Serial Monitor for initialization errors + +**Device not joining network** + * Verify the operational dataset parameters (network name, network key, channel, PAN ID) + * Ensure the device is within range of the Thread network + * Check that the network key and extended PAN ID match the network you're trying to join + * Verify the device role is not "Detached" + +**CLI commands not working** + * Ensure ``OpenThreadCLI::begin()`` is called before using CLI functions + * Check that ``OpenThreadCLI::startConsole()`` is called with a valid Stream + * Verify the CLI is properly initialized and running + * Check Serial Monitor for CLI initialization errors + +**Address not available** + * Wait for the device to join the Thread network (role should be Child, Router, or Leader) + * Check that the network interface is up using ``networkInterfaceUp()`` + * Verify the device has obtained a mesh-local address + * Check network connectivity using ``getRloc()`` or ``getMeshLocalEid()`` + +**Dataset not applying** + * Ensure all required dataset parameters are set (network name, network key, channel) + * Verify the dataset is valid before applying + * Check that OpenThread is started before applying the dataset + * Verify the dataset parameters match the target network + +Initialization Order +******************** + +For proper initialization, follow this order: + +1. Initialize OpenThread stack: ``OpenThread::begin()`` +2. Initialize OpenThreadCLI (if using CLI): ``OpenThreadCLI::begin()`` +3. Start CLI console (if using CLI): ``OpenThreadCLI::startConsole()`` +4. Configure dataset (if needed): Create and configure ``DataSet`` +5. Apply dataset (if needed): ``OThread.commitDataSet(dataset)`` +6. Start Thread network: ``OThread.start()`` +7. Bring network interface up: ``OThread.networkInterfaceUp()`` + +Example +------- + +Basic OpenThread Setup +********************** + +Using the Classes API: + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread stack + OpenThread::begin(); + + // Wait for OpenThread to be ready + while (!OThread) { + delay(100); + } + + // Create and configure dataset + DataSet dataset; + dataset.initNew(); + dataset.setNetworkName("MyThreadNetwork"); + dataset.setChannel(15); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + // Print network information + OpenThread::otPrintNetworkInformation(Serial); + } + +Using the CLI Helper Functions API: + +.. code-block:: arduino + + #include + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread stack + OpenThread::begin(); + + // Initialize and start CLI + OThreadCLI.begin(); + OThreadCLI.startConsole(Serial); + + // Wait for CLI to be ready + while (!OThreadCLI) { + delay(100); + } + + // Execute CLI commands + char resp[256]; + if (otGetRespCmd("state", resp)) { + Serial.printf("Thread state: %s\r\n", resp); + } + + if (otExecCommand("networkname", "MyThreadNetwork", NULL)) { + Serial.println("Network name set successfully"); + } + + if (otExecCommand("ifconfig", "up", NULL)) { + Serial.println("Network interface up"); + } + } diff --git a/docs/en/openthread/openthread_cli.rst b/docs/en/openthread/openthread_cli.rst new file mode 100644 index 00000000000..1d598fb5063 --- /dev/null +++ b/docs/en/openthread/openthread_cli.rst @@ -0,0 +1,580 @@ +############## +OpenThread CLI +############## + +About +----- + +The OpenThread CLI (Command-Line Interface) provides two ways to interact with the OpenThread stack through CLI commands: + +* **CLI Helper Functions API**: Utility functions that execute CLI commands and parse responses +* **OpenThreadCLI Class**: Stream-based interface for interactive CLI access + +The CLI Helper Functions API is useful for programmatic control using OpenThread CLI commands, while the ``OpenThreadCLI`` class provides a Stream interface for interactive console access. + +CLI Helper Functions API +************************ + +The CLI Helper Functions API consists of utility functions that execute OpenThread CLI commands and handle responses. These functions interact with the OpenThread CLI through the ``OpenThreadCLI`` interface. + +otGetRespCmd +^^^^^^^^^^^^ + +Executes a CLI command and gets the response. + +.. code-block:: arduino + + bool otGetRespCmd(const char *cmd, char *resp = NULL, uint32_t respTimeout = 5000); + +* ``cmd`` - The CLI command to execute (e.g., ``"state"``, ``"networkname"``) +* ``resp`` - Buffer to store the response (optional, can be ``NULL``) +* ``respTimeout`` - Timeout in milliseconds for waiting for response (default: 5000 ms) + +This function executes a CLI command and collects all response lines until "Done" or "Error" is received. If ``resp`` is not ``NULL``, the response is stored in the buffer. + +**Returns:** ``true`` if command executed successfully, ``false`` on error or timeout. + +**Example:** + +.. code-block:: arduino + + char response[256]; + if (otGetRespCmd("state", response)) { + Serial.printf("Thread state: %s\r\n", response); + } + + if (otGetRespCmd("networkname", response)) { + Serial.printf("Network name: %s\r\n", response); + } + +otExecCommand +^^^^^^^^^^^^^ + +Executes a CLI command with arguments. + +.. code-block:: arduino + + bool otExecCommand(const char *cmd, const char *arg, ot_cmd_return_t *returnCode = NULL); + +* ``cmd`` - The CLI command to execute (e.g., ``"networkname"``, ``"channel"``) +* ``arg`` - The command argument (can be ``NULL`` for commands without arguments) +* ``returnCode`` - Pointer to ``ot_cmd_return_t`` structure to receive error information (optional) + +This function executes a CLI command with an optional argument and returns the success status. If ``returnCode`` is provided, it will be populated with error information on failure. + +**Returns:** ``true`` if command executed successfully, ``false`` on error. + +**Error Structure:** + +.. code-block:: arduino + + typedef struct { + int errorCode; // OpenThread error code + String errorMessage; // Error message string + } ot_cmd_return_t; + +**Example:** + +.. code-block:: arduino + + ot_cmd_return_t errorInfo; + + // Set network name + if (otExecCommand("networkname", "MyThreadNetwork", &errorInfo)) { + Serial.println("Network name set successfully"); + } else { + Serial.printf("Error %d: %s\r\n", errorInfo.errorCode, errorInfo.errorMessage.c_str()); + } + + // Set channel + if (otExecCommand("channel", "15", &errorInfo)) { + Serial.println("Channel set successfully"); + } + + // Bring interface up + if (otExecCommand("ifconfig", "up", NULL)) { + Serial.println("Interface is up"); + } + +otPrintRespCLI +^^^^^^^^^^^^^^ + +Executes a CLI command and prints the response to a Stream. + +.. code-block:: arduino + + bool otPrintRespCLI(const char *cmd, Stream &output, uint32_t respTimeout); + +* ``cmd`` - The CLI command to execute +* ``output`` - The Stream object to print responses to (e.g., ``Serial``) +* ``respTimeout`` - Timeout in milliseconds per response line (default: 5000 ms) + +This function executes a CLI command and prints all response lines to the specified Stream until "Done" or "Error" is received. + +**Returns:** ``true`` if command executed successfully, ``false`` on error or timeout. + +**Example:** + +.. code-block:: arduino + + // Print all IP addresses + if (otPrintRespCLI("ipaddr", Serial, 5000)) { + Serial.println("IP addresses printed"); + } + + // Print all multicast addresses + if (otPrintRespCLI("ipmaddr", Serial, 5000)) { + Serial.println("Multicast addresses printed"); + } + +OpenThreadCLI Class +******************* + +The ``OpenThreadCLI`` class provides a Stream-based interface for interacting with the OpenThread CLI. It allows you to send CLI commands and receive responses programmatically or through an interactive console. + +Initialization +************** + +begin +^^^^^ + +Initializes the OpenThread CLI. + +.. code-block:: arduino + + void begin(); + +This function initializes the OpenThread CLI interface. It must be called after ``OpenThread::begin()`` and before using any CLI functions. + +**Note:** The OpenThread stack must be started before initializing the CLI. + +end +^^^ + +Stops and cleans up the OpenThread CLI. + +.. code-block:: arduino + + void end(); + +This function stops the CLI interface and cleans up all CLI resources. + +Console Management +****************** + +startConsole +^^^^^^^^^^^^ + +Starts an interactive console for CLI access. + +.. code-block:: arduino + + void startConsole(Stream &otStream, bool echoback = true, const char *prompt = "ot> "); + +* ``otStream`` - The Stream object for console I/O (e.g., ``Serial``) +* ``echoback`` - If ``true``, echo characters back to the console (default: ``true``) +* ``prompt`` - The console prompt string (default: ``"ot> "``, can be ``NULL`` for no prompt) + +This function starts an interactive console task that allows you to type CLI commands directly. The console will echo input and display responses. + +**Example:** + +.. code-block:: arduino + + OThreadCLI.startConsole(Serial, true, "ot> "); + +stopConsole +^^^^^^^^^^^ + +Stops the interactive console. + +.. code-block:: arduino + + void stopConsole(); + +This function stops the interactive console task. + +setStream +^^^^^^^^^ + +Changes the console Stream object. + +.. code-block:: arduino + + void setStream(Stream &otStream); + +* ``otStream`` - The new Stream object for console I/O + +This function changes the Stream object used by the console. + +setEchoBack +^^^^^^^^^^^ + +Changes the echo back setting. + +.. code-block:: arduino + + void setEchoBack(bool echoback); + +* ``echoback`` - If ``true``, echo characters back to the console + +This function changes whether characters are echoed back to the console. + +setPrompt +^^^^^^^^^ + +Changes the console prompt. + +.. code-block:: arduino + + void setPrompt(char *prompt); + +* ``prompt`` - The new prompt string (can be ``NULL`` for no prompt) + +This function changes the console prompt string. + +onReceive +^^^^^^^^^ + +Sets a callback function for CLI responses. + +.. code-block:: arduino + + void onReceive(OnReceiveCb_t func); + +* ``func`` - Callback function to call when a complete line of output is received + +The callback function is called whenever a complete line of output is received from the OpenThread CLI. This allows you to process CLI responses asynchronously. + +**Callback Signature:** + +.. code-block:: arduino + + typedef std::function OnReceiveCb_t; + +**Example:** + +.. code-block:: arduino + + void handleCLIResponse() { + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + // Process response character + } + } + + OThreadCLI.onReceive(handleCLIResponse); + +Buffer Management +***************** + +setTxBufferSize +^^^^^^^^^^^^^^^ + +Sets the transmit buffer size. + +.. code-block:: arduino + + size_t setTxBufferSize(size_t tx_queue_len); + +* ``tx_queue_len`` - The size of the transmit buffer in bytes (default: 256) + +This function sets the size of the transmit buffer used for sending CLI commands. + +**Returns:** The actual buffer size set, or 0 on error. + +setRxBufferSize +^^^^^^^^^^^^^^^ + +Sets the receive buffer size. + +.. code-block:: arduino + + size_t setRxBufferSize(size_t rx_queue_len); + +* ``rx_queue_len`` - The size of the receive buffer in bytes (default: 1024) + +This function sets the size of the receive buffer used for receiving CLI responses. + +**Returns:** The actual buffer size set, or 0 on error. + +Stream Interface +**************** + +The ``OpenThreadCLI`` class implements the Arduino ``Stream`` interface, allowing you to use it like any other Stream object. + +write +^^^^^ + +Writes a byte to the CLI. + +.. code-block:: arduino + + size_t write(uint8_t c); + +* ``c`` - The byte to write + +This function writes a single byte to the CLI transmit buffer. + +**Returns:** The number of bytes written (1 on success, 0 on failure). + +available +^^^^^^^^^ + +Checks if data is available to read. + +.. code-block:: arduino + + int available(); + +This function returns the number of bytes available in the receive buffer. + +**Returns:** Number of bytes available, or -1 if CLI is not initialized. + +read +^^^^ + +Reads a byte from the CLI. + +.. code-block:: arduino + + int read(); + +This function reads a single byte from the CLI receive buffer. + +**Returns:** The byte read, or -1 if no data is available. + +peek +^^^^ + +Peeks at the next byte without removing it. + +.. code-block:: arduino + + int peek(); + +This function returns the next byte in the receive buffer without removing it. + +**Returns:** The byte, or -1 if no data is available. + +flush +^^^^^ + +Flushes the transmit buffer. + +.. code-block:: arduino + + void flush(); + +This function waits for all data in the transmit buffer to be sent. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns whether the CLI is started. + +.. code-block:: arduino + + operator bool() const; + +This operator returns ``true`` if the CLI is started and ready, ``false`` otherwise. + +**Example:** + +.. code-block:: arduino + + if (OThreadCLI) { + Serial.println("CLI is ready"); + } + +Example +------- + +Using CLI Helper Functions API +****************************** + +.. code-block:: arduino + + #include + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize CLI + OThreadCLI.begin(); + while (!OThreadCLI) { + delay(100); + } + + // Get network state + char resp[256]; + if (otGetRespCmd("state", resp)) { + Serial.printf("Thread state: %s\r\n", resp); + } + + // Set network name + ot_cmd_return_t errorInfo; + if (otExecCommand("networkname", "MyThreadNetwork", &errorInfo)) { + Serial.println("Network name set"); + } else { + Serial.printf("Error: %s\r\n", errorInfo.errorMessage.c_str()); + } + + // Set channel + if (otExecCommand("channel", "15", NULL)) { + Serial.println("Channel set"); + } + + // Bring interface up + if (otExecCommand("ifconfig", "up", NULL)) { + Serial.println("Interface up"); + } + + // Print IP addresses + otPrintRespCLI("ipaddr", Serial, 5000); + } + +Using OpenThreadCLI Class +************************* + +Interactive Console +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize and start CLI console + OThreadCLI.begin(); + OThreadCLI.startConsole(Serial, true, "ot> "); + + Serial.println("OpenThread CLI Console Ready"); + Serial.println("Type OpenThread CLI commands (e.g., 'state', 'networkname')"); + } + +Programmatic CLI Access +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize CLI + OThreadCLI.begin(); + while (!OThreadCLI) { + delay(100); + } + + // Send CLI commands programmatically + OThreadCLI.println("state"); + delay(100); + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + Serial.write(c); + } + + // Send command with argument + OThreadCLI.print("networkname "); + OThreadCLI.println("MyThreadNetwork"); + delay(100); + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + Serial.write(c); + } + } + +Using Callback for Responses +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #include + #include + + void handleCLIResponse() { + String response = ""; + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + if (c == '\n' || c == '\r') { + if (response.length() > 0) { + Serial.printf("CLI Response: %s\r\n", response.c_str()); + response = ""; + } + } else { + response += c; + } + } + } + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize CLI with callback + OThreadCLI.begin(); + OThreadCLI.onReceive(handleCLIResponse); + + // Send commands + OThreadCLI.println("state"); + delay(500); + OThreadCLI.println("networkname"); + delay(500); + } + +Common OpenThread CLI Commands +****************************** + +Here are some commonly used OpenThread CLI commands: + +* ``state`` - Get the current Thread state +* ``networkname `` - Set or get the network name +* ``channel `` - Set or get the channel (11-26) +* ``panid `` - Set or get the PAN ID +* ``extpanid `` - Set or get the extended PAN ID +* ``networkkey `` - Set or get the network key +* ``ifconfig up`` - Bring the network interface up +* ``ifconfig down`` - Bring the network interface down +* ``ipaddr`` - List all IPv6 addresses +* ``ipmaddr`` - List all multicast addresses +* ``rloc16`` - Get the RLOC16 +* ``leaderdata`` - Get leader data +* ``router table`` - Get router table +* ``child table`` - Get child table + +For a complete list of OpenThread CLI commands, refer to the `OpenThread CLI Reference `_. diff --git a/docs/en/openthread/openthread_core.rst b/docs/en/openthread/openthread_core.rst new file mode 100644 index 00000000000..0ba88acde88 --- /dev/null +++ b/docs/en/openthread/openthread_core.rst @@ -0,0 +1,579 @@ +################ +OpenThread Class +################ + +About +----- + +The ``OpenThread`` class provides direct access to OpenThread API functions for managing Thread network operations. This is the **Classes API** approach, which offers object-oriented methods that directly call OpenThread API functions. + +**Key Features:** +* Direct OpenThread API access +* Network management (start, stop, interface control) +* Dataset management +* Address management with caching +* Network information retrieval +* Device role monitoring + +**Use Cases:** +* Thread network configuration and management +* Direct control over Thread operations +* Programmatic network setup +* Address and routing information access + +API Reference +------------- + +Initialization +************** + +begin +^^^^^ + +Initializes the OpenThread stack. + +.. code-block:: arduino + + static void begin(bool OThreadAutoStart = true); + +* ``OThreadAutoStart`` - If ``true``, automatically starts Thread with default dataset from NVS or ESP-IDF settings (default: ``true``) + +This function initializes the OpenThread stack and creates the OpenThread task. If ``OThreadAutoStart`` is ``true``, it will attempt to start Thread using the active dataset from NVS or ESP-IDF default settings. + +**Note:** This is a static function and should be called before creating an ``OpenThread`` instance. + +end +^^^ + +Stops and cleans up the OpenThread stack. + +.. code-block:: arduino + + static void end(); + +This function stops the OpenThread task and cleans up all OpenThread resources. It should be called when you no longer need the OpenThread stack. + +**Note:** This is a static function. + +Network Control +*************** + +start +^^^^^ + +Starts the Thread network. + +.. code-block:: arduino + + void start(); + +This function enables the Thread network. The device will attempt to join or form a Thread network based on the active dataset. + +**Note:** The network interface must be brought up separately using ``networkInterfaceUp()``. + +stop +^^^^ + +Stops the Thread network. + +.. code-block:: arduino + + void stop(); + +This function disables the Thread network. The device will leave the Thread network and stop participating in Thread operations. + +networkInterfaceUp +^^^^^^^^^^^^^^^^^^ + +Brings the Thread network interface up. + +.. code-block:: arduino + + void networkInterfaceUp(); + +This function enables the Thread IPv6 interface (equivalent to CLI command ``ifconfig up``). The device will be able to send and receive IPv6 packets over the Thread network. + +networkInterfaceDown +^^^^^^^^^^^^^^^^^^^^ + +Brings the Thread network interface down. + +.. code-block:: arduino + + void networkInterfaceDown(); + +This function disables the Thread IPv6 interface (equivalent to CLI command ``ifconfig down``). The device will stop sending and receiving IPv6 packets. + +Dataset Management +****************** + +commitDataSet +^^^^^^^^^^^^^ + +Commits an operational dataset to the Thread network. + +.. code-block:: arduino + + void commitDataSet(const DataSet &dataset); + +* ``dataset`` - The ``DataSet`` object containing the operational dataset parameters + +This function sets the active operational dataset for the Thread network. The dataset must be properly configured before committing. + +**Example:** + +.. code-block:: arduino + + DataSet dataset; + dataset.initNew(); + dataset.setNetworkName("MyThreadNetwork"); + dataset.setChannel(15); + dataset.setNetworkKey(networkKey); + OThread.commitDataSet(dataset); + +getCurrentDataSet +^^^^^^^^^^^^^^^^^ + +Gets the current active operational dataset. + +.. code-block:: arduino + + const DataSet &getCurrentDataSet() const; + +This function returns a reference to a ``DataSet`` object containing the current active operational dataset parameters. + +Network Information +******************* + +getNetworkName +^^^^^^^^^^^^^^ + +Gets the Thread network name. + +.. code-block:: arduino + + String getNetworkName() const; + +This function returns the network name as a ``String``. + +getExtendedPanId +^^^^^^^^^^^^^^^^ + +Gets the extended PAN ID. + +.. code-block:: arduino + + const uint8_t *getExtendedPanId() const; + +This function returns a pointer to an 8-byte array containing the extended PAN ID. + +getNetworkKey +^^^^^^^^^^^^^ + +Gets the network key. + +.. code-block:: arduino + + const uint8_t *getNetworkKey() const; + +This function returns a pointer to a 16-byte array containing the network key. + +**Note:** The network key is stored in static storage and persists after the function returns. + +getChannel +^^^^^^^^^^ + +Gets the Thread channel. + +.. code-block:: arduino + + uint8_t getChannel() const; + +This function returns the Thread channel number (11-26). + +getPanId +^^^^^^^^ + +Gets the PAN ID. + +.. code-block:: arduino + + uint16_t getPanId() const; + +This function returns the PAN ID as a 16-bit value. + +Device Role +*********** + +otGetDeviceRole +^^^^^^^^^^^^^^^ + +Gets the current device role. + +.. code-block:: arduino + + static ot_device_role_t otGetDeviceRole(); + +This function returns the current Thread device role: + +* ``OT_ROLE_DISABLED`` - The Thread stack is disabled +* ``OT_ROLE_DETACHED`` - Not currently participating in a Thread network +* ``OT_ROLE_CHILD`` - The Thread Child role +* ``OT_ROLE_ROUTER`` - The Thread Router role +* ``OT_ROLE_LEADER`` - The Thread Leader role + +**Note:** This is a static function. + +otGetStringDeviceRole +^^^^^^^^^^^^^^^^^^^^^ + +Gets the current device role as a string. + +.. code-block:: arduino + + static const char *otGetStringDeviceRole(); + +This function returns a human-readable string representation of the current device role. + +**Note:** This is a static function. + +otPrintNetworkInformation +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Prints network information to a Stream. + +.. code-block:: arduino + + static void otPrintNetworkInformation(Stream &output); + +* ``output`` - The Stream object to print to (e.g., ``Serial``) + +This function prints comprehensive network information including: +* Device role +* RLOC16 +* Network name +* Channel +* PAN ID +* Extended PAN ID +* Network key + +**Note:** This is a static function. + +Address Management +****************** + +getMeshLocalPrefix +^^^^^^^^^^^^^^^^^^ + +Gets the mesh-local prefix. + +.. code-block:: arduino + + const otMeshLocalPrefix *getMeshLocalPrefix() const; + +This function returns a pointer to the mesh-local prefix structure. + +getMeshLocalEid +^^^^^^^^^^^^^^^ + +Gets the mesh-local EID (Endpoint Identifier). + +.. code-block:: arduino + + IPAddress getMeshLocalEid() const; + +This function returns the mesh-local IPv6 address as an ``IPAddress`` object. + +getLeaderRloc +^^^^^^^^^^^^^ + +Gets the Thread Leader RLOC (Routing Locator). + +.. code-block:: arduino + + IPAddress getLeaderRloc() const; + +This function returns the IPv6 address of the Thread Leader as an ``IPAddress`` object. + +getRloc +^^^^^^^ + +Gets the node RLOC (Routing Locator). + +.. code-block:: arduino + + IPAddress getRloc() const; + +This function returns the IPv6 RLOC address of this node as an ``IPAddress`` object. + +getRloc16 +^^^^^^^^^ + +Gets the RLOC16 (16-bit Routing Locator). + +.. code-block:: arduino + + uint16_t getRloc16() const; + +This function returns the 16-bit RLOC of this node. + +Unicast Address Management +************************** + +getUnicastAddressCount +^^^^^^^^^^^^^^^^^^^^^^ + +Gets the number of unicast addresses. + +.. code-block:: arduino + + size_t getUnicastAddressCount() const; + +This function returns the number of unicast IPv6 addresses assigned to this node. The count is cached for performance. + +getUnicastAddress +^^^^^^^^^^^^^^^^^ + +Gets a unicast address by index. + +.. code-block:: arduino + + IPAddress getUnicastAddress(size_t index) const; + +* ``index`` - The index of the address (0-based) + +This function returns the unicast IPv6 address at the specified index as an ``IPAddress`` object. + +**Note:** Addresses are cached for performance. Use ``clearUnicastAddressCache()`` to refresh the cache. + +getAllUnicastAddresses +^^^^^^^^^^^^^^^^^^^^^^ + +Gets all unicast addresses. + +.. code-block:: arduino + + std::vector getAllUnicastAddresses() const; + +This function returns a vector containing all unicast IPv6 addresses assigned to this node. + +Multicast Address Management +**************************** + +getMulticastAddressCount +^^^^^^^^^^^^^^^^^^^^^^^^ + +Gets the number of multicast addresses. + +.. code-block:: arduino + + size_t getMulticastAddressCount() const; + +This function returns the number of multicast IPv6 addresses subscribed by this node. The count is cached for performance. + +getMulticastAddress +^^^^^^^^^^^^^^^^^^^ + +Gets a multicast address by index. + +.. code-block:: arduino + + IPAddress getMulticastAddress(size_t index) const; + +* ``index`` - The index of the address (0-based) + +This function returns the multicast IPv6 address at the specified index as an ``IPAddress`` object. + +**Note:** Addresses are cached for performance. Use ``clearMulticastAddressCache()`` to refresh the cache. + +getAllMulticastAddresses +^^^^^^^^^^^^^^^^^^^^^^^^ + +Gets all multicast addresses. + +.. code-block:: arduino + + std::vector getAllMulticastAddresses() const; + +This function returns a vector containing all multicast IPv6 addresses subscribed by this node. + +Cache Management +**************** + +clearUnicastAddressCache +^^^^^^^^^^^^^^^^^^^^^^^^ + +Clears the unicast address cache. + +.. code-block:: arduino + + void clearUnicastAddressCache() const; + +This function clears the cached unicast addresses. The cache will be automatically repopulated on the next address access. + +clearMulticastAddressCache +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Clears the multicast address cache. + +.. code-block:: arduino + + void clearMulticastAddressCache() const; + +This function clears the cached multicast addresses. The cache will be automatically repopulated on the next address access. + +clearAllAddressCache +^^^^^^^^^^^^^^^^^^^^ + +Clears all address caches. + +.. code-block:: arduino + + void clearAllAddressCache() const; + +This function clears both unicast and multicast address caches. + +Advanced Access +*************** + +getInstance +^^^^^^^^^^^ + +Gets the OpenThread instance pointer. + +.. code-block:: arduino + + otInstance *getInstance(); + +This function returns a pointer to the underlying OpenThread instance. This allows direct access to OpenThread API functions for advanced use cases. + +**Warning:** Direct use of the OpenThread instance requires knowledge of the OpenThread API. Use with caution. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns whether OpenThread is started. + +.. code-block:: arduino + + operator bool() const; + +This operator returns ``true`` if OpenThread is started and ready, ``false`` otherwise. + +**Example:** + +.. code-block:: arduino + + if (OThread) { + Serial.println("OpenThread is ready"); + } + +Example +------- + +Basic Thread Network Setup +************************** + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread stack + OpenThread::begin(); + + // Wait for OpenThread to be ready + while (!OThread) { + delay(100); + } + + // Create and configure dataset + DataSet dataset; + dataset.initNew(); + dataset.setNetworkName("MyThreadNetwork"); + dataset.setChannel(15); + + // Set network key (16 bytes) + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + // Wait for network to be ready + while (OpenThread::otGetDeviceRole() == OT_ROLE_DETACHED) { + delay(100); + } + + // Print network information + OpenThread::otPrintNetworkInformation(Serial); + + // Get and print addresses + Serial.printf("Mesh Local EID: %s\r\n", OThread.getMeshLocalEid().toString().c_str()); + Serial.printf("RLOC: %s\r\n", OThread.getRloc().toString().c_str()); + Serial.printf("RLOC16: 0x%04x\r\n", OThread.getRloc16()); + } + +Monitoring Device Role +********************** + +.. code-block:: arduino + + void loop() { + ot_device_role_t role = OpenThread::otGetDeviceRole(); + const char *roleStr = OpenThread::otGetStringDeviceRole(); + + Serial.printf("Current role: %s\r\n", roleStr); + + switch (role) { + case OT_ROLE_LEADER: + Serial.println("This device is the Thread Leader"); + break; + case OT_ROLE_ROUTER: + Serial.println("This device is a Thread Router"); + break; + case OT_ROLE_CHILD: + Serial.println("This device is a Thread Child"); + break; + case OT_ROLE_DETACHED: + Serial.println("This device is not attached to a network"); + break; + case OT_ROLE_DISABLED: + Serial.println("Thread is disabled"); + break; + } + + delay(5000); + } + +Address Management +****************** + +.. code-block:: arduino + + void printAddresses() { + // Print unicast addresses + size_t unicastCount = OThread.getUnicastAddressCount(); + Serial.printf("Unicast addresses: %zu\r\n", unicastCount); + for (size_t i = 0; i < unicastCount; i++) { + Serial.printf(" [%zu] %s\r\n", i, OThread.getUnicastAddress(i).toString().c_str()); + } + + // Print multicast addresses + size_t multicastCount = OThread.getMulticastAddressCount(); + Serial.printf("Multicast addresses: %zu\r\n", multicastCount); + for (size_t i = 0; i < multicastCount; i++) { + Serial.printf(" [%zu] %s\r\n", i, OThread.getMulticastAddress(i).toString().c_str()); + } + + // Clear cache to force refresh + OThread.clearAllAddressCache(); + } diff --git a/docs/en/openthread/openthread_dataset.rst b/docs/en/openthread/openthread_dataset.rst new file mode 100644 index 00000000000..1cffd5cac2d --- /dev/null +++ b/docs/en/openthread/openthread_dataset.rst @@ -0,0 +1,461 @@ +############# +DataSet Class +############# + +About +----- + +The ``DataSet`` class provides a convenient way to create, configure, and manage Thread operational datasets. An operational dataset contains all the parameters needed to join or form a Thread network, including network name, channel, PAN ID, network key, and extended PAN ID. + +**Key Features:** +* Create new operational datasets +* Configure dataset parameters +* Apply datasets to the Thread network +* Retrieve dataset parameters +* Clear and reset datasets + +**Use Cases:** +* Creating new Thread networks +* Joining existing Thread networks +* Configuring network parameters +* Network migration and reconfiguration + +API Reference +------------- + +Constructor +*********** + +DataSet +^^^^^^^ + +Creates a new DataSet object. + +.. code-block:: arduino + + DataSet(); + +This constructor creates an empty dataset. You must either call ``initNew()`` to create a new dataset or configure parameters manually. + +Dataset Management +****************** + +clear +^^^^^ + +Clears all dataset parameters. + +.. code-block:: arduino + + void clear(); + +This function clears all dataset parameters, resetting the dataset to an empty state. + +initNew +^^^^^^^ + +Initializes a new operational dataset. + +.. code-block:: arduino + + void initNew(); + +This function creates a new operational dataset with randomly generated values for network key, extended PAN ID, and other parameters. The dataset will be ready to form a new Thread network. + +**Note:** OpenThread must be started (``OpenThread::begin()``) before calling this function. + +**Example:** + +.. code-block:: arduino + + DataSet dataset; + dataset.initNew(); // Creates new dataset with random values + dataset.setNetworkName("MyNewNetwork"); + dataset.setChannel(15); + +getDataset +^^^^^^^^^^ + +Gets the underlying OpenThread dataset structure. + +.. code-block:: arduino + + const otOperationalDataset &getDataset() const; + +This function returns a reference to the underlying ``otOperationalDataset`` structure. This is used internally when applying the dataset to the Thread network. + +**Note:** This function is typically used internally by ``OpenThread::commitDataSet()``. + +Setters +******* + +setNetworkName +^^^^^^^^^^^^^^ + +Sets the network name. + +.. code-block:: arduino + + void setNetworkName(const char *name); + +* ``name`` - The network name string (maximum 16 characters) + +This function sets the network name for the Thread network. The network name is a human-readable identifier for the network. + +**Example:** + +.. code-block:: arduino + + dataset.setNetworkName("MyThreadNetwork"); + +setExtendedPanId +^^^^^^^^^^^^^^^^ + +Sets the extended PAN ID. + +.. code-block:: arduino + + void setExtendedPanId(const uint8_t *extPanId); + +* ``extPanId`` - Pointer to an 8-byte array containing the extended PAN ID + +This function sets the extended PAN ID, which uniquely identifies the Thread network partition. + +**Example:** + +.. code-block:: arduino + + uint8_t extPanId[8] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77}; + dataset.setExtendedPanId(extPanId); + +setNetworkKey +^^^^^^^^^^^^^ + +Sets the network key. + +.. code-block:: arduino + + void setNetworkKey(const uint8_t *key); + +* ``key`` - Pointer to a 16-byte array containing the network key + +This function sets the network key, which is used for encryption and authentication in the Thread network. + +**Example:** + +.. code-block:: arduino + + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + +setChannel +^^^^^^^^^^ + +Sets the Thread channel. + +.. code-block:: arduino + + void setChannel(uint8_t channel); + +* ``channel`` - The Thread channel number (11-26) + +This function sets the IEEE 802.15.4 channel used by the Thread network. Valid channels are 11 through 26. + +**Example:** + +.. code-block:: arduino + + dataset.setChannel(15); // Use channel 15 + +setPanId +^^^^^^^^ + +Sets the PAN ID. + +.. code-block:: arduino + + void setPanId(uint16_t panId); + +* ``panId`` - The PAN ID (16-bit value) + +This function sets the PAN (Personal Area Network) ID for the Thread network. + +**Example:** + +.. code-block:: arduino + + dataset.setPanId(0x1234); // Set PAN ID to 0x1234 + +Getters +******* + +getNetworkName +^^^^^^^^^^^^^^ + +Gets the network name. + +.. code-block:: arduino + + const char *getNetworkName() const; + +This function returns a pointer to the network name string. + +**Returns:** Pointer to the network name, or ``NULL`` if not set. + +getExtendedPanId +^^^^^^^^^^^^^^^^ + +Gets the extended PAN ID. + +.. code-block:: arduino + + const uint8_t *getExtendedPanId() const; + +This function returns a pointer to the 8-byte extended PAN ID array. + +**Returns:** Pointer to the extended PAN ID array, or ``NULL`` if not set. + +getNetworkKey +^^^^^^^^^^^^^ + +Gets the network key. + +.. code-block:: arduino + + const uint8_t *getNetworkKey() const; + +This function returns a pointer to the 16-byte network key array. + +**Returns:** Pointer to the network key array, or ``NULL`` if not set. + +getChannel +^^^^^^^^^^ + +Gets the Thread channel. + +.. code-block:: arduino + + uint8_t getChannel() const; + +This function returns the Thread channel number. + +**Returns:** The channel number (11-26), or 0 if not set. + +getPanId +^^^^^^^^ + +Gets the PAN ID. + +.. code-block:: arduino + + uint16_t getPanId() const; + +This function returns the PAN ID. + +**Returns:** The PAN ID, or 0 if not set. + +Dataset Application +******************* + +apply +^^^^^ + +Applies the dataset to an OpenThread instance. + +.. code-block:: arduino + + void apply(otInstance *instance); + +* ``instance`` - Pointer to the OpenThread instance + +This function applies the dataset to the specified OpenThread instance, making it the active operational dataset. + +**Note:** This function is typically used internally. For normal use, use ``OpenThread::commitDataSet()`` instead. + +**Example:** + +.. code-block:: arduino + + otInstance *instance = OThread.getInstance(); + dataset.apply(instance); + +Example +------- + +Creating a New Network +********************** + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Create a new dataset + DataSet dataset; + dataset.initNew(); // Generate random values + + // Configure network parameters + dataset.setNetworkName("MyNewThreadNetwork"); + dataset.setChannel(15); + + // Set network key (16 bytes) + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + + // Set extended PAN ID (8 bytes) + uint8_t extPanId[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef}; + dataset.setExtendedPanId(extPanId); + + // Set PAN ID + dataset.setPanId(0x1234); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + Serial.println("New Thread network created"); + } + +Joining an Existing Network +*************************** + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Create dataset for existing network + DataSet dataset; + + // Configure with existing network parameters + dataset.setNetworkName("ExistingThreadNetwork"); + dataset.setChannel(15); + + // Set the network key from the existing network + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + + // Set the extended PAN ID from the existing network + uint8_t extPanId[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef}; + dataset.setExtendedPanId(extPanId); + + // Set PAN ID + dataset.setPanId(0x1234); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + Serial.println("Joining existing Thread network"); + } + +Reading Current Dataset +*********************** + +.. code-block:: arduino + + void printCurrentDataset() { + // Get current dataset from OpenThread + const DataSet ¤tDataset = OThread.getCurrentDataSet(); + + // Print dataset parameters + Serial.println("Current Thread Dataset:"); + Serial.printf(" Network Name: %s\r\n", currentDataset.getNetworkName()); + Serial.printf(" Channel: %d\r\n", currentDataset.getChannel()); + Serial.printf(" PAN ID: 0x%04x\r\n", currentDataset.getPanId()); + + // Print extended PAN ID + const uint8_t *extPanId = currentDataset.getExtendedPanId(); + if (extPanId) { + Serial.print(" Extended PAN ID: "); + for (int i = 0; i < 8; i++) { + Serial.printf("%02x", extPanId[i]); + } + Serial.println(); + } + + // Print network key (first 4 bytes for security) + const uint8_t *networkKey = currentDataset.getNetworkKey(); + if (networkKey) { + Serial.print(" Network Key: "); + for (int i = 0; i < 4; i++) { + Serial.printf("%02x", networkKey[i]); + } + Serial.println("..."); + } + } + +Modifying Dataset Parameters +**************************** + +.. code-block:: arduino + + void modifyNetworkChannel() { + // Get current dataset + DataSet dataset = OThread.getCurrentDataSet(); + + // Modify channel + dataset.setChannel(20); // Change to channel 20 + + // Apply modified dataset + OThread.commitDataSet(dataset); + + Serial.println("Network channel changed to 20"); + } + +Best Practices +-------------- + +Dataset Security +**************** + +* **Network Key**: Keep the network key secure and never expose it in logs or serial output +* **Extended PAN ID**: Use unique extended PAN IDs to avoid network conflicts +* **Channel Selection**: Choose channels that avoid interference with Wi-Fi networks (channels 11, 15, 20, 25 are often good choices) + +Required Parameters +******************* + +For a dataset to be valid and usable, you typically need: + +* **Network Name**: Required for human identification +* **Network Key**: Required for security (16 bytes) +* **Channel**: Required for radio communication (11-26) +* **Extended PAN ID**: Recommended for network identification (8 bytes) +* **PAN ID**: Optional, will be assigned if not set + +Parameter Validation +******************** + +The DataSet class performs basic validation: + +* Network name length is checked (maximum 16 characters) +* Channel range is validated (11-26) +* Null pointer checks for array parameters + +However, it's your responsibility to ensure: + +* Network key is properly generated (use ``initNew()`` for random generation) +* Extended PAN ID is unique within your network environment +* All required parameters are set before applying the dataset From 333bfffcc6ab56e61b1db1b6bba522ab198ae241 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Mon, 10 Nov 2025 09:56:39 -0300 Subject: [PATCH 18/23] feat(rmt): improves RMT documentation (#11992) * feat(rmt): improves RMT documentation * fix(rmt): includes missing reference to C5 and P4 Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(rmt): note rewritting Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(rmt): rephasing Clarify behavior of rmtTransmitCompleted in looping mode. * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- docs/en/api/rmt.rst | 448 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 439 insertions(+), 9 deletions(-) diff --git a/docs/en/api/rmt.rst b/docs/en/api/rmt.rst index 6f87054a9c2..84d885c7d90 100644 --- a/docs/en/api/rmt.rst +++ b/docs/en/api/rmt.rst @@ -1,24 +1,454 @@ -### -RMT -### +#################### +Remote Control (RMT) +#################### About ----- +The Remote Control Transceiver (RMT) peripheral was originally designed to act as an infrared transceiver, +but it can be used to generate or receive many other types of digital signals with precise timing. -.. note:: This is a work in progress project and this section is still missing. If you want to contribute, please see the `Contributions Guide <../contributing.html>`_. +The RMT peripheral is capable of transmitting and receiving digital signals with precise timing control, +making it ideal for protocols that require specific pulse widths and timing, such as: -Remote Control Transceiver (RMT) peripheral was designed to act as an infrared transceiver. +* **Infrared (IR) remote control protocols** (NEC, RC5, Sony, etc.) +* **WS2812/NeoPixel RGB LED control** (requires precise timing) +* **Custom communication protocols** with specific timing requirements +* **Pulse generation** for various applications -Example -------- +RMT operates by encoding digital signals as sequences of high/low pulses with specific durations. +Each RMT symbol represents two consecutive pulses (level0/duration0 and level1/duration1). -To get started with RMT, you can try: +RMT Memory Blocks +----------------- -RMT Write RGB LED +RMT channels use memory blocks to store signal data. The number of available memory blocks varies by SoC: + +========= ================== ====================================== +ESP32 SoC Memory Blocks Notes +========= ================== ====================================== +ESP32 8 blocks total Shared between TX and RX channels +ESP32-S2 4 blocks total Shared between TX and RX channels +ESP32-S3 4 blocks TX + 4 RX Separate memory for TX and RX channels +ESP32-C3 2 blocks TX + 2 RX Separate memory for TX and RX channels +ESP32-C5 2 blocks TX + 2 RX Separate memory for TX and RX channels +ESP32-C6 2 blocks TX + 2 RX Separate memory for TX and RX channels +ESP32-H2 2 blocks TX + 2 RX Separate memory for TX and RX channels +ESP32-P4 4 blocks TX + 4 RX Separate memory for TX and RX channels +========= ================== ====================================== + +Each memory block can store ``RMT_SYMBOLS_PER_CHANNEL_BLOCK`` symbols (64 for ESP32/ESP32-S2, 48 for ESP32-S3/ESP32-C3/ESP32-C5/ESP32-C6/ESP32-H2/ESP32-P4). + +**Note:** Each RMT symbol is 4 bytes (32 bits), containing two pulses with their durations and levels. + +Arduino-ESP32 RMT API +--------------------- + +rmtInit +******* + +Initializes an RMT channel for a specific GPIO pin with the specified direction, memory size, and frequency. + +.. code-block:: arduino + + bool rmtInit(int pin, rmt_ch_dir_t channel_direction, rmt_reserve_memsize_t memsize, uint32_t frequency_Hz); + +* ``pin`` - GPIO pin number to use for RMT +* ``channel_direction`` - Channel direction: + + * ``RMT_RX_MODE`` - Receive mode (for reading signals) + * ``RMT_TX_MODE`` - Transmit mode (for sending signals) + +* ``memsize`` - Number of memory blocks to reserve for this channel: + + * ``RMT_MEM_NUM_BLOCKS_1`` - 1 block + * ``RMT_MEM_NUM_BLOCKS_2`` - 2 blocks + * ``RMT_MEM_NUM_BLOCKS_3`` - 3 blocks (ESP32 only) + * ``RMT_MEM_NUM_BLOCKS_4`` - 4 blocks (ESP32 only) + * ``RMT_MEM_NUM_BLOCKS_5`` through ``RMT_MEM_NUM_BLOCKS_8`` - 5-8 blocks (ESP32 only) + +* ``frequency_Hz`` - RMT channel frequency in Hz (tick frequency). Must be between 312.5 kHz and 80 MHz. + + The frequency determines the resolution of pulse durations. For example: + + * 10 MHz (100 ns tick) - High precision, suitable for WS2812 LEDs + * 1 MHz (1 µs tick) - Good for most IR protocols + * 400 kHz (2.5 µs tick) - Suitable for slower protocols + +This function returns ``true`` if initialization is successful, ``false`` otherwise. + +**Note:** The RMT tick is set by the frequency parameter. Example: 100 ns tick => 10 MHz, thus frequency will be 10,000,000 Hz. + +rmtDeinit +********* + +Deinitializes the RMT channel and releases all allocated resources for the specified pin. + +.. code-block:: arduino + + bool rmtDeinit(int pin); + +* ``pin`` - GPIO pin number that was initialized with RMT + +This function returns ``true`` if deinitialization is successful, ``false`` otherwise. + +rmtSetEOT +********* + +Sets the End of Transmission (EOT) level for the RMT pin when transmission ends. +This function affects how ``rmtWrite()``, ``rmtWriteAsync()``, or ``rmtWriteLooping()`` will set the pin after writing the data. + +.. code-block:: arduino + + bool rmtSetEOT(int pin, uint8_t EOT_Level); + +* ``pin`` - GPIO pin number configured for RMT TX mode +* ``EOT_Level`` - End of transmission level: + + * ``0`` (LOW) - Pin will be set to LOW after transmission (default) + * Non-zero (HIGH) - Pin will be set to HIGH after transmission + +**Note:** This only affects the transmission process. The pre-transmission idle level can be set manually using ``digitalWrite(pin, level)``. + +This function returns ``true`` if EOT level is set successfully, ``false`` otherwise. + +rmtWrite +******** + +Sends RMT data in blocking mode. The function waits until all data is transmitted or until timeout occurs. + +.. code-block:: arduino + + bool rmtWrite(int pin, rmt_data_t *data, size_t num_rmt_symbols, uint32_t timeout_ms); + +* ``pin`` - GPIO pin number configured for RMT TX mode +* ``data`` - Pointer to array of ``rmt_data_t`` symbols to transmit +* ``num_rmt_symbols`` - Number of RMT symbols to transmit +* ``timeout_ms`` - Timeout in milliseconds. Use ``RMT_WAIT_FOR_EVER`` for indefinite wait + +**Blocking mode:** The function only returns after sending all data or by timeout. + +This function returns ``true`` if transmission is successful, ``false`` on error or timeout. + +**Example:** + +.. code-block:: arduino + + rmt_data_t symbols[] = { + {8, 1, 4, 0}, // High for 8 ticks, Low for 4 ticks (bit '1') + {4, 1, 8, 0} // High for 4 ticks, Low for 8 ticks (bit '0') + }; + + rmtWrite(pin, symbols, 2, RMT_WAIT_FOR_EVER); + +rmtWriteAsync +************* + +Sends RMT data in non-blocking (asynchronous) mode. The function returns immediately after starting the transmission. + +.. code-block:: arduino + + bool rmtWriteAsync(int pin, rmt_data_t *data, size_t num_rmt_symbols); + +* ``pin`` - GPIO pin number configured for RMT TX mode +* ``data`` - Pointer to array of ``rmt_data_t`` symbols to transmit +* ``num_rmt_symbols`` - Number of RMT symbols to transmit + +**Non-blocking mode:** Returns immediately after execution. Use ``rmtTransmitCompleted()`` to check if transmission is finished. + +**Note:** If ``rmtWriteAsync()`` is called while a previous transmission is still in progress, it will return ``false`` immediately to indicate failure; it does not wait for the previous transmission to finish. + +This function returns ``true`` on execution success, ``false`` otherwise. + +rmtWriteLooping +**************** + +Sends RMT data in infinite looping mode. The data will be transmitted continuously until stopped. + +.. code-block:: arduino + + bool rmtWriteLooping(int pin, rmt_data_t *data, size_t num_rmt_symbols); + +* ``pin`` - GPIO pin number configured for RMT TX mode +* ``data`` - Pointer to array of ``rmt_data_t`` symbols to transmit +* ``num_rmt_symbols`` - Number of RMT symbols to transmit + +**Looping mode:** The data is transmitted continuously in a loop. To stop looping, call ``rmtWrite()`` or ``rmtWriteAsync()`` with new data, or call ``rmtWriteLooping()`` with ``NULL`` data or zero size. + +**Note:** Looping mode needs a zero-ending data symbol ``{0, 0, 0, 0}`` to mark the end of data. + +This function returns ``true`` on execution success, ``false`` otherwise. + +rmtWriteRepeated +**************** + +Sends RMT data a fixed number of times (repeated transmission). + +.. code-block:: arduino + + bool rmtWriteRepeated(int pin, rmt_data_t *data, size_t num_rmt_symbols, uint32_t loop_count); + +* ``pin`` - GPIO pin number configured for RMT TX mode +* ``data`` - Pointer to array of ``rmt_data_t`` symbols to transmit +* ``num_rmt_symbols`` - Number of RMT symbols to transmit +* ``loop_count`` - Number of times to repeat the transmission (must be at least 1) + +**Note:** +* ``loop_count == 0`` is invalid (no transmission) +* ``loop_count == 1`` transmits once (no looping) +* ``loop_count > 1`` transmits the data repeatedly + +**Note:** Loop count feature is only supported on certain SoCs. On unsupported SoCs, this function will return ``false``. + +This function returns ``true`` on execution success, ``false`` otherwise. + +rmtTransmitCompleted +******************** + +Checks if the RMT transmission is completed and the channel is ready for transmitting new data. + +.. code-block:: arduino + + bool rmtTransmitCompleted(int pin); + +* ``pin`` - GPIO pin number configured for RMT TX mode + +This function returns ``true`` when all data has been sent and the channel is ready for a new transmission, ``false`` otherwise. + +**Note:** +* If ``rmtWrite()`` times out or ``rmtWriteAsync()`` is called, this function will return ``false`` until all data is sent out. +* ``rmtTransmitCompleted()`` will always return ``true`` when ``rmtWriteLooping()`` is active, because it has no effect in such case. + +rmtRead +******* + +Initiates blocking receive operation. Reads RMT data and stores it in the provided buffer. + +.. code-block:: arduino + + bool rmtRead(int pin, rmt_data_t *data, size_t *num_rmt_symbols, uint32_t timeout_ms); + +* ``pin`` - GPIO pin number configured for RMT RX mode +* ``data`` - Pointer to buffer where received RMT symbols will be stored +* ``num_rmt_symbols`` - Pointer to variable containing maximum number of symbols to read. + + On return, this variable will contain the actual number of symbols read. + +* ``timeout_ms`` - Timeout in milliseconds. Use ``RMT_WAIT_FOR_EVER`` for indefinite wait + +**Blocking mode:** The function waits until data is received or timeout occurs. + +If the reading operation times out, ``num_rmt_symbols`` won't change and ``rmtReceiveCompleted()`` can be used later to check if data is available. + +This function returns ``true`` when data is successfully read, ``false`` on error or timeout. + +rmtReadAsync +************ + +Initiates non-blocking (asynchronous) receive operation. Returns immediately after starting the receive process. + +.. code-block:: arduino + + bool rmtReadAsync(int pin, rmt_data_t *data, size_t *num_rmt_symbols); + +* ``pin`` - GPIO pin number configured for RMT RX mode +* ``data`` - Pointer to buffer where received RMT symbols will be stored +* ``num_rmt_symbols`` - Pointer to variable containing maximum number of symbols to read. + + On completion, this variable will be updated with the actual number of symbols read. + +**Non-blocking mode:** Returns immediately after execution. Use ``rmtReceiveCompleted()`` to check if data is available. + +This function returns ``true`` on execution success, ``false`` otherwise. + +rmtReceiveCompleted +******************* + +Checks if RMT data reception is completed and new data is available for processing. + +.. code-block:: arduino + + bool rmtReceiveCompleted(int pin); + +* ``pin`` - GPIO pin number configured for RMT RX mode + +This function returns ``true`` when data has been received and is available in the buffer, ``false`` otherwise. + +**Note:** The data reception information is reset when a new ``rmtRead()`` or ``rmtReadAsync()`` function is called. + +rmtSetCarrier +************* + +Sets carrier frequency modulation/demodulation for RMT TX or RX channel. + +.. code-block:: arduino + + bool rmtSetCarrier(int pin, bool carrier_en, bool carrier_level, uint32_t frequency_Hz, float duty_percent); + +* ``pin`` - GPIO pin number configured for RMT +* ``carrier_en`` - Enable/disable carrier modulation (TX) or demodulation (RX) +* ``carrier_level`` - Carrier polarity level: + + * ``true`` - Positive polarity (active high) + * ``false`` - Negative polarity (active low) + +* ``frequency_Hz`` - Carrier frequency in Hz (e.g., 38000 for 38 kHz IR carrier) +* ``duty_percent`` - Duty cycle as a float from 0.0 to 1.0 (e.g., 0.33 for 33% duty cycle, 0.5 for 50% square wave) + +**Note:** Parameters changed in Arduino Core 3: low and high (ticks) are now expressed in Carrier Frequency in Hz and duty cycle in percentage (float 0.0 to 1.0). + +**Example:** 38.5 kHz carrier with 33% duty cycle: ``rmtSetCarrier(pin, true, true, 38500, 0.33)`` + +This function returns ``true`` if carrier is set successfully, ``false`` otherwise. + +rmtSetRxMinThreshold +******************** + +Sets the minimum pulse width filter threshold for RX channel. Pulses smaller than this threshold will be ignored as noise. + +.. code-block:: arduino + + bool rmtSetRxMinThreshold(int pin, uint8_t filter_pulse_ticks); + +* ``pin`` - GPIO pin number configured for RMT RX mode +* ``filter_pulse_ticks`` - Minimum pulse width in RMT ticks. Pulses (high or low) smaller than this will be filtered out. + + Set to ``0`` to disable the filter. + +**Note:** The filter threshold is specified in RMT ticks, which depends on the RMT frequency set during ``rmtInit()``. + +This function returns ``true`` if filter threshold is set successfully, ``false`` otherwise. + +rmtSetRxMaxThreshold +******************** + +Sets the maximum idle threshold for RX channel. When no edge is detected for longer than this threshold, the receiving process is finished. + +.. code-block:: arduino + + bool rmtSetRxMaxThreshold(int pin, uint16_t idle_thres_ticks); + +* ``pin`` - GPIO pin number configured for RMT RX mode +* ``idle_thres_ticks`` - Maximum idle time in RMT ticks. When no edge is detected for longer than this time, reception ends. + + This threshold also defines how many low/high bits are read at the end of the received data. + +**Note:** The idle threshold is specified in RMT ticks, which depends on the RMT frequency set during ``rmtInit()``. + +This function returns ``true`` if idle threshold is set successfully, ``false`` otherwise. + +RMT Data Structure +------------------ + +rmt_data_t +********** + +RMT data structure representing a single RMT symbol (two consecutive pulses). + +.. code-block:: arduino + + typedef union { + struct { + uint32_t duration0 : 15; // Duration of first pulse in RMT ticks + uint32_t level0 : 1; // Level of first pulse (0 = LOW, 1 = HIGH) + uint32_t duration1 : 15; // Duration of second pulse in RMT ticks + uint32_t level1 : 1; // Level of second pulse (0 = LOW, 1 = HIGH) + }; + uint32_t val; // Access as 32-bit value + } rmt_data_t; + +Each RMT symbol contains two pulses: +* **First pulse:** ``level0`` for ``duration0`` ticks +* **Second pulse:** ``level1`` for ``duration1`` ticks + +**Example:** + +.. code-block:: arduino + + // Create a symbol: HIGH for 8 ticks, then LOW for 4 ticks + rmt_data_t symbol = { + .duration0 = 8, + .level0 = 1, + .duration1 = 4, + .level1 = 0 + }; + + // Or using struct initialization + rmt_data_t symbol2 = {8, 1, 4, 0}; + +Helper Macros +------------- + +RMT_SYMBOLS_OF +************** + +Helper macro to calculate the number of RMT symbols in an array. + +.. code-block:: arduino + + #define RMT_SYMBOLS_OF(x) (sizeof(x) / sizeof(rmt_data_t)) + +**Example:** + +.. code-block:: arduino + + rmt_data_t data[] = { + {8, 1, 4, 0}, + {4, 1, 8, 0} + }; + + size_t num_symbols = RMT_SYMBOLS_OF(data); // Returns 2 + +RMT_WAIT_FOR_EVER ***************** +Constant for indefinite timeout in blocking operations. + +.. code-block:: arduino + + #define RMT_WAIT_FOR_EVER ((uint32_t)portMAX_DELAY) + +Use this constant as the ``timeout_ms`` parameter in ``rmtWrite()`` or ``rmtRead()`` to wait indefinitely. + +**Example:** + +.. code-block:: arduino + + rmtWrite(pin, data, num_symbols, RMT_WAIT_FOR_EVER); + +RMT_SYMBOLS_PER_CHANNEL_BLOCK +****************************** + +Constant defining the number of RMT symbols per memory block. + +* ESP32/ESP32-S2: 64 symbols per block +* ESP32-S3/ESP32-C3/ESP32-C5/ESP32-C6/ESP32-H2/ESP32-P4: 48 symbols per block + +**Example:** + +.. code-block:: arduino + + // Allocate buffer for 1 memory block + rmt_data_t buffer[RMT_SYMBOLS_PER_CHANNEL_BLOCK]; + +Example Applications +******************** + +RMT Write RGB LED (WS2812): +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. literalinclude:: ../../../libraries/ESP32/examples/RMT/RMTWrite_RGB_LED/RMTWrite_RGB_LED.ino :language: arduino +RMT LED Blink: +^^^^^^^^^^^^^^ + +.. literalinclude:: ../../../libraries/ESP32/examples/RMT/RMT_LED_Blink/RMT_LED_Blink.ino + :language: arduino + +RMT Read XJT Protocol: +^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../../../libraries/ESP32/examples/RMT/RMTReadXJT/RMTReadXJT.ino + :language: arduino Complete list of `RMT examples `_. From 96520bc5726e85f2fea2999364e3672759b6c1c6 Mon Sep 17 00:00:00 2001 From: Piotr Gniado Date: Wed, 12 Nov 2025 10:55:06 +0100 Subject: [PATCH 19/23] fix(network): Fix getting fallback DNS server (#12013) - Fix getting fallback DNS server using NetworkInterface::dnsIP() getter - Remove magic number from NetworkInterface::dnsIP() setter --- libraries/Network/src/NetworkInterface.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/libraries/Network/src/NetworkInterface.cpp b/libraries/Network/src/NetworkInterface.cpp index 94675e65e12..393d2b9cf7f 100644 --- a/libraries/Network/src/NetworkInterface.cpp +++ b/libraries/Network/src/NetworkInterface.cpp @@ -352,7 +352,7 @@ bool NetworkInterface::enableIPv6(bool en) { } bool NetworkInterface::dnsIP(uint8_t dns_no, IPAddress ip) { - if (_esp_netif == NULL || dns_no > 2) { + if (_esp_netif == NULL || dns_no >= ESP_NETIF_DNS_MAX) { return false; } esp_netif_flags_t flags = esp_netif_get_flags(_esp_netif); @@ -708,11 +708,11 @@ IPAddress NetworkInterface::gatewayIP() const { } IPAddress NetworkInterface::dnsIP(uint8_t dns_no) const { - if (_esp_netif == NULL) { + if (_esp_netif == NULL || dns_no >= ESP_NETIF_DNS_MAX) { return IPAddress(); } esp_netif_dns_info_t d; - if (esp_netif_get_dns_info(_esp_netif, dns_no ? ESP_NETIF_DNS_BACKUP : ESP_NETIF_DNS_MAIN, &d) != ESP_OK) { + if (esp_netif_get_dns_info(_esp_netif, (esp_netif_dns_type_t)dns_no, &d) != ESP_OK) { return IPAddress(); } if (d.ip.type == ESP_IPADDR_TYPE_V6) { From 7bfecf2b309bb12f376f6c6032a884973ab8e197 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Proch=C3=A1zka?= <90197375+P-R-O-C-H-Y@users.noreply.github.com> Date: Wed, 12 Nov 2025 11:07:56 +0100 Subject: [PATCH 20/23] feat(zigbee): Update esp-zigbee-sdk to latest 1.6.8 (#12017) --- idf_component.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/idf_component.yml b/idf_component.yml index 7a883f1658a..99bf7048c1c 100644 --- a/idf_component.yml +++ b/idf_component.yml @@ -54,12 +54,12 @@ dependencies: espressif/esp_modem: version: "^1.1.0" espressif/esp-zboss-lib: - version: "==1.6.4" # compatible with esp-zigbee-lib 1.6.7 + version: "==1.6.4" # compatible with esp-zigbee-lib 1.6.8 require: public rules: - if: "target not in [esp32c2, esp32p4]" espressif/esp-zigbee-lib: - version: "==1.6.7" + version: "==1.6.8" require: public rules: - if: "target not in [esp32c2, esp32p4]" From 088d416b0f1829d2ec217ac4ab9fed3fee326f72 Mon Sep 17 00:00:00 2001 From: Me No Dev Date: Wed, 12 Nov 2025 16:00:24 +0200 Subject: [PATCH 21/23] feat(hosted): Add OTA and version functionality to esp-hosted (#11936) * feat(hosted): Add OTA and version functionality to esp-hosted * feat(hosted): Add hostedActivateUpdate() function * feat(hosted): Add new BLE init/deinit API calls * fix(hosted): Apply suggestion from @lucasssvaz Co-authored-by: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> * fix(hosted): Apply suggestion from @lucasssvaz Co-authored-by: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> * ci(pre-commit): Apply automatic fixes --------- Co-authored-by: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> --- cores/esp32/esp32-hal-hosted.c | 130 ++++++++++++++++++++++++++++++++- cores/esp32/esp32-hal-hosted.h | 8 ++ 2 files changed, 135 insertions(+), 3 deletions(-) diff --git a/cores/esp32/esp32-hal-hosted.c b/cores/esp32/esp32-hal-hosted.c index 0bb8023432a..3e510438bd0 100644 --- a/cores/esp32/esp32-hal-hosted.c +++ b/cores/esp32/esp32-hal-hosted.c @@ -18,9 +18,10 @@ #include "esp32-hal-hosted.h" #include "esp32-hal-log.h" +#include "esp_hosted.h" #include "esp_hosted_transport_config.h" -extern esp_err_t esp_hosted_init(); -extern esp_err_t esp_hosted_deinit(); +// extern esp_err_t esp_hosted_init(); +// extern esp_err_t esp_hosted_deinit(); static bool hosted_initialized = false; static bool hosted_ble_active = false; @@ -46,6 +47,100 @@ static sdio_pin_config_t sdio_pin_config = { #endif }; +static esp_hosted_coprocessor_fwver_t slave_version_struct = {.major1 = 0, .minor1 = 0, .patch1 = 0}; +static esp_hosted_coprocessor_fwver_t host_version_struct = { + .major1 = ESP_HOSTED_VERSION_MAJOR_1, .minor1 = ESP_HOSTED_VERSION_MINOR_1, .patch1 = ESP_HOSTED_VERSION_PATCH_1 +}; + +void hostedGetHostVersion(uint32_t *major, uint32_t *minor, uint32_t *patch) { + *major = host_version_struct.major1; + *minor = host_version_struct.minor1; + *patch = host_version_struct.patch1; +} + +void hostedGetSlaveVersion(uint32_t *major, uint32_t *minor, uint32_t *patch) { + *major = slave_version_struct.major1; + *minor = slave_version_struct.minor1; + *patch = slave_version_struct.patch1; +} + +bool hostedHasUpdate() { + uint32_t host_version = ESP_HOSTED_VERSION_VAL(host_version_struct.major1, host_version_struct.minor1, host_version_struct.patch1); + uint32_t slave_version = 0; + + esp_err_t ret = esp_hosted_get_coprocessor_fwversion(&slave_version_struct); + if (ret != ESP_OK) { + log_e("Could not get slave firmware version: %s", esp_err_to_name(ret)); + } else { + slave_version = ESP_HOSTED_VERSION_VAL(slave_version_struct.major1, slave_version_struct.minor1, slave_version_struct.patch1); + } + + log_i("Host firmware version: %" PRIu32 ".%" PRIu32 ".%" PRIu32, host_version_struct.major1, host_version_struct.minor1, host_version_struct.patch1); + log_i("Slave firmware version: %" PRIu32 ".%" PRIu32 ".%" PRIu32, slave_version_struct.major1, slave_version_struct.minor1, slave_version_struct.patch1); + + // compare major.minor only + // slave_version &= 0xFFFFFF00; + // host_version &= 0xFFFFFF00; + + if (host_version == slave_version) { + log_i("Versions Match!"); + } else if (host_version > slave_version) { + log_w("Version on Host is NEWER than version on co-processor"); + log_w("Update URL: %s", hostedGetUpdateURL()); + return true; + } else { + log_w("Version on Host is OLDER than version on co-processor"); + } + return false; +} + +char *hostedGetUpdateURL() { + // https://espressif.github.io/arduino-esp32/hosted/esp32c6-v1.2.3.bin + static char url[92] = {0}; + snprintf( + url, 92, "https://espressif.github.io/arduino-esp32/hosted/%s-v%" PRIu32 ".%" PRIu32 ".%" PRIu32 ".bin", CONFIG_ESP_HOSTED_IDF_SLAVE_TARGET, + host_version_struct.major1, host_version_struct.minor1, host_version_struct.patch1 + ); + return url; +} + +bool hostedBeginUpdate() { + esp_err_t err = esp_hosted_slave_ota_begin(); + if (err != ESP_OK) { + log_e("Failed to begin Update: %s", esp_err_to_name(err)); + } + return err == ESP_OK; +} + +bool hostedWriteUpdate(uint8_t *buf, uint32_t len) { + esp_err_t err = esp_hosted_slave_ota_write(buf, len); + if (err != ESP_OK) { + log_e("Failed to write Update: %s", esp_err_to_name(err)); + } + return err == ESP_OK; +} + +bool hostedEndUpdate() { + esp_err_t err = esp_hosted_slave_ota_end(); + if (err != ESP_OK) { + log_e("Failed to end Update: %s", esp_err_to_name(err)); + } + return err == ESP_OK; +} + +bool hostedActivateUpdate() { + esp_err_t err = esp_hosted_slave_ota_activate(); + if (err != ESP_OK) { + log_e("Failed to activate Update: %s", esp_err_to_name(err)); + } + // else { + // hostedDeinit(); + // delay(1000); + // hostedInit(); + // } + return err == ESP_OK; +} + static bool hostedInit() { if (!hosted_initialized) { log_i("Initializing ESP-Hosted"); @@ -69,6 +164,12 @@ static bool hostedInit() { return false; } log_i("ESP-Hosted initialized!"); + if (esp_hosted_connect_to_slave() != ESP_OK) { + log_e("Failed to connect to slave"); + return false; + } + hostedHasUpdate(); + return true; } // Attach pins to PeriMan here @@ -101,8 +202,21 @@ static bool hostedDeinit() { bool hostedInitBLE() { log_i("Initializing ESP-Hosted for BLE"); + if (!hostedInit()) { + return false; + } + esp_err_t err = esp_hosted_bt_controller_init(); + if (err != ESP_OK) { + log_e("esp_hosted_bt_controller_init failed: %s", esp_err_to_name(err)); + return false; + } + err = esp_hosted_bt_controller_enable(); + if (err != ESP_OK) { + log_e("esp_hosted_bt_controller_enable failed: %s", esp_err_to_name(err)); + return false; + } hosted_ble_active = true; - return hostedInit(); + return true; } bool hostedInitWiFi() { @@ -113,6 +227,16 @@ bool hostedInitWiFi() { bool hostedDeinitBLE() { log_i("Deinitializing ESP-Hosted for BLE"); + esp_err_t err = esp_hosted_bt_controller_disable(); + if (err != ESP_OK) { + log_e("esp_hosted_bt_controller_disable failed: %s", esp_err_to_name(err)); + return false; + } + err = esp_hosted_bt_controller_deinit(false); + if (err != ESP_OK) { + log_e("esp_hosted_bt_controller_deinit failed: %s", esp_err_to_name(err)); + return false; + } hosted_ble_active = false; if (!hosted_wifi_active) { return hostedDeinit(); diff --git a/cores/esp32/esp32-hal-hosted.h b/cores/esp32/esp32-hal-hosted.h index 0a916bfac85..1b329fcb469 100644 --- a/cores/esp32/esp32-hal-hosted.h +++ b/cores/esp32/esp32-hal-hosted.h @@ -44,6 +44,14 @@ bool hostedIsBLEActive(); bool hostedIsWiFiActive(); bool hostedSetPins(int8_t clk, int8_t cmd, int8_t d0, int8_t d1, int8_t d2, int8_t d3, int8_t rst); void hostedGetPins(int8_t *clk, int8_t *cmd, int8_t *d0, int8_t *d1, int8_t *d2, int8_t *d3, int8_t *rst); +void hostedGetHostVersion(uint32_t *major, uint32_t *minor, uint32_t *patch); +void hostedGetSlaveVersion(uint32_t *major, uint32_t *minor, uint32_t *patch); +bool hostedHasUpdate(); +char *hostedGetUpdateURL(); +bool hostedBeginUpdate(); +bool hostedWriteUpdate(uint8_t *buf, uint32_t len); +bool hostedEndUpdate(); +bool hostedActivateUpdate(); #ifdef __cplusplus } From 9167b18a800e6a61869a6193c9041c80455d1cc0 Mon Sep 17 00:00:00 2001 From: Me No Dev Date: Wed, 12 Nov 2025 16:00:54 +0200 Subject: [PATCH 22/23] IDF release/v5.5 8410210c (#12018) --- package/package_esp32_index.template.json | 68 +++++++++++------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/package/package_esp32_index.template.json b/package/package_esp32_index.template.json index 3219801be0c..32fba7d3082 100644 --- a/package/package_esp32_index.template.json +++ b/package/package_esp32_index.template.json @@ -51,7 +51,7 @@ { "packager": "esp32", "name": "esp32-arduino-libs", - "version": "idf-release_v5.5-f1a1df9b-v3" + "version": "idf-release_v5.5-8410210c-v2" }, { "packager": "esp32", @@ -104,63 +104,63 @@ "tools": [ { "name": "esp32-arduino-libs", - "version": "idf-release_v5.5-f1a1df9b-v3", + "version": "idf-release_v5.5-8410210c-v2", "systems": [ { "host": "i686-mingw32", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "x86_64-mingw32", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "arm64-apple-darwin", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "x86_64-apple-darwin", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "x86_64-pc-linux-gnu", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "i686-pc-linux-gnu", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "aarch64-linux-gnu", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" }, { "host": "arm-linux-gnueabihf", - "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-f1a1df9b-v3.zip", - "checksum": "SHA-256:35c0cc87b1965d0e70d599472dc6640e0363b05340488e73ccb7481d349906f3", - "size": "451353300" + "url": "https://github.com/espressif/esp32-arduino-lib-builder/releases/download/idf-release_v5.5/esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "archiveFileName": "esp32-arduino-libs-idf-release_v5.5-8410210c-v2.zip", + "checksum": "SHA-256:ebcc69e1db0681147c3ef145f4cd5a063a7d3cb87820ddf57e2a04e363e42223", + "size": "449287409" } ] }, From 491e2d21367a43626fedb8b22cb2f4449abb2078 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 14:05:15 +0000 Subject: [PATCH 23/23] change(version): Update core version to 3.3.4 --- .github/ISSUE_TEMPLATE/Issue-report.yml | 1 + .gitlab/workflows/common.yml | 2 +- cores/esp32/esp_arduino_version.h | 2 +- docs/conf_common.py | 2 +- libraries/ArduinoOTA/library.properties | 2 +- libraries/AsyncUDP/library.properties | 2 +- libraries/BLE/library.properties | 2 +- libraries/BluetoothSerial/library.properties | 2 +- libraries/DNSServer/library.properties | 2 +- libraries/EEPROM/library.properties | 2 +- libraries/ESP32/library.properties | 2 +- libraries/ESP_I2S/library.properties | 2 +- libraries/ESP_NOW/library.properties | 2 +- libraries/ESP_SR/library.properties | 2 +- libraries/ESPmDNS/library.properties | 2 +- libraries/Ethernet/library.properties | 2 +- libraries/FFat/library.properties | 2 +- libraries/FS/library.properties | 2 +- libraries/HTTPClient/library.properties | 2 +- libraries/HTTPUpdate/library.properties | 2 +- libraries/HTTPUpdateServer/library.properties | 2 +- libraries/Hash/library.properties | 2 +- libraries/Insights/library.properties | 2 +- libraries/LittleFS/library.properties | 2 +- libraries/Matter/library.properties | 2 +- libraries/NetBIOS/library.properties | 2 +- libraries/Network/library.properties | 2 +- libraries/NetworkClientSecure/library.properties | 2 +- libraries/OpenThread/library.properties | 2 +- libraries/PPP/library.properties | 2 +- libraries/Preferences/library.properties | 2 +- libraries/RainMaker/library.properties | 2 +- libraries/SD/library.properties | 2 +- libraries/SD_MMC/library.properties | 2 +- libraries/SPI/library.properties | 2 +- libraries/SPIFFS/library.properties | 2 +- libraries/SimpleBLE/library.properties | 2 +- libraries/TFLiteMicro/library.properties | 2 +- libraries/Ticker/library.properties | 2 +- libraries/USB/library.properties | 2 +- libraries/Update/library.properties | 2 +- libraries/WebServer/library.properties | 2 +- libraries/WiFi/library.properties | 2 +- libraries/WiFiProv/library.properties | 2 +- libraries/Wire/library.properties | 2 +- libraries/Zigbee/library.properties | 2 +- package.json | 2 +- platform.txt | 2 +- 48 files changed, 48 insertions(+), 47 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/Issue-report.yml b/.github/ISSUE_TEMPLATE/Issue-report.yml index b3c3e4a944c..53f28c46e89 100644 --- a/.github/ISSUE_TEMPLATE/Issue-report.yml +++ b/.github/ISSUE_TEMPLATE/Issue-report.yml @@ -43,6 +43,7 @@ body: - latest stable Release (if not listed below) - latest development Release Candidate (RC-X) - latest master (checkout manually) + - v3.3.4 - v3.3.3 - v3.3.2 - v3.3.1 diff --git a/.gitlab/workflows/common.yml b/.gitlab/workflows/common.yml index b5183114dc9..0f4bda9bcce 100644 --- a/.gitlab/workflows/common.yml +++ b/.gitlab/workflows/common.yml @@ -13,7 +13,7 @@ stages: variables: ESP_IDF_VERSION: "5.5" - ESP_ARDUINO_VERSION: "3.3.3" + ESP_ARDUINO_VERSION: "3.3.4" ############# # `default` # diff --git a/cores/esp32/esp_arduino_version.h b/cores/esp32/esp_arduino_version.h index 2919a4979a2..587fe02cd16 100644 --- a/cores/esp32/esp_arduino_version.h +++ b/cores/esp32/esp_arduino_version.h @@ -23,7 +23,7 @@ extern "C" { /** Minor version number (x.X.x) */ #define ESP_ARDUINO_VERSION_MINOR 3 /** Patch version number (x.x.X) */ -#define ESP_ARDUINO_VERSION_PATCH 3 +#define ESP_ARDUINO_VERSION_PATCH 4 /** * Macro to convert ARDUINO version number into an integer diff --git a/docs/conf_common.py b/docs/conf_common.py index 4e3a3e31f0d..0960d7c4315 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -4,7 +4,7 @@ # Used for substituting variables in the documentation rst_prolog = """ -.. |version| replace:: 3.3.3 +.. |version| replace:: 3.3.4 .. |idf_version| replace:: 5.5 """ diff --git a/libraries/ArduinoOTA/library.properties b/libraries/ArduinoOTA/library.properties index 19e4ff49497..604e21d2819 100644 --- a/libraries/ArduinoOTA/library.properties +++ b/libraries/ArduinoOTA/library.properties @@ -1,5 +1,5 @@ name=ArduinoOTA -version=3.3.3 +version=3.3.4 author=Ivan Grokhotkov and Hristo Gochkov maintainer=Hristo Gochkov sentence=Enables Over The Air upgrades, via wifi and espota.py UDP request/TCP download. diff --git a/libraries/AsyncUDP/library.properties b/libraries/AsyncUDP/library.properties index 2bddae6ed53..0dc51eae1f7 100644 --- a/libraries/AsyncUDP/library.properties +++ b/libraries/AsyncUDP/library.properties @@ -1,5 +1,5 @@ name=ESP32 Async UDP -version=3.3.3 +version=3.3.4 author=Me-No-Dev maintainer=Me-No-Dev sentence=Async UDP Library for ESP32 diff --git a/libraries/BLE/library.properties b/libraries/BLE/library.properties index 2c2b07649b7..f4faf62a79e 100644 --- a/libraries/BLE/library.properties +++ b/libraries/BLE/library.properties @@ -1,5 +1,5 @@ name=BLE -version=3.3.3 +version=3.3.4 author=Neil Kolban maintainer=lucasssvaz sentence=BLE functions for ESP32 diff --git a/libraries/BluetoothSerial/library.properties b/libraries/BluetoothSerial/library.properties index 0ed931d2e2a..03d5687a49e 100644 --- a/libraries/BluetoothSerial/library.properties +++ b/libraries/BluetoothSerial/library.properties @@ -1,5 +1,5 @@ name=BluetoothSerial -version=3.3.3 +version=3.3.4 author=Evandro Copercini maintainer=Evandro Copercini sentence=Simple UART to Classical Bluetooth bridge for ESP32 diff --git a/libraries/DNSServer/library.properties b/libraries/DNSServer/library.properties index 3f880f80b1e..6d124cace69 100644 --- a/libraries/DNSServer/library.properties +++ b/libraries/DNSServer/library.properties @@ -1,5 +1,5 @@ name=DNSServer -version=3.3.3 +version=3.3.4 author=Kristijan Novoselić maintainer=Kristijan Novoselić, sentence=A simple DNS server for ESP32. diff --git a/libraries/EEPROM/library.properties b/libraries/EEPROM/library.properties index 4e69f9ea949..bf03f1a66e1 100644 --- a/libraries/EEPROM/library.properties +++ b/libraries/EEPROM/library.properties @@ -1,5 +1,5 @@ name=EEPROM -version=3.3.3 +version=3.3.4 author=Ivan Grokhotkov maintainer=Paolo Becchi sentence=Enables reading and writing data a sequential, addressable FLASH storage diff --git a/libraries/ESP32/library.properties b/libraries/ESP32/library.properties index 122a53435a9..ef14a246302 100644 --- a/libraries/ESP32/library.properties +++ b/libraries/ESP32/library.properties @@ -1,5 +1,5 @@ name=ESP32 -version=3.3.3 +version=3.3.4 author=Hristo Gochkov, Ivan Grokhtkov maintainer=Hristo Gochkov sentence=ESP32 sketches examples diff --git a/libraries/ESP_I2S/library.properties b/libraries/ESP_I2S/library.properties index e1dc8e34a03..da985780ca7 100644 --- a/libraries/ESP_I2S/library.properties +++ b/libraries/ESP_I2S/library.properties @@ -1,5 +1,5 @@ name=ESP_I2S -version=3.3.3 +version=3.3.4 author=me-no-dev maintainer=me-no-dev sentence=Library for ESP I2S communication diff --git a/libraries/ESP_NOW/library.properties b/libraries/ESP_NOW/library.properties index 4483af3c038..cae0ed03dc3 100644 --- a/libraries/ESP_NOW/library.properties +++ b/libraries/ESP_NOW/library.properties @@ -1,5 +1,5 @@ name=ESP_NOW -version=3.3.3 +version=3.3.4 author=me-no-dev maintainer=P-R-O-C-H-Y sentence=Library for ESP_NOW diff --git a/libraries/ESP_SR/library.properties b/libraries/ESP_SR/library.properties index 8752b08b2ee..5e019e501a2 100644 --- a/libraries/ESP_SR/library.properties +++ b/libraries/ESP_SR/library.properties @@ -1,5 +1,5 @@ name=ESP_SR -version=3.3.3 +version=3.3.4 author=me-no-dev maintainer=me-no-dev sentence=Library for ESP Sound Recognition diff --git a/libraries/ESPmDNS/library.properties b/libraries/ESPmDNS/library.properties index 68327251265..44a14541f40 100644 --- a/libraries/ESPmDNS/library.properties +++ b/libraries/ESPmDNS/library.properties @@ -1,5 +1,5 @@ name=ESPmDNS -version=3.3.3 +version=3.3.4 author=Hristo Gochkov, Ivan Grokhtkov maintainer=Hristo Gochkov sentence=ESP32 mDNS Library diff --git a/libraries/Ethernet/library.properties b/libraries/Ethernet/library.properties index d5cf3006131..bc342dff285 100644 --- a/libraries/Ethernet/library.properties +++ b/libraries/Ethernet/library.properties @@ -1,5 +1,5 @@ name=Ethernet -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Enables network connection (local and Internet) using the ESP32 Ethernet. diff --git a/libraries/FFat/library.properties b/libraries/FFat/library.properties index dcce91754b8..707c593d9d2 100644 --- a/libraries/FFat/library.properties +++ b/libraries/FFat/library.properties @@ -1,5 +1,5 @@ name=FFat -version=3.3.3 +version=3.3.4 author=Hristo Gochkov, Ivan Grokhtkov, Larry Bernstone maintainer=Hristo Gochkov sentence=ESP32 FAT on Flash File System diff --git a/libraries/FS/library.properties b/libraries/FS/library.properties index c5c63775763..1ff59d3308d 100644 --- a/libraries/FS/library.properties +++ b/libraries/FS/library.properties @@ -1,5 +1,5 @@ name=FS -version=3.3.3 +version=3.3.4 author=Hristo Gochkov, Ivan Grokhtkov maintainer=Hristo Gochkov sentence=ESP32 File System diff --git a/libraries/HTTPClient/library.properties b/libraries/HTTPClient/library.properties index c685164c092..ffbcc9101be 100644 --- a/libraries/HTTPClient/library.properties +++ b/libraries/HTTPClient/library.properties @@ -1,5 +1,5 @@ name=HTTPClient -version=3.3.3 +version=3.3.4 author=Markus Sattler maintainer=Markus Sattler sentence=HTTP Client for ESP32 diff --git a/libraries/HTTPUpdate/library.properties b/libraries/HTTPUpdate/library.properties index f5a5bbe25bd..dcf5f1219d7 100644 --- a/libraries/HTTPUpdate/library.properties +++ b/libraries/HTTPUpdate/library.properties @@ -1,5 +1,5 @@ name=HTTPUpdate -version=3.3.3 +version=3.3.4 author=Markus Sattler maintainer=Markus Sattler sentence=Http Update for ESP32 diff --git a/libraries/HTTPUpdateServer/library.properties b/libraries/HTTPUpdateServer/library.properties index 9529c3831a8..bd034861f1e 100644 --- a/libraries/HTTPUpdateServer/library.properties +++ b/libraries/HTTPUpdateServer/library.properties @@ -1,5 +1,5 @@ name=HTTPUpdateServer -version=3.3.3 +version=3.3.4 author=Hristo Kapanakov maintainer= sentence=Simple HTTP Update server based on the WebServer diff --git a/libraries/Hash/library.properties b/libraries/Hash/library.properties index 8e416c03005..c497c42f71e 100644 --- a/libraries/Hash/library.properties +++ b/libraries/Hash/library.properties @@ -1,5 +1,5 @@ name=Hash -version=3.3.3 +version=3.3.4 author=lucasssvaz maintainer=lucasssvaz sentence=Bundle of hashing functions for the ESP32 diff --git a/libraries/Insights/library.properties b/libraries/Insights/library.properties index 49ffe5c0a1b..27285e999fe 100644 --- a/libraries/Insights/library.properties +++ b/libraries/Insights/library.properties @@ -1,5 +1,5 @@ name=ESP Insights -version=3.3.3 +version=3.3.4 author=Sanket Wadekar maintainer=Sanket Wadekar sentence=ESP Insights diff --git a/libraries/LittleFS/library.properties b/libraries/LittleFS/library.properties index e85cd5b4810..f5ad750a315 100644 --- a/libraries/LittleFS/library.properties +++ b/libraries/LittleFS/library.properties @@ -1,5 +1,5 @@ name=LittleFS -version=3.3.3 +version=3.3.4 author= maintainer= sentence=LittleFS for esp32 diff --git a/libraries/Matter/library.properties b/libraries/Matter/library.properties index 29d698d9f0e..b95e4e09a10 100644 --- a/libraries/Matter/library.properties +++ b/libraries/Matter/library.properties @@ -1,5 +1,5 @@ name=Matter -version=3.3.3 +version=3.3.4 author=Rodrigo Garcia | GitHub @SuGlider maintainer=Rodrigo Garcia sentence=Library for supporting Matter environment on ESP32. diff --git a/libraries/NetBIOS/library.properties b/libraries/NetBIOS/library.properties index 32609f02d6a..527a4aa1835 100644 --- a/libraries/NetBIOS/library.properties +++ b/libraries/NetBIOS/library.properties @@ -1,5 +1,5 @@ name=NetBIOS -version=3.3.3 +version=3.3.4 author=Pablo@xpablo.cz maintainer=Hristo Gochkov sentence=Enables NBNS (NetBIOS) name resolution. diff --git a/libraries/Network/library.properties b/libraries/Network/library.properties index 4e11bf73edc..f6c465eebb5 100644 --- a/libraries/Network/library.properties +++ b/libraries/Network/library.properties @@ -1,5 +1,5 @@ name=Networking -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=General network management library. diff --git a/libraries/NetworkClientSecure/library.properties b/libraries/NetworkClientSecure/library.properties index 02c0e566e38..2b867985222 100644 --- a/libraries/NetworkClientSecure/library.properties +++ b/libraries/NetworkClientSecure/library.properties @@ -1,5 +1,5 @@ name=NetworkClientSecure -version=3.3.3 +version=3.3.4 author=Evandro Luis Copercini maintainer=Github Community sentence=Enables secure network connection (local and Internet) using the ESP32 built-in WiFi. diff --git a/libraries/OpenThread/library.properties b/libraries/OpenThread/library.properties index d29ce033544..68b9c85f864 100644 --- a/libraries/OpenThread/library.properties +++ b/libraries/OpenThread/library.properties @@ -1,5 +1,5 @@ name=OpenThread -version=3.3.3 +version=3.3.4 author=Rodrigo Garcia | GitHub @SuGlider maintainer=Rodrigo Garcia sentence=Library for OpenThread Network on ESP32. diff --git a/libraries/PPP/library.properties b/libraries/PPP/library.properties index 8a4590ce1ac..b6ce0d16f34 100644 --- a/libraries/PPP/library.properties +++ b/libraries/PPP/library.properties @@ -1,5 +1,5 @@ name=PPP -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Enables network connection using GSM Modem. diff --git a/libraries/Preferences/library.properties b/libraries/Preferences/library.properties index ea452b9e363..a9e3932888e 100644 --- a/libraries/Preferences/library.properties +++ b/libraries/Preferences/library.properties @@ -1,5 +1,5 @@ name=Preferences -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Provides friendly access to ESP32's Non-Volatile Storage diff --git a/libraries/RainMaker/library.properties b/libraries/RainMaker/library.properties index 6c7d63a1c1f..af0c63b233b 100644 --- a/libraries/RainMaker/library.properties +++ b/libraries/RainMaker/library.properties @@ -1,5 +1,5 @@ name=ESP RainMaker -version=3.3.3 +version=3.3.4 author=Sweety Mhaiske maintainer=Hristo Gochkov sentence=ESP RainMaker Support diff --git a/libraries/SD/library.properties b/libraries/SD/library.properties index 81fcfc705b5..4bb9876e684 100644 --- a/libraries/SD/library.properties +++ b/libraries/SD/library.properties @@ -1,5 +1,5 @@ name=SD -version=3.3.3 +version=3.3.4 author=Arduino, SparkFun maintainer=Arduino sentence=Enables reading and writing on SD cards. For all Arduino boards. diff --git a/libraries/SD_MMC/library.properties b/libraries/SD_MMC/library.properties index 31447c8b95a..6011ed115ea 100644 --- a/libraries/SD_MMC/library.properties +++ b/libraries/SD_MMC/library.properties @@ -1,5 +1,5 @@ name=SD_MMC -version=3.3.3 +version=3.3.4 author=Hristo Gochkov, Ivan Grokhtkov maintainer=Hristo Gochkov sentence=ESP32 SDMMC File System diff --git a/libraries/SPI/library.properties b/libraries/SPI/library.properties index 9c4c8abec3e..15a17d9101c 100644 --- a/libraries/SPI/library.properties +++ b/libraries/SPI/library.properties @@ -1,5 +1,5 @@ name=SPI -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Enables the communication with devices that use the Serial Peripheral Interface (SPI) Bus. For all Arduino boards, BUT Arduino DUE. diff --git a/libraries/SPIFFS/library.properties b/libraries/SPIFFS/library.properties index 5e73cf85f84..923172dd6ae 100644 --- a/libraries/SPIFFS/library.properties +++ b/libraries/SPIFFS/library.properties @@ -1,5 +1,5 @@ name=SPIFFS -version=3.3.3 +version=3.3.4 author=Hristo Gochkov, Ivan Grokhtkov maintainer=Hristo Gochkov sentence=ESP32 SPIFFS File System diff --git a/libraries/SimpleBLE/library.properties b/libraries/SimpleBLE/library.properties index 78c6d010b4b..cfa030f860d 100644 --- a/libraries/SimpleBLE/library.properties +++ b/libraries/SimpleBLE/library.properties @@ -1,5 +1,5 @@ name=SimpleBLE -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Provides really simple BLE advertizer with just on and off diff --git a/libraries/TFLiteMicro/library.properties b/libraries/TFLiteMicro/library.properties index 7aa9c1381e9..52641b149d1 100644 --- a/libraries/TFLiteMicro/library.properties +++ b/libraries/TFLiteMicro/library.properties @@ -1,5 +1,5 @@ name=TFLite Micro -version=3.3.3 +version=3.3.4 author=Sanket Wadekar maintainer=Sanket Wadekar sentence=TensorFlow Lite for Microcontrollers diff --git a/libraries/Ticker/library.properties b/libraries/Ticker/library.properties index ccb63ec4f98..441519edab0 100644 --- a/libraries/Ticker/library.properties +++ b/libraries/Ticker/library.properties @@ -1,5 +1,5 @@ name=Ticker -version=3.3.3 +version=3.3.4 author=Bert Melis maintainer=Hristo Gochkov sentence=Allows to call functions with a given interval. diff --git a/libraries/USB/library.properties b/libraries/USB/library.properties index cb4ddfe231b..8698f2cffbe 100644 --- a/libraries/USB/library.properties +++ b/libraries/USB/library.properties @@ -1,5 +1,5 @@ name=USB -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=ESP32S2 USB Library diff --git a/libraries/Update/library.properties b/libraries/Update/library.properties index bb1ce7dd38d..e1b77c462b1 100644 --- a/libraries/Update/library.properties +++ b/libraries/Update/library.properties @@ -1,5 +1,5 @@ name=Update -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=ESP32 Sketch Update Library diff --git a/libraries/WebServer/library.properties b/libraries/WebServer/library.properties index 33a24010ecc..4d491effc14 100644 --- a/libraries/WebServer/library.properties +++ b/libraries/WebServer/library.properties @@ -1,5 +1,5 @@ name=WebServer -version=3.3.3 +version=3.3.4 author=Ivan Grokhotkov maintainer=Ivan Grokhtkov sentence=Simple web server library diff --git a/libraries/WiFi/library.properties b/libraries/WiFi/library.properties index 3f22467ad0d..61e8ddb0ca5 100644 --- a/libraries/WiFi/library.properties +++ b/libraries/WiFi/library.properties @@ -1,5 +1,5 @@ name=WiFi -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Enables network connection (local and Internet) using the ESP32 built-in WiFi. diff --git a/libraries/WiFiProv/library.properties b/libraries/WiFiProv/library.properties index 134d86472f8..0a4aa5f9837 100644 --- a/libraries/WiFiProv/library.properties +++ b/libraries/WiFiProv/library.properties @@ -1,5 +1,5 @@ name=WiFiProv -version=3.3.3 +version=3.3.4 author=Switi Mhaiske maintainer=Hristo Gochkov sentence=Enables provisioning. diff --git a/libraries/Wire/library.properties b/libraries/Wire/library.properties index 72f3278a8d7..f016c349b88 100644 --- a/libraries/Wire/library.properties +++ b/libraries/Wire/library.properties @@ -1,5 +1,5 @@ name=Wire -version=3.3.3 +version=3.3.4 author=Hristo Gochkov maintainer=Hristo Gochkov sentence=Allows the communication between devices or sensors connected via Two Wire Interface Bus. For esp8266 boards. diff --git a/libraries/Zigbee/library.properties b/libraries/Zigbee/library.properties index 9f5fc6ef46e..cb671149723 100644 --- a/libraries/Zigbee/library.properties +++ b/libraries/Zigbee/library.properties @@ -1,5 +1,5 @@ name=Zigbee -version=3.3.3 +version=3.3.4 author=P-R-O-C-H-Y maintainer=Jan Procházka sentence=Enables zigbee connection with the ESP32 diff --git a/package.json b/package.json index 6c609c154bc..b8e8085d815 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "framework-arduinoespressif32", - "version": "3.3.3", + "version": "3.3.4", "description": "Arduino Wiring-based Framework for the Espressif ESP32, ESP32-P4, ESP32-S and ESP32-C series of SoCs", "keywords": [ "framework", diff --git a/platform.txt b/platform.txt index ff0f7c92062..d715c0e2dca 100644 --- a/platform.txt +++ b/platform.txt @@ -1,5 +1,5 @@ name=ESP32 Arduino -version=3.3.3 +version=3.3.4 tools.esp32-arduino-libs.path={runtime.platform.path}/tools/esp32-arduino-libs tools.esp32-arduino-libs.path.windows={runtime.platform.path}\tools\esp32-arduino-libs