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-21 16:27:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added Restore state info + Updated config style (#4343)

Browse Source 
* Updated input_boolean

* new Configuration style
* Linkable title Automation Examples

* Updated input_select

* new Configuration style
* Services as table
* Rearaged scenes
* small improvments

* Updated input_number

* linkformat

* Updated input_text

* New configuration style

* Update input_datetime

* New configuration style

* Updated recorder

* New configuration style

* Added Restore State Info
This commit is contained in:
cdce8p 2018-01-05 11:53:52 +01:00 committed by Fabian Affolter
parent c624d5fc00
commit 5b873e2380
6 changed files with 214 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
source/_components/input_boolean.markdown
View File

@ -24,16 +24,34 @@ input_boolean:
icon: mdi:car
```
Configuration variables:
{% configuration %}
input_boolean:
description: Alias for the input. Multiple entries are allowed.
required: true
type: map
keys:
name:
description: Friendly name of the input.
required: false
type: String
initial:
description: Initial value whe Home Assistant starts.
required: false
type: boolean
default: false
icon:
description: Icon to display for the component. Refer to the [Customizing devices](/docs/configuration/customizing-devices/#possible-values) page for possible values.
required: false
type: icon
{% endconfiguration %}
- **[alias]** (*Required*): Alias for the input.
- **name** (*Optional*): Friendly name of the input.
- **initial** (*Optional*): Initial value when Home Assistant starts. Defaults to `False`.
- **icon** (*Optional*): Icon for entry.
### {% linkable_title Restore State %}
Pick an icon that you can find on [materialdesignicons.com](https://materialdesignicons.com/) to use for your input and prefix the name with `mdi:`. For example `mdi:car`, `mdi:ambulance`, or `mdi:motorbike`.
This component supports the `restore_state` function which restores the state value after Home Assistant has started to the value it has been before Home Assistant stopped. The use this feature please make sure that the [`recorder`](/components/recorder/) component is enabled and your entity does not have and initial value. Additional information and a list of components that support this feature can be found here [recorder/#restore-state](/components/recorder/#restore-state).
Here's an example of an automation using the above input_boolean. This action will only occur if the switch is on.
## {% linkable_title Automation Examples %}
Here's an example of an automation using the above `input_boolean`. This action will only occur if the switch is on.
```yaml
automation:

51
source/_components/input_datetime.markdown
View File

@ -33,18 +33,45 @@ input_datetime:
has_time: true
```
Configuration variables:
{% configuration %}
input_datetime:
description: Alias for the datetime input. Multiple entries are allowed.
required: true
type: map
keys:
name:
description: Friendly name of the datetime input.
required: false
type: String
has_time:
description: Set to `true` if the input should have a time. At least one `has_time` or `has_date` must be defined.
required: false
type: Boolean
default: false
has_date:
description: Set to `true` if the input should have a date. At least one `has_time` or `has_date` must be defined.
required: false
type: Boolean
default: false
initial:
description: Set the initial value of this input, depending on `has_time` and `has_date`.
required: false
type: datetime | time | date
default: 1970-01-01 00:00 | 1970-01-01 | 00:00
{% endconfiguration %}
- **[alias]** (*Required*): Alias for the datetime input. Multiple entries are allowed.
- **name** (*Optional*): Friendly name of the datetime input.
- **has_time** (*Optional*): Set to `true` if this input should have time. Defaults to `false`.
- **has_date** (*Optional*): Set to `true` if this input should have a date. Defaults to `false`.
- **initial** (*Optional*): Set the initial value of this input. Defaults to '1970-01-01 00:00'. If has_time is `false` this must be just a date (e.g.: '1970-01-01'). If has_date is `false` this must be just a time (e.g.: '15:16').
### {% linkable_title Attributes %}
A datetime input entity's state exports several attributes that can be useful in automations and templates:
A datetime input entity's state exports several attributes that can be useful in automations and templates.
- **has_time**: `true` if this entity has time.
- **has_date**: `true` if this entity has a date.
- **year**, **month**, **day** (Only available if *has_date* is true): The year, month and day of the date.
- **hour**, **minute**, **second** (Only available if *has_time* is true): The hour, minute and second of the time.
- **timestamp**: A timestamp representing the time held in the input. If *has_date* is true, this is the UNIX timestamp of the date / time held by the input. Otherwise (i.e., if only *has_time* is true) the number of seconds since midnight representing the time held by the input.
| Attribute | Description |
| --------- | ----------- |
| `has_time` | `true` if this entity has a time.
| `has_date` | `true` if this entity has a date.
| `year`<br>`month`<br>`day` | The year, month and day of the date.<br>(only availabel if `has_date: true`)
| `hour`<br>`minute`<br>`second` | The hour, minute and second of the time.<br>(only available if `has_time: true`)
| `timestamp` | A timestamp representing the time held in the input.<br>If `has_date: true`, this is the UNIX timestamp of the date / time held by the input. Otherwise if only `has_time: true`, this is the number of seconds since midnight representing the time held by the input.
### {% linkable_title Restore State %}
This component supports the `restore_state` function which restores the state value after Home Assistant has started to the value it has been before Home Assistant stopped. The use this feature please make sure that the [`recorder`](/components/recorder/) component is enabled and your entity does not have and initial value. Additional information and a list of components that support this feature can be found here [recorder/#restore-state](/components/recorder/#restore-state).

6
source/_components/input_number.markdown
View File

@ -78,11 +78,15 @@ input_number:
required: false
type: string
icon:
description: Icon to display in front of the box/slider in the frontend. Refer to the [Customizing devices](https://home-assistant.io/docs/configuration/customizing-devices/#possible-values) page for possible values.
description: Icon to display in front of the box/slider in the frontend. Refer to the [Customizing devices](/docs/configuration/customizing-devices/#possible-values) page for possible values.
required: false
type: icon
{% endconfiguration %}
### {% linkable_title Restore State %}
This component supports the `restore_state` function which restores the state value after Home Assistant has started to the value it has been before Home Assistant stopped. The use this feature please make sure that the [`recorder`](/components/recorder/) component is enabled and your entity does not have and initial value. Additional information and a list of components that support this feature can be found here [recorder/#restore-state](/components/recorder/#restore-state).
## {% linkable_title Automation Examples %}
Here's an example of `input_number` being used as a trigger in an automation.

84
source/_components/input_select.markdown
View File

@ -33,27 +33,64 @@ input_select:
- Home Alone
```
Configuration variables:
- **[alias]** array (*Required*): Alias for the input. Multiple entries are allowed..
- **name** (*Optional*): Friendly name of the input.
- **options** array (*Required*): List of options to choose from.
- **initial** (*Optional*): Initial value when Home Assistant starts.
- **icon** (*Optional*): Icon for entry.
Pick an icon that you can find on [materialdesignicons.com](https://materialdesignicons.com/) to use for your input and prefix the name with `mdi:`. For example `mdi:car`, `mdi:ambulance`, or `mdi:motorbike`.
{% configuration %}
input_select:
description: Alias for the input. Multiple entries are allowed.
required: true
type: map
keys:
name:
description: Friendly name of the input.
required: false
type: String
options:
description: List of options to choose from.
required: true
type: Array
initial:
description: Initial value when Home Assistant starts.
required: false
type: Element of options
default: First element of options
icon:
description: Icon to display for the component. Refer to the [Customizing devices](/docs/configuration/customizing-devices/#possible-values) page for possible values.
required: false
type: icon
{% endconfiguration %}
<p class='note'>
Because YAML defines [booleans](http://yaml.org/type/bool.html) as equivalent, any variations of 'On', 'Yes', 'Y', 'Off', 'No', or 'N' (regardless of case) used as option names will be replaced by True and False unless they are defined in quotation marks.
</p>
### {% linkable_title Restore State %}
This component supports the `restore_state` function which restores the state value after Home Assistant has started to the value it has been before Home Assistant stopped. The use this feature please make sure that the [`recorder`](/components/recorder/) component is enabled and your entity does not have and initial value. Additional information and a list of components that support this feature can be found here [recorder/#restore-state](/components/recorder/#restore-state).
### {% linkable_title Services %}
This components provide three services to modify the state of the `input_select`:
This components provide three services to modify the state of the `input_select`.
- `input_select.select_option`: This can be used to select a specific option. The option is passed as `option` attribute in the service data.
- `input_select.select_previous`: Select the previous option.
- `input_select.select_next`: Select the next option.
| Service | Data | Description |
| ------- | ---- | ----------- |
| `select_option` | `option` | This can be used to select a specific option.
| `set_options` | `options`<br>`entity_id(s)` | Set the options for specific `input_select` entities.
| `select_previous` | | Select the previous option.
| `select_next` | | Select the next option.
### {% linkable_title Scenes %}
To specify a target option in a [Scene](/components/scene/) you have to specify the target as `option` attribute:
```yaml
# Example configuration.yaml entry
scene:
- name: Example1
entities:
input_select.who_cooks:
option: Paulus
```
## {% linkable_title Automation Examples %}
The following example shows the usage of the `input_select.select_option` service in an automation:
@ -87,23 +124,10 @@ automation:
options: ["Item A", "Item B", "Item C"]
```
### {% linkable_title Scenes %}
To specify a target option in a [Scene](/components/scene/) you have to specify the target as `option` attribute:
```yaml
# Example configuration.yaml entry
scene:
- name: Example1
entities:
input_select.who_cooks:
option: Paulus
```
Example of `input_select` being used in a bidirectional manner, both being set by and controlled by an MQTT action in an automation.
```yaml
{% raw %}
```yaml
# Example configuration.yaml entry using 'input_select' in an action in an automation
# Define input_select
@ -129,7 +153,7 @@ input_select:
service: input_select.select_option
data_template:
entity_id: input_select.thermostat_mode
option: '{{ trigger.payload }}'
option: "{{ trigger.payload }}"
# This automation script runs when the thermostat mode selector is changed.
# It publishes its value to the same MQTT topic it is also subscribed to.
@ -142,6 +166,6 @@ input_select:
data_template:
topic: "thermostatMode"
retain: true
payload: '{{ states.input_select.thermostat_mode.state }}'
{% endraw %}
payload: "{{ states('input_select.thermostat_mode') }}"
```
{% endraw %}

41
source/_components/input_text.markdown
View File

@ -29,11 +29,38 @@ input_text:
pattern: '[a-fA-F0-9]*'
```
Configuration variables:
{% configuration %}
input_text:
description: Alias for the input. Multiple entries are allowed.
required: true
type: map
keys:
name:
description: Friendly name of the text input.
required: false
type: String
min:
description: Minimum length for the text value.
required: false
type: int
default: 0
max:
description: Maximum length for the text value.
required: false
type: int
default: 100
initial:
description: Initial value when Home Assistant starts.
required: false
type: String
default: empty
pattern:
description: Regex pattern for client side validation.
required: false
type: String
default: empty
{% endconfiguration %}
- **[alias]** (*Required*): Alias for the text input.
- **min** (*Optional*): Minimum length for the text value. Default is `0`.
- **max** (*Optional*): Maximum length for the text value. Default is `100`.
- **name** (*Optional*): Friendly name of the text input.
- **initial** (*Optional*): Initial value when Home Assistant starts. Default is empty string.
- **pattern** (*Optional*): Regex pattern for client side validation. Default is empty string, which is treated same as `.*`.
### {% linkable_title Restore State %}
This component supports the `restore_state` function which restores the state value after Home Assistant has started to the value it has been before Home Assistant stopped. The use this feature please make sure that the [`recorder`](/components/recorder/) component is enabled and your entity does not have and initial value. Additional information and a list of components that support this feature can be found here [recorder/#restore-state](/components/recorder/#restore-state).

69
source/_components/recorder.markdown
View File

@ -25,18 +25,51 @@ To setup the `recorder` component in your installation, add the following to you
recorder:
```
Configuration variables:
- **purge_interval** (*Optional*): (days) Enable scheduled purge of older events and states. The purge task runs every x days from when the `recorder component` is first enabled. If a scheduled purge is missed (e.g. if Home Assistant was not running) then the schedule will resume soon after Home Assistant restarts. You can use [service](#service-purge) call `recorder.purge` when required without impacting the purge schedule.
- **purge_keep_days** (*Required with `purge_interval`*): Specify number of history days to keep in recorder database after purge.
- **exclude** (*Optional*): Configure which components should be excluded from recordings.
- **entities** (*Optional*): The list of entity ids to be excluded from recordings.
- **domains** (*Optional*): The list of domains to be excluded from recordings.
- **include** (*Optional*): Configure which components should be included in recordings. If set, all other entities will not be recorded.
- **entities** (*Optional*): The list of entity ids to be included from recordings.
- **domains** (*Optional*): The list of domains to be included from recordings.
- **db_url** (*Optional*): The URL which point to your database.
{% configuration %}
recorder:
description: Enables the recorder component. Only allowed once.
required: true
type: map
keys:
db_url:
description: The URL which points to your database.
required: false
type: URL
purge_interval:
description: Enable scheduled purge of older events and states. The purge task runs every `purge_interval` days from when the `recorder component` is first enabled. If a scheduled purge is missed (e.g if Home Assistant was not running), the schedule will resume soon after Home Assistant restarts. You can use the [service](#service-purge) call `purge` when required without impacting the purge schedule. If `purge_interval` is set, `purge_keep_days` needs to be set as well.
required: Inclusive
type: int
purge_keep_days:
description: Specify the number of history days to keep in recorder database after purge. If `purge_interval` is set, `purge_keep_days` needs to be set as well.
required: Inclusive
type: int
exclude:
description: Configure which components should be excluded
required: false
type: map
keys:
domains:
description: The list of domains to be excluded from recordings.
required: false
type: List
entities:
description: The list of entity ids to be excluded from recordings.
required: false
type: List
include:
description: Configure which components should be included in recordings. If set, all other entities will not be recorded.
required: false
type: map
keys:
domains:
description: The list of domains to be included in the recordings.
required: false
type: List
entities:
description: The list of entity ids to be included in the recordings.
required: false
type: List
{% endconfiguration %}
Define domains and entities to `exclude` (aka. blacklist). This is convenient when you are basically happy with the information recorded, but just want to remove some entities or domains. Usually these are entities/domains which do not change (like `weblink`) or rarely change (`updater` or `automation`).
@ -100,6 +133,18 @@ action:
keep_days: 5
```
### {% linkable_title Restore State %}
If the `recorder` component is activated, some components support `restore_state` which will restore the state of the entity after Home Assistant is started to to state before Home Assistant was stopped. Please make sure that you do not exclude the entities for which you want the state to be restored from your recordings. An uncomplete list of components that currently support `restore_state`:
* [`input_boolean`](/components/input_boolean/#restore-state)
* [`input_number`](/components/input_number/#restore-state)
* [`input_select`](/components/input_select/#restore-state)
* [`input_datetime`](/components/input_datetime/#restore-state)
* [`input_text`](/components/input_text/#restore-state)
* ...
## Custom database engines
| Database engine | `db_url` |