ZHA troubleshooting Zigbee OTA upgrades of device firmware #35884
Conversation
Add new sections under troubleshooting about resolving ZHA problems with Zigbee OTA upgrading of device firmware not starting or failing.
Hedda
requested review from
dmulcahey,
Adminiuga,
puddly and
TheJulianJES
as code owners
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe changes in the pull request enhance the documentation for the Zigbee Home Automation (ZHA) integration in Home Assistant. Notable additions include a section addressing issues with Over-The-Air (OTA) firmware upgrades for Zigbee devices, emphasizing battery life and device readiness. Additionally, a new subsection on Zigbee network visualization is included to help users assess device connectivity. Minor adjustments throughout the document improve clarity and organization, while the overall structure remains consistent. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant ZHA
participant ZigbeeDevice
User->>ZHA: Initiate OTA firmware upgrade
ZHA->>ZigbeeDevice: Check battery status
ZigbeeDevice-->>ZHA: Battery sufficient
ZHA->>ZigbeeDevice: Wake up device
ZHA->>ZigbeeDevice: Start firmware upgrade
ZigbeeDevice-->>ZHA: Upgrade successful
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (2)
source/_integrations/zha.markdown (2)
586-593: Enhance the organization and emphasis of the OTA upgrade section.While the content is valuable, consider these improvements for better readability and user safety:
- Add a prominent warning box at the start of the section using the existing warning template:
{% warning %} - OTA updates can take up to 10 minutes and generate significant network traffic - Battery-powered devices require at least 70% battery life - Multiple simultaneous updates are not recommended {% endwarning %}
- Organize the content into clear subsections with headers:
- Prerequisites
- Troubleshooting
- Network Considerations
Line range hint
594-605: Consider adding more context for technical terms.The network visualization section is well-structured but could be more accessible to non-technical users. Consider:
- Adding a brief introduction explaining what network visualization means in simple terms:
The network visualization feature provides a visual map of how your Zigbee devices communicate with each other. This can help you identify devices that might have connection problems or need to be relocated for better performance.
- Including a simple diagram or screenshot showing an example of the visualization.
| @@ -583,6 +583,14 @@ Since all Zigbee Coordinator radio adapters are very sensitive/susceptible to al | |||
| - Place your Zigbee Coordinator away from any Wi-Fi access points and all other sources of WiFi. | |||
| - Wi-Fi frequency ranges can overlap with Zigbee, see the section above on defining Zigbee channel use. | |||
|
|
|||
| ### Problems upgrading Zigbee device firmware via OTA | |||
|
|
|||
| Be aware that OTAU (Over-The-Air Upgrade) of Zigbee devices typically takes around 10 minutes. While a device is updating a lot of traffic is generated on the network, therefore it is recommended to not execute multiple updates at the same time. Always check that battery-powered devices have at least 70% of battery-life left before starting a firmware upgrade (a general tip is therefore to simply put new fresh batteries in before upgrading any OTA firmware upgrade), OTA updating of firmware is very power-consuming and while some devices do check for a minimum battery-level before starting the upgrade and might refuse to update unless have enough battery-life left, not all do so. | |||
There was a problem hiding this comment.
therefore it is recommended to not execute multiple updates at the same time.
This is not something we should burden our users with. If this is an issue it should be fixed.
There was a problem hiding this comment.
Always check that battery-powered devices have at least 70% of battery-life left before starting a firmware upgrade
Same.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Co-authored-by: Franck Nijhof <[email protected]>
Co-authored-by: Franck Nijhof <[email protected]>
Proposed change
Document basic troubleshooting/resolving ZHA problems with Zigbee OTA upgrading if device OTA firmware does not start or fail.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.Summary by CodeRabbit
New Features
Documentation