From 16b8a628e57da9cee9b2367a4cd69cb16e709772 Mon Sep 17 00:00:00 2001 From: Maciej Bieniek Date: Mon, 26 May 2025 11:05:44 +0200 Subject: [PATCH] Update entity naming convention for Shelly (#39091) --- source/_integrations/shelly.markdown | 59 +++++++++++++++++++++------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index adc9086cf9a..6fc908c3505 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -131,23 +131,26 @@ Currently, only static IP or DHCP reserved IP are supported for the main device. ## Entity naming (generation 1) -The integration uses `Device Name` to name its entities if the device has only one relay or no relays at all. +The integration uses the following strategy to name its devices and entities if the device has only one relay (channel) or no relays at all: -The integration uses the following strategy to name its entities if the device has more than one relay: +- If a `Device Name` is set in the device, the integration will use it to generate the device name and entity names. +- If a `Device Name` is not set, the integration will use the `Device ID` to generate the device name and entity names. -- If `Device Name` or `Channel Name` is set in the device, the integration will use them to generate the entities' name. -- If channel names are set, they will be used in the entity names. The device name will not be used. -- If only the device name is set, and the device has multiple channels, the channel number will be appended to the entity name (e.g., Channel 2). -- In case device name and channel names are not set, the entity name will be generated by the `Device Type`, `Device ID` and `Channel Number`. +The integration creates a sub-device for every relay and uses the following strategy to name its entities if the device has more than one relay: + +- If a `Device Name` is set in the device, the integration will use it to generate the main device name and entity names assigned to the main device. +- If a `Device Name` is not set, the integration will use the `Device ID` to generate the main device name and entity names assigned to the main device. +- If a `Channel Name` is set in the device, the integration will use it to generate the sub-device name and entity names assigned to this sub-device (channel/relay). +- If a `Channel Name` is not set in the device, the integration will use the device name and channel/relay number to generate the sub-device name and entity names assigned to this sub-device (channel/relay). Examples: -| Device Name | Channel Name | Entity Name | -| ----------- | -------------- | ------------------------------- | -| `Not set` | `Not Set` | shellyswitch25-ABC123 Channel 1 | -| `Not set` | Kids Room Bulb | Kids Room Bulb | -| Kitchen | `Not Set` | Kitchen Channel 1 | -| Bedroom | Round Bulb | Round Bulb | +| Device Name | Channel Name | Main Device Name | Sub-device Name | Entity Name | +| ----------- | -------------- | --------------------- | ------------------------------- | -------------------------------- | +| `Not set` | `Not Set` | shellyswitch25-ABC123 | shellyswitch25-ABC123 Channel 1 | shellyswitch25-ABC123 Channel 1 | +| `Not set` | Kids Room Bulb | shellyswitch25-ABC123 | Kids Room Bulb | Kids Room Bulb | +| Kitchen | `Not Set` | Kitchen | Kitchen Channel 1 | Kitchen Channel 1 | +| Bedroom | Round Bulb | Bedroom | Round Bulb | Round Bulb | Names are set from the device web page: @@ -157,10 +160,36 @@ Names are set from the device web page: ## Entity naming (generation 2+) -The integration uses the following strategy to name its entities: +The integration uses the following strategy to name its devices and entities if the device has only one relay (channel) or no relays at all: -- If `Channel Name` is set in the device, the integration will use it to generate the entities' name, e.g. `Kitchen Light` -- If `Channel Name` is set to the default value, the integration will use the `Device ID` and default channel name to generate the entities' name, e.g. `ShellyPro4PM-9808D1D8B912 Switch 0`. +- If a `Device Name` is set in the device, the integration will use it to generate the device name and entity names. +- If a `Device Name` is not set, the integration will use the `Device ID` to generate the device name and entity names. +- If a `Channel Name` is set in the device, the integration will add it as a suffix to the entity names. + +Examples: + +| Device Name | Channel Name | Integration Device Name | Entity Name | +| ----------- | -------------- | ------------------------ | --------------------------------------- | +| `Not set` | `Not Set` | shelly1gen3-aabbccddeeff | shelly1gen3-aabbccddeeff | +| `Not set` | Kids Room Bulb | shelly1gen3-aabbccddeeff | shelly1gen3-aabbccddeeff Kids Room Bulb | +| Kitchen | `Not Set` | Kitchen | Kitchen | +| Bedroom | Round Bulb | Bedroom | Bedroom Round Bulb | + +The integration creates a sub-device for every relay (channel) and uses the following strategy to name its devices and entities if the device has more than one relay: + +- If a `Device Name` is set in the device, the integration will use it to generate the main device name and entity names assigned to the main device. +- If a `Device Name` is not set, the integration will use the `Device ID` to generate the main device name and entity names assigned to the main device. +- If a `Channel Name` is set in the device, the integration will use it to generate the sub-device name and entity names assigned to this sub-device (channel/relay). +- If a `Channel Name` is set to the default value in the device, the integration will use the device name and this ddefault channel name to generate the sub-device name and entity names assigned to this sub-device (channel/relay). + +Examples: + +| Device Name | Channel Name | Main Device Name | Sub-device Name | Entity Name | +| ----------- | -------------- | -------------------------- | ----------------------------------- | ----------------------------------- | +| `Not set` | `Not Set` | shelly2pmgen3-aabbccddeeff | shelly2pmgen3-aabbccddeeff Switch 1 | shelly2pmgen3-aabbccddeeff Switch 1 | +| `Not set` | Kids Room Bulb | shelly2pmgen3-aabbccddeeff | Kids Room Bulb | Kids Room Bulb | +| Kitchen | `Not Set` | Kitchen | Kitchen Switch 1 | Kitchen Switch 1 | +| Bedroom | Round Bulb | Bedroom | Round Bulb | Round Bulb | ## Cover entities