mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 17:27:19 +00:00
Rearrange "adding devices" and "configuration" sections
This commit is contained in:
kylehakala
parent
c9aec73ad6
commit
290015798e
@ -236,6 +236,121 @@ If you are use ZiGate or Sonoff ZBBridge you have to use some special usb_path c
|
||||
- Wifi Zigate : `socket://[IP]:[PORT]` for example `socket://192.168.1.10:9999`
|
||||
- Sonoff ZBBridge : `socket://[IP]:[PORT]` for example `socket://192.168.1.11:8888`
|
||||
|
||||
### Global Options
|
||||
|
||||
There are a few global options available once ZHA has been configured. Press **Configure** to access these settings.
|
||||
|
||||
The options are as follows:
|
||||
|
||||
{% configuration_basic %}
|
||||
Enable enhanced light color/temperature transition from an off-state:
|
||||
description: "For older non Zigbee 3.0 lights, this still allows a proper transition from an off-state to a new color (without seeing the old color). _(default: off)_"
|
||||
Enable enhanced brightness slider during light transition:
|
||||
description: "This avoids seeing intermediary brightness state when turning on lights with a transition. _(default: on)_"
|
||||
Group members assume state of group:
|
||||
description: "When using ZHA groups, turning on a ZHA group light makes the ZHA group members optimistically change their state to \"on\", instead of waiting and polling the lights when off. _(default: on)_"
|
||||
{% endconfiguration_basic %}
|
||||
|
||||
### Configuration - YAML
|
||||
|
||||
For more advanced configuration, you can modify {% term "`configuration.yaml`" %} and restart Home Assistant
|
||||
|
||||
{% configuration %}
|
||||
database_path:
|
||||
description: _Full_ path to the database which will keep persistent network data.
|
||||
required: false
|
||||
type: string
|
||||
enable_quirks:
|
||||
description: Enable quirks mode for devices where manufacturers didn't follow specs.
|
||||
required: false
|
||||
type: boolean
|
||||
default: true
|
||||
custom_quirks_path:
|
||||
description: Full path to a directory containing custom quirk modules that will take precedence over any built-in quirks matching a device.
|
||||
required: false
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
#### Advanced OTA configuration
|
||||
|
||||
OTA for a few manufacturers is enabled by default, currently Ledvance, Sonoff, Inovelli, and ThirdReality. Other manufacturers are supported but disabled by default because their updates may change or remove device functionality, may require you to reconfigure devices, or are contributed by the community and may be minimally tested.
|
||||
|
||||
Refer to the [zigpy documentation for OTA configuration](https://github.com/zigpy/zigpy/wiki/OTA-Configuration) for more information on additional OTA providers.
|
||||
|
||||
#### Defining Zigbee channel to use
|
||||
|
||||
Tip! Before considering to change to an other Zigbee channel on an existing Zigbee network, it is highly recommended that you read through the two segments under the [troubleshooting](#troubleshooting) section below about _Best practices to avoid pairing/connection difficulties_ and _Zigbee interference avoidance and network range/coverage optimization_. These sections provide prerequisite information and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
|
||||
ZHA prefers to use Zigbee channel 15 by default. You can change this using YAML configuration, but this only works
|
||||
if there's no existing network. To change the channel for an existing network, radio has to be factory reset and a new network to be formed. This requires re-pairing of all the devices.
|
||||
|
||||
```yaml
|
||||
zha:
|
||||
zigpy_config:
|
||||
network:
|
||||
channel: 15 # What channel the radio should try to use.
|
||||
channels: [15, 20, 25] # Channel mask
|
||||
```
|
||||
|
||||
{% note %}
|
||||
The best practice is to not change the Zigbee channel from the ZHA default.
|
||||
{% endnote %}
|
||||
|
||||
The related troubleshooting segments mentioned above will, among other things, inform that if you have issues with overlapping frequencies between Wi-Fi and Zigbee, then it is usually better to first only try changing and setting a static Wi-Fi channel on your Wi-Fi router or all your Wi-Fi access points (instead of just changing to another Zigbee channel).
|
||||
|
||||
MetaGeek Support has a good reference article about channel selection for [Zigbee and WiFi coexistence](https://support.metageek.com/hc/en-us/articles/203845040-ZigBee-and-WiFi-Coexistence).
|
||||
|
||||
The Zigbee specification standards divide the 2.4 GHz ISM radio band into 16 Zigbee channels (i.e. distinct radio frequencies for Zigbee). For all Zigbee devices to be able to communicate, they must support the same Zigbee channel (i.e. Zigbee radio frequency) that is set on the Zigbee Coordinator as the channel to use for its Zigbee network. Not all Zigbee devices support all Zigbee channels. Channel support usually depends on the age of the hardware and firmware, as well as on the device's power ratings.
|
||||
|
||||
The general recommendation is to only use channels 15, 20, or 25 in order to avoid interoperability problems with Zigbee devices. Not only because there is less chance of Wi-Fi networks interfering too much with the Zigbee network on other channels, but also because not all Zigbee devices support all channels. Some devices, for example, are limited to only being compatible with ZLL (Zigbee Light Link) channels. It is therefore especially not recommended to use Zigbee channels 11, 24, 25, or 26 on your Zigbee coordinator. These Zigbee channels are commonly only supported by relatively modern Zigbee hardware devices with newer Zigbee firmware. If using those channels, your coordinator may not be usable with older Zigbee devices.
|
||||
|
||||
#### Modifying the device type
|
||||
|
||||
As not all device manufacturers follow the Zigbee standard, at times a device can be incorrectly classified. For example, a switch could be classified as a light.
|
||||
|
||||
To correct the device type, also called domain, add the following to your {% term "`configuration.yaml`" %} and restart Home Assistant:
|
||||
|
||||
```yaml
|
||||
zha:
|
||||
device_config:
|
||||
84:71:27:ff:fe:93:17:24-1: # format: {ieee}-{endpoint_id}
|
||||
type: "switch" # corrected device type
|
||||
```
|
||||
|
||||
`{ieee}` is the device hardware address which can be read from the Home Assistant UI when looking at _Device info_. From device info, you can find the `{endpoint_id}` by viewing the _Zigbee device signature_.
|
||||
|
||||
## Adding devices
|
||||
|
||||
Tip! It is highly recommended that you read through the two segments under the troubleshooting section below about _Best practices to avoid pairing/connection difficulties_ and _Zigbee interference avoidance and network range/coverage optimization_ for general prerequisite knowledge and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
|
||||
**To add a new Zigbee device:**
|
||||
|
||||
1. Go to {% my integrations title="**Settings** > **Devices & services**" %}.
|
||||
2. Select the **Zigbee Home Automation** {% term integration %}. Then, select **Configure**.
|
||||
3. To start a scan for new devices, on the bottom right corner of the screen, select **Add device**.
|
||||
4. Reset your Zigbee devices to factory default settings according to the device instructions provided by the manufacturer (e.g., turn on/off lights up to 10 times; switches usually have a reset button/pin). It might take a few seconds for the devices to appear. You can click on **Show logs** for more verbose output.
|
||||
5. Once the device is found, it will appear on that page and will be automatically added to your devices. You can optionally change its name and add it to an area (you can change this later). You can search again to add another device, or you can go back to the list of added devices.
|
||||
|
||||
### Using router devices to add more devices
|
||||
|
||||
Most mains-powered devices, e.g., many always-powered wall plugs or light bulbs in your Zigbee network will automatically act as a Zigbee router device (sometimes also referred to as a Zigbee "signal repeater" or "range extender").
|
||||
|
||||
Because Zigbee should use a [wireless mesh network](https://en.wikipedia.org/wiki/Wireless_mesh_network) to be effective, you will need to add Zigbee router devices to increase the number of Zigbee devices that can be used in your Zigbee network, both in the total number of devices that can be added as well as the total range and coverage of the network. Some Zigbee router devices do a much better job at routing and repeating Zigbee signals and messages than some other devices. You should not have a setup where Zigbee router devices (e.g. light bulbs) are often powered-off. Zigbee router devices are meant to be always available.
|
||||
|
||||
All Zigbee coordinator firmware will only allow you to directly connect a certain amount of devices. That limit is set for two reasons; firstly, to not overload the Zigbee coordinator, and secondly, to encourage your Zigbee network to quickly begin to utilize a "[mesh networking](https://en.wikipedia.org/wiki/Mesh_networking)" topology instead of only a "[star network](https://en.wikipedia.org/wiki/Star_network)" topology.
|
||||
|
||||
The total number of Zigbee devices that you can have on a Zigbee network depends on a few things. The Zigbee coordinator hardware and its firmware only play a larger role in Zigbee networks with a lot of devices. More important is the number of directly connected devices ("direct children") versus the number of routers that are connected to your Zigbee coordinator. The Zigpy library, which the ZHA {% term integration %} depends on, has an upper limit that is 32 direct children, but you can still have hundreds of Zigbee devices in total connected indirectly through routes via Zigbee router devices.
|
||||
|
||||
In this theoretical example, a CC2652-based Zigbee coordinator has three CC2530 Zigbee router devices for a total limit of 77 devices:
|
||||
|
||||
- Coordinator: 32 Zigbee End devices - 3 routers = 29
|
||||
- Router one: + 16 devices
|
||||
- Router two: + 16 devices
|
||||
- Router three: + 16 devices
|
||||
- Total device limit = **77 devices**
|
||||
|
||||
In practice, you will likely need to add a lot more Zigbee router devices than in this example in order to extend the coverage of the network to reach that many devices.
|
||||
|
||||
### Discovery via USB or Zeroconf
|
||||
|
||||
Some devices can be auto-discovered, which can simplify the ZHA setup process. The following devices have been tested with discovery and offer a quick setup experience.
|
||||
@ -322,89 +437,6 @@ To see OTA updates for a device, it must support OTA updates and firmware images
|
||||
Before updating a device, you should search for any disadvantages or if you even need to install an available update. Some firmware updates can break features you might use (e.g. group binding for IKEA devices). Some updates might also require changes to ZHA. In rare cases, you can even brick devices by installing a firmware update.
|
||||
{% endwarning %}
|
||||
|
||||
### Global Options
|
||||
|
||||
There are a few global options available once ZHA has been configured. Press **Configure** to access these settings.
|
||||
|
||||
The options are as follows:
|
||||
|
||||
{% configuration_basic %}
|
||||
Enable enhanced light color/temperature transition from an off-state:
|
||||
description: "For older non Zigbee 3.0 lights, this still allows a proper transition from an off-state to a new color (without seeing the old color). _(default: off)_"
|
||||
Enable enhanced brightness slider during light transition:
|
||||
description: "This avoids seeing intermediary brightness state when turning on lights with a transition. _(default: on)_"
|
||||
Group members assume state of group:
|
||||
description: "When using ZHA groups, turning on a ZHA group light makes the ZHA group members optimistically change their state to \"on\", instead of waiting and polling the lights when off. _(default: on)_"
|
||||
{% endconfiguration_basic %}
|
||||
|
||||
### Configuration - YAML
|
||||
|
||||
For more advanced configuration, you can modify {% term "`configuration.yaml`" %} and restart Home Assistant
|
||||
|
||||
{% configuration %}
|
||||
database_path:
|
||||
description: _Full_ path to the database which will keep persistent network data.
|
||||
required: false
|
||||
type: string
|
||||
enable_quirks:
|
||||
description: Enable quirks mode for devices where manufacturers didn't follow specs.
|
||||
required: false
|
||||
type: boolean
|
||||
default: true
|
||||
custom_quirks_path:
|
||||
description: Full path to a directory containing custom quirk modules that will take precedence over any built-in quirks matching a device.
|
||||
required: false
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
#### Advanced OTA configuration
|
||||
|
||||
OTA for a few manufacturers is enabled by default, currently Ledvance, Sonoff, Inovelli, and ThirdReality. Other manufacturers are supported but disabled by default because their updates may change or remove device functionality, may require you to reconfigure devices, or are contributed by the community and may be minimally tested.
|
||||
|
||||
Refer to the [zigpy documentation for OTA configuration](https://github.com/zigpy/zigpy/wiki/OTA-Configuration) for more information on additional OTA providers.
|
||||
|
||||
#### Defining Zigbee channel to use
|
||||
|
||||
Tip! Before considering to change to an other Zigbee channel on an existing Zigbee network, it is highly recommended that you read through the two segments under the [troubleshooting](#troubleshooting) section below about _Best practices to avoid pairing/connection difficulties_ and _Zigbee interference avoidance and network range/coverage optimization_. These sections provide prerequisite information and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
|
||||
ZHA prefers to use Zigbee channel 15 by default. You can change this using YAML configuration, but this only works
|
||||
if there's no existing network. To change the channel for an existing network, radio has to be factory reset and a new network to be formed. This requires re-pairing of all the devices.
|
||||
|
||||
```yaml
|
||||
zha:
|
||||
zigpy_config:
|
||||
network:
|
||||
channel: 15 # What channel the radio should try to use.
|
||||
channels: [15, 20, 25] # Channel mask
|
||||
```
|
||||
|
||||
{% note %}
|
||||
The best practice is to not change the Zigbee channel from the ZHA default.
|
||||
{% endnote %}
|
||||
|
||||
The related troubleshooting segments mentioned above will, among other things, inform that if you have issues with overlapping frequencies between Wi-Fi and Zigbee, then it is usually better to first only try changing and setting a static Wi-Fi channel on your Wi-Fi router or all your Wi-Fi access points (instead of just changing to another Zigbee channel).
|
||||
|
||||
MetaGeek Support has a good reference article about channel selection for [Zigbee and WiFi coexistence](https://support.metageek.com/hc/en-us/articles/203845040-ZigBee-and-WiFi-Coexistence).
|
||||
|
||||
The Zigbee specification standards divide the 2.4 GHz ISM radio band into 16 Zigbee channels (i.e. distinct radio frequencies for Zigbee). For all Zigbee devices to be able to communicate, they must support the same Zigbee channel (i.e. Zigbee radio frequency) that is set on the Zigbee Coordinator as the channel to use for its Zigbee network. Not all Zigbee devices support all Zigbee channels. Channel support usually depends on the age of the hardware and firmware, as well as on the device's power ratings.
|
||||
|
||||
The general recommendation is to only use channels 15, 20, or 25 in order to avoid interoperability problems with Zigbee devices. Not only because there is less chance of Wi-Fi networks interfering too much with the Zigbee network on other channels, but also because not all Zigbee devices support all channels. Some devices, for example, are limited to only being compatible with ZLL (Zigbee Light Link) channels. It is therefore especially not recommended to use Zigbee channels 11, 24, 25, or 26 on your Zigbee coordinator. These Zigbee channels are commonly only supported by relatively modern Zigbee hardware devices with newer Zigbee firmware. If using those channels, your coordinator may not be usable with older Zigbee devices.
|
||||
|
||||
#### Modifying the device type
|
||||
|
||||
As not all device manufacturers follow the Zigbee standard, at times a device can be incorrectly classified. For example, a switch could be classified as a light.
|
||||
|
||||
To correct the device type, also called domain, add the following to your {% term "`configuration.yaml`" %} and restart Home Assistant:
|
||||
|
||||
```yaml
|
||||
zha:
|
||||
device_config:
|
||||
84:71:27:ff:fe:93:17:24-1: # format: {ieee}-{endpoint_id}
|
||||
type: "switch" # corrected device type
|
||||
```
|
||||
|
||||
`{ieee}` is the device hardware address which can be read from the Home Assistant UI when looking at _Device info_. From device info, you can find the `{endpoint_id}` by viewing the _Zigbee device signature_.
|
||||
|
||||
## Actions
|
||||
|
||||
### Action `zha.permit`
|
||||
@ -476,38 +508,6 @@ This action disables a lock code on a Zigbee lock.
|
||||
| ----------- | -------- | ------------------------------- |
|
||||
| `code_slot` | no | Which lock code slot to disable |
|
||||
|
||||
## Adding devices
|
||||
|
||||
Tip! It is highly recommended that you read through the two segments under the troubleshooting section below about _Best practices to avoid pairing/connection difficulties_ and _Zigbee interference avoidance and network range/coverage optimization_ for general prerequisite knowledge and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
|
||||
**To add a new Zigbee device:**
|
||||
|
||||
1. Go to {% my integrations title="**Settings** > **Devices & services**" %}.
|
||||
2. Select the **Zigbee Home Automation** {% term integration %}. Then, select **Configure**.
|
||||
3. To start a scan for new devices, on the bottom right corner of the screen, select **Add device**.
|
||||
4. Reset your Zigbee devices to factory default settings according to the device instructions provided by the manufacturer (e.g., turn on/off lights up to 10 times; switches usually have a reset button/pin). It might take a few seconds for the devices to appear. You can click on **Show logs** for more verbose output.
|
||||
5. Once the device is found, it will appear on that page and will be automatically added to your devices. You can optionally change its name and add it to an area (you can change this later). You can search again to add another device, or you can go back to the list of added devices.
|
||||
|
||||
### Using router devices to add more devices
|
||||
|
||||
Most mains-powered devices, e.g., many always-powered wall plugs or light bulbs in your Zigbee network will automatically act as a Zigbee router device (sometimes also referred to as a Zigbee "signal repeater" or "range extender").
|
||||
|
||||
Because Zigbee should use a [wireless mesh network](https://en.wikipedia.org/wiki/Wireless_mesh_network) to be effective, you will need to add Zigbee router devices to increase the number of Zigbee devices that can be used in your Zigbee network, both in the total number of devices that can be added as well as the total range and coverage of the network. Some Zigbee router devices do a much better job at routing and repeating Zigbee signals and messages than some other devices. You should not have a setup where Zigbee router devices (e.g. light bulbs) are often powered-off. Zigbee router devices are meant to be always available.
|
||||
|
||||
All Zigbee coordinator firmware will only allow you to directly connect a certain amount of devices. That limit is set for two reasons; firstly, to not overload the Zigbee coordinator, and secondly, to encourage your Zigbee network to quickly begin to utilize a "[mesh networking](https://en.wikipedia.org/wiki/Mesh_networking)" topology instead of only a "[star network](https://en.wikipedia.org/wiki/Star_network)" topology.
|
||||
|
||||
The total number of Zigbee devices that you can have on a Zigbee network depends on a few things. The Zigbee coordinator hardware and its firmware only play a larger role in Zigbee networks with a lot of devices. More important is the number of directly connected devices ("direct children") versus the number of routers that are connected to your Zigbee coordinator. The Zigpy library, which the ZHA {% term integration %} depends on, has an upper limit that is 32 direct children, but you can still have hundreds of Zigbee devices in total connected indirectly through routes via Zigbee router devices.
|
||||
|
||||
In this theoretical example, a CC2652-based Zigbee coordinator has three CC2530 Zigbee router devices for a total limit of 77 devices:
|
||||
|
||||
- Coordinator: 32 Zigbee End devices - 3 routers = 29
|
||||
- Router one: + 16 devices
|
||||
- Router two: + 16 devices
|
||||
- Router three: + 16 devices
|
||||
- Total device limit = **77 devices**
|
||||
|
||||
In practice, you will likely need to add a lot more Zigbee router devices than in this example in order to extend the coverage of the network to reach that many devices.
|
||||
|
||||
## Zigbee groups and binding devices
|
||||
|
||||
ZHA supports the creation of Zigbee groups (different from Home Assistant's [Group](/integrations/group/) integration), as well as binding devices to each other. Groups and device binding can be set up independently of each other, but they can be also used in combination (such as binding a device to another group of devices).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user