From b9bef83a41500a682dcb6ef3bf483d89d214ea67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Vikstr=C3=B6m?= <daniel@vikstrom.name>
Date: Thu, 10 Apr 2025 10:24:29 +0200
Subject: [PATCH 1/2] Add a basic instruction

---
 components/devices.rst | 59 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 components/devices.rst

diff --git a/components/devices.rst b/components/devices.rst
new file mode 100644
index 0000000000..115327b7f9
--- /dev/null
+++ b/components/devices.rst
@@ -0,0 +1,59 @@
+Sub Device Configuration
+========================
+
+.. seo::
+    :description: Instructions for setting up sub devices in ESPHome.
+    :image: folder-open.svg
+
+ESPHome has support for createting sub devices in configuration where
+individual entities can be grouped to. The grouping has no direct effect
+on the functionality of the entities, but it can be used to group
+entities together in the Home Assistant UI. This is useful for
+example when you have a mix sensors on one device that are related to
+different physical devices.
+
+.. note::
+
+    Requires Home Assistant 2025.x or newer.
+
+Base Sub Device Configuration
+-----------------------------
+
+All devices in ESPHome have an id and name, and an optional suggested area.
+
+.. code-block:: yaml
+
+    # Example devices configuration
+    id: my_device
+    name: My Device
+
+    # Optional variables:
+    area: Living Room
+
+Configuration variables:
+
+- **id** (**Required**, string): Specify the ID for code generation.
+- **name** (**Required**, string): The name for the sub device.
+- **area** (*Optional*, string): The suggested area for the sub device.
+
+Assign entity to sub device
+---------------------------
+
+For individual entities in your configuration, you can assign them to a
+sub device by using the ``device_id`` option. This is done by adding
+the ``device_id`` option to the entity configuration. The value should
+be the ID of the sub device you want to assign the entity to.
+
+.. code-block:: yaml
+
+    sensor:
+      - platform: template
+        # ...
+        device_id: my_device
+
+
+See Also
+--------
+
+- :doc:`esphome`
+- :ghedit:`Edit`

From 2f52f2007c59513e1eac907512db5c5b0ca8f6f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Vikstr=C3=B6m?= <daniel@vikstrom.name>
Date: Thu, 10 Apr 2025 12:24:26 +0200
Subject: [PATCH 2/2] Add to index

---
 components/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/components/index.rst b/components/index.rst
index 9e29e590fb..24515b71af 100644
--- a/components/index.rst
+++ b/components/index.rst
@@ -65,6 +65,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning
     JSON, components/json, json.svg, dark-invert
     XXTEA, components/xxtea, xxtea.svg
     Script, components/script, description.svg, dark-invert
+    Sub Devices, components/devices, home-assistant.svg, dark-invert
 
 ESPHome Configuration
 ---------------------