From 47d91ccbe9c17d3f90dd81f68a095344170f71e5 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Tue, 1 Aug 2023 09:19:18 -1000
Subject: [PATCH] Document friendly and legacy rules in ESPHome (#28396)

Co-authored-by: Franck Nijhof <git@frenck.dev>
---
 source/_integrations/esphome.markdown | 43 +++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/source/_integrations/esphome.markdown b/source/_integrations/esphome.markdown
index 864956d51b1..d495ab855a1 100644
--- a/source/_integrations/esphome.markdown
+++ b/source/_integrations/esphome.markdown
@@ -47,3 +47,46 @@ This integration allows [ESPHome](https://esphome.io) devices to connect directl
 ESPHome devices can make service calls to any [Home Assistant service](https://esphome.io/components/api.html#homeassistant-service-action). This functionality is not enabled by default for newly configured device, but can be turned on the options flow on a per device basis.
 
 {% include integrations/option_flow.md %}
+
+## Entity naming and IDs
+
+ESPHome uses different naming and entity ID rules based on the configuration of the ESPHome device. It is recommended to set a `friendly_name` in the ESPHome `configuration.yaml` to take advantage of the newer naming structure, which is consistent with Home Assistant naming standards and makes it much easier to tell similar devices apart. The legacy naming rules apply when the `friendly_name` is not set in the `configuration.yaml`.
+
+### Friendly naming
+
+- Entity name is a combination of the friendly name and component name
+- Device name is prepended to the entity ID
+- Entity ID uses the ESPHome ID
+
+Example:
+
+```yaml
+esphome:
+   name: "livingroomdesk"
+   friendly_name: "Living room desk"
+
+sensor:
+   name: "Temperature"
+   id: "temperature"
+```
+
+The entity will be named `Living room desk Temperature` and will default to having an entity ID of `sensor.livingroomdesk_temperature`.
+
+### Legacy naming
+
+- Entity name is the component name
+- Device name is not prepended to the entity name
+- Entity ID is derived solely from the entity name
+
+Example:
+
+```yaml
+esphome:
+   name: "livingroomdesk"
+
+sensor:
+   name: "Temperature"
+   id: "temperature"
+```
+
+The entity will be named `Temperature` and will default to having an entity_id of `sensor.temperature`.