From ac5172cd366652f72ba8a2fbf988d92053f03b0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20Arnauts?= Date: Mon, 3 Aug 2020 16:46:58 +0200 Subject: [PATCH] Add documentation for unique_id on template platforms (#14052) Co-authored-by: Franck Nijhof --- .../alarm_control_panel.template.markdown | 4 ++++ source/_integrations/binary_sensor.template.markdown | 4 ++++ source/_integrations/cover.template.markdown | 4 ++++ source/_integrations/fan.template.markdown | 4 ++++ source/_integrations/light.template.markdown | 4 ++++ source/_integrations/lock.template.markdown | 4 ++++ source/_integrations/switch.template.markdown | 4 ++++ source/_integrations/template.markdown | 10 +++++++++- source/_integrations/vacuum.template.markdown | 4 ++++ 9 files changed, 41 insertions(+), 1 deletion(-) diff --git a/source/_integrations/alarm_control_panel.template.markdown b/source/_integrations/alarm_control_panel.template.markdown index ebaa5efcad6..4789b200013 100644 --- a/source/_integrations/alarm_control_panel.template.markdown +++ b/source/_integrations/alarm_control_panel.template.markdown @@ -72,6 +72,10 @@ panels: required: false type: string default: Template Alarm Control Panel + unique_id: + description: An ID that uniquely identifies this alarm control panel. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: "Defines a template to set the state of the alarm panel. Only the states `armed_away`, `armed_home`, `armed_night`, `disarmed`, `pending`, `triggered` and `unavailable` are used." required: false diff --git a/source/_integrations/binary_sensor.template.markdown b/source/_integrations/binary_sensor.template.markdown index e99744508ac..979ba785bd1 100644 --- a/source/_integrations/binary_sensor.template.markdown +++ b/source/_integrations/binary_sensor.template.markdown @@ -51,6 +51,10 @@ sensors: description: A list of entity IDs so the sensor only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: [string, list] + unique_id: + description: An ID that uniquely identifies this binary sensor. Set this to an unique value to allow customisation trough the UI. + required: false + type: string device_class: description: Sets the [class of the device](/integrations/binary_sensor/), changing the device state and icon that is displayed on the frontend. required: false diff --git a/source/_integrations/cover.template.markdown b/source/_integrations/cover.template.markdown index 852fee2690e..fb6a7ed1693 100644 --- a/source/_integrations/cover.template.markdown +++ b/source/_integrations/cover.template.markdown @@ -53,6 +53,10 @@ cover: description: A list of entity IDs so the cover only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: [string, list] + unique_id: + description: An ID that uniquely identifies this cover. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: Defines a template to get the state of the cover. Valid values are `open`/`true` or `closed`/`false`. [`value_template`](#value_template) and [`position_template`](#position_template) cannot be specified concurrently. required: exclusive diff --git a/source/_integrations/fan.template.markdown b/source/_integrations/fan.template.markdown index f470d92ddf1..98547519c04 100644 --- a/source/_integrations/fan.template.markdown +++ b/source/_integrations/fan.template.markdown @@ -63,6 +63,10 @@ fan: description: Name to use in the frontend. required: false type: string + unique_id: + description: An ID that uniquely identifies this fan. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: "Defines a template to get the state of the fan. Valid value: 'on'/'off'" required: true diff --git a/source/_integrations/light.template.markdown b/source/_integrations/light.template.markdown index 1f0568a5c3c..d26fc767b14 100644 --- a/source/_integrations/light.template.markdown +++ b/source/_integrations/light.template.markdown @@ -74,6 +74,10 @@ light: description: A list of entity IDs so the light only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: [string, list] + unique_id: + description: An ID that uniquely identifies this light. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: Defines a template to get the state of the light. required: false diff --git a/source/_integrations/lock.template.markdown b/source/_integrations/lock.template.markdown index ecab0fe932e..f263dd65af7 100644 --- a/source/_integrations/lock.template.markdown +++ b/source/_integrations/lock.template.markdown @@ -47,6 +47,10 @@ lock: required: false type: string default: Template Lock + unique_id: + description: An ID that uniquely identifies this lock. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: Defines a template to set the state of the lock. required: true diff --git a/source/_integrations/switch.template.markdown b/source/_integrations/switch.template.markdown index ad351a8dbd4..4721779aecb 100644 --- a/source/_integrations/switch.template.markdown +++ b/source/_integrations/switch.template.markdown @@ -54,6 +54,10 @@ switch: description: A list of entity IDs so the switch only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: [string, list] + unique_id: + description: An ID that uniquely identifies this switch. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: Defines a template to set the state of the switch. If not defined, the switch will optimistically assume all commands are successful. required: false diff --git a/source/_integrations/template.markdown b/source/_integrations/template.markdown index 01fd2e40560..9fd036cb54a 100644 --- a/source/_integrations/template.markdown +++ b/source/_integrations/template.markdown @@ -54,6 +54,10 @@ sensor: description: A list of entity IDs so the sensor only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: [string, list] + unique_id: + description: An ID that uniquely identifies this sensor. Set this to an unique value to allow customisation trough the UI. + required: false + type: string unit_of_measurement: description: "Defines the units of measurement of the sensor, if any. This will also influence the graphical presentation in the history visualization as a continuous value. Sensors with missing `unit_of_measurement` are showing as discrete values." required: false @@ -104,6 +108,10 @@ If you are using the state of a platform that takes extra time to load, the Temp The template engine will attempt to work out what entities should trigger an update of the sensor. This can fail, for example, if your template loops over the contents of a group. In this case, you can use `entity_id` to provide a list of entity IDs that will cause the sensor to update or you can run the service `homeassistant.update_entity` to update the sensor at will. +### Unique ID + +The optional `unique_id` can be set so the entity will be registered in the [entity registry](https://developers.home-assistant.io/docs/entity_registry_index). This allows changing the `name`, `icon` and `entity_id` from the web interface instead of having to use the [customize](/docs/configuration/customizing-devices/) key in your `configuration.yaml` file. + ## Examples In this section, you find some real-life examples of how to use this sensor. @@ -349,7 +357,7 @@ sensor: Useful entities to choose might be `sensor.date` which update once per day or `sensor.time`, which updates once per minute. Please note that the resulting template will be evaluated by Home Assistant state engine on every state change of these sensors, which in case of `sensor.time` happens every minute and might have a negative impact on performance. - + An alternative to this is to create an interval-based automation that calls the service `homeassistant.update_entity` for the entities requiring updates. This modified example updates every 5 minutes: {% raw %} diff --git a/source/_integrations/vacuum.template.markdown b/source/_integrations/vacuum.template.markdown index 2ff3b7c1b18..7c90d679558 100644 --- a/source/_integrations/vacuum.template.markdown +++ b/source/_integrations/vacuum.template.markdown @@ -39,6 +39,10 @@ vacuum: description: Name to use in the frontend. required: false type: string + unique_id: + description: An ID that uniquely identifies this vacuum. Set this to an unique value to allow customisation trough the UI. + required: false + type: string value_template: description: "Defines a template to get the state of the vacuum. Valid value: `docked`/`cleaning`/`idle`/`paused`/`returning`/`error`" required: false