Thread integration page: update and add more content (#30913)

* Thread integration: update, rough draft

* Code-fence term to satisfy linter

* Improve cohesion

* First mention of TBR: add link to explainer section

* Fix typo

* Fix typo

* Cleanup logic and cohesion in logo section

* Fix typo

* Rephrase

* Improve section intro

* Tweaks

* Fix titles

* Remove procedural content from description

* remove redundant information, add missing word

* Tweaks

* Restructure network section

* Restructure preferred network section

* Rename headings

* Tweak

* Remove reduant information on other manufaturers

* Apply suggestions from code review

Co-authored-by: Stefan Agner <stefan@agner.ch>

* Fix Thread logo

* Add link to procedure on enabling Thread on SkyConnect

* Rephrase statement on mDNS announcements

* Tiny tweak

* Using HA as TBR without adding a 3rd TBR first

- add section
- partially addresses feedback from #30822

* Note that Thread support on Yellow and SkyConnetc is experimental

- implements review feedback

* Make it clear that logo is on the packaging

* Remove reference to multiprotocol add-on, as per review comment

* rephrase

Co-authored-by: Marcel van der Veldt <m.vanderveldt@outlook.com>

* Update source/_integrations/thread.markdown

Co-authored-by: Marcel van der Veldt <m.vanderveldt@outlook.com>

* Add note the HA only OTBR setup does not work with iOS Companion App

* for HA only OTBR, no other Thread networks present

* Apply suggestions from code review

Co-authored-by: Stefan Agner <stefan@agner.ch>

* HA border router: add note that limited to Android

* Tweak

* List of border routers: add links to Matter/HomeKit to check prereqs

* Add missing link to Thread on Yellow

---------

Co-authored-by: Stefan Agner <stefan@agner.ch>
Co-authored-by: Marcel van der Veldt <m.vanderveldt@outlook.com>

source/_integrations/homekit_controller.markdown

@@ -52,7 +52,7 @@ There are different methods to add a HomeKit device to Home Assistant:
 
 - [via Ethernet or Wi-Fi](#adding-a-homekit-device-via-ethernet-or-wi-fi)
 - [via Bluetooth](#adding-a-homekit-device-through-bluetooth)
-- via Thread
+- [via Thread](#adding-a-homekit-device-through-thread)
   - [by using Home Assistant’s preferred Thread network](#adding-a-homekit-device-to-a-thread-network-via-home-assistant)
   - [by using Apple Thread border router](#adding-a-homekit-device-via-apple-thread-border-router)
 
@@ -64,7 +64,7 @@ The HomeKit Device integration automatically detects HomeKit [compatible devices
 
 - If you do not have the [`default_config`](/integrations/default_config/) integration, add [`zeroconf`](/integrations/zeroconf/) to your `configuration.yaml` file.
 - Find your HomeKit pairing code. The code is on the device itself, or on the packaging. If your device has a screen, it may be shown on screen.
-   - There is no way to recover this if you do not have it. In this case, you will need to contact the manufacturer to see what options you have.
+  - There is no way to recover this if you do not have it. In this case, you will need to contact the manufacturer to see what options you have.
 - Make sure your device is powered up.
 - Make sure the device is on your network, but not paired with another HomeKit controller. Depending on the device, you need to follow a different set of steps:
   - If your device is not already in your network: Join the device to your network:
@@ -114,7 +114,14 @@ You can add a HomeKit [compatible device](#supported-devices) to Home Assistant
    - Bluetooth devices may take significantly longer to pair than IP devices.
    - Add the device to a room and **Finish**.
 
-## Adding a HomeKit device to a Thread network via Home Assistant
+## Adding a HomeKit device through Thread
+
+This section shows the the ways you can join a HomeKit device to a Thread network:
+
+1. via Home Assistant
+2. via Apple Thread border router
+
+### Adding a HomeKit device to a Thread network via Home Assistant
 
 There are two methods to add a HomeKit [compatible device](#supported-devices) to a Thread network:
 
@@ -123,7 +130,7 @@ There are two methods to add a HomeKit [compatible device](#supported-devices) t
 
 This section describes how to add it via Home Assistant's preferred Thread network.
 
-### Prerequisites
+#### Prerequisites
 
 - A HomeKit device which supports Thread. This is indicated by the Thread label on the packaging.
 - Make sure the HomeKit device has been [joined using Bluetooth](#adding-a-homekit-device-through-bluetooth).
@@ -134,7 +141,7 @@ This section describes how to add it via Home Assistant's preferred Thread netwo
     - Documentation on [enabling multiprotocol on Yellow](https://yellow.home-assistant.io/guides/enable-multiprotocol/)
     - Documentation on [enabling multiprotocol on SkyConnect](https://skyconnect.home-assistant.io/procedures/enable-multiprotocol/)
 
-### To add a HomeKit device to a Thread network via Home Assistant
+#### To add a HomeKit device to a Thread network via Home Assistant
 
 1. To open the device configuration page, on the **HomeKit** integration, select the **device**.
 2. Under **Diagnostic**, you can see the **Thread Status** as **Disabled**.
@@ -145,7 +152,7 @@ This section describes how to add it via Home Assistant's preferred Thread netwo
        ![Thread status](/images/integrations/homekit_controller/homekit_controller_add_02.png)
    - That's it. Your HomeKit device now communicates via Thread.
 
-## Adding a HomeKit device via Apple Thread border router
+### Adding a HomeKit device via Apple Thread border router
 
 There are two methods to add a HomeKit [compatible device](#supported-devices) to a Thread network:
 
@@ -154,14 +161,14 @@ There are two methods to add a HomeKit [compatible device](#supported-devices) t
 
 This section describes how to add a HomeKit [compatible device](#supported-devices) using an Apple Thread border router device such as a HomePod mini.
 
-### Prerequisites
+#### Prerequisites
 
 - An Apple device that can act as a Thread border router, such as a HomePod mini.
 - A HomeKit device which supports Thread. This is indicated by the Thread label on the packaging.
 - Make sure your Home Assistant instance is on the same network (LAN) as the border router.
 - Make sure the HomeKit device has been paired in the Apple Home app (using the iOS Home app).
 
-### To add a HomeKit device via Apple Thread border router
+#### To add a HomeKit device via Apple Thread border router
 
 1. Remove the HomeKit device from the Apple Home app. Don't reset the device.
    - This leaves the Thread network details on the HomeKit device.

source/_integrations/matter.markdown

@@ -34,7 +34,7 @@ The Matter integration allows you to control Matter devices on your local Wi-Fi
 The integration is marked BETA: Both the Matter standard itself and its implementation within Home Assistant are in a early stage. You may run into compatibility issues and/or other bugs.
 </div>
 
-# Introduction- What is Matter?
+# Introduction - What is Matter?
 
 Matter is a new smart home connectivity standard for home automation products and IoT (Internet of Things) devices, see its [Wikipedia article](https://en.wikipedia.org/wiki/Matter_(standard)).
 
@@ -62,7 +62,7 @@ Matter goes hand-in-hand with (but is not the same as) [Thread](<https://en.wiki
 Thread devices become directly addressable by Matter controllers (such as Home Assistant) thanks to the use of so-called Thread Border Routers, which are in fact just devices that are both within your network and have a Thread chip builtin and thus act as a "router" between the Thread radio signal and your local network. These border routers (you will probably end up having multiple of them in your house) make sure that your Thread-based devices are reachable on your regular network and thus can be controlled with Matter. Examples of Thread Borders routers are the Apple TV 4K, HomePod (gen 2 or Mini), and the Google Nest Hub V2, so devices that you may already own. Besides that, all kind of other border routers are available, built-in to hardware appliances or software solutions based on OpenThread Border Router, such as the add-on we provide to use with the built-in Zigbee/Thread chip of the [Home Assistant Yellow](/yellow/) or the [Home Assistant SkyConnect](/skyconnect/) dongle.
 
 To use any Thread-based devices on a Matter controller, you need to have at least one Thread Border router device within range of the device.
-More info about Thread and diagnosing Thread networks and Border routers, see the [Thread](/integrations/thread/) integration.
+More info about Thread and diagnosing Thread networks and Border routers, refer to the [Thread](/integrations/thread/) integration page.
 
 <div class='note'>
 Many devices that (will) hit the market will use Thread for radio communication and Matter as a control protocol, but this is not guaranteed. For example, Thread-based devices are available that only support Apple HomeKit or some vendor-specific communication protocol. There are also a few cases where you need to apply for a (beta) firmware update on the device to enable Matter as a communication protocol. Therefore, do not assume Matter support when you see a Thread logo when looking for devices. Please be sure to look for the *Matter* logo itself (on either Wi-Fi/Ethernet-based devices or Thread) or any other confirmation by the manufacturer that the device supports Matter.

source/_integrations/thread.markdown

@@ -14,30 +14,165 @@ ha_platforms:
 ha_zeroconf: true
 ---
 
-The Thread integration helps you track the different Thread networks in your home and helps you manage their credentials. It is currently a work in progress.
+The Thread integration helps you track the different Thread networks in your home and store the Thread network credentials (similar to a Wi-Fi password). The Thread integration in Home Assistant is currently still a work in progress.
 
-Thread-based consumer devices use one of the two Home Automation standards: Matter or HomeKit. To add a thread-based device to Home Assistant, use the respective Home Assistant integration:
+You do not need to install this integration. The Thread integration shows up automatically when Home Assistant detects a [border router](#thread-border-router-devices).
 
-| Logo                                                                        | Home Assistant integration        |
-| :-------------------------------------------------------------------------: | :--------------------------------:|
-| <img src="https://brands.home-assistant.io/_/matter/icon.png"  width="50">  | [Matter](/integrations/Matter/)   |
-| <img src="https://brands.home-assistant.io/_/homekit/icon.png"  width="50"> | [HomeKit](/integrations/homekit_controller/) |
+## Logos on Thread-based smart home devices
 
+If you have a Thread-based consumer device, you will typically see a Thread logo on the packaging.
 
-## Thread &#8212; A communication protocol
+<p class='img'><img width="200" src='/images/integrations/thread/thread-requires-border-router.png'></p>
 
-Thread is a low-power mesh networking standard that allows users to connect their devices within a home network. Thread allows devices to communicate with each other without the need for a central controller. This makes it ideal for home automation, where a large number of devices may need to be connected. Thread uses the same RF technology as Zigbee but provides IP connectivity similar to Wi-Fi. Unlike Zigbee, Thread does not allow to control devices directly: It is just a communication protocol. A higher-level protocol, such as Matter or HomeKit, is required to control Thread-enabled devices. To see which home automation standard is supported by your device, check the icon on the packaging.
+The "Built on Thread: requires border router" logo means Thread is the only supported network protocol for this device. You cannot use Wi-Fi to communicate with this device.
 
-## TBRs connect Thread network to Home Assistant
+In addition, you will see a Matter or Apple HomeKit logo on the packaging.
 
-To connect a Thread network to Home Assistant, Thread border routers (TBRs) are used. TBRs are devices that bridge the Thread network to a local Wi-Fi or Ethernet network. To add a TBR to Home Assistant, you can use our [Home Assistant Yellow](/yellow/) hub or the [Home Assistant SkyConnect](/skyconnect/) Zigbee/Thread stick.
+Matter and Apple HomeKit are smart home protocols. They are responsible for handling the Thread credentials and connecting your Thread device to the Thread network. A smart home protocol is needed to control your device. Both home automation standards are supported natively by Home Assistant.
 
-Home Assistant communicates with TBRs over the local network. This means that TBRs do not have to be physically attached to Home Assistant to be used. You might already have a TBR as part of other products in your home, like a Google Nest Hub Gen 2 or Apple HomePod Mini. 
+## Adding a Thread-based device to Home Assistant
 
-### Vendor specific Thread networks
+How a Thread-based device is added to Home Assistant depends on the home automation standard it uses.
 
-Each vendor forms their own network when you start using their products, so you can end up having a Home Assistant, an Apple, and a Google Thread network in your home. These are all separate networks using different credentials, which prevents devices from roaming between TBRs.
+1. If you see the Matter logo on your device packaging, follow the procedure [adding a Matter device to Home Assistant](/integrations/matter/#adding-a-matter-device-to-home-assistant).
 
-It is possible to align credentials for TBRs from different vendors and have them form a single network together. This allows you to freely move devices between rooms without losing connectivity. To do this, you need to make sure that all TBRs use the same credentials. Currently, this works differently for each TBR vendor.
+   <img src="/images/integrations/thread/matter_onpackbadge_logo.png"  width="200">
 
-Home Assistant will sync the Thread credentials with Google when starting to {% term commission %} a Matter device via the Home Assistant Companion app. For other vendors, if the vendor allows you to see the operational dataset in TLV format, you can import it to Home Assistant from the Thread panel.
+2. If you see the Apple HomeKit logo on your device packaging, follow the procedure [adding a HomeKit device to Home Assistant](/integrations/homekit_controller/#adding-a-homekit-device-through-thread).
+
+   <img src="/images/integrations/thread/apple-works-with-homekit-logo.png"  width="200">
+
+## About Thread
+
+This section introduces the terms *Thread* and *border router* and lists border routers that are supported by Home Assistant.
+
+### A communication protocol for IoT devices
+
+Thread is a low-power mesh networking standard for IoT devices. The low-power aspect is important for battery-powered smart home devices. However, it's also low-bandwidth, making it ideal for applications that don't send a lot of data, like switches or motion sensors.
+
+Thread uses the same <abbr title="radio frequency">RF</abbr> technology as Zigbee (IEEE 802.15.4) but provides IP connectivity similar to Wi-Fi. Unlike Zigbee, Thread by itself does not allow controlling devices: It is just a communication protocol. To control the Thread devices, a higher-level protocol is required: Matter or Apple HomeKit. Thread devices use the IPv6 standard to communicate both inside and outside the mesh network.
+
+### About Thread border routers
+
+The devices use Thread border routers to communicate outside the mesh with any IPv6-capable device. A Thread border router is connected to your network either via Wi-Fi or Ethernet and uses its <abbr title="radio frequency">RF</abbr> radio to communicate with the Thread mesh network. The <abbr title="Thread border router">TBR</abbr> routes packets between your local network and the Thread mesh. It does not look at the content of these packets, it just forwards them.
+
+Often, Thread border routing is only an auxiliary functionality of a smart home device. For example, the Nest Hub (2nd gen) is a smart display, a Google Home controller, and a Chromecast target, but also has a Thread border router included.
+
+Unlike other protocols, Thread can use multiple border routers in a single network. This increases wireless coverage and reduces the risk of a single point of failure. Ideal for home automation, with a potentially large number of devices spread over a large area.
+
+OpenThread is an open source implementation of Thread, originally released by Google. Almost all commercially available Thread border routers are based on the open source implementation. However, the configuration of <abbr title="Thread border routers">TBRs</abbr> is not part of the Thread standard. This means that Google and Apple <abbr title="Thread border routers">TBRs</abbr> implementation setup and configured by their respective ecosystems.
+
+Home Assistant can only control OpenThread border routers built with the REST API available in the open source implementation. The OpenThread Border Router add-on (as well as the OpenThread Border Router bundled in the experimental Silicon Labs Multiprotocol add-on) are built from this open source OpenThread code and have the REST API enabled.
+
+### List of Thread border router devices
+
+Currently, the following <abbr title="Thread border router">TBR</abbr> devices are known to work with Home Assistant.
+These border routers may require an iPhone or Android phone for onboarding. What the exact requirements are, depends on the home automation protocol (Matter or Apple HomeKit) that your devices are using. Before buying a border router, check the prerequisites in the corresponding procedures:
+
+- [Adding a Matter device to Home Assistant](/integrations/matter/#adding-a-matter-device-to-home-assistant)
+- [Adding an Apple HomeKit device through Thread](/integrations/homekit_controller/#adding-a-homekit-device-through-thread)
+
+#### Home Assistant
+
+The Thread support on these devices is in experimental state. Out of the box, they runs Zigbee, not Thread.
+
+- [Home Assistant Yellow](/yellow/). Follow this procedure to [enable Thread](https://yellow.home-assistant.io/procedures/enable-thread/).
+- [Home Assistant SkyConnect](/skyconnect/) USB stick. Follow this procedure to [enable Thread](https://skyconnect.home-assistant.io/procedures/enable-thread/).
+
+#### Google
+
+- **Displays**: Nest Hub (2nd gen), Nest Hub Max
+- **Wi-Fi routers**: Nest Wifi Pro (Wi-Fi 6E), Nest Wifi
+
+#### Apple
+
+- **Speakers**: HomePod (2nd generation), HomePod mini
+- **TVs**: Apple TV 4K (3rd generation) Wi-Fi + Ethernet, Apple TV 4K (2nd generation)
+
+#### Others
+
+There are also other companies that provide devices with border router capability, such as Nanoleaf or Amazon.
+
+## Understanding the Thread configuration page
+
+This section explains why you might see multiple networks on the Thread configuration page and what this means for your network.
+
+### About different Thread networks
+
+Today, each vendor forms their own Thread network when you start using their products. This means you can end up having a Home Assistant, an Apple, and a Google Thread network in your home. The Thread configuration panel lists all Thread border routers and groups them by the Thread network.
+
+<p class='img'><img width="400" src='/images/integrations/thread/thread-no-3rd-party-credentials.png'>
+The Thread configuration page shows three vendor-specific Thread networks.
+</p>
+
+These are all separate networks using different credentials. This means devices can't roam between the Thread networks.
+
+The <img width="30px" src='/images/integrations/thread/information-outline.png'> icon indicates that Home Assistant has the credentials for that network. In this case, only the credentials of the `home assistant` network are known.
+
+Home Assistant discovers all Thread border routers in your network because they send mDNS/DNS-SD announcements. These local announcements don't contain the network credentials. That's why you see the network there, but not the credentials.
+
+#### About the preferred network
+
+The intention of the **Preferred network** in Home Assistant is that it will be used as the default network when adding Thread⁻based devices.
+
+<div class="note">
+
+The **preferred network** function isn't completely implemented yet. In particular, when adding Matter devices through the companion apps, the preferred network of the mobile device is being used.
+
+</div>
+
+#### Making a network your preferred network
+
+You can only set a Thread network as preferred if the credentials are known.
+
+1. To import Thread credentials, you need your Android and iOS companion app.
+2. On your companion app, navigate to the Thread configuration page.
+   - You should see an **Import credentials** button on the lower right corner.
+
+   <img width="400" src='/images/integrations/thread/thread-import-credentials.png'>
+
+   - Importing the credentials allows a Google- or Apple-created Thread network to be the preferred network of Home Assistant.
+   <img width="400" src='/images/integrations/thread/thread-preferred-network.png'>
+
+#### Using Home Assistant as a <abbr title="Thread border routers">TBRs</abbr> without setting up another vendor's TBR first
+
+This scenario currently only works in one particular case, under the following conditions:
+
+- Make sure there are no other Thread networks set up:
+  - For example: Make sure you do not have any Google <abbr title="Thread border routers">TBRs</abbr> set up yet (otherwise the Google <abbr title="Thread border routers">TBRs</abbr> will be the preferred Thread network, and Android APIs do not allow to change that currently).
+- You have the OpenThread Border Router add-on installed. If you have the experimental Silicon Labs Multiprotocol add-on installed, we recommend migrating to the pure Thread firmware, as especially Thread traffic appears to cause stability issues. For instructions on how to enable/migrate to a dedicated Thread setup on SkyConnect or Yellow, refer to the following guides:
+  - [Enabling Thread on SkyConnect](https://skyconnect.home-assistant.io/procedures/enable-thread/)
+  - [Enabling Thread on Yellow](https://yellow.home-assistant.io/procedures/enable-thread/)
+- You have an Android phone and the Home Assistant Companion App. (Note: this does not work with the iOS Companion App).
+- The devices you want to add to the network support Matter. For instructions on how to add Thread-based Matter devices, refer to the section [Adding a Matter device to Home Assistant](/integrations/matter/#adding-a-matter-device-to-home-assistant)
+
+Which TBR are supported mostly depends on (access to) the Thread credentials. And Thread credentials are required during on-boarding/commissioning, which is part of the smart home protocol.
+
+### Combining Thread networks
+
+In the current implementation, having multiple <abbr title="Thread border routers">TBRs</abbr> from different vendors results in separate networks using different credentials. This prevents devices from roaming between the Thread networks. In theory, it would be better to join all Thread networks into a single network to increase the size of the mesh network. A dense mesh network should lead to better <abbr title="radio frequency">RF</abbr> coverage and better link quality, which lowers transmission latencies, making communication faster.
+
+<div class="warning">
+
+Currently, combining Thread networks seems to lead to instabilities. Therefore, we do not recommend combining networks in production just yet. This is especially true for our OpenThread Border Router in combination with Google or Apple Thread networks.
+
+</div>
+
+## Related topics
+
+### Related hardware
+
+- [Home Assistant Yellow](/yellow/) hub
+- [Home Assistant SkyConnect](/skyconnect/) Zigbee/Thread USB stick
+
+### Related integrations for smart home standards
+
+- [Matter](/integrations/matter/)
+- [HomeKit](/integrations/homekit_controller/)
+
+### Related guides
+
+- [Adding a Matter device to Home Assistant](/integrations/matter/#adding-a-matter-device-to-home-assistant)
+- [Adding an Apple HomeKit device through Thread](/integrations/homekit_controller/#adding-a-homekit-device-through-thread)
+- [Enabling Thread on SkyConnect](https://skyconnect.home-assistant.io/procedures/enable-thread/)
+- [Enabling Thread on Yellow](https://yellow.home-assistant.io/procedures/enable-thread/)