Update Zigbee OTA best practices #35886
Conversation
Update Zigbee OTA best practices in the normal section (this is not same as for troubleshooting sections).
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 documentation for the Zigbee Home Automation (ZHA) integration in Home Assistant focus on enhancing user guidance regarding firmware updates, device pairing, and troubleshooting. Key updates include warnings about firmware updates, advice on checking device battery levels, and detailed YAML configuration examples. The documentation now emphasizes the importance of using mains-powered devices as Zigbee routers and provides improved troubleshooting tips to optimize network performance and mitigate interference. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant ZHA Integration
participant Device
User->>ZHA Integration: Initiate firmware update
ZHA Integration-->>User: Check battery levels
User->>Device: Verify device status
Device-->>User: Confirm battery level
User->>ZHA Integration: Proceed with update
ZHA Integration-->>Device: Perform OTA update
Device-->>ZHA Integration: Update status
ZHA Integration-->>User: Update complete
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 (1)
source/_integrations/zha.markdown (1)
232-236: Improve markdown formatting and warning message structure.The warning section about firmware updates could be improved for better readability and proper markdown formatting.
Apply this diff to fix the formatting and enhance the structure:
- - Always check if the firmware update will bring you advantages or disadvantages, you might not need to install an available update and can maybe just ignore it. Firmware updates are often not made specifically for this ZHA integration but instead only tested to work with different Zigbee gateways (usually just from the same brand). 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. The best practise is therefore to search online and read the device manufacturer changelog before deciding to upgrade the firmware on any specific device. -Some other more general but related tips are these: - - Recommend you check that battery-powered devices have at least 70% battery life before upgrading. - - OTA updates can take 10 minutes or longer and generate significant network traffic, be patient! - - Multiple simultaneous updates is not recommended as it generates more Zigbee network traffic. +- Always check if the firmware update will bring you advantages or disadvantages: + - You might not need to install an available update and can ignore it + - Firmware updates are often not made specifically for ZHA integration + - Updates are usually tested only with the manufacturer's own gateway + - Some updates can break features (e.g., group binding for IKEA devices) + - Some updates might require changes to ZHA + - In rare cases, you can even brick devices + +Best practices for firmware updates: + +- Search online and read the device manufacturer changelog before updating +- Ensure battery-powered devices have at least 70% battery life +- Be patient as OTA updates can take 10 minutes or longer +- Avoid multiple simultaneous updates to reduce network traffic🧰 Tools
🪛 Markdownlint (0.35.0)
232-232: Expected: 0 or 2; Actual: 1
Trailing spaces(MD009, no-trailing-spaces)
232-232: null
Lists should be surrounded by blank lines(MD032, blanks-around-lists)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/zha.markdown(1 hunks)
🧰 Additional context used
🪛 Markdownlint (0.35.0)
source/_integrations/zha.markdown
232-232: Expected: 0 or 2; Actual: 1
Trailing spaces
(MD009, no-trailing-spaces)
232-232: null
Lists should be surrounded by blank lines
(MD032, blanks-around-lists)
Update OTA warnings as per bot suggestions
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (1)
source/_integrations/zha.markdown (1)
232-242: LGTM! Consider minor formatting improvements.The warning section provides valuable information about OTA firmware updates, helping users make informed decisions and avoid potential issues. The content is well-structured and comprehensive.
Consider these formatting improvements for better readability:
{% warning %} + - Always check if the firmware update will bring you advantages or disadvantages: - Search online and read the device manufacturer changelog before updating. - You might not need to install an available update and can maybe ignore it. - Firmware updates are often not made specifically for ZHA integration. - Updates are usually only tested with the manufacturer's own gateway. - Some updates can break features (e.g., group binding for IKEA devices). - Some updates might require changes to ZHA (e.g. updated ZHA Device Handlers). - In rare cases, a bad firmware upgrade can sometimes even brick a device. - Ensure battery-powered devices have at least 70% battery life. - Be patient as OTA updates can take 10 minutes or longer. - Avoid multiple simultaneous updates to reduce network traffic. + {% endwarning %}🧰 Tools
🪛 Markdownlint (0.35.0)
232-232: null
Lists should be surrounded by blank lines(MD032, blanks-around-lists)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/zha.markdown(1 hunks)
🧰 Additional context used
🪛 Markdownlint (0.35.0)
source/_integrations/zha.markdown
232-232: null
Lists should be surrounded by blank lines
(MD032, blanks-around-lists)
Added blank rows for formatting
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (1)
source/_integrations/zha.markdown (1)
232-244: LGTM! Clear and comprehensive OTA update warnings.The restructured warning section effectively communicates important considerations for OTA updates. The bullet-point format improves readability, and the content covers essential aspects like battery requirements, timing expectations, and potential risks.
Consider adding these minor enhancements:
- Add a note about backing up device configurations before updates
- Include guidance on what to do if an update fails
{% warning %} - Always check if the firmware update will bring you advantages or disadvantages: - Search online and read the device manufacturer changelog before updating. - You might not need to install an available update and can maybe ignore it. - Firmware updates are often not made specifically for ZHA integration. - Updates are usually only tested with the manufacturer's own gateway. - Some updates can break features (e.g., group binding for IKEA devices). - Some updates might require changes to ZHA (e.g. updated ZHA Device Handlers). - In rare cases, a bad firmware upgrade can sometimes even brick a device. + - Before updating: + - Back up your device configurations if possible + - Document current device settings for reference - Ensure battery-powered devices have at least 70% battery life. - Be patient as OTA updates can take 10 minutes or longer. - Avoid multiple simultaneous updates to reduce network traffic. + - If an update fails: + - Wait 15 minutes before retrying + - Ensure stable network conditions + - Contact device manufacturer support if issues persist {% endwarning %}
| @@ -229,7 +229,19 @@ The ZHA integration has the ability to perform OTA (over-the-air) firmware updat | |||
| To see OTA updates for a device, it's required that it both supports OTA updates and that firmware images for the device are publicly provided by the manufacturer. For this reason, ZHA currently only includes OTA providers for a few manufacturers that provide these updates publicly. This includes IKEA, Inovelli, Ledvacnce/OSRAM, SALUS/Computime, Sonoff/iTead, and Third Reality. | |||
|
|
|||
| {% warning %} | |||
| 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. | |||
|
|
|||
| - Always check if the firmware update will bring you advantages or disadvantages: | |||
There was a problem hiding this comment.
I'm not sure how this is a item in the list.
|
|
||
| - Always check if the firmware update will bring you advantages or disadvantages: | ||
| - Search online and read the device manufacturer changelog before updating. | ||
| - You might not need to install an available update and can maybe ignore it. |
There was a problem hiding this comment.
This doesn't help. It confuses. "You should be able to jump from this ledge safely without breaking legs, or maybe not.."
| - Always check if the firmware update will bring you advantages or disadvantages: | ||
| - Search online and read the device manufacturer changelog before updating. | ||
| - You might not need to install an available update and can maybe ignore it. | ||
| - Firmware updates are often not made specifically for ZHA integration. |
There was a problem hiding this comment.
Not understanding how this even matters. This is not about ZHA, this is about the device.
| - Some updates can break features (e.g., group binding for IKEA devices). | ||
| - Some updates might require changes to ZHA (e.g. updated ZHA Device Handlers). | ||
| - In rare cases, a bad firmware upgrade can sometimes even brick a device. | ||
| - Ensure battery-powered devices have at least 70% battery life. |
There was a problem hiding this comment.
Seems like a random number. If this is problematic, we should guard from it from the ZHA end, and not impose this onto the user.
| - In rare cases, a bad firmware upgrade can sometimes even brick a device. | ||
| - Ensure battery-powered devices have at least 70% battery life. | ||
| - Be patient as OTA updates can take 10 minutes or longer. | ||
| - Avoid multiple simultaneous updates to reduce network traffic. |
There was a problem hiding this comment.
This is not a burden we should be putting on users, it is up to us to handle this stuff.
|
Thanks for the PR @Hedda 👍 I've reviewed it, and honestly think this is not an improvement. I'm going to friendly decline the PR for that reason. ../Frenck |
Proposed change
Update Zigbee OTA "warnings "(i.e. best practices) in the normal section, (this is not the same as for the troubleshooting section).
(Posting changes under warning in the normal section was suggeted as outside diff range and nitpick comments by coderabbitai).
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.Summary by CodeRabbit