Merge branch 'v1.1_docs' into 'main'

docs: update for v1.1 release

See merge request espressif/esp-thread-br!142

Author: chshu

.gitlab-ci.yml

@@ -57,8 +57,6 @@ pre_commit:
   - cd $ESP_THREAD_BR_PATH/examples/basic_thread_border_router
   - rm -rf CMakeLists.txt
   - cp ${CI_TOOLS_PATH}/basic_thread_border_router.cmake CMakeLists.txt
-  - rm -rf sdkconfig.defaults
-  - cp ${CI_TOOLS_PATH}/sdkconfig.br.basic sdkconfig.defaults
   - idf.py build
 
 .build_local_components: &build_local_components
@@ -72,8 +70,6 @@ pre_commit:
   - cp ${CI_TOOLS_PATH}/idf_component_local.yml main/idf_component.yml
   - rm -rf CMakeLists.txt
   - cp ${CI_TOOLS_PATH}/basic_thread_border_router.cmake CMakeLists.txt
-  - rm -rf sdkconfig.defaults
-  - cp ${CI_TOOLS_PATH}/sdkconfig.br.basic sdkconfig.defaults
   - idf.py build
 
 .build_idf_example_ot_br: &build_idf_example_ot_br

README.md

@@ -8,6 +8,8 @@ ESP-THREAD-BR is the official [ESP Thread Border Router](https://openthread.io/g
 
 The SDK is built on top of [ESP-IDF](https://github.com/espressif/esp-idf) and [OpenThread](https://github.com/openthread/openthread). The OpenThread port and ESP Border Router implementation is provided as pre-built library in ESP-IDF.
 
+It is recommended to use ESP-IDF [v5.3.1](https://github.com/espressif/esp-idf/tree/v5.3.1) with this SDK.
+
 # Hardware Platforms
 
 ## Wi-Fi based Thread Border Router

components/esp_ot_cli_extension/CMakeLists.txt

@@ -28,18 +28,16 @@ if(CONFIG_OPENTHREAD_RCP_COMMAND)
 endif()
 
 set(include "include")
-if(CONFIG_OPENTHREAD_CLI_WIFI)
-    list(APPEND include $ENV{IDF_PATH}/examples/common_components/protocol_examples_common/include)
-endif()
+
 idf_component_register(SRCS "${srcs}"
                     INCLUDE_DIRS "${include}"
                     PRIV_REQUIRES lwip openthread iperf esp_netif esp_wifi http_parser esp_http_client esp_coex heap mbedtls nvs_flash esp_eth)
 
-if (CONFIG_OPENTHREAD_CLI_OTA)
-    idf_component_optional_requires(PUBLIC esp_br_http_ota)
+if(CONFIG_OPENTHREAD_CLI_OTA)
+    idf_component_optional_requires(PRIVATE esp_br_http_ota)
 endif()
 
-if (CONFIG_OPENTHREAD_RCP_COMMAND)
+if(CONFIG_OPENTHREAD_RCP_COMMAND)
     idf_component_optional_requires(PRIVATE esp_rcp_update)
 endif()
 

components/esp_ot_cli_extension/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.2.4"
+version: "1.2.5"
 description: Espressif OpenThread CLI Extension
 url: https://github.com/espressif/esp-thread-br/tree/main/components/esp_ot_cli_extension
 dependencies:

docs/en/dev-guide/build_and_run.rst

@@ -9,9 +9,11 @@ This document contains instructions on building the images for ESP Thread Border
 
 Clone the `esp-idf <https://github.com/espressif/esp-idf>`_ and the `esp-thread-br <https://github.com/espressif/esp-thread-br>`_ repository.
 
+It is recommended to use ESP-IDF `v5.3.1 <https://github.com/espressif/esp-idf/tree/v5.3.1>`_ with this SDK.
+
 .. code-block:: bash
 
-   git clone -b v5.1.3 --recursive https://github.com/espressif/esp-idf.git
+   git clone -b v5.3.1 --recursive https://github.com/espressif/esp-idf.git
 
 .. code-block:: bash
 
@@ -85,6 +87,22 @@ For any other customized settings, you can configure the project in menuconfig.
 
    idf.py menuconfig
 
+.. note::
+
+   `LWIP_IPV6_NUM_ADDRESSES` configuration is fixed in the border router library, it was changed from 8 to 12 since IDF v5.3.1 release. Please update this configuration based on the following table:
+
+      +--------------------+-------------------------+
+      |    IDF Versions    | LWIP_IPV6_NUM_ADDRESSES |
+      +--------------------+-------------------------+
+      | v5.1.4 and earlier |            8            |
+      +--------------------+-------------------------+
+      | v5.2.2 and earlier |            8            |
+      +--------------------+-------------------------+
+      | v5.3.0             |            8            |
+      +--------------------+-------------------------+
+      | v5.3.1 and later   |            12           |
+      +--------------------+-------------------------+
+
 2.1.3.1. Wi-Fi based Thread Border Router
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

examples/basic_thread_border_router/CMakeLists.txt

@@ -2,13 +2,5 @@
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
-# (Not part of the boilerplate)
-# This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
-set(EXTRA_COMPONENT_DIRS
-    ${CMAKE_CURRENT_SOURCE_DIR}/../common
-    ${CMAKE_CURRENT_SOURCE_DIR}/../../components/esp_br_http_ota
-    ${CMAKE_CURRENT_SOURCE_DIR}/../../components/esp_ot_br_server
-)
-
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(esp_ot_br)

examples/basic_thread_border_router/README.md

@@ -14,25 +14,30 @@ Please refer to [ESP Thread Border Router Hardware](../../README.md##Hardware-Pl
 
 Refer to [ESP-IDF Get Started](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/index.html).
 
-Note that it is recommended to use the latest [esp-idf](https://github.com/espressif/esp-idf).
+It is recommended to use ESP-IDF [v5.3.1](https://github.com/espressif/esp-idf/tree/v5.3.1) with this example.
 
 ### Configure the project
 
-ESP32-S3 is the host SoC on ESP Thread Border Router Board, so set target to esp32s3:
+ESP32-S3 is the host SoC on ESP Thread Border Router Board, esp32s3 is selected by default in the example. Set the other target with this command:
 
 ```
-idf.py set-target esp32s3
+idf.py set-target <target>
 ```
 
-The host could be pre-configured with `OPENTHREAD_RADIO_SPINEL_UART` or `OPENTHREAD_RADIO_SPINEL_SPI` to select UART or SPI to access the Radio Co-Processor.
-
-If the `OPENTHREAD_BR_AUTO_START` option is enabled, the device will connect to the configured Wi-Fi and form Thread network automatically then act as the border router.
+`LWIP_IPV6_NUM_ADDRESSES` configuration is fixed in the border router library, it was changed from 8 to 12 since IDF v5.3.1 release. Please update this configuration based on the following table:
 
-The Wi-Fi network's ssid and psk needs to be pre-configured with `EXAMPLE_WIFI_SSID` and `EXAMPLE_WIFI_PASSWORD`.
+|     IDF Versions        |  LWIP_IPV6_NUM_ADDRESSES  |
+|:-----------------------:|:-------------------------:|
+|   v5.1.4 and earlier    |            8              |
+|   v5.2.2 and earlier    |            8              |
+|   v5.3.0                |            8              |
+|   v5.3.1 and later      |            12             |
 
-Note that in this mode, the device will first attempt to use the Wi-Fi SSID and password stored in NVS. If no Wi-Fi information is stored, it will then use the `EXAMPLE_WIFI_SSID` and `EXAMPLE_WIFI_PASSWORD` from menuconfig.
+The host could be pre-configured with `OPENTHREAD_RADIO_SPINEL_UART` or `OPENTHREAD_RADIO_SPINEL_SPI` to select UART or SPI to access the Radio Co-Processor.
 
-The Thread network parameters could be pre-configured with `OPENTHREAD_NETWORK_xx` options.
+If the `OPENTHREAD_BR_AUTO_START` option is enabled, the device will connect to the configured Wi-Fi and form Thread network automatically then act as the border router:
+- The Wi-Fi network's ssid and psk needs to be pre-configured with `EXAMPLE_WIFI_SSID` and `EXAMPLE_WIFI_PASSWORD`. In this mode, the device will first attempt to use the Wi-Fi SSID and password stored in NVS. If no Wi-Fi information is stored, it will then use the pre-configured ssid and psk.
+- The Thread network parameters could be pre-configured with `OPENTHREAD_NETWORK_xx` options.
 
 If the `OPENTHREAD_BR_START_WEB` option is enabled, [ESP Thread Border Router Web Server](../../components/esp_ot_br_server/README.md) will be provided to configure and query Thread network via a Web GUI.
 

examples/basic_thread_border_router/main/idf_component.yml

@@ -7,9 +7,15 @@ dependencies:
   espressif/esp_rcp_update:
     version: "~1.3.0"
     override_path: '../../../components/esp_rcp_update'
+  esp_br_http_ota:
+    path: ../../../components/esp_br_http_ota
+  esp_ot_br_server:
+    path: ../../../components/esp_ot_br_server
+  thread_border_router:
+    path: ../../common/thread_border_router
+  protocol_examples_common:
+    path: ${IDF_PATH}/examples/common_components/protocol_examples_common
+
   ## Required IDF version
   idf:
-    version: ">=4.1.0"
-  # # Put list of dependencies here
-  protocol_examples_common:
-     path: ${IDF_PATH}/examples/common_components/protocol_examples_common
+    version: ">=5.1.0"

examples/basic_thread_border_router/sdkconfig.defaults

@@ -60,7 +60,10 @@ CONFIG_AUTO_UPDATE_RCP=y
 # lwIP
 #
 CONFIG_LWIP_IPV6_FORWARD=y
-CONFIG_LWIP_IPV6_NUM_ADDRESSES=8
+
+# Use 12 with IDF v5.3.1 and later, and use 8 with earlier versions of IDF.
+CONFIG_LWIP_IPV6_NUM_ADDRESSES=12
+
 CONFIG_LWIP_MULTICAST_PING=y
 CONFIG_LWIP_NETIF_STATUS_CALLBACK=y
 CONFIG_LWIP_HOOK_IP6_ROUTE_DEFAULT=y

tools/ci/basic_thread_border_router.cmake

@@ -8,14 +8,5 @@ set(ENV{EXTRA_CFLAGS} "-Werror -Werror=deprecated-declarations -Werror=unused-va
 set(ENV{EXTRA_CXXFLAGS} "-Werror -Werror=deprecated-declarations -Werror=unused-variable \
     -Werror=unused-but-set-variable -Werror=unused-function")
 
-# (Not part of the boilerplate)
-# This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
-set(EXTRA_COMPONENT_DIRS
-    ${CMAKE_CURRENT_SOURCE_DIR}/../common
-    ${CMAKE_CURRENT_SOURCE_DIR}/../../components/esp_br_http_ota
-    ${CMAKE_CURRENT_SOURCE_DIR}/../../components/esp_ot_br_server
-    $ENV{IDF_PATH}/examples/common_components/protocol_examples_common
-)
-
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(esp_ot_br)