jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-15 13:26:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update entity naming convention for Shelly (#39091)

Browse Source
This commit is contained in:
Maciej Bieniek 2025-05-26 11:05:44 +02:00 committed by GitHub
parent 4bb58717b2
commit 16b8a628e5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 44 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
source/_integrations/shelly.markdown
View File

@ -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