Add device_id param documentation #5108
Open
+19
−0
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
## Walkthrough
The documentation for multiple ESPHome components was updated to include a new optional configuration variable, `device_id`. This variable allows specifying the identifier of a sub-device to which an entity belongs. If omitted, entities remain attached to the main ESP device. No changes were made to code, logic, or exported/public entity declarations.
## Changes
| Files | Change Summary |
|-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| components/binary_sensor/index.rst<br>components/button/index.rst<br>components/climate/index.rst<br>components/cover/index.rst<br>components/datetime/index.rst<br>components/esp32_camera.rst<br>components/event/index.rst<br>components/fan/index.rst<br>components/light/index.rst<br>components/lock/index.rst<br>components/media_player/index.rst<br>components/number/index.rst<br>components/select/index.rst<br>components/sensor/index.rst<br>components/switch/index.rst<br>components/text/index.rst<br>components/text_sensor/index.rst<br>components/update/index.rst<br>components/valve/index.rst | Added documentation for new optional configuration variable `device_id` to associate entities with sub-devices. No code or logic changes. |
## Suggested reviewers
- jesserockz📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (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 (
|
![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
♻️ Duplicate comments (4)
components/text/index.rst (1)
51-51: Same style-consistency issue as flagged earlier – apply the italicised*Optional*formatting here as well.components/datetime/index.rst (1)
51-51: Repeat of the*Optional*formatting mismatch noted for the cover docs.components/esp32_camera.rst (1)
45-45: Same bullet-list formatting nit: use(*Optional*, string)for consistency.components/text_sensor/index.rst (1)
50-50: Consistent with earlier comments: italiciseOptionalinside parentheses.
🧹 Nitpick comments (15)
components/cover/index.rst (1)
55-55: Use italicised*Optional*to stay consistent with surrounding bullet-list styleAll other optional items in this list format the keyword as
(*Optional*, …).
Keeping the same convention avoids visual inconsistency across docs.- - **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + - **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/valve/index.rst (1)
53-53: Keep style consistent & replace non-standard hyphenThe newly-added line deviates from the surrounding convention (
(*Optional*, …)) and includes a U+2011 non-breaking hyphen that can cause Sphinx warnings or awkward copy-pasting.- - **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + - **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/update/index.rst (1)
38-38: Match bullet formatting with the rest of the pageUse italics around “Optional” and swap the non-breaking hyphen for a normal hyphen.
- - **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + - **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/media_player/index.rst (1)
47-47: Follow existing parameter-list styleSame minor consistency issue as other files.
- - **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + - **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/switch/index.rst (1)
68-69: Tweak wording for consistency & fix typography- - **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + - **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/binary_sensor/index.rst (1)
78-80: Align with house style & remove non-breaking hyphen- Set to ``""`` to remove the default entity category. - - **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + Set to ``""`` to remove the default entity category. + - **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.(Space at end of previous line also trimmed to avoid trailing-whitespace warnings.)
components/climate/index.rst (1)
89-90: Align with existing “(Optional, …)” bullet styleThe new line drops the surrounding asterisks around Optional and uses a non-breaking hyphen in “sub-device”. Keep the same bullet syntax and a regular hyphen to stay consistent with the rest of the docs.
- **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/fan/index.rst (1)
58-59: Match bullet-point formatting with surrounding optionsUse the
(*Optional*, type)pattern and replace the non-breaking hyphen inside “sub-device”.- **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/lock/index.rst (1)
47-48: Stylistic consistency for new optionAll previous bullets italicise Optional. Update the new line and normalise the hyphen.
- **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/sensor/index.rst (1)
84-85: Format Optional like the other entriesKeep the option list uniform and swap the non-breaking hyphen.
- **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/button/index.rst (1)
60-61: Use the same optional-indicator styleOther bullets wrap Optional in asterisks—do the same here and replace the special hyphen.
- **device_id** (Optional, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device. + **device_id** (*Optional*, string): Identifier of the sub-device this entity belongs to. Must match the id of an entry in :ref:`esphome.devices <esphome-devices>`. If omitted, the entity remains attached to the main ESP device.components/light/index.rst (1)
94-95: Align bullet-point markup with surrounding styleThe surrounding list consistently formats the option qualifier as
(*Optional*, <type>), whereas the new bullet uses plain(Optional, string).
Keep the markup uniform for readability and to avoid Sphinx/reST style regressions.- - **device_id** (Optional, string): Identifier of the sub-device … + - **device_id** (*Optional*, string): Identifier of the sub-device …components/event/index.rst (1)
68-69: Use the same “Optional” inline markup as the other bulletsAll previous entries use italics for Optional. Update this line for consistency.
- - **device_id** (Optional, string): Identifier of the sub-device … + - **device_id** (*Optional*, string): Identifier of the sub-device …components/number/index.rst (1)
52-53: Restore consistent option-qualifier formattingStick to
(*Optional*, …)to match the rest of the list.- - **device_id** (Optional, string): Identifier of the sub-device … + - **device_id** (*Optional*, string): Identifier of the sub-device …components/select/index.rst (1)
52-53: Minor style fix – italicise “Optional”Same consistency issue as in the other files:
- - **device_id** (Optional, string): Identifier of the sub-device … + - **device_id** (*Optional*, string): Identifier of the sub-device …
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (19)
components/binary_sensor/index.rst(1 hunks)components/button/index.rst(1 hunks)components/climate/index.rst(1 hunks)components/cover/index.rst(1 hunks)components/datetime/index.rst(1 hunks)components/esp32_camera.rst(1 hunks)components/event/index.rst(1 hunks)components/fan/index.rst(1 hunks)components/light/index.rst(1 hunks)components/lock/index.rst(1 hunks)components/media_player/index.rst(1 hunks)components/number/index.rst(1 hunks)components/select/index.rst(1 hunks)components/sensor/index.rst(1 hunks)components/switch/index.rst(1 hunks)components/text/index.rst(1 hunks)components/text_sensor/index.rst(1 hunks)components/update/index.rst(1 hunks)components/valve/index.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
Instructions used from:
Sources:
⚙️ CodeRabbit Configuration File
🧠 Learnings (6)
📓 Common learnings
Learnt from: jesserockz
PR: esphome/esphome-docs#4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Learnt from: clydebarrow
PR: esphome/esphome-docs#0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.
Learnt from: realzoulou
PR: esphome/esphome-docs#4879
File: components/gps.rst:34-34
Timestamp: 2025-05-04T09:40:22.331Z
Learning: In ESPHome's GPS component, the `update_interval` parameter belongs to the `gps` component itself, not to individual sensors like `altitude`. It should be indented at the same level as the sensor configurations in the YAML.
Learnt from: jesserockz
PR: esphome/esphome-docs#4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.
components/datetime/index.rst (1)
Learnt from: realzoulou
PR: esphome/esphome-docs#4879
File: components/gps.rst:34-34
Timestamp: 2025-05-04T09:40:22.331Z
Learning: In ESPHome's GPS component, the `update_interval` parameter belongs to the `gps` component itself, not to individual sensors like `altitude`. It should be indented at the same level as the sensor configurations in the YAML.
components/switch/index.rst (1)
Learnt from: jesserockz
PR: esphome/esphome-docs#4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.
components/binary_sensor/index.rst (1)
Learnt from: jesserockz
PR: esphome/esphome-docs#4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.
components/sensor/index.rst (1)
Learnt from: realzoulou
PR: esphome/esphome-docs#4879
File: components/gps.rst:34-34
Timestamp: 2025-05-04T09:40:22.331Z
Learning: In ESPHome's GPS component, the `update_interval` parameter belongs to the `gps` component itself, not to individual sensors like `altitude`. It should be indented at the same level as the sensor configurations in the YAML.
components/update/index.rst (1)
Learnt from: realzoulou
PR: esphome/esphome-docs#4879
File: components/gps.rst:34-34
Timestamp: 2025-05-04T09:40:22.331Z
Learning: In ESPHome's GPS component, the `update_interval` parameter belongs to the `gps` component itself, not to individual sensors like `altitude`. It should be indented at the same level as the sensor configurations in the YAML.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This comment was marked as off-topic.
This comment was marked as off-topic.
Sorry, something went wrong.
jesserockz
requested changes
Jul 17, 2025
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Co-authored-by: Jesse Hills <[email protected]>
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.
Description:
I noticed that we added documentation for esphome.devices and esphome.areas, but we did not add documentation for the device_id parameter that can be used on the entity.
This PR updates every entity-platform page to document the new optional device_id key for sub-device support. Up to now, the feature was only mentioned on the central Sub-Devices page; individual entity docs still lacked any reference to it.
Users reading an entity page now immediately see that sub-devices are supported and how to enable them for entities.
Every platform follows the same wording and link target, reducing confusion and copy-paste errors.
Follow up: #4813
CC: @dala318
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.