Merge branch 'docs/refine_docs' into 'main'

docs: add more supported features and faq

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

Author: chshu

README.md

@@ -1,20 +1,20 @@
-# ESP Thread Boarder Router SDK
+# ESP Thread Border Router SDK
 
-ESP-THREAD-BR is the official [ESP Thread Border Router](https://openthread.io/guides/border-router/espressif-esp32) SDK. It supports all fundamental network features to build a Thread Border Router and integrates rich product level features for quick productization.
+ESP-THREAD-BR is the official Espressif Thread Border Router SDK. It supports all fundamental network features to build a [Thread Border Router](https://openthread.io/guides/border-router) (BR) and integrates rich product level features for quick productization.
 
 # Software Components
 
 ![esp_br_solution](docs/images/esp-thread-border-router-solution.png)
 
-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.
+The SDK is built on top of [ESP-IDF](https://github.com/espressif/esp-idf) and [OpenThread](https://github.com/openthread/openthread). The BR implementation is provided as pre-built library in ESP-IDF.
 
 # Hardware Platforms
 
 ## Wi-Fi based Thread Border Router
 
-The Wi-Fi based ESP Thread Border Router consists of two SoCs:
+The Wi-Fi based ESP Thread BR consists of two SoCs:
 
-* An ESP32 series Wi-Fi SoC (ESP32, ESP32-C, ESP32-S, etc) loaded with ESP Thread Border Router and OpenThread Stack.
+* An ESP32 series Wi-Fi SoC (ESP32, ESP32-C, ESP32-S, etc) loaded with ESP Thread BR and OpenThread Stack.
 * An ESP32-H 802.15.4 SoC loaded with OpenThread RCP.
 
 ### ESP Thread Border Router Board
@@ -55,33 +55,33 @@ ESP32 pin           | ESP32-H2 pin
   GPIO13 (SPI MISO) |     GPIO1
 
 Note that:
-1. The GPIO17 and GPIO18 on ESP32-S3 have different driver current([refer to ESP32-S3 TRM, Chapter 6.12](https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf)). If ESP32-S3 is used as the host, please change the UART RX/TX GPIOs to GPIO4 and GPIO5 which are recommended.
+1. Please update the GPIO pin configuration (`radio_uart_config`) in `esp_ot_config.h` for both the ot_rcp and ot_br examples to accurately reflect the GPIO connections between the Wi-Fi and 802.15.4 SoCs.
 
 2. The configure `ESP_CONSOLE_USB_SERIAL_JTAG` is enabled by default, please connect the USB port of the ESP32 series Wi-Fi SoC to host.
 
 ## Ethernet based Thread Border Router
 
-Similar to the previous Wi-Fi based Thread Border Router setup, but a device with Ethernet interface is required, such as [ESP32-Ethernet-Kit](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-ethernet-kit.html).
+Similar to the previous Wi-Fi based Thread BR setup, but a device with Ethernet interface is required, such as [ESP32-Ethernet-Kit](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-ethernet-kit.html).
 
 # Provided Features
 
 These features are currently provided by the SDK:
 
-* **Bi-directional IPv6 Connectivity**: The devices on the backbone link (typically Wi-Fi) and the Thread network can reach each other.
-* **Service Discovery Delegate**: The nodes on the Thread network can find the mDNS services on the backbone link.
-* **Service Registration Server**: The nodes on the Thread network can register services to the border router for devices on the backbone link to discover.
+* **Bi-directional IPv6 Connectivity**: The devices on the backbone link (typically Wi-Fi or Ethernet) and the Thread network can reach each other.
+* **Service Discovery Delegate**: The devices on the Thread network can find the mDNS services on the backbone link.
+* **Service Registration Server**: The devices on the Thread network can register services to the BR for devices on the backbone link to discover.
 * **Multicast Forwarding**: The devices joining the same multicast group on the backbone link and the Thread network can be reached with one single multicast.
-* **NAT64**: The devices can access the IPv4 Internet via the border router.
-* **RCP Update**: The built border router image will contain an updatable RCP image and can automatically update the RCP on version mismatch or RCP failure.
-* **Web GUI**: The border router will enable a web server and provide some practical functions including Thread network discovery, network formation and status query. 
-* **RF Coexistence**: The border router supports optional external coexistence, a feature that enhances the transmission performance when there are channel conflicts between the Wi-Fi and Thread networks.
+* **NAT64**: The devices can access the IPv4 Internet via the BR.
+* **Credential Sharing**: The BR could safely share administrative access and allow extracting the network credentials of the network.
+* **TREL**: It enables Thread devices to communicate directly over IPv6-based links other than IEEE 802.15.4, including Wi-Fi and Ethernet.
+* **RCP Update**: The built BR image will contain an updatable RCP image and can automatically update the RCP on version mismatch or RCP failure.
+* **Web GUI**: The BR will enable a web server and provide some practical functions including Thread network discovery, network formation, status query and topology monitor.
+* **RF Coexistence**: The BR supports optional external coexistence, a feature that enhances the transmission performance when there are channel conflicts between the Wi-Fi and Thread networks.
 
 # Resources
 
 * Documentation for the latest version: https://docs.espressif.com/projects/esp-thread-br/. This documentation is built from the [docs directory](docs) of this repository.
 
-* The [esp32.com forum](https://esp32.com/) is a place to ask questions and find community resources.
-
 * [Check the Issues section on github](https://github.com/espressif/esp-thread-br/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one.
 
 * If you're interested in contributing to ESP-THREAD-BR, please check the [Contributions Guide](https://docs.espressif.com/projects/esp-idf/en/latest/contribute/index.html).

docs/en/codelab/home_assistant.rst

@@ -0,0 +1,74 @@
+*******************************
+3.7. Home Assistant Integration
+*******************************
+
+Home Assistant offers integration with `OpenThread Border Routers <https://www.home-assistant.io/integrations/thread/#openthread-border-routers>`_, which can be configured and controlled via REST APIs.
+
+The Espressif Thread BR solution provides the same `REST APIs <https://docs.espressif.com/projects/esp-thread-br/en/latest/codelab/web-gui.html#thread-rest-apis>`_ as OpenThread Border Routers (based on ot-br-posix), making it compatible with Home Assistant.
+
+Hardware Prerequisites
+----------------------
+
+- An ESP Thread Border Router
+- A `Home Assistant Hub <https://www.home-assistant.io/installation/>`_
+- A smartphone with the Home Assistant App installed
+
+The ESP Thread BR firmware must have the ``CONFIG_OPENTHREAD_BR_START_WEB`` option enabled to activate the Web Server feature.
+
+Ensure that the ESP Thread BR, Home Assistant Hub, and smartphone are connected to the same local network via Wi-Fi or Ethernet.
+
+Add OpenThread Border Router Integration
+----------------------------------------
+
+In the Home Assistant App, navigate to ``Settings`` -> ``Devices & services`` -> ``ADD INTEGRATION``, then add the following integrations:
+
+- OpenThread Border Router
+- Thread
+
+.. figure:: ../../images/HA_Thread_BR1.png
+   :align: center
+   :alt: Add Thread integrations
+   :figclass: align-center
+
+   Add Thread integrations
+
+Once the ESP Thread BR successfully connects to Wi-Fi and starts a Web server, obtain it's IPv4 address from the log entries (as shown below):
+
+.. code-block::
+
+    I (5211) obtr_web: <=======================server start========================>
+
+    I (5211) obtr_web: http://192.168.3.112:80/index.html
+
+    I (5211) obtr_web: <===========================================================>
+
+Go to the ``OpenThread Border Router`` integration, click ``ADD SERVICE``, then enter the IPv4 address of the Thread BR obtained earlier (with port number) in the ``URL`` field:
+
+.. code-block::
+
+    http://192.168.3.112:80
+
+The Home Assistant App will communicate with the Thread BR using Rest APIs once the URL has been successfully configured.
+
+.. figure:: ../../images/HA_Thread_BR2.png
+   :align: center
+   :alt: Add Thread BR service
+   :figclass: align-center
+
+   Add Thread BR service
+
+Add Thread Integration
+----------------------
+
+Go to the ``Thread`` integration and click ``CONFIGURE``, and ensure that the ESP Thread BR has been selected as the preferred network.
+
+Next, click ``Send Credentials to Home Assistant`` and ``Send Credentials To Phone``. Home Assistant will retrieve the Thread credentials from the BR and store them in the user's account.
+
+The Thread BR integration is now complete. You can now add Thread-based devices, such as those using the Matter integration.
+
+.. figure:: ../../images/HA_Thread_BR3.png
+   :align: center
+   :alt: Add Matter over Thread device
+   :figclass: align-center
+
+   Add Matter over Thread device

docs/en/codelab/index.rst

@@ -12,5 +12,6 @@
    nat64
    web-gui
    trel
+   home_assistant
 
 

docs/en/dev-guide/build_and_run.rst

@@ -9,10 +9,10 @@ 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.
 
-The current esp-thread-br master branch is compatible with the ESP-IDF commit `e6aeb3d <https://github.com/espressif/esp-idf/commit/e6aeb3d36d2fcaf578e4e53308191a8e262dc822>`_.
-
 Refer to the specific tags for each stable release at `esp-thread-br releases <https://github.com/espressif/esp-thread-br/releases>`_.
 
+Follow the steps below to obtain the latest esp-thread-br master branch and the recommended ESP-IDF version `v5.2.4 <https://github.com/espressif/esp-idf/tree/v5.2.4>`_ release:
+
 .. code-block:: bash
 
    git clone --recursive https://github.com/espressif/esp-idf.git
@@ -23,7 +23,7 @@ Refer to the specific tags for each stable release at `esp-thread-br releases <h
 
 .. code-block:: bash
 
-   git checkout e6aeb3d36d2fcaf578e4e53308191a8e262dc822
+   git checkout v5.2.4
 
 .. code-block:: bash
 
@@ -63,16 +63,13 @@ Select the ESP32-H2 as the RCP.
 
    idf.py set-target esp32h2
 
-The default communication interface on the ESP Thread Border Router board is UART0 with 460800 baudrate, which can be configured in `esp_ot_config.h <https://github.com/espressif/esp-idf/blob/master/examples/openthread/ot_rcp/main/esp_ot_config.h>`_.
-
-.. code-block:: bash
-
-   idf.py menuconfig
-
 .. code-block:: bash
 
    idf.py build
 
+.. note::
+
+   The default communication interface on the ESP Thread Border Router board uses UART0 with `baud rate = 460800`. If you are setting up a project using standalone modules, please update the UART configurations (`radio_uart_config`) in `esp_ot_config.h <https://github.com/espressif/esp-idf/blob/master/examples/openthread/ot_rcp/main/esp_ot_config.h>`_ before building the project.
 
 2.1.3. Configure ESP Thread Border Router
 -----------------------------------------
@@ -101,17 +98,17 @@ For any other customized settings, you can configure the project in menuconfig.
 
    `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           |
-      +--------------------+-------------------------+
+      +----------------------------------------+-------------------------+
+      |    IDF Versions                        | LWIP_IPV6_NUM_ADDRESSES |
+      +----------------------------------------+-------------------------+
+      | v5.1.4 and earlier                     |            8            |
+      +----------------------------------------+-------------------------+
+      | v5.2.2 and earlier                     |            8            |
+      +----------------------------------------+-------------------------+
+      | v5.3.0                                 |            8            |
+      +----------------------------------------+-------------------------+
+      | v5.1.5, v5.2.3, v5.3.1, v5.4 and later |            12           |
+      +----------------------------------------+-------------------------+
 
 2.1.3.1. Wi-Fi based Thread Border Router
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/en/hardware_platforms.rst

@@ -57,7 +57,7 @@ The development board has a variety of variants to choose from, as shown in the
 
    * - ESP Thread BR-Zigbee GW
      - ESP32-S3-WROOM-1 and ESP32-H2-MINI-1
-     - 4 MB
+     - 8 MB [B]_
      - 2 MB
      - ESP Thread Border Router/Zigbee Gateway Board
    * - ESP Thread BR-Zigbee GW_SUB
@@ -67,6 +67,7 @@ The development board has a variety of variants to choose from, as shown in the
      - ESP Thread Border Router/Zigbee Gateway Sub-Ethernet
 
 .. [A] The flash is integrated in the chip's package.
+.. [B] It was 4 MB in some early samples.
 
 Retail Orders
 ^^^^^^^^^^^^^

docs/en/index.rst

@@ -18,6 +18,8 @@ It provides the following features:
   - Service Discovery
   - Multicast Forwarding
   - NAT64
+  - Credential Sharing
+  - TREL
   - RCP update
   - RF coexistence
   - Web GUI