[API] Sub devices and areas #1146
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1146 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 2936 2965 +29
=========================================
+ Hits 2936 2965 +29 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
CodSpeed Performance ReportMerging #1146 will not alter performanceComparing Summary
|
|
Caution Review failedThe pull request is closed. """ WalkthroughThe changes introduce new protocol buffer message types for area and device metadata, add a device association field to various entity response messages, and extend the Python model layer to support sub-device information and device-entity associations. New tests verify correct conversion of area and sub-device lists and handling of area fields within device info structures. Changes
Sequence Diagram(s)sequenceDiagram
participant APIClient
participant ESPHomeDevice
participant HomeAssistant
APIClient->>ESPHomeDevice: Request DeviceInfoResponse
ESPHomeDevice-->>APIClient: DeviceInfoResponse (devices, areas, area, ...)
APIClient->>HomeAssistant: Register devices and areas
loop For each entity type
APIClient->>ESPHomeDevice: Request ListEntities<Type>Response
ESPHomeDevice-->>APIClient: ListEntities<Type>Response (device_id, ...)
APIClient->>HomeAssistant: Associate entity with device via device_id
end
Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes found. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
✨ Finishing Touches
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
🧹 Nitpick comments (2)
aioesphomeapi/model.py (1)
220-221: Consider implementing device_id at the EntityInfo base class level.The commented-out code suggests a plan to add device_id to the base EntityInfo class. This would be a more maintainable approach than adding it to each entity type individually.
- # # Is it ok to ad for the generic device info before all are added? - # device_id: str = "" + device_id: str = ""Since this is marked as a comment/question, please clarify if there's a specific reason to delay adding this field to the base class. Adding it now would simplify future implementations across all entity types.
aioesphomeapi/api.proto (1)
387-387: Consider implementing device_id for all entity types consistently.Many entity types have commented-out device_id fields. Consider whether these should be implemented now for consistency, or if there's a specific reason to add them incrementally.
A phased approach is reasonable, but ensure there's a clear plan for adding support to all entity types in subsequent PRs. Document this plan if there are specific prerequisites or dependencies that would benefit from a staged implementation.
Also applies to: 456-457, 546-547, 577-578, 613-614, 777-778, 879-880, 961-962, 1000-1001, 1100-1101, 1136-1137, 1192-1193, 1690-1691, 1734-1735, 1773-1774, 1815-1816, 1860-1861, 1890-1891, 1935-1936, 1974-1975
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.github/workflows/ci.yml(1 hunks)aioesphomeapi/api.proto(24 hunks)aioesphomeapi/model.py(5 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
aioesphomeapi/model.pyaioesphomeapi/api.proto
🪛 GitHub Check: codecov/patch
aioesphomeapi/model.py
[warning] 145-146: aioesphomeapi/model.py#L145-L146
Added lines #L145 - L146 were not covered by tests
[warning] 148-148: aioesphomeapi/model.py#L148
Added line #L148 was not covered by tests
🔇 Additional comments (9)
.github/workflows/ci.yml (1)
125-131: Improved error handling output for protobuf file differences.The added echo statements enhance developer experience by providing clearer debugging information when generated protobuf files differ from expected versions.
aioesphomeapi/model.py (4)
172-174: Added sub_devices list to DeviceInfo class.This addition enables the representation of multiple virtual devices within a single physical device, which aligns well with the PR objectives.
234-234: Added device_id to BinarySensorInfo.This enables linking binary sensors to specific sub-devices.
251-251: Added device_id to CoverInfo.This enables linking covers to specific sub-devices.
136-150:❓ Verification inconclusive
New SubDeviceInfo class added to support virtual device grouping.
This class implements the data model for sub-devices with identification, name, and location information. Good implementation of the convert_list method for handling different input formats.
🏁 Script executed:
#!/bin/bash # Check if there are any unit tests for the new SubDeviceInfo class echo "Checking for unit tests covering SubDeviceInfo class..." rg "SubDeviceInfo" tests/Length of output: 146
Attention: Confirm Unit Test Coverage for SubDeviceInfo Class
The implementation of the new
SubDeviceInfoclass—with its clear data model and the robustconvert_listmethod handling both dictionary and protobuf inputs—is well done. However, our search in the tests directory did not locate any unit tests for this class. Please manually verify whether tests exist in another location or consider adding unit tests to cover its functionality (especially for bothfrom_dictandfrom_pbconversion paths).🧰 Tools
🪛 GitHub Check: codecov/patch
[warning] 145-146: aioesphomeapi/model.py#L145-L146
Added lines #L145 - L146 were not covered by tests
[warning] 148-148: aioesphomeapi/model.py#L148
Added line #L148 was not covered by testsaioesphomeapi/api.proto (4)
185-189: New SubDeviceInfo message type added.This protocol buffer message provides the structure for transmitting sub-device information with fields for id, name, and suggested_area.
237-237: Added sub_devices field to DeviceInfoResponse message.This allows the API to report multiple sub-devices associated with a single physical device.
281-281: Implemented device_id field for binary sensors and covers.These are the first entity types to fully implement the sub-device association. This implementation correctly links these entity types to the new sub-device structure.
Also applies to: 315-315
1-2007:❓ Verification inconclusive
Verify compatibility with the linked esphome repository PR.
The PR objectives mention a linked PR to the main esphome repository (esphome/esphome#8544). Ensure these API changes are compatible with the changes in that PR.
🌐 Web query:
What's the current status of esphome/esphome PR #8544?💡 Result:
The current search results do not provide specific information about the status of esphome/esphome PR #8544. The latest mentions in the provided data refer to releases up to 2025.3.3 and changes in 2024.8.x, but no details about PR #8544 are included.
For the most accurate and up-to-date status, you would need to check the esphome/esphome GitHub repository directly. The provided results do not indicate whether this PR has been merged, closed, or is still under review[3][6].
Citations:
- 1: https://esphome.io/changelog/v1.15.0.html
- 2: https://static.xtremeownage.com/blog/2023/pioneer-mini-split-esphome/
- 3: https://github.com/esphome/esphome/releases
- 4: https://www.sudo.is/docs/esphome/boards/esp32nodemcu/
- 5: https://esphome.io/components/sensor/index.html
- 6: https://esphome.io/changelog/2024.8.0.html
- 7: https://www.sudo.is/docs/esphome/boards/esp8266d1mini/
- 8: https://www.sudo.is/docs/esphome/components/pcd8544/
- 9: https://esphome.io/guides/faq.html
- 10: https://esphome.io/components/
Action: Manually verify compatibility with esphome/esphome#8544
The API changes in this file (aioesphomeapi/api.proto, lines 1–2007) should be checked against the upstream modifications introduced in esphome/esphome PR #8544. Currently, web searches did not return specific status details for that PR. Please ensure that:
- The updated service definitions and RPC options are fully aligned with the upstream changes.
- Any removed or replaced code in this API file is compatible with the handling in [API] Sub devices and areas esphome#8544.
- You cross-check the most recent state of the upstream PR directly on GitHub to confirm compatibility.
🧰 Tools
🪛 Buf (1.47.2)
3-3: import "api_options.proto": file does not exist
(COMPILE)
bdraco
added
the
waiting-for-esphome
Enable the rest of entities
This reverts commit c67a390.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
.github/workflows/ci.yml (1)
127-135: Fix typo in artifact name.There's a typo in the artifact name that should be corrected.
- name: genrated-proto-files + name: generated-proto-filesaioesphomeapi/api.proto (2)
191-195: Add newSubDeviceInfomessage
TheSubDeviceInfomessage cleanly encapsulates UID, name, and suggested area for sub-devices. To improve maintainability, consider adding a brief proto-doc comment above the message to explain the intended use of each field.
246-247: Embed sub-device list intoDeviceInfoResponse
Great addition ofrepeated SubDeviceInfo sub_devices = 20;to enable virtual device grouping. Please verify that your Python client’smodel.pyand accompanying tests have been updated to deserialize this new field correctly.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.github/workflows/ci.yml(1 hunks)aioesphomeapi/api.proto(24 hunks)aioesphomeapi/model.py(3 hunks)tests/test_model.py(3 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
tests/test_model.pyaioesphomeapi/model.pyaioesphomeapi/api.proto
🔇 Additional comments (25)
.github/workflows/ci.yml (1)
127-135: Good addition for debugging protobuf mismatches!These debugging steps will help identify the exact differences when protobuf files don't match the expected output, making it easier to resolve CI failures.
aioesphomeapi/model.py (1)
137-152: Well-implemented sub-device support!The implementation correctly adds sub-device support with:
- A proper
SubDeviceInfoclass with appropriate fields and conversion logic- Clean integration into
DeviceInfousing converter fields- Addition of
device_uidtoEntityInfofor device-entity linkageThe code follows the existing patterns in the codebase and handles both dictionary and protobuf conversions appropriately.
Also applies to: 174-176, 222-222
tests/test_model.py (1)
702-739: Comprehensive test coverage for SubDeviceInfo conversion!The test properly validates the list conversion functionality by:
- Testing mixed input types (both SubDeviceInfo objects and dictionaries)
- Verifying correct conversion to SubDeviceInfoModel instances
- Following the established testing patterns in the file
Good test coverage for the new feature.
aioesphomeapi/api.proto (22)
290-291: Exposedevice_uidin binary sensor listing
Addinguint32 device_uid = 10;toListEntitiesBinarySensorResponsemakes it possible to map sensors back to their parent devices. This is an additive change and non-breaking.
324-325: Exposedevice_uidin cover listing
The newdevice_uidfield here will let clients associate covers with sub-devices correctly. Field number 13 aligns sequentially.
396-397: Exposedevice_uidin fan listing
Inclusion ofuint32 device_uid = 13;is consistent with other entity messages and non-breaking.
478-479: Exposedevice_uidin light listing
Thedevice_uid = 16;field integrates seamlessly. Good to see uniform support across all entity types.
569-570: Exposedevice_uidin sensor listing
uint32 device_uid = 14;is correctly placed and aids in entity-to-device resolution.
600-601: Exposedevice_uidin switch listing
device_uid = 10;followsdevice_class—this will streamline device lookups.
636-637: Exposedevice_uidin text sensor listing
Withuint32 device_uid = 9;, clients can now map text sensors accurately.
817-818: Exposedevice_uidin camera listing
Thedevice_uid = 8;field is a logical extension to link camera entities to their sub-device.
919-920: Exposedevice_uidin climate listing
Addinguint32 device_uid = 26;completes the pattern for climate entities.
1001-1002: Exposedevice_uidin number listing
uint32 device_uid = 14;is added correctly, enabling number entities to reference their device.
1040-1041: Exposedevice_uidin select listing
Fielddevice_uid = 9;is in place and non-breaking.
1142-1143: Exposedevice_uidin lock listing
uint32 device_uid = 12;will help clients identify which lock belongs to which sub-device.
1180-1181: Exposedevice_uidin button listing
Inclusion ofdevice_uid = 9;for buttons is consistent with the new feature scope.
1236-1237: Exposedevice_uidin media player listing
uint32 device_uid = 10;aligns with other list responses.
1774-1775: Exposedevice_uidin alarm control panel listing
Great—device_uid = 11;will link alarms back to the correct device.
1818-1819: Exposedevice_uidin text listing
uint32 device_uid = 12;extends device mapping to generic text entities.
1857-1858: Exposedevice_uidin date listing
device_uid = 8;is now available for date pickers.
1899-1900: Exposedevice_uidin time listing
Addinguint32 device_uid = 8;ensures consistency across datetime entities.
1944-1945: Exposedevice_uidin event listing
device_uid = 10;looks correct and is non-breaking.
1974-1975: Exposedevice_uidin valve listing
uint32 device_uid = 12;completes entity-to-device linkage for valves.
2019-2020: Exposedevice_uidin datetime listing
device_uid = 8;is properly placed for DateTime entities.
2058-2059: Exposedevice_uidin update listing
Addinguint32 device_uid = 9;extends sub-device support to update entities as well.
|
merged the new api.proto, but we really should fix #1218 before we do a new release |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
aioesphomeapi/api.proto (2)
251-253: Extend DeviceInfoResponse with devices, areas, and top-level area
Addingrepeated DeviceInfo devices,repeated AreaInfo areas, and the singularAreaInfo areaaligns with the sub-device grouping feature.Consider marking the legacy
suggested_area = 16as deprecated ([deprecated = true]) to guide clients toward the newareafield and prevent silent drift.Also applies to: 255-255
300-300: Add device_id to ListEntities responses
EachListEntities…Responsenow includes auint32 device_idfield at the end to associate entities with their physical device. Field numbers correctly follow existing sequences with no collisions.Don’t forget to regenerate all language bindings (Python models, stubs) and update the public API documentation/changelog to surface these new fields to integrators.
Also applies to: 336-336, 410-410, 494-494, 587-587, 621-621, 659-659, 842-842, 945-945, 1029-1029, 1070-1070, 1113-1113, 1177-1177, 1217-1217, 1273-1273, 1815-1815, 1901-1901, 1946-1946, 1993-1993, 2025-2025, 2072-2072, 2113-2113
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
aioesphomeapi/api.proto(25 hunks)aioesphomeapi/model.py(3 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- aioesphomeapi/model.py
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
aioesphomeapi/api.proto
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Run benchmarks
🔇 Additional comments (2)
aioesphomeapi/api.proto (2)
191-194: Define new AreaInfo for grouping sub-devices
TheAreaInfomessage cleanly encapsulates an area’s ID and name. Field numbers are sequenced correctly.
196-200: Define new DeviceInfo for grouping metadata
TheDeviceInfomessage correctly associates adevice_idwith its name and parentarea_id. Numbering is consistent and non-conflicting.
bdraco
added
minor
and removed
waiting-for-esphome
What does this implement/fix?
Adds the possibility to group entities on one physical device into virtual devices (in Home Assistant), handy when one ESP serves several purposes.
Read more in related ESP Home PR
Types of changes
Related issue or feature (if applicable):
Pull request in esphome (if applicable):
Checklist:
tests/folder).