Update ZHA documentation with tips on improving Zigbee network range #18864

Hedda · 2021-08-09T14:10:11Z

Proposed change

Update ZHA docs with best practice guidelines for improving Zigbee network range and coverage by following some general tips.

Suggest adding this to ZHA integration troubleshooting section as questions and issues or problems related to range or coverage as well as Zigbee network stability with lost connections due to common known sources of interference are very common today.

FYI, as the ZHA integration (and other Zigbee implementations) are getting popular, more end-user beginners and new users of Zigbee devices are posting in the Home Assistant community forums about issues/problems related to Zigbee range and stability.

https://community.home-assistant.io/c/configuration/zha/48

https://community.home-assistant.io/c/configuration/zigbee/39

Note! Please remember that while users of other Zigbee implementations (like ex. Zigbee2MQTT and deCONZ) can be referred to extensive documentation on their respective websites, the ZHA integration have no other website/pages with documentation.

These suggestions will therefore advise ZHA users on relatively simple actions they can and should take if they wish to greatly improve signal range and mesh network coverage or lessen possible signal interference due to electromagnetic interference (a.k.a. radio interference). All of these essential actions to set up a solid Zigbee network can easily and relatively quickly be solved by the users themselves. Also following the recommendations as a new user and Zigbee beginners should a lot of people much frustration as poor signal reception quality can cause intermittent connection issues which can be a pain to troubleshoot.

The recommendations are largely indirectly based on posts in different communities with recommendations from experienced Zigbee developers (like Koen Kanters a.k.a. "Koenkk" of Zigbee2MQTT fame and Omer Kilic a.k.a. "omerk" who designed the open-source zzh adapter) plus several longer Zigbee range discussions threads found all around in the Home Assistant / ZHA / Zigpy, Zigbee2MQTT, Hubitat, openHAB, and Domoticz community forums with users tips on how-to improve network range and stability and other support channels.

For example, the most important advice posted in the forums is for users to use a long USB-extension cable for their Zigbee Coordinator and to also buy more "Zigbee Router" devices (normally AC mains-powered Zigbee devices) to their home because they will route/repeat the Zigbee communication and as such extend the network range. Also, more common advice is upgrading firmware on both Zigbee Coordinator as well as Zigbee devices, or just buying a better Zigbee Coordinator adapter if users are using ones that are based on an obsolete chip and/or one for which the firmware is no longer maintained by the manufacturer.

Below are just a few direct references with questions and answers related to connectivity posted in Home Assistant community forums, where most of these topics could probably have been resolved quicker if those or similar troubleshooting tips in ZHA docs:

Well researched with indirectly inspirations from basic Zigbee troubleshooting tips in other communities and other references:

https://www.zigbee2mqtt.io/advanced/zigbee/02_improve_network_range_and_stability.html#usb-based-adapter
https://www.zigbee2mqtt.io/guide/faq/
https://docs.hubitat.com/index.php?title=How_to_Build_a_Solid_Zigbee_Mesh
https://community.hubitat.com/t/xiaomi-aqara-devices-pairing-keeping-them-connected/623
https://home-assistant-guide.com/2020/10/29/choose-your-zigbee-channel-wisely/
https://electrolama.com/radio-docs/troubleshooting/
https://gadget-freakz.com/how-to-improve-your-zigbee-network/
https://nts.com/services/education/articles/zigbee-best-practices/
https://zigbeealliance.org/news_and_articles/step-by-step-guide-getting-started-with-zigbee/
https://www.digikey.com/en/articles/tips-for-optimizing-performance-and-energy-use-of-zigbee-radios
https://www.control4.com/docs/product/zigbee/best-practices/english/revision/B/
https://www.metageek.com/training/resources/zigbee-wifi-coexistence/
https://community.smartthings.com/t/faq-networking-and-reducing-channel-interference-between-wifi-and-zigbee/40159/3
https://notenoughtech.com/featured/a-simple-trick-to-reduce-zigbee-coordinator-wifi-interference/
https://phoscon.de/en/support
https://www.usb.org/sites/default/files/327216.pdf (USB 3.0* Radio Frequency Interference Impact on 2.4 GHz Wireless Devices)
https://www.unit3compliance.co.uk/2-4ghz-intra-system-or-self-platform-interference-demonstration/

