Clarify entity naming (#1437)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Erik Montnemery 2022-08-18 17:16:41 +02:00 committed by GitHub
parent ecafe79075
commit ee769c7d60
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -8,6 +8,10 @@ For a generic introduction of entities, see [entities architecture](../architect
## Basic implementation ## Basic implementation
Below is an example switch entity that keeps track of its state in memory. Below is an example switch entity that keeps track of its state in memory.
In addition, the switch in the example represents the main feature of a device,
meaning the entity has the same name as its device.
Please refer to [Entity naming](#entity-naming) for how to give an entity its own name.
```python ```python
from homeassistant.components.switch import SwitchEntity from homeassistant.components.switch import SwitchEntity
@ -18,11 +22,8 @@ class MySwitch(SwitchEntity):
def __init__(self): def __init__(self):
self._is_on = False self._is_on = False
self._attr_device_info = ... # For automatic device registration
@property self._attr_unique_id = ...
def name(self):
"""Name of the entity."""
return "My Switch"
@property @property
def is_on(self): def is_on(self):
@ -68,6 +69,7 @@ Properties should always only return information from memory and not do I/O (lik
| attribution | string | `None` | The branding text required by the API provider. | | attribution | string | `None` | The branding text required by the API provider. |
| available | boolean | `True` | Indicate if Home Assistant is able to read the state and control the underlying device. | | available | boolean | `True` | Indicate if Home Assistant is able to read the state and control the underlying device. |
| device_class | string | `None` | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. | | device_class | string | `None` | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. |
| device_info | dict | `None` | [Device registry](/docs/device_registry_index) descriptor for [automatic device registration.](/docs/device_registry_index#automatic-registration-through-an-entity)
| entity_category | string | `None` | Classification of a non-primary entity. Set to `config` for an entity which allows changing the configuration of a device, for example a switch entity making it possible to turn the background illumination of a switch on and off. Set to `diagnostic` for an entity exposing some configuration parameter or diagnostics of a device but does not allow changing it, for example a sensor showing RSSI or MAC-address. | | entity_category | string | `None` | Classification of a non-primary entity. Set to `config` for an entity which allows changing the configuration of a device, for example a switch entity making it possible to turn the background illumination of a switch on and off. Set to `diagnostic` for an entity exposing some configuration parameter or diagnostics of a device but does not allow changing it, for example a sensor showing RSSI or MAC-address. |
| entity_picture | URL | `None` | Url of a picture to show for the entity. | | entity_picture | URL | `None` | Url of a picture to show for the entity. |
| extra_state_attributes | dict | `None` | Extra information to store in the state machine. It needs to be information that further explains the state, it should not be static information like firmware version. | | extra_state_attributes | dict | `None` | Extra information to store in the state machine. It needs to be information that further explains the state, it should not be static information like firmware version. |
@ -105,7 +107,8 @@ The following properties are used and controlled by Home Assistant, and should n
The entity's name property only identifies the data point represented by the entity, and should not include the name of the device or the type of the entity. So for a sensor that represents the power usage of its device, this would be “Power usage”. The entity's name property only identifies the data point represented by the entity, and should not include the name of the device or the type of the entity. So for a sensor that represents the power usage of its device, this would be “Power usage”.
The main entity of a device may have its name property return `None`. If the entity represents a single main feature of a device the entity should typically have its name property return `None`.
The "main feature" of a device would for example be the `LightEntity` of a smart light bulb.
The `friendly_name` state attribute is generated by combining then entity name with the device name as follows: The `friendly_name` state attribute is generated by combining then entity name with the device name as follows:
- The entity is not a member of a device: `friendly_name = entity.name` - The entity is not a member of a device: `friendly_name = entity.name`
@ -114,6 +117,44 @@ The `friendly_name` state attribute is generated by combining then entity name w
Entity names should start with a capital letter, the rest of the words are lower case (unless it's a proper noun or a capitalized abbreviation of course). Entity names should start with a capital letter, the rest of the words are lower case (unless it's a proper noun or a capitalized abbreviation of course).
#### Example of a switch entity which is the main feature of a device
*Note: The example is using class attributes to implement properties, for other ways
to implement properties see [Property implementation.](#property-implementation)*
*Note: The example is incomplete, the `unique_id` property must be implemented, and the entity
must be [registered with a device.](/docs/device_registry_index#defining-devices)
```python
from homeassistant.components.switch import SwitchEntity
class MySwitch(SwitchEntity):
_attr_has_entity_name = True
_attr_name = None
```
#### Example of a switch entity which is either not the main feature of a device, or is not part of a device:
*Note: The example is using class attributes to implement properties, for other ways*
*to implement properties see [Property implementation.](#property-implementation)*
*Note: If the entity is part of a device, the `unique_id` property must be implemented, and the entity
must be [registered with a device.](/docs/device_registry_index#defining-devices)
```python
from homeassistant.components.switch import SwitchEntity
class MySwitch(SwitchEntity):
_attr_has_entity_name = True
@property
def name(self):
"""Name of the entity."""
return "My Switch"
```
### `has_entity_name` not implemented or False (Deprecated) ### `has_entity_name` not implemented or False (Deprecated)
The entity's name property may be a combination of the device name and the data point represented by the entity. The entity's name property may be a combination of the device name and the data point represented by the entity.