diff --git a/.textlintrc.json b/.textlintrc.json index dfeb972a496..f63d815c550 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -28,7 +28,6 @@ "Alarm.com", "AlarmDecoder", "Alexa", - "Almond", "Alpha Vantage", "Amazon Alexa", "Amazon Polly", diff --git a/CODEOWNERS b/CODEOWNERS index 7db65f4f74d..6fccd50d732 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -32,7 +32,6 @@ source/_integrations/alarm_control_panel.markdown @home-assistant/core source/_integrations/alert.markdown @home-assistant/core @frenck source/_integrations/alexa.markdown @home-assistant/cloud @ochlocracy @jbouwh source/_integrations/alexa.smart_home.markdown @home-assistant/cloud @ochlocracy -source/_integrations/almond.markdown @gcampax @balloob source/_integrations/amberelectric.markdown @madpilot source/_integrations/ambiclimate.markdown @danielhiversen source/_integrations/ambient_station.markdown @bachya diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 9c4fffd7ec4..b5164732616 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -239,7 +239,7 @@ The same thing can also be expressed as a filter: {% raw %} ```text -{{ expand(['device_tracker.paulus', 'group.child_trackers']) +{{ expand(['device_tracker.paulus', 'group.child_trackers']) | selectattr("attributes.battery", 'defined') | join(', ', attribute="attributes.battery") }} ``` @@ -262,7 +262,7 @@ The same thing can also be expressed as a test: {% raw %} ```text -{{ expand('group.energy_sensors') +{{ expand('group.energy_sensors') | selectattr("state", 'is_number') | join(', ') }} ``` @@ -450,7 +450,7 @@ For example, if you wanted to select a field from `trigger` in an automation bas ```yaml # Is the current time past 10:15? - {{ now() > today_at("10:15") }} + {{ now() > today_at("10:15") }} ``` {% endraw %} @@ -465,8 +465,8 @@ For example, if you wanted to select a field from `trigger` in an automation bas {% raw %} ```yaml - # 77 minutes before current time. - {{ now() - timedelta( hours = 1, minutes = 17 ) }} + # 77 minutes before current time. + {{ now() - timedelta( hours = 1, minutes = 17 ) }} ``` {% endraw %} @@ -476,15 +476,15 @@ For example, if you wanted to select a field from `trigger` in an automation bas {% raw %} ```yaml - # Renders to "00:10:00" - {{ as_timedelta("PT10M") }} + # Renders to "00:10:00" + {{ as_timedelta("PT10M") }} ``` {% endraw %} - Filter `timestamp_local(default)` converts a UNIX timestamp to the ISO format string representation as date/time in your local timezone. If that fails, returns the `default` value, or if omitted raises an error. If a custom string format is needed in the string, use `timestamp_custom` instead. - Filter `timestamp_utc(default)` converts a UNIX timestamp to the ISO format string representation representation as date/time in UTC timezone. If that fails, returns the `default` value, or if omitted raises an error. If a custom string format is needed in the string, use `timestamp_custom` instead. -- Filter `timestamp_custom(format_string, local=True, default)` converts an UNIX timestamp to its string representation based on a custom format, the use of a local timezone is the default. If that fails, returns the `default` value, or if omitted raises an error. Supports the standard [Python time formatting options](https://docs.python.org/3/library/time.html#time.strftime). +- Filter `timestamp_custom(format_string, local=True, default)` converts an UNIX timestamp to its string representation based on a custom format, the use of a local timezone is the default. If that fails, returns the `default` value, or if omitted raises an error. Supports the standard [Python time formatting options](https://docs.python.org/3/library/time.html#time.strftime).
@@ -681,11 +681,11 @@ The last argument of the closest function has an implicit `expand`, and can take {% raw %} ```text -Closest out of given entities: +Closest out of given entities: {{ closest(['group.children', states.device_tracker]) }} -Closest to a coordinate: +Closest to a coordinate: {{ closest(23.456, 23.456, ['group.children', states.device_tracker]) }} -Closest to some entity: +Closest to some entity: {{ closest(states.zone.school, ['group.children', states.device_tracker]) }} ``` @@ -696,16 +696,42 @@ It will also work as a filter over an iterable group of entities or groups: {% raw %} ```text -Closest out of given entities: +Closest out of given entities: {{ ['group.children', states.device_tracker] | closest }} -Closest to a coordinate: +Closest to a coordinate: {{ ['group.children', states.device_tracker] | closest(23.456, 23.456) }} -Closest to some entity: +Closest to some entity: {{ ['group.children', states.device_tracker] | closest(states.zone.school) }} ``` {% endraw %} +### Contains + +Jinja provides by default a [`in` operator](https://jinja.palletsprojects.com/en/latest/templates/#other-operators) how return `True` when one element is `in` a provided list. +The `contains` test and filter allow you to do the exact opposite and test for a list containing an element. This is particularly useful in `select` or `selectattr` filter, as well as to check if a device has a specific attribute, a `supported_color_modes`, a specific light effect. + +Some examples: +{% raw %} + +- `{{ state_attr('light.dining_room', 'effect_list') | contains('rainbow') }}` will return `true` if the light has a `rainbow` effect. +- `{{ expand('light.office') | selectattr("attributes.supported_color_modes", 'contains', 'color_temp') | list }}` will return all light that support color_temp in the office group. +- ```text + {% set current_month = now().month %} + {% set extra_ambiance = [ + {'name':'Halloween', 'month': [10,11]}, + {'name':'Noel', 'month': [1,11,12]} + ]%} + {% set to_add = extra_ambiance | selectattr('month', 'contains', current_month ) | map(attribute='name') | list %} + {% set to_remove = extra_ambiance | map(attribute='name') | reject('in', to_add) | list %} + {{ (state_attr('input_select.light_theme', 'options') + to_add ) | unique | reject('in', to_remove) | list }} + ``` + This more complex example uses the `contains` filter to match the current month with a list. In this case, it's used to generate a list of light theme to give to the `Input select: Set options` service. + + +{% endraw %} + + ### Numeric functions and filters Some of these functions can also be used in a [filter](https://jinja.palletsprojects.com/en/latest/templates/#id11). This means they can act as a normal function like this `sqrt(2)`, or as part of a filter like this `2|sqrt`. @@ -863,7 +889,7 @@ The following overview contains a couple of options to get the needed values: # Incoming value: {"primes": [2, 3, 5, 7, 11, 13]} -# Extract first prime number +# Extract first prime number {{ value_json.primes[0] }} # Format output diff --git a/source/_integrations/alexa.smart_home.markdown b/source/_integrations/alexa.smart_home.markdown index 633f81e567f..7c5a850a67b 100644 --- a/source/_integrations/alexa.smart_home.markdown +++ b/source/_integrations/alexa.smart_home.markdown @@ -70,7 +70,7 @@ Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant: - [Humidifier Mode](#humidifier-mode) - [Image Processing](#image-processing) - [Presence Detection Notification](#presence-detection-notification) - - [Input Number](#input-number) + - [Input Number and Number](#input-number-and-number) - [Light](#light) - [Brightness](#brightness) - [Color Temperature](#color-temperature) @@ -488,7 +488,7 @@ The following integrations are currently supported: - [Humidifier Mode](#humidifier-mode) - [Image Processing](#image-processing) - [Presence Detection Notification](#presence-detection-notification) - - [Input Number](#input-number) + - [Input Number and Number](#input-number-and-number) - [Light](#light) - [Brightness](#brightness) - [Color Temperature](#color-temperature) @@ -852,15 +852,15 @@ Display category will default to `CAMERA` to enable presence detected notificati
-### Input Number +### Input Number and Number -Control an `input_number` entity with Alexa. Configures Alexa with the `min`, `max`, `step`, and `unit_of_measurement` attributes for the entity. +Control an `input_number` or `number` entity with Alexa. Configures Alexa with the `min`, `max`, `step`, and `unit_of_measurement` attributes for the entity. - _"Alexa, set [entity name] to forty five [unit of measurement]."_ - _"Alexa, increase the [entity name] by two."_ - _"Alexa, set the [entity name] to maximum."_ -The following table lists the possible friendly name synonyms available for a Input Number with `min: -90, max: 90, step: 45, unit_of_measurement: degrees`. +The following table lists the possible friendly name synonyms available for a Input Number or Number with `min: -90, max: 90, step: 45, unit_of_measurement: degrees`. | Fan Range | Friendly Name Synonyms | | --------- | ----------------------------------------- | @@ -870,6 +870,10 @@ The following table lists the possible friendly name synonyms available for a In | 45 | _"forty five"_ | | 90 | _"ninety"_, _"maximum"_, _"max"_ | +The `unit_of_measurement` will be used to select a supported unit label from the [Global Alexa catalog](https://developer.amazon.com/en-US/docs/alexa/device-apis/resources-and-assets.html#global-alexa-catalog). If there is no match it will be assigned a preset controller. + +The following units are supported: °C, °F, K, m, km, mi, yd, in, kg, g, oz, lb, L, ft³, m³, gal and % + ### Light Control lights with _"turn on"_ and _"turn off"_ utterances, adjust brightness, color, and temperature. diff --git a/source/_integrations/almond.markdown b/source/_integrations/almond.markdown deleted file mode 100644 index d9aa73d9c53..00000000000 --- a/source/_integrations/almond.markdown +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Almond -description: Instructions on how to setup Almond within Home Assistant. -ha_category: - - Voice -ha_iot_class: Local Polling -ha_release: '0.102' -ha_config_flow: true -ha_codeowners: - - '@gcampax' - - '@balloob' -ha_domain: almond -ha_integration_type: integration ---- - -[Almond](https://almond.stanford.edu/) is an open, privacy-preserving virtual assistant by [Stanford Open Virtual Assistant Lab](https://oval.cs.stanford.edu/). It allows you, among other things, to control Home Assistant using natural language. Once installed, it will be available in the user interface via the microphone icon in the top right. - -Almond consists of three parts: - -- Almond Server: Knows about Home Assistant and your data. Executes your sentences. -- LUInet: Neural network that converts your sentences into Thingtalk programs. -- Thingpedia: Skills that provide the building blocks for Thingtalk programs. - -Architectural overview of how all pieces fit together. - -## Installation - -### Home Assistant add-on installation - -To install Almond Server, go to the Home Assistant add-on store, search for Genie and click on Install. Once started, it will initiate a configuration flow to finish set up in Home Assistant. You can find it on the integrations page in the configuration panel. - -### Manual installation - -You can install Almond Server by following [the instructions in their README](https://github.com/stanford-oval/almond-server#running-almond-server). - -Before linking it to Home Assistant, you will need to visit the Almond UI once to create a password. It is by default available on port 3000. - -Once installed, configure Almond like this: - -```yaml -# Example configuration.yaml entry -almond: - type: local - host: http://127.0.0.1:3000 -``` - -The Almond integration does not update configuration entries yet. If you make a change to configuration.yaml, you will need to remove the configuration entry and then restart Home Assistant. - -### Almond Web - -Stanford offers a hosted version of Almond Server called Almond Web. To use this, go to the integrations page and add Almond using the add integration flow. - -Your Home Assistant installation needs to be externally accessible if you want Almond Web to be able to control Home Assistant. - -### Almond Web - Manual installation - -It is possible to set up Almond Web manually. You will need to create your own client ID and secret in the web interface. - -```yaml -# Example configuration.yaml entry -almond: - type: oauth2 - client_id: AAAAAAAAAAAAA - client_secret: BBBBBBBBBBBBBBBBB -``` - -You can now go to the integrations page and start the configuration flow. - -## Language Support - -Almond is currently limited to the English language. This is not a technical limitation but requires specialized engineering effort. Almond has currently no public timeline for adding other languages. - -## Device Support - -Almond is constantly improving. It does not currently support all devices, but we're working with Almond on improving this. diff --git a/source/_integrations/calendar.markdown b/source/_integrations/calendar.markdown index ecafdee3080..174bc570baf 100644 --- a/source/_integrations/calendar.markdown +++ b/source/_integrations/calendar.markdown @@ -38,6 +38,8 @@ Some calendar integrations allow Home Assistant to manage your calendars directly from Home Assistant. In this case, you can add new events by clicking the “Add event” button in the lower right corner of the calendar dashboard. +Also see [Services](#services) below. + ## Automation Calendar [Triggers](/docs/automation/trigger) enable automation based on an @@ -139,3 +141,41 @@ automation: {% endraw %} {% enddetails %} + +## Services + +Some calendar integrations allow Home Assistant to manage your calendars +directly using services. The services provided by some calendar entities are described below or you can read more about [Service Calls](/docs/scripts/service-calls/). + +### Service `calendar.create_event` + +Add a new calendar event. A calendar `target` is selected with a [Target Selector](/docs/blueprint/selectors/#target-selector) and the `data` payload supports the following fields: + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | --------| +| `summary` | no | Acts as the title of the event. | Bowling +| `description` | yes | The description of the event. | Birthday bowling +| `start_date_time` | yes | The date and time the event should start. | 2019-03-10 20:00:00 +| `end_date_time` | yes | The date and time the event should end. | 2019-03-10 23:00:00 +| `start_date` | yes | The date the whole day event should start. | 2019-03-10 +| `end_date` | yes | The date the whole day event should end. | 2019-03-11 +| `in` | yes | Days or weeks that you want to create the event in. | "days": 2 + + +
+ +You either use `start_date_time` and `end_date_time`, or `start_date` and `end_date`, or `in`. + +
+ +This is a full example of service call in YAML: + +```yaml +service: calendar.create_event +target: + entity_id: calendar.device_automation_schedules +data: + summary: "Example" + start_date: "2022-10-01" + end_date: "2022-10-02" +``` \ No newline at end of file diff --git a/source/_integrations/frontend.markdown b/source/_integrations/frontend.markdown index 92891e3f074..867d96ad78d 100644 --- a/source/_integrations/frontend.markdown +++ b/source/_integrations/frontend.markdown @@ -76,18 +76,18 @@ They can be changed it using `primary-color` and `accent-color` variables. #### State color -Each entity has its own color, based on `domain`, `device_class`, and `state`, to be easily recognizable. Theses colors are used in [dashboards](/dashboards/) and [history](/integrations/history/). Home Assistant has default rules that fit most use cases. +Each entity has its own color, based on `domain`, `device_class`, and `state`, to be easily recognizable. Theses colors are used in [dashboards](/dashboards/) and [history](/integrations/history/). Home Assistant has default color rules that fit most use cases. Here is a list of domains that support colors: `alarm_control_panel`, `alert`, `automation`, `binary_sensor`, `calendar`, `camera`, `climate`, `cover`, `device_tracker`, `fan`, `group`, `humidifier`, `input_boolean`, `light`, `lock`, `media_player`, `person`, `plant`, `remote`, `schedule`, `script`, `siren`, `sun`, `switch`, `timer`, `update`, and `vacuum`. -These rules can be customized using theme variables: +The color rules can be customized using theme variables: 1. `state-{domain}-{device_class}-{state}-color` 2. `state-{domain}-{state}-color` 3. `state-{domain}-(active|inactive)-color` 4. `state-(active|inactive)-color` -Note that if multiple properties match your entity, the first one will be used in this order. +Note that the variables will be used in the listed order, so if multiple match your entity, the first matching variable (= most specific one) will be used. ```yaml # Example configuration.yaml entry diff --git a/source/_integrations/google_assistant_sdk.markdown b/source/_integrations/google_assistant_sdk.markdown index e2e7c103d54..fec45b9eadc 100644 --- a/source/_integrations/google_assistant_sdk.markdown +++ b/source/_integrations/google_assistant_sdk.markdown @@ -158,12 +158,6 @@ data: ## Conversation agent -In `configuration.yaml` add: - -```yaml -conversation: -``` - In the configure options of the integration, enable the conversation agent and then you can converse with Google Assistant by pressing the microphone in the frontend (supported browsers only): ![Screenshot Conversation](/images/integrations/google_assistant_sdk/conversation.png) @@ -175,3 +169,5 @@ service: conversation.process data: text: "Dim the family room lights" ``` + +Note: due to a bug in the Google Assistant API, not all responses contain text, especially for home control commands, like turn on the lights. These will be shown as ``. For those, Google Assistant responds with HTML and Home Assistant integrations are [not allowed](https://github.com/home-assistant/architecture/blob/master/adr/0004-webscraping.md) to parse HTML. diff --git a/source/_integrations/homewizard.markdown b/source/_integrations/homewizard.markdown index 8e54ebacf0a..025395ddcb4 100644 --- a/source/_integrations/homewizard.markdown +++ b/source/_integrations/homewizard.markdown @@ -87,4 +87,4 @@ This feature is currently only available for the Wifi P1 meter and the Wifi Ener The HomeWizard Energy devices are designed to work with the HomeWizard Energy app and require communication with the HomeWizard cloud to make them function with the app. The "Cloud connection" configuration toggle can be used to turn off all communication with the HomeWizard cloud, making the device fully local. The device cannot communicate with the app, and the device won't receive any future firmware updates. Cloud communication is restored when the switch is turned on again. Cloud communications are also restored after a factory reset, or when the device is put in pairing mode. -This feature is currently only available for the Wifi P1 meter and the Wifi Energy Socket. +This feature is currently not available for the Wifi Water meter. diff --git a/source/_integrations/mopeka.markdown b/source/_integrations/mopeka.markdown new file mode 100644 index 00000000000..1bb82c38d2c --- /dev/null +++ b/source/_integrations/mopeka.markdown @@ -0,0 +1,27 @@ +--- +title: Mopeka +description: Instructions on how to integrate Mopeka devices into Home Assistant. +ha_category: + - Sensor +ha_bluetooth: true +ha_release: 2023.2 +ha_iot_class: Local Push +ha_codeowners: + - '@bdraco' +ha_domain: mopeka +ha_config_flow: true +ha_platforms: + - sensor +ha_integration_type: integration +--- + +Integrates [Mopeka](https://www.mopekaiot.com/) devices into Home Assistant. + +{% include integrations/config_flow.md %} + +The Mopeka integration will automatically discover devices once the [Bluetooth](/integrations/bluetooth) integration is enabled and functional. + +## Supported devices + +- [Pro Plus](https://www.mopekaiot.com/product/mopeka-pro-plus-sensor) (M1015) +- [Pro Check](https://www.mopekaiot.com/product/mopeka-pro-check-sensor-aluminum-lpg-cylinders-w-collar) (M1017) diff --git a/source/_integrations/number.markdown b/source/_integrations/number.markdown index d5b5ff93b8e..cd6bbf5ad90 100644 --- a/source/_integrations/number.markdown +++ b/source/_integrations/number.markdown @@ -58,7 +58,7 @@ The type of data a number represents impacts how it is displayed in the frontend - **sound_pressure**: Sound pressure in dB or dBA - **speed**: Generic speed in ft/s, in/d, in/h, km/h, kn, m/s, mph, or mm/d - **sulphur_dioxide**: Concentration of sulphur dioxide in µg/m³ -- **temperature**: Temperature in °C or °F +- **temperature**: Temperature in °C, °F or K - **volatile_organic_compounds**: Concentration of volatile organic compounds in µg/m³ - **voltage**: Voltage in V, mV - **volume**: Generic volume in L, mL, gal, fl. oz., m³, ft³, or CCF diff --git a/source/_integrations/openai_conversation.markdown b/source/_integrations/openai_conversation.markdown new file mode 100644 index 00000000000..87d6a66779b --- /dev/null +++ b/source/_integrations/openai_conversation.markdown @@ -0,0 +1,21 @@ +--- +title: OpenAI conversation agent +description: Instructions on how to integrate OpenAI as a conversation agent +ha_category: + - Voice +ha_release: 2023.2 +ha_iot_class: Cloud Polling +ha_config_flow: true +ha_codeowners: + - '@balloob' +ha_domain: openai_conversation +ha_integration_type: service +--- + +The OpenAI integration adds a conversation agent powered by [OpenAI](https://www.openai.com) in Home Assistant. + +This conversation agent is unable to control your house. It can only query information that has been provided by Home Assistant. To be able to answer questions about your house, Home Assistant will need to provide OpenAI with the details of your house, which include areas, devices and their states. + +This integration requires an API key to use, [which you can generate here.](https://beta.openai.com/account/api-keys). + +{% include integrations/config_flow.md %} diff --git a/source/_integrations/sensor.markdown b/source/_integrations/sensor.markdown index 8ead805349d..4f6490f4783 100644 --- a/source/_integrations/sensor.markdown +++ b/source/_integrations/sensor.markdown @@ -58,7 +58,7 @@ The type of data a sensor returns impacts how it is displayed in the frontend. T - **sound_pressure**: Sound pressure in dB or dBA - **speed**: Generic speed in ft/s, in/d, in/h, km/h, kn, m/s, mph or mm/d - **sulphur_dioxide**: Concentration of sulphur dioxide in µg/m³ -- **temperature**: Temperature in °C or °F +- **temperature**: Temperature in °C, °F or K - **timestamp**: Datetime object or timestamp string (ISO 8601) - **volatile_organic_compounds**: Concentration of volatile organic compounds in µg/m³ - **voltage**: Voltage in V, mV diff --git a/source/_redirects b/source/_redirects index 2ba5898b889..a4ea2966ba7 100644 --- a/source/_redirects +++ b/source/_redirects @@ -419,6 +419,7 @@ # Removed integrations /integrations/alarmdotcom /more-info/removed-integration 301 +/integrations/almond /more-info/removed-integration 301 /integrations/ambee /more-info/removed-integration 301 /integrations/apns /more-info/removed-integration 301 /integrations/arlo /more-info/removed-integration 301 diff --git a/source/images/integrations/google_assistant_sdk/conversation.png b/source/images/integrations/google_assistant_sdk/conversation.png index e656ba4fd17..ee696e0533f 100644 Binary files a/source/images/integrations/google_assistant_sdk/conversation.png and b/source/images/integrations/google_assistant_sdk/conversation.png differ