https://www.youtube.com/watch?v=1dcAXkJxzcY&ab_channel=digiblurDIY
https://www.youtube.com/watch?v=t-gw7kURXCk&t=2s&ab_channel=HomeAutomationGuy
https://www.youtube.com/watch?v=UmpDXc3cXbU&ab_channel=EverythingSmartHome

Type of change

Spelling, grammar or other readability improvements (current branch).
Adjusted missing or incorrect information in the current documentation (current branch).
Added documentation for a new integration I'm adding to Home Assistant (next branch).
- I've opened up a PR to add logo's and icons in Brands repository.
Added documentation for a new feature I'm adding to Home Assistant (next branch).
Removed stale or deprecated documentation.

Additional information

Link to parent pull request in the codebase: NA
Link to parent pull request in the Brands repository: NA
This PR fixes or closes issue: NA

Checklist

This PR uses the correct branch, based on one of the following:
- I made a change to the existing documentation and used the current branch.
- I made a change that is related to an upcoming version of Home Assistant and used the next branch.
The documentation follows the Home Assistant documentation standards.

Update zha.markdown with tips on improving Zigbee network range and coverage.

github-actions · 2021-10-08T15:00:56Z

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
Thank you for your contributions.

Hedda · 2021-12-01T16:08:11Z

Possible to get this reviewed? Again this answers some of the most asked Zigbee questions in Home Assistant's forum for ZHA.

frenck · 2022-02-18T23:22:49Z

While I do get this is being added, it is really really hard to read. Bot in markdown and in the actual result on the website.

Before this can be considered, it really needs to become more readable.

Hedda · 2022-02-20T08:25:19Z

Before this can be considered, it really needs to become more readable.

Are there maybe some volunteering technical writers/editors in the community who are willing to help with that here?

Help is wanted as I am not good at writing documentation shorter myself, (and I am also not a native English speaker).

I can write more and longer on the topic but find it really hard to write less that still convey all the same information.

Hedda · 2022-02-20T08:27:14Z

Rather than wait another six months, is it not better to add this 'as-is' now and then let someone rewrite parts of it in a new PR?

frenck · 2022-02-22T01:50:23Z

Rather than wait another six months, is it not better to add this 'as-is' now and then let someone rewrite parts of it in a new PR?

I dunno, you could also try to improve on it?

Corecii · 2022-02-24T12:32:05Z

This is hard to make concise because there's a lot of information here.

Here's my second attempt:

Second attempt (click to expand)

Poor signal quality and signal interference can cause significant degradation in Zigbee network performance. Here are some tips for optimizing signal quality and coverage. Following all of these tips will typically resolve most range and transmission issues.

Common causes of Zigbee connectivity problems:

2.4 GHz RF interference (from routers and other electronics)
Conflicting Zigbee and WiFi channels
USB 3 RF interference
Bad coordinator placement
Bad coordinator orientation
Too many obstacles between the coordinator or router and end devices
Too few routers / repeaters between the coordinator and end devices
Devices not paired in their final locations
End devices paired before routers are paired
Underpowered coordinator
Underpowered coordinator antenna
Bad / outdated / incompatible firmware on the coordinator
Hardware issue in the connection between the coordinator and the host computer
Issues in the host software

We suggest:

Test the network with devices in line-of-sight of the coordinator
Pair your end devices after pairing your router / repeater devices
Put your Zigbee network on the channel that interferes the least with your neighbors' WiFi
Put your WiFi network on the channel that interferes the least with your Zigbee network
Only use USB 2 ports to connect your coordinator
Use a long USB 2 extension cable to place and orient your coordinator properly, away from interference
Use the best firmware for your coordinator according to the community of that coordinator
Try a different host computer
Try a powerful coordinator with an external antenna
Try a coordinator that connects over Ethernet instead of USB
Try different Zigbee host software

Resources:

ZigBee and Wi-Fi Coexistence
[put a link to repeaters here]
[put some other link here]

Source

Poor signal quality and signal interference can cause significant degradation in Zigbee network performance. Here are some tips for optimizing signal quality and coverage. Following all of these tips will typically resolve most range and transmission issues.

