Add ability to have same entity names on different sub devices (#9355)

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

esphome/components/api/api_connection.cpp

@@ -42,18 +42,37 @@ static const char *const TAG = "api.connection";
 static const int CAMERA_STOP_STREAM = 5000;
 #endif
 
-// Helper macro for entity command handlers - gets entity by key, returns if not found, and creates call object
+#ifdef USE_DEVICES
+// Helper macro for entity command handlers - gets entity by key and device_id, returns if not found, and creates call
+// object
+#define ENTITY_COMMAND_MAKE_CALL(entity_type, entity_var, getter_name) \
+  entity_type *entity_var = App.get_##getter_name##_by_key(msg.key, msg.device_id); \
+  if ((entity_var) == nullptr) \
+    return; \
+  auto call = (entity_var)->make_call();
+
+// Helper macro for entity command handlers that don't use make_call() - gets entity by key and device_id and returns if
+// not found
+#define ENTITY_COMMAND_GET(entity_type, entity_var, getter_name) \
+  entity_type *entity_var = App.get_##getter_name##_by_key(msg.key, msg.device_id); \
+  if ((entity_var) == nullptr) \
+    return;
+#else  // No device support, use simpler macros
+// Helper macro for entity command handlers - gets entity by key, returns if not found, and creates call
+// object
 #define ENTITY_COMMAND_MAKE_CALL(entity_type, entity_var, getter_name) \
   entity_type *entity_var = App.get_##getter_name##_by_key(msg.key); \
   if ((entity_var) == nullptr) \
     return; \
   auto call = (entity_var)->make_call();
 
-// Helper macro for entity command handlers that don't use make_call() - gets entity by key and returns if not found
+// Helper macro for entity command handlers that don't use make_call() - gets entity by key and returns if
+// not found
 #define ENTITY_COMMAND_GET(entity_type, entity_var, getter_name) \
   entity_type *entity_var = App.get_##getter_name##_by_key(msg.key); \
   if ((entity_var) == nullptr) \
     return;
+#endif  // USE_DEVICES
 
 APIConnection::APIConnection(std::unique_ptr<socket::Socket> sock, APIServer *parent)
     : parent_(parent), initial_state_iterator_(this), list_entities_iterator_(this) {

esphome/core/application.h

@@ -368,8 +368,19 @@ class Application {
 
   uint8_t get_app_state() const { return this->app_state_; }
 
-// Helper macro for entity getter method declarations - reduces code duplication
-// When USE_DEVICE_ID is enabled in the future, this can be conditionally compiled to add device_id parameter
+// Helper macro for entity getter method declarations
+#ifdef USE_DEVICES
+#define GET_ENTITY_METHOD(entity_type, entity_name, entities_member) \
+  entity_type *get_##entity_name##_by_key(uint32_t key, uint32_t device_id, bool include_internal = false) { \
+    for (auto *obj : this->entities_member##_) { \
+      if (obj->get_object_id_hash() == key && obj->get_device_id() == device_id && \
+          (include_internal || !obj->is_internal())) \
+        return obj; \
+    } \
+    return nullptr; \
+  }
+  const std::vector<Device *> &get_devices() { return this->devices_; }
+#else
 #define GET_ENTITY_METHOD(entity_type, entity_name, entities_member) \
   entity_type *get_##entity_name##_by_key(uint32_t key, bool include_internal = false) { \
     for (auto *obj : this->entities_member##_) { \
@@ -378,10 +389,7 @@ class Application {
     } \
     return nullptr; \
   }
-
-#ifdef USE_DEVICES
-  const std::vector<Device *> &get_devices() { return this->devices_; }
-#endif
+#endif  // USE_DEVICES
 #ifdef USE_AREAS
   const std::vector<Area *> &get_areas() { return this->areas_; }
 #endif

esphome/core/entity_helpers.py

@@ -198,9 +198,12 @@ def entity_duplicate_validator(platform: str) -> Callable[[ConfigType], ConfigTy
 
         # Get device name if entity is on a sub-device
         device_name = None
+        device_id = ""  # Empty string for main device
         if CONF_DEVICE_ID in config:
             device_id_obj = config[CONF_DEVICE_ID]
             device_name = device_id_obj.id
+            # Use the device ID string directly for uniqueness
+            device_id = device_id_obj.id
 
         # Calculate what object_id will actually be used
         # This handles empty names correctly by using device/friendly names
@@ -209,11 +212,12 @@ def entity_duplicate_validator(platform: str) -> Callable[[ConfigType], ConfigTy
         )
 
         # Check for duplicates
-        unique_key = (platform, name_key)
+        unique_key = (device_id, platform, name_key)
         if unique_key in CORE.unique_ids:
+            device_prefix = f" on device '{device_id}'" if device_id else ""
             raise cv.Invalid(
-                f"Duplicate {platform} entity with name '{entity_name}' found. "
-                f"Each entity must have a unique name within its platform across all devices."
+                f"Duplicate {platform} entity with name '{entity_name}' found{device_prefix}. "
+                f"Each entity on a device must have a unique name within its platform."
             )
 
         # Add to tracking set