Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update zha.markdown with tips on improving Zigbee network range #15789

Closed
wants to merge 17 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
13 changes: 13 additions & 0 deletions source/_integrations/zha.markdown
Expand Up @@ -242,6 +242,19 @@ Such a custom "ZHA Device Handler" are Python scripts that internally is also re

The custom quirks implementations for zigpy implemented as ZHA Device Handlers for Home Assistant are a similar concept to that of [Hub-connected Device Handlers for the SmartThings Classics platform](https://docs.smartthings.com/en/latest/device-type-developers-guide/) as well as that of [Zigbee-Herdsman Converters (formerly Zigbee-Shepherd Converters) as used by Zigbee2mqtt](https://www.zigbee2mqtt.io/how_tos/how_to_support_new_devices.html), meaning they are each virtual representations of a physical device that expose additional functionality that is not provided out-of-the-box by the existing integration between these platforms.

### Improving Zigbee network range

Low signal quality can lead to transmission errors and related issues. This section has a list of fundamental tips on how to improve signal quality. Improving signal quality also maximizes range and resolves most problems related to transmission errors. Please try to follow at least some of these recommendations before posting on the community forums or reporting issues to developers and submitting debug logs.



1. Add more Zigbee routers between devices far away and the next closest router. Distribute more Zigbee routers in areas with poor reception. Zigbee network topology uses a "mesh network" design which means that each device that acts as a Zigbee router will extend the range of your Zigbee network as a whole. While there are exceptions, almost all permanently powered devices serve as a Zigbee router. Adding more permanently powered Zigbee devices allows getting better coverage. There are also dedicated Zigbee routers which you can [find by doing a community search for "Zigbee signal repeater" or "Zigbee range extender"](https://community.home-assistant.io/t/advice-on-zigbee-range-extending/175882/)). Devices that can not act as routers are typically battery-operated and known as "end devices". Some end devices have issues connecting through routers (e.g. Xiaomi/Aqara devices).
2. Use a USB extension cable. This allows positioning the Zigbee coordinator adapter for better signal quality. Position the Zigbee coordinator away from Wi-Fi access-points/routers or other sources of 2.4GHz signals to avoid signal interference. The best location depends on your building's floorplan. Ideally, you want to place the Zigbee coordinator somewhere in the middle. Building materials do influence signal quality too, for example, dense/thick concrete, bricks, masonry, etc. dampen all wireless signals. Place the Zigbee coordinator with some distance from walls, ceilings and floors. Also, try different orientations of your Zigbee antenna (or your whole Zigbee coordinator adapter if it has an internal antenna). Some Antennas have a stronger signal in a certain direction. Simply changing orientation can improve signal quality already. Note: A bad USB extension cable may lead to connection issues between the system and the Zigbee coordinator adapter, symptoms of this are disconnection messages.
3. Zigbee and Wi-Fi can operate on various channels in the 2.4GHz spectrum. A busy Wi-Fi access-points/routers that are operating in the same frequency range (overlapping channels) as your Zigbee coordinator will drown out the Zigbee traffic, especially if they are located close to each other. To avoid interference between Zigbee and Wi-Fi try to choose channels without overlap. Check the channel your Wi-Fi access-points/routers are using (either by checking on the router's web interface or using a Wi-Fi analyzer app). The Zigbee channel is currently not shown in the Home Assistant front-end but you can find the channel in the logs (watch out for Network parameters log entry with the channel number, e.g., `radioChannel=15`). Changing the channel of the Zigbee network needs recreating it and re-join/re-pair all of your Zigbee devices. Typically it's a lot easier to change the channel used by your Wi-Fi. See [this article for Wi-Fi and Zigbee channels coexistance](https://www.metageek.com/training/resources/zigbee-wifi-coexistence.html) to avoid using overlapping frequency ranges.
4. Update the firmware on your Zigbee coordinator adapter and your Zigbee devices. Note that depending on your hardware the latest Zigbee coordinator firmware might not always be the one recommended by the community so it is advised to ask before upgrading.
5. If your Zigbee coordinator adapter has a removable antenna (e.g., with an SMA-connector) then you have the option of using a high-gain antenna. Note that antennas with higher gain have directionality: You might have better reception on the same floor, but reception across floors might suffer. In addition, you also have the option to use an antenna extension-cable if needed (usually using just a USB extension cable for your Zigbee coordinator adapter is the better alternative). This should really only be needed if you are trying to cover a long distance, like to another building or very dense/thick walls, ceilings and floors.
6. Buy more powerful Zigbee radio hardware with better radio range, preferably with an external antenna. If you are not only experimenting but want a permanently stable and healthy Zigbee network with potentially many devices then you should consider upgrading to a more powerful Zigbee coordinator USB adapter. Generally, those with an external antenna will have better range, therefore you will also want to avoid buying an internal adapter unless it has an external antenna.

### Reporting issues

When reporting issues, please provide the following information in addition to information requested by issue template:
Expand Down