Common factors of Zigbee connectivity:
* 2.4 GHz RF interference (from routers and other electronics)
* Conflicting Zigbee and WiFi channels
* USB 3 RF interference
* Bad coordinator placement
* Bad coordinator orientation
* Too many obstacles between the coordinator or router and end devices
* Too few routers / repeaters between the coordinator and end devices
* Devices not paired in their final locations
* End devices paired *before* routers are paired
* Underpowered coordinator
* Underpowered coordinator antenna
* Bad / outdated / incompatible firmware on the coordinator
* Hardware issue in the connection between the coordinator and the host computer
* Issues in the host software

For these reasons, we suggest:
* Test the network with devices in line-of-sight of the coordinator
* Pair your end devices *after* pairing your router / repeater devices
* Put your Zigbee network on the channel that interferes the least with your neighbors' WiFi
* Put your WiFi network on the channel that interferes the least with your Zigbee network
* Only use USB 2 ports to connect your coordinator
* Use a *long* USB 2 extension cable to place and orient your coordinator properly, away from interference
* Use the best firmware for your coordinator according to the community of that coordinator
* Try a different host computer
* Try a powerful coordinator with an external antenna
* Try a coordinator that connects over Ethernet instead of USB
* Try different Zigbee host software

Resources:
* [ZigBee and Wi-Fi Coexistence](https://www.metageek.com/training/resources/zigbee-wifi-coexistence.html)
* [put a link to repeaters here]
* [put some other link here]

Here's my first attempt, if it helps:

First attempt (click to expand)

Poor signal quality and signal interference can cause significant degradation in Zigbee network performance. Here are some tips for optimizing signal quality and coverage. Following all of these tips will typically resolve most range and transmission issues.

Test the network with a small number of devices to minimize external variables.
For an initial test your coordinator should have line-of-sight to connected Zigbee devices. Once that works consistently, re-pair your devices in more realistic test locations or in their final locations.
Add routers (repeaters) between the coordinator and end devices.
Zigbee is a mesh network. If you're seeing issues connecting to far away devices or devices with walls between them and the coordinator then a router / repeater may solve your issues.
Reset your end device after adding a router / repeater. Most devices will not connect to a router / repeater unless initially paired with the router / repeater in place.
Most (but not all) mains-powered devices will act as a router / repeater. Battery-powered devices are not routers / repeaters.
Pair your devices after pairing all routers / repeaters.
Pair your devices in their final location.
Zigbee builds its mesh according to where devices are paired at. Most devices do not re-build their connections when moved, so the mesh will often not adapt to you moving a device after pairing it.
Place your Zigbee coordinator far from other electronic devices.
Interference from 2.4 GHz Wifi is a major source of Zigbee issues.
Other equipment can emit RF noise in the 2.4 GHz range, like USB 3 ports on computers.
Place your Zigbee coordinator central to your house or your Zigbee devices.
Avoid walls and other obstacles between your coordinator and devices, where possible.
Try initially testing with devices in line-of-sight to each other.
Try different orientations of your Zigbee coordinator's antenna.
If your coordinator is an all-in-one device like a USB stick, re-orient the whole device.
Avoid USB 3.
USB 3 can emit RF noise in the 2.4 GHz range, which interferes with Zigbee.
Ensure you're using a USB 2 port, and try different ports to see if one performs better.
A USB 2 extension cable may help eliminate some USB 3 RF noise.
Use a long USB 2 extension cable or use a Zigbee router that connects over Ethernet.
A long cable allows you to avoid interference and orient your coordinator optimally.
Ensure 2.4 GHz WiFi and Zigbee are not operating on the same RF channels.
- See ZigBee and Wi-Fi Coexistence for a a detailed description of how Zigbee and WiFi can interfere.
- Use a WiFi scanning app to see which channels your neighbors are using. Place your Zigbee network on the Zigbee channel with the least interference from your neighbors.
- Place your 2.4 GHz WiFi on a channel that does not overlap your Zigbee network.
- Changing your Zigbee channel require re-pairing all Zigbee devices.
Update the firmware of your Zigbee coordinator to the most-compatible version.
This is typically the most-recent version, but sometimes older versions have better compatibility. Check community resources for your Zigbee router first.
Try a different computer, or try a Zigbee router that connects over Ethernet.
Rarely, an issue with the host computer may be at fault.
Cut the host computer out of the equation by testing with a different computer or using an Ethernet coordinator.
If your coordinator has a removable antenna, you can try a directional high-gain antenna.
This is only necessary for covering long distances or significant obstacles. If you are trying to resolve fundamental issues with close devices you have line-of-sight too, then something else is the cause.
Buy a more powerful Zigbee coordinator.
Zigbee coordinators with external antennas give you the best power, range, and flexibility.
Zigbee coordinators that work over Ethernet give you the most flexibility and eliminate hardware connection issues between the coordinator and the host computer.

Source

Poor signal quality and signal interference can cause significant degradation in Zigbee network performance. Here are some tips for optimizing signal quality and coverage. Following all of these tips will typically resolve most range and transmission issues.

* Test the network with a small number of devices to minimize external variables.
  For an initial test your coordinator should have line-of-sight to connected Zigbee devices. Once that works consistently, *re-pair* your devices in more realistic test locations or in their final locations.
* Add routers (repeaters) between the coordinator and end devices.
  Zigbee is a mesh network. If you're seeing issues connecting to far away devices or devices with walls between them and the coordinator then a router / repeater may solve your issues.
  **Reset your end device after adding a router / repeater.** Most devices will not connect to a router / repeater unless initially paired with the router / repeater in place.
  Most (but not all) mains-powered devices will act as a router / repeater. Battery-powered devices are *not* routers / repeaters.
* Pair your devices *after* pairing all routers / repeaters.
* Pair your devices in their final location.
  Zigbee builds its mesh according to where devices are *paired* at. Most devices do not re-build their connections when moved, so the mesh will often not adapt to you moving a device after pairing it.
* Place your Zigbee coordinator far from other electronic devices.
  Interference from 2.4 GHz Wifi is a major source of Zigbee issues.
  Other equipment can emit RF noise in the 2.4 GHz range, like USB 3 ports on computers.
* Place your Zigbee coordinator central to your house or your Zigbee devices.
  Avoid walls and other obstacles between your coordinator and devices, where possible.
  Try initially testing with devices in line-of-sight to each other.
* Try different orientations of your Zigbee coordinator's antenna.
  If your coordinator is an all-in-one device like a USB stick, re-orient the whole device.
* Avoid USB 3.
  USB 3 can emit RF noise in the 2.4 GHz range, which interferes with Zigbee.
  Ensure you're using a USB 2 port, and try different ports to see if one performs better.
  A USB 2 extension cable may help eliminate some USB 3 RF noise.
* Use a *long* USB 2 extension cable *or* use a Zigbee router that connects over Ethernet.
  A long cable allows you to avoid interference and orient your coordinator optimally.
* Ensure 2.4 GHz WiFi and Zigbee are not operating on the same RF channels.
  * See [ZigBee and Wi-Fi Coexistence](https://www.metageek.com/training/resources/zigbee-wifi-coexistence.html) for a a detailed description of how Zigbee and WiFi can interfere.
  * Use a WiFi scanning app to see which channels your neighbors are using. Place your Zigbee network on the Zigbee channel with the least interference from your neighbors.
  * Place your 2.4 GHz WiFi on a channel that does not overlap your Zigbee network.
  * Changing your Zigbee channel require re-pairing all Zigbee devices.
* Update the firmware of your Zigbee coordinator to the most-compatible version.
  This is typically the most-recent version, but sometimes older versions have better compatibility. Check community resources for your Zigbee router first.
* Try a different computer, or try a Zigbee router that connects over Ethernet.
  Rarely, an issue with the host computer may be at fault.
  Cut the host computer out of the equation by testing with a different computer or using an Ethernet coordinator.
* If your coordinator has a removable antenna, you can try a directional high-gain antenna.
  This is only necessary for covering long distances or significant obstacles. If you are trying to resolve fundamental issues with close devices you have line-of-sight too, then something else is the cause.
* Buy a more powerful Zigbee coordinator.
  Zigbee coordinators with external antennas give you the best power, range, and flexibility.
  Zigbee coordinators that work over Ethernet give you the most flexibility and eliminate hardware connection issues between the coordinator and the host computer.

I think the best way to make this more concise is to slim each significant point down to a single sentence, then either provide a link to more information or let the user use it as a starting point for their own search.

There's too much information to put it all here at once. Presenting the user a concise summary of all possible problems as a starting point is valuable as it lets users easily scan for problems and it's really the only way to hold the whole set of problems and solutions in your head.

Feel free to take either of my attempts above and expand on them.

(I came from one of the linked posts. Having all this information available would have helped me, but I agree it needs to be made more concise!)

Hedda · 2022-02-24T14:54:26Z

There's too much information to put it all here at once.

While it could wait I would actually like to have added another bullet point about shielding computer and USB devices/peripherals:

Shield your computer and USB devices or peripherals connected to computers as well as other appliances or cables/wires located close to your Zigbee Coordinator. As already established, Zigbee radio can be very susceptible to electromagnetic interference (EMI, also called radio-frequency interference or RFI), and one very common source that generates electromagnetic fields is unshielded computers and unshielded peripherals so make sure that you use for example enclosures for external hard drives and single-board-computers that are made of metal instead of plastic. Especially known to have a huge interference impact on wireless devices using radio frequency like Zigbee radios are USB 3.0 devices/peripherals (for more details on that read white paper report on the subject by Intel at https://www.usb.org/sites/default/files/327216.pdf).

The reason for this is seeing a lot of community forum posts with Zigbee interference problems caused by electromagnetic fields.

frenck · 2022-03-27T10:59:13Z

Ok, I'm stumbling on this PR again (during my pre-release preparation rounds). Either this PR works on the contents, or I'll consider it stale and close it.

I really appreciate any improvement to the documentation to the documentation, but as said before above; this is really unreadable.

If you have no intention to improve it, please close it. Thanks 👍

Hedda · 2022-03-28T06:59:47Z

Ok, I'm stumbling on this PR again (during my pre-release preparation rounds). Either this PR works on the contents, or I'll consider it stale and close it.

I really appreciate any improvement to the documentation to the documentation, but as said before above; this is really unreadable.

If you have no intention to improve it, please close it. Thanks 👍

I can edit it to try to shorten or separate some sentences and add more full stops. But I then hope you add it as-is as IMHO it is better to add something on this as a baseline that others can work from and edit than to have nothing at all as you have now.

frenck · 2022-03-28T07:26:46Z

is better to add something on this as a baseline that others can work from

We don't agree on this being a baseline. Again, its unreadable.

Improving Zigbee network range tips for ZHA in zha.markdown Split and converted previous submission to shorter bullet points.

Hedda · 2022-03-28T10:18:38Z

While I do get this is being added, it is really really hard to read. Bot in markdown and in the actual result on the website.

OK, I have now tried to fully break up or split and converted the previous submission attempt into much shorter bullet points.

I hope this makes it readable enough to make this PR acceptable for merger into ZHA docs?

As mentioned by @Corecii it is hard to make this initial entry shorter and concise because there is still a lot of information.

Again, please consider this as an initial entry that can commit as-is that can then be tweaked by other users after they see it.

Improving Zigbee network range

Poor signal quality or interference can lead to transmission problems and show symptoms such as or errors when sending and/or receiving Zigbee messages that will cause significant degradation in Zigbee network performance. Below is some fundamental background information and tips for a Zigbee setup starting point to achieve better signal quality, coverage and range.

Following these essential optimization tips will typically resolve many known issues caused by a bad setup of Zigbee Coordinator adapter and Zigbee network mesh or Zigbee devices. At the very least taking these actions should improve most message transmitting and receiving issues caused by not knowing the basics needed to workaround related Zigbee limitations.

Understanding common causes of problems in Zigbee setups

Zigbee Coordinator adapter hardware:
- Poor placement of the Zigbee Coordinator and/or wrong orientation of Zigbee Coordinator antenna.
- Poor / outdated / incompatible Zigbee Coordinator firmware on the Zigbee Coordinator adapter.
- Old, outdated or underpowered Zigbee Coordinator hardware or poor Zigbee Coordinator antenna.
Zigbee Coordinator and Zigbee devices sensitive to all types of RFI/EMI/EMF interference:
- Electromagnetic interference (EMI) from electronics caused by Electromagnetic Fields (EMF).
- USB 3.0 ports and computer peripherals are known culprits of EMI/EMF disrupting Zigbee.
- 2.4 GHz Radio Frequency Interference (RFI) from Wi-Fi Routers and Wi-Fi Access Points, or others.
- Radio proximity as well conflicting radio frequencies (Wi-Fi) overlapping used Zigbee frequency.
Too few or far distance between Zigbee devices in Zigbee network mesh:
- Too many obstacles between the Zigbee Coordinator or Zigbee Router and Zigbee End Device.
  - Zigbee network mesh depends on Zigbee Router devices to extend range and coverage.
  - All individual Zigbee devices do have poor signal penetration and not long range.
- Too few Zigbee Router devices Zigbee Coordinator or Zigbee Router and Zigbee End Device.
  - Only mains-powered devices can be repeaters that extend network range and coverage.
  - Any battery-operated products are a Zigbee End Device and will never be a Zigbee Router.

Simple actions that should improve most Zigbee setups

Zigbee Coordinator adapter hardware:
- Try different physical placement and orientations of Zigbee Coordinator or its antenna.
  - Optimal placement of Zigbee Coordinator is as much in middle of the house as possible.
  - Try to place the Zigbee coordinator at some distance way from walls, ceilings and floors.
  - Try different orientations of your Zigbee antenna (or whole Zigbee coordinator adapter).
- Update to a later released Zigbee Coordinator firmware on the Zigbee Coordinator adapter.
  - Updating FW is easy and community often provide newer firmware than manufacturer.
- Buy a more powerful Zigbee Coordinator adapter based on a newer/modern Zigbee chip hardware.
  - Recommended as older adapter might work but have obsolete hardware and/or firmware.
Zigbee Coordinator and Zigbee devices RFI sensitive as susceptible to all types of EMI/EMF interference:
- Use a long USB extension cable to place Zigbee Coordinator away from interference and obstacles.
  - Try to make sure the USB extension cable has proper shielded (thick cables usually do).
  - Longer USB extension cable also make it easier to orient Zigbee Coordinator and antenna.
- Only connect Zigbee Coordinator USB adapter to a USB 2.0 ports (or a powered USB 2.0 hub).
  - USB 3.0 ports and peripherals are infamously known for causing EMI/EMF interference.
- Shield close unshielded computers and unshielded peripherals by using metal enclosures/chassis.
  - Single-board-computers and USB hard drives are especially known as source of EMI/EMF.
- Change Wi-Fi Router and Access Points channels to not interfere with the default Zigbee channel.
  - Changing Wi-Fi channel on Wi-Fi devices is recommended over changing Zigbee channel.
- Change Zigbee channel on Zigbee network if have too many strong sources of overlapping Wi-Fi.
  - Changing Zigbee channel is considered a last resort so make sure to do research before.
    - Normally require re-pairing all, and not all devices support all Zigbee channels.
Too few or far distance between Zigbee devices in Zigbee network mesh:
- Zigbee network mesh depends on having Zigbee Router devices to extend range and coverage:
  - Add additional mains-powered Zigbee devices known to be good as Zigbee Router device.
    - Add more Zigbee Router devices to extend network mesh range and coverage.
    - Note that not all mains-powered Zigbee devices act as a Zigbee Router device.
    - Some Zigbee Router devices are know to only work well with same brand devices.
  - Buy a few known good dedicated Zigbee Router product (ex. “IKEA Tradfri Signal Repeater”).
    - Search community forums for "Zigbee signal repeater" or "Zigbee range extender".
  - Buy a few extra new Zigbee USB adapters to use after flashing with Zigbee Router firmware.
  - Reflash/reuse Zigbee USB adapters to Zigbee Router when upgrading Zigbee Coordinator.

External resources for initial Zigbee setup optimizations:

kroimon · 2022-04-26T10:19:20Z

LGTM.

I like the bullet point style. I don't think it can be any shorter without leaving out important hints or information.

Hedda · 2023-02-05T14:04:30Z

Does anyone else have any constructive feedback on how to rewrite this to make it good enough for merging into the ZHA docs?

frenck · 2023-02-14T07:51:17Z

The constructive feedback was given: it is a huge unreadable bullet list, that is hard to read, especially on mobile.

The solution is: don't make a huge bullet list. Make some chapters/paragraphs with some readable text in it that flows and is easy to the eyes to read. Sure some sections may have some bullet point, that is fine. The huge list is the issue here.

../Frenck

Shorten, restructured and rewritten the bullet point list

Hedda · 2023-02-14T11:47:46Z

The solution is: don't make a huge bullet list. Make some chapters/paragraphs with some readable text in it that flows and is easy to the eyes to read. Sure some sections may have some bullet point, that is fine. The huge list is the issue here.

OK, based on that more specific feedback I have now tried to clean and restructured as separate smaller bullet point lists, removing some parts as well as splitting some other parts into shorter chapters/paragraphs instead.

Hedda · 2023-03-01T13:13:35Z

For reference, Home Assistant SkyConnect website and FAQ on webpage where to buy it do now contain some of this information:

https://skyconnect.home-assistant.io/connectivity/

https://www.home-assistant.io/skyconnect -> FAQs -> "Why include a USB extension cable?"

"USB 3.0 ports (the ones with blue on the inside) are known to cause significant noise and radio interference to any 2.4Ghz wireless devices. This includes Zigbee and Thread. If you do not use the extension cable, it may not work at all, and if it does, it could be flaky at best with intermittent problems (issues with pairing, device dropouts, unreachable devices, timeout errors, etc)."

Issue with USB 3.0 interference for Zigbee was also mentioned in Home Assistant's latest newsletter for Building the Open Home:

https://building.open-home.io/assisting-the-open-home/

Zigbee interference caused by USB 3.0

A lot of users build their smart home around a Raspberry Pi. It's quite popular to expand the storage using an external hard drive connected to the Raspberry Pi via USB 3. What most users don't know is that USB 3 causes enormous interference with any Zigbee device or stick that comes close, to a point that it no longer works.

Gabriela recently joined the Nabu Casa team as a technical documentation writer and has been focusing on documentation to help users avoid common pitfalls like these. She updated the documentation for the Home Assistant SkyConnect including this 30 second video that shows how bad the issue is:

https://www.youtube.com/watch?v=tHqZhNcFEvA&t=1s&ab_channel=HomeAssistant

frenck

This looks nice now! Good work.
Some nitpicks left, which I provided suggestions for.

source/_integrations/zha.markdown

home-assistant · 2023-03-09T09:51:16Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

Hedda · 2023-03-10T10:27:18Z

OK marking this as ready for review now.

frenck

Thanks, @Hedda 👍 🎉

../Frenck

Update zha.markdown with tips on improving Zigbee network range

b21c495

Update zha.markdown with tips on improving Zigbee network range and coverage.

Hedda requested review from Adminiuga and dmulcahey as code owners August 9, 2021 14:10

probot-home-assistant bot added the current This PR goes into the current branch label Aug 9, 2021

homeassistant added the cla-signed label Aug 9, 2021

github-actions bot added Stale The PR had no activity for quite some time, and is marked as Stale and removed Stale The PR had no activity for quite some time, and is marked as Stale labels Oct 8, 2021

Hedda mentioned this pull request Oct 21, 2021

RF Range diyruz/flower#37

Open

frenck added the smash Indicator this PR is close to finish for merging or closing label Oct 26, 2021

Hedda mentioned this pull request Dec 6, 2021

Readme Troubleshooting zigpy/zigpy-znp#80

Closed

Hedda mentioned this pull request Feb 1, 2022

ZHA device communication failures after restore/migration home-assistant/core#64404

Closed

SNoof85 mentioned this pull request Feb 9, 2022

Warning about interferences on the radio modules #21565

Closed

Hedda mentioned this pull request Feb 15, 2022

ZHA unreliable and slow on boot (async_initialize: all attempts have failed) with Conbee 2 home-assistant/core#62494

Closed

Improving Zigbee network range tips for zha.markdown

970295a

Improving Zigbee network range tips for ZHA in zha.markdown Split and converted previous submission to shorter bullet points.

Hedda mentioned this pull request Apr 6, 2022

Add short intro and to dictionary to zha.markdown #22260

Closed

8 tasks

Merge branch 'current' into patch-49

8778b24

frenck marked this pull request as draft February 3, 2023 22:40

Hedda mentioned this pull request Feb 5, 2023

Pull request #18864 is locked so no one including myself can comment or make changes to it #26119

Closed

home-assistant unlocked this conversation Feb 5, 2023

Merge branch 'current' into patch-49

0ce301f

Hedda mentioned this pull request Feb 13, 2023

Radio migration procedure in ZHA docs #26236

Merged

8 tasks

Restructured last segments

92949c8

Hedda marked this pull request as ready for review February 13, 2023 15:06

frenck marked this pull request as draft February 14, 2023 07:51

Shorten, restructured and rewritten bullets

dddc6e0

Shorten, restructured and rewritten the bullet point list

Hedda marked this pull request as ready for review February 14, 2023 11:49

frenck requested changes Mar 9, 2023

View reviewed changes

source/_integrations/zha.markdown Outdated Show resolved Hide resolved

source/_integrations/zha.markdown Outdated Show resolved Hide resolved

source/_integrations/zha.markdown Outdated Show resolved Hide resolved

source/_integrations/zha.markdown Outdated Show resolved Hide resolved

home-assistant bot marked this pull request as draft March 9, 2023 09:51

Hedda and others added 5 commits March 10, 2023 11:03

Update source/_integrations/zha.markdown

d3a07b2

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

Update source/_integrations/zha.markdown

5f59802

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

Update source/_integrations/zha.markdown

da4113c

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

Update source/_integrations/zha.markdown

0b7792d

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

Merge branch 'current' into patch-49

2b994df

Hedda marked this pull request as ready for review March 10, 2023 10:26

home-assistant bot requested a review from frenck March 10, 2023 10:26

frenck changed the title ~~Update zha.markdown with tips on improving Zigbee network range~~ Update ZHA documentation with tips on improving Zigbee network range Mar 10, 2023

frenck approved these changes Mar 10, 2023

View reviewed changes

frenck merged commit 48f4ac3 into home-assistant:current Mar 10, 2023

home-assistant bot removed the in-progress This PR/Issue is currently being worked on label Mar 10, 2023

github-actions bot locked and limited conversation to collaborators Mar 11, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update ZHA documentation with tips on improving Zigbee network range #18864

Update ZHA documentation with tips on improving Zigbee network range #18864

Hedda commented Aug 9, 2021 •

edited

Loading

github-actions bot commented Oct 8, 2021

Hedda commented Dec 1, 2021 •

edited

Loading

frenck commented Feb 18, 2022

Hedda commented Feb 20, 2022

Hedda commented Feb 20, 2022

frenck commented Feb 22, 2022

Corecii commented Feb 24, 2022 •

edited

Loading

Hedda commented Feb 24, 2022 •

edited

Loading

frenck commented Mar 27, 2022

Hedda commented Mar 28, 2022

frenck commented Mar 28, 2022

Hedda commented Mar 28, 2022 •

edited

Loading

kroimon commented Apr 26, 2022

Hedda commented Feb 5, 2023

frenck commented Feb 14, 2023

Hedda commented Feb 14, 2023

Hedda commented Mar 1, 2023 •

edited

Loading

frenck left a comment

home-assistant bot commented Mar 9, 2023

Hedda commented Mar 10, 2023

frenck left a comment

Update ZHA documentation with tips on improving Zigbee network range #18864

Update ZHA documentation with tips on improving Zigbee network range #18864

Conversation

Hedda commented Aug 9, 2021 • edited Loading

Proposed change

Type of change

Additional information

Checklist

github-actions bot commented Oct 8, 2021

Hedda commented Dec 1, 2021 • edited Loading

frenck commented Feb 18, 2022

Hedda commented Feb 20, 2022

Hedda commented Feb 20, 2022

frenck commented Feb 22, 2022

Corecii commented Feb 24, 2022 • edited Loading

Hedda commented Feb 24, 2022 • edited Loading

frenck commented Mar 27, 2022

Hedda commented Mar 28, 2022

frenck commented Mar 28, 2022

Hedda commented Mar 28, 2022 • edited Loading

Improving Zigbee network range

Understanding common causes of problems in Zigbee setups

Simple actions that should improve most Zigbee setups

External resources for initial Zigbee setup optimizations:

kroimon commented Apr 26, 2022

Hedda commented Feb 5, 2023

frenck commented Feb 14, 2023

Hedda commented Feb 14, 2023

Hedda commented Mar 1, 2023 • edited Loading

Zigbee interference caused by USB 3.0

frenck left a comment

Choose a reason for hiding this comment

home-assistant bot commented Mar 9, 2023

Hedda commented Mar 10, 2023

frenck left a comment

Choose a reason for hiding this comment

Hedda commented Aug 9, 2021 •

edited

Loading

Hedda commented Dec 1, 2021 •

edited

Loading

Corecii commented Feb 24, 2022 •

edited

Loading

Hedda commented Feb 24, 2022 •

edited

Loading

Hedda commented Mar 28, 2022 •

edited

Loading

Hedda commented Mar 1, 2023 •

edited

Loading