Update off and unavailable in standby state #2728
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
frenck
reviewed
Jul 16, 2025
docs/core/integration-quality-scale/rules/entity-unavailable.md
Outdated
Show resolved
Hide resolved
📝 Walkthrough""" WalkthroughDocumentation was updated to clarify the meaning of the Changes
Sequence Diagram(s)No sequence diagram generated as changes are limited to documentation updates without control flow or feature modifications. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. 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
🧹 Nitpick comments (3)
docs/core/entity/media-player.md (1)
95-99: Break up the run-on sentence and fix minor style inconsistenciesThe note is great but hard to read in its current form and contains a case/anchor mismatch.
:::note -It is common that media players can't be controlled when in a standby state, If Home Assistant can turn on the device using another protocol or method it should be shown as `OFF` even if the main channel used to control the device is currently unavailable, if Home Assistant has no way to turn on the device it should be shown as `unavailable`, see [entity-unavailable Exceptions](/docs/core/integration-quality-scale/rules/entity-unavailable.md#Exceptions) for more details. +It is common that media players cannot be controlled while they are in standby. +• If Home Assistant can turn the device on via an alternative protocol or method, the entity should be reported as `OFF`, even if the main control channel is unavailable. +• If Home Assistant has no way to turn the device on, the entity should be reported as `unavailable`. +See the [entity-unavailable exceptions](/docs/core/integration-quality-scale/rules/entity-unavailable.md#exceptions) for more details. :::Changes:
- Split the long sentence into clear bullets.
- Expanded “can't” → “cannot” for a formal tone.
- Lower-cased the
#exceptionsanchor to match generated IDs.- Removed double space after “state”.
docs/core/entity.md (1)
72-78: Use “can” instead of “is able to” for concisenessAlso keeps wording consistent with the rest of the table.
-| available | `bool` | `True` | Indicate if Home Assistant is able to read the state or control the underlying device, see [entity-unavailable](/docs/core/integration-quality-scale/rules/entity-unavailable.md) for more details. +| available | `bool` | `True` | Indicate if Home Assistant can read the state or control the underlying device; see [entity-unavailable](/docs/core/integration-quality-scale/rules/entity-unavailable.md) for more details.docs/core/integration-quality-scale/rules/entity-unavailable.md (1)
84-91: Align state constants and tighten grammarConsistently use the exact enum strings (
OFF,ON) and polish the prose.-If an integration has a way to turn on a device, either via a user-defined automation trigger or by automatically creating a secondary control channel (e.g., using Wake On Lan or Infra-Red blaster) - then the device should be reported as `off` when it is in standby and unresponsive to the main channel (e.g., TCP). +If an integration can turn a device on—either through a user-defined automation trigger or a secondary control channel (e.g., Wake-on-LAN or IR blaster)—the device should be reported as `OFF` while it is in standby and the primary control channel (e.g., TCP) is unresponsive. @@ -- If the user configures an automation (e.g., using an IR blaster) to turn it on, the device will be shown as `off` while in standby. -- Once turned on via the external method, and the main connection is established, the state will update to `on`. +- If the user configures an automation (e.g., an IR blaster) to turn it on, the device will be shown as `OFF` while in standby. +- Once powered on via the external method and the main connection is established, the state will update to `ON`.Also capitalised “Wake-on-LAN” and removed the dash before then, which was breaking the sentence.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (3)
docs/core/entity.md(1 hunks)docs/core/entity/media-player.md(1 hunks)docs/core/integration-quality-scale/rules/entity-unavailable.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/core/entity.md
[style] ~76-~76: As a shorter alternative for ‘able to’, consider using “can”.
Context: ... | True | Indicate if Home Assistant is able to read the state or control the underlyin...
(BE_ABLE_TO)
Co-authored-by: Franck Nijhof <git@frenck.dev>
frenck
approved these changes
Jul 16, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Proposed change
Define when to show a device as off and when as unavailable in standby state.
Update developer documentation to reflect the accepted change from home-assistant/architecture#1251
This pull request updates the documentation to clarify the behavior of entities in Home Assistant when they are unavailable or in standby mode. It also introduces exceptions to the rules for handling unavailable entities, particularly for devices like media players that may require alternative methods to turn on. Below are the key changes grouped by theme:
Documentation Updates for Entity Behavior:
availableproperty indocs/core/entity.mdto specify that Home Assistant can read the state or control the device, with a reference to theentity-unavailablerules for more details.docs/core/entity/media-player.mdexplaining how media players should be represented when in standby or unavailable states, with a link to the exceptions in theentity-unavailablerules.New Exceptions for Unavailable Entities:
entity-unavailablerules indocs/core/integration-quality-scale/rules/entity-unavailable.mdto include scenarios where devices can be turned on using alternative methods, such as automations or secondary control channels. Provided an example for media players in standby mode.Type of change
Checklist
Additional information
Summary by CodeRabbit