Document the options to send retained MQTT discovery messages #35763
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Caution Review failedThe pull request is closed. 📝 Walkthrough📝 WalkthroughWalkthroughThe MQTT integration documentation for Home Assistant has been updated with several modifications regarding entity management and discovery processes. A new condition has been introduced for enabling disabled entities, clarifying that they will cause the MQTT integration to reload if added after 30 seconds. The documentation specifies that all MQTT devices and entities will be unavailable at startup until a discovery message is processed. Additionally, requirements for shared device configurations have been updated, and the section on Birth and Last Will messages has been expanded with examples for configuring MQTT items. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant MQTT Broker
participant Home Assistant
User->>Home Assistant: Enable disabled entity
Home Assistant->>MQTT Broker: Send enable command
MQTT Broker->>Home Assistant: Acknowledge enable command
Home Assistant->>Home Assistant: Reload MQTT integration
Home Assistant->>MQTT Broker: Request discovery messages
MQTT Broker->>Home Assistant: Send discovery messages
Home Assistant->>User: Notify about available entities
Warning Rate limit exceeded@jbouwh has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 5 minutes and 7 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 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 (3)
source/_integrations/mqtt.markdown (3)
212-214: Improve clarity of critical timing behavior.The explanation of the MQTT integration's reload behavior and timing constraints could be clearer. Consider restructuring for better readability.
-In case a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. -When MQTT starts up, all existing MQTT devices, entities, tags and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe the Birth message and use this as a trigger to send the [discovery payload](#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended. +Important timing considerations: +1. If a disabled entity is enabled after 30 seconds: + - The MQTT integration will reload + - All discovered MQTT entities will be unloaded + +2. During MQTT startup: + - All existing MQTT devices, entities, tags, and device triggers will be unavailable + - They remain unavailable until discovery messages are received and processed + - Devices should: + - Subscribe to the Birth message + - Use it as a trigger to send discovery payloads + - Add a random delay to prevent high broker IO load
215-219: Improve clarity of alternative approaches and fix grammar.The section about alternative approaches needs better structure and grammar improvements.
-An alternative approaches are: - -- Retaining the [discovery payload](#discovery-payload). This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities this can cause high IO loads. -- Periodic re-sending the discovery payload. This can could some delay, or a lot of IO if there are a lot of MQTT discovery messages. +Alternative approaches: + +1. Retaining the [discovery payload](#discovery-payload): + - Stores the payload at the MQTT broker + - Automatically offered to MQTT integration upon subscription + - Warning: May cause high IO loads with numerous entities + +2. Periodic re-sending of discovery payloads: + - Ensures eventual discovery + - Warning: May introduce delays + - Warning: Can cause significant IO load with numerous entities🧰 Tools
🪛 LanguageTool
[style] ~217-~217: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...ibes for MQTT discovery. When there are a lot of entities this can cause high IO loads. ...(A_LOT_OF)
632-633: Improve clarity of retained discovery message documentation.The explanation of retained discovery messages could be clearer and better structured.
-A discovery payload could be sent with a retain flag set. In that case it will be stored at the MQTT broker and will be processed automatically without the need to resent the discovery messages. A better approach thought, is that the software generating MQTT discovery messages, sends them when the MQTT integration sends the [Birth message](#birth-and-last-will-messages). +Discovery payloads can be handled in two ways: + +1. Using retain flag: + - Set retain flag when sending discovery payload + - Payload is stored at the MQTT broker + - Automatic processing without resending + +2. Recommended approach: + - Send discovery messages in response to MQTT integration's [Birth message](#birth-and-last-will-messages) + - More efficient and controlled approach🧰 Tools
🪛 LanguageTool
[formatting] ~632-~632: Consider inserting a comma after an introductory phrase for better readability.
Context: ...d could be sent with a retain flag set. In that case it will be stored at the MQTT broker an...(IN_THAT_CASE_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/mqtt.markdown(2 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/mqtt.markdown
[style] ~217-~217: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...ibes for MQTT discovery. When there are a lot of entities this can cause high IO loads. ...
(A_LOT_OF)
[formatting] ~632-~632: Consider inserting a comma after an introductory phrase for better readability.
Context: ...d could be sent with a retain flag set. In that case it will be stored at the MQTT broker an...
(IN_THAT_CASE_COMMA)
📝 WalkthroughWalkthroughThe changes involve updates to the MQTT integration documentation, focusing on entity management and discovery processes. Key modifications include clarifications on the behavior of entities during startup, the importance of subscribing to the Birth message, and alternative methods for managing discovery payloads. The documentation also specifies updated requirements for mandatory fields in device configurations and expands on the naming conventions for MQTT entities, including the implications of using retained messages. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant MQTT_Broker
participant Device
Client->>MQTT_Broker: Subscribe to Birth message
Device->>MQTT_Broker: Send discovery payload
MQTT_Broker->>Client: Deliver discovery payload
Client->>Device: Initialize entities
Device->>Client: Send entity status
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 (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
source/_integrations/mqtt.markdown (3)
212-214: Improve clarity of startup behavior documentationThe explanation of entity behavior during startup could be more structured and clearer. Consider this revision:
-In case a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. -When MQTT starts up, all existing MQTT devices, entities, tags and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe the Birth message and use this as a trigger to send the [discovery payload](#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended. +When a disabled MQTT entity is enabled after 30 seconds of startup, the MQTT integration will reload, causing all discovered MQTT entities to be temporarily unloaded. + +During MQTT startup: +1. All existing MQTT devices, entities, tags, and device triggers will be marked as unavailable +2. They remain unavailable until a discovery message is received and processed +3. Devices should subscribe to the Birth message to trigger sending their [discovery payload](#discovery-payload) +4. To prevent broker overload, devices should add a random delay before sending discovery payloads
215-219: Fix grammatical issues and improve clarityThe section about alternative approaches contains some grammatical errors and could be more precise.
-An alternative approaches are: - -- Retaining the [discovery payload](#discovery-payload). This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities this can cause high IO loads. -- Periodic re-sending the discovery payload. This can could some delay, or a lot of IO if there are a lot of MQTT discovery messages. +Alternative approaches are: + +- Retaining the [discovery payload](#discovery-payload): The payload is stored at the MQTT broker and delivered to the MQTT integration upon subscription. Note: This may cause significant I/O load with numerous entities. +- Periodically resending the discovery payload: While this ensures eventual discovery, it may introduce delays and increase I/O load with multiple entities.🧰 Tools
🪛 LanguageTool
[style] ~217-~217: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...ibes for MQTT discovery. When there are a lot of entities this can cause high IO loads. ...(A_LOT_OF)
632-633: Improve formatting and clarity of retention explanationThe explanation of retained discovery payloads needs a comma after the introductory phrase and could be more concise.
-A discovery payload could be sent with a retain flag set. In that case it will be stored at the MQTT broker and will be processed automatically without the need to resent the discovery messages. +A discovery payload can be sent with a retain flag set. In that case, it will be stored at the MQTT broker and processed automatically without requiring message retransmission.🧰 Tools
🪛 LanguageTool
[formatting] ~632-~632: Consider inserting a comma after an introductory phrase for better readability.
Context: ...d could be sent with a retain flag set. In that case it will be stored at the MQTT broker an...(IN_THAT_CASE_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/mqtt.markdown(2 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/mqtt.markdown
[style] ~217-~217: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...ibes for MQTT discovery. When there are a lot of entities this can cause high IO loads. ...
(A_LOT_OF)
[formatting] ~632-~632: Consider inserting a comma after an introductory phrase for better readability.
Context: ...d could be sent with a retain flag set. In that case it will be stored at the MQTT broker an...
(IN_THAT_CASE_COMMA)
Co-authored-by: J. Nick Koston <nick@koston.org>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
source/_integrations/mqtt.markdown (3)
212-214: Improve clarity of the MQTT startup behavior description.The technical information is accurate, but the wording could be clearer. Consider this revision:
-If a disabled entity is enabled and added after 30 seconds, the MQTT integration will be reloaded and will cause all discovered MQTT entities to be unloaded. -When MQTT starts up, all existing MQTT devices, entities, tags, and device triggers, will be unavailable until a discovery message is received and processed. A device or service that exposes the MQTT discovery should subscribe to the Birth message and use this as a trigger to send the [discovery payload](#discovery-payload). To avoid high IO loads on the MQTT broker, adding some random delay in sending the discovery payload is recommended. +When a disabled entity is enabled after 30 seconds, the MQTT integration reloads, causing all discovered MQTT entities to be unloaded. +During MQTT startup, all existing MQTT devices, entities, tags, and device triggers remain unavailable until they receive and process a discovery message. Devices and services using MQTT discovery should: +1. Subscribe to the Birth message +2. Use it as a trigger to send the [discovery payload](#discovery-payload) +3. Add a random delay before sending discovery payloads to prevent high IO loads on the MQTT broker
215-219: Fix grammatical errors and improve wording.There are some grammatical errors and opportunities to improve clarity.
-Alternative approaches are: - -- Retaining the [discovery payload](#discovery-payload): This will store the discovery payload at the MQTT broker, and offer it to the MQTT integration as soon as it subscribes for MQTT discovery. When there are a lot of entities, this can cause high IO loads. -- Periodic re-sending the discovery payload: This can could some delay, or a lot of IO if there are a lot of MQTT discovery messages. +Alternative approaches: + +- Retaining the [discovery payload](#discovery-payload): Stores the discovery payload at the MQTT broker, making it immediately available when the MQTT integration subscribes. Note: This may cause high IO loads with numerous entities. +- Periodically resending the discovery payload: While this approach works, it may introduce delays and significant IO overhead when managing multiple MQTT discovery messages.🧰 Tools
🪛 LanguageTool
[style] ~217-~217: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...ibes for MQTT discovery. When there are a lot of entities, this can cause high IO loads....(A_LOT_OF)
632-633: Fix grammatical error in retained discovery message description.There's a subject-verb agreement error in the text.
-A discovery payload could be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker, and will be processed automatically when the MQTT integrations starts up. This removes the need for it to be resent. +A discovery payload can be sent with a retain flag set. In that case, the discovery message will be stored at the MQTT broker and will be processed automatically when the MQTT integration starts up. This removes the need for it to be resent.🧰 Tools
🪛 LanguageTool
[grammar] ~632-~632: “integrations” is a plural noun. It appears that the verb form is incorrect.
Context: ...utomatically when the MQTT integrations starts up. This removes the need for it to be ...(PCT_PLURAL_NOUN_SINGULAR_VERB_AGREEMENT)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/mqtt.markdown(2 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/mqtt.markdown
[style] ~217-~217: The phrase ‘a lot of’ might be wordy and overused. Consider using an alternative.
Context: ...ibes for MQTT discovery. When there are a lot of entities, this can cause high IO loads....
(A_LOT_OF)
[grammar] ~632-~632: “integrations” is a plural noun. It appears that the verb form is incorrect.
Context: ...utomatically when the MQTT integrations starts up. This removes the need for it to be ...
(PCT_PLURAL_NOUN_SINGULAR_VERB_AGREEMENT)
Co-authored-by: J. Nick Koston <nick@koston.org>
Proposed change
Improve MQTT documentation to explain MQTT discovery payloads can be retained or should be triggered by the Birth message to ensure entities are initialized when MQTT starts or is reloaded, e.g. when a disabled entity is enabled.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
connection,identifiers, andname.