Create General_Zigbee_Best_Practices_and_Troubleshooting_Tips.md

en-eng/General_Zigbee_Best_Practices_and_Troubleshooting_Tips.md

@@ -0,0 +1,26 @@
+### Best practices for optimizing reception and transmission to improve Zigbee network range and coverage
+
+Both poor signal quality and signal interference can lead to transmission errors and related issues.  This section contains fundamental troubleshooting tips on how to improve signal quality plus optimize range and coverage. Improving signal quality and removing sources of signal interference can in most cases maximize range and resolves 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.
+
+1. Adding more Zigbee routers between devices far away and the next closest router or your Zigbee coordinator. Zigbee network topology uses a "mesh network" design which means that each device that acts as a Zigbee router will extend the total range and coverage of your Zigbee network as a whole. The solution is to distribute more Zigbee routers in areas with poor reception. Note that while there are exceptions, understand that almost all permanently powered devices will serve as a Zigbee router. Thus adding more permanently powered Zigbee devices will allow greater range 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/)) (an example being IKEA Tradfri Signal Repeater). Devices that can not act as routers are typically battery-operated and known as "end devices". There are some exceptions as some end devices (e.g. Xiaomi/Aqara devices) have issues connecting through routers that are not from the same manufacturer.
+2. Use a long USB extension cable with your Zigbee coordinator adapter. This not only enables you to position the Zigbee coordinator adapter for better signal quality, but it also allows you to locate the Zigbee coordinator further away from Wi-Fi access-points/routers or other sources of 2.4GHz signals to avoid signal interference. Optimally in the best area in your home depending on your building's floorplan. Ideally, you want to place the Zigbee coordinator somewhere in the middle of your house/apartment. Building materials influence signal quality, 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. 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).
+4. 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.
+5. Check if updating the firmware on your Zigbee coordinator adapter and your Zigbee end devices is possible. 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.
+6. If your Zigbee coordinator adapter has a removable antenna (e.g., with an SMA-connector) then you have the option of replacing it with a high-gain antenna. Note that antennas with higher gain usually 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.
+7. Buy more powerful Zigbee radio hardware with a better radio range, preferably with an external antenna and based on a newer chip that offers up-to-date firmware. If you are not only experimenting with Zigbee but want a permanently stable and healthy Zigbee mesh network with potentially many devices then you should consider upgrading to a more powerful and newer Zigbee coordinator USB adapter or Ethernet to serial gateway/bridge. Generally, Zigbee adapters with an external antenna will have a better range and offer you more flexibility, therefore you will also want to avoid buying an internal Zigbee adapter unless it has a port for an external antenna.
+
+### Best practices to avoid pairing/connection difficulties
+
+Verify that you try to follow recommended best practices to avoid pairing and/or connection issues:
+
+- If possible try to pair your Zigbee devices in their intended final location, (and not pair it next to the Zigbee coordinator and then need to move it after). 
+  - Pairing a Zigbee device next to the Zigbee coordinator and then moving it later can result in dropped/lost connections or other issues. 
+    - If the device you want to add is not brand new and as such never paired before then you always have to make sure to first manually reset the device to its factory default settings before you will be able to add/pair it. 
+- Some battery-operated Zigbee devices are known to have problems with pairing if they have Low battery voltage. 
+    - Some people have reported replacing the battery on their newly received Xiaomi/Aqara devices solved pairing issues. 
+- Check that you have enough Zigbee router devices (also known as Zigbee signal repeaters or range extenders) and if you do not have any, invest and add some mains-powered devices that will work as Zigbee routers. 
+    - Aim to start out with mains-powered devices before adding battery-operated devices as a "weak" Zigbee network mesh (e.g., the device is too far from the Zigbee coordinator or a Zigbee router) may prevent some devices from being paired. Zigbee router devices are also needed to increase the maximum of devices that can be connected to your Zigbee mesh network. 
+    - Note that some Zigbee devices are not fully compatible with all brands of Zigbee router devices. Xiaomi/Aqara devices are for example known not to work with Zigbee router devices from Centralite, General Electrics, Iris, Ledvance/OSRAM, LIGHTIFY/Sylvania, Orvibo, PEQ, Securifi, and SmartThings/Samsung. Better results can usually be achieved by using mains-powered devices IKEA and Nue/3A Home or dedicated DIY routing devices based on Texas Instruments CC253x/CC26x2 and XBee Series 2/3 Zigbee radios. 
+- Be patient as the pairing of some Zigbee devices may require multiple attempts and you may sometimes need to try again and again. 
+    - Some devices, like example those from Xiaomi/Aqara, are known to not be 100% compliant with the standard Zigbee specifications and may therefore require many paring attempts over 10-20 minutes or longer.