diff --git a/.textlintrc.json b/.textlintrc.json index 914366e2bd9b..f63d815c5509 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -28,7 +28,6 @@ "Alarm.com", "AlarmDecoder", "Alexa", - "Almond", "Alpha Vantage", "Amazon Alexa", "Amazon Polly", @@ -142,6 +141,7 @@ "IP", "iPad", "iPhone", + "ISY", "ISY994", "iTunes", "JSON-RPC", diff --git a/CODEOWNERS b/CODEOWNERS index b00510ac5090..6fccd50d7326 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 @@ -192,6 +191,7 @@ source/_integrations/epsonworkforce.markdown @ThaStealth source/_integrations/eq3btsmart.markdown @rytilahti source/_integrations/escea.markdown @lazdavila source/_integrations/esphome.markdown @OttoWinter @jesserockz +source/_integrations/eufylife_ble.markdown @bdr99 source/_integrations/evil_genius_labs.markdown @balloob source/_integrations/evohome.markdown @zxdavb source/_integrations/ezviz.markdown @RenierM26 @baqs @@ -353,6 +353,7 @@ source/_integrations/landisgyr_heat_meter.markdown @vpathuis source/_integrations/launch_library.markdown @ludeeus @DurgNomis-drol source/_integrations/laundrify.markdown @xLarry source/_integrations/lcn.markdown @alengwenus +source/_integrations/ld2410_ble.markdown @930913 source/_integrations/led_ble.markdown @bdraco source/_integrations/legrand.markdown @cgtobi source/_integrations/leviton_z_wave.markdown @home-assistant/z-wave diff --git a/source/_dashboards/iframe.markdown b/source/_dashboards/iframe.markdown index 5e3e27d54d48..60869ab9e990 100644 --- a/source/_dashboards/iframe.markdown +++ b/source/_dashboards/iframe.markdown @@ -38,6 +38,11 @@ aspect_ratio: description: 'Forces the height of the image to be a ratio of the width. Valid formats: Height percentage value (`23%`) or ratio expressed with colon or "x" separator (`16:9` or `16x9`). For a ratio, the second element can be omitted and will default to "1" (`1.78` equals `1.78:1`).' type: string default: "50%" +allow_open_top_navigation: + required: false + description: 'Allow the user to open iframe content links by opening the default browser in the Home Assistant mobile app. It is false by default because it adds allow-top-navigation-by-user-activation on the iframe sandbox attribute which is less secure. So set it to true if you need it and are confident with the iframe content.' + type: boolean + default: false title: required: false description: The card title. diff --git a/source/_dashboards/picture.markdown b/source/_dashboards/picture.markdown index c66fbe8d851e..b7e84d23940c 100644 --- a/source/_dashboards/picture.markdown +++ b/source/_dashboards/picture.markdown @@ -27,6 +27,10 @@ image: required: true description: "The URL of an image. When you want to store images in your Home Assistant installation use the [hosting files documentation](/integrations/http/#hosting-files). After storing your files, use the `/local` path, for example, `/local/filename.jpg`." type: string +alt_text: + required: false + description: Alternative text for the image. This is necessary for users of assistive technology. The [W3C images tutorial](https://www.w3.org/WAI/tutorials/images/) provides simple guidance for writing alternative text. + type: string theme: required: false description: Override the used theme for this card with any loaded theme. For more information about themes, see the [frontend documentation](/integrations/frontend/). diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown index 93dd66a86fae..e1a06fdf79b2 100644 --- a/source/_docs/blueprint/schema.markdown +++ b/source/_docs/blueprint/schema.markdown @@ -55,6 +55,10 @@ domain: `automation` and `script` are supported. type: string required: true +author: + description: The name of the blueprint author. + type: string + required: false homeassistant: description: > Home Assistant requirements to be able to use the blueprint successfully. diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index b5f75ac2d8d9..e4f0b6a9c124 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -802,6 +802,15 @@ mode: will use a `dropdown` input. type: string required: false +translation_key: + description: > + Allows translations provided by an integration where `translation_key` + is the translation key that is providing the selector option strings + translation. See the documentation on + [Backend Localization](https://developers.home-assistant.io/docs/internationalization/core/#selectors) + for more information. + type: string + required: false {% endconfiguration %} Alternatively, a mapping can be used for the options. When you want to return diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 9c4fffd7ec4d..982ef60f95bf 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(', ') }} ``` @@ -309,6 +309,7 @@ The same thing can also be expressed as a test: ### Areas +- `areas()` returns the full list of area IDs - `area_id(lookup_value)` returns the area ID for a given device ID, entity ID, or area name. Can also be used as a filter. - `area_name(lookup_value)` returns the area name for a given device ID, entity ID, or area ID. Can also be used as a filter. - `area_entities(area_name_or_id)` returns the list of entity IDs tied to a given area ID or name. Can also be used as a filter. @@ -318,6 +319,10 @@ The same thing can also be expressed as a test: {% raw %} +```text +{{ areas() }} # ['area_id'] +``` + ```text {{ area_id('Living Room') }} # 'deadbeefdeadbeefdeadbeefdeadbeef' ``` @@ -450,7 +455,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 +470,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 +481,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 +686,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 +701,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 +894,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/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index b45a3ae4087b..00d0c66cce3e 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -681,7 +681,7 @@ Every individual condition can be disabled, without removing it. To do so, add `enabled: false` to the condition configuration. This can be useful if you want to temporarily disable a condition, for example, -for testing. A disabled condition will always pass. +for testing. A disabled condition will behave as if it were removed. For example: diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index c70bc53be070..dbf972094bfe 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -40,9 +40,17 @@

Topics

  • - Home Energy Management + {% active_link /docs/assist/ Assist %} + +
    • +
  • + {% active_link /docs/energy/ Home Energy Management %}
  • - Advanced Configuration + Advanced Configuration
  • - Core objects + Core objects
    • -### 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 d9aa73d9c530..000000000000 --- 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/analytics.markdown b/source/_integrations/analytics.markdown index b3804f367d7a..29da513a91e2 100644 --- a/source/_integrations/analytics.markdown +++ b/source/_integrations/analytics.markdown @@ -75,6 +75,7 @@ This includes: - The names of all your core integrations - The names and versions of all your custom integrations if you have any +- The name and version of the engine used in the [recorder integration](/integrations/recorder) - Boolean to indicate that the [energy integration](/integrations/energy) is configured - Boolean to indicate that [HTTP certificate](https://www.home-assistant.io/integrations/http/#ssl_certificate) is configured @@ -114,6 +115,10 @@ If your system includes the Supervisor, this will also contain: "energy": { "configured": true }, + "recorder": { + "engine": "sqlite", + "version": "123" + }, "certificate": false } ``` diff --git a/source/_integrations/anwb_energie.markdown b/source/_integrations/anwb_energie.markdown new file mode 100644 index 000000000000..043cab048cc3 --- /dev/null +++ b/source/_integrations/anwb_energie.markdown @@ -0,0 +1,20 @@ +--- +title: ANWB Energie +description: Get the energy market prices from ANWB Energie using the EnergyZero integration. +ha_category: + - Energy + - Sensor +ha_domain: anwb_energie +ha_release: 2023.2 +ha_integration_type: virtual +ha_supporting_domain: energyzero +ha_supporting_integration: energyzero +ha_codeowners: + - '@klaasnicolaas' +ha_config_flow: true +ha_platforms: + - sensor +ha_iot_class: Cloud Polling +--- + +{% include integrations/supported_brand.md %} \ No newline at end of file diff --git a/source/_integrations/bluetooth_adapters.markdown b/source/_integrations/bluetooth_adapters.markdown new file mode 100644 index 000000000000..6c1a2be3a1c6 --- /dev/null +++ b/source/_integrations/bluetooth_adapters.markdown @@ -0,0 +1,17 @@ +--- +title: Bluetooth Adapters +description: Bluetooth Adapters provides access to local and remote Bluetooth Adapters +ha_release: 2023.2 +ha_category: + - Other +ha_codeowners: + - '@bdraco' +ha_domain: bluetooth_adapters +ha_integration_type: system +--- + +Bluetooth Adapters provides access to local and remote Bluetooth Adapters to integrations that use Bluetooth. + +## Configuration + +This integration is not user configurable. diff --git a/source/_integrations/braviatv.markdown b/source/_integrations/braviatv.markdown index bde701d0c4bc..7ec2b1107c45 100644 --- a/source/_integrations/braviatv.markdown +++ b/source/_integrations/braviatv.markdown @@ -44,6 +44,52 @@ If you have previously set up your TV with any Home Assistant instances via PIN - On your TV, go to: **Settings** -> **Network** -> **Remote device settings** -> **Deregister remote device**. Disable and re-enable the **Control remotely** after. Menu titles may differ slightly between models. If needed, refer to your specific model's [manual](https://www.sony.com/electronics/support/manuals) for additional guidance. - Reset your TV to factory condition. +## Media Browser + +Using the Media Browser, you can view a list of all installed applications and TV channels and launch them. + +## Play Media service + +The `play_media` service can be used in a automation or script to switch to a specified application or TV channel. It selects the best matching application or channel according to the `media_content_id`: + + 1. Channel number *(i.e., '1' or '6')* + 2. Exact app or channel name *(i.e., 'Google Play' or 'CNN')* + 3. Substring in app or channel name *(i.e., 'BFM' in 'BFM TV')* + 4. URI-string of app or channel *(i.e., 'tv:dvbt?trip=9999.441.41104&srvName=BBC HD')* + +**Example to open YouTube app:** + +```yaml +service: media_player.play_media +target: + entity_id: media_player.bravia_tv +data: + media_content_id: "YouTube" + media_content_type: "app" +``` + +**Example to switch to channel number 11:** + +```yaml +service: media_player.play_media +target: + entity_id: media_player.bravia_tv +data: + media_content_id: 11 + media_content_type: "channel" +``` + +**Example to switch to channel including 'news' in its name:** + +```yaml +service: media_player.play_media +target: + entity_id: media_player.bravia_tv +data: + media_content_id: "news" + media_content_type: "channel" +``` + ## Remote The integration supports `remote` platform. The remote allows you to send key commands to your TV with the `remote.send_command` service. @@ -77,13 +123,19 @@ The commands that can be sent to the TV depends on the model of your TV. To disp {% enddetails %} -## Buttons +**Example to send `Down` key command:** -The integration supports `button` platform and allows you to reboot the device or terminate all running applications. +```yaml +service: remote.send_command +target: + entity_id: media_player.bravia_tv +data: + command: "Down" +``` -{% include integrations/option_flow.md %} +## Buttons -The integration allows you to customize the list of ignored sources. +The integration supports `button` platform and allows you to reboot the device or terminate all running applications. ## For TVs older than 2013 diff --git a/source/_integrations/calendar.markdown b/source/_integrations/calendar.markdown index ecafdee30801..174bc570baf6 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/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown index 4754c3a4c06c..cea20bb49a7e 100644 --- a/source/_integrations/climate.mqtt.markdown +++ b/source/_integrations/climate.mqtt.markdown @@ -83,6 +83,14 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +current_humidity_template: + description: A template with which the value received on `current_humidity_topic` will be rendered. + required: false + type: template +current_humidity_topic: + description: The MQTT topic on which to listen for the current humidity. + required: false + type: string current_temperature_template: description: A template with which the value received on `current_temperature_topic` will be rendered. required: false @@ -189,10 +197,20 @@ json_attributes_topic: description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. Usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation. required: false type: string +max_humidity: + description: The minimum target humidity percentage that can be set. + required: false + type: integer + default: 99 max_temp: description: Maximum set point available. type: float required: false +min_humidity: + description: The maximum target humidity percentage that can be set. + required: false + type: integer + default: 30 min_temp: description: Minimum set point available. type: float @@ -202,7 +220,7 @@ mode_command_template: required: false type: template mode_command_topic: - description: The MQTT topic to publish commands to change the HVAC operation mode. + description: The MQTT topic to publish commands to change the HVAC operation mode. Use with `mode_command_template` if you only want to publish the power state. required: false type: string mode_state_template: @@ -227,6 +245,11 @@ object_id: description: Used instead of `name` for automatic generation of `entity_id` required: false type: string +optimistic: + description: Flag that defines if the climate works in optimistic mode + required: false + type: boolean + default: "`true` if no state topic defined, else `false`." payload_available: description: The payload that represents the available state. required: false @@ -247,10 +270,6 @@ payload_on: required: false type: string default: "ON" -power_command_topic: - description: The MQTT topic to publish commands to change the power state. This is useful if your device has a separate power toggle in addition to mode. - required: false - type: string precision: description: The desired precision for this device. Can be used to match your actual thermostat's precision. Supported values are `0.1`, `0.5` and `1.0`. required: false @@ -308,6 +327,22 @@ swing_modes: required: false default: ['on', 'off'] type: list +target_humidity_command_template: + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `target_humidity_command_topic`. + required: false + type: template +target_humidity_command_topic: + description: The MQTT topic to publish commands to change the target humidity. + required: false + type: string +target_humidity_state_topic: + description: The MQTT topic subscribed to receive the target humidity. If this is not set, the target humidity works in optimistic mode (see below). + required: false + type: string +target_humidity_state_template: + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value for the climate `target_humidity` state. + required: false + type: string temperature_command_template: description: A template to render the value sent to the `temperature_command_topic` with. required: false @@ -377,7 +412,7 @@ value_template: ## Optimistic mode -If a property works in *optimistic mode* (when the corresponding state topic is not set), Home Assistant will assume that any state changes published to the command topics did work and change the internal state of the entity immediately after publishing to the command topic. If it does not work in optimistic mode, the internal state of the entity is only updated when the requested update is confirmed by the device through the state topic. +If a property works in *optimistic mode* (when the corresponding state topic is not set), Home Assistant will assume that any state changes published to the command topics did work and change the internal state of the entity immediately after publishing to the command topic. If it does not work in optimistic mode, the internal state of the entity is only updated when the requested update is confirmed by the device through the state topic. You can enforce optimistic mode by setting the `optimistic` option to `true`. When set, the internal state will always be updated, even when a state topic is defined. ## Using Templates @@ -410,6 +445,8 @@ Similarly for `*_command_topic`s, a template can be specified to render the outg A full configuration example looks like the one below. +{% raw %} + ```yaml # Full example configuration.yaml entry mqtt: @@ -430,11 +467,13 @@ mqtt: - "eco" - "sleep" - "activity" - power_command_topic: "study/ac/power/set" preset_mode_command_topic: "study/ac/preset_mode/set" mode_command_topic: "study/ac/mode/set" + mode_command_template: "{{ value if value=="off" else "on" }}" temperature_command_topic: "study/ac/temperature/set" fan_mode_command_topic: "study/ac/fan/set" swing_mode_command_topic: "study/ac/swing/set" precision: 1.0 ``` + +{% endraw %} \ No newline at end of file diff --git a/source/_integrations/conversation.markdown b/source/_integrations/conversation.markdown index f1038151e184..111a0cb45cb8 100644 --- a/source/_integrations/conversation.markdown +++ b/source/_integrations/conversation.markdown @@ -24,79 +24,146 @@ The conversation integration allows you to converse with Home Assistant. You can conversation: ``` -{% configuration %} -intents: - description: Intents that the conversation integration should understand. - required: false - type: map - keys: - '``': - description: Sentences that should trigger this intent. - required: true - type: list -{% endconfiguration %} +## Default sentences + +By default, a collection of [community contributed sentences](https://github.com/home-assistant/intents/) are supported in a growing [list of languages](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages). + +In English, you can say things like "turn on kitchen lights" or "turn off lights in the bedroom" if you have an area named "bedroom". ## Adding custom sentences -By default, it will support turning devices on and off. You can say things like "turn on kitchen lights" or "turn the living room lights off". You can also configure your own sentences to be processed. This works by mapping sentences to intents and then configure the [intent script integration](/integrations/intent_script/) to handle these intents. +You can add your own [sentence templates](https://developers.home-assistant.io/docs/voice/intent-recognition/template-sentence-syntax) to teach Home Assistant about new sentences. These sentences can work with the [built-in intents](https://developers.home-assistant.io/docs/intent_builtin/) or trigger a custom action by defining custom intents with the [intent script integration](/integrations/intent_script/). -Here is a simple example to be able to ask what the temperature in the living room is. +To get started, create a `custom_sentences/` directory in your Home Assistant `config` directory where `` is the [language code](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages) of your language, such as `en` for English. These YAML files are automatically merged, and may contain intents, lists, or expansion rules. + +For an English example, create the file `config/custom_sentences/en/temperature.yaml` and add: {% raw %} ```yaml -# Example configuration.yaml entry -conversation: - intents: - LivingRoomTemperature: - - What is the temperature in the living room +# Example temperature.yaml entry +language: "en" +intents: + CustomOutsideHumidity: + data: + - sentences: + - "What is the humidity outside" +``` + +{% endraw %} + +To teach Home Assistant how to handle the custom `CustomOutsideHumidity` intent, create an `intent_script` entry in your `configuration.yaml` file: +{% raw %} + +```yaml +# Example configuration.yaml entry intent_script: - LivingRoomTemperature: + CustomOutsideHumidity: speech: - text: It is currently {{ states.sensor.temperature }} degrees in the living room. + text: "It is currently {{ states("sensor.outside_humidity") }} percent humidity outside." ``` {% endraw %} -## Adding advanced custom sentences +More complex [actions](/docs/scripts/) can be done in `intent_script`, such as calling services and firing events. -Sentences can contain slots (marked with curly braces: `{name}`) and optional words (marked with square brackets: `[the]`). The values of slots will be passed on to the intent and are available inside the templates. -The following configuration can handle the following sentences: +## Extending built-in intents -- Change the lights to red -- Change the lights to green -- Change the lights to blue -- Change the lights to the color red -- Change the lights to the color green -- Change the lights to the color blue +Extending the built-in intents, such as `HassTurnOn` and `HassTurnOff`, can be done as well. + +For example, create the file `config/custom_sentences/en/on_off.yaml` and add: {% raw %} ```yaml -# Example configuration.yaml entry -conversation: - intents: - ColorLight: - - Change the lights to [the color] {color} -intent_script: - ColorLight: - speech: - text: Changed the lights to {{ color }}. - action: - service: light.turn_on - data: - rgb_color: - - "{% if color == 'red' %}255{% else %}0{% endif %}" - - "{% if color == 'green' %}255{% else %}0{% endif %}" - - "{% if color == 'blue' %}255{% else %}0{% endif %}" +# Example on_off.yaml entry +language: "en" +intents: + HassTurnOn: + data: + - sentences: + - "engage [the] kitchen lights" + slots: + name: "kitchen lights" + HassTurnOff: + data: + - sentences: + - "disengage [the] kitchen lights" + slots: + name: "kitchen lights" +``` + +{% endraw %} + +Now when you say "engage the kitchen lights", it will turn on a light named "kitchen lights". Saying "disengage kitchen lights" will turn it off. + +Let's generalize this to other entities. The built-in `{name}` and `{area}` lists contain the names of your Home Assistant entities and areas. + +Adding `{name}` to `config/custom_sentences/en/on_off.yaml`: + +{% raw %} + +```yaml +# Example on_off.yaml entry +language: "en" +intents: + HassTurnOn: + data: + - sentences: + - "engage [the] {name}" + HassTurnOff: + data: + - sentences: + - "disengage [the] {name}" ``` {% endraw %} +You can now "engage" or "disengage" any entity. + +Lastly, let's add sentences for turning lights on and off in specific areas: + +{% raw %} + +```yaml +# Example on_off.yaml entry +language: "en" +intents: + HassTurnOn: + data: + - sentences: + - "engage [the] {name}" + - sentences: + - "engage [all] lights in [the] {area}" + slots: + name: "all" + domain: "light" + HassTurnOff: + data: + - sentences: + - "disengage [the] {name}" + - sentences: + - "disengage [all] lights in [the] {area}" + slots: + name: "all" + domain: "light" +``` + +{% endraw %} + +It's now possible to say "engage all lights in the bedroom", which will turn on every light in the area named "bedroom". + + ## Service `conversation.process` -| Service data attribute | Optional | Description | -|------------------------|----------|--------------------------------------------------| -| `text` | yes | Transcribed text | +| Service data attribute | Optional | Description | +|------------------------|----------|------------------| +| `text` | yes | Transcribed text | + +## Service `conversation.reload` + +| Service data attribute | Optional | Description | +|------------------------|----------|--------------------------------------------------------------------------| +| `language` | yes | Language to clear intent cache for. Defaults to Home Assistant language. | diff --git a/source/_integrations/default_config.markdown b/source/_integrations/default_config.markdown index a075a1f87bdb..a14035a942aa 100644 --- a/source/_integrations/default_config.markdown +++ b/source/_integrations/default_config.markdown @@ -17,6 +17,7 @@ This integration is a meta-component and configures a default set of integration - [Backup](/integrations/backup/) (`backup`) - [Bluetooth](/integrations/bluetooth/) (`bluetooth`) - [Configuration](/integrations/config/) (`config`) +- [Conversation](/integrations/conversation/) (`conversation`) - [Counter](/integrations/counter/) (`counter`) - [DHCP Discovery](/integrations/dhcp/) (`dhcp`) - [Energy](/integrations/energy/) (`energy`) diff --git a/source/_integrations/denonavr.markdown b/source/_integrations/denonavr.markdown index 8f794e6e4e15..ef48dfd01217 100644 --- a/source/_integrations/denonavr.markdown +++ b/source/_integrations/denonavr.markdown @@ -50,6 +50,8 @@ Known supported devices: - Denon AVR-X4700H - Denon AVR-X6500H - Denon AVR-X6700H +- Denon AVR-X7200W +- Denon AVR-X8500H - Denon AVR-1912 - Denon AVR-2112CI - Denon AVR-2312CI @@ -106,15 +108,20 @@ host: description: IP address of the device, e.g., 192.168.1.32. If not set, auto-discovery is used. show_all_sources: description: If True all sources are displayed in sources list even if they are marked as deleted in the receiver. If False deleted sources are not displayed. Some receivers have a bug that marks all sources as deleted in the interface. In this case, this option could help. -zone1: - description: Specifies if zone 1 should be activated. Zones are displayed as additional media players with the same functionality as the Main Zone of the device supports. zone2: - description: Specifies if zone 2 should be activated. Zones are displayed as additional media players with the same functionality as the Main Zone of the device supports. Some receivers do not support a second zone. + description: Specifies if zone 2 should be activated. Zones are displayed as additional media players with the same functionality as the Main Zone of the device supports. +zone3: + description: Specifies if zone 3 should be activated. Zones are displayed as additional media players with the same functionality as the Main Zone of the device supports. Some receivers do not support a second zone. update_audyssey: description: Specifies if Audyssey settings should be updated. This can take up to 10 seconds for some receivers. required: false default: false type: boolean +use_telnet: + description: Specifies if a telnet connection should be used to receive device status updates. Using telnet provides realtime updates (local push) for many values but each receiver is limited to a single connection. If you enable this setting, no other connection to your device can be made via telnet. This will be set to true for new installations of the integration but false for existing installs to prevent compatibility issues. + required: false + default: true + type: boolean {% endconfiguration_basic %} A few notes: diff --git a/source/_integrations/devolo_home_network.markdown b/source/_integrations/devolo_home_network.markdown index d08b5aad986e..98a43c8803d9 100755 --- a/source/_integrations/devolo_home_network.markdown +++ b/source/_integrations/devolo_home_network.markdown @@ -5,6 +5,7 @@ ha_category: - Binary Sensor - Presence Detection - Sensor + - Switch ha_release: '2021.12' ha_iot_class: Local Polling ha_config_flow: true @@ -17,6 +18,7 @@ ha_platforms: - binary_sensor - device_tracker - sensor + - switch ha_zeroconf: true ha_integration_type: device --- @@ -53,14 +55,25 @@ Currently the following device types within Home Assistant are supported. * Updates every 5 minutes * Is disabled by default because it typically rarely changes +### Switch + +* Turn on/off guest wifi + * Is enabled by default +* Turn on/off the device LEDs + * Is enabled by default + ## Supported devolo Devices The list of supported devolo devices depends on the device firmware and the device features. The following devices were tested running firmware 5.6.0: +* Magic 2 WiFi 6 * Magic 2 WiFi next * Magic 2 WiFi 2-1 * Magic 1 WiFi mini * Magic 1 WiFi 2-1 +* WiFi 6 Repeater 5400 +* WiFi 6 Repeater 3000 +* WiFi Repeater+ ac * dLAN 1200+ WiFi ac * dLAN 550+ Wifi * dLAN 550 WiFi diff --git a/source/_integrations/dlink.markdown b/source/_integrations/dlink.markdown index e604a87b619f..9f36c0b88b67 100644 --- a/source/_integrations/dlink.markdown +++ b/source/_integrations/dlink.markdown @@ -5,53 +5,25 @@ ha_category: - Switch ha_iot_class: Local Polling ha_release: 0.14 +ha_config_flow: true +ha_dhcp: true ha_domain: dlink ha_platforms: - switch -ha_integration_type: integration +ha_codeowners: + - '@tkdrob' +ha_integration_type: device --- -The `dlink` switch platform allows you to control the state of your [D-Link Wi-Fi Smart Plugs](https://us.dlink.com/en/consumer/smart-home). +The D-Link Wi-Fi Smart Plugs integration allows you to control the state of your [D-Link Wi-Fi Smart Plugs](https://us.dlink.com/en/consumer/smart-home). + +{% include integrations/config_flow.md %} Supported devices (tested): - DSP-W215 - DSP-W110 -To use your D-Link smart plugs in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -switch: - - platform: dlink - host: IP_ADRRESS - username: YOUR_USERNAME - password: YOUR_PASSWORD -``` +Password: The default password is the PIN included on the configuration card or on the back of the unit. -{% configuration %} -host: - description: "The IP address of your D-Link plug, e.g., 192.168.1.32." - required: true - type: string -name: - description: The name to use when displaying this switch. - required: false - default: D-link Smart Plug W215 - type: string -username: - description: The username for your plug. - required: true - default: admin - type: string -password: - description: The password for your plug. - required: true - default: The default password is the `PIN` included on the configuration card. - type: string -use_legacy_protocol: - description: Enable limited support for legacy firmware protocols (Tested with v1.24, v1.26). - required: false - default: false - type: boolean -{% endconfiguration %} +Use the legacy protocol in case the integration does not work. This enables limited support for legacy firmware protocols (Tested with v1.24, v1.26). Data such as power consumption will not be available. The temperature will also show a freezing level. diff --git a/source/_integrations/dormakaba_dkey.markdown b/source/_integrations/dormakaba_dkey.markdown new file mode 100644 index 000000000000..dd0e760b71c0 --- /dev/null +++ b/source/_integrations/dormakaba_dkey.markdown @@ -0,0 +1,27 @@ +--- +title: Dormakaba dKey +description: Instructions on how to integrate Dormakaba dKey locks into Home Assistant. +ha_category: + - Lock +ha_bluetooth: true +ha_release: 2023.3 +ha_iot_class: Local Polling +ha_codeowners: + - '@emontnemery' +ha_domain: dormakaba_dkey +ha_config_flow: true +ha_platforms: + - binary_sensor + - lock + - sensor +ha_integration_type: device +--- + +Integrates Dormakaba dKey Bluetooth Low Energy connected locks into Home Assistant. + +{% include integrations/config_flow.md %} + +In addition to a lock entity, each added dKey lock will also have: +- A battery sensor +- A binary_sensor which shows if the door is open or not +- A binary_sensor which shows the position of the lock's dead bolt diff --git a/source/_integrations/easyenergy.markdown b/source/_integrations/easyenergy.markdown new file mode 100644 index 000000000000..cd71cee2981f --- /dev/null +++ b/source/_integrations/easyenergy.markdown @@ -0,0 +1,54 @@ +--- +title: easyEnergy +description: Instructions on how to integrate easyEnergy within Home Assistant. +ha_category: + - Energy + - Sensor +ha_release: 2023.3 +ha_iot_class: Cloud Polling +ha_config_flow: true +ha_codeowners: + - '@klaasnicolaas' +ha_domain: easyenergy +ha_platforms: + - sensor +ha_quality_scale: platinum +ha_integration_type: integration +--- + +The easyEnergy integration integrates the [easyEnergy](https://www.easyenergy.com) API platform with Home Assistant. + +The integration makes it possible to retrieve the dynamic energy/gas prices +from easyEnergy in order to gain insight into the price trend of the day and +to adjust your consumption accordingly. + +Companies that use the data from easyEnergy: + +- [NieuweStroom](https://nieuwestroom.nl) + +{% include integrations/config_flow.md %} + +## Sensors + +The easyEnergy integration creates a number of sensor entities for both gas +and electricity prices. + +### Energy market prices + +In terms of electricity you get two separate services, easyEnergy uses separate +prices for electricity that you use (buy) or return (sell). Every day around +**14:00 UTC time**, the new prices are published for the following day. + +- The `current` and `next hour` electricity market price +- Average electricity price of the day +- Lowest energy price +- Highest energy price +- Time of day when the price is highest +- Time of day when the price is at its lowest +- Percentage of the current price compared to the maximum price + +### Gas market price + +For the dynamic gas prices, only entities are created that display the +`current` and `next hour` price because the price is always fixed for +24 hours; new prices are published every morning at **05:00 UTC time**. \ No newline at end of file diff --git a/source/_integrations/elgato.markdown b/source/_integrations/elgato.markdown index 3b010b62f5e0..21edb1daaedd 100644 --- a/source/_integrations/elgato.markdown +++ b/source/_integrations/elgato.markdown @@ -15,6 +15,8 @@ ha_platforms: - button - diagnostics - light + - sensor + - switch ha_integration_type: device --- @@ -27,6 +29,7 @@ integration: - [Elgato Key Light](https://www.elgato.com/en/key-light) - [Elgato Key Light Air](https://www.elgato.com/en/key-light-air) +- [Elgato Key Light Mini](https://www.elgato.com/en/key-light-mini) - [Elgato Ring Light](https://www.elgato.com/en/ring-light) - [Elgato Light Strip](https://www.elgato.com/en/light-strip) @@ -40,6 +43,23 @@ allows you to control the color temperature, brightness, and its on/off state. When using the Elgato Light Strip, color support is automatically detected and enabled in Home Assistant. +## Other entities + +Besides the above mentioned light entity, this integration also provides other +secondary entities that can be useful for monitoring and controlling your +Elgato light. + +### Sensors + +If you have a Key Light Mini, Home Assistant will provide an additional +sensor that indicates the level of your battery in percent (%). + +### Switches + +If you have a Key Light Mini, Home Assistant will provide an additional +switch that allows the control of the "Studio mode" of your light. When +studio mode is enabled, your battery will not be used and bypassed. + ## Services ### Service `elgato.identify` diff --git a/source/_integrations/energie_vanons.markdown b/source/_integrations/energie_vanons.markdown new file mode 100644 index 000000000000..f5754bfc4342 --- /dev/null +++ b/source/_integrations/energie_vanons.markdown @@ -0,0 +1,20 @@ +--- +title: Energie VanOns +description: Get the energy market prices from Energie VanOns using the EnergyZero integration. +ha_category: + - Energy + - Sensor +ha_domain: energie_vanons +ha_release: 2023.2 +ha_integration_type: virtual +ha_supporting_domain: energyzero +ha_supporting_integration: energyzero +ha_codeowners: + - '@klaasnicolaas' +ha_config_flow: true +ha_platforms: + - sensor +ha_iot_class: Cloud Polling +--- + +{% include integrations/supported_brand.md %} \ No newline at end of file diff --git a/source/_integrations/energyzero.markdown b/source/_integrations/energyzero.markdown new file mode 100644 index 000000000000..4bf6d1dc2f4b --- /dev/null +++ b/source/_integrations/energyzero.markdown @@ -0,0 +1,53 @@ +--- +title: EnergyZero +description: Instructions on how to integrate EnergyZero within Home Assistant. +ha_category: + - Energy +ha_release: 2023.2 +ha_iot_class: Cloud Polling +ha_config_flow: true +ha_codeowners: + - '@klaasnicolaas' +ha_domain: energyzero +ha_platforms: + - sensor +ha_quality_scale: platinum +ha_integration_type: integration +--- + +The EnergyZero integration integrates the [EnergyZero](https://www.energyzero.nl/) API platform with Home Assistant. + +The integration makes it possible to retrieve the dynamic energy/gas prices +from EnergyZero in order to gain insight into the price trend of the day and +to adjust your consumption accordingly. + +Partners who purchase their energy through EnergyZero: + +- [ANWB Energie](https://www.anwb.nl/huis/energie/anwb-energie) +- [Mijndomein Energie](https://www.mijndomein.nl/energie) +- [Energie van Ons](https://www.energie.vanons.org) +- [GroeneStroomLokaal](https://www.groenestroomlokaal.nl) + +{% include integrations/config_flow.md %} + +## Sensors + +The EnergyZero integration creates a number of sensor entities for both gas and electricity prices. + +### Energy market price + +Every day around **14:00 UTC time**, the new prices are published for the following day. + +- The `current` and `next hour` electricity market price +- Average electricity price of the day +- Lowest energy price +- Highest energy price +- Time of day when the price is highest +- Time of day when the price is at its lowest +- Percentage of the current price compared to the maximum price + +### Gas market price + +For the dynamic gas prices, only entities are created that display the +`current` and `next hour` price because the price is always fixed for +24 hours; new prices are published every morning at **05:00 UTC time**. \ No newline at end of file diff --git a/source/_integrations/eufy.markdown b/source/_integrations/eufy.markdown index 71984a4a5f7c..77a3059d6745 100644 --- a/source/_integrations/eufy.markdown +++ b/source/_integrations/eufy.markdown @@ -1,6 +1,6 @@ --- -title: eufy -description: Instructions on how to integrate Eufy devices into Home Assistant. +title: EufyHome +description: Instructions on how to integrate EufyHome devices into Home Assistant. ha_category: - Hub - Light @@ -14,14 +14,14 @@ ha_platforms: ha_integration_type: integration --- -The `eufy` integration is the main integration to integrate various [eufy](https://www.eufylife.com/) devices with Home Assistant. +The EufyHome integration is the main integration to integrate [eufy](https://eufy.com/) devices sold under the EufyHome product line with Home Assistant. There is currently support for the following device types within Home Assistant: - Light - Switch -Supported devices will be discovered after the `eufy` integration is configured: +Supported devices will be discovered after the EufyHome integration is configured: ```yaml # Example configuration.yaml entry @@ -30,7 +30,7 @@ eufy: password: PASSWORD ``` -where username and password are the ones configured in the EufyHome app. Alternately, Eufy devices that are not discoverable can be statically configured. +where username and password are the ones configured in the EufyHome app. Alternately, EufyHome devices that are not discoverable can be statically configured. ```yaml eufy: @@ -45,7 +45,7 @@ eufy: name: Smart Switch ``` -`access_token can be obtained by running: +`access_token` can be obtained by running: ```bash $ curl -H "Content-Type: application/json" \ @@ -53,7 +53,7 @@ $ curl -H "Content-Type: application/json" \ https://home-api.eufylife.com/v1/user/email/login ``` -replacing USERNAME and PASSWORD with the Eufy username and password. This will give an `access_token`. Then run: +replacing USERNAME and PASSWORD with the EufyHome username and password. This will give an `access_token`. Then run: ```bash $ curl -H token:TOKEN -H category:Home \ diff --git a/source/_integrations/eufylife_ble.markdown b/source/_integrations/eufylife_ble.markdown new file mode 100644 index 000000000000..c58e4999bf09 --- /dev/null +++ b/source/_integrations/eufylife_ble.markdown @@ -0,0 +1,41 @@ +--- +title: EufyLife +description: Instructions on how to integrate your EufyLife Bluetooth device with Home Assistant. +ha_release: '2023.2' +ha_category: + - Sensor +ha_iot_class: Local Push +ha_config_flow: true +ha_codeowners: + - '@bdr99' +ha_domain: eufylife_ble +ha_platforms: + - sensor +ha_integration_type: integration +--- + +The EufyLife integration allows you to integrate Eufy smart scales with Home Assistant. + +## Supported devices + +- [Smart Scale (T9140)](https://www.eufy.com/products/t9140) +- [Smart Scale C1 (T9146)](https://www.eufy.com/products/t9146) +- [Smart Scale P1 (T9147)](https://www.eufy.com/products/t9147) +- [Smart Scale P2 (T9148)](https://www.eufy.com/products/t9148) +- [Smart Scale P2 Pro (T9149)](https://www.eufy.com/products/t9149111) + +
    + +This integration does not support the Wi-Fi capabilities of the P2 and P2 Pro. It can only connect to your smart scale via Bluetooth. + +
    + +## Features + +All smart scale models provide a weight sensor entity and a real-time weight sensor entity. The real-time weight entity updates in real time while the scale is taking a weight measurement. The weight entity updates with the final weight value only when the scale is finished taking a weight measurement. + +The Smart Scale P2 Pro additionally provides a heart rate sensor entity that will display the most recent heart rate measurement taken by the scale. + +The EufyLife integration will automatically discover devices once the [Bluetooth](/integrations/bluetooth) integration is enabled and functional. Alternatively, follow the steps below to add the integration manually. + +{% include integrations/config_flow.md %} diff --git a/source/_integrations/fire_tv.markdown b/source/_integrations/fire_tv.markdown new file mode 100644 index 000000000000..3c9a2693791f --- /dev/null +++ b/source/_integrations/fire_tv.markdown @@ -0,0 +1,21 @@ +--- +title: Amazon Fire TV +description: Instructions on how to integrate Amazon Fire TV devices into Home Assistant. +ha_category: + - Media Player +ha_domain: fire_tv +ha_integration_type: virtual +ha_supporting_domain: androidtv +ha_supporting_integration: Android TV +ha_release: 0.7.6 +ha_codeowners: + - '@JeffLIrion' + - '@ollo69' +ha_config_flow: true +ha_platforms: + - diagnostics + - media_player +ha_iot_class: Local Polling +--- + +{% include integrations/supported_brand.md %} diff --git a/source/_integrations/fritzbox_callmonitor.markdown b/source/_integrations/fritzbox_callmonitor.markdown index 077044e40bfb..eeea5b06f85c 100644 --- a/source/_integrations/fritzbox_callmonitor.markdown +++ b/source/_integrations/fritzbox_callmonitor.markdown @@ -19,7 +19,7 @@ It can also access the internal phone book of the router to look up the names co ## Prerequisites -To use the FRITZ!Box call monitor in your installation, a user with at least `FRITZ!Box Settings` and `Voice messages, faxes, FRITZ!App Fon and call list` rights has to be created: +To use the FRITZ!Box call monitor in your installation, a user with at least `Voice messages, faxes, FRITZ!App Fon and call list` rights has to be created: 1. Open the web user interface via `fritz.box` or the IP address of your FRITZ!Box (e.g. `192.168.1.1`). 2. Log in with your admin user credentials. The default admin user credentials can be found at the bottom of your FRITZ!Box. @@ -27,7 +27,7 @@ To use the FRITZ!Box call monitor in your installation, a user with at least `FR 4. Click the `Add User` button. 5. Enable the option `User account enabled`. 6. Enter a user name and password. -7. Check the rights boxes next to `FRITZ!Box Settings`, which automatically checks the boxes for `Voice messages, faxes, FRITZ!App Fon and call list` and `Smart Home`. +7. Check the rights box next to `Voice messages, faxes, FRITZ!App Fon and call list`. 8. Click the `Apply` button. ## Setup diff --git a/source/_integrations/frontend.markdown b/source/_integrations/frontend.markdown index f4ea78e709ec..867d96ad78d1 100644 --- a/source/_integrations/frontend.markdown +++ b/source/_integrations/frontend.markdown @@ -51,7 +51,7 @@ frontend: ### Theme format -The frontend integration allows you to create custom themes to influence the look and feel of the user interface. Note that we only officially support the `primary-color` and `accent-color` properties. Although we do our best to keep things working, the behavior of other properties can change between releases. +The frontend integration allows you to create custom themes to influence the look and feel of the user interface. ```yaml # Example configuration.yaml entry @@ -59,13 +59,50 @@ frontend: themes: happy: primary-color: pink - text-primary-color: purple - mdc-theme-primary: plum + accent-color: orange sad: primary-color: steelblue + accent-color: darkred ``` -The example above defines two themes named `happy` and `sad`. For each theme, you can set values for CSS variables. If you want to provide hex color values, wrap those in apostrophes, since otherwise, YAML would consider them a comment (`primary-color: '#123456'`). For a partial list of variables used by the main frontend see [ha-style.ts](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/resources/ha-style.ts). +The example above defines two themes named `happy` and `sad`. For each theme, you can set values for CSS variables. If you want to provide hex color values, wrap those in apostrophes, since otherwise, YAML would consider them a comment (`primary-color: "#123456"`). + +### Supported theme variables + +#### Primary and accent color + +Primary and accent colors are the main colors of the application. +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 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`. + +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 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 +frontend: + themes: + my_theme: + state-cover-garage_door-open-color: "#ff0000" + state-media_player-inactive-color: "#795548" +``` + +The example above defines red color for open garage doors and brown color for inactive media players. + +### Unsupported theme variables + +Although we do our best to keep things working, the behavior of other theme variables can change between releases. For a partial list of variables used by the main frontend see [ha-style.ts](https://github.com/home-assistant/frontend/blob/master/src/resources/ha-style.ts). ### Dark mode support @@ -82,7 +119,6 @@ frontend: happy: primary-color: pink text-primary-color: purple - mdc-theme-primary: plum sad: primary-color: steelblue modes: diff --git a/source/_integrations/google_assistant_sdk.markdown b/source/_integrations/google_assistant_sdk.markdown index e2f10af023e2..6ee45742f9ee 100644 --- a/source/_integrations/google_assistant_sdk.markdown +++ b/source/_integrations/google_assistant_sdk.markdown @@ -8,7 +8,7 @@ ha_release: 2023.1 ha_config_flow: true ha_domain: google_assistant_sdk ha_codeowners: - - '@tronikos' + - "@tronikos" ha_integration_type: service ha_platforms: - notify @@ -29,6 +29,12 @@ This integration allows: - Someone is at the front door - Smoke detected in the master bedroom - Water leak detected in the master bathroom +- Playback Google Assistant audio response for any query on any media player. Examples: + - Tell me a joke + - Say the ABC + - Sing happy birthday + - What does the elephant say? +- Having a conversation with Google Assistant using the [conversation](/integrations/conversation/) integration via text or voice. @@ -48,18 +54,18 @@ This section explains how to generate a Client ID and Client Secret on 3. Click to enable this API. 4. Click on the field on the left of the screen, **OAuth Consent Screen**. 5. Select **External** and **Create**. -6. Set the *App Name* (the name of the application asking for consent) to anything you want e.g. *Home Assistant*. -7. You then need to select a *Support email*. To do this, simply click the drop down box and select your email address. -8. You finally need to complete the section: *Developer contact information*. To do this, simply enter your email address (same as above is fine). +6. Set the _App Name_ (the name of the application asking for consent) to anything you want e.g. _Home Assistant_. +7. You then need to select a _Support email_. To do this, simply click the drop down box and select your email address. +8. You finally need to complete the section: _Developer contact information_. To do this, simply enter your email address (same as above is fine). 9. Scroll to the bottom and click **Save and Continue**. Don't have to fill out anything else or it may enable additional review. 10. You will then be automatically taken to the Scopes page. You do not need to add any scopes here so click Save and Continue to move to the Optional info page. You do not need to add anything to the Optional info page so click Save and Continue which will take you to the Summary page. Click Back to Dashboard. -11. Click **OAuth consent screen** again and set *Publish Status* to **Production** otherwise your credentials will expire every 7 days. +11. Click **OAuth consent screen** again and set _Publish Status_ to **Production** otherwise your credentials will expire every 7 days. 12. Make sure **Publishing status** is set to production. -13. Click **Credentials** in the menu on the left hand side of the screen, then click **Create credentials** (at the top of the screen), then select *OAuth client ID*. -14. Set the Application type to *Web application* and give this credential set a name (like "Home Assistant Credentials"). -15. Add https://my.home-assistant.io/redirect/oauth to *Authorized redirect URIs* then click **Create**. -16. You will then be presented with a pop-up saying *OAuth client created* showing *Your Client ID* and *Your Client Secret*. Make a note of these (for example, copy and paste them into a text editor) as you will need these shortly. Once you have noted these strings, click **OK**. If you need to find these credentials again at any point then simply navigate to *APIs & Services > Credentials* and you will see *Home Assistant Credentials* (or whatever you named them in the previous step) under *OAuth 2.0 Client IDs*. To view both the *Client ID* and *Client secret*, click on the pencil icon, this will take you to the settings page for these credentials and the information will be on the right hand side of the page. -17. Double check that the *Google Assistant API* has been automatically enabled. To do this, select **Library** from the menu, then search for *Google Assistant API*. If it is enabled you will see *API Enabled* with a green tick next to it. If it is not enabled, then enable it. +13. Click **Credentials** in the menu on the left hand side of the screen, then click **Create credentials** (at the top of the screen), then select _OAuth client ID_. +14. Set the Application type to _Web application_ and give this credential set a name (like "Home Assistant Credentials"). +15. Add https://my.home-assistant.io/redirect/oauth to _Authorized redirect URIs_ then click **Create**. +16. You will then be presented with a pop-up saying _OAuth client created_ showing _Your Client ID_ and _Your Client Secret_. Make a note of these (for example, copy and paste them into a text editor) as you will need these shortly. Once you have noted these strings, click **OK**. If you need to find these credentials again at any point then simply navigate to _APIs & Services > Credentials_ and you will see _Home Assistant Credentials_ (or whatever you named them in the previous step) under _OAuth 2.0 Client IDs_. To view both the _Client ID_ and _Client secret_, click on the pencil icon, this will take you to the settings page for these credentials and the information will be on the right hand side of the page. +17. Double check that the _Google Assistant API_ has been automatically enabled. To do this, select **Library** from the menu, then search for _Google Assistant API_. If it is enabled you will see _API Enabled_ with a green tick next to it. If it is not enabled, then enable it. {% enddetails %} @@ -75,9 +81,9 @@ The integration setup will next give you instructions to enter the [Application 3. You can now see the details of what you are authorizing Home Assistant to access with two options at the bottom. Click **Continue**. -4. The page will now display *Link account to Home Assistant?*, note *Your instance URL*. If this is not correct, please refer to [My Home Assistant](/integrations/my). If everything looks good, click **Link Account**. +4. The page will now display _Link account to Home Assistant?_, note _Your instance URL_. If this is not correct, please refer to [My Home Assistant](/integrations/my). If everything looks good, click **Link Account**. -5. You may close the window, and return back to Home Assistant where you should see a *Success!* message from Home Assistant. +5. You may close the window, and return back to Home Assistant where you should see a _Success!_ message from Home Assistant. {% enddetails %} @@ -107,24 +113,42 @@ You can use the service `google_assistant_sdk.send_text_command` to send command | Service data attribute | Optional | Description | Example | | ---------------------- | -------- | ----------- | --------| -| `command` | no | Command to send to Google Assistant. | turn off kitchen TV | +| `command` | no | Command(s) to send to Google Assistant. | turn off kitchen TV | +| `media_player` | yes | Name(s) of media player entities to play response on | media_player.living_room_speaker | -Example: +Examples: ```yaml service: google_assistant_sdk.send_text_command data: - command: turn off kitchen TV + command: "turn off kitchen TV" +``` + +```yaml +# Say a joke on the living room speaker +service: google_assistant_sdk.send_text_command +data: + command: "tell me a joke" + media_player: media_player.living_room_speaker + +You can also send multiple commands in the same conversation context which is useful to unlock doors or open covers that need a PIN. Example: + +```yaml +service: google_assistant_sdk.send_text_command +data: + command: + - "open the garage door" + - "1234" ``` ### Service `notify.google_assistant_sdk` You can use the service `notify.google_assistant_sdk` to broadcast messages to Google Assistant speakers and displays without interrupting music/video playback. -| Service data attribute | Optional | Description | Example | -| ---------------------- | -------- | ----------- | --------| -| `message` | no | Message to broadcast. | someone is at the front door | -| `target` | yes | Rooms (in Google Assistant) | bedroom | +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | --------------------------- | ---------------------------- | +| `message` | no | Message to broadcast. | someone is at the front door | +| `target` | yes | Rooms (in Google Assistant) | bedroom | Example to broadcast to all speakers: @@ -144,3 +168,19 @@ data: - bedroom - basement ``` + +## Conversation agent + +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) + +Or by calling the `conversation.process` service with the transcribed text: + +```yaml +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/google_mail.markdown b/source/_integrations/google_mail.markdown new file mode 100644 index 000000000000..1a41ac5c9ee9 --- /dev/null +++ b/source/_integrations/google_mail.markdown @@ -0,0 +1,123 @@ +--- +title: Google Mail +description: Instructions on how to use Google Mail in Home Assistant. +ha_category: + - Notifications +ha_iot_class: Cloud Polling +ha_release: '2023.2' +ha_config_flow: true +ha_domain: google_mail +ha_platforms: + - notify + - sensor +ha_codeowners: + - '@tkdrob' +ha_integration_type: device +--- + +The Google Mail integration allows you to connect your [Google Mail](https://mail.google.com) to Home Assistant. The integration adds a service to allow you to set an email auto-response for when you go on vacation. A `notify` service is also added, allowing you to draft or send emails in plain text. + +## Prerequisites + +You need to configure developer credentials to allow Home Assistant to access your Google Account. +These credentials are the same as the ones for [Nest](/integrations/nest) and [Google Sheets](/integrations/google_sheets). +If you have already set up credentials, you can do step 1 and then skip to step 13 on the below instructions. + +{% details "Generate Client ID and Client Secret" %} + +This section explains how to generate a Client ID and Client Secret on +[Google Developers Console](https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=home-assistant-17698). + +1. First, go to the Google Developers Console to enable [Google Mail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=home-assistant-17698) +2. The wizard will ask you to choose a project to manage your application. Select a project and click continue. +3. Verify that your drive API was enabled and click 'Go to credentials' +4. Navigate to APIs & Services (left sidebar) > [Credentials](https://console.cloud.google.com/apis/credentials) +5. Click on the field on the left of the screen, **OAuth Consent Screen**. +6. Select **External** and **Create**. +7. Set the *App Name* (the name of the application asking for consent) to anything you want, e.g., *Home Assistant*. +8. You then need to select a *Support email*. To do this, click the drop-down box and select your email address. +9. You finally need to complete the section: *Developer contact information*. To do this, enter your email address (the same as above is fine). +10. Scroll to the bottom and click **Save and Continue**. You don't have to fill out anything else, or it may enable additional review. +11. You will then be automatically taken to the Scopes page. You do not need to add any scopes here, so click Save and Continue to move to the Optional info page. You do not need to add anything to the Optional info page, so click Save and Continue, which will take you to the Summary page. Click Back to Dashboard. +12. Click **OAuth consent screen** again and set *Publish Status* to **Production** otherwise your credentials will expire every 7 days. +13. Make sure **Publishing status** is set to production. +14. Click **Credentials** in the menu on the left-hand side of the screen, then click **Create credentials** (at the top of the screen), then select *OAuth client ID*. +15. Set the Application type to *Web application* and give this credential set a name (like "Home Assistant Credentials"). +16. Add https://my.home-assistant.io/redirect/oauth to *Authorized redirect URIs* then click **Create**. +17. You will then be presented with a pop-up saying *OAuth client created* showing *Your Client ID* and *Your Client Secret*. Make a note of these (for example, copy and paste them into a text editor), as you will need these shortly. Once you have noted these strings, click **OK**. If you need to find these credentials again at any point, then navigate to *APIs & Services > Credentials*, and you will see *Home Assistant Credentials* (or whatever you named them in the previous step) under *OAuth 2.0 Client IDs*. To view both the *Client ID* and *Client secret*, click on the pencil icon; this will take you to the settings page for these credentials, and the information will be on the right-hand side of the page. +18. Double-check that the *Google Drive API* has been automatically enabled. To do this, select **Library** from the menu, then search for *Google Drive API*. If it is enabled you will see *API Enabled* with a green tick next to it. If it is not enabled, then enable it. + +{% enddetails %} + +{% include integrations/config_flow.md %} + +The integration setup will next give you instructions to enter the [Application Credentials](/integrations/application_credentials/) (OAuth Client ID and Client Secret) and authorize Home Assistant to access your Google Mail. + +{% details "OAuth and Device Authorization steps" %} + +1. Continue through the steps of selecting the account you want to authorize. + +2. **NOTE**: You may get a message telling you that the app has not been verified and you will need to acknowledge that in order to proceed. + +3. You can now see the details of what you are authorizing Home Assistant to access with two options at the bottom. Click **Continue**. + +4. The page will now display *Link account to Home Assistant?*, note *Your instance URL*. If this is not correct, please refer to [My Home Assistant](/integrations/my). If everything looks good, click **Link Account**. + +5. You may close the window, and return back to Home Assistant where you should see a *Success!* message from Home Assistant. + +{% enddetails %} + +## Troubleshooting + +If you have an error with your credentials you can delete them in the [Application Credentials](/integrations/application_credentials/) user interface. + +### Service `google_mail.set_vacation` + +You can use the service `google_mail.set_vacation` to set vacation options. + +{% details "Create Event Service details" %} + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | --------| +| `enabled` | yes | Turn this off to end vacation responses. | True +| `title` | | no | The subject for the email. | Vacation +| `message` | yes | Body of the email. | I am on vacation. +| `plain_text` | no | Choose to send message in plain text or HTML. | True +| `restrict_contacts` | no | Restrict automatic reply to contacts. | True +| `restrict_domain` | no | Restrict automatic reply to domain. This only affects GSuite accounts. | False +| `start` | no | First day of the vacation. | 11-20-2022 +| `end` | no | Last day of the vacation. | 11-26-2022 + +{% enddetails %} + +The added `notify` service will be named after the email address you chose on the consent screen. For example, an email address named "example@gmail.com" wil display as `notify.example_gmail_com`. + +### Google Mail Notify Service Data + +The following attributes can be placed inside the `data` key of the service call for extended functionality: + +| Attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `cc` | yes | List of recipients to be carbon copied. +| `bcc` | yes | List of recipients to be back carbon copied. +| `from` | yes | Default is current authenticated user. Typically only applies to GSuite accounts where the user has delegate access to a shared mailbox. +| `send` | yes | Default is true. Set this to false to create a draft instead. Recipients are not required in this instance. + +### Examples + +This is the full service call to send an email: + +```yaml +service: notify.example_gmail_com +data: + message: "test" + title: "test email" + target: + - "example2@gmail.com" + data: + cc: + - "example3@gmail.com" + bcc: + - "example4@gmail.com" + from: "example@gmail.com" +``` diff --git a/source/_integrations/group.markdown b/source/_integrations/group.markdown index 6e256132c3cb..210322595da1 100644 --- a/source/_integrations/group.markdown +++ b/source/_integrations/group.markdown @@ -11,6 +11,7 @@ ha_category: - Media Player - Notifications - Organization + - Sensor - Switch ha_release: pre 0.7 ha_iot_class: Calculated @@ -27,6 +28,7 @@ ha_platforms: - lock - media_player - notify + - sensor - switch ha_integration_type: helper --- @@ -98,6 +100,13 @@ In short, when any group member entity is `unlocked`, the group will also be `un - Otherwise, the group state is `on` if at least one group member is not `off`, `unavailable` or `unknown`. - Otherwise, the group state is `off`. +### Sensor groups + +- The group state is combined / calculated based on `type` selected to determine the minimum, maximum, latest (last), mean, median, range or sum of the collected states. +- Members can be any `sensor`, `number` or `input_number` holding numeric states. +- The group state is `unavailable` if all group members are `unavailable`. +- If `ignore_non_numeric` is `false` then group state will be `unavailable` if one member is `unavailable` or does not have a numeric state. + ## Managing groups To edit a group, **{% my helpers title="Settings -> Devices & Services -> Helpers" %}**. Find and select the group from the list. @@ -190,6 +199,18 @@ media_player: - media_player.living_room_tv ``` +Example YAML configuration of a sensor group: + +```yaml +# Example configuration.yaml entry +sensor: + - platform: group + type: mean + entities: + - sensor.temperature_kitchen + - sensor.temperature_hallway +``` + Example YAML configuration of a switch group: ```yaml @@ -219,6 +240,27 @@ all: required: false type: boolean default: false +type: + description: "Only available for `sensor` group. The type of sensor: `min`, `max`, `last`, `mean`, `median`, `range`, or `sum`." + type: string + required: true +ignore_non_numeric: + description: Only available for `sensor` group. Set this to `true` if the group state should ignore sensors with non numeric values. + type: boolean + required: false + default: false +unit_of_measurement: + description: Only available for `sensor` group. Set the unit of measurement for the sensor. + type: string + required: false +device_class: + description: Only available for `sensor` group. Set the device class for the sensor according to [available options](/integrations/sensor/#device-class). + type: string + required: false +state_class: + description: Only available for `sensor` group. Set the state class for the sensor according to [available options](https://developers.home-assistant.io/docs/core/entity/sensor/#available-state-classes). + type: string + required: false {% endconfiguration %} ## Notify Groups @@ -359,6 +401,7 @@ This integration provides the following services to modify groups and a service | | `Icon` | Name of the icon for the group. | | `Entities` | List of all members in the group. Not compatible with **delta**. | | `Add Entities` | List of members that will change on group listening. +| | `Remove Entities` | List of members that will be removed from group listening. | | `All` | Enable this option if the group should only turn on when all entities are on. | `remove` | `Object ID` | Group id and part of entity id. | `reload` | `Object ID` | Group id and part of entity id. diff --git a/source/_integrations/history.markdown b/source/_integrations/history.markdown index 6025e7555fba..efffd6a9c5ff 100644 --- a/source/_integrations/history.markdown +++ b/source/_integrations/history.markdown @@ -133,20 +133,6 @@ history: - sensor.date ``` -If you'd like the order of display of the sensors to follow the way they are -listed in the included entity list, -you can set the flag `use_include_order` to true. - -```yaml -# Example configuration.yaml entry using specified entity display order -history: - use_include_order: true - include: - entities: - - sun.sun - - light.front_porch -``` - {% include common-tasks/filters.md %} #### Implementation details diff --git a/source/_integrations/homewizard.markdown b/source/_integrations/homewizard.markdown index 3a8bf47edb54..025395ddcb4b 100644 --- a/source/_integrations/homewizard.markdown +++ b/source/_integrations/homewizard.markdown @@ -47,25 +47,26 @@ You have to enable the local API to allow Home Assistant to communicate with you ## Sensors -The HomeWizard Energy API only exposes properties that are used within the HomeWizard Energy app. The available properties are listed below. - -| Name | Unit | Availability | Description | -| --- | --- | --- | --- | -| Wi-Fi SSID | | HWE-P1, HWE-SKT, HWE-WTR, SDM230-wifi, SDM630-wifi | The SSID of the connected network. | -| Wi-Fi strength | % | HWE-P1, HWE-SKT, HWE-WTR, SDM230-wifi, SDM630-wifi | Percentage of the Wi-Fi connection. | -| Total energy import T1 | kWh | HWE-P1, HWE-SKT, SDM230-wifi, SDM630-wifi | Energy import reading. | -| Total energy import T2 | kWh | HWE-P1 | Energy import reading for other tariff. | -| Total energy export T1 | kWh | HWE-P1, HWE-SKT, SDM230-wifi, SDM630-wifi | Energy export reading. | -| Total energy export T2 | kWh | HWE-P1 | Energy export reading for other tariff. | -| Active power | w | HWE-P1, HWE-SKT, SDM230-wifi, SDM630-wifi | Active power usage. | -| Active power L1 | w | HWE-P1, HWE-SKT, SDM230-wifi, SDM630-wifi | Active power usage line 1, for `SDM230-wifi` and`HWE-SKT` this value is the same as `Active power`. | -| Active power L2 | w | HWE-P1, SDM630-wifi | Active power usage line 2. | -| Active power L3 | w | HWE-P1, SDM630-wifi | Active power usage line 3. | -| Total gas | m3 | HWE-P1 | Current gas import reading, only available when your smart meter is connected to a gas meter. | -| DSMR version | | HWE-P1 | The detected DSMR version. | -| Smart meter model | | HWE-P1 | The detected smart meter model. | -| Active water usage | liter per minute | HWE-WTR | The current usage of water. | -| Total water usage | m3 | HWE-WTR | Total of water measured since installation. | +Sensors for the P1 meter, Energy socket, and kWh meter: + +- **Total energy import/export (kWh)**: Total energy imported or exported since installation. Each tariff has its own sensor (e.g., T1, T2) and a sensor for the combined value. +- **Active power (W)**: Active power that is measured on each phase. + +Sensors for P1 meter, only available when smart meter exposes these values: + +- **Gas usage (m³)**: Total gas used since the installation of the gas meter. A gas meter sends its measurement once every 5 minutes or per hour, depending on the version of the smart meter. +- **Active tariff**: Current tariff that is used. Can be used to keep consumption as low as possible during peak hours. +- **Active voltage (V)**: Active voltage that is measured on each phase. +- **Active current (A)**: Active current that is measured on each phase. +- **Active frequency (Hz)**: Net frequency. +- **Voltage sags and swells**: Number of times a voltage sag or well has been detected. +- **Power failures**: Two sensors that indicate the number of power failures that have been detected by the smart meter. One for all power failures and another for 'long' power failures. +- **Peak demand**: Belgium users are started to get charged for the peak usage per month (see [capaciteitstarief](https://www.fluvius.be/nl/thema/factuur-en-tarieven/capaciteitstarief)). Two sensors are available: One that shows the current quarterly average and another that shows the peak measured this month. Both these sensors are provided directly from the smart meter and can be used to keep the peak as low as possible. + +Sensors for Water meter: + +- **Active usage (L/min)**: Flow of water that is measured at that time. +- **Total usage (m³)**: Total water usage since the installation of the HomeWizard Water meter. ## Energy Socket @@ -79,11 +80,11 @@ You can also control the green status light brightness with **Status light brigh ## Identify The identify button can be pressed to let the status light blink for a few seconds. -This feature is currently only available for the Wifi Energy Socket with firmware version `3.01` or later. +This feature is currently only available for the Wifi P1 meter and the Wifi Energy Socket. ## Cloud communication 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 Energy Socket with firmware version `3.01` or later. +This feature is currently not available for the Wifi Water meter. diff --git a/source/_integrations/imap.markdown b/source/_integrations/imap.markdown index 359432a28b06..bac642c00d39 100644 --- a/source/_integrations/imap.markdown +++ b/source/_integrations/imap.markdown @@ -9,72 +9,28 @@ ha_domain: imap ha_platforms: - sensor ha_integration_type: integration +ha_codeowners: + - '@engrbm87' +ha_config_flow: true --- -The `imap` integration is observing your [IMAP server](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol) and reporting the amount of unread emails. +The IMAP integration is observing your [IMAP server](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol) and reporting the number of unread emails. Other search criteria can be used, as shown in the example below. -## Configuration - -To enable this sensor, add the following lines to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: imap - server: YOUR_IMAP_SERVER - username: YOUR_USERNAME - password: YOUR_PASSWORD -``` - -{% configuration %} -server: - description: The IP address or hostname of the IMAP server. - required: true - type: string -port: - description: The port where the server is accessible. - required: false - default: 993 - type: integer -name: - description: Name of the IMAP sensor. - required: false - type: string -username: - description: Username for the IMAP server. - required: true - type: string -password: - description: Password for the IMAP server. - required: true - type: string -folder: - description: The IMAP folder to watch. - required: false - default: inbox - type: string -search: - description: The IMAP search to perform on the watched folder. - required: false - default: UnSeen UnDeleted - type: string -charset: - description: The character set used for this connection. - required: false - default: utf-8 - type: string -{% endconfiguration %} +{% include integrations/config_flow.md %} ### Gmail with App Password -If you’re going to use Gmail, it’s always good practice to create a [App Password](https://support.google.com/mail/answer/185833). +If you’re going to use Gmail, you need to create an [App Password](https://support.google.com/mail/answer/185833). 1. Go to your [Google Account](https://myaccount.google.com/) 2. Select **Security** 3. Under “Signing in to Google” select **App Passwords** 4. Sign in to your Account, and create a new App Password for Gmail. - -You can now use this as your password for Gmail, in your configuration. +5. Then you can setup the intergation as below: + - Server: `imap.gmail.com` + - Port: `993` + - Username: Your full email address + - Password: The new app password ### Configuring IMAP Searches @@ -84,27 +40,12 @@ By default, this integration will count unread emails. By configuring the search * `FROM`, `TO`, `SUBJECT` to find emails in a folder (see [IMAP RFC for all standard options](https://tools.ietf.org/html/rfc3501#section-6.4.4)) * [Gmail's IMAP extensions](https://developers.google.com/gmail/imap/imap-extensions) allow raw Gmail searches, like `X-GM-RAW "in: inbox older_than:7d"` to show emails older than one week in your inbox. Note that raw Gmail searches will ignore your folder configuration and search all emails in your account! -#### Full configuration sample with search - -```yaml -# Example configuration.yaml entry for gmail -sensor: - - platform: imap - server: imap.gmail.com - port: 993 - username: YOUR_USERNAME - password: YOUR_PASSWORD - search: FROM , SUBJECT - # Or use X-GM-RAW search-term like this, to find unread emails from the last 7 days in your inbox - # search: 'X-GM-RAW "in: inbox newer_than:7d is:unread"' +### Selecting a charset supported by the imap server -# Example configuration.yaml entry for Office 365 -sensor: - - platform: imap - server: outlook.office365.com - port: 993 - username: email@address.com - password: password - search: FROM , SUBJECT - charset: US-ASCII -``` +Below is an example for setting up the integration to connect to your Microsoft 365 account that requires `US_ASCII` as charset: + - Server: `outlook.office365.com` + - Port: `993` + - Username: Your full email address + - Password: Your password + - Charset: `US-ASCII` + diff --git a/source/_integrations/intellifire.markdown b/source/_integrations/intellifire.markdown index 005fb57eaea3..97a6d72e41bb 100644 --- a/source/_integrations/intellifire.markdown +++ b/source/_integrations/intellifire.markdown @@ -5,6 +5,7 @@ ha_category: - Binary Sensor - Climate - Fan + - Light - Number - Sensor - Switch @@ -17,6 +18,7 @@ ha_config_flow: true ha_platforms: - binary_sensor - climate + - light - fan - number - sensor @@ -57,6 +59,11 @@ If your unit is equipped with a fan - this entry will be present. There are 5 po - **Thermostat** - This entity will be present if your unit has thermostatic control. + +### Light + +The integration provides a light entity if the unit is equipped with lights. + ### Number The integration uses a Number entity to control flame height. Valid flame height vales are `1-5`. diff --git a/source/_integrations/isy994.markdown b/source/_integrations/isy994.markdown index 015110725bb3..530e431df5a6 100644 --- a/source/_integrations/isy994.markdown +++ b/source/_integrations/isy994.markdown @@ -1,14 +1,17 @@ --- -title: Universal Devices ISY994 -description: Instructions on how to setup the ISY994 controller within Home Assistant. +title: Universal Devices ISY/IoX +description: Instructions on how to setup an ISY controller within Home Assistant. ha_category: - Binary Sensor + - Button - Climate - Cover - Fan - Hub - Light - Lock + - Number + - Select - Sensor - Switch ha_release: 0.28 @@ -21,97 +24,66 @@ ha_codeowners: ha_ssdp: true ha_platforms: - binary_sensor + - button - climate - cover - fan - light - lock + - number + - select - sensor - switch ha_dhcp: true ha_integration_type: hub --- -The ISY994 is a home automation controller that is capable of controlling Insteon and X10 devices. Some models of the ISY994 can even control Z-Wave devices. -The ISY994 controller is manufactured by [Universal Devices](https://www.universal-devices.com/smarthome). +ISY is a home automation controller capable of controlling Insteon, X10, Z-Wave and Zigbee/Matter devices connected to supported hardware manufactured by [Universal Devices, Inc.](https://www.universal-devices.com/). -There is currently support for the following device types within Home Assistant: +This integration supports the legacy ISY994 hardware family, as well as current ISY-on-Anything (IoX) hardware, such as the [eisy](https://www.universal-devices.com/product/eisy-home/) or [Polisy](https://www.universal-devices.com/polisy/) devices. + +There is currently support for the following platforms within Home Assistant: - Binary Sensor +- Button - Climate - Cover - Light - Fan - Lock +- Number +- Select - Sensor - Switch -Home Assistant is capable of communicating with any binary sensor, cover, fan, light, lock, sensor and switch that is configured on the controller. Using the programs on the controller, custom binary sensors, covers, fans, locks, and switches can also be created. +Home Assistant is capable of communicating with any binary sensor, cover, fan, light, lock, sensor and switch that is configured on the controller. Using the programs on the controller, custom binary sensors, covers, fans, locks, and switches can also be created. Each device and the ISY hub also include a Query button to query the device. -{% include integrations/config_flow.md %} +ISY Networking Module Resources can be executed using the buttons created. -## Manual configuration +{% include integrations/config_flow.md %} -You may also configure the integration manually by adding the following section to your `configuration.yaml` file: +Once the ISY controller is configured, it will automatically import any binary sensors, covers, fans, lights, locks, sensors and switches it can locate. -```yaml -# Example configuration.yaml entry -isy994: - host: ISY_ADDRESS - username: ISY_USERNAME - password: ISY_PASSWORD -``` +### Configuration Options -{% configuration %} -host: - description: The host entry should be in full URL format, e.g., `http://192.168.10.100:80` - required: true - type: string -username: - description: The username that is used to access the ISY interface. - required: true - type: string -password: - description: The password that is used to access the ISY interface. - required: true - type: string -sensor_string: - description: This is the string that is used to identify which devices are to be assumed to be sensors instead of lights or switches. If this string is found in the device name or folder, Home Assistant will assume it is a sensor or binary sensor (if the device has on/off or true/false states). This is only necessary for nodes that are not automatically detected as sensors by Home Assistant. Insteon door, window, motion and leak sensors should all be detected automatically. - required: false - type: string - default: sensor -variable_sensor_string: - description: This is the string that is used to identify which Integer or State Variables are to be added as sensors. If this string is found in the device name, Home Assistant will assume it is a sensor. - required: false - type: string - default: sensor -ignore_string: - description: Any devices that contain this string in their name (or folder path) will be ignored by Home Assistant. They will not become entities at all and will not fire `control_events`. - required: false - type: string - default: {IGNORE ME} -tls: - description: This entry should reflect the version of TLS that the ISY controller is using for HTTPS encryption. This value can be either 1.1 or 1.2. If this value is not set, it is assumed to be version 1.1. This is the default for most users. ISY994 Pro users may likely be using 1.2. When using HTTPS in the host entry, it is best practice to set this value. - required: false - type: string -restore_light_state: - description: If disabled (default behavior), lights turned ON from Home Assistant without a `brightness` parameter set, will turn on to the `on_level` set within the physical device. For example, on Insteon devices this would be the same brightness as if the switch/device was turned ON. If this setting is enabled, lights that are turned on from Home Assistant will go to the last known brightness value. Both the `on_level` and `last_brightness` values are available as attributes if needed for device-specific customization. - required: false - type: boolean - default: false -{% endconfiguration %} +There are several options available to further customize what is imported from the ISY controller and entity behavior. -Once the ISY controller is configured, it will automatically import any binary sensors, covers, fans, lights, locks, sensors and switches it can locate. +- Sensor String: This is the string that is used to identify which devices are to be assumed to be sensors instead of lights or switches. If this string is found in the device name or folder, Home Assistant will consider it a sensor or binary sensor (if the device has on/off or true/false states). This is only necessary for nodes that are not automatically detected as sensors by Home Assistant. Insteon door, window, motion, and leak sensors should all be detected automatically. +- Variable Sensor String: This is the string that is used to identify which Integer or State Variables are to be enabled by default as `number` entities. If this string is found in the device name, Home Assistant will assume it is a sensor. The default is `"HA."`. +- Ignore String: Any devices that contain this string in their name (or folder path) will be ignored by Home Assistant. They will not become entities and will not fire `control_events`. The default is `"{IGNORE ME}"`. +- Restore Light State: If disabled (default behavior), lights turned ON from Home Assistant without a `brightness` parameter set will turn on to the `on_level` set within the physical device. For example, on Insteon devices, this would be the same brightness as if the switch/device was turned ON. If this setting is enabled, lights that are turned on from Home Assistant will go to the last known brightness value. Both the `on_level` and `last_brightness` values are available as attributes if needed for device-specific customization. ### Sensors -An Insteon door/window sensor will show up as a single Binary Sensor rather than two discrete devices like it does in the ISY994 admin panel. Note that when in "Two Nodes" mode, the sensor will have an UNKNOWN state until the sensor changes for the first time since the last Home Assistant reboot. If you do not use Insteon scenes that are controlled directly from the door sensor, you may prefer to set the sensor to "One Node" mode using the ISY Admin Panel. +An Insteon door/window sensor will show up as a single Binary Sensor rather than two discrete devices like it does in the ISY Admin Console. Note that when in "Two Nodes" mode, the sensor will have an UNKNOWN state until the sensor changes for the first time since the last Home Assistant reboot. If you do not use Insteon scenes that are controlled directly from the door sensor, you may prefer to set the sensor to "One Node" mode using the ISY Admin Panel. -Each Insteon leak sensor will also show up as a single Binary Sensor as opposed to the two nodes seen in the ISY994. The name of the device will be based on what the parent node is named in the ISY994, which is typically the one with "-Dry" at the end of the name. This may be confusing, because "On" means wet in Home Assistant. You can rename this node in Home Assistant to be more clear, see the [Customization section](/docs/configuration/customizing-devices/) of your configuration. +Each Insteon leak sensor will also show up as a single Binary Sensor as opposed to the two nodes seen in the ISY Admin Console. The name of the device will be based on what the parent node is named in the ISY, which is typically the one with "-Dry" at the end of the name. This may be confusing, because "On" means wet in Home Assistant. You can rename this node in Home Assistant to be more clear, see the [Customization section](/docs/configuration/customizing-devices/) of your configuration. If your leak or door/window sensor supports heartbeats, a new binary_sensor device will be added to Home Assistant to represent the battery state. The sensor will stay "Off" so long as the daily heartbeats occur. If a heartbeat is missed, the sensor will flip to "On". The name of this device will be based on the heartbeat node in the ISY. -Integer and State Variables from the ISY can be used as sensors by setting the `variable_sensor_string` and adding it as part of the variable name in the ISY. For example, if you have a variable named `HA.my_variable` and a `variable_sensor_string` of `"HA."`, it will be automatically added as a `sensor` in Home Assistant. +### ISY/IoX Variables + +Integer and State Variables from the ISY are imported as `number` entities. You can choose which variables are enabled by default by setting the "Variable Sensor String" Config Option and using it as part of the variable name in the ISY Admin Console (e.g., `HA.` in options and `HA.Variable Name` on the ISY) or you can manually enable the entities you need from the ISY Variables device in Home Assistant. ### Handling Insteon or Other ISY Control Events @@ -136,7 +108,7 @@ automation: entity_id: light.lr_track_lights_rear ``` -All `isy994_control` events will have an `entity_id` and `control` parameter in its `event_data`. You'll need to refer to ISY994 documentation for the list of every possible control type, but the common ones are: +All `isy994_control` events will have an `entity_id` and `control` parameter in its `event_data`. You'll need to refer to ISY documentation for the list of every possible control type, but the common ones are: - `DON`: On button. - `DOF`: Off button. @@ -150,17 +122,20 @@ All `isy994_control` events will have an `entity_id` and `control` parameter in ### Insteon Scenes & Keypad/Remote Buttons -All Insteon scenes configured in the ISY994 will show up as a `switch` in Home Assistant, as they do not support dimming or setting specific brightness settings as Home Assistant's `light` component. +All Insteon scenes configured in the ISY Admin Console will show up as a `switch` in Home Assistant, as they do not support dimming or setting specific brightness settings as Home Assistant's `light` component. Insteon Secondary Keypad buttons and Remote buttons are added to Home Assistant to allow support for using Control Events in Automations. These devices are added as `sensors` since they cannot be directly controlled (turned on/off); their state is the last ON level command they sent, in a range from `0` (Off) to `255` (On 100%). Note: these devices may report incorrect states before being used after a reboot of the ISY. Secondary Keypad buttons may be turned on or off using ISY Scenes (refer to ISY Documentation for more details). +### Insteon Device Configuration Support + +Insteon devices will include entities for setting the device On Level, Ramp Rate, and Backlight Level, if supported; as well as `button` entities for `Beep` and `Query` actions. Note: Backlight Level cannot be read from the device, so an assumed state is used. The current state in Home Assistant will be valid if the backlight is changed from Home Assistant and will also be updated if changed from the ISY Admin Console or REST command while Home Assistant is running. Additional configuration changes still require the ISY Admin Console. + ### Services Once loaded, the following services will be exposed with the `isy994.` prefix, to allow advanced control over the ISY and its connected devices: - - Entity services for Home Assistant-connected entities: `send_node_command`, `send_raw_node_command`, `set_on_level`, and `set_ramp_rate`. - - Generic ISY services: `system_query`, `set_variable`, `send_program_command`, and `run_network_resource`. - - Management services for the ISY994 Home Assistant integration: `reload` and `cleanup_entities`. + - Entity services for Home Assistant-connected entities: `send_node_command`, `send_raw_node_command`, and `set_ramp_rate`. + - Generic ISY services: `send_program_command` #### Service `isy994.send_node_command` @@ -210,47 +185,7 @@ Rename a node or group (scene) on the ISY994. Note: this will not automatically | Service data attribute | Optional | Description | | ---------------------- | -------- | -------------------------------------------------------------- | | `entity_id` | no | Name of target entity for the command, e.g., `light.front_porch`. | -| `name` | no | The new name to use within the ISY994. | - -#### Service `isy994.set_on_level` - -Send an ISY set_on_level command to a `light` Node to set the devices' local On Level. - -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of target entities for the command, e.g., `light.front_porch`. | -| `value` | no | The integer value to set the On Level to in a range of 0-255, e.g., `255` | - -#### Service `isy994.set_ramp_rate` - -Send an ISY set_ramp_rate command to a `light` Node to set the devices' ramp rate. Refer to the PyISY documentation for the [available values](https://github.com/automicus/PyISY/blob/d053369f7531370a907136bf25a177632adccd1e/pyisy/constants.py#L630). - -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of target entities for the command, e.g., `light.front_porch`. | -| `value` | no | The integer index value to set the Ramp Rate to in a range of `0` (9.5 minutes) to `31` (0.1 Seconds), e.g., `28` | - -#### Service `isy994.system_query` - -Request the ISY Query the connected devices. - -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `address` | yes | ISY Address to Query. Omitting this requests a system-wide scan (typically recommended by UDI to be scheduled once per day), e.g., `"1A 2B 3C 1"` | -| `isy` | yes | If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). Omitting this will cause all ISYs to be queried, e.g., `"ISY"` | - -#### Service `isy994.set_variable` - -Set an ISY variable's current or initial value. Variables can be set by either type/address or by name. - -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `value` | no | The integer value to be sent, e.g., `255` | -| `address` | no | The address of the variable for which to set the value, e.g., `5` | -| `type` | no | The variable type, 1 = Integer, 2 = State, e.g., `2` | -| `name` | yes | The name of the variable to set (Optional, use `name` instead of `type` and `address`), e.g., `"my_variable_name"` | -| `init` | yes | If True, the initial (init) value will be updated instead of the current value, e.g., `false` | -| `isy` | yes | If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). If you have the same variable name or address on multiple ISYs, omitting this will run the command on them all, e.g., `"ISY"` | +| `name` | no | The new name to use within the ISY. | #### Service `isy994.send_program_command` @@ -263,25 +198,6 @@ Send a command to control an ISY program or folder. Valid commands are `run`, `r | `name` | yes | The name of the program to control (optional, use either `address` or `name`), e.g., `"My Program"` | | `isy` | yes | (Optional) If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). If you have the same program name or address on multiple ISYs, omitting this will run the command on them all, e.g., `"ISY"` | -#### Service `isy994.run_network_resource` - -Run a network resource on the ISY. - -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `address` | yes | The address of the network resource to execute (optional, use either `address` or `name`), e.g., `121` | -| `name` | yes | The name of the network resource to execute (optional, use either `address` or `name`), e.g., `"Network Resource 1"` | -| `isy` | yes | (Optional) If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). If you have the same resource name or address on multiple ISYs, omitting this will run the command on them all, e.g., `"ISY"` | - -#### Service `isy994.reload` - -Reload the ISY994 connection(s) without restarting Home Assistant. Use this service to pick up new devices that have been added or changed on the ISY since the last restart of Home Assistant. - -#### Service `isy994.cleanup_entities` - -Cleanup old entities no longer used by the ISY994 integrations. Useful if you've removed devices from the ISY or changed the filter string options in the configuration to exclude additional items and they were not properly removed -by Home Assistant. - ### Creating Custom Devices using ISY Programs Using the Programs tab in the controller's Administrative Console, custom devices can be created that will appear natively inside of Home Assistant. Home Assistant will scan the following folders and build the device to the associated domains: diff --git a/source/_integrations/jellyfin.markdown b/source/_integrations/jellyfin.markdown index 3d8d156b467e..c005d05ca527 100644 --- a/source/_integrations/jellyfin.markdown +++ b/source/_integrations/jellyfin.markdown @@ -20,7 +20,7 @@ ha_integration_type: service --- The Jellyfin integration exposes a [Jellyfin](https://jellyfin.org/) server as a Media Source in Home Assistant. -Support is currently limited to music and movie libraries only. Other libraries will not appear in the Media Browser. This integration has been tested with Jellyfin server version 10.6.4 and later. +Support is currently limited to music, movie and tvshow libraries only. Other libraries will not appear in the Media Browser. This integration has been tested with Jellyfin server version 10.6.4 and later. Additionally, this integration sets up every media session connected to the Jellyfin server as a media player in Home Assistant to provide media controls for each session. diff --git a/source/_integrations/kitchen_sink.markdown b/source/_integrations/kitchen_sink.markdown new file mode 100644 index 000000000000..9500242c3db8 --- /dev/null +++ b/source/_integrations/kitchen_sink.markdown @@ -0,0 +1,26 @@ +--- +title: Everything but the Kitchen Sink +description: Instructions on how to set up the Everything but the Kitchen Sink integration +ha_category: + - Other +ha_release: 2023.2 +ha_quality_scale: internal +ha_codeowners: + - '@home-assistant/core' +ha_domain: kitchen_sink +ha_iot_class: Calculated +ha_platforms: +ha_integration_type: integration +--- + +The Kitchen Sink integration contains demonstrations of various odds and ends. + +This sets up a demo environment of features which are obscure or which represent incorrect behavior, and are thus not wanted in the `demo` integration. + +To enable the `kitchen_sink` integration in Home Assistant, add the following section to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry + +kitchen_sink: +``` diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 3372c82283fb..9139fe6d0604 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -85,16 +85,15 @@ knx: Please see the dedicated platform sections below about how to configure them correctly. - ### Group addresses Group addresses are configured as strings or integers in the format "1/2/3" for 3-level GA-structure, "1/2" for 2-level GA-structure or "1" for free GA-structure. The HA KNX integration uses configured `state_address` or `*_state_address` to update the state of a function. These addresses are read by GroupValueRead requests on startup and when there was no incoming telegram for one hour (default `sync_state`). -It is possible to configure passive/listening group addresses for all functions of every KNX platform (except `expose` and `notify`). This allows having multiple group addresses to update the state of its function (e.g., the brightness of a light). When group addresses are configured as a list of strings, the first item is the active sending or state-reading address and the rest is registered as passive addresses. This schema behaves like in ETS configuration where the first is the "sending" address and others are just for updating the communication object. +It is possible to configure passive/listening group addresses for all functions of every KNX platform (except `expose` and `notify`). This allows having multiple group addresses to update the state of its function (e.g., the brightness of a light). When group addresses are configured as a list of strings, the first item is the active sending or state-reading address and the rest is registered as passive addresses. This schema behaves like in ETS configuration where the first is the "sending" address and others are just for updating the group object. -If your KNX device provides active state communication objects it is advised to use `*_state_address` instead of passive addresses as it reduces configuration complexity and avoids wrong states (e.g., when channels are logically locked). +If your KNX device provides active state group objects it is advised to use `*_state_address` instead of passive addresses as it reduces configuration complexity and avoids wrong states (e.g., when channels are logically locked). ```yaml knx: @@ -627,7 +626,7 @@ knx: ``` `operation_mode_frost_protection_address` / `operation_mode_night_address` / `operation_mode_comfort_address` / `operation_mode_standby_address` are not necessary if `operation_mode_address` is specified. -If the actor doesn't support explicit state communication objects the `*_state_address` can be configured with the same group address as the writeable `*_address`. The read flag for the `*_state_address` communication object has to be set in ETS to support initial reading e.g., when starting Home Assistant. +If the actor doesn't support explicit state group objects the `*_state_address` can be configured with the same group address as the writeable `*_address`. The read flag for the `*_state_address` group object has to be set in ETS to support initial reading e.g., when starting Home Assistant. The following values are valid for the `heat_cool_address` and the `heat_cool_state_address`: @@ -1090,7 +1089,7 @@ entity_category: Many KNX devices can change their state internally without a message to the switch address on the KNX bus, e.g., if you configure a scene or a timer on a channel. The optional `state_address` can be used to inform Home Assistant about these state changes. If a KNX message is seen on the bus addressed to the given `state_address` (in most cases from the light actuator), it will overwrite the state of the object. -For switching/light actuators that are only controlled by a single group address and don't have dedicated state communication objects you can set `state_address` to the same value as `address`. +For switching/light actuators that are only controlled by a single group address and don't have dedicated state group objects you can set `state_address` to the same value as `address`. *Note on tunable white:* Home Assistant uses Mireds as the unit for color temperature, whereas KNX typically uses Kelvin. The Kelvin/Mireds relationship is reciprocal, not linear, therefore the color temperature pickers (sliders) in Home Assistant may not align with ones of KNX visualizations. This is the expected behavior. @@ -1173,7 +1172,7 @@ knx: color_temperature_mode: absolute min_kelvin: 2550 max_kelvin: 6200 - # actuator without dedicated state communication object + # actuator without dedicated state group object # color mode: onoff - name: "Simple light" address: "1/0/5" @@ -1510,6 +1509,7 @@ device_class: | 8.007 | delta_time_hrs | 2 | -32768 ... 32767 | h | | 8.010 | percentV16 | 2 | -32768 ... 32767 | % | | 8.011 | rotation_angle | 2 | -32768 ... 32767 | ° | +| 8.012 | length_m | 2 | -32768 ... 32767 | m | | 9 | 2byte_float | 2 | -671088.64 ... 670760.96 | | | 9.001 | temperature | 2 | -273 ... 670760 | °C | | 9.002 | temperature_difference_2byte | 2 | -670760 ... 670760 | K | @@ -1519,6 +1519,7 @@ device_class: | 9.006 | pressure_2byte | 2 | 0 ... 670760 | Pa | | 9.007 | humidity | 2 | 0 ... 670760 | % | | 9.008 | ppm | 2 | -671088.64 ... 670760.96 | ppm | +| 9.009 | air_flow | 2 | -671088.64 ... 670760.96 | m³/h | | 9.010 | time_1 | 2 | -670760 ... 670760 | s | | 9.011 | time_2 | 2 | -670760 ... 670760 | ms | | 9.020 | voltage | 2 | -671088.64 ... 670760.96 | mV | @@ -1530,12 +1531,18 @@ device_class: | 9.026 | rain_amount | 2 | -671088.64 ... 670760.96 | l/m² | | 9.027 | temperature_f | 2 | -459.6 ... 670760 | °F | | 9.028 | wind_speed_kmh | 2 | 0 ... 670760 | km/h | +| 9.029 | absolute_humidity | 2 | 0 ... 670760 | g/m³ | +| 9.030 | concentration_ugm3 | 2 | 0 ... 670760 | μg/m³ | | 9.? | enthalpy | 2 | -671088.64 ... 670760.96 | H | | 12 | 4byte_unsigned | 4 | 0 ... 4294967295 | | +| 12.001 | pulse_4_ucount | 4 | 0 ... 4294967295 | counter pulses | +| 12.100 | long_time_period_sec | 4 | 0 ... 4294967295 | s | +| 12.101 | long_time_period_min | 4 | 0 ... 4294967295 | min | +| 12.100 | long_time_period_hrs | 4 | 0 ... 4294967295 | h | | 12.1200 | volume_liquid_litre | 4 | 0 ... 4294967295 | l | | 12.1201 | volume_m3 | 4 | 0 ... 4294967295 | m³ | | 13 | 4byte_signed | 4 | -2147483648 ... 2147483647 | | -| 13.001 | pulse_4byte | 4 | -2147483648 ... 2147483647 | pulses | +| 13.001 | pulse_4byte | 4 | -2147483648 ... 2147483647 | counter pulses | | 13.002 | flow_rate_m3h | 4 | -2147483648 ... 2147483647 | m³/h | | 13.010 | active_energy | 4 | -2147483648 ... 2147483647 | Wh | | 13.011 | apparant_energy | 4 | -2147483648 ... 2147483647 | VAh | @@ -1543,6 +1550,7 @@ device_class: | 13.013 | active_energy_kwh | 4 | -2147483648 ... 2147483647 | kWh | | 13.014 | apparant_energy_kvah | 4 | -2147483648 ... 2147483647 | kVAh | | 13.015 | reactive_energy_kvarh | 4 | -2147483648 ... 2147483647 | kVARh | +| 13.016 | active_energy_mwh | 4 | -2147483648 ... 2147483647 | MWh | | 13.100 | long_delta_timesec | 4 | -2147483648 ... 2147483647 | s | | 14 | 4byte_float | 4 | | | | 14.000 | acceleration | 4 | | m/s² | @@ -1602,11 +1610,11 @@ device_class: | 14.054 | phaseanglerad | 4 | | rad | | 14.055 | phaseangledeg | 4 | | ° | | 14.056 | power | 4 | | W | -| 14.057 | powerfactor | 4 | | cosΦ | +| 14.057 | powerfactor | 4 | | | | 14.058 | pressure | 4 | | Pa | | 14.059 | reactance | 4 | | Ω | | 14.060 | resistance | 4 | | Ω | -| 14.061 | resistivity | 4 | | Ω m | +| 14.061 | resistivity | 4 | | Ωm | | 14.062 | self_inductance | 4 | | H | | 14.063 | solid_angle | 4 | | sr | | 14.064 | sound_intensity | 4 | | W/m² | @@ -1620,11 +1628,12 @@ device_class: | 14.072 | thermal_conductivity | 4 | | W/mK | | 14.073 | thermoelectric_power | 4 | | V/K | | 14.074 | time_seconds | 4 | | s | -| 14.075 | torque | 4 | | N m | +| 14.075 | torque | 4 | | Nm | | 14.076 | volume | 4 | | m³ | | 14.077 | volume_flux | 4 | | m³/s | | 14.078 | weight | 4 | | N | | 14.079 | work | 4 | | J | +| 14.080 | apparent_power | 4 | | VA | | 16.000 | string | 14 | ASCII | | | 16.001 | latin_1 | 14 | ISO 8859-1 / Latin-1 | | | 17.001 | scene_number | 1 | 1 ... 64 | | @@ -1868,11 +1877,14 @@ logger: logs: # For most debugging needs `xnx.log` and `xknx.telegram` are a good choice. xknx: info # sets the level of all loggers + # Loggers for different layers of KNX communication xknx.log: debug # provides general information (connection, etc.) - xknx.raw_socket: warning # logs incoming UDP frames in raw hex format - xknx.knx: debug # logs incoming and outgoing KNX/IP frames at socket level + xknx.telegram: debug # logs telegrams before they are being processed or sent xknx.cemi: debug # logs incoming and outgoing CEMI frames - xknx.telegram: debug # logs telegrams before they are being processed at device level or sent to an interface + xknx.ip_secure: debug # logs IP Secure relevant information + xknx.knx: debug # logs incoming and outgoing KNX/IP frames + xknx.raw_socket: warning # logs incoming UDP/TCP frames in raw hex format at socket level + # Loggers for xknx internals xknx.state_updater: warning # provides information about the state updater ``` @@ -1888,13 +1900,14 @@ Every `*_state_address` is read on startup sequentially if not configured differ > Error: KNX bus did not respond in time (2.0 secs) to GroupValueRead request for: '1/2/3' ``` -#### No communication object (CO) assigned to the group address (GA) has the Read-Flag set in ETS +#### No group object (GO) assigned to the group address (GA) has the Read-Flag set in ETS -- Enable the read flag for *one* CO assigned to the GA. Use the one most likely to hold the current state (e.g., for a light entity's `brightness_state_address` the according CO of the dimming actuator). +- Enable the read flag for *one* GO assigned to the GA. Use the one most likely to hold the current state (e.g., for a light entity's `brightness_state_address` the according GO of the dimming actuator). #### Response telegrams are not passing a line coupler, router or other filter in the installation -- Use a dummy device in ETS for Home Assistant. These can be found in the ETS online catalog. Assign it to the line your interface connects Home Assistant to and link its communication objects to the group addresses you are using in Home Assistant. ETS will generate filter tables that are applied to your line couplers after updating their application. +- Assign the group addresses used by Home Assistant to the used interface in ETS if your interface application supports that. ETS will generate filter tables that are applied to your line couplers after updating their application. +- If your interface application doesn't support that, use a dummy device in ETS for Home Assistant. These can be found in the ETS online catalog. Assign it to the line your interface connects Home Assistant to and link its group objects to the group addresses you are using in Home Assistant. #### Unresponsive system @@ -1923,12 +1936,3 @@ The `unique_id` for KNX entities is generated based on required configuration va - weather: `address_temperature` There can not be multiple entities on the same platform sharing these exact group addresses, even if they differ in other configuration. - -### xknx.yaml configuration - -```log -> The 'config_file' option near /homeassistant/configuration.yaml:42 is deprecated, please remove it from your configuration -> Invalid config for [knx]: [config_file] is an invalid option for [knx]. Check: knx->knx->config_file. -``` - -The feature to specify a xknx configuration schema file in the Home Assistant configuration YAML file (via `config_file:`) is deprecated since Home Assistant 2021.4. You can use the [xknx.yaml config converter](https://xknx.io/config-converter/) to convert it to a Home Assistant compatible `configuration.yaml` schema. diff --git a/source/_integrations/ld2410_ble.markdown b/source/_integrations/ld2410_ble.markdown new file mode 100644 index 000000000000..5c2f03185771 --- /dev/null +++ b/source/_integrations/ld2410_ble.markdown @@ -0,0 +1,48 @@ +--- +title: LD2410 BLE +description: Instructions on how to integrate LD2410 BLE devices into Home Assistant. +ha_category: + - Sensor + - Presence Detection +ha_bluetooth: true +ha_release: 2023.2 +ha_iot_class: Local Push +ha_codeowners: + - '@930913' +ha_domain: ld2410_ble +ha_config_flow: true +ha_platforms: + - sensor +ha_integration_type: integration +--- + +Integrates LD2410 BLE sensors from [Hi-Link](http://www.hlktech.net/) into Home Assistant. + +{% include integrations/config_flow.md %} + +You can currently configure the settings for motion/static triggers by USB with either the [desktop software](https://drive.google.com/drive/folders/1p4dhbEJA3YubyIjIIC7wwVsSo8x29Fq-?usp=sharing) or the Bluetooth [mobile app](https://www.pgyer.com/Lq8p). + +(This integration may not work if you reconfigure the default password or the number of gates.) + +## Sensors Provided + +The following sensors are provided: + +- Motion detected +- Occupancy detected +- Moving target distance & energy* +- Static target distance & energy* +- Detection distance* +- Number of moving/static gates +- Moving energy at gates 0-8* +- Static energy at gates 0-8* + +\* Denotes entity is hidden by default, but can be enabled in the UI. + +## Purchasing + +
    +There are multiple similar versions of the board. Make sure to buy the LD2410B or LD2410C versions as these are the ones with Bluetooth and have been tested. The C variant has 2.54mm pitch pins which is the one used by Arduino type devices, whereas the B variant has half pitch pins. +
    + +You can buy this module bareboard or in a devkit from [AliExpress](https://www.aliexpress.com/item/1005004351593073.html). diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index e57197810360..1d853dcd1ba1 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -217,6 +217,10 @@ effect_value_template: description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the effect value." required: false type: string +hs_command_template: + description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `hs_command_topic`. Available variables: `hue` and `sat`." + required: false + type: string hs_command_topic: description: "The MQTT topic to publish commands to change the light's color state in HS format (Hue Saturation). Range for Hue: 0° .. 360°, Range of Saturation: 0..100. @@ -224,7 +228,7 @@ hs_command_topic: required: false type: string hs_state_topic: - description: "The MQTT topic subscribed to receive color state updates in HS format. + description: "The MQTT topic subscribed to receive color state updates in HS format. The expected payload is the hue and saturation values separated by commas, for example, `359.5,100.0`. Note: Brightness is received separately in the `brightness_state_topic`." required: false type: string @@ -374,12 +378,16 @@ white_scale: required: false type: integer default: 255 +xy_command_template: + description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `xy_command_topic`. Available variables: `x` and `y`." + required: false + type: string xy_command_topic: description: "The MQTT topic to publish commands to change the light's XY state." required: false type: string xy_state_topic: - description: The MQTT topic subscribed to receive XY state updates. + description: The MQTT topic subscribed to receive XY state updates. The expected payload is the X and Y color values separated by commas, for example, `0.675,0.322`. required: false type: string xy_value_template: diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown index d8e2bc2c84f1..c64b9512b0dc 100644 --- a/source/_integrations/lock.mqtt.markdown +++ b/source/_integrations/lock.mqtt.markdown @@ -20,6 +20,7 @@ Optimistic mode can be forced, even if state topic is available. Try to enable i It's mandatory for locks to support `lock` and `unlock`. A lock may optionally support `open`, (e.g. to open the bolt in addition to the latch), in this case, `payload_open` is required in the configuration. If the lock is in optimistic mode, it will change states to `unlocked` when handling the `open` command. +An MQTT lock can also report the intermediate states `unlocking`, `locking` or `jammed` if the motor reports a jammed state. To enable MQTT locks in your installation, add the following to your `configuration.yaml` file: @@ -68,6 +69,14 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +code_format: + description: A regular expression to validate a supplied code when it is set during the service call to `open`, `lock` or `unlock` the MQTT lock. + required: false + type: string +command_template: + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `command_topic`. The lock command template accepts the parameters `value` and `code`. The `value` parameter will contain the configured value for either `payload_open`, `payload_lock` or `payload_unlock`. The `code` parameter is set during the service call to `open`, `lock` or `unlock` the MQTT lock and will be set `None` if no code was passed. + required: false + type: template command_topic: description: The MQTT topic to publish commands to change the lock state. required: true @@ -193,26 +202,41 @@ retain: required: false type: boolean default: false +state_jammed: + description: The payload sent to `state_topic` by the lock when it's jammed. + required: false + type: string + default: JAMMED state_locked: - description: The payload sent to by the lock when it's locked. + description: The payload sent to `state_topic` by the lock when it's locked. required: false type: string default: LOCKED +state_locking: + description: The payload sent to `state_topic` by the lock when it's locking. + required: false + type: string + default: LOCKING state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. It accepts states configured with `state_jammed`, `state_locked`, `state_unlocked`, `state_locking` or `state_unlocking`. required: false type: string state_unlocked: - description: The payload sent to by the lock when it's unlocked. + description: The payload sent to `state_topic` by the lock when it's unlocked. required: false type: string default: UNLOCKED +state_unlocking: + description: The payload sent to `state_topic` by the lock when it's unlocking. + required: false + type: string + default: UNLOCKING unique_id: description: An ID that uniquely identifies this lock. If two locks have the same unique ID, Home Assistant will raise an exception. required: false type: string value_template: - description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the payload." + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a state value from the payload. required: false type: string {% endconfiguration %} @@ -238,12 +262,18 @@ The example below shows a full configuration for a MQTT lock. mqtt: lock: - name: Frontdoor - state_topic: "home-assistant/frontdoor/" + state_topic: "home-assistant/frontdoor/state" + code_format: "^\\d{4}$" command_topic: "home-assistant/frontdoor/set" + command_template: '{ "action": "{{ value }}", "code":"{{ code }}" }' payload_lock: "LOCK" payload_unlock: "UNLOCK" state_locked: "LOCK" state_unlocked: "UNLOCK" + state_locking: "LOCKING" + state_unlocking: "UNLOCKING" + state_jammed: "MOTOR_JAMMED" + state_ok: "MOTOR_OK" optimistic: false qos: 1 retain: true diff --git a/source/_integrations/mijndomein_energie.markdown b/source/_integrations/mijndomein_energie.markdown new file mode 100644 index 000000000000..13c3c1d1ffcb --- /dev/null +++ b/source/_integrations/mijndomein_energie.markdown @@ -0,0 +1,20 @@ +--- +title: Mijndomein Energie +description: Get the energy market prices from Mijndomein Energie using the EnergyZero integration. +ha_category: + - Energy + - Sensor +ha_domain: mijndomein_energie +ha_release: 2023.2 +ha_integration_type: virtual +ha_supporting_domain: energyzero +ha_supporting_integration: energyzero +ha_codeowners: + - '@klaasnicolaas' +ha_config_flow: true +ha_platforms: + - sensor +ha_iot_class: Cloud Polling +--- + +{% include integrations/supported_brand.md %} \ No newline at end of file diff --git a/source/_integrations/modbus.markdown b/source/_integrations/modbus.markdown index 68d595efc5a8..5fd0885e61f6 100644 --- a/source/_integrations/modbus.markdown +++ b/source/_integrations/modbus.markdown @@ -268,7 +268,7 @@ slave: type: integer default: 0 unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. + description: An ID that uniquely identifies this sensor. Slaves will be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception. required: false type: string {% endconfiguration %} @@ -375,7 +375,7 @@ binary_sensors: default: coil type: string unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. + description: An ID that uniquely identifies this sensor. Slaves will be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception. required: false type: string slave_count: @@ -993,12 +993,24 @@ sensors: description: Unit to attach to value. required: false type: string + min_value: + description: The minimum allowed value of a sensor. If value < min_value --> min_value. Can be float or integer + required: false + type: float + max_value: + description: The maximum allowed value of a sensor. If value > max_value --> max_value. Can be float or integer + required: false + type: float + zero_suppress: + description: Suppress values close to zero. If -zero_suppress <= value <= +zero_suppress --> 0. Can be float or integer + required: false + type: float state_class: description: The [state_class](https://developers.home-assistant.io/docs/core/entity/sensor#available-state-classes) of the sensor. required: false type: string unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. + description: An ID that uniquely identifies this sensor. Slaves will be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception. required: false type: string slave_count: diff --git a/source/_integrations/moehlenhoff_alpha2.markdown b/source/_integrations/moehlenhoff_alpha2.markdown index d136b197b3b8..2fa58dfe9090 100644 --- a/source/_integrations/moehlenhoff_alpha2.markdown +++ b/source/_integrations/moehlenhoff_alpha2.markdown @@ -13,6 +13,7 @@ ha_platforms: - binary_sensor - climate - sensor + - button ha_integration_type: integration --- diff --git a/source/_integrations/mopeka.markdown b/source/_integrations/mopeka.markdown new file mode 100644 index 000000000000..1bb82c38d2c7 --- /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/mqtt.markdown b/source/_integrations/mqtt.markdown index e567a2e5b8dd..58837871d635 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -308,6 +308,7 @@ Configuration variable names in the discovery payload may be abbreviated to cons 'hold_stat_tpl': 'hold_state_template', 'hold_stat_t': 'hold_state_topic', 'hs_cmd_t': 'hs_command_topic', + 'hs_cmd_tpl': 'hs_command_template', 'hs_stat_t': 'hs_state_topic', 'hs_val_tpl': 'hs_value_template', 'ic': 'icon', @@ -391,9 +392,6 @@ Configuration variable names in the discovery payload may be abbreviated to cons 'pl_unlk': 'payload_unlock', 'pos_clsd': 'position_closed', 'pos_open': 'position_open', - 'pow_cmd_t': 'power_command_topic', - 'pow_stat_t': 'power_state_topic', - 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', @@ -428,18 +426,22 @@ Configuration variable names in the discovery payload may be abbreviated to cons 'stat_cla': 'state_class', 'stat_clsd': 'state_closed', 'stat_closing': 'state_closing', + 'stat_jam': 'state_jammed', 'stat_off': 'state_off', 'stat_on': 'state_on', 'stat_open': 'state_open', 'stat_opening': 'state_opening', 'stat_stopped': 'state_stopped', 'stat_locked': 'state_locked', + 'stat_locking': 'state_locking', 'stat_unlocked': 'state_unlocked', + 'stat_unlocking': 'state_unlocking', 'stat_t': 'state_topic', 'stat_tpl': 'state_template', 'stat_val_tpl': 'state_value_template', 'step': 'step', 'stype': 'subtype', + 'sug_dsp_prc': 'suggested_display_precision', 'sup_clrm': 'supported_color_modes', 'sup_dur': 'support_duration', 'sup_vol': 'support_volume_set', @@ -483,6 +485,7 @@ Configuration variable names in the discovery payload may be abbreviated to cons 'whit_val_stat_t': 'white_value_state_topic', 'whit_val_tpl': 'white_value_template', 'xy_cmd_t': 'xy_command_topic', + 'xy_cmd_tpl': 'xy_command_template', 'xy_stat_t': 'xy_state_topic', 'xy_val_tpl': 'xy_value_template', ``` diff --git a/source/_integrations/mysensors.markdown b/source/_integrations/mysensors.markdown index 75c47015cec1..b5e98a66957a 100644 --- a/source/_integrations/mysensors.markdown +++ b/source/_integrations/mysensors.markdown @@ -16,8 +16,10 @@ ha_platforms: - device_tracker - light - notify + - remote - sensor - switch + - text ha_config_flow: true ha_integration_type: integration --- @@ -841,6 +843,12 @@ void send_status_message() ## Notify +
    + +The Notify platform is deprecated and replaced with the [Text platform](#text). + +
    + Setting the `target` key in the service call will target the name of the MySensors device in Home Assistant. MySensors device names follow the notation: "[Child description]" or alternatively "[Sketch name] [Node id] [Child id]". #### Notify automation example @@ -920,6 +928,96 @@ void receive(const MyMessage &message) { } ``` +## Remote + +The following type combinations are supported: + +#### MySensors version 1.4 and higher + +| S_TYPE | V_TYPE | +| -------- | ------------------ | +| S_IR | V_IR_SEND, V_LIGHT | + +#### MySensors version 1.5 and higher + +| S_TYPE | V_TYPE | +| ------------ | --------------------- | +| S_IR | V_IR_SEND, V_STATUS | + +V_LIGHT or V_STATUS is required to report the on / off state of the remote. Use either V_LIGHT or V_STATUS depending on library version. + +#### IR transceiver example sketch + +```cpp +/* + * Documentation: https://www.mysensors.org + * Support Forum: https://forum.mysensors.org + * + * https://www.mysensors.org/build/ir + */ + +#include +#include +#include + +#define SN "IR Sensor" +#define SV "1.0" +#define CHILD_ID 1 + +MySensor gw; + +char code[10] = "abcd01234"; +char oldCode[10] = "abcd01234"; +MyMessage msgCodeRec(CHILD_ID, V_IR_RECEIVE); +MyMessage msgCode(CHILD_ID, V_IR_SEND); +MyMessage msgSendCode(CHILD_ID, V_LIGHT); + +void setup() +{ + gw.begin(incomingMessage); + gw.sendSketchInfo(SN, SV); + gw.present(CHILD_ID, S_IR); + // Send initial values. + gw.send(msgCodeRec.set(code)); + gw.send(msgCode.set(code)); + gw.send(msgSendCode.set(0)); +} + +void loop() +{ + gw.process(); + // IR receiver not implemented, just a dummy report of code when it changes + if (String(code) != String(oldCode)) { + Serial.print("Code received "); + Serial.println(code); + gw.send(msgCodeRec.set(code)); + strcpy(oldCode, code); + } +} + +void incomingMessage(const MyMessage &message) { + if (message.type==V_LIGHT) { + // IR sender not implemented, just a dummy print. + if (message.getBool()) { + Serial.print("Sending code "); + Serial.println(code); + } + gw.send(msgSendCode.set(message.getBool() ? 1 : 0)); + // Always turn off device + gw.wait(100); + gw.send(msgSendCode.set(0)); + } + if (message.type == V_IR_SEND) { + // Retrieve the IR code value from the incoming message. + String codestring = message.getString(); + codestring.toCharArray(code, sizeof(code)); + Serial.print("Changing code to "); + Serial.println(code); + gw.send(msgCode.set(code)); + } +} +``` + ## Sensor The following sensor types are supported: @@ -965,6 +1063,7 @@ The following sensor types are supported: | S_INFO | V_TEXT | | S_GAS | V_FLOW, V_VOLUME | | S_GPS | V_POSITION | +| S_IR | V_IR_RECORD | | S_WATER_QUALITY | V_TEMP, V_PH, V_ORP, V_EC | ### Custom unit of measurement @@ -1051,7 +1150,6 @@ The following actuator types are supported: | S_SMOKE | V_ARMED | | S_LIGHT | V_LIGHT | | S_LOCK | V_LOCK_STATUS | -| S_IR | V_IR_SEND, V_LIGHT | #### MySensors version 1.5 and higher @@ -1073,42 +1171,6 @@ The following actuator types are supported: All V_TYPES for each S_TYPE above are required to activate the actuator for the platform. Use either V_LIGHT or V_STATUS depending on library version for cases where that V_TYPE is required. -### Services - -The MySensors switch platform exposes a service to change an IR code attribute for an IR switch device and turn the switch on. See the [example sketch](#ir-switch-sketch) for the IR switch below. - -| Service | Description | -| ---------------------- | -------------------------------------------------------------------------------------------- | -| mysensors.send_ir_code | Set an IR code as a state attribute for a MySensors IR device switch and turn the switch on. | - -The service can be used as part of an automation script. For example: - -```yaml -# Example configuration.yaml automation entry -automation: - - alias: "Turn HVAC on" - trigger: - platform: time - at: "5:30:00" - action: - service: mysensors.send_ir_code - target: - entity_id: switch.hvac_1_1 - data: - V_IR_SEND: "0xC284" # the IR code to send - - - alias: "Turn HVAC off" - trigger: - platform: time - at: "0:30:00" - action: - service: mysensors.send_ir_code - target: - entity_id: switch.hvac_1_1 - data: - V_IR_SEND: "0xC288" # the IR code to send -``` - #### Switch example sketch ```cpp @@ -1155,74 +1217,70 @@ void incomingMessage(const MyMessage &message) } ``` -#### IR switch example sketch +## Text + +The following sensor types are supported: + +#### MySensors version 2.0 and higher + +| S_TYPE | V_TYPE | +| ------ | ------ | +| S_INFO | V_TEXT | + +#### Text example sketch ```cpp /* * Documentation: https://www.mysensors.org * Support Forum: https://forum.mysensors.org - * - * https://www.mysensors.org/build/ir */ -#include +// Enable debug prints to serial monitor +#define MY_DEBUG +#define MY_RADIO_NRF24 + +#include #include -#include -#define SN "IR Sensor" +#define SN "TextSensor" #define SV "1.0" #define CHILD_ID 1 -MySensor gw; +MyMessage textMsg(CHILD_ID, V_TEXT); +bool initialValueSent = false; -char code[10] = "abcd01234"; -char oldCode[10] = "abcd01234"; -MyMessage msgCodeRec(CHILD_ID, V_IR_RECEIVE); -MyMessage msgCode(CHILD_ID, V_IR_SEND); -MyMessage msgSendCode(CHILD_ID, V_LIGHT); +void setup(void) { +} -void setup() -{ - gw.begin(incomingMessage); - gw.sendSketchInfo(SN, SV); - gw.present(CHILD_ID, S_IR); - // Send initial values. - gw.send(msgCodeRec.set(code)); - gw.send(msgCode.set(code)); - gw.send(msgSendCode.set(0)); +void presentation() { + sendSketchInfo(SN, SV); + present(CHILD_ID, S_INFO, "TextSensor1"); } -void loop() -{ - gw.process(); - // IR receiver not implemented, just a dummy report of code when it changes - if (String(code) != String(oldCode)) { - Serial.print("Code received "); - Serial.println(code); - gw.send(msgCodeRec.set(code)); - strcpy(oldCode, code); +void loop() { + if (!initialValueSent) { + Serial.println("Sending initial value"); + // Send initial values. + send(textMsg.set("-")); + Serial.println("Requesting initial value from controller"); + request(CHILD_ID, V_TEXT); + wait(2000, C_SET, V_TEXT); } } -void incomingMessage(const MyMessage &message) { - if (message.type==V_LIGHT) { - // IR sender not implemented, just a dummy print. - if (message.getBool()) { - Serial.print("Sending code "); - Serial.println(code); +void receive(const MyMessage &message) { + if (message.type == V_TEXT) { + if (!initialValueSent) { + Serial.println("Receiving initial value from controller"); + initialValueSent = true; } - gw.send(msgSendCode.set(message.getBool() ? 1 : 0)); - // Always turn off device - gw.wait(100); - gw.send(msgSendCode.set(0)); - } - if (message.type == V_IR_SEND) { - // Retrieve the IR code value from the incoming message. - String codestring = message.getString(); - codestring.toCharArray(code, sizeof(code)); - Serial.print("Changing code to "); - Serial.println(code); - gw.send(msgCode.set(code)); + // Dummy print + Serial.print("Message: "); + Serial.print(message.sensor); + Serial.print(", Message: "); + Serial.println(message.getString()); + // Send message to controller + send(textMsg.set(message.getString())); } } ``` diff --git a/source/_integrations/nuki.markdown b/source/_integrations/nuki.markdown index fa74e455abd4..405b311b14d8 100644 --- a/source/_integrations/nuki.markdown +++ b/source/_integrations/nuki.markdown @@ -13,6 +13,7 @@ ha_domain: nuki ha_platforms: - binary_sensor - lock + - sensor ha_config_flow: true ha_dhcp: true ha_integration_type: integration diff --git a/source/_integrations/number.markdown b/source/_integrations/number.markdown index d5b5ff93b8ef..122af2051a2e 100644 --- a/source/_integrations/number.markdown +++ b/source/_integrations/number.markdown @@ -33,8 +33,8 @@ The type of data a number represents impacts how it is displayed in the frontend - **data_rate**: Data rate in bit/s, kbit/s, Mbit/s, Gbit/s, B/s, kB/s, MB/s, GB/s, KiB/s, MiB/s, or GiB/s - **data_size**: Data size in bit, kbit, Mbit, Gbit, B, kB, MB, GB, TB, PB, EB, ZB, YB, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, or YiB - **distance**: Generic distance in km, m, cm, mm, mi, yd, or in -- **energy**: Energy in Wh, kWh or MWh -- **frequency**: Frequency in Hz, kHz, MHz or GHz +- **energy**: Energy in Wh, kWh, MWh, MJ, or GJ +- **frequency**: Frequency in Hz, kHz, MHz, or GHz - **gas**: Gasvolume in m³, ft³, or CCF - **humidity**: Percentage of humidity in the air - **illuminance**: The current light level in lx @@ -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/onewire.markdown b/source/_integrations/onewire.markdown index 50a93d58af53..899a2998dea8 100644 --- a/source/_integrations/onewire.markdown +++ b/source/_integrations/onewire.markdown @@ -10,6 +10,7 @@ ha_codeowners: - '@garbled1' - '@epenet' ha_domain: onewire +ha_quality_scale: gold ha_platforms: - binary_sensor - diagnostics diff --git a/source/_integrations/onvif.markdown b/source/_integrations/onvif.markdown index aa8b219f0f68..c3297eee1a83 100644 --- a/source/_integrations/onvif.markdown +++ b/source/_integrations/onvif.markdown @@ -15,6 +15,7 @@ ha_platforms: - camera - diagnostics - sensor + - switch ha_integration_type: integration --- @@ -72,6 +73,8 @@ To help with development of this component, enable `info` level logging for `hom | Last Clock Synchronization | Sensor | Timestamp | When the device clock was last synchronized. | | Last Backup | Sensor | Timestamp | When the last backup of the device configuration has been retrieved. | +If you are running into trouble with this sensor, please refer to the [Troubleshooting section](/integrations/ffmpeg/#troubleshooting). + ### Service `onvif.ptz` If your ONVIF camera supports PTZ, you will be able to pan, tilt or zoom your camera. @@ -88,4 +91,12 @@ If your ONVIF camera supports PTZ, you will be able to pan, tilt or zoom your ca | `move_mode` | PTZ moving mode. Allowed values: `ContinuousMove`, `RelativeMove`, `AbsoluteMove`, `GotoPreset`, `Stop`. Default :`RelativeMove` | | `continuous_duration` | Set ContinuousMove delay in seconds before stopping the move. Allowed values: floating point numbers or integer. Default : 0.5 | -If you are running into trouble with this sensor, please refer to the [Troubleshooting section](/integrations/ffmpeg/#troubleshooting). +### Supported Switches + +This integration uses the ONVIF auxiliary command and imaging service to send certain settings and information to the camera via switch entities. Below is a list of currently supported switches. + +| Name | Entity Name | Description | +|----------|-------------|-------------| +| IR lamp | `ir_lamp` | Turn infrared lamp on and off via `IrCutFilter` ONVIF imaging setting. | +| Autofocus | `autofocus` | Turn autofocus on and off via `AutoFocusMode` ONVIF imaging setting. | +| Wiper | `wiper` | Turn on the lens wiper on and off via the `Wiper` ONVIF auxiliary command. | diff --git a/source/_integrations/openai_conversation.markdown b/source/_integrations/openai_conversation.markdown new file mode 100644 index 000000000000..87196f9d5ca8 --- /dev/null +++ b/source/_integrations/openai_conversation.markdown @@ -0,0 +1,49 @@ +--- +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://platform.openai.com/account/api-keys). This is a paid service, we advise you to monitor your costs in the [OpenAI portal](https://platform.openai.com/account) closely and configure [usage limits](https://platform.openai.com/account/billing/limits) to avoid unwanted costs associated with using the service. + +{% include integrations/config_flow.md %} + +### Generate an API Key + +The OpenAI key is used to authenticate requests to the OpenAI API. To generate an API key take the following steps: + +- Log in to the [OpenAI portal](https://platform.openai.com/account) or sign up for an account. +- Enable billing with a valid credit card +- Configure [usage limits](https://platform.openai.com/account/billing/limits). +- Visit the [API Keys page](https://platform.openai.com/account/api-keys) to retrieve the API key you'll use to configure the integration. + +{% include integrations/option_flow.md %} +{% configuration_basic %} +Prompt Template: + description: The starting text for the AI language model to generate new text from. This text can include information about your Home Assistant instance, devices, and areas and is written using [Home Assistant Templating](/docs/configuration/templating/). + +Completion Model: + description: The GPT-3 language model is used for text generation. You can find more details on the available models in the [OpenAI GPT-3 Documentation](https://platform.openai.com/docs/models/gpt-3). + +Maximum Tokens to Return in Response: + description: The maximum number of words or "tokens" that the AI model should generate in its completion of the prompt. For more information, see the [OpenAI Completion Documentation](https://platform.openai.com/docs/guides/completion/introduction). + +Temperature: + description: A value that determines the level of creativity and risk-taking the model should use when generating text. A higher temperature means the model is more likely to generate unexpected results, while a lower temperature results in more deterministic results. See the [OpenAI Completion Documentation](https://platform.openai.com/docs/guides/completion/introduction) for more information. + +Top P: + description: An alternative to temperature, top_p determines the proportion of the most likely word choices the model should consider when generating text. A higher top_p means the model will only consider the most likely words, while a lower top_p means a wider range of words, including less likely ones, will be considered. For more information, see the [OpenAI Completion API Reference](https://platform.openai.com/docs/api-reference/completions/create#completions/create-top_p). + +{% endconfiguration_basic %} diff --git a/source/_integrations/openalpr_local.markdown b/source/_integrations/openalpr_local.markdown deleted file mode 100644 index 2f438773d062..000000000000 --- a/source/_integrations/openalpr_local.markdown +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: OpenALPR Local -description: Instructions on how to integrate licences plates with OpenALPR local into Home Assistant. -ha_category: - - Image Processing -ha_iot_class: Local Push -ha_release: 0.36 -ha_domain: openalpr_local -ha_integration_type: integration ---- - -
    - This integration is pending removal from Home Assistant and will be no longer available as of Home Assistant 2022.10. -
    - -The [OpenALPR](https://www.openalpr.com/) integration for Home Assistant allows you -to process vehicle license plates from a camera. You can use this information to -trigger [automations](/integrations/automation/) like opening a garage door. - -For using the result inside an automation rule, take a look at the -[image processing integration](/integrations/image_processing) page. - -## Local installation - -If you want process all data locally, you will need version 2.3.1 or higher of the -`alpr` command line tool. - -If you don't find binaries for your distribution, you can compile the tool from source. -Documentation of how to build OpenALPR is found -[here](https://github.com/openalpr/openalpr/wiki). - -On a Debian system you can use the following `cmake` command to build only the command -line tool: - -```bash -cmake -DWITH_TEST=FALSE -DWITH_BINDING_JAVA=FALSE --DWITH_BINDING_PYTHON=FALSE \ - --DWITH_BINDING_GO=FALSE -DWITH_DAEMON=FALSE -DCMAKE_INSTALL_PREFIX:PATH=/usr .. -``` - -For other operating systems, please refer to the -[OpenALPR wiki](https://github.com/openalpr/openalpr/wiki). - -Verify your `alpr` installation with a command like the following: - -```bash -wget -O- -q http://plates.openalpr.com/h786poj.jpg | alpr - -``` - -### Configuration - -```yaml -# Example configuration.yaml entry -image_processing: - - platform: openalpr_local - region: eu - source: - - entity_id: camera.garage -``` - -{% configuration %} -region: - description: Country or region. List of [supported values](https://github.com/openalpr/openalpr/tree/master/runtime_data/config). - required: true - type: string -alpr_bin: - description: The command line tool alpr from OpenALPR software for local processing. - required: false - type: string - default: alpr -confidence: - description: The minimum confidence in percent to process with Home Assistant. - required: false - type: integer - default: 80 -source: - description: List of image sources. - required: true - type: list - keys: - entity_id: - description: A camera entity id to get the picture from. - required: true - type: string - name: - description: This parameter allows you to override the name of your OpenALPR entity. - required: false - type: string -{% endconfiguration %} diff --git a/source/_integrations/oralb.markdown b/source/_integrations/oralb.markdown index 1e89d99cc06e..fd78d674d23c 100644 --- a/source/_integrations/oralb.markdown +++ b/source/_integrations/oralb.markdown @@ -8,6 +8,7 @@ ha_release: 2022.11 ha_iot_class: Local Push ha_codeowners: - '@bdraco' + - '@Lash-L' ha_domain: oralb ha_config_flow: true ha_platforms: @@ -24,17 +25,22 @@ The Oral-B integration will automatically discover devices once the [Bluetooth]( ## Supported devices - [IO 4 Series](https://oralb.com/en-us/products/electric-toothbrushes/oralbio) +- [IO 6 Series](https://oralb.com/en-us/products/electric-toothbrushes/io-series-6-electric-toothbrush-gray-opal/) - [IO 7 Series](https://oralb.com/en-us/products/electric-toothbrushes/oralbio) - [IO 8 Series](https://oralb.com/en-us/products/electric-toothbrushes/oralbio) - [IO 9 Series](https://oralb.com/en-us/products/electric-toothbrushes/oralbio) +- Smart Series 4000 +- Smart Series 6000 - [Smart Series 7000](https://oralb.com/en-us/products/electric-toothbrushes/smart-7000-rechargeable-electric-toothbrush/) +- Smart Series 8000 - [Genius Series 9000](https://oralb.com/en-us/products/electric-toothbrushes/genius-9600-rechargeable-electric-toothbrush-white/) +- Triumph V2 ## Sensor * Mode - selected cleaning mode e.g. daily clean. * Number of sectors - brushing areas set in the **Set Pacer Visualisation** in the brushing preferences in the mobile app. -* Sector - the current area of the mouth you are brushing. -* Sector time - amount time brushing the current sector in seconds. +* Sector - the current sector of brush goal you are in (i.e. if brush goal is 2:00 minutes, and you are at 0:37, you are in sector 2) * Time - total brushing time in seconds. * Toothbrush state - whether the toothbrush is running, idle. +* Battery - toothbrush battery percentage. diff --git a/source/_integrations/otbr.markdown b/source/_integrations/otbr.markdown new file mode 100644 index 000000000000..98d802a9c4e3 --- /dev/null +++ b/source/_integrations/otbr.markdown @@ -0,0 +1,18 @@ +--- +title: Open Thread Border Router +ha_category: + - Other +ha_release: 2023.2 +ha_quality_scale: internal +ha_codeowners: + - '@home-assistant/core' +ha_domain: otbr +ha_iot_class: Local Polling +ha_platforms: +ha_integration_type: integration +--- + +The Open Thread Border Router integration allows calling an Open Thread Border Router's REST API from Python and via WebSocket. +The integration is automatically set up when the "Silicon Labs Multiprotocol" add-on is installed. + +{% include integrations/config_flow.md %} diff --git a/source/_integrations/powerwall.markdown b/source/_integrations/powerwall.markdown index dfe91bea7e4a..ef1de6b55019 100644 --- a/source/_integrations/powerwall.markdown +++ b/source/_integrations/powerwall.markdown @@ -5,17 +5,20 @@ ha_category: - Binary Sensor - Energy - Sensor + - Switch ha_release: 0.108 ha_iot_class: Local Polling ha_config_flow: true ha_codeowners: - '@bdraco' - '@jrester' + - '@daniel-simpson' ha_domain: powerwall ha_dhcp: true ha_platforms: - binary_sensor - sensor + - switch ha_integration_type: integration --- @@ -25,6 +28,7 @@ There is currently support for the following device types within Home Assistant: - [Binary Sensor](#binary-sensor) - [Sensor](#sensor) +- [Switch](#switch) {% include integrations/config_flow.md %} @@ -65,6 +69,12 @@ The following sensors show the direction of energy: - Powerwall Generator Export - Generator energy exported in kWh - Powerwall Generator Import - Generator energy imported in kWh +### Switch + +The following switches are added for each Powerwall: + +- Off-Grid operation - Take your Powerwall off-grid (simulate a grid outage) + ### Device Info - Model Number diff --git a/source/_integrations/profiler.markdown b/source/_integrations/profiler.markdown index 3cd11b4e5f8a..99300f75b835 100644 --- a/source/_integrations/profiler.markdown +++ b/source/_integrations/profiler.markdown @@ -53,6 +53,10 @@ gprof2dot -f pstats profile.1234567890123456.cprof | dot -Tsvg -o profile.svg ### Service `profiler.memory` +
    +This service is unavailable when using Python 3.11 as the underlying guppy3 library does not yet support Python 3.11. +
    + Start the memory profiler for the specified number of seconds. | Service data attribute | Optional | Description | diff --git a/source/_integrations/pvpc_hourly_pricing.markdown b/source/_integrations/pvpc_hourly_pricing.markdown index fe2187f5a631..7e91863fab5c 100644 --- a/source/_integrations/pvpc_hourly_pricing.markdown +++ b/source/_integrations/pvpc_hourly_pricing.markdown @@ -43,43 +43,6 @@ In case you did nothing after the tariff change on 2021-06-01, both powers are e You can add up to 2 sensors (one for each geographic zone) by adding them again through the integrations panel, and you can change the sensor configuration anytime by going to the integration's options. -### Advanced configuration - -PVPC Hourly Pricing allows manual configuration by adding a section to your `configuration.yaml`. - -```yaml -# Set up electricity price sensors as a component: -pvpc_hourly_pricing: - - name: "PVPC" - tariff: "2.0TD" - power: 3.45 - power_p3: 4.6 - - name: "PVPC-CYM" - tariff: "2.0TD (Ceuta/Melilla)" -``` - -{% configuration %} -name: - description: Custom name for the sensor. - required: true - type: string -tariff: - description: Electric tariff by geographic zone. - required: true - default: 2.0TD - type: string -power: - description: Contracted electric power in kW. - required: false - default: 3.3 - type: float -power_p3: - description: Contracted electric power in kW for valley period (P3). - required: false - default: 3.3 - type: float -{% endconfiguration %} -
    The sensor provides an hourly price for energy consumed, but the variable cost of energy is only one of the factors that add up to the electricity bill: diff --git a/source/_integrations/qnap_qsw.markdown b/source/_integrations/qnap_qsw.markdown index d37dc7a5d928..08d9d797c56e 100644 --- a/source/_integrations/qnap_qsw.markdown +++ b/source/_integrations/qnap_qsw.markdown @@ -62,6 +62,17 @@ The following *sensors* are created: | temperature | Switch temperature. | | uptime | Uptime seconds. | +The following sensors are created for each port (or LACP): + +| Condition | Description | +| :------------------ | :--------------------------------- | +| link_speed | Link speed. | +| rx | RX bytes. | +| rx_errors | Number of RX errors. | +| rx_speed | RX speed. | +| tx | TX bytes. | +| tx_speed | TX speed. | + ## Update | Update | Description | diff --git a/source/_integrations/rainbird.markdown b/source/_integrations/rainbird.markdown index 829e3576cb08..e7b606e0c774 100644 --- a/source/_integrations/rainbird.markdown +++ b/source/_integrations/rainbird.markdown @@ -3,8 +3,10 @@ title: Rain Bird description: Instructions on how to integrate your Rain Bird LNK WiFi Module within Home Assistant. ha_category: - Irrigation + - Binary Sensor - Sensor - Switch +ha_config_flow: true ha_release: 0.61 ha_iot_class: Local Polling ha_codeowners: @@ -22,109 +24,43 @@ This `rainbird` integration allows interacting with [LNK WiFi](https://www.rainb There is currently support for the following device types within Home Assistant: -- [Sensor](#sensor) +- [Binary Sensor](#binary-sensor) +- [Number](#number) - [Switch](#switch) -## Configuration +{% include integrations/config_flow.md %} -To enable it, add the following to your `configuration.yaml` file: +## Configuration Options -```yaml -# Example configuration.yaml entry -rainbird: - host: IP_ADDRESS_OF_MODULE - password: YOUR_PASSWORD - trigger_time: 360 - -``` - -{% configuration %} -host: - description: IP Address of the Module - required: true - type: string -password: - description: The password for accessing the module. - required: true - type: string -trigger_time: - description: Irrigation time. The time will be rounded down to whole minutes. - required: true - type: time -zones: - description: Dictionary of zone configurations - required: false - type: map - keys: - ZONE_NUMBER: - description: Zone ID - type: map - keys: - friendly_name: - description: Friendly name to see in GUI - required: false - type: string - trigger_time: - description: Irrigation time. Seconds are ignored. - required: false - type: time -{% endconfiguration %} - - -More complex configuration using all possible features could look like this example: -```yaml -# Example configuration.yaml entry -rainbird: - - host: IP_ADDRESS_OF_MODULE - password: YOUR_PASSWORD - trigger_time: - minutes: 6 - zones: - 1: - friendly_name: My zone 1 - trigger_time: - minutes: 6 - 2: - friendly_name: My zone 2 - trigger_time: - minutes: 2 - - host: IP_ADDRESS_OF_ANOTHER_MODULE - password: YOUR_ANOTHER_PASSWORD - trigger_time: 0:06 - zones: - 1: - friendly_name: My zone 1 - trigger_time: 0:06 - 3: - friendly_name: My zone 3 - trigger_time: 0:05 -``` -
    -Please note that due to the implementation of the API within the LNK Module, there is a concurrency issue. For example, the Rain Bird app will give connection issues (like already a connection active). -
    - -## Sensor - -This `rainbird` sensor allows interacting with [LNK WiFi](https://www.rainbird.com/products/lnk-wifi-module) module of the Rain Bird Irrigation system in Home Assistant. - -The integration adds `rainsensor` and `raindelay` sensors and their `binary_sensor` alternatives. +The integration has a configuration option to change the default amount of time that the irrigation +will run when turning on a zone switch (default is 6 minutes). This can be overridden with a service call (see below). -## Switch +## Binary Sensor + +The `rainsensor` sensor will tell if you if the device has detected rain. + +## Number -This `rainbird` switch platform allows interacting with [LNK WiFi](https://www.rainbird.com/products/lnk-wifi-module) module of the Rain Bird Irrigation system in Home Assistant. +The Rain Delay Number Entity lets you set and view the number of days, if any, the automatic irrigation schedule has been delayed. + +## Switch Switches are automatically added for all available zones of configured controllers. ## Services -The Rain Bird switch platform exposes a service to start a single irrigation for a given duration. +The integration exposes services to give additional control over a Rain Bird device. + +### `rainbird.start_irrigation` + +Start a Rain Bird zone for a set number of minutes. This service accepts a Rain Bird sprinkler +zone switch entity and allows a custom duration unlike the switch. -| Service | Description | -| ------- | ----------- | -| rainbird.start_irrigation | Set a duration state attribute for a switch and turn the irrigation on.| -| rainbird.set_rain_delay | Set how long automatic irrigation is turned off.| +| Service Data Attribute | Optional | Description | +| ---------------------- | -------- | ----------------------------------------------------- | +| `entity_id` | no | The Rain Bird Sprinkler zone switch to turn on. | +| `duration` | no | Number of minutes for this zone to be turned on. | -The service can be used as part of an automation script. For example: ```yaml # Example configuration.yaml automation entry @@ -136,6 +72,6 @@ automation: action: - service: rainbird.start_irrigation data: - entity_id: switch.sprinkler_1 + entity_id: switch.rain_bird_sprinkler_1 duration: 5 -``` +``` \ No newline at end of file diff --git a/source/_integrations/recollect_waste.markdown b/source/_integrations/recollect_waste.markdown index e4f5194b8de2..ad999774d78e 100644 --- a/source/_integrations/recollect_waste.markdown +++ b/source/_integrations/recollect_waste.markdown @@ -10,12 +10,13 @@ ha_codeowners: - '@bachya' ha_config_flow: true ha_platforms: + - calendar - diagnostics - sensor ha_integration_type: service --- -The `recollect_waste` integration allows you to track the next scheduled waste pickup and what type of waste from [ReCollect](https://recollect.net/waste-haulers/). +The `recollect_waste` integration allows you to track the next scheduled waste pickup and what type of waste from [ReCollect Waste](https://recollect.net/waste-haulers/). To use this integration, you must know both your ReCollect Place and Service IDs. In general, cities/municipalities that utilize ReCollect will give you a way to subscribe to a calendar with pickup dates. If you examine the iCal URL for this calendar, the Place and Service IDs are embedded in it: diff --git a/source/_integrations/recorder.markdown b/source/_integrations/recorder.markdown index 11c335cc4587..a6bc6c19cc2a 100644 --- a/source/_integrations/recorder.markdown +++ b/source/_integrations/recorder.markdown @@ -75,9 +75,9 @@ recorder: default: 10 type: integer commit_interval: - description: How often (in seconds) the events and state changes are committed to the database. The default of `1` allows events to be committed almost right away without trashing the disk when an event storm happens. Increasing this will reduce disk I/O and may prolong disk (SD card) lifetime with the trade-off being that the logbook and history will lag. If this is set to `0` (zero), commit are made as soon as possible after an event is processed. + description: How often (in seconds) the events and state changes are committed to the database. The default of `5` allows events to be committed almost right away without trashing the disk when an event storm happens. Increasing this will reduce disk I/O and may prolong disk (SD card) lifetime with the trade-off being that the logbook and history will lag. If this is set to `0` (zero), commit are made as soon as possible after an event is processed. required: false - default: 1 + default: 5 type: integer exclude: description: Configure which integrations should be excluded from recordings. ([Configure Filter](#configure-filter)) diff --git a/source/_integrations/renault.markdown b/source/_integrations/renault.markdown index 8cabf016667a..d83638a30761 100644 --- a/source/_integrations/renault.markdown +++ b/source/_integrations/renault.markdown @@ -13,6 +13,7 @@ ha_config_flow: true ha_codeowners: - '@epenet' ha_domain: renault +ha_quality_scale: platinum ha_platforms: - binary_sensor - button @@ -88,11 +89,3 @@ Notes: }, ] ``` - -### Service `renault.charge_start` - -Start charge on vehicle. - - | Service data attribute | Required | Description | - | ---------------------- | -------- | ----------- | - | `vehicle`| yes | device_id of the vehicle | diff --git a/source/_integrations/reolink.markdown b/source/_integrations/reolink.markdown index 5eebafa85070..2305d9222958 100644 --- a/source/_integrations/reolink.markdown +++ b/source/_integrations/reolink.markdown @@ -7,7 +7,7 @@ ha_iot_class: Local Polling ha_release: 2023.1 ha_domain: reolink ha_codeowners: - - '@starkillerOG' + - "@starkillerOG" ha_config_flow: true ha_platforms: - Camera @@ -23,14 +23,35 @@ A Reolink user account with admin privileges is needed for the proper operation {% include integrations/option_flow.md %} {% configuration_basic %} Protocol: - description: Switch between RTSP or RTMP streaming protocol. + description: Switch between RTSP, RTMP or FLV streaming protocol. {% endconfiguration_basic %} ## Camera streams This integration creates a few camera entities, one for each stream type with different resolutions: Main, Sub, Ext, and Snapshots. The Sub stream camera entity is enabled by default; the other streams are disabled by default. -The snapshots stream provides a sequence of image snapshots giving very low latency at the cost of a very low frame rate; this can be used when the hi-res RTMP/RTSP video stream has too much lag. +The Images stream provides a sequence of image snapshots giving very low latency at the cost of a very low frame rate; this can be used when the RTMP/RTSP/FLV video stream has too much lag. + +## Binary sensors + +Depending on the supported features of the camera binary sensors are added for: + +- Motion detection +- Doorbell presses +- AI person detection +- AI vehicle detection +- AI pet detection +- AI face detection + +These sensors are polled every 60 seconds and receive ONVIF push events for immediate updates. +Not all camera models generate ONVIF push events for all event types, some binary sensors might, therefore, only be polled. + +## Number entities + +Depending on the supported features of the camera number entities are added for: + +- Optical zoom control +- Focus control ## Tested models diff --git a/source/_integrations/ruuvi_gateway.markdown b/source/_integrations/ruuvi_gateway.markdown new file mode 100644 index 000000000000..546f6eb7ef37 --- /dev/null +++ b/source/_integrations/ruuvi_gateway.markdown @@ -0,0 +1,31 @@ +--- +title: Ruuvi Gateway +description: Support for Ruuvi Gateway devices acting as BLE remote scanners. +ha_category: + - Sensor +ha_release: '2023.2' +ha_iot_class: Local Polling +ha_config_flow: true +ha_codeowners: + - '@akx' +ha_domain: ruuvi_gateway +ha_dhcp: true +ha_integration_type: integration +--- + +Integrates [Ruuvi Gateway](https://ruuvi.com/gateway/) devices as +polling BLE remote scanners [via the `/history` endpoint][poll]. + +## Setup + +Make sure to [enable Bearer Token authentication][poll] on the Ruuvi Gateway device +(and take note of the token). + +You may also wish to enable scanning for _all_ BLE beacons (not just RuuviTags); +be sure to set the "Use Ruuvi Cloud or/and a custom server and configure more settings" +option on the Cloud Options setup page, and when you get to the "Bluetooth Scanning" page, +select "All (including third party beacons)". + +{% include integrations/config_flow.md %} + +[poll]: https://docs.ruuvi.com/gw-examples/polling-mode diff --git a/source/_integrations/rympro.markdown b/source/_integrations/rympro.markdown new file mode 100644 index 000000000000..3e53b11ca292 --- /dev/null +++ b/source/_integrations/rympro.markdown @@ -0,0 +1,23 @@ +--- +title: Read Your Meter Pro +description: Instructions on how to integrate water meters through Read Your Meter Pro. +ha_category: + - Sensor +ha_release: '2023.2' +ha_iot_class: Cloud Polling +ha_config_flow: true +ha_codeowners: + - '@OnFreund' +ha_domain: rympro +ha_platforms: + - sensor +ha_integration_type: integration +--- + +This integration connects with a [Read Your Meter Pro](https://rym-pro.com/) account to get water meter reads into Home Assistant. + +{% include integrations/config_flow.md %} + +## Supported Platforms: + +- [Sensor](/integrations/sensor/) diff --git a/source/_integrations/select.markdown b/source/_integrations/select.markdown index 16af11e944e3..566ee76dccf8 100644 --- a/source/_integrations/select.markdown +++ b/source/_integrations/select.markdown @@ -15,10 +15,127 @@ Keeps track on `select` entities in your environment, their state, and allows you to control them. This integration allows other integrations to offer a limited set of selectable options for the entity. -### Services +## Services -The Select entities registers the following services: +The select entity exposes additional to control the entity in, for example, +automation or scripts. These service can be created via the UI, but are +also available in YAML (for which examples are provided below). -| Service | Data | Description | -| ------- | ---- | ----------- | -| `select_option` | `option`
    `entity_id(s)`
    `area_id(s)` | Set the current select option of specific `select` entities +### Service `select.select_first` + +The {% my developer_call_service service="select.select_first" %} service +changes the selected option of the select entity to the first option in the +list of options available. + +This service does not have additional options. + + {% my developer_call_service badge service="select.select_first" %} + +An example in YAML: + +```yaml +service: select.select_first +target: + entity_id: select.my_entity +``` + +### Service `select.select_last` + +The {% my developer_call_service service="select.select_last" %} service changes +the selected option of the select entity to the last option in the list of +options available. + +This service does not have additional options. + +{% my developer_call_service badge service="select.select_last" %} + +An example in YAML: + +```yaml +service: select.select_last +target: + entity_id: select.my_entity +``` + +### Service `select.select_next` + +The {% my developer_call_service service="select.select_next" %} service changes +the selected option of the select entity to the next option in the list of +options available. If the current select option is unknown, the first option +in the list is selected instead. + +In case the current select option is the last option in the list, it will by +default, cycle back the first option and select that one instead. This cycle +behavior can be disabled by setting the `cycle` option to `false` in the +service call data. + +{% my developer_call_service badge service="select.select_next" %} + +Examples in YAML: + +```yaml +service: select.select_next +target: + entity_id: select.my_entity +``` + +```yaml +# Disable cycling back to the first option +service: select.select_next +target: + entity_id: select.my_entity +data: + cycle: false +``` + +### Service `select.select_option` + +The {% my developer_call_service service="select.select_option" %} service +changes the selected option to a specific desired option provided in the +service call using the required `option` service call data. + +The service call wil not succeed if the selected option is not available in +the list of options for the targeted entity. + +{% my developer_call_service badge service="select.select_option" %} + +An example in YAML: + +```yaml +service: select.select_option +target: + entity_id: select.my_entity +data: + option: "example_option" +``` + +### Service `select.select_previous` + +The {% my developer_call_service service="select.select_previous" %} service +changes the selected option of the select entity to the previous option in the +list of options available. If the current select option is unknown, the +last option in the list is selected instead. + +In case the current select option is the first option in the list, it will by +default, cycle back the last option and select that one instead. This cycle +behavior can be disabled by setting the `cycle` option to `false` in the +service call data. + +{% my developer_call_service badge service="select.select_previous" %} + +Examples in YAML: + +```yaml +service: select.select_previous +target: + entity_id: select.my_entity +``` + +```yaml +# Disable cycling back to the last option +service: select.select_previous +target: + entity_id: select.my_entity +data: + cycle: false +``` diff --git a/source/_integrations/sensor.markdown b/source/_integrations/sensor.markdown index 2335a91ea447..4b7a037f542a 100644 --- a/source/_integrations/sensor.markdown +++ b/source/_integrations/sensor.markdown @@ -7,11 +7,11 @@ ha_release: 0.7 ha_quality_scale: internal ha_domain: sensor ha_codeowners: - - '@home-assistant/core' + - "@home-assistant/core" ha_integration_type: entity --- -Sensors are a basic platform component in Home Assistant. They monitor the states and conditions of a variety of entities. An entity can be many things. This can include a physical device like a motion sensor that reports the battery level, a web service that retrieves the weather temperature, a built-in function that calculates the sun's elevation relative to your GPS position, or even a custom sensor you may have created to report the free space on your laptop. These are all *things* reporting different types of information. +Sensors are a basic platform component in Home Assistant. They monitor the states and conditions of a variety of entities. An entity can be many things. This can include a physical device like a motion sensor that reports the battery level, a web service that retrieves the weather temperature, a built-in function that calculates the sun's elevation relative to your GPS position, or even a custom sensor you may have created to report the free space on your laptop. These are all _things_ reporting different types of information. Some of these sensors are built-in to Home Assistant, some are created automatically when you add an integration (see this [list](/integrations/#sensor)), and some can be created manually. The [Statistics](/integrations/statistics) and [Template](/integrations/template) sensors are two examples of the last case. @@ -25,16 +25,16 @@ The type of data a sensor returns impacts how it is displayed in the frontend. T - **atmospheric_pressure**: Atmospheric pressure in cbar, bar, hPa, inHg, kPa, mbar, Pa or psi - **battery**: Percentage of battery that is left in % - **carbon_dioxide**: Carbon Dioxide in CO2 (Smoke) in ppm -- **carbon_monoxide**: Carbon Monoxide in CO (Gas CNG/LPG) in ppm +- **carbon_monoxide**: Carbon Monoxide in CO (Gas CNG/LPG) in ppm - **current**: Current in A, mA - **data_rate**: Data rate in bit/s, kbit/s, Mbit/s, Gbit/s, B/s, kB/s, MB/s, GB/s, KiB/s, MiB/s or GiB/s - **data_size**: Data size in bit, kbit, Mbit, Gbit, B, kB, MB, GB, TB, PB, EB, ZB, YB, KiB, MiB, GiB, TiB, PiB, EiB, ZiB or YiB - **date**: Date string (ISO 8601) -- **distance**: Generic distance in km, m, cm, mm, mi, yd or in -- **duration**: Duration in d, h, min or s -- **energy**: Energy in Wh, kWh or MWh +- **distance**: Generic distance in km, m, cm, mm, mi, yd, or in +- **duration**: Duration in d, h, min, or s +- **energy**: Energy in Wh, kWh, MWh, MJ, or GJ - **enum**: Has a limited set of (non-numeric) states -- **frequency**: Frequency in Hz, kHz, MHz or GHz +- **frequency**: Frequency in Hz, kHz, MHz, or GHz - **gas**: Gasvolume in m³, ft³ or CCF - **humidity**: Percentage of humidity in the air in % - **illuminance**: The current light level in lx @@ -58,14 +58,14 @@ 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 -- **volume**: Generic volume in L, mL, gal, fl. oz., m³, ft³ or CCF -- **water**: Water consumption in L, gal, m³, ft³ or CCF -- **weight**: Generic mass in kg, g, mg, µg, oz, lb or st -- **wind_speed**: Wind speed in ft/s, km/h, kn, m/s or mph +- **volume**: Generic volume in L, mL, gal, fl. oz., m³, ft³, or CCF +- **water**: Water consumption in L, gal, m³, ft³, or CCF +- **weight**: Generic mass in kg, g, mg, µg, oz, lb, or st +- **wind_speed**: Wind speed in ft/s, km/h, kn, m/s, or mph

    diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown index 7ab82ff789aa..34dc163add2e 100644 --- a/source/_integrations/sensor.mqtt.markdown +++ b/source/_integrations/sensor.mqtt.markdown @@ -170,6 +170,10 @@ payload_not_available: required: false type: string default: offline +suggested_display_precision: + description: The number of decimals which should be used in the sensor's state after rounding. + required: false + type: integer qos: description: The maximum QoS level of the state topic. required: false @@ -323,6 +327,7 @@ mqtt: sensor: - name: "Temperature" state_topic: "office/sensor1" + suggested_display_precision: 1 unit_of_measurement: "°C" value_template: "{{ value_json.temperature }}" - name: "Humidity" diff --git a/source/_integrations/sfr_box.markdown b/source/_integrations/sfr_box.markdown new file mode 100644 index 000000000000..4d3c46af7cfa --- /dev/null +++ b/source/_integrations/sfr_box.markdown @@ -0,0 +1,27 @@ +--- +title: SFR Box +description: Instructions on how to integrate SFR Box into Home Assistant. +ha_category: + - Sensor +ha_release: 2023.2 +ha_iot_class: Local Polling +ha_config_flow: true +ha_codeowners: + - '@epenet' +ha_domain: sfr_box +ha_platforms: + - binary_sensor + - button + - sensor +ha_integration_type: device +--- + +The SFR Box integration offers integration with the **SFR** broadband router. + +This integration provides the following platforms: + +- Binary Sensors - such as ADSL status. +- Buttons - such as reboot. +- Sensors - such as ADSL line status, attenuation, noise and data rate. + +{% include integrations/config_flow.md %} diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index 9133d54f53c3..d8842a335744 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -193,7 +193,7 @@ You can also create automations using YAML, for example: | `SL` | `single_long` | | `LS` | `long_single` | -Generation 2 devices use the values `btn_down`, `btn_up`, `single_push`, `double_push` and `long_push` as `click_type`. +Generation 2 devices use the values `btn_down`, `btn_up`, `single_push`, `double_push`, `triple_push` and `long_push` as `click_type`.

    diff --git a/source/_integrations/snooz.markdown b/source/_integrations/snooz.markdown index 5751f78bb1d5..85f256e01f4c 100644 --- a/source/_integrations/snooz.markdown +++ b/source/_integrations/snooz.markdown @@ -49,3 +49,61 @@ Fan speed percentage is mapped to the device volume level.
    Speed percentages less than 10 have no effect - they all map to a value of 1 on the device.
    + +## Services + +### Service `snooz.transition_on` + +Transition the volume level over the specified duration. If the device is powered off, the transition will start at the lowest volume level. + +{% my developer_call_service badge service="snooz.transition_on" %} + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `duration` | yes | Number of seconds to transition to target volume. +| `volume` | yes | Percentage volume level. If not specified, the volume on the device is used. + +#### Automation example + +```yaml +automation: + - trigger: + - platform: time + at: "04:20:00" + action: + - service: snooz.transition_on + target: + entity_id: fan.snooz_abcd + data: + volume: 33 + duration: 120 +``` + +### Service `snooz.transition_off` + +Transition the volume level to the lowest setting over the specified duration, then power off the device. + +
    +Once the transition completes, the volume level is restored to the value before the transition started. +
    + +{% my developer_call_service badge service="snooz.transition_off" %} + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `duration` | yes | Number of seconds to complete the transition. + +#### Automation example + +```yaml +automation: + - trigger: + - platform: time + at: "16:20:00" + action: + - service: snooz.transition_off + target: + entity_id: fan.snooz_abcd + data: + duration: 120 +``` diff --git a/source/_integrations/sql.markdown b/source/_integrations/sql.markdown index 59e453c34fd0..0da077cca3a4 100644 --- a/source/_integrations/sql.markdown +++ b/source/_integrations/sql.markdown @@ -19,8 +19,68 @@ ha_integration_type: integration The `sql` sensor platform enables you to use values from an [SQL](https://en.wikipedia.org/wiki/SQL) database supported by the [sqlalchemy](https://www.sqlalchemy.org) library, to populate a sensor state (and attributes). This can be used to present statistics about Home Assistant sensors if used with the `recorder` integration database. It can also be used with an external data source. +**This integration can be configured using both config flow and by YAML.** + {% include integrations/config_flow.md %} +## Configuration by YAML + +To configure this sensor, define the sensor connection variables and a list of queries to your `configuration.yaml` file. A sensor will be created for each query. + +To enable it, add the following lines to your `configuration.yaml` file (example by required fields): + +{% raw %} +```yaml +# Example configuration.yaml +sql: + - name: Sun state + query: > + SELECT * + FROM states + WHERE entity_id = 'sun.sun' + ORDER BY state_id + DESC LIMIT 1; + column: "state" +``` +{% endraw %} + +{% configuration %} +sql: + description: Integration. + required: true + type: map + keys: + db_url: + description: The URL which points to your database. See [supported engines](/integrations/recorder/#custom-database-engines). + required: false + default: "Defaults to the default recorder `db_url` (not the current `db_url` of recorder)." + type: string + name: + description: The name of the sensor. + required: true + type: string + query: + description: An SQL QUERY string, should return 1 result at most. + required: true + type: string + column: + description: The field name to select. + required: true + type: string + unit_of_measurement: + description: Defines the units of measurement of the sensor, if any. + required: false + type: string + value_template: + description: Defines a template to extract a value from the payload. + required: false + type: template + unique_id: + description: Provide a unique id for this sensor. + required: false + type: string +{% endconfiguration %} + ## Information See [supported engines](/integrations/recorder/#custom-database-engines) for which you can connect with this integration. diff --git a/source/_integrations/ssdp.markdown b/source/_integrations/ssdp.markdown index 7130818db77d..6c019bf08968 100644 --- a/source/_integrations/ssdp.markdown +++ b/source/_integrations/ssdp.markdown @@ -47,6 +47,6 @@ The following integrations are automatically discovered by the SSDP integration: - [Sony Songpal](/integrations/songpal/) - [Synology DSM](/integrations/synology_dsm/) - [Ubiquiti UniFi](/integrations/unifi/) - - [Universal Devices ISY994](/integrations/isy994/) + - [Universal Devices ISY/IoX](/integrations/isy994/) - [UPnP](/integrations/upnp/) - [WiLight](/integrations/wilight/) diff --git a/source/_integrations/starlink.markdown b/source/_integrations/starlink.markdown new file mode 100644 index 000000000000..316b096c134d --- /dev/null +++ b/source/_integrations/starlink.markdown @@ -0,0 +1,56 @@ +--- +title: Starlink +description: Instructions on how to integrate Starlink into Home Assistant. +ha_category: + - Sensor + - Binary Sensor + - Button + - Switch + - Network +ha_release: 2023.2 +ha_iot_class: Local Polling +ha_config_flow: true +ha_codeowners: + - '@boswelja' +ha_domain: starlink +ha_platforms: + - sensor + - binary_sensor + - switch + - button +ha_integration_type: integration +--- + +The Starlink integration allows you to integrate your [Starlink](https://www.starlink.com/) into Home Assistant. + +**Important:** Your Starlink must **not** be in bypass mode. In this mode, the local API is unavailable, and this integration will not work. + +{% include integrations/config_flow.md %} + +### Sensor + +- Ping - The ping that Starlink has measured, in ms +- Azimuth - The direction Dishy is facing in degrees +- Elevation - Dishy's current elevation in degrees +- Uplink throughput - The amount of data being uploaded through Starlink in Mbit/s +- Downlink throughput - The amount of data being downloaded through Starlink in Mbit/s +- Last boot time - The time Starlink was last turned on + +### Binary Sensor + +- Obstructed - Whether Dishy is currently obstructed +- Roaming - Whether Starlink is "roaming". Roaming is an optional upgrade that allows you to use your Starlink outside of your home address. It is also known as "portability" +- Heating - Whether Dishy is currently heating. This may be due to cold temperatures, or an attempt to thaw snow and ice +- Idle - Whether Starlink is in an "idle" state to save power +- Mast near vertical - Whether Dishy is mounted straight +- Motors stuck - Whether Dishy is unable to move +- Thermal throttle - Whether Starlink has reduced performance to avoid overheating +- Unexpected location - Whether Starlink has detected operation outside of its designated area + +### Button + +- Reboot - Reboots your Starlink system + +### Switch + +- Stowed - Controls whether Dishy is stowed diff --git a/source/_integrations/stookwijzer.markdown b/source/_integrations/stookwijzer.markdown new file mode 100644 index 000000000000..22a02798f684 --- /dev/null +++ b/source/_integrations/stookwijzer.markdown @@ -0,0 +1,21 @@ +--- +title: Stookwijzer +description: Instructions on how to use Stookwijzer data within Home Assistant +ha_category: + - Sensor + - Environment +ha_release: 2023.2 +ha_iot_class: Cloud Polling +ha_codeowners: + - '@fwestenberg' +ha_domain: stookwijzer +ha_config_flow: true +ha_platforms: + - sensor + - diagnostics +ha_integration_type: service +--- + +The Stookwijzer integration queries the [Stookwijzer](https://www.stookwijzer.nu) API for windspeed and gets the air quality index from [Luchtmeetnet](https://www.luchtmeetnet.nl). Using these parameters, Stookwijzer advises people not to burn pallets or wood, or to use the barbecue. This can prevent health problems for people in the area. + +{% include integrations/config_flow.md %} diff --git a/source/_integrations/switchbot.markdown b/source/_integrations/switchbot.markdown index 8087e3519c1f..3ea76769f549 100644 --- a/source/_integrations/switchbot.markdown +++ b/source/_integrations/switchbot.markdown @@ -61,6 +61,7 @@ Please note, device names configured in the SwitchBot app are not transferred in - Motion Sensor (WoPresence) - Plug Mini (WoPlug), both the original (model W1901400) and HomeKit-enabled (model W1901401) - Lock (WoLock) +- Blind Tilt (WoBlindTilt) ## SwitchBot Entity @@ -107,6 +108,56 @@ Encryption key: For instructions on how to obtain the locks encryption key, see README in [PySwitchbot](https://github.com/Danielhiversen/pySwitchbot#obtaining-locks-encryption-key) project. +## SwitchBot Blind Tilt + +The blind tilt is exposed as a cover entity with control of the tilt position only: + +| Tilt Position | Blind State | +| ------------- | ----------- | +| 100% | Closed Up | +| 50% | Fully Open | +| 0% | Closed Down | + +The close button will close the blinds to the closest closed position (either 0% or 100%), and defaults to closing down if the blinds are fully open. Because Home Assistant believes 100% is open, the default cards will disable the open button when the tilt is at 100%, but the service call will still work and open the blind to 50%. + +### Simple cover template entity + +Some integrations may expose your SwitchBot Blind Tilt to other services which expect that 100% is open and 0% is fully closed. Using a [Cover Template](/integrations/cover.template), a proxy entity can be created which will be open at 100% and closed at 0%. This template entity is limited to closing in one direction. + +{% raw %} + +```yaml +# Example configuration.yaml entry +cover: + - platform: template + covers: + example_blinds_simple: + device_class: blind + friendly_name: Example Blinds (Simple Down) + open_cover: + service: cover.set_cover_tilt_position + data: + tilt_position: 50 + target: + entity_id: cover.example_blinds + close_cover: + service: cover.set_cover_tilt_position + data: + tilt_position: 0 + target: + entity_id: cover.example_blinds + position_template: > + {{ int(states.cover.example_blinds.attributes.current_tilt_position)*2 }} + set_cover_position: + service: cover.set_cover_tilt_position + data: + tilt_position: "{{position/2}}" + target: + entity_id: cover.example_blinds +``` + +{% endraw %} + ## Error codes and troubleshooting The SwitchBot integration will automatically discover devices once the [Bluetooth](/integrations/bluetooth) integration is enabled and functional. diff --git a/source/_integrations/thread.markdown b/source/_integrations/thread.markdown new file mode 100644 index 000000000000..c7c54743b437 --- /dev/null +++ b/source/_integrations/thread.markdown @@ -0,0 +1,16 @@ +--- +title: Thread +ha_category: + - Other +ha_release: 2023.2 +ha_quality_scale: internal +ha_codeowners: + - '@home-assistant/core' +ha_domain: thread +ha_iot_class: Local Polling +ha_platforms: +ha_integration_type: integration +--- + +The Thread integration is currently a placheolder, but will manage Thread network credentials in a future release. +The integration is automatically setup when the "Silicon Labs Multiprotocol" add-on is installed. diff --git a/source/_integrations/tplink.markdown b/source/_integrations/tplink.markdown index decb26c26e25..93c21fd747b4 100644 --- a/source/_integrations/tplink.markdown +++ b/source/_integrations/tplink.markdown @@ -156,6 +156,7 @@ The light strips allow setting a sequence effect. | `segments` | List of segments (0 for all) | | `brightness` | Initial brightness | | `duration` | Duration | +| `repeat_times` | Repetitions (0 for continuous) | | `transition` | Transition | | `spread` | Speed of spread | | `direction` | Direction | diff --git a/source/_integrations/venstar.markdown b/source/_integrations/venstar.markdown index a30e68c6b8a7..28a1935d284f 100644 --- a/source/_integrations/venstar.markdown +++ b/source/_integrations/venstar.markdown @@ -39,6 +39,7 @@ Currently supported functionality: - Remote temperature sensors - Thermostat alerts (Filter replacement/etc) - Reading IAQ and CO2 levels (on supported devices, e.g. T3950, only) +- Reading the current schedule state (morning/day/evening/night/inactive) The following values are supported for the preset_mode state attribute: diff --git a/source/_integrations/whirlpool.markdown b/source/_integrations/whirlpool.markdown index ef781b8a7517..a2b909500501 100644 --- a/source/_integrations/whirlpool.markdown +++ b/source/_integrations/whirlpool.markdown @@ -1,9 +1,10 @@ --- -title: Whirlpool Sixth Sense -description: Instructions on how to integrate Whirlpool 6th Sense Live appliances with Home Assistant. +title: Whirlpool Appliances +description: Instructions on how to integrate Whirlpool appliances with Home Assistant. ha_category: - Climate -ha_release: '2021.10' + - Sensor +ha_release: '2022.10' ha_iot_class: Cloud Push ha_config_flow: true ha_codeowners: @@ -11,24 +12,41 @@ ha_codeowners: ha_domain: whirlpool ha_platforms: - climate + - sensor ha_integration_type: integration --- -The `whirlpool` integration integrates Whirlpool 6th Sense Live appliances into Home Assistant. +The `whirlpool` integration integrates Whirlpool 6th Sense Live, and Whirlpool/Maytag Washer and Dryer appliances into Home Assistant. There is currently support for the following device types within Home Assistant: +- [Supported hardware](#supported-hardware) +- [Sensor](#sensor) - [Climate](#climate) ## Supported hardware The following air conditioners are confirmed to be working, but other models that use the 6th Sense Live application may also work: +Climate: + - SPIW309A2WF/SPIW312A2WF - SPIW409A2WF +Washer: + +- WTW6120HW2 + +Dryer: + +- Not confirmed + {% include integrations/config_flow.md %} +## Sensor + +The `whirlpool` sensor platform integrates Whirlpool Washer and Dryer systems into Home Assistant, allowing views of the machine state, time remaining and the "wash & go" tank fill status as sensors for each device. + ## Climate The `whirlpool` climate platform integrates Whirlpool air conditioning systems into Home Assistant, allowing control of the appliance trough the user interface. The current inside temperature is also displayed on the thermostat card. diff --git a/source/_integrations/zeversolar.markdown b/source/_integrations/zeversolar.markdown new file mode 100644 index 000000000000..b853e562c074 --- /dev/null +++ b/source/_integrations/zeversolar.markdown @@ -0,0 +1,34 @@ +--- +title: Zeversolar +description: Instructions on how to configure the Zeversolar integration within Home Assistant +ha_category: + - Environment +ha_release: 2023.2 +ha_iot_class: Local Polling +ha_domain: zeversolar +ha_platforms: + - sensor +ha_config_flow: true +ha_integration_type: integration +ha_codeowners: + - '@kvanzuijlen' +--- + +The Zeversolar integration uses the local device IP to get information like the current power and +today's total energy production. +This integration allows you to collect and save data providig a historical overview of your Zeversolar +production. + +## Prerequisites + +You need a Zeversolar inverter connected to your solar panels and Wi-Fi. Furthermore, you need to +get the Zeversolar IP address. + +{% include integrations/config_flow.md %} + +## Sensor Types + +When configured, the integration will create two sensors for each configured inverter: + +- Energy today, in `kWh` (Kilowatt-hour) +- Current power, in `W` (Watts) diff --git a/source/_redirects b/source/_redirects index a2e7650ce1b4..bb2f58a3d201 100644 --- a/source/_redirects +++ b/source/_redirects @@ -195,7 +195,6 @@ /integrations/input_slider /integrations/input_number /integrations/leviton /integrations/leviton_z_wave /integrations/light.switch /integrations/switch_as_x -/integrations/openalpr /integrations/openalpr_local /integrations/pca /integrations/elv /integrations/pollen /integrations/iqvia /integrations/polling /integrations/telegram_polling @@ -420,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 @@ -479,6 +479,8 @@ /integrations/nello /more-info/removed-integration 301 /integrations/nma /more-info/removed-integration 301 /integrations/nuimo_controller /more-info/removed-integration 301 +/integrations/openalpr /more-info/removed-integration 301 +/integrations/openalpr_local /more-info/removed-integration 301 /integrations/orangepi_gpio /more-info/removed-integration 301 /integrations/ozw /more-info/removed-integration 301 /integrations/pcal9535a /more-info/removed-integration 301 diff --git a/source/dashboards/header-footer.markdown b/source/dashboards/header-footer.markdown index 20fc36f33f0c..5e25b4241755 100644 --- a/source/dashboards/header-footer.markdown +++ b/source/dashboards/header-footer.markdown @@ -28,6 +28,10 @@ image: required: true description: The URL of an image. type: string +alt_text: + required: false + description: Alternative text for the image. This is necessary for users of assistive technology. The [W3C images tutorial](https://www.w3.org/WAI/tutorials/images/) provides simple guidance for writing alternative text. + type: string tap_action: required: false description: Action taken on card tap. See [action documentation](/dashboards/actions/#tap-action). diff --git a/source/docs/assist/aliases.markdown b/source/docs/assist/aliases.markdown new file mode 100644 index 000000000000..75dcadce3587 --- /dev/null +++ b/source/docs/assist/aliases.markdown @@ -0,0 +1,9 @@ +--- +title: "Assist - Entity Aliases" +--- + +Assist will use the names of your entities, as well as any aliases you've configured. + +![Alias example](/images/blog/2023-01/aliases-cloud-multi-language.png) + +By adding aliases in your native language, you can speak to Home Assistant with the language configured on your [Android watch](/docs/assist/android/) or [Apple device](/docs/assist/apple/). diff --git a/source/docs/assist/android.markdown b/source/docs/assist/android.markdown new file mode 100644 index 000000000000..8b622444eabd --- /dev/null +++ b/source/docs/assist/android.markdown @@ -0,0 +1,28 @@ +--- +title: "Assist on Android." +--- + +Assist is available on WearOS using the [Home Assistant Companion App](https://companion.home-assistant.io/) and "Assist" tile. + + + +## Installation + +After [installing the companion app](https://companion.home-assistant.io/docs/getting_started/) and connecting it to your Home Assistant, visit the Android WatchOS app and click "Add tile" inside the Tiles area. Select the "Assist" tile to add it to your watch: + +![Conversation tile](/images/assist/android_tile.png) + + +## Usage + +Swipe left on your watch until the "Assist" button is visible: + +![Assist button](/images/assist/android_watch_1.png) + +After pressing "Assist", wait for "Speak Now" to be displayed: + +![Assist button](/images/assist/android_watch_2.png) + +Speak your command, then press the "play" icon on the right to send the command to Home Assistant: + +![Assist button](/images/assist/android_watch_3.png) diff --git a/source/docs/assist/apple.markdown b/source/docs/assist/apple.markdown new file mode 100644 index 000000000000..2ee7c69cc5df --- /dev/null +++ b/source/docs/assist/apple.markdown @@ -0,0 +1,69 @@ +--- +title: "Assist on Apple devices" +--- + +_The Assist shortcut will be available in the Mac and iOS beta channel today and will be part of the next release for iOS and Mac._ + +Assist is integrated into Apple devices using the [Shortcuts app](https://support.apple.com/guide/shortcuts/welcome/ios) that is available on all Apple devices. Assist can be used in the following ways on Apple devices: + +- Activated by Siri by saying the shortcut name "Hey Siri, Assist" +- Added to your iPhone home screen +- Pinned to your Mac menu bar +- Activated via a keyboard shortcut on your Mac +- Added as an Apple Watch complication + + + +## Installation + +To get started make sure you're running the latest version of the [Home Assistant Companion app](https://apps.apple.com/us/app/home-assistant/id1099568401?itsct=apps_box_badge&itscg=30200) and have updated your Apple devices. Then download the two shortcuts and open them to import them: + +- [Assist shortcut](https://www.icloud.com/shortcuts/4172210db1d74599bf9ae4f9e1e3d6ed) +- [Assist Button shortcut](https://www.icloud.com/shortcuts/73ebb68ca1a24ae1811b7d6971203334) + +![Expanded Shortcuts Action](/images/assist/ios-expanded-shortcut-action.jpeg) + +There are two versions of the shortcut. The normal shortcut works better with Siri while the Button shortcut has the ability to use speech-to-text when triggered outside of Siri and can customize the input language (instead of relying on the OS language) + +[_Last updated: Jan 26, 2022_](#changelog) + +### Adjusting the language + +Shortcuts triggerd via Siri will always use the same language as Siri is set to. The Assist Button shortcut is meant to be manually triggered and can be configured for any language. + +Open the shortcuts app, and edit the Button Assist shortcut. The text in quotes will be shown in the language of your device. + +- Use the arrow to expand the _"Dictate text"_ action options, and select your language +- Use the arrow to expand the _"Assist with `Provided Input`"_ options, and select your language. + +

    +You can import the button shortcut multiple times to create versions for different languages, when asked if you would like to replace your Shortcut, choose "Keep Both". +

    + +## Multiple servers + +The Assist shortcut works also if you have configured multiple Home Assistant servers. By default it will prompt you to pick the server to sent the command too. This is not very hands-off, and so you can update the shortcut to point at a specific server. You will need to import the shortcuts multiple times, once for each server. + +Open the shortcuts app and edit each Assist shortcut. The text in quotes will be shown in the language of your device. + +- Use the arrow to expand the _"Assist with `Provided Input`"_ action, and select your Home Assistant server. + +## Customizing the Siri experience + +Siri allows activating shortcuts by their name. If you change the name of the "Assist" shortcut, you will also have to refer to it by its new name: "Hey Siri, my new name". Be aware that Siri can get confused and might not work if your shortcut name overlaps with actual Siri commands. + +It is possible to change the text that Siri says when activating the Assist shortcut. Open the shortcuts app and edit each your Assist shortcut. The text in quotes will be shown in the language of your device. + +- Find _"Ask for `Text`"_ and tap on _`How can I assist?`_ and change it to your desired prompt. + +You can also use the share action to [add a Shortcut to your Home Screen](https://support.apple.com/guide/shortcuts/apd735880972/ios) or set an [Accessibility Shortcut](https://support.apple.com/en-gb/HT204390) to run this Shortcut when you triple-click the Side button. + +## Troubleshooting + +The latest version of Siri on the Apple Watch contains an annoying bug where it will not remember that the shortcut is allowed to talk to Home Assistant. This requires the user to tap or say "Allow" for every invocation of the Assist shortcut. The workaround is to remove the Home Assistant application from your watch, which will have the shortcut execute on your phone which does not have this problem. Removing the app prevents you from triggering actions via the Home Assistant interface for Apple Watch. It does not prevent you from adding shortcuts to trigger assist from a complication. + +## Changelog + +### Version 1 - Jan 26, 2022 + +Initial release diff --git a/source/docs/assist/builtin_sentences.markdown b/source/docs/assist/builtin_sentences.markdown new file mode 100644 index 000000000000..41abf4245e7c --- /dev/null +++ b/source/docs/assist/builtin_sentences.markdown @@ -0,0 +1,27 @@ +--- +title: "Assist - Default Sentences" +--- + +Home Assistant comes with built-in sentences [contributed by the community](https://github.com/home-assistant/intents/) for [dozens of languages](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages). +These sentences allow you to: + +* **Turn entities on and off** + * *"turn on the living room light"* + * *"turn off ceiling fan"* +* **Open and close covers** + * *"Close the garage door"* + * *"Open kitchen window"* +* **Set the brightness and color of lights** + * *"Change kitchen lights brightness to 50%"* + * *"Set bed light to green"* + +In addition to individual entities, commands can target **areas**: + +* *"turn on all lights in the living room"* +* *"open windows in the kitchen"* +* *"change kitchen brightness to 50%"* +* *"set bedroom lights to green"* + +Entity [aliases](/docs/assist/aliases) are also matched so multiple names can be used, even in different languages. + +You can extend the built-in sentences or [add your own](/docs/assist/custom_sentences) to trigger any action in Home Assistant. diff --git a/source/docs/assist/custom_sentences.markdown b/source/docs/assist/custom_sentences.markdown new file mode 100644 index 000000000000..5c2e5112a921 --- /dev/null +++ b/source/docs/assist/custom_sentences.markdown @@ -0,0 +1,120 @@ +--- +title: "Assist - Custom Sentences" +--- + +You may add your own sentences to the intent recognizer by either extending an [existing intent](https://developers.home-assistant.io/docs/intent_builtin/) or creating a new one. You may also [customize responses](#customizing-responses) for existing intents. + +## In configuration.yaml + +Intents and sentences may be added in the [`conversation`](/integrations/conversation/) config in your `configuration.yaml` file: + +{% raw %} + +```yaml +# Example configuration.yaml +conversation: + intents: + HassTurnOn: + - "activate [the] {name}" +``` + +```yaml +# Example configuration.yaml +conversation: + intents: + HassTurnOn: + - "activate [the] {name}" +``` + +{% endraw %} + +This extends the default English sentences for the `HassTurnOn` intent, allowing you to say "activate the kitchen lights" as well as "turn on the kitchen lights". + +New intents can also be added, with their responses and actions defined using the [`intent_script`](/integrations/intent_script/) integration: + +{% raw %} + +```yaml +# Example configuration.yaml +conversation: + intents: + YearOfVoice: + - "how is the year of voice going" + +intent_script: + YearOfVoice: + speech: + text: "Great! We're at over 40 languages and counting." +``` + +{% endraw %} + +Besides a text response, `intent_script` can trigger any `action` available in Home Assistant, such as calling a service or firing an event. + +## In config directory + +More advanced customization can be done in Home Assistant's `config` directory. YAML files in `config/custom_sentences/en`, for example, will be loaded when English sentences (language code `en`) are requested. + +The following example creates a new `SetVolume` intent that changes the volume on one of two media players: + +{% raw %} + +```yaml +# Example config/custom_sentences/en/media.yaml +language: "en" +intents: + SetVolume: + data: + - sentences: + - "(set|change) {media_player} volume to {volume} [percent]" + - "(set|change) [the] volume for {media_player} to {volume} [percent]" +lists: + media_player: + values: + - in: "living room" + out: "media_player.living_room" + - in: "bedroom" + out: "media_player.bedroom" + volume: + range: + from: 0 + to: 100 +``` + +{% endraw %} + +As mentioned above, you can then use the `intent_script` integration to implement an action and provide a response for `SetVolume`: + +{% raw %} + +```yaml +# Example configuration.yaml +intent_script: + SetVolume: + action: + service: "media_player.volume_set" + data: + entity_id: "{{ media_player }}" + volume_level: "{{ volume / 100.0 }}" + speech: + text: "Volume changed to {{ volume }}" +``` + +{% endraw %} + +## Customizing Responses + +Responses for existing intents can be customized as well in `config/custom_sentences/`: + +{% raw %} + +```yaml +# Example config/custom_sentences/en/responses.yaml +language: "en" +responses: + intents: + HassTurnOn: + default: "I have turned on the {{ slots.name }}" +``` + +{% endraw %} diff --git a/source/docs/assist/index.markdown b/source/docs/assist/index.markdown new file mode 100644 index 000000000000..bfde547ee8c0 --- /dev/null +++ b/source/docs/assist/index.markdown @@ -0,0 +1,21 @@ +--- +title: Assist - Talking to Home Assistant +--- + +Assist logo + +Assist is our feature to allow you to control Home Assistant using natural language. It is built on top of an open voice foundation and powered by knowledge provided by our community. You can use the [built-in sentences](/docs/assist/builtin_sentences) to control entities and areas, or [create your own](/docs/assist/custom_sentences). + +[List of supported languages.](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages) + +Assist is available to use on most platforms that can interface with Home Assistant. Look for the Assist icon Assist icon: + +- Inside the Home Assistant app in the top-right corner +- On Android Watch using [Assist tile](/docs/assist/android) +- On Apple devices via [Siri and Assist shortcuts](/docs/assist/apple) + +Did Assist not understand your sentence? [Contribute them.](https://developers.home-assistant.io/docs/voice/intent-recognition/) + +_Assist was introduced in Home Assistant 2023.2._ + + diff --git a/source/images/assist/android_tile.png b/source/images/assist/android_tile.png new file mode 100644 index 000000000000..bcfced7ad913 Binary files /dev/null and b/source/images/assist/android_tile.png differ diff --git a/source/images/assist/android_watch.png b/source/images/assist/android_watch.png new file mode 100644 index 000000000000..ae93b94b8e21 Binary files /dev/null and b/source/images/assist/android_watch.png differ diff --git a/source/images/assist/android_watch_1.png b/source/images/assist/android_watch_1.png new file mode 100644 index 000000000000..9c921883a266 Binary files /dev/null and b/source/images/assist/android_watch_1.png differ diff --git a/source/images/assist/android_watch_2.png b/source/images/assist/android_watch_2.png new file mode 100644 index 000000000000..769bcc4c3622 Binary files /dev/null and b/source/images/assist/android_watch_2.png differ diff --git a/source/images/assist/android_watch_3.png b/source/images/assist/android_watch_3.png new file mode 100644 index 000000000000..7614b7ca75bc Binary files /dev/null and b/source/images/assist/android_watch_3.png differ diff --git a/source/images/assist/assist-logo.png b/source/images/assist/assist-logo.png new file mode 100644 index 000000000000..b9717beb3355 Binary files /dev/null and b/source/images/assist/assist-logo.png differ diff --git a/source/images/assist/ios-expanded-shortcut-action.jpeg b/source/images/assist/ios-expanded-shortcut-action.jpeg new file mode 100644 index 000000000000..be98e8b1ff37 Binary files /dev/null and b/source/images/assist/ios-expanded-shortcut-action.jpeg differ diff --git a/source/images/integrations/google_assistant_sdk/conversation.png b/source/images/integrations/google_assistant_sdk/conversation.png new file mode 100644 index 000000000000..ee696e0533f2 Binary files /dev/null and b/source/images/integrations/google_assistant_sdk/conversation.png differ diff --git a/source/images/screenshots/voice-commands.png b/source/images/screenshots/voice-commands.png index 39a98deef7ed..cfed4415f2d1 100644 Binary files a/source/images/screenshots/voice-commands.png and b/source/images/screenshots/voice-commands.png differ