diff --git a/source/_integrations/homekit_controller.markdown b/source/_integrations/homekit_controller.markdown index 911968d75b5..96f983d3acc 100644 --- a/source/_integrations/homekit_controller.markdown +++ b/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. diff --git a/source/_integrations/matter.markdown b/source/_integrations/matter.markdown index d7f59a2a16d..824b8872859 100644 --- a/source/_integrations/matter.markdown +++ b/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. -# 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]( 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. diff --git a/source/_integrations/thread.markdown b/source/_integrations/thread.markdown index bf44f7c7c56..f1656bd2d32 100644 --- a/source/_integrations/thread.markdown +++ b/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 | -| :-------------------------------------------------------------------------: | :--------------------------------:| -| | [Matter](/integrations/Matter/) | -| | [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 — A communication protocol +

-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. + -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). + + + +## 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 RF 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 RF radio to communicate with the Thread mesh network. The TBR 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 TBRs is not part of the Thread standard. This means that Google and Apple TBRs 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 TBR 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. + +

+The Thread configuration page shows three vendor-specific Thread networks. +

+ +These are all separate networks using different credentials. This means devices can't roam between the Thread networks. + +The 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. + +
+ +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. + +
+ +#### 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. + + + + - Importing the credentials allows a Google- or Apple-created Thread network to be the preferred network of Home Assistant. + + +#### Using Home Assistant as a TBRs 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 TBRs set up yet (otherwise the Google TBRs 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 TBRs 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 RF coverage and better link quality, which lowers transmission latencies, making communication faster. + +
+ +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. + +
+ +## 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/) \ No newline at end of file diff --git a/source/images/integrations/thread/apple-works-with-homekit-logo.png b/source/images/integrations/thread/apple-works-with-homekit-logo.png new file mode 100644 index 00000000000..90dc90eda21 Binary files /dev/null and b/source/images/integrations/thread/apple-works-with-homekit-logo.png differ diff --git a/source/images/integrations/thread/information-outline.png b/source/images/integrations/thread/information-outline.png new file mode 100644 index 00000000000..79ba32c966c Binary files /dev/null and b/source/images/integrations/thread/information-outline.png differ diff --git a/source/images/integrations/thread/matter_onpackbadge_logo.png b/source/images/integrations/thread/matter_onpackbadge_logo.png new file mode 100644 index 00000000000..da1a2db632d Binary files /dev/null and b/source/images/integrations/thread/matter_onpackbadge_logo.png differ diff --git a/source/images/integrations/thread/thread-import-credentials.png b/source/images/integrations/thread/thread-import-credentials.png new file mode 100644 index 00000000000..5e88aef4c40 Binary files /dev/null and b/source/images/integrations/thread/thread-import-credentials.png differ diff --git a/source/images/integrations/thread/thread-no-3rd-party-credentials.png b/source/images/integrations/thread/thread-no-3rd-party-credentials.png new file mode 100644 index 00000000000..220c8ff7dbc Binary files /dev/null and b/source/images/integrations/thread/thread-no-3rd-party-credentials.png differ diff --git a/source/images/integrations/thread/thread-preferred-network.png b/source/images/integrations/thread/thread-preferred-network.png new file mode 100644 index 00000000000..ac3898a4327 Binary files /dev/null and b/source/images/integrations/thread/thread-preferred-network.png differ diff --git a/source/images/integrations/thread/thread-requires-border-router.png b/source/images/integrations/thread/thread-requires-border-router.png new file mode 100644 index 00000000000..f48c14b8476 Binary files /dev/null and b/source/images/integrations/thread/thread-requires-border-router.png differ