diff --git a/CODEOWNERS b/CODEOWNERS index c0c6c5e75ed1..23e63a7f9d11 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -451,6 +451,7 @@ source/_integrations/ld2410_ble.markdown @930913 source/_integrations/leaone.markdown @bdraco source/_integrations/led_ble.markdown @bdraco source/_integrations/legrand.markdown @cgtobi +source/_integrations/lektrico.markdown @lektrico source/_integrations/leviton_z_wave.markdown @home-assistant/z-wave source/_integrations/lg_netcast.markdown @Drafteed @splinter98 source/_integrations/lidarr.markdown @tkdrob diff --git a/source/_docs/asterisk_mbox.markdown b/source/_docs/asterisk_mbox.markdown deleted file mode 100644 index e91f229f9611..000000000000 --- a/source/_docs/asterisk_mbox.markdown +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Asterisk Voicemail server installation" -description: "Instructions on how to integrate your existing Asterisk voicemail within Home Assistant." ---- - -Asterisk Voicemail integration allows Home Assistant to view, listen to and delete voicemails from a Asterisk voicemail mailbox. - -There are two components to the integration: - -- A server that runs on the Asterisk PBX host and communicates over an open port. -- A client which can request information from the server. - -Both parts are necessary for Asterisk voicemail integration. - -The server installation is documented below. The client is [integrated inside Home Assistant](/integrations/asterisk_mbox) - -{% note %} -Currently this module can only monitor a single Asterisk PBX mailbox. -{% endnote %} - -### Prerequisites - -Before beginning make sure that you have the following: - -- A functional Asterisk PBX setup which is using the default `voicemail` application. -- Both Home Assistant and Asterisk PBX running on the same LAN (or the same server). -- The Asterisk PBX server has Python 3.5 or newer installed. -- Administrator access on the Asterisk PBX (for Python module installation). -- Account access to the `asterisk` user that runs the Asterisk PBX software. - -### Installation - -1. Apply for a Google API key to enable speech-transcription services - -2. Install the `asterisk_mbox_server` Python module: - - ```bash - pip3 install asterisk_mbox_server - ``` - -3. Create a configuration file for the server - - As the `asterisk` user create an `asterisk_mbox.ini` file. You can place this in any directory you choose, but the recommended location is `/etc/asterisk/asterisk_mbox.ini`. - - ```ini - [default] - host = IP_ADDRESS - port = PORT - password = PASSWORD - mbox_path = PATH_TO_VOICEMAIL_FILES - cache_file = PATH_TO_CACHE_FILE - google_key = GOOGLE_API_KEY - cdr = mysql+pymysql://:@localhost/asterisk/cdr - - ``` - - - `host` (*Optional*): The IP address to listen on for client requests. This defaults to all IP addresses on the server. To listen only locally, choose `127.0.0.1` - - `port` (*Optional*): The port to listen on for client requests. Defaults to 12345. - - `password` (*Required*): A password shared between client and server. Use only alphanumeric characters and spaces - - `mbox_path` (*Required*): The path to the storage location of mailbox files. This is typically `/var/spool/asterisk/voicemail/default//` - - `cache_file` (*Required*): A fully-qualified path to a file that can be written by the server containing transcriptions of voicemails. Example: `/var/spool/asterisk/transcription.cache` - - `google_key` (*Required*): Your 40 characters Google API key. - - `cdr` (*Optional*): Where to find CDR data. Supports various SQL databases as well as a file log. Configuring the CDR will enable the `asterisk_cdr` platform. - - Once complete, ensure this file is only accessible by the Asterisk user: - - ```bash - sudo chown asterisk:asterisk /etc/asterisk/asterisk_mbox.ini - sudo chmod 600 /etc/asterisk/asterisk_mbox.ini - ``` - -4. Interactively start the server to verify it is functioning - - ```bash - sudo -u asterisk asterisk_mbox_server -v --cfg /etc/asterisk/asterisk_mbox.ini - ``` - - Now complete the [Home Assistant configuration](/integrations/asterisk_mbox) and verify that Home Assistant can communicate with the server - - You can use `Ctrl-c` to terminate the server when done testing - -5. Configure the server to start automatically - - Copy the following code into `/etc/systemd/system/asterisk_mbox.service`: - ```ini - [Unit] - Description=Asterisk PBX voicemail server for Home Assistant - Wants=network.target - After=network.target - - [Service] - Type=simple - User=asterisk - Group=asterisk - ExecStart=/usr/local/bin/asterisk-mbox-server --cfg /etc/asterisk/asterisk_mbox.ini - Restart=on-failure - - [Install] - WantedBy=multi-user.target - ``` - -{% note %} -This assumes that your Asterisk PBX server is using `systemd` for init handling. If not, you will need to create the appropriate configuration files yourself. -{% endnote %} diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index 44145e990fd8..212787188039 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -31,6 +31,8 @@ An {% term automation %} can be triggered by an {% term event %}, a certain {% t - [Sentence trigger](#sentence-trigger) - [Multiple triggers](#multiple-triggers) - [Multiple Entity IDs for the same Trigger](#multiple-entity-ids-for-the-same-trigger) +- [Disabling a trigger](#disabling-a-trigger) +- [Merging lists of triggers](#merging-lists-of-triggers) ## Trigger ID @@ -1070,3 +1072,28 @@ blueprint: ``` {% endraw %} + +## Merging lists of triggers + +{% caution %} +This feature requires Home Assistant version 2024.10 or later. If using this in a blueprint, set the `min_version` for the blueprint to at least this version. +{% endcaution %} + +In some advanced cases (like for blueprints with trigger selectors), it may be necessary to insert a second list of triggers into the main trigger list. This can be done by adding a dictionary in the main trigger list with the sole key `triggers`, and the value for that key contains a second list of triggers. These will then be flattened into a single list of triggers. For example: + +```yaml +blueprint: + name: Nested Trigger Blueprint + domain: automation + input: + usertrigger: + selector: + trigger: + +trigger: + - platform: event + event_type: manual_event + - triggers: !input usertrigger +``` + +This blueprint automation can then be triggered either by the fixed manual_event trigger, or additionally by any triggers selected in the trigger selector. This is also applicable for `wait_for_trigger` action. diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index bfa929f53f29..a172e72a946a 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -1091,6 +1091,38 @@ While Jinja natively supports the conversion of an iterable to a `list`, it does Note that, in Home Assistant, to convert a value to a `list`, a `string`, an `int`, or a `float`, Jinja has built-in functions with names that correspond to each type. +### Iterating multiple objects + +The `zip()` function can be used to iterate over multiple collections in one operation. + +{% raw %} + +```text +{% set names = ['Living Room', 'Dining Room'] %} +{% set entities = ['sensor.living_room_temperature', 'sensor.dining_room_temperature'] %} +{% for name, entity in zip(names, entities) %} + The {{ name }} temperature is {{ states(entity) }} +{% endfor %} +``` + +{% endraw %} + +`zip()` can also unzip lists. + +{% raw %} + +```text +{% set information = [ + ('Living Room', 'sensor.living_room_temperature'), + ('Dining Room', 'sensor.dining_room_temperature') +] %} +{% set names, entities = zip(*information) %} +The names are {{ names | join(', ') }} +The entities are {{ entities | join(', ') }} +``` + +{% endraw %} + ### Functions and filters to process raw data These functions are used to process raw value's in a `bytes` format to values in a native Python type or vice-versa. @@ -1148,6 +1180,178 @@ See: [Python regular expression operations](https://docs.python.org/3/library/re - Filter `value | regex_findall(find='', ignorecase=False)` will find all regex matches of the find expression in `value` and return the array of matches. - Filter `value | regex_findall_index(find='', index=0, ignorecase=False)` will do the same as `regex_findall` and return the match at index. +## Merge action responses + +Using action responses we can collect information from various entities at the same time. +Using the `merge_response` template we can merge several responses into one list. + +| Variable | Description | +| -------------- | ---------------------------------- | +| `value` | The incoming value (must be an action response). | + +The `entity_id` key is appended to each dictionary within the template output list as a reference of origin. If the input dictionary already contains an `entity_id` key, the template will fail. + +The `value_key` key is appended to each dictionary within the template output list as a reference of origin if the original service call was providing a list of dictionaries, for example, `calendar.get_events` or `weather.get_forecasts`. + +Examples of these two keys can be seen in [example merge calendar action response](#example-merge-calendar-action-response) template output. + + +### Example + +```yaml +{% raw %} + +{% set combined_forecast = merge_response(response) %} +{{ combined_forecast[0].precipitation | float(0) | round(1) }} + +{% endraw %} +``` + +### Example how to sort + +Sorting the dictionaries within the list based on a specific key can be done directly by using Jinja's `sort` filter. + +```yaml +{% raw %} + +{{ merge_response(calendar_response) | sort(attribute='start') | ... }} + +{% endraw %} +``` + +### Example merge calendar action response + +```json +{ + "calendar.sports": { + "events": [ + { + "start": "2024-02-27T17:00:00-06:00", + "end": "2024-02-27T18:00:00-06:00", + "summary": "Basketball vs. Rockets", + "description": "", + } + ] + }, + "calendar.local_furry_events": {"events": []}, + "calendar.yap_house_schedules": { + "events": [ + { + "start": "2024-02-26T08:00:00-06:00", + "end": "2024-02-26T09:00:00-06:00", + "summary": "Dr. Appt", + "description": "", + }, + { + "start": "2024-02-28T20:00:00-06:00", + "end": "2024-02-28T21:00:00-06:00", + "summary": "Bake a cake", + "description": "something good", + } + ] + }, +} +``` + +```yaml +{% raw %} +{{ merge_response(response_variable) }} +{% endraw %} +``` + +```json +[ + { + "description": "", + "end": "2024-02-27T18:00:00-06:00", + "entity_id": "calendar.sports", + "start": "2024-02-27T17:00:00-06:00", + "summary": "Basketball vs. Rockets", + "value_key": "events" + }, + { + "description": "", + "end": "2024-02-26T09:00:00-06:00", + "entity_id": "calendar.yap_house_schedules", + "start": "2024-02-26T08:00:00-06:00", + "summary": "Dr. Appt", + "value_key": "events" + }, + { + "description": "something good", + "end": "2024-02-28T21:00:00-06:00", + "entity_id": "calendar.yap_house_schedules", + "start": "2024-02-28T20:00:00-06:00", + "summary": "Bake a cake", + "value_key": "events" + } +] +``` + +### Example non-list action responses + +```json +{ + "vacuum.deebot_n8_plus_1": { + "header": { + "ver": "0.0.1", + }, + "payloadType": "j", + "resp": { + "body": { + "msg": "ok", + }, + }, + }, + "vacuum.deebot_n8_plus_2": { + "header": { + "ver": "0.0.1", + }, + "payloadType": "j", + "resp": { + "body": { + "msg": "ok", + }, + }, + }, +} +``` + +```yaml +{% raw %} +{{ merge_response(response_variable) }} +{% endraw %} +``` + +```json +[ + { + "entity_id": "vacuum.deebot_n8_plus_1", + "header": { + "ver": "0.0.1", + }, + "payloadType": "j", + "resp": { + "body": { + "msg": "ok", + }, + }, + }, + { + "entity_id": "vacuum.deebot_n8_plus_2", + "header": { + "ver": "0.0.1", + }, + "payloadType": "j", + "resp": { + "body": { + "msg": "ok", + }, + }, + }, +] +``` + ## Processing incoming data The other part of templating is processing incoming data. It allows you to modify incoming data and extract only the data you care about. This will only work for platforms and integrations that mention support for this in their documentation. @@ -1284,7 +1488,7 @@ For actions, command templates are defined to format the outgoing MQTT payload t {% note %} -Example command template: +**Example command template with JSON data:** With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endraw %} renders to: @@ -1298,6 +1502,14 @@ Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used {% endnote %} +**Example command template with raw data:** + +When a command template renders to a valid `bytes` literal, then MQTT will publish this data as raw data. In other cases, a string representation will be published. So: + +- Template {% raw %}`{{ "16" }}`{% endraw %} renders to payload encoded string `"16"`. +- Template {% raw %}`{{ 16 }}`{% endraw %} renders to payload encoded string `"16"`. +- Template {% raw %}`{{ pack(0x10, ">B") }}`{% endraw %} renders to a raw 1 byte payload `0x10`. + ## Some more things to keep in mind ### `entity_id` that begins with a number diff --git a/source/_integrations/airgradient.markdown b/source/_integrations/airgradient.markdown index e843a783f00d..cfc40711a6b2 100644 --- a/source/_integrations/airgradient.markdown +++ b/source/_integrations/airgradient.markdown @@ -17,6 +17,7 @@ ha_platforms: - select - sensor - switch + - update ha_integration_type: device ha_zeroconf: true --- diff --git a/source/_integrations/amazon_polly.markdown b/source/_integrations/amazon_polly.markdown index b0c8284c4d6d..9e552cb010ed 100644 --- a/source/_integrations/amazon_polly.markdown +++ b/source/_integrations/amazon_polly.markdown @@ -54,7 +54,7 @@ profile_name: region_name: description: The region identifier to connect to. required: false - type: [string, list] + type: string default: us-east-1 text_type: description: "Whether to interpret messages as `text` or as [`ssml`](https://docs.aws.amazon.com/polly/latest/dg/ssml.html) by default." @@ -76,7 +76,7 @@ sample_rate: type: string default: 22050 for MP3 and Ogg Vorbis, 16000 for pcm engine: - description: "Override the default engine. Can be either of `standard` or `neural`. See Amazon documentation for compatible regions and voices." + description: "Override the default engine. Can be either of [`standard`](https://docs.aws.amazon.com/polly/latest/dg/standard-voices.html), [`neural`](https://docs.aws.amazon.com/polly/latest/dg/neural-voices.html), [`long-form`](https://docs.aws.amazon.com/polly/latest/dg/long-form-voices.html) or [`generative`](https://docs.aws.amazon.com/polly/latest/dg/generative-voices.html). See Amazon documentation for compatible regions and voices." required: false type: string default: standard @@ -127,6 +127,21 @@ Say with break: Amazon Polly ``` + +Say with specific voice and engine as options: + +```yaml +- service: tts.amazon_polly_say + data: + message: "Hello from Amazon Polly" + entity_id: media_player.living_room + language: en-GB + options: + voice: Amy + engine: generative +``` + + ## Advanced usage Amazon Polly supports accented bilingual voices and you may find that you'd prefer the voice you like be slowed down, or speeded up. If the speed of the voice is a concern, Amazon Polly provides the ability to modify this using SSML tags. First enable SSML in configuration: diff --git a/source/_integrations/amcrest.markdown b/source/_integrations/amcrest.markdown index c886a1df0652..3a729edae661 100644 --- a/source/_integrations/amcrest.markdown +++ b/source/_integrations/amcrest.markdown @@ -292,7 +292,7 @@ elements: bottom: 50px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: up @@ -304,7 +304,7 @@ elements: bottom: 0px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: down @@ -316,7 +316,7 @@ elements: bottom: 25px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: left @@ -328,7 +328,7 @@ elements: bottom: 25px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: right @@ -340,7 +340,7 @@ elements: bottom: 50px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: left_up @@ -352,7 +352,7 @@ elements: bottom: 50px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: right_up @@ -364,7 +364,7 @@ elements: bottom: 0px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: left_down @@ -376,7 +376,7 @@ elements: bottom: 0px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: right_down @@ -388,13 +388,13 @@ elements: right: 25px tap_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control service_data: entity_id: camera.lakehouse movement: zoom_in hold_action: action: call-service - action: amcrest.ptz_control + service: amcrest.ptz_control data: entity_id: camera.lakehouse movement: zoom_out diff --git a/source/_integrations/apsystems.markdown b/source/_integrations/apsystems.markdown index 9aeee5b468ed..8c155974c8fd 100644 --- a/source/_integrations/apsystems.markdown +++ b/source/_integrations/apsystems.markdown @@ -18,20 +18,42 @@ ha_codeowners: - '@SonnenladenGmbH' --- -The **APsystems** {% term integration %} allows you to read the data from your [APsystems EZ1](https://emea.apsystems.com/diy/ez1/) microinverter. It also allows you to set the output limit to any number between 30 and 800 watts. -The following data is provided by the integration: +The **APsystems** {% term integration %} allows you to read the data from your [APsystems EZ1](https://emea.apsystems.com/diy/ez1/) microinverter. It also allows you to set the output limit to anything above 30 watts. + +## Sensors + +### Numerical sensors + +| Sensor ID | Unit | Description +|---|---| ---| +| total_power | W | Total current output of the inverter +| lifetime_production_p1 | kWh | Lifetime production of first input +| lifetime_production_p2 | kWh | Lifetime production of second input +| lifetime_production | kWh | Lifetime production of both inputs combined +| total_power_p1 | W | Current input on first input +| total_power_p2 | W | Current input on second input +| today_production | kWh | Today's production of both inputs combined +| today_production_p1 | kWh | Today's production of first input +| today_production_p2 | kWh | Today's production of second input + +### Binary sensors + +| Sensor ID | Description +|---|---| +| off_grid_status | On when the inverter is not connected to the power grid +| dc_1_short_circuit_error_status | Short circuit detected on first input +| dc_2_short_circuit_error_status | Short circuit detected on second input +| output_fault_status | Output because of any error deactivated + +## Settings + +| Setting ID | Type | Description +|---|---|---| +| inverter_status | switch | Enables or disables the inverter's output +| output_limit | number | Sets the max output of the inverter -- Lifetime production (Per input and in total) -- Current production (Per input and in total) -- Today's production (Per input and in total) -- Short circuit error status (per input) -- Off grid status -- Output status -The following data can be set by the integration: -- Maximal output in watts -- Inverter status (on or off) ## Prerequisites diff --git a/source/_integrations/aquacell.markdown b/source/_integrations/aquacell.markdown index edd0ea9f44ea..1f884148aaa2 100644 --- a/source/_integrations/aquacell.markdown +++ b/source/_integrations/aquacell.markdown @@ -1,5 +1,5 @@ --- -title: Aquacell +title: AquaCell description: Instructions on how to integrate AquaCell with Home Assistant. ha_category: - Sensor @@ -17,10 +17,12 @@ ha_integration_type: device AquaCell is a water-softening device. The **AquaCell** {% term integration %} allows you to monitor your AquaCell device in Home Assistant. You will need your Aquacell account information as used in the **AquaCell** app. +This integration also supports **Harvey** softeners. + {% include integrations/config_flow.md %}
-This integration only works with AquaCell devices which have an i-Lid and are configured through the 'Mijn AquaCell' mobile app. +This integration only works with AquaCell or Harvey devices which have an i-Lid and are configured through the 'Mijn AquaCell' or 'My Harvey' mobile app.
## Sensors diff --git a/source/_integrations/aranet.markdown b/source/_integrations/aranet.markdown index 92001ff7a37f..67397f2502af 100644 --- a/source/_integrations/aranet.markdown +++ b/source/_integrations/aranet.markdown @@ -27,5 +27,7 @@ The Aranet integration will automatically discover devices once the [Bluetooth]( - [Aranet2](https://aranet.com/products/aranet2/) - [Aranet4](https://aranet.com/products/aranet4/) +- [Aranet Radiation](https://aranet.com/products/aranet-radiation-sensor/) +- [Aranet Radon Plus](https://aranet.com/products/aranet-radon-sensor) The Aranet integration requires that your Aranet device is updated to at least firmware version 1.2.0 and has the "Smart Home integration" feature enabled. Both of these can be done within the settings portion of the Aranet Home mobile application on both Android and iOS. diff --git a/source/_integrations/artsound.markdown b/source/_integrations/artsound.markdown new file mode 100644 index 000000000000..05311b87fac7 --- /dev/null +++ b/source/_integrations/artsound.markdown @@ -0,0 +1,17 @@ +--- +title: ArtSound +description: Connect and control your ArtSound media players using the LinkPlay integration +ha_release: 2024.9 +ha_category: + - Media player +ha_domain: artsound +ha_integration_type: virtual +works_with: + - linkplay +--- + +The **ArtSound** {% term integration %} allows users to control their ArtSound media players through the **LinkPlay** {% term integration %}. + +[Learn more about LinkPlay in Home Assistant.](/integrations/linkplay/) + +{% include integrations/supported_brand.md %} diff --git a/source/_integrations/asuswrt.markdown b/source/_integrations/asuswrt.markdown index 881b7cfc4911..ec46bc5dfb19 100644 --- a/source/_integrations/asuswrt.markdown +++ b/source/_integrations/asuswrt.markdown @@ -42,9 +42,18 @@ These sensors are automatically created and associated to the router device: - Upload sensor (unit_of_measurement: Gigabyte - *Daily accumulation*) - Upload Speed sensor (unit_of_measurement: Mbit/s) - Load average sensors (1min, 5min, 15min) -- Temperature sensors (2ghz, 5ghz, cpu). NB: only temperature sensors available on your router will be created +- Temperature sensors (2 GHz, 5 GHz, 6 GHz, CPU). Only temperature sensors available on your router will be created. -Only `Connected devices sensor` is created in status **enabled**, all other sensors are created in status **disabled**. To use them, simply **enable** on the devices page. +If the integration is configured to use the http(s) protocol, also the following sensors will be available: + +- CPU usage sensors (percentage for total and single core) +- Memory usage sensor (percentage) +- Free memory sensor (Megabyte) +- Memory used sensor (Megabyte) +- Last boot sensor (Timestamp) +- Uptime sensor (HH:MM:SS) + +Only `Connected devices sensor` and `Last boot sensor` are created in status **enabled**, all other sensors are created in status **disabled**. To use them, simply **enable** on the devices page. {% include integrations/option_flow.md %} {% configuration_basic %} diff --git a/source/_integrations/august.markdown b/source/_integrations/august.markdown index fec9f55ebaf5..68e33ed0f1cc 100644 --- a/source/_integrations/august.markdown +++ b/source/_integrations/august.markdown @@ -29,6 +29,8 @@ ha_integration_type: integration The `august` integration allows you to integrate your [August](https://august.com/) and some Yale Access devices in Home Assistant. +For devices that use the [Yale Home](https://yalehome.com/global) app, the [Yale](/integrations/yale) integration should be used instead. + {% include integrations/config_flow.md %} ## Known working devices @@ -43,10 +45,6 @@ The `august` integration allows you to integrate your [August](https://august.co | August View | no | | Yale Assure Lock | yes | | Yale Assure Lock 2 | yes | -| Yale Conexis L1 | yes | -| Yale Conexis L2 | yes | -| Yale Doorman L3 | yes | -| Yale Linus | yes | | Yale Smart Safe | yes | Other devices not listed above have not been tested and may not function as expected. @@ -124,9 +122,7 @@ If you have an August Keypad, once you have enabled the August integration, you ## Integration with Yale Access Bluetooth -Following Assa Abloy, Yale's parent company, purchasing August in 2017, most newer devices use the Yale Access branding. - -The [Yale Access Bluetooth](/integrations/yalexs_ble) integration provides local control over Bluetooth of many Yale Access locks and some August locks that use the same system. +The [Yale Access Bluetooth](/integrations/yalexs_ble) integration provides local control over Bluetooth of many Yale Access locks and some August locks that use the same system. For locks that support the Yale Access system, the August integration can keep your offline access keys up to date to ensure you can operate your lock over Bluetooth. The following requirements must be met for the offline key updates to work: diff --git a/source/_integrations/azure_devops.markdown b/source/_integrations/azure_devops.markdown index 39013b176e7b..114004d3be24 100644 --- a/source/_integrations/azure_devops.markdown +++ b/source/_integrations/azure_devops.markdown @@ -33,4 +33,5 @@ This integration provides a sensor for Azure DevOps: - Latest build queue time - How long the latest build was queued. - Latest build start time - The time when the latest build actually started. - Latest build finish time - The time when the latest build finished. -- Latest build URL - The URL to the latest build. +- Latest build URL - The URL to the latest build. +- Work item count - The number of work items for each work item type and state in the project. diff --git a/source/_integrations/cambridge_audio.markdown b/source/_integrations/cambridge_audio.markdown new file mode 100644 index 000000000000..fb54e2a5a9e0 --- /dev/null +++ b/source/_integrations/cambridge_audio.markdown @@ -0,0 +1,64 @@ +--- +title: Cambridge Audio +description: Instructions on how to integrate Cambridge Audio Receivers into Home Assistant. +ha_category: + - Media player +ha_release: '2024.10' +ha_iot_class: Local Push +ha_domain: cambridge_audio +ha_platforms: + - media_player +ha_codeowners: + - '@noahhusby' +ha_config_flow: true +ha_integration_type: integration +--- + +The **Cambridge Audio** {% term integration %} allows you to control all receivers and streamers that support the StreamMagic app. + +The integration automatically discovers all enabled zones and sources. Each zone is added as a media player device with the enabled sources available as inputs. Media information and controls (such as play, pause, skip) are supported if the selected source reports it. + +## Supported devices + +This integration allows you to connect the following devices: + +- Cambridge Audio Evo 75 +- Cambridge Audio Evo 150 +- Cambridge Audio CXN +- Cambridge Audio CXN (v2) +- Cambridge Audio CXR120 +- Cambridge Audio CXR200 +- Cambridge Audio 851N +- Cambridge Audio Edge NQ + +Older, RS-232 serial-based amplifiers like the [CXA series](https://www.cambridgeaudio.com/usa/en/products/hi-fi/cx-series-2/cxa81) +use a different protocol and are not currently supported. + +{% include integrations/config_flow.md %} + +{% configuration_basic %} +Host: + description: The IP address of your device can be found by navigating to the device on the [StreamMagic app](https://www.cambridgeaudio.com/usa/en/products/streammagic) and selecting `Settings` → `IP address`. + required: true + type: string +{% endconfiguration_basic %} + +## Troubleshooting + +### The buttons to skip, shuffle, and repeat the track are missing + +Control functionality depends on the source / service that is currently selected. +The interface automatically sets which controls are available depending on which source is selected. + +### The ability to change volume is missing + +Volume control is only supported on all-in-one amps, or streamers with pre-amp mode. +Likely, the device is not configured to be in pre-amp mode. +This can be changed by navigating to the IP address of the device in a web browser, +or selecting settings in the StreamMagic app and setting **Pre-Amp** to **On**. + +### Turning on the device doesn't work from Home Assistant + +Cambridge Audio devices come with ECO mode enabled by default, which disables the network interface when +the device is powered down. This can be changed by navigating to the IP address of the device in a web browser, +or selecting settings in the StreamMagic app and setting **Standby Mode** to **Network standby**. diff --git a/source/_integrations/chacon_dio.markdown b/source/_integrations/chacon_dio.markdown index 06df560d3d94..0bbcbc645afe 100644 --- a/source/_integrations/chacon_dio.markdown +++ b/source/_integrations/chacon_dio.markdown @@ -3,6 +3,7 @@ title: Chacon Dio description: Instructions on how to integrate your Chacon Dio devices within Home Assistant. ha_category: - Cover + - Switch ha_release: 2024.8 ha_iot_class: Cloud Push ha_config_flow: true @@ -11,15 +12,17 @@ ha_codeowners: ha_domain: chacon_dio ha_platforms: - cover + - switch ha_integration_type: integration --- [Chacon Dio devices](https://chacon.com/en/) are connected home devices that can be controlled via RF 433 MHz or Wi-Fi. This {% term integrations %} gives you access to the Wi-Fi connection so that Home Assistant can list your Chacon Dio devices and interact with them in real time, the same way the vendor's smartphone application does. -There is currently support for the following information within Home Assistant: +There is currently support for the following device types within Home Assistant: -- Cover devices (get statuses, move up, down, stop, and move to a given percentage) +- [Cover](#cover) +- [Switch](#switch) ## Prerequisites @@ -30,6 +33,25 @@ You will need to use the standalone app for this device to register a username a {% include integrations/config_flow.md %} +## Cover + +The cover platform integrates Chacon Dio devices to manage covers (like the REV-SHUTTER model) into Home Assistant, enabling control of the following: + +- get the **state** of the cover (connected or not, position and current movement) +- **Open/close/stop** the cover +- **Set position** of the cover (0-100%) + +## Switch + +The switch platform integrates Chacon Dio devices to manage switches (like the REV-SWITCH model) into Home Assistant, enabling control of the following: + +- get the **state** of the switch (connected or not and on/off state) +- **Turn on/off** the switch + +## Actions + +In rare cases, such as Wi-Fi interruptions, you may need to manually update the state of your devices. You can use the `homeassistant.update_entity` action to refresh the device state manually. + ## Tips You can use the [group integration](/integrations/group) to group entities as the application proposes (for example covers of the first floor). diff --git a/source/_integrations/coinbase.markdown b/source/_integrations/coinbase.markdown index 0f98291d6c14..e6fad373c009 100644 --- a/source/_integrations/coinbase.markdown +++ b/source/_integrations/coinbase.markdown @@ -18,7 +18,7 @@ ha_integration_type: integration The `coinbase` integration lets you access account balances and exchange rates from [Coinbase](https://coinbase.com). -You will need to obtain an API key from the API section in Coinbase's [User Settings](https://www.coinbase.com/settings/api) to use this integration. You need to select the account wallet or wallets (e.g. "BTC Wallet") that you wish to show in Home Assistant and give read access to `wallet:accounts` in order for the integration to access relevant data. It is worth noting that once you close the New API Key popup on Coinbase you will not be able to see the API Secret again. +You will need to obtain an API key from the API section in Coinbase's [User Settings](https://www.coinbase.com/settings/api) to use this integration. Your API key and secret should be of the form `organizations/XXXXX/apiKeys/XXXXX` and `-----BEGIN EC PRIVATE KEY-----\nXXXXXXXXXXXXXXXXX\n-----END EC PRIVATE KEY-----\n` respectively. When creating your API key, it is highly recommended to ensure that only the **View** box is ticked in the **API restrictions** section. {% include integrations/config_flow.md %} diff --git a/source/_integrations/comelit.markdown b/source/_integrations/comelit.markdown index 1864b138f10f..c0cc86022a72 100644 --- a/source/_integrations/comelit.markdown +++ b/source/_integrations/comelit.markdown @@ -17,6 +17,7 @@ ha_codeowners: ha_iot_class: Local Polling ha_platforms: - alarm_control_panel + - binary_sensor - climate - cover - humidifier @@ -38,4 +39,4 @@ There is support for the following platform types within Home Assistant: ## Alarm control panel -The integration will create an alarm entity for each area and a sensor for each zone. +The integration will create an alarm entity for each area. Additionally, it will create a sensor and a presence detection binary sensor for each zone, enhancing monitoring capabilities. diff --git a/source/_integrations/deako.markdown b/source/_integrations/deako.markdown new file mode 100644 index 000000000000..462290d0df2a --- /dev/null +++ b/source/_integrations/deako.markdown @@ -0,0 +1,36 @@ +--- +title: Deako Smart Lighting +description: Instructions on how to integrate Deako Smart Lighting into Home Assistant. +ha_category: + - Switch +ha_iot_class: Local Polling +ha_release: "2024.10" +ha_domain: deako +ha_config_flow: true +ha_platforms: + - light +ha_codeowners: + - '@sebirdman' + - '@balake' + - '@deakolights' +ha_zeroconf: true +ha_integration_type: integration +--- + +The **Deako Smart Lighting** integration allows you to control your [Deako](https://deako.com) devices from Home Assistant. + +## Prerequisites + +For this integration to work, your devices must be listed **online**, viewable in the Deako app. Once devices have been onboarded and are online, the Deako app is no longer needed. Devices will continue to work without the app. + +{% include integrations/config_flow.md %} + +## Supported devices + +- all smart Deako devices + +Features not currently supported: + +- Deako groups +- Deako scenes + diff --git a/source/_integrations/devolo_home_network.markdown b/source/_integrations/devolo_home_network.markdown index 3c32f23cd682..7389f469dd96 100755 --- a/source/_integrations/devolo_home_network.markdown +++ b/source/_integrations/devolo_home_network.markdown @@ -77,6 +77,9 @@ Currently the following device types within Home Assistant are supported. - PLC PHY rates - Updates every 5 minutes - PHY rates to/from the device attached to the router are enabled by default. PHY rates between all other devices are disabled by default. +- Last restart of the device + - Updates every 15 seconds + - Is disabled by default because it's of lower interest to most users. ### Switch diff --git a/source/_integrations/drop_connect.markdown b/source/_integrations/drop_connect.markdown index f770e1f57046..d8abe554a9d4 100644 --- a/source/_integrations/drop_connect.markdown +++ b/source/_integrations/drop_connect.markdown @@ -37,6 +37,7 @@ There is currently support for the following DROP products within Home Assistant - **Pump Controller**: smart replacement for an FSG pressure switch. - **RO Filter**: reverse osmosis drinking water filtration. - **Salt Sensor**: alerts when the salt level in the softener brine tank is low. +- **Alert**: monitors both the water level in a sump pit and electrical power to the sump pump. ### Prerequisites diff --git a/source/_integrations/econet.markdown b/source/_integrations/econet.markdown index f036a5c0a76a..8ada75431158 100644 --- a/source/_integrations/econet.markdown +++ b/source/_integrations/econet.markdown @@ -5,6 +5,7 @@ ha_category: - Binary sensor - Climate - Sensor + - Switch - Water heater ha_release: 0.61 ha_iot_class: Cloud Push @@ -16,6 +17,7 @@ ha_platforms: - binary_sensor - climate - sensor + - switch - water_heater ha_integration_type: integration --- @@ -31,6 +33,7 @@ EcoNet devices may be represented by one or more platforms. - [Binary sensor](#binary-sensor) - [Climate](#climate) - [Sensor](#sensor) +- [Switch](#switch) - [Water heater](#water-heater) ### Binary sensor @@ -45,6 +48,10 @@ The EcoNet Climate platform lets you control your EcoNet thermostat. Multi-zone The EcoNet Sensor platform lets you view sensors associated with your EcoNet thermostat or water heater. For example, alert count or available hot water. +### Switch + +The EcoNet Switch platform let's you control the EcoNet thermostat emergency heat. + ### Water heater The EcoNet water heater platform lets you control your EcoNet water heater. Water heaters do not report the current water temperature. diff --git a/source/_integrations/emoncms.markdown b/source/_integrations/emoncms.markdown index 3f923a92f5c7..a7f3f8232206 100644 --- a/source/_integrations/emoncms.markdown +++ b/source/_integrations/emoncms.markdown @@ -15,181 +15,26 @@ ha_integration_type: integration related: - docs: /docs/configuration/ title: Configuration file +ha_config_flow: true --- The `emoncms` sensor {% term integration %} creates sensors for the feeds available in your local or cloud based version of [Emoncms](https://emoncms.org). -To enable this {% term integration %}, add the following lines to your {% term "`configuration.yaml`" %} file. It will list all feeds as a sensor. -{% include integrations/restart_ha_after_config_inclusion.md %} - -```yaml -# Example configuration.yaml entry using cloud based Emoncms -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - id: 1 -``` - -As of Feb 2020, the integration will discover all sensors from Emoncms and will use the unit of measurement specified in the Feed from Emoncms, in preference to the one set in the configuration. Tested with [Emoncms](https://github.com/emoncms/emoncms) V10.1.13 - `unit` was added to the API around version V9.9.1. - To write information from Home Assistant to Emoncms, you can use the [`emoncms_history`](/integrations/emoncms_history) {% term integration %}. -## Configuration variables - -{% configuration %} -api_key: - description: The read API key for your Emoncms user. - required: true - type: string -url: - description: "The base URL of Emoncms, use for the cloud-based version. For self-hosted Emoncms or EmonPi you may need to use a URL of `http://x.x.x.x/emoncms`." - required: true - type: string -id: - description: Positive integer identifier for the sensor. Must be unique if you specify multiple Emoncms sensors. - required: true - type: integer -include_only_feed_id: - description: Positive integer list of Emoncms feed IDs. Only the feeds with feed IDs specified here will be displayed. Can not be specified if `exclude_feed_id` is specified. - required: false - type: list -exclude_feed_id: - description: Positive integer list of Emoncms feed IDs. All the feeds will be displayed as sensors except the ones listed here. Can not be specified if `include_only_feed_id` is specified. - required: false - type: list -sensor_names: - description: "Dictionary of names for the sensors created that are created based on feed ID. The dictionary consists of `feedid: name` pairs. Sensors for feeds with their feed ID mentioned here will get the chosen name instead of the default name." - required: false - type: [integer, list] -value_template: - description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to alter the feed value. - required: false - type: template -scan_interval: - description: Defines the update interval of the sensor in seconds. - required: false - type: integer -unit_of_measurement: - description: Defines the unit of measurement to be used for any sensor where the unit is *not* set in Emoncms. If no unit is set in Emoncms or in the configuration, the default (W) will be used. - required: false - default: W - type: string -{% endconfiguration %} - -## Default naming scheme - -The names of the sensors created by this integration will use the feed names defined in Emoncms if available, -or the feed ID otherwise, and will be prefixed with "Emoncms", e.g., "Emoncms Total Power" or "Emoncms Feed 5". -If the `id` property is anything but `1`, the ID will be shown as well, e.g., "Emoncms 2 Feed 5". - -If `sensor_names` is used, any feeds with defined names will get those names exactly, with no prefix. - -### Examples - -In this section you find some more examples of how this sensor can be used. - -Minimal configuration. All feeds are added as sensors with the unit of measurement being set by the Emoncms Feed or the default unit. - -```yaml -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - id: 1 -``` - -Display only feeds with their feed IDs specified in `include_only_feed_id`. - -```yaml -# Example configuration.yaml entry -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - id: 1 - unit_of_measurement: "W" - include_only_feed_id: - - 107 - - 105 -``` - -Display all feeds except feeds with their feed ID specified in `exclude_feed_id`. - -```yaml -# Example configuration.yaml entry -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - id: 1 - unit_of_measurement: "kWh" - exclude_feed_id: - - 107 - - 105 -``` - -Display only feeds with their feed IDs specified in `include_only_feed_id` and give the feed sensors a name using `sensor_names`. You don't have to specify all feeds names in `sensor_names`, the remaining sensor names will be chosen based on `id` and the Emoncms `feedid`. - -```yaml -# Example configuration.yaml entry -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - id: 1 - unit_of_measurement: "kW" - include_only_feed_id: - - 5 - - 120 - sensor_names: - 5: "feed 1" - 48: "kWh feed" - 61: "amp feed" - 110: "watt feed" -``` - -Use a `value_template` to add 1500 to the feed value for all specified feed IDs in `include_feed_id`. - -{% raw %} +## Prerequisites -```yaml -# Example configuration.yaml entry -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - scan_interval: 15 - id: 1 - value_template: "{{ value | float + 1500 }}" - include_only_feed_id: - - 107 - - 106 -``` + To use this service, you need an Emoncms account and an API key. You can find the API key in your local or cloud-based Emoncms account settings. -{% endraw %} +{% include integrations/config_flow.md %} -Display feeds from the same Emoncms instance with 2 groups of feeds, where one has a differing `scan_interval` and the other a differing `unit_of_measurement`. +## Sensors -```yaml -# Example configuration.yaml entry -sensor: - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - scan_interval: 30 - id: 1 - unit_of_measurement: "W" - include_only_feed_id: - - 107 - - 106 - - platform: emoncms - api_key: API_KEY - url: https://emoncms.org - id: 2 - scan_interval: 60 - unit_of_measurement: "A" - include_only_feed_id: - - 108 - - 61 -``` +- **energy** in Wh, kWh +- **power** in W +- **voltage** in V +- **current** in A +- **apparent power** in VA +- **temperature** in °C, °F or K +- **frequency** in Hz +- **pressure** in hPa diff --git a/source/_integrations/enphase_envoy.markdown b/source/_integrations/enphase_envoy.markdown index 30b90d7549db..d969202a18a0 100644 --- a/source/_integrations/enphase_envoy.markdown +++ b/source/_integrations/enphase_envoy.markdown @@ -44,10 +44,13 @@ For Envoy S Metered / IQ Gateway Metered with installed and configured current t - Sensors for net production (grid export) and net consumption (grid import) if the consumption CT is a net-consumption CT. - Disabled sensors for: + - `Balanced net power consumption` and `lifetime balanced net energy consumption` (grid import - grid export) if either a net-consumption or total-consumption CT is installed. The `balanced net power consumption` value is calculated by the Envoy if a total-consumption CT is used. When a net-consumption CT is installed, it is the same value as the `current net power consumption`, which is enabled by default if the CT is present. - Production and consumption sensors for each phase, if CT are installed on more than 1 phase. - Phase net production and net consumption, if CT are installed on more than 1 phase. - - Frequency net consumption CT (aggregate and phase). - - Voltage net consumption CT (aggregate and phase).[^1] + - Frequency for production and net consumption CT (aggregate and phase). + - Voltage for production and net consumption CT (aggregate and phase).[^1] + - Current for production and net consumption CT (aggregate and phase).[^1] + - Powerfactor for production and net consumption CT (aggregate and phase).[^1] - Metering status for net consumption and production CT (`normal` | `not-metering` | `check-wiring`) (aggregate and phase). - Count of meter status flags active for net consumption and production CT (aggregate and phase).[^2] @@ -59,22 +62,27 @@ For Envoy S Metered / IQ Gateway Metered with installed and configured current t For Enphase Ensemble systems with the Enpower/IQ System Controller and Encharge/IQ Batteries installed, additional features are available: - Sensors for battery status and usage -- Sensors for grid status (*) -- Sensors for the state of the Enpower's four load-shedding relays (*) -- A switch allowing you to take your system on-grid and off-grid. Note that the Enpower has a slight delay built-in between receiving these commands and actually switching the system on or off grid. (*) -- A switch allowing you to enable or disable charging the Encharge/IQ batteries from the power grid. (*) -- Support for changing the battery storage mode between full backup, self-consumption, and savings mode and setting the reserve battery level for outages. +- Sensors for grid status * +- Sensors for the state of the Enpower's four load-shedding relays * +- A switch allowing you to take your system on-grid and off-grid. Note that the Enpower has a slight delay built-in between receiving these commands and actually switching the system on or off grid. * +- A switch allowing you to enable or disable charging the Encharge/IQ batteries from the power grid. ** +- Support for changing the battery storage mode between full backup, self-consumption, and savings mode, and setting the reserve battery level for outages. ** - If a storage CT is installed: - Sensors for battery storage energy charged and discharged and current active power discharge/charge - Disabled sensors for: - Phase battery storage energy charged and discharged and current power discharge/charge - - Voltage storage CT (aggregate and phase) + - Voltage for storage CT (aggregate and phase) + - Current for storage CT (aggregate and phase) + - Frequency for storage CT (aggregate and phase) + - Powerfactor for storage CT (aggregate and phase) - Metering status for storage CT (aggregate and phase) - Count of meter status flags active storage CT (aggregate and phase) -The load shedding and on/off-grid functions marked (*) are only available with the Enpower/IQ System Controller installed. In battery installations without off-grid functionality, used in many EU countries, these off-grid related sensors and switches are not available. +*: The load shedding and on/off-grid functions are only available with the Enpower/IQ System Controller installed. In battery installations without load-shedding and off-grid functionality, used in many EU countries, these sensors and switches are not available. -In multiphase installations with batteries, in countries with phase-balancing grid meters, the battery will export to the grid on one phase the amount it lacks on another phase, as if it is using the grid as a 'transport' between phases. Since the grid meter will balance the amount in and exported on the two phases, the net result is zero. The Envoy multiphase consumption CTs, however, will report the amounts on both phases, resulting in too high export on one and too high import on the other. One needs to use the sum of grid import and export to eliminate this effect. +**: When used with Enpower/IQ System Controller, the entities to charge from the grid, battery storage mode, and reserve battery level are connected to the Enpower device with the Enpower serial number in their entity and unique IDs. When no Enpower is installed, these are connected to the Envoy itself and the Envoy serial number is used in the IDs. + +In multiphase installations with batteries, in countries with phase-balancing grid meters, the battery will export to the grid on one phase the amount it lacks on another phase which pulls the amount from the grid, as if it is using the grid as a 'transport' between phases. Since the grid meter will balance the amount imported and exported on the two phases, the net result is zero. The Envoy multiphase consumption CTs, however, will report the amounts on both phases, resulting in too high export on one and too high import on the other. One may consider using the `lifetime balanced net energy consumption` which is the sum of grid import and export to eliminate this effect. This would require some templating to split these values into import and export values. Alternatively, use the `current net power consumption` or `balanced net power consumption` with a Riemann integral sum helper. ## Envoy authentication requirements diff --git a/source/_integrations/epson.markdown b/source/_integrations/epson.markdown index e89a645d235f..aca9d8e1a32f 100644 --- a/source/_integrations/epson.markdown +++ b/source/_integrations/epson.markdown @@ -20,7 +20,7 @@ When you want to add a device for the first time, turn it on before following th {% include integrations/config_flow.md %} -### Supported features +## Supported features - turn on/off - set input @@ -29,7 +29,7 @@ When you want to add a device for the first time, turn it on before following th - mute/unmute audio - send next/previous track -### Supported devices +## Supported devices - Epson projectors supporting ESC/VP21 protocol. @@ -38,6 +38,29 @@ When you want to add a device for the first time, turn it on before following th - Epson EH-TW5350 - Epson EH-TW7000 - Epson EH-TW9400W (shares platform with 7400/8400/9400(w)) +- Epson EH-TW3200 -To make this module work you need to connect your projector to your LAN. -The best is to use iProjection app by Epson to test if it is working. +## Configuration + +This integration supports connecting to an Epson projector via LAN or Serial. + +### LAN connection + +Connect the projector to your LAN and enter the IP address of the projector when prompted, selecting either HTTP or TCP depending on what the projector model supports. +The iProjection app by Epson can be used to test if it is working. + +### Serial connection + +Connect projector directly to Home Assistant via a serial cable, or ser2net can be used as a Serial to network proxy. + +#### ser2net configuration + +A ser2net configuration similar to below can be used to expose the projector connected to `/dev/ttyUSB0` on port `3629`. + +```yaml +connection: &con1 + accepter: tcp,3629 + connector: serialdev,/dev/ttyUSB0,9600n81 +``` + +Then the projector can be added to the integration using `socket://:3629`. diff --git a/source/_integrations/fujitsu_fglair.markdown b/source/_integrations/fujitsu_fglair.markdown new file mode 100644 index 000000000000..b3a6628b751e --- /dev/null +++ b/source/_integrations/fujitsu_fglair.markdown @@ -0,0 +1,36 @@ +--- +title: Fujitsu FGLair +description: Control your Fujitsu heat pump or air conditioner that uses the FGLair app +ha_category: + - Climate +ha_release: 2024.9 +ha_domain: fujitsu_fglair +ha_integration_type: integration +ha_codeowners: + - '@crevetor' +ha_config_flow: true +ha_platforms: + - climate +ha_iot_class: "Cloud Polling" +--- + +The {{ page.title }} {% term integration %} provides support for Fujitsu heat pumps and air conditioners that use the FGLair app. +To find out which app to use for your heat pump, check [the Fujitsu FGLair FAQ](https://www.fujitsu-general.com/global/support/faq/airstage-mobile/0127.html). + +## Prerequisites + +First, set up your device in the FGLair app before using this integration. +To configure this integration, you will need the credentials (login and password) used to connect to the FGLair application. + +{% include integrations/config_flow.md %} + +## Climate + +This integration supports the following functionalities (if the devices support them): + +- [`set_hvac_mode`](/integrations/climate/#action-climateset_hvac_mode) +- [`target temperature`](/integrations/climate#action-climateset_temperature) +- [`turn on/off`](/integrations/climate#action-climateturn_on) +- [`fan mode`](/integrations/climate#action-climateset_fan_mode) +- [`swing mode`](/integrations/climate#action-climateset_swing_mode) + diff --git a/source/_integrations/google_cloud.markdown b/source/_integrations/google_cloud.markdown index d0428de15c04..83ff89ea574f 100644 --- a/source/_integrations/google_cloud.markdown +++ b/source/_integrations/google_cloud.markdown @@ -2,39 +2,27 @@ title: Google Cloud Platform description: Google Cloud Platform integration. ha_category: + - Speech-to-text - Text-to-speech + - Voice ha_release: 0.95 +ha_config_flow: true ha_iot_class: Cloud Push ha_codeowners: - '@lufton' + - '@tronikos' ha_domain: google_cloud ha_platforms: + - stt - tts -ha_integration_type: integration +ha_integration_type: service --- -The `google_cloud` platform allows you to use [Google Cloud Platform](https://cloud.google.com/) API and integrate them into Home Assistant. +The Google Cloud integration allows you to use [Google Cloud Platform](https://cloud.google.com/) APIs and integrate them into Home Assistant. -## Configuration +{% include integrations/config_flow.md %} -To use Google Cloud Platform, you need to provide `config` directory relative path of [`API key`](#obtaining-an-api-key) file you are going to use. Place it under `config` folder and set `key_file` parameter in {% term "`configuration.yaml`" %}: - -```yaml -# Example configuration.yaml entry -tts: - - platform: google_cloud - key_file: googlecloud.json -``` - -## Obtaining an API key - -API key obtaining process described in corresponding documentation: - -- [Text-to-speech](https://cloud.google.com/text-to-speech/docs/quickstart-protocol) -- [Speech-to-text](https://cloud.google.com/speech-to-text/docs/quickstart-protocol) -- [Geocoding](https://developers.google.com/maps/documentation/geocoding/start) - -Basic instruction for all APIs: +## Obtaining service account file 1. Visit [Cloud Resource Manager](https://console.cloud.google.com/cloud-resource-manager). 2. Click `CREATE PROJECT` button at the top. @@ -45,7 +33,6 @@ Basic instruction for all APIs: - [Text-to-speech](https://console.cloud.google.com/flows/enableapi?apiid=texttospeech.googleapis.com) - [Speech-to-text](https://console.cloud.google.com/flows/enableapi?apiid=speech.googleapis.com) - - [Geocoding](https://console.cloud.google.com/flows/enableapi?apiid=geocoding-backend.googleapis.com) 6. Set up authentication: 1. Visit [this link](https://console.cloud.google.com/apis/credentials/serviceaccountkey) @@ -61,31 +48,22 @@ Basic instruction for all APIs: 8. In the `Add Key` dropdown, select `Create New Key`. 9. Specify a `JSON` key type and click `Create`. 10. A `[serviceaccountname].json` file will download to your browser. + 11. Upload this file when asked in the integration setup. ## Google Cloud text-to-speech -[Google Cloud text-to-speech](https://cloud.google.com/text-to-speech/) converts text into human-like speech in more than 100 voices across 20+ languages and variants. It applies groundbreaking research in speech synthesis (WaveNet) and Google's powerful neural networks to deliver high-fidelity audio. With this easy-to-use API, you can create lifelike interactions with your users that transform customer service, device interaction, and other applications. +[Google Cloud text-to-speech](https://cloud.google.com/text-to-speech/) converts text into human-like speech in [380+ voices across 50+ languages and variants](https://cloud.google.com/text-to-speech/docs/voices). It applies groundbreaking research in speech synthesis and Google's powerful neural networks to deliver high-fidelity audio. With this easy-to-use API, you can create lifelike interactions with your users that transform customer service, device interaction, and other applications. ### Pricing -The Cloud text-to-speech API is priced monthly based on the amount of characters to synthesize into audio sent to the service. - -| Voice | Monthly free tier | Paid usage | -| ------------------ | ------------------------- | --------------------------------- | -| Neural2 | 0 to 1 million bytes | $16.00 USD / 1 million bytes | -| Polyglot (Preview) | 0 to 1 million bytes | $16.00 USD / 1 million bytes | -| Studio (Preview) | 0 to 100 thousand bytes | $160.00 USD / 1 million bytes | -| Standard | 0 to 4 million characters | $4.00 USD / 1 million characters | -| WaveNet | 0 to 1 million characters | $16.00 USD / 1 million characters | +The Cloud text-to-speech API is priced monthly based on the number of characters to synthesize into audio sent to the service. For up-to-date pricing, see [here](https://cloud.google.com/text-to-speech/pricing). ### Text-to-speech configuration +Below settings can be configured in the options of the integration and in the `options` parameter of the `tts.speak` service. + {% configuration %} -key_file: - description: "The [`API key`](#obtaining-an-api-key) file to use with Google Cloud Platform. If not specified `os.environ['GOOGLE_APPLICATION_CREDENTIALS']` path will be used." - required: false - type: string language: description: "Default language of the voice, e.g., `en-US`. Supported languages, genders and voices listed [here](https://cloud.google.com/text-to-speech/docs/voices). Also there are extra not documented but supported languages (see dropdown [here](https://cloud.google.com/text-to-speech/#streaming_demo_section))." required: false @@ -132,16 +110,20 @@ text_type: default: "text" {% endconfiguration %} -### Full configuration example +### Full example -The Google Cloud text-to-speech configuration can look like: +A `tts.speak` service call can look like: ```yaml -# Example configuration.yaml entry -tts: - - platform: google_cloud - key_file: googlecloud.json - language: en-US +service: tts.speak +target: + entity_id: tts.google_cloud +data: + cache: true + media_player_entity_id: media_player.living_room_display + message: this is a test + language: en-US + options: gender: male voice: en-US-Wavenet-F encoding: linear16 @@ -153,3 +135,20 @@ tts: - telephony-class-application - wearable-class-device ``` + +## Google Cloud speech-to-text + +[Google Cloud speech-to-text](https://cloud.google.com/speech-to-text) converts audio into text transcriptions for [125 languages and variants](https://cloud.google.com/speech-to-text/docs/speech-to-text-supported-languages). + +### Pricing + +Speech-to-text is priced based on the amount of audio successfully processed by the service each month, measured in increments of one second. For up-to-date pricing, see [here](https://cloud.google.com/speech-to-text/pricing) under the Speech-to-text v1 API. + +### Speech-to-text configuration + +{% configuration %} +stt_model: + description: "One of the transcription models [here](https://cloud.google.com/speech-to-text/docs/transcription-model). Defaults to `latest_short`." + required: false + type: string +{% endconfiguration %} diff --git a/source/_integrations/google_photos.markdown b/source/_integrations/google_photos.markdown new file mode 100644 index 000000000000..03c8f2cff5c9 --- /dev/null +++ b/source/_integrations/google_photos.markdown @@ -0,0 +1,81 @@ +--- +title: Google Photos +description: Instructions on how to use Google Photos in Home Assistant. +ha_category: + - Media source +ha_iot_class: Cloud Polling +ha_release: "2024.10" +ha_config_flow: true +ha_domain: google_photos +ha_codeowners: + - '@allenporter' +ha_integration_type: integration +ha_platforms: + - media_source +related: + - docs: /integrations/media_source + title: Media source integration documentation + - url: https://photos.google.com/ + title: Google Photos + - url: https://console.cloud.google.com/apis/library/photoslibrary.googleapis.com + title: Google Developers Console +--- + +The **Google Photos** integration allows you to connect your [Google Photos](https://photos.google.com/) to Home Assistant. The integration adds a [media source](/integrations/media_source) with +recent photos allowing you to view or cast your photos from the media browser. + +## 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), [Google Tasks](/integrations/google_tasks), and [Google Mail](/integrations/google_mail). +These are not the same as *Device Auth* credentials previously recommended for [Google Calendar](/integrations/google). + +If you have already set up the correct 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/photoslibrary.googleapis.com). + +1. First, go to the Google Developers Console to enable [Google Photos Library API](https://console.cloud.google.com/apis/library/photoslibrary.googleapis.com) +2. The wizard will ask you to choose a project to manage your application. Select a project and select **Continue**. +3. Verify that your Google Photos Library API was enabled and select **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, for example to *Home Assistant*. +8. You then need to select a **Support email**. To do this, from the dropdown menu, 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 select **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 select **Save and Continue** to move to the **Optional info** page. You do not need to add anything to the **Optional info** page, so select **Save and Continue**, which will take you to the **Summary** page. Select **Back to Dashboard**. +12. Select **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. Select **Credentials** in the menu on the left-hand side of the screen, then select **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 select **Create**. This is not a placeholder and is the URI that must be used. +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 them shortly. Once you have noted these strings, select **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**, select 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 Photos Library API** has been automatically enabled. To do this, select **Library** from the menu, then search for **Google Photos Library 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 Photos. + +{% 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. Select **Continue**. Keep in mind this is giving sensitive access to your private Photo Library. + +4. The page will now display **Link account to Home Assistant?**, note **Your instance URL**. If this is not correct, refer to [My Home Assistant](/integrations/my). If everything looks good, select **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. diff --git a/source/_integrations/habitica.markdown b/source/_integrations/habitica.markdown index 03faae79d252..3f95f86baf3b 100644 --- a/source/_integrations/habitica.markdown +++ b/source/_integrations/habitica.markdown @@ -20,7 +20,15 @@ ha_config_flow: true ha_integration_type: integration --- -The Habitca {% term integration %} enables you to monitor your adventurer's progress and stats in Home Assistant and seamlessly integrates your to-do's and daily tasks. +The Habitca {% term integration %} enables you to monitor your adventurer's progress and stats in Home Assistant and seamlessly integrates your to-do's and daily tasks. + +## Prerequisites for Habitica integration + +- To set up the Habitica integration, you must first have an active Habitica account. You can register for an account at [Habitica.com](https://habitica.com/). +- During the setup process in Home Assistant, you can choose between two login options: + - "Login to Habitica", which allows you to log in with your *username* or *email* and *password*. + - "Login to other instances", which requires your `User ID` and `API Token`. The `User ID` and `API Token` can be retrieved by logging into your Habitica account, navigating to the **Settings** menu, and selecting **Site Data**. + - Additionally, you will need to provide the URL for the Habitica instance you wish to connect to; the default URL is `https://habitica.com`, but you can specify a different URL if you are using an alternative Habitica instance or a self-hosted instance. {% include integrations/config_flow.md %} diff --git a/source/_integrations/homematicip_cloud.markdown b/source/_integrations/homematicip_cloud.markdown index 4dc697d794e2..5b5b696539a4 100644 --- a/source/_integrations/homematicip_cloud.markdown +++ b/source/_integrations/homematicip_cloud.markdown @@ -219,6 +219,7 @@ Executable by all users: - `homematicip_cloud.deactivate_eco_mode`: Deactivates the eco mode immediately. - `homematicip_cloud.deactivate_vacation`: Deactivates the vacation mode immediately. - `homematicip_cloud.set_active_climate_profile`: Set the active climate profile index. +- `homematicip_cloud.set_home_cooling_mode`: Enable or disable cooling for the home. Executable by administrators or within the context of an automation: - `homematicip_cloud.dump_hap_config`: Dump the configuration of the Homematic IP Access Point(s). @@ -318,6 +319,16 @@ action: entity_id: switch.livingroom ``` +Enable (or disable) Cooling mode for the entire home. Disabling Cooling mode will revert to Heating. + +```yaml +... +action: + action: homematicip_cloud.set_home_cooling_mode + data: + cooling: True + accesspoint_id: 3014xxxxxxxxxxxxxxxxxxxx +``` ## Additional info diff --git a/source/_integrations/html5.markdown b/source/_integrations/html5.markdown index da7d2cb19c63..ff8ed39a08bc 100644 --- a/source/_integrations/html5.markdown +++ b/source/_integrations/html5.markdown @@ -4,6 +4,7 @@ description: Instructions on how to use the HTML5 push notifications platform fr ha_category: - Notifications ha_release: 0.27 +ha_config_flow: true ha_iot_class: Cloud Push ha_domain: html5 ha_platforms: @@ -20,35 +21,6 @@ The `html5` notification {% term integration %} enables you to receive push noti HTML5 push notifications **do not** work on iOS versions below 16.4. {% endimportant %} -## Configuration - -To enable this platform, add the following lines to your {% term "`configuration.yaml`" %} file. -{% include integrations/restart_ha_after_config_inclusion.md %} - -```yaml -# Example configuration.yaml entry -notify: - - platform: html5 - vapid_pub_key: YOUR_PUBLIC_KEY - vapid_prv_key: YOUR_PRIVATE_KEY - vapid_email: YOUR_EMAIL -``` - -{% configuration %} -vapid_pub_key: - description: The VAPID public key generated by Google (this is the key that is immediately visible under "webpush certificates"), [see configuring the platform](#configuring-the-platform). - required: true - type: string -vapid_prv_key: - description: The VAPID private key generated by Google, [see configuring the platform](#configuring-the-platform). - required: true - type: string -vapid_email: - description: The email account of your Google account associated with your Firebase project, [see configuring the platform](#configuring-the-platform). - required: true - type: string -{% endconfiguration %} - ### Requirements The `html5` platform can only function if all of the following requirements are met: @@ -60,15 +32,8 @@ The `html5` platform can only function if all of the following requirements are - You have configured SSL/TLS for your Home Assistant. It doesn't need to be configured in Home Assistant though, e.g., you can be running NGINX in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e., not self-signed). - You are willing to accept the notification permission in your browser. -### Configuring the platform -1. Create a new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard), this project will be imported into Firebase later (alternatively, the project can also be created in the next step). -2. Go to [https://console.firebase.google.com](https://console.firebase.google.com), and click the "Add project" button -3. Choose your Google Cloud project for the name field (or create a new one). Decline analytics. -4. Then, click the cogwheel on top left and select "Project settings". -5. Select the "Cloud Messaging" tab. -6. Generate a new key pair in "Web configuration" at the bottom of the page. Add the public key as `vapid_pub_key` in the config, then choose the 3 dots, and copy the private key for `vapid_prv_key` in the config. -7. Input your Google email as `vapid_email` in the config. +{% include integrations/config_flow.md %} ### Setting up your browser diff --git a/source/_integrations/husqvarna_automower.markdown b/source/_integrations/husqvarna_automower.markdown index ed7364cb4f11..9dba15565dff 100644 --- a/source/_integrations/husqvarna_automower.markdown +++ b/source/_integrations/husqvarna_automower.markdown @@ -107,7 +107,7 @@ The integration will create the following binary sensors: ### Button (if available) -The integration will create a button entity for confirming minor mower errors. This entity is disabled by default. You have to enable it manually. The API can't detect if the mower has the capability to confirm minor errors remotely. Before enabling this function, refer to the mower documentation. +The integration will create a button entity for confirming minor mower errors. ### Device tracker (if available) diff --git a/source/_integrations/iskra.markdown b/source/_integrations/iskra.markdown new file mode 100644 index 000000000000..d0d49c5b9ea4 --- /dev/null +++ b/source/_integrations/iskra.markdown @@ -0,0 +1,81 @@ +--- +title: Iskra +description: Instructions on how to connect your Iskra energy meters to Home Assistant. +ha_release: "2024.10" +ha_category: + - Energy + - Sensor +ha_codeowners: + - '@iskramis' +ha_config_flow: true +ha_domain: iskra +ha_iot_class: local_polling +ha_platforms: + - sensor +ha_integration_type: integration +--- + + +The [Iskra](https://www.iskra.eu/) {% term integration %} allows you to connect Iskra energy meters and power quality analyzers to Home Assistant. Data is polled using Modbus TCP or the Iskra Smart Gateway's REST API. + +## Supported devices + +### Energy meters + +Most Iskra's DIN rail mountable energy meters support Modbus RTU over RS485 and IR. To integrate them, you will need a Modbus TCP gateway or Iskra's Smart Gateway: + +- Impact series ([IE38XX / IE14XX](https://www.iskra.eu/en/Iskra-Energy-meters/)) +- WM series ([WM3XX / WM1XX](https://www.iskra.eu/en/Iskra-Energy-meters/)) + +### Power quality analyzers + +These devices typically support Ethernet connections and use Modbus TCP for data polling: + +- iMT/MT series ([MTXXX / iMTXXX](https://www.iskra.eu/en/NEW_SERIES_Universal_measuring_devices_/)) +- iMC/MC series ([MCXXX / iMCXXX](https://www.iskra.eu/en/NEW_SERIES_Universal_measuring_devices_/)) + +## Configuration options + +There are two ways to configure your devices with Home Assistant: +- [Using a Smart Gateway with REST API](#smart-gateway-with-rest-api) +- [Using a Modbus TCP connection](#modbus-tcp-connection) + +### Smart Gateway with REST API + +If your device supports Modbus RTU over RS485/IR, you can use Iskra's Smart Gateway to connect them via the REST API: + +- **Smart Gateway**: Connect your devices to the Smart Gateway and add your devices to the Smart Gateway's configuration. It's also recommended to set a static IP on your smart gateway. +- **Home Assistant**: Add the Iskra integration, enter the Smart Gateway's **IP address**, and select **RestAPI** as the connection type within the Home Assistant integration. If authentication is required, Home Assistant will prompt you to enter the Smart Gateway's **credentials**. All devices configured on the Smart Gateway will be automatically added to your Home Assistant. + +### Modbus TCP connection + +If your device supports a direct internet connection, such as PQ meters (iMC/MC series/ iMT/MT series usually), you can use Modbus TCP: + +- **Device**: Find your device using the [MiQen](https://www.iskra.si/sl/Programska-oprema/MiQen/) software and configure it to use a static IP. +- **Home Assistant**: Add the Iskra integration, enter the device's **IP address**, and select **Modbus TCP** as the connection type within the Home Assistant integration. Home Assistant will prompt you to enter the Modbus TCP port and Modbus address of your device. + +{% include integrations/config_flow.md %} + +## Sensors + +The integration provides detailed information about power, current, and voltage for each phase. The data is updated every minute. + +| Name | Unit | Description | +| ------------------- | ---- | :-------------------------------------------------------------------------- | +| total_active_power | W | Total active power. | +| total_reactive_power| var | Total reactive power. | +| total_apparent_power| VA | Total apparent power. | +| phase1_power | W | Active power of phase 1. | +| phase2_power | W | Active power of phase 2. | +| phase3_power | W | Active power of phase 3. | +| phase1_voltage | V | Voltage of phase 1. | +| phase2_voltage | V | Voltage of phase 2. | +| phase3_voltage | V | Voltage of phase 3. | +| phase1_current | A | Current of phase 1. | +| phase2_current | A | Current of phase 2. | +| phase3_current | A | Current of phase 3. | +| frequency | Hz | Frequency. | + +## Note + +This integration supports Iskra's energy meters, not Iskra Emeco ones. diff --git a/source/_integrations/ista_ecotrend.markdown b/source/_integrations/ista_ecotrend.markdown index 254958515c72..04de97bf2314 100644 --- a/source/_integrations/ista_ecotrend.markdown +++ b/source/_integrations/ista_ecotrend.markdown @@ -34,3 +34,37 @@ The **ista EcoTrend** integration exposes the last monthly readings as sensors. - **Water costs**: estimated costs in EUR Not all values may be available in your ista EcoTrend account. Cost estimation is an optional service that has to be booked by your property manager. Therefore, the cost sensors are deactivated by default. + +## Long-term statistics + +The **ista EcoTrend** integration allows you to import all your historical consumption readings from your ista EcoTrend account into long-term statistic entities. These entities can be displayed in your Home Assistant energy dashboard, providing a comprehensive view of your consumption data over time. + +### Identifying ista EcoTrend statistic entities + +The statistic entities imported via this integration have a `ista_ecotrend:` prefix. This prefix helps you identify and distinguish these entities from other sensor statistics when setting up the long-term statistics in the energy dashboard. + +### Setting up long-term statistics in the energy dashboard + +To set up the **ista EcoTrend** long-term statistics in your Home Assistant energy dashboard, follow these steps: + +- **Access the energy configuration panel** + - Go to the [energy configuration panel](https://my.home-assistant.io/redirect/config_energy/) of your Home Assistant instance. + + [![Open your Home Assistant instance and show your energy configuration panel.](https://my.home-assistant.io/badges/config_energy.svg)](https://my.home-assistant.io/redirect/config_energy/) + +- **Add heating energy usage** + - Go to **Gas consumption**. + - Select **Add gas source**. + - Choose your **Heating energy** entity (for example, `ista_ecotrend:luxemburger_str_1_heating_energy`). + - For cost tracking, select the **Use an entity tracking the total costs** option. + - Select the corresponding **Heating costs** entity (for example, `ista_ecotrend:luxemburger_str_1_heating_cost`). +- **Add hot water energy usage** + - To track hot water energy usage and costs (for example, `ista_ecotrend:luxemburger_str_1_hot_water_energy` and `ista_ecotrend:luxemburger_str_1_hot_water_cost`), repeat the above steps for your **Hot water energy** and **Hot water costs** entities. +- **Add hot water consumption** + - Go to **Water consumption**. + - Select **Add water source**. + - Choose the **Hot water** entity (for example, `ista_ecotrend:luxemburger_str_1_hot_water`). + - For cost tracking, select the **Use an entity tracking the total costs** option. + - Select the corresponding **Hot water costs** entity (for example, `ista_ecotrend:luxemburger_str_1_hot_water_cost`). +- **Add water consumption** + - To track cold water consumption and costs (for example, `ista_ecotrend:luxemburger_str_1_water` and `ista_ecotrend:luxemburger_str_1_water_cost`), repeat the above steps for your **Water** and **Water costs** entities. diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 37266f726dc2..7e6a628415b8 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -74,10 +74,6 @@ There is currently support for the following device types within Home Assistant: - [Time](#time) - [Weather](#weather) -## Free KNX online training - -As a Home Assistant KNX user, you can start a FREE KNX online training and get a discounted ETS Home license on the [KNX website](https://www.knx.org/knx-en/for-your-home/home-assistant/). - {% include integrations/config_flow.md %} ## Basic configuration @@ -787,29 +783,28 @@ 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 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`: - `0` (cooling) - `1` (heating) -The following values are valid for the Home Assistant [Climate](/integrations/climate/) `hvac_mode` attribute. Supported values for your KNX thermostats can be specified via `controller_modes` configuration variable: +Supported HVAC modes for your KNX thermostats are found automatically. This can be overridden by using the `controller_modes` configuration variable. The following values are valid controller modes: -- `off` (maps internally to `HVAC_MODE_OFF` within Home Assistant) -- `auto` (maps internally to `HVAC_MODE_AUTO` within Home Assistant) -- `heat` (maps internally to `HVAC_MODE_HEAT` within Home Assistant) -- `cool` (maps internally to `HVAC_MODE_COOL` within Home Assistant) -- `fan_only` (maps internally to `HVAC_MODE_FAN_ONLY` within Home Assistant) -- `dehumidification` (maps internally to `HVAC_MODE_DRY` within Home Assistant) +- `off` +- `auto` +- `heat` +- `cool` +- `fan_only` +- `dehumidification` -The following presets are valid for the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute. Supported values for your KNX thermostats can be specified via `operation_modes` configuration variable: +Supported preset modes for your KNX thermostats are found automatically. This can be overridden by using the `operation_modes` configuration variable. The following values are valid operation modes: -- `auto` (maps to `none` of the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute) -- `comfort` (maps to `comfort` of the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute) -- `standby` (maps to `away` of the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute) -- `economy` (maps to `sleep` of the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute) -- `building_protection` (maps to `eco` of the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute) +- `auto` +- `comfort` +- `standby` +- `economy` +- `building_protection` {% configuration %} name: @@ -914,11 +909,11 @@ operation_mode_standby_address: required: false type: [string, list] operation_modes: - description: Overrides the supported operation modes. Provide the supported `preset_mode` values for your device. + description: Overrides the supported operation modes. Provide the supported `preset_modes` value for your device. required: false type: list controller_modes: - description: Overrides the supported controller modes. Provide the supported `hvac_mode` values for your device. + description: Overrides the supported controller modes. Provide the supported `hvac_modes` value for your device. required: false type: list default_controller_mode: diff --git a/source/_integrations/lektrico.markdown b/source/_integrations/lektrico.markdown new file mode 100644 index 000000000000..14857ea8068c --- /dev/null +++ b/source/_integrations/lektrico.markdown @@ -0,0 +1,79 @@ +--- +title: Lektrico Charging Station +description: Instructions on how to integrate a Lektrico Chargering Station with Home Assistant. +ha_category: + - Sensor +ha_release: "2024.10" +ha_iot_class: Local Polling +ha_config_flow: true +ha_codeowners: + - '@lektrico' +ha_domain: lektrico +ha_zeroconf: true +ha_platforms: + - sensor +--- + +The **Lektrico Charging Station** integration integrates your [Lektrico Charging Station](https://lektri.co) into your Home Assistant and allows you to monitor it. + +The Lektrico Charging Station device will be added as a sensor in Home Assistant. + +{% include integrations/config_flow.md %} + +## Sensors + +Sensors available in the library: + +### Single-phase charger + +| Condition | Unit | Description | +| :------------------ | :--- | :-------------------------------------------------------- | +| state | | State of the charger. | +| charging_time | s | Indicates the current session charging time. | +| power | kW | Current instant power. | +| energy | kWh | Total charged energy for the current charging session. | +| temperature | °C | Board temperature. | +| lifetime_energy | kWh | Total charged energy since installation. | +| installation_current| A | Current value [A] to be limited by software. | +| limit_reason | | Current limit reason. | +| voltage | V | Measured voltage. | +| current | A | Measured current. | + +### Three-phase charger + +| Condition | Unit | Description | +| :------------------ | :--- | :-------------------------------------------------------- | +| state | | State of the charger. | +| charging_time | s | Indicates the current session charging time. | +| power | kW | Current instant power. | +| energy | kWh | Total charged energy for the current charging session. | +| temperature | °C | Board temperature. | +| lifetime_energy | kWh | Total charged energy since installation. | +| installation_current| A | Current value [A] to be limited by software. | +| limit_reason | | Current limit reason. | +| voltage_l1 | V | Measured voltage on L1. | +| voltage_l2 | V | Measured voltage on L2. | +| voltage_l3 | V | Measured voltage on L3. | +| current_l1 | A | Measured current on L1. | +| current_l2 | A | Measured current on L2. | +| current_l3 | A | Measured current on L3. | + +### Single-phase energy meter + +| Condition | Unit | Description | +| :------------------ | :--- | :-------------------------------------------------------- | +| breaker_current | A | Main breaker current. | +| power | kW | Measured active power. | +| pf | | Power factor. | + +### Three-phase energy meter + +| Condition | Unit | Description | +| :------------------ | :--- | :-------------------------------------------------------- | +| breaker_current | A | Main breaker current. | +| power_l1 | kW | Measured active power on L1. | +| power_l2 | kW | Measured active power on L2. | +| power_l3 | kW | Measured active power on L3. | +| pf_l1 | | Power factor on L1. | +| pf_l2 | | Power factor on L2. | +| pf_l3 | | Power factor on L3. | diff --git a/source/_integrations/lg_thinq.markdown b/source/_integrations/lg_thinq.markdown new file mode 100644 index 000000000000..1d5818006bf4 --- /dev/null +++ b/source/_integrations/lg_thinq.markdown @@ -0,0 +1,139 @@ +--- +title: LG ThinQ +description: Setup for LG ThinQ Integration. +ha_category: + - Hub +ha_release: "2024.10" +ha_iot_class: Cloud Push +ha_code_owners: + - '@LG-ThinQ-Integration' +ha_config_flow: true +ha_domain: lg_thinq +ha_platforms: + - switch + - binary_sensor +ha_integration_type: integration +--- + +The **LG ThinQ** integration allows you to connect LG ThinQ devices to Home Assistant. The features of this integration include: + +- Control LG appliances as Home Assistant entities through the [LG ThinQ Connect API](https://thinq.developer.lge.com/ko/cloud/). + +## Prerequisites + +- This feature works via LG ThinQ cloud. Therefore, an internet connection is required. +- A [personal access token](https://connect-pat.lgthinq.com) to use the [LG ThinQ Connect API](https://thinq.developer.lge.com/ko/cloud/). + +### Personal Access Token (PAT) + +1. Access the **[personal access token](https://connect-pat.lgthinq.com)** page (requires an LG ThinQ account). +2. Select **ADD NEW TOKEN**. +3. Enter a new token name and select the following authorized scopes: + - **Permission to view all devices** + - **Permission to view all device statuses** + - **All device control rights** + - **All device event subscription rights** + - **All device push notification permissions** +4. Select **CREATE TOKEN**. +5. Once all the steps are completed, you will see that a **PAT** has been generated. + +{% include integrations/config_flow.md %} + +1. Enter the information to use LG ThinQ Connect API: + - The **Token Value** obtained through the PAT issuance process. (Required) + - The entry name. +2. Choose the region (country). + +## Supported Devices + +### Appliance + +Support LG Appliances as follows: + +- [Air Conditioner](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/air-conditioner/) +- [Air Purifier](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/air-purifier/) +- [Ceiling Fan](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/ceiling-fan/) +- [Cooktop](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/cooktop/) +- [Dehumidifier](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/dehumidifier/) +- [Dishwasher](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/dish-washer/) +- [Dryer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/dryer/) +- [Home Brew](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/home-brew/) +- [Hood](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/hood/) +- [Kimchi Refrigerator](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/kimchi-refrigerator/) +- [Microwave Oven](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/microwave-oven/) +- [Oven](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/oven/) +- [Plant Cultivator](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/plant-cultivator/) +- [Refrigerator](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/refrigerator/) +- [Robot Cleaner](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/robot-cleaner/) +- [Stick Cleaner](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/Stick-Cleaner/) +- [Styler](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/styler/) +- [System Boiler](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/system-boiler/) +- [Washer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/washer/) +- [Water Heater](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/water-heater/) +- [Water Purifier](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/water-purifier/) +- [Wine Cellar](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/wine-cellar/) +{% note %} +Air Purifier Fan, Washtower Dryer, Washtower Washer, Humidifier, Washcombo Main and Washcombo Mini are also supported. +{% endnote %} + +## Platforms + +LG ThinQ represents devices as a set of [profiles](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/refrigerator/). And these are mapped to entities in Home Assistant. + +A list of all Entity Platforms provided by LG ThinQ Integration: + +- [Binary sensor](#binary-sensor) +- [Switch](#switch) + +### Binary sensor + +A read-only property which has only two states that can be toggled is represented as a binary sensor platform. + +| Device | Property | +| ------ | -------- | +| [Cooktop](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/Cooktop/)
[Dryer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/Dryer/)
[Oven](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/Oven/)
[Styler](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/styler/)
Washcombo Main
Washcombo Mini
[Washer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/washer/)
[Washtower Dryer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/WashTower-Dryer/)
[Washtower](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/WashTower-Single-Unit/)
[Washtower Washer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/WashTower-Washer/)
| Enable remote control | +| [Dish Washer](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/dish-washer/) | Rinse refill needed | +| [Refrigerator](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/refrigerator/) | Eco-friendly mode | +| | Power saving mode | +| | Enable Sabbath mode | +| [Wine Cellar](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/Wine-Cellar/) | Enable Sabbath mode | + +### Switch + +A read-wirte property which has only two states that can be toggled is represensted as a switch platform. + +| Device | Property | +| ------ | -------- | +| [Air Purifier Fan](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/Air-Purifier-Fan/) | Fan operation mode | +| [Air Purifier](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/air-purifier/) | Air purifier operation mode | +| [Dehumidifier](https://thinq.developer.lge.com/en/cloud/docs/thinq-connect/device-profile/dehumidifier/) | Dehumidifier operation mode | +| Humidifier | Humidifier operation mode | + +## Troubleshooting + +### Setup + +#### Aborted: The token is not valid + +This error occurs when the Personal Access Token (PAT) is invalid or entered incorrectly. Please visit the [Personal Access Token Page](https://d1jykc6oogauei.cloudfront.net/) page to check if your token is valid. + +#### Aborted: The country is not supported + +Check your PAT's valid country in the **Choose the region / Country** section. + +#### Error: The number of API calls has been exceeded + +This error occurs when there's an abnormal number of API calls made using the PAT. +The LG ThinQ integration will work properly after some time. + +## Debugging + +The LG ThinQ integration will show additional information by enabling log configuration. Add the line to your {% term "`configuration.yaml`" %}: +Don't forget to remove the line again once you are done debugging. + +```yaml +logger: + default: info + logs: + homeassistant.components.lg_thinq: debug +``` diff --git a/source/_integrations/manual.markdown b/source/_integrations/manual.markdown index 2d795a6fa995..e08e4c85ac3f 100644 --- a/source/_integrations/manual.markdown +++ b/source/_integrations/manual.markdown @@ -34,6 +34,10 @@ name: required: false type: string default: HA Alarm +unique_id: + description: Create a unique id for the entity. + required: false + type: string code: description: > If defined, specifies a code to enable or disable the alarm in the frontend. @@ -147,6 +151,7 @@ In the configuration example below: alarm_control_panel: - platform: manual name: Home Alarm + unique_id: a_very_unique_id code: "1234" arming_time: 30 delay_time: 20 diff --git a/source/_integrations/mastodon.markdown b/source/_integrations/mastodon.markdown index e90b1e3b70a6..40149c2e01e1 100644 --- a/source/_integrations/mastodon.markdown +++ b/source/_integrations/mastodon.markdown @@ -8,9 +8,11 @@ ha_codeowners: - '@fabaff' - '@andrew-codechimp' ha_domain: mastodon -ha_iot_class: Cloud Push +ha_iot_class: Cloud Polling ha_platforms: + - diagnostics - notify + - sensor ha_integration_type: service ha_config_flow: true --- @@ -24,6 +26,10 @@ If you want to grant only required accesses, uncheck all checkboxes then check o {% include integrations/config_flow.md %} +## Sensors + +The integration will create sensors for the Mastodon account showing total followers, following, and posts. + ## Notifications The integration will create a `notify` action matching the name of the integration entry. diff --git a/source/_integrations/motion_blinds.markdown b/source/_integrations/motion_blinds.markdown index 3bc415616108..14dd9a1d4113 100644 --- a/source/_integrations/motion_blinds.markdown +++ b/source/_integrations/motion_blinds.markdown @@ -10,6 +10,7 @@ ha_codeowners: - '@starkillerOG' ha_config_flow: true ha_platforms: + - button - cover - sensor ha_dhcp: true @@ -95,6 +96,12 @@ In the official Bloc Blinds app go to settings (three bars > gear icon), go to t Click the about page of the connector app 5 times to get the key ([iOS app](https://apps.apple.com/us/app/connector/id1344058317), [Android app](https://play.google.com/store/apps/details?id=com.smarthome.app.connector)). +## Favorite position + +A **Go to favorite position** button entity allows you to move the blind to its favorite position. For this entity to show up, you first need to set the blind's favorite position in the mobile app, using a remote or physical buttons on the blind. Refer to the manual of your specific blind for instructions. + +The **Set current position as favorite** button entity allows you to change the favorite position. For this to work, the blind first needs to be put in programming mode by shortly pressing the reset button on the blind. It will start stepping (moving a small bit up-down repeatedly). You can then use the **Set current position as favorite** entity. After you are done, shortly press the reset button again to exit the programming mode. + ## Top Down Bottom Up (TDBU) blinds TDBU blinds consist of two bars controlled by two motors designated by Top and Bottom with fabric in between. diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 139e0e52bb17..15ef81aa1fe5 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -119,6 +119,15 @@ MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things Your first step to get MQTT and Home Assistant working is to choose a broker. +The easiest option is to install the official Mosquitto Broker add-on. You can choose to set up and configure this add-on automatically when you set up the MQTT integration. Home Assistant will automatically generate and assign a safe username and password, and no further attention is required. This also works if you have already set up this add-on yourself in advance. +You can set up additional logins for your MQTT devices and services using the [Mosquitto add-on configuration](https://my.home-assistant.io/create-link/?redirect=supervisor_addon&addon=core_mosquitto). + +{% important %} +When MQTT is set up with the official Mosquitto MQTT broker add-on, the broker's credentials are generated and kept secret. If the official Mosquitto MQTT broker needs to be re-installed, make sure you save a copy of the add-on user options, like the additional logins. After re-installing the add-on, the MQTT integration will automatically update the new password for the re-installed broker. It will then reconnect automatically. +{% endimportant %} + + Alternatively, you can use a different MQTT broker that you configure yourself, ensuring it is compatible with Home Assistant. + ## Setting up a broker While public MQTT brokers are available, the easiest and most private option is running your own. @@ -1110,9 +1119,13 @@ The MQTT integration will register the `mqtt.publish` action, which allows publi | ---------------------- | -------- | ------------------------------------------------------------ | | `topic` | no | Topic to publish payload to. | | `payload` | no | Payload to publish. | +| `evaluate_payload` | yes | If a `bytes` literal in `payload` should be evaluated to publish raw data. (default: false)| | `qos` | yes | Quality of Service to use. (default: 0) | | `retain` | yes | If message should have the retain flag set. (default: false) | +{% note %} +When `payload` is rendered from [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) in a YAML script or automation, and the template renders to a `bytes` literal, the outgoing MQTT payload will only be sent as `raw` data, if the `evaluate_payload` option flag is set to `true`. +{% endnote %} {% important %} You must include either `topic` or `topic_template`, but not both. If providing a payload, you need to include either `payload` or `payload_template`, but not both. diff --git a/source/_integrations/nest.markdown b/source/_integrations/nest.markdown index a7dab2597476..10bfd6fb3b94 100644 --- a/source/_integrations/nest.markdown +++ b/source/_integrations/nest.markdown @@ -5,6 +5,7 @@ ha_category: - Camera - Climate - Doorbell + - Event - Hub - Media source - Sensor @@ -20,6 +21,7 @@ ha_platforms: - camera - climate - diagnostics + - event - sensor ha_integration_type: integration --- @@ -31,6 +33,7 @@ There is currently support for the following device types within Home Assistant: - [Climate](#climate) - [Sensor](#sensor) - [Camera](#camera) +- [Event](#event) Cameras and doorbells use [Automation and device triggers](#automation-and-device-triggers) for events and a [media source](#media-source) for capturing media images on supported devices. Other device types like Smoke and CO Alarms or Security systems are not currently supported by the SDM API. @@ -260,6 +263,8 @@ Home Assistant supports all SDM API features. However, every Camera or Doorbell - **RTSP**: These devices have an HLS stream served by the Home Assistant Core. These cameras support server-side `camera` actions like stream recording or image preview. See [Low Latency HLS](/integrations/stream#ll-hls) as a great option to enable to reduce stream latency. - **WebRTC**: These devices support direct browser to camera communication and a super low latency stream. A [Picture Glance Card](/dashboards/picture-glance/) can show the live stream in the grid with the *Camera View* set to `live` (not recommended for battery-powered cameras). `camera` actions like stream recording are *not supported*. +Given a camera named `Front Yard`, then the camera is created with a name such as `camera.front_yard`. + {% note %} This feature is enabled by the following permissions: @@ -269,10 +274,10 @@ This feature is enabled by the following permissions: {% endnote %} +All cameras also expose event entities for automation. Some camera models also +support capturing media (snapshots or clips) through device triggers. The table below summarizes the [supported SDM API features](https://developers.google.com/nest/device-access/supported-devices) for each device. -All cameras have motion and person triggers, however only some support capturing snapshots for events. The table below summarizes the [Supported SDM API features](https://developers.google.com/nest/device-access/supported-devices) for each device. - -| Device | Live Stream | Triggers / Events | Media Source
for Triggers / Events | +| Device | Live stream | Event entities / triggers | Media source
for triggers | | -------------------------------------------------------------------------------- | :---------------: | :--------------------------------: | :------------------------------------: | | Nest Cam (indoor, wired)
Nest Cam (outdoor, battery) | WebRTC | Motion
Person | N/A | | Nest Cam Indoor
Nest Cam IQ Indoor
Nest Cam IQ Outdoor
Nest Cam Outdoor | RTSP
Recording | Motion
Person
Sound | Snapshot (jpg) | @@ -282,13 +287,26 @@ All cameras have motion and person triggers, however only some support capturing | Nest Doorbell (wired, 2nd gen) | WebRTC | Motion
Person
Chime | Clip Preview (mp4, gif) | | Nest Hub Max | RTSP
Recording | Motion
Person
Sound
| Snapshot (jpg) | -Given a camera named `Front Yard` then the camera is created with a name such as `camera.front_yard`. +## Event + +All doorbells and cameras support event entities. See the [Event](https://www.home-assistant.io/integrations/event/) integration documentation for more about how to use event entities in automations. + +There are two classes of event entities that are available based on the above camera features: -## Automation and device triggers +- `motion` for cameras that support any of the event types `camera_motion`, `camera_person`, or `camera_sound` +- `doorbell` for all cameras that are doorbells and support `doorbell_chime` events + +Nest event entities are updated immediately when an event message is received +without waiting for any media to be fetched. See Device Triggers for media support. + +## Device Triggers The Nest integration provides [device triggers](/docs/automation/trigger/#device-triggers) to enable automation in Home Assistant. You should review the [Automating Home Assistant](/getting-started/automation/) getting started guide on automations or the [Automation](/docs/automation/) documentation for full details. +Device triggers will wait to fire after any media associated with the event is downloaded. Use an +event entity for immediate notifications without media. + {% my automations badge %} ![Screenshot Device Triggers](/images/integrations/nest/device_triggers.png) @@ -305,13 +323,18 @@ This is an example of what the `nest_event` payload looks like for a Device Trig "type": "doorbell_chime", "timestamp": "2022-01-26T04:56:54.031000+00:00", "nest_event_id": "EXAMPLE_EVENT_ID", + "attachment": { + "image": "/api/nest/event_media/DEVICE_ID/EVENT_ID/thumbnail", + "video": "/api/nest/event_media/DEVICE_ID/EVENT_ID", + } "zones": ["Zone 1"], }, } ``` - `device_id`: The Home Assistant device identifier for the camera -- `nest_event_id`: is an opaque identifier that can be used with the Media Source Attachments described below for supported cameras. +- `nest_event_id`: is an opaque identifier that identifies the event. +- `attachment`: May be present if the device supports snapshots or clips and depends on the device's capabilities. This is a URL where media can be fetched from the media source. - `zones`: Zones triggering the event if available. Zones are configured in the Google Home App, though not supported by all cameras. Events in the area outside of a named zone will be an empty zone name. {% enddetails %} @@ -327,7 +350,7 @@ This feature is enabled by the following permissions: - *Other permissions and notification settings in the Nest or Google Home apps*. {% endnote %} -### Google Home App Notification Settings +## Google Home App Notification Settings The Google Home App Notifications settings control not only which notifications are sent to your phone, but also what gets published to the Pub/Sub feed. @@ -346,7 +369,6 @@ If you are still not getting notifications, you can read this [troubleshooting g {% details "Google Home App Notification Settings" %} - | Google Home App Setting | Notes | | ------------------------ | :---------------------------------------------------------------------: | | Notifications: Push | Required for any detection event to be published | @@ -362,7 +384,7 @@ If you are still not getting notifications, you can read this [troubleshooting g The Nest [media source](/integrations/media_source) platform allows you to browse clips for recent camera events. Home Assistant is not intended to be a Network Video Recorder (NVR) platform, however, basic support for capturing recent events is supported. -The table above describes which devices support event image snapshots or 10-frame mp4 video clips for recent events. +The table above describes which devices support image snapshots or 10-frame mp4 video clips. ### Media Attachments @@ -372,7 +394,7 @@ The Media Source APIs can be used in [Companion App Attachments](https://compani - `/api/nest/event_media/DEVICE_ID/EVENT_ID/thumbnail`: A thumbnail preview of the media, which supports image snapshots (jpg) or clip previews (gif) depending on the camera type. -You can use the event payload fields `device_id` and `event_id` in an [automation](/getting-started/automation/) to send a notification from an [actions](/getting-started/automation-action/) as shown in the examples below. +You can use the Nest Device Trigger payload fields `attachment.image` or `attachment.video`in an [automation](/getting-started/automation/) to send a notification from an [actions](/getting-started/automation-action/) as shown in the examples below. {% details "Example Action: Clip Preview (mp4) attachment for iOS" %} @@ -386,10 +408,8 @@ data: message: Doorbell Pressed title: Someone pressed the doorbell data: - image: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }}/thumbnail - video: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }} + image: {{ trigger.event.data.attachment.image }} + video: {{ trigger.event.data.attachment.video }} mode: single ``` @@ -409,8 +429,7 @@ data: message: Doorbell Pressed title: Someone pressed the doorbell data: - image: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }}/thumbnail + image: {{ trigger.event.data.attachment.image }} ``` {% endraw %} @@ -429,8 +448,7 @@ data: message: Doorbell Pressed title: Someone pressed the doorbell data: - image: >- - /api/nest/event_media/{{ trigger.event.data.device_id }}/{{ trigger.event.data.nest_event_id }}/thumbnail + image: {{ trigger.event.data.attachment.image }} ``` {% endraw %} diff --git a/source/_integrations/nice_go.markdown b/source/_integrations/nice_go.markdown new file mode 100644 index 000000000000..b26348d53e43 --- /dev/null +++ b/source/_integrations/nice_go.markdown @@ -0,0 +1,46 @@ +--- +title: Nice G.O. +description: Control Nice G.O. garage doors +ha_release: '2024.9' +ha_category: + - Cover + - Event + - Light + - Switch +ha_iot_class: Cloud Push +ha_config_flow: true +ha_codeowners: + - '@IceBotYT' +ha_domain: nice_go +ha_platforms: + - cover + - diagnostics + - event + - light + - switch +ha_integration_type: integration +--- + +The **Nice G.O.** {% term integration %} lets you control Nice G.O. garage doors through Home Assistant. Device names in Home Assistant are generated based on the names defined in your Nice G.O. mobile app. + +## Prerequisites + +Make sure you have a working account with the Nice G.O. app and have your email and password ready. + +{% include integrations/config_flow.md %} + +## Cover + +Garage doors linked to your Nice G.O. account will appear as covers. + +## Event + +The barrier obstructed event entity will be triggered whenever the barrier gets obstructed. This could be triggered by anything that results in the closure being unsuccessful. This may include beam block during closure, beam block before closure, and an object in the way. + +## Light + +Lights on your garage door will appear as lights. + +## Switch + +A switch for turning vacation mode on and off will be made available for each device. Vacation mode prevents the operation of the door from physical control points such as a wall station, wireless keypad, remote control, or HomeLink. It can still be controlled from Home Assistant. diff --git a/source/_integrations/ollama.markdown b/source/_integrations/ollama.markdown index ec007662651a..a083e1e3ff01 100644 --- a/source/_integrations/ollama.markdown +++ b/source/_integrations/ollama.markdown @@ -38,6 +38,8 @@ Model: 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/). +Context window size: + description: "The context window size is the number of tokens the model can take as input. Home Assistant defaults to 8k, which is larger than the default value in Ollama Server (2k), and you may adjust it based on the maximum context size of the specific model used. A larger value will better support larger homes with more entities, and smaller values may lower Ollama server RAM usage." Max history messages: description: Maximum number of messages to keep for each conversation (0 = no limit). Limiting this value will cause older messages in a conversation to be dropped. diff --git a/source/_integrations/onvif.markdown b/source/_integrations/onvif.markdown index 84c90c7e3d2a..e7b73a3013ad 100644 --- a/source/_integrations/onvif.markdown +++ b/source/_integrations/onvif.markdown @@ -66,6 +66,7 @@ To help with development of this integration, enable `info` level logging for `h | Motion alarm | Binary sensor | Motion | Generic motion alarm. | | Field detection | Binary sensor | Motion | Polygonal field detection determines if each object in the scene is inside or outside the polygon. | | Cell motion detection | Binary sensor | Motion | Cell based motion detection determined by placing a grid over the video source and determining changes. | +| Human shape detection | Binary sensor | Motion | Detection of human shapes by on-camera recognition algorithm. | | Motion region detector | Binary sensor | Motion | Detects any motion against the specified motion region. The rule is configured for an area defined by a polygon. | | Detected sound | Binary sensor | Sound | Device detected sound. | | Digital input | Binary sensor | None | A digital input was triggered on the device. Amcrest is known to use this as a doorbell button press on the AD410. | diff --git a/source/_integrations/opentherm_gw.markdown b/source/_integrations/opentherm_gw.markdown index fa3d1c257edf..8f885180d46b 100644 --- a/source/_integrations/opentherm_gw.markdown +++ b/source/_integrations/opentherm_gw.markdown @@ -2,9 +2,11 @@ title: OpenTherm Gateway description: Control your OpenTherm Gateway from Home Assistant. ha_category: + - Button - Binary sensor - Climate - Hub + - Select - Sensor ha_release: 0.81 ha_iot_class: Local Push @@ -13,21 +15,18 @@ ha_codeowners: - '@mvn23' ha_domain: opentherm_gw ha_platforms: + - button - binary_sensor - climate + - select - sensor + - switch ha_integration_type: integration --- The `opentherm_gw` integration is used to control the [OpenTherm Gateway](https://otgw.tclcode.com/) from Home Assistant. -The following device types are currently supported within Home Assistant: - -- Binary sensor -- Climate -- Sensor - -This integration will add a single `climate` entity to Home Assistant for each configured gateway. Each gateway also has a collection of `sensor` and `binary_sensor` entities, which are disabled by default. These can be enabled from the `Devices` panel in the `Configuration` page of the web interface. +This integration will add three devices to Home Assistant for each configured gateway. The main control of the integration is a single `climate` entity which can be found on the added `OpenTherm Thermostat` device. All added devices have a collection of `sensor` and `binary_sensor` entities, which are disabled by default. To enable them, follow the steps on [enabling entities](/common-tasks/general/#enabling-or-disabling-entities). {% note %} The OpenTherm protocol is based on polling. The thermostat sends requests to the boiler at specific intervals. As a result, it may take some time for changes to propagate between Home Assistant and the thermostat. @@ -70,6 +69,16 @@ Floor Temperature: description: "Some thermostats round all temperatures down to the lower value according to their precision. Default behavior for Home Assistant is to round temperatures to the nearest value. Enable this setting to override this behavior and round to the lower value according to the configured precision." {% endconfiguration_basic %} +## Entities + +### Button + +The restart button on the `OpenTherm Gateway` device can be used to restart the OpenTherm Gateway. + +### Select + +Several `select` configuration entities can be found on the `OpenTherm Gateway` device. These can be used to configure the LEDs and GPIO pins of the OpenTherm Gateway. More information about the available modes can be found in the sections [LED modes](#led-modes) and [GPIO modes](#gpio-modes) or in the [commands documentation](https://otgw.tclcode.com/firmware.html#configuration) of the OpenTherm Gateway. + ## Actions ### Action `opentherm_gw.reset_gateway` @@ -222,315 +231,6 @@ Send a transparent [command](https://otgw.tclcode.com/firmware.html) to the Open | `transp_cmd` | no | The serial command to be sent to the OpenTherm Gateway. | | `transp_arg` | no | The serial command argument to be sent to the OpenTherm Gateway. | -## Sensors - -The following `sensor` entities will be created for each configured gateway. The `entity_id` of every sensor will have a suffix containing the data source (`boiler`, `gateway` or `thermostat`) and the `gateway_id` of the gateway to which it belongs. All `sensor` entities are disabled by default. -{% note %} -Not all boilers and thermostats properly support all OpenTherm features, so not all of the sensors will have useful values. -{% endnote %} - -- **burner_hours** - Boiler flame on time. - -- **burner_starts** - Number of burner starts. - -- **ch_pump_hours** - Central heating pump running time. - -- **ch_pump_starts** - Number of central heating pump starts. - -- **ch_water_pressure** - Central heating water pressure. - -- **ch_water_temp** - Central heating water temperature. - -- **ch_water_temp_2** - Central heating 2 water temperature. - -- **control_setpoint** - Central heating water target temperature. - -- **control_setpoint_2** - Central heating 2 water target temperature. - -- **cooling_control** - Cooling control signal value. - -- **dhw_burner_hours** - Hot water flame on time. - -- **dhw_burner_starts** - Number of hot water burner starts. - -- **dhw_flow_rate** - Hot water flow rate. - -- **dhw_pump_hours** - Hot water pump running time. - -- **dhw_pump_starts** - Number of hot water pump starts. - -- **dhw_setpoint** - Hot water target temperature. - -- **dhw_temp** - Hot water temperature. - -- **dhw_temp_2** - Hot water 2 temperature. - -- **exhaust_temp** - Boiler exhaust temperature. - -- **master_memberid** - Thermostat member ID. - -- **master_ot_version** - Thermostat OpenTherm protocol version. - -- **master_product_type** - Thermostat product type. - -- **master_product_version** - Thermostat product version. - -- **max_ch_setpoint** - Boiler maximum central heating water temperature. - -- **oem_diag** - OEM diagnostic information. - -- **otgw_about** - OpenTherm Gateway firmware version. - -- **otgw_build** - OpenTherm Gateway firmware build date and time. - -- **otgw_clockmhz** - OpenTherm Gateway firmware design clock speed. - -- **otgw_dhw_ovrd** - OpenTherm Gateway hot water override status. - -- **otgw_gpio_a** - OpenTherm Gateway GPIO port A operating mode. - -- **otgw_gpio_b** - OpenTherm Gateway GPIO port B operating mode. - -- **otgw_led_a** - OpenTherm Gateway LED A operating mode. - -- **otgw_led_b** - OpenTherm Gateway LED B operating mode. - -- **otgw_led_c** - OpenTherm Gateway LED C operating mode. - -- **otgw_led_d** - OpenTherm Gateway LED D operating mode. - -- **otgw_led_e** - OpenTherm Gateway LED E operating mode. - -- **otgw_led_f** - OpenTherm Gateway LED F operating mode. - -- **otgw_mode** - OpenTherm Gateway operating mode. - -- **otgw_setback_temp** - OpenTherm Gateway setback temperature for `away mode`. - -- **otgw_setpoint_ovrd_mode** - OpenTherm Gateway central heating setpoint override mode. - -- **otgw_smart_pwr** - OpenTherm Gateway smart power operating mode. - -- **otgw_thermostat_detect** - OpenTherm Gateway automatic thermostat detection status. - -- **otgw_vref** - OpenTherm Gateway voltage reference setting. - -- **outside_temp** - Outside temperature as reported in the OpenTherm protocol. - -- **relative_mod_level** - Relative modulation level. - -- **return_water_temp** - Boiler return water temperature. - -- **room_setpoint** - Room target temperature. - -- **room_setpoint_2** - Room 2 target temperature. - -- **room_setpoint_ovrd** - Room target temperature override value. - -- **room_temp** - Current room temperature. - -- **slave_ch_max_setp** - Maximum boiler supported central heating water target temperature. - -- **slave_ch_min_setp** - Minimum boiler supported central heating water target temperature. - -- **slave_dhw_max_setp** - Maximum boiler supported hot water target temperature. - -- **slave_dhw_min_setp** - Minimum boiler supported hot water target temperature. - -- **slave_max_capacity** - Maximum boiler capacity. - -- **slave_max_relative_modulation** - Maximum boiler supported relative modulation. - -- **slave_memberid** - Boiler member ID. - -- **slave_min_mod_level** - Minimum boiler supported modulation level. - -- **slave_oem_fault** - Boiler OEM fault indication. - -- **slave_ot_version** - Boiler OpenTherm protocol version. - -- **slave_product_type** - Boiler product type. - -- **slave_product_version** - Boiler product version. - -- **solar_coll_temp** - Solar collector temperature. - -- **solar_storage_temp** - Solar storage unit temperature. - - -## Binary sensors - -The following `binary_sensor` entities will be created for each configured gateway. The `entity_id` of every sensor will have a suffix containing the data source (`boiler`, `gateway` or `thermostat`) and the `gateway_id` of the gateway to which it belongs. All `binary_sensor` entities are disabled by default. -{% note %} -Not all boilers and thermostats properly support all OpenTherm features, so not all of the sensors will have useful values. -{% endnote %} - -- **master_ch2_enabled** - Thermostat requests central heating 2 on. - -- **master_ch_enabled** - Thermostat requests central heating on. - -- **master_cooling_enabled** - Thermostat requests cooling. - -- **master_dhw_enabled** - Thermostat requests hot water to be heated. - -- **master_otc_enabled** - Thermostat is using outside temperature correction. - -- **otgw_gpio_a_state** - OpenTherm Gateway GPIO A state. - -- **otgw_gpio_b_state** - OpenTherm Gateway GPIO B state. - -- **otgw_ignore_transitions** - OpenTherm Gateway ignores ripples in the signal during high/low transitions. - -- **otgw_ovrd_high_byte** - OpenTherm Gateway overrides high byte with message ID 100. - -- **remote_rw_dhw** - Boiler supports writing hot water setpoint. - -- **remote_rw_max_ch** - Boiler supports writing maximum central heating setpoint. - -- **remote_transfer_dhw** - Boiler supports reading hot water setpoint. - -- **remote_transfer_max_ch** - Boiler supports reading maximum central heating setpoint. - -- **rovrd_auto_prio** - Programmed room setpoint change takes priority over remote override setting. - -- **rovrd_man_prio** - Manual room setpoint change takes priority over remote override setting. - -- **slave_air_pressure_fault** - Boiler reports air pressure fault. - -- **slave_ch2_active** - Boiler reports central heating 2 active. - -- **slave_ch2_present** - Boiler has a central heating 2 circuit. - -- **slave_ch_active** - Boiler reports central heating active. - -- **slave_control_type** - Boiler control type ('off' is modulating, 'on' is on/off). - -- **slave_cooling_active** - Boiler reports cooling active. - -- **slave_cooling_supported** - Boiler supports cooling. - -- **slave_dhw_active** - Boiler reports hot water active. - -- **slave_dhw_config** - Boiler hot water mode ('off' is instantaneous or unspecified, 'on' is storage tank). - -- **slave_dhw_present** - Boiler reports hot water present. - -- **slave_diagnostic_indication** - Boiler diagnostic indication. - -- **slave_fault_indication** - Boiler fault indication. - -- **slave_flame_on** - Boiler reports flame on. - -- **slave_gas_fault** - Boiler reports gas fault. - -- **slave_low_water_pressure** - Boiler reports low water pressure. - -- **slave_master_low_off_pump** - Boiler supports low-off and pump control commands (this sensor is inverted, 'on' is not supported, 'off' is supported) - -- **slave_remote_reset** - Boiler reports 'lockout-reset' supported. - -- **slave_service_required** - Boiler reports service required. - -- **slave_water_overtemp** - Boiler reports water overtemperature. - ## GPIO modes Possible modes and their meaning for the GPIO pins are listed here: @@ -563,3 +263,11 @@ Possible LED modes and their meaning are listed here: - E. Transmission error has been detected. - M. Boiler requires maintenance. - P. Raised power mode active on thermostat interface. + +## Disabled configuration entities + +{% warning %} +Please read [this information](http://otgw.tclcode.com/standalone.html) from the designer of the OpenTherm Gateway before considering using the information in this section. +{% endwarning %} +For advanced control of your heating system, some `switch` configuration entities can be found on the added `OpenTherm Gateway` device. +These entities are disabled by default, as they can cause your heating system to run continuously and/or increase your energy consumption significantly if used improperly. In most setups, these entities are not needed and should be left disabled. diff --git a/source/_integrations/opower.markdown b/source/_integrations/opower.markdown index 6979a117aee1..9d4f620ac7c0 100644 --- a/source/_integrations/opower.markdown +++ b/source/_integrations/opower.markdown @@ -41,6 +41,7 @@ More than 175 utilities use Opower. Currently only the following utilities are s - PECO Energy Company (PECO) - Potomac Electric Power Company (Pepco) - Mercury NZ Limited +- National Grid NY Upstate - Pacific Gas & Electric (PG&E) - Portland General Electric (PGE) - Puget Sound Energy (PSE) diff --git a/source/_integrations/plex.markdown b/source/_integrations/plex.markdown index 8359925364b9..8951117cd3af 100644 --- a/source/_integrations/plex.markdown +++ b/source/_integrations/plex.markdown @@ -160,6 +160,7 @@ Required fields within the `media_content_id` payloads are marked as such, other - `resume`: Resumes playback at the last partially watched position if available, otherwise plays at the beginning. - `offset`: The desired playback start position in seconds. - `allow_multiple`: A search must find one specific item to succeed. This parameter accepts multiple matches in a search and enqueues all found items for playback. Accepts `1` or `true` to enable. +- `username`: A username for a local Plex user account. This is only required if the Plex server has multiple users and you wish to play media for a specific user. Simplified examples are provided for [music](#music), [TV episodes](#tv-episode), and [movies](#movie). See [advanced searches](#advanced-searches) for complex/smart search capabilities. diff --git a/source/_integrations/prometheus.markdown b/source/_integrations/prometheus.markdown index d4c88d886554..8fa1bb1287f5 100644 --- a/source/_integrations/prometheus.markdown +++ b/source/_integrations/prometheus.markdown @@ -209,4 +209,4 @@ For example: Metrics are exported only for the following domains: -`automation`, `binary_sensor`, `climate`, `cover`, `counter`, `device_tracker`, `fan`, `humidifier`, `input_boolean`, `input_number`, `light`, `lock`, `number`, `person`, `sensor`, `update`, `switch` +`alarm_control_panel`, `automation`, `binary_sensor`, `climate`, `cover`, `counter`, `device_tracker`, `fan`, `humidifier`, `input_boolean`, `input_number`, `light`, `lock`, `number`, `person`, `sensor`, `switch`, `update` diff --git a/source/_integrations/reolink.markdown b/source/_integrations/reolink.markdown index cac2c1e41837..f83326a20440 100644 --- a/source/_integrations/reolink.markdown +++ b/source/_integrations/reolink.markdown @@ -177,6 +177,15 @@ Depending on the supported features of the camera, select entities are added for **Play quick reply messages**/**Auto quick reply messages** can be recorded in the Reolink phone app where a name is also supplied. New or updated quick reply messages will be loaded into Home Assistant at the start of the integration. When adding new quick reply messages, please restart the Reolink integration. +### Action reolink.play_chime + +To play a ringtone on a Reolink chime, the `reolink.play_chime` action can be used. + +| Data attribute | Optional | Description | +| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `device_id` | no | List of device ids of the Reolink Chimes to control. For example, `- 12a34b56c7d8ef9ghijklm0n1op2345q`. | +| `ringtone` | no | The ringtone to play. For example `operetta`. | + ## Siren entities If the camera supports a siren, a siren entity will be created. diff --git a/source/_integrations/ring.markdown b/source/_integrations/ring.markdown index beede8e2c26b..f29068051c1e 100644 --- a/source/_integrations/ring.markdown +++ b/source/_integrations/ring.markdown @@ -6,6 +6,7 @@ ha_category: - Button - Camera - Doorbell + - Event - Light - Sensor - Switch @@ -20,6 +21,7 @@ ha_platforms: - button - camera - diagnostics + - event - light - sensor - siren @@ -49,7 +51,9 @@ This integration does NOT allow for live viewing of your Ring camera within Home ## Binary sensor -Once you have enabled the [Ring integration](/integrations/ring), you can start using a binary sensor. Currently, it supports doorbell, external chimes and stickup cameras. +The binary sensor switches off and on when motion, doorbell rings, and intercom unlock events occur. + +The binary sensor is being replaced with the event entity, and you should migrate any automations to the event entity by release 2025.4.0. ## Button @@ -132,6 +136,20 @@ data = { hass.services.call("downloader", "download_file", data) ``` +## Event + +The event entity captures events like doorbell rings, motion alerts, and intercom unlocking. + +### Realtime event stability + +If you are experiencing issues with receiving ring alerts, the reason could be that you have too many authenticated devices on your ring account. +Prior to version 2023.12.0, the Home Assistant ring integration would register a new entry in `Authorized Client Devices` in the `Control Centre` at [ring.com](https://account.ring.com/account/control-center/authorized-devices) every time it restarted. +If you have been using the ring integration before this, you may have many `Authorized Client Devices` in the `Control Centre` on [ring.com](https://account.ring.com/account/control-center/authorized-devices). +This can cause issues receiving ring alerts. +You should delete all authorised devices from [ring.com](https://account.ring.com/account/control-center/authorized-devices) `Control Centre` which are from Home Assistant +(i.e. do not delete those named `iPhone` or `Android`; Home Assistant authorized devices are named `ring-doorbell:HomeAssistant/something` or `Python`). +If you have too many `Authorised Client Devices` to delete them individually, it might be easier to `Remove all devices` and then re-authorize your required devices. + ## Sensor Once you have enabled the [Ring integration](/integrations/ring), you can start using the sensor platform. Currently, it supports doorbell, external chimes and stickup cameras. diff --git a/source/_integrations/ruckus_unleashed.markdown b/source/_integrations/ruckus_unleashed.markdown index 0cadb84fcfa5..a6a9c22dcba0 100644 --- a/source/_integrations/ruckus_unleashed.markdown +++ b/source/_integrations/ruckus_unleashed.markdown @@ -1,6 +1,6 @@ --- -title: Ruckus Unleashed -description: Instructions on how to integrate your Ruckus Unleashed device into Home Assistant. +title: Ruckus +description: Instructions on how to integrate your Ruckus Networks device into Home Assistant. ha_category: - Presence detection ha_release: 0.117 @@ -16,38 +16,52 @@ ha_platforms: ha_integration_type: hub --- -This platform allows you to connect to a [Ruckus Unleashed](https://support.ruckuswireless.com/product_families/19-ruckus-unleashed) access point. +This platform allows you to connect to [Ruckus](https://www.ruckusnetworks.com/) access points. + +[Ruckus Unleashed](https://www.ruckusnetworks.com/products/network-control-and-management/controller-less/), +[Ruckus ZoneDirector](https://support.ruckuswireless.com/products/73), +[Ruckus SmartZone](https://www.ruckusnetworks.com/products/network-control-and-management/network-controllers/), +and [Ruckus One](https://www.ruckusnetworks.com/products/network-control-and-management/cloud-managed/) +access points are supported. Access points running Standalone/Solo firmware are not supported. There is currently support for the following device types within Home Assistant: -- **Presence detection** - The platform will look at devices connected to the access point and will create a `device_tracker` for each discovered device. +- **Presence detection** - The platform will look at devices connected to the access point and will +create a `device_tracker` for each discovered device. -## Configuration +## Prerequisites -To add a Ruckus Unleashed device to your installation, go to **Settings** -> **Devices & services**, click the `+` button, then select **Ruckus** from the list of integrations. +- **IP address / hostname**, **Username** and **Password** which you use to connect + to your Ruckus controller's web dashboard. -It is required to configure the IP address of your **master access point**. See the section Access Points on the management web interface. And perhaps consider to set a preferred master (Admin & Services>System>System Info>Preferred master). -You will have to create a user on the device which is a **Monitoring Admin**. Login to the Ruckus Unleashed admin UI and follow these steps: +### Ruckus Unleashed - - [Create a new role](https://docs.ruckuswireless.com/unleashed/200.1.9.12/t-ConfigUserRoles.html). - - Check **Allow Unleashed Administration**. - - Select the **Monitoring Admin (Monitoring and viewing operation status only)** radio button. - - [Create a new user](https://docs.ruckuswireless.com/unleashed/200.1.9.12/t-AddingNewUsersInternal.html) with the new role. +You may enter the **IP address / hostname** of any access point as the Host. +If you've configured an Unleashed Management Interface, then use this instead. -## Troubleshooting +### Ruckus One + +You'll need to use your Ruckus One dashboard to create an Application Token. Go to the bottom of the +**Administration** > **Settings** screen and select the **Add Token** link. Choose any +**Application Name**, for example `Home Assistant`. The **Token Scope** can be **Read Only**. + +When Home Assistant prompts for Ruckus connection details, use the full URL of a Ruckus One +dashboard page as the Host (such as `https://asia.ruckus.cloud/5dd1000334cc2a01fcf28a740a6c95cf/t/dashboard`), +your Token **Client ID** as the Username & your Token **Shared Secret** as the Password. -For this platform to work, the Ruckus Unleashed device will need to be accessible over SSH. If you are having trouble with Home Assistant not connecting, make sure the user you created above can log in to SSH and can run privileged commands. +{% include integrations/config_flow.md %} -Terminal: +## Limitations -```bash -ssh +This integration is not currently suitable for large multi-venue SmartZone or Ruckus One networks: there +is no way to filter devices by Venue or Zone. + +If you've configured your access points with an extended Client Inactivity Timeout, then this is how long +you'll need to wait for devices to be detected as `not_home`. + +## Troubleshooting -Please login: -Password: -Welcome to Ruckus Unleashed Network Command Line Interface -ruckus> enable -ruckus# exit -Exit ruckus CLI. -``` +For this platform to work, the Ruckus controller or Unleashed AP will need to be accessible over HTTPS. +If you are having trouble with Home Assistant not connecting, make sure the user you have specified +can log in to the web dashboard and view AP, WLAN, and Client information. diff --git a/source/_integrations/russound_rio.markdown b/source/_integrations/russound_rio.markdown index c9fd3113135e..868f0f6aebf5 100644 --- a/source/_integrations/russound_rio.markdown +++ b/source/_integrations/russound_rio.markdown @@ -6,6 +6,7 @@ ha_category: ha_release: 0.49 ha_iot_class: Local Push ha_domain: russound_rio +ha_quality_scale: silver ha_platforms: - media_player ha_codeowners: diff --git a/source/_integrations/sensor.markdown b/source/_integrations/sensor.markdown index 83c1b091accd..ee3f98d9f5f9 100644 --- a/source/_integrations/sensor.markdown +++ b/source/_integrations/sensor.markdown @@ -46,8 +46,8 @@ The following device classes are supported for sensors: - **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, MWh, MJ, or GJ -- **energy_storage**: Stored energy in Wh, kWh, MWh, MJ, or GJ +- **energy**: Energy in J, kJ, MJ, GJ, Wh, kWh, MWh, cal, kcal, Mcal, or Gcal +- **energy_storage**: Stored energy in J, kJ, MJ, GJ, Wh, kWh, MWh, cal, kcal, Mcal, or Gcal - **enum**: Has a limited set of (non-numeric) states - **frequency**: Frequency in Hz, kHz, MHz, or GHz - **gas**: Gasvolume in m³, ft³ or CCF diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown index e3e517d5a0f5..7e0d60f4ea83 100644 --- a/source/_integrations/sensor.mqtt.markdown +++ b/source/_integrations/sensor.mqtt.markdown @@ -165,6 +165,10 @@ object_id: description: Used instead of `name` for automatic generation of `entity_id` required: false type: string +options: + description: List of allowed sensor state value. An empty list is not allowed. The sensor's `device_class` should be set to `enum`. Cannot be used together with `state_class` or `unit_of_measurement`. + required: false + type: list payload_available: description: The payload that represents the available state. required: false diff --git a/source/_integrations/sensoterra.markdown b/source/_integrations/sensoterra.markdown new file mode 100644 index 000000000000..49ba117663ab --- /dev/null +++ b/source/_integrations/sensoterra.markdown @@ -0,0 +1,35 @@ +--- +title: Sensoterra +description: Instructions on how to integrate your Sensoterra probes with Home Assistant. +ha_release: 2024.10 +ha_category: + - Sensor +ha_iot_class: Cloud Poll +ha_config_flow: true +ha_domain: sensoterra +ha_platforms: + - sensor +ha_codeowners: + - '@markruys' +ha_integration_type: integration +--- + +This {% term integration %} communicates with your [Sensoterra](https://sensoterra.com) soil moisture probes using the public [Sensoterra Customer API](https://monitor.sensoterra.com/api/v3/) via HTTPS. + +## Prerequisites + +Soil moisture probes can be purchased at Sensoterra.com. Create a free account in the Sensoterra app and register your probes. The Sensoterra Home Assistant integration needs your credentials to obtain a token to access your probe data. + +{% include integrations/config_flow.md %} + +## Sensors + +The integration provides the following sensors for each probe: + +- Soil moisture (either in volumetric-% or in SI) +- Temperature (in degrees Celsius) +- LoRaWAN signal strength (RSSI level) +- Battery level (100, 50 or 10% approximations) +- Last seen timestamp + +Typically, soil moisture probes measure once an hour. The Home Assistant integration polls this data every 15 minutes. diff --git a/source/_integrations/seventeentrack.markdown b/source/_integrations/seventeentrack.markdown index c8308a9ee8ee..d53ee73c9066 100644 --- a/source/_integrations/seventeentrack.markdown +++ b/source/_integrations/seventeentrack.markdown @@ -79,7 +79,6 @@ content: > The `seventeentrack.get_packages` action allows you to query the 17track API for the latest package data. - | Data attribute | Optional | Description | |------------------------|----------|---------------------------------------------| | `config_entry_id` | No | The ID of the 17Track service config entry. | @@ -92,3 +91,20 @@ The `seventeentrack.get_packages` action allows you to query the 17track API for config_entry_id: 2b4be47a1fa7c3764f14cf756dc98991 package_state: ["Delivered", "In transit"] ``` + +### Action `seventeentrack.archive_package` + +The `seventeentrack.archive_package` action allows you to archive a package using the 17track API. + +| Data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------| +| `config_entry_id` | No | The ID of the 17Track service config entry. | +| `package_tracking_number` | No | The package tracking number. | + +```yaml +# Example automation action to archive a package with a tracking number +- action: seventeentrack.archive_package + data: + config_entry_id: 2b4be47a1fa7c3764f14cf756dc98991 + package_tracking_number: RU0103445624A +``` diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index 5286adc46ba1..9d2197ee8c1c 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -73,7 +73,7 @@ The list below will help you diagnose and fix the problem: ## Shelly device configuration (generation 2 and 3) -Generation 2 and 3 devices use the `RPC` protocol to communicate with the integration. **Battery operated devices** (even if USB connected) need manual outbound WebSocket configuration, Navigate to the local IP address of your Shelly device, **Settings** >> **Connectivity** >> **Outbound WebSocket** and check the box **Enable Outbound WebSocket**, under server enter the following address: +Generation 2 and 3 devices use the `RPC` protocol to communicate with the integration. **Battery-operated devices** (even if USB connected) may need manual outbound WebSocket configuration if Home Assistant cannot correctly determine your instance's internal URL or the outbound WebSocket was previously configured for a different Home Assistant instance. In this case, navigate to the local IP address of your Shelly device, **Settings** >> **Connectivity** >> **Outbound WebSocket** and check the box **Enable Outbound WebSocket**, under server enter the following address: `ws://` + `Home_Assistant_local_ip_address:Port` + `/api/shelly/ws` (for example: `ws://192.168.1.100:8123/api/shelly/ws`), click **Apply** to save the settings. In case your installation is set up to use SSL encryption (HTTP**S** with certificate), an additional `s` needs to be added to the WebSocket protocol, too, so that it reads `wss://` (for example: `wss://192.168.1.100:8123/api/shelly/ws`). diff --git a/source/_integrations/simplefin.markdown b/source/_integrations/simplefin.markdown index 01df36cce232..20f2f6ef5f18 100644 --- a/source/_integrations/simplefin.markdown +++ b/source/_integrations/simplefin.markdown @@ -31,5 +31,6 @@ Each `account` will be set up as a device in Home Assistant, and it will contain |Sensor|Description| |-------|---------------| -|Balance|Account balance| |Age| This sensor shows when the data was retrieved by the SimpleFin API | +|Balance|Account balance| +|Problem| Binary sensor that indicates whether the account sync may have a problem | diff --git a/source/_integrations/smartthings.markdown b/source/_integrations/smartthings.markdown index 102a4dec54d7..e321f44135e9 100644 --- a/source/_integrations/smartthings.markdown +++ b/source/_integrations/smartthings.markdown @@ -171,7 +171,6 @@ For a SmartThings thermostat to be represented by the climate platform, it must | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [`thermostat`](https://developer.smartthings.com/docs/devices/capabilities/deprecated#thermostat) (set a) | `hvac mode`, `hvac action`, `target temp high`, `target temp low` and `fan mode` | | [`thermostatMode`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#thermostatMode) (set b) | `hvac mode` | -| [`thermostatCoolingSetpoint`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#thermostatCoolingSetpoint) (seb b) | `target temp low` | | [`thermostatHeatingSetpoint`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#thermostatHeatingSetpoint) (set b) | `target temp high` | | [`temperatureMeasurement`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#temperatureMeasurement) (set b) | | [`thermostatOperatingState`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#thermostatOperatingState) | `hvac action` | diff --git a/source/_integrations/smlight.markdown b/source/_integrations/smlight.markdown new file mode 100644 index 000000000000..fec30ece6f43 --- /dev/null +++ b/source/_integrations/smlight.markdown @@ -0,0 +1,64 @@ +--- +title: SMLIGHT SLZB +description: The SMLIGHT SLZB integration allows users to monitor and manage their SMLIGHT SLZB-06x devices from directly within Home Assistant. +ha_category: + - Sensor +ha_release: 2024.9 +ha_iot_class: Local Polling +ha_config_flow: true +ha_domain: smlight +ha_zeroconf: true +ha_platforms: + - button + - sensor +ha_codeowners: + - '@tl-sl' +ha_integration_type: device +--- + +The [SMLIGHT](https://smlight.tech) SLZB-06x Ethernet Zigbee coordinators +provide a convenient way to add Zigbee to your smart home setup. + +The **SMLIGHT SLZB** {% term integration %} allows users to monitor and manage their SLZB-06x devices +directly from within Home Assistant and to directly access many of the +features found in the SMLIGHT web UI. You can also use these in your automations. + +## Prerequisites + +You need a supported SLZB-06 adapter. + + This integration has been tested with the following devices: + +- [SLZB-06](https://smlight.tech/product/slzb-06) +- [SLZB-06M](https://smlight.tech/product/slzb-06m) +- [SLZB-06p7](https://smlight.tech/product/slzb-06p7) +- [SLZB-06p10](https://smlight.tech/product/slzb-06p10/) + +{% include integrations/config_flow.md %} + +## Integration entities + +The following sensors will be created: + +- **Core Temperature** - Temperature of core ESP32 +- **Zigbee Temperature** - Temperature of Zigbee CC2652 or EFR32 chip +- **Core Uptime** - Uptime of Core device +- **Zigbee Uptime** - Uptime of Zigbee connection to ZHA/Z2M +- **RAM Usage** - Monitor RAM Usage +- **FS Usage** - Monitor filesystem usage +- **Ethernet** - Ethernet connection status +- **Wi-Fi** - Wi-Fi connection status + +The following buttons will be created: + +- **Core restart** - Restart core ESP32 +- **Zigbee restart** - Restart Zigbee CCCC2652 or EFR32 chip +- **Zigbee flash mode** - Trigger the Zigbee chip into bootloader flash mode so it can be flashed. It is possible to flash Zigbee firmware over a network socket once this is activated. + +### Switches + +The following switches will be created: + +- **Disable LEDs** - Disable all LEDs on the SLZB-06x device. +- **LED night mode** - Enables night mode, which turns off the LEDs overnight, based on the times set in SLZB-06x web UI. +- **Auto Zigbee update** - This allows the core firmware on SLZB-06x to manage Zigbee firmware updates and it will automatically install updates when they are released. diff --git a/source/_integrations/solarlog.markdown b/source/_integrations/solarlog.markdown index d5772baf68f9..26681476f679 100644 --- a/source/_integrations/solarlog.markdown +++ b/source/_integrations/solarlog.markdown @@ -24,7 +24,7 @@ When activating the interface, a red warning triangle with security information The `solarlog` integration uses the default host address "http://solar-log" if you don't specify a host. If your device isn't accessible on this address, use its IP Address instead. {% important %} -The open JSON interface is deactivated by default. To activate the open JSON interface, a user password must first be set. The password isn't needed for accessing the open JSON interface. +The open JSON interface is deactivated by default. To activate the open JSON interface, a user password should be set for security purposes. The password isn't needed for accessing the open JSON interface. {% endimportant %} {% include integrations/config_flow.md %} @@ -75,6 +75,27 @@ The following sensors are available in the library: | power_available | W | Available power (equals to power_ac - consumption_ac) | | usage | % | Usage (equals to consumption_ac / power_ac) | +## Additional data + +{% important %} +The additional data is only accessible if the user's password protection is deactivated. Obviously, deactivating password protection is a security risk and should only be done in specific circumstances. In any event, you do this at your own risk. +{% endimportant %} + +You can get additional data from the Solar-Log device. To enable this, select the checkbox for extended data in the integration's system options. + +The following additional sensor becomes available: + +| Name | Unit | Description | +|-----------------------|--------|:-------------------------------------------| +| self_consumption_year | kWh | Annual self-consumed solar power. | + +In addition, information from devices connected to the Solar-Log device becomes available. The following additional sensors become available (all values are per inverter/device): + +| Name | Unit | Description | +|-----------------------|--------|:-------------------------------------------| +| current_power | W | Current power provided/used by the device. | +| consumption_year | kWh | Total energy provided/used by the device. | + {% note %} The solarlog integration is using the solarlog_cli pypi package to get the data from your Solar-Log device. The last five sensors are not reported by your Solar-Log device directly, but are computed by the library. {% endnote %} diff --git a/source/_integrations/sonos.markdown b/source/_integrations/sonos.markdown index b86a2ff98018..5a5e439eea01 100644 --- a/source/_integrations/sonos.markdown +++ b/source/_integrations/sonos.markdown @@ -342,6 +342,47 @@ Force start playing the queue, allows switching from another stream (such as rad | `entity_id` | yes | String or list of `entity_id`s that will start playing. It must be the coordinator if targeting a group. | `queue_position` | yes | Position of the song in the queue to start playing from, starts at 0. +### Action `sonos.get_queue` + +Returns the media_players queue. + +| Data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | media_player entity id. | + +This example script does the following: get the queue, loop through in reverse order, and remove media containing the words "holiday". + +{% raw %} + +```yaml + - action: sonos.get_queue + target: + entity_id: media_player.living_room + response_variable: queue + - variables: + queue_len: '{{ queue["media_player.living_room"] | length }}' + - repeat: + sequence: + - variables: + title: '{{ queue["media_player.living_room"][queue_len - repeat.index]["media_title"].lower() }}' + album: '{{ queue["media_player.living_room"][queue_len - repeat.index]["media_album_name"].lower() }}' + position: '{{ queue_len - repeat.index }}' + - if: + - '{{ "holiday" in title or "holiday" in album }}' + then: + - action: sonos.remove_from_queue + target: + entity_id: media_player.living_room + data: + queue_position: '{{position}}' + until: + - condition: template + value_template: '{{queue_len == repeat.index}}' + +``` + +{% endraw %} + ### Action `sonos.remove_from_queue` Removes an item from the queue. diff --git a/source/_integrations/squeezebox.markdown b/source/_integrations/squeezebox.markdown index 112e3bc75423..884a2cdb60c2 100644 --- a/source/_integrations/squeezebox.markdown +++ b/source/_integrations/squeezebox.markdown @@ -1,6 +1,6 @@ --- title: Squeezebox (Lyrion Music Server) -description: Instructions on how to integrate a Squeezebox player into Home Assistant. +description: Instructions on how to integrate Squeezebox players and a Lyrion Music Server (LMS) into Home Assistant. ha_category: - Media player ha_release: pre 0.7 @@ -12,10 +12,14 @@ ha_config_flow: true ha_dhcp: true ha_platforms: - media_player + - binary_sensor + - sensor ha_integration_type: integration --- -The Squeezebox integration allows you to control music players from the [Lyrion Music Server](https://lyrion.org/) (LMS) ecosystem. Lyrion Music Server was previously known as [Logitech Media Server](https://en.wikipedia.org/wiki/Squeezebox_%28network_music_player%29). +The Squeezebox integration allows you to control music players from the [Lyrion Music Server](https://lyrion.org/) (LMS) ecosystem. Lyrion Music Server was formerly known as [Logitech Media Server](https://en.wikipedia.org/wiki/Squeezebox_%28network_music_player%29). + +This integration provides both media players connected to the server and supporting binary sensors for the server status. The Squeezebox music player ecosystem, which can be controlled through this integration, includes hardware audio players from Logitech, including [Squeezebox 3rd Generation, Squeezebox Boom, Squeezebox Receiver, Transporter, Squeezebox2, Squeezebox and SLIMP3](https://lms-community.github.io/players-and-controllers/hardware-comparison/), and many software emulators like [Squeezelite, SqueezeSlave, SoftSqueeze and SqueezePlay](https://sourceforge.net/projects/lmsclients/files/). @@ -46,6 +50,26 @@ transporter_toslink: media_content_type: "music" ``` +## Entities + +### Binary sensors + +- **Needs restart**: Server Service needs to be restarted (typically, this is needed to apply updates). +- **Library rescan**: The music library is currently being scanned by LMS (depending on the type of scan, some content may be unavailable). + +### Sensors + +- **Last scan**: Date of the last library scan. +- **Player count**: Number of players on the service. +- **Player count off service**: Number of players not on this service. +- **Total albums**: Total number of albums currently available in the service. +- **Total artists**: Total number of artists currently available in the service. +- **Total duration**: Duration of all tracks in service (HHHH:MM:SS). +- **Total genres**: Total number of genres used in current service. +- **Total songs**: Total number of music files currently in service. + +## Actions + ### Action `call_method` Call a custom Squeezebox JSON-RPC API. diff --git a/source/_integrations/swiss_public_transport.markdown b/source/_integrations/swiss_public_transport.markdown index 34e519329110..66fd5b8d984b 100644 --- a/source/_integrations/swiss_public_transport.markdown +++ b/source/_integrations/swiss_public_transport.markdown @@ -41,6 +41,21 @@ name: The public timetables are coming from [Swiss public transport](https://transport.opendata.ch/). -### Defining a custom polling interval +## Actions + +The Swiss public transport integration has the following action: + +- `swiss_public_transport.fetch_connections` + +### Action `swiss_public_transport.fetch_connections` + +Fetch the connections for a specific instance. + +| Data attribute | Optional | Description | +|------------------------|----------|----------------------------------------------------------| +| `config_entry_id` | No | The ID of the Swiss public transport config entry to get data from. For example, in YAML: `config_entry_id: zurich_geneva` or in UI `Instance: zurich_geneva`)| +| `limit` | Yes | The number of connections to fetch. (default: 3, range: [1,15])| + +## Defining a custom polling interval {% include common-tasks/define_custom_polling.md %} diff --git a/source/_integrations/technove.markdown b/source/_integrations/technove.markdown index 140bdc3cbfd4..f524bae96338 100644 --- a/source/_integrations/technove.markdown +++ b/source/_integrations/technove.markdown @@ -64,3 +64,4 @@ The {% term integration %} adds the following switch: | Name | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Auto-charge mode | When enabled, vehicles will start charging automatically when plugged in. When turned off, charging will need to be manually started each time a vehicle is plugged in. Note: Disabling auto-charge mode does not interrupt an ongoing charging session. | +| Charging enabled | When enabled, vehicles will be able to charge. Disable it to stop a vehicle from charging. Note: This switch can only be used when auto-charge mode is disabled. | diff --git a/source/_integrations/template.markdown b/source/_integrations/template.markdown index 7ebd0120e94a..a16c288d35cd 100644 --- a/source/_integrations/template.markdown +++ b/source/_integrations/template.markdown @@ -41,7 +41,9 @@ related: The `template` integration allows creating entities which derive their values from other data. This is done by specifying [templates](/docs/configuration/templating/) for properties of an entity, like the name or the state. -Sensors, binary (on/off) sensors, buttons, images, numbers and selects are covered on this page. For other types, please see the specific pages: +Sensors, binary (on/off) sensors, buttons, images, numbers, and selects are covered on this page. They can be configured using [UI](#configuration) or [YAML](#yaml-configuration) file. + +For other types, please see the specific pages: - [Alarm control panel](/integrations/alarm_control_panel.template/) - [Cover](/integrations/cover.template/) @@ -52,16 +54,6 @@ Sensors, binary (on/off) sensors, buttons, images, numbers and selects are cover - [Vacuum](/integrations/vacuum.template/) - [Weather](/integrations/weather.template/) -Sensor, binary sensor, button, image and select can be configured using [UI](#ui-configuration) or [YAML](#yaml-configuration) file. - -Number template entities are defined in your YAML configuration files under the `template:` key and cannot be configured via the UI. You can define multiple configuration blocks as a list. Each block defines sensor/binary sensor/number/select entities and can contain an optional update trigger. - -_For old sensor/binary sensor configuration format, [see below](#legacy-binary-sensor-configuration-format)._ - -## UI configuration - -Sensor template, binary sensor template, button template, image template and select template can be configured using the user interface at **{% my helpers title="Settings > Devices & services > Helpers" %}**. Select the **+ Add helper** button and then select the **{% my config_flow_start domain=page.ha_domain title=page.title %}** helper. - {% include integrations/config_flow.md %} {% important %} @@ -76,6 +68,10 @@ If you need more specific features for your use case, the manual [YAML-configura ## YAML configuration +Entities (sensors, binary sensors, buttons, images, numbers, and selections) are defined in your YAML configuration files under the `template:` key. You can define multiple configuration blocks as a list. Each block defines sensor/binary sensor/number/select entities and can contain an optional update trigger. + +_For old sensor/binary sensor configuration format, [see below](#legacy-binary-sensor-configuration-format)._ + ### State-based template binary sensors, buttons, images, numbers, selects and sensors Template entities will by default update as soon as any of the referenced data in the template updates. @@ -137,6 +133,10 @@ unique_id: description: The unique ID for this config block. This will be prefixed to all unique IDs of all entities in this block. required: false type: string +condition: + description: Define conditions that have to be met after a trigger fires and before any actions are executed or sensor updates are performed. Optional. [See condition documentation](/docs/automation/condition). + required: false + type: list action: description: Define actions to be executed when the trigger fires. Optional. Variables set by the action script are available when evaluating entity templates. This can be used to interact with anything using actions, in particular actions with [response data](/docs/scripts/service-calls#use-templates-to-handle-response-data). [See action documentation](/docs/automation/action). required: false @@ -218,6 +218,11 @@ number: description: Template for the number's current value. required: true type: template + unit_of_measurement: + description: Defines the units of measurement of the number, if any. + required: false + type: string + default: None set_value: description: Defines actions to run when the number value changes. The variable `value` will contain the number entered. required: true @@ -540,6 +545,27 @@ template: state: "true" ``` +### Using conditions with triggers to control status updates + +This example shows how to store the last valid value of a temperature sensor. It will update as long as the source sensor has a valid (numeric) state. Otherwise, the template sensor's state will remain unchanged. + +{% raw %} + +```yaml +template: + - trigger: + platform: state + entity_id: sensor.outside_temperature + condition: + - condition: template + value_template: "{{ is_number(states('sensor.outside_temperature')) }}" + sensor: + - name: Outside Temperature last known value + state: "{{ states('sensor.outside_temperature') }}" +``` + +{% endraw %} + ### State based sensor exposing sun angle This example shows the sun angle in the frontend. @@ -813,6 +839,33 @@ template: {% endraw %} +### Number entity changing the unit of measurement of another number + +This example demonstrates the usage of a template number with a unit of measurement set to change a unit-less value of another number entity. + +{% raw %} + +```yaml +template: + - number: + - name: "Cutting Height" + unit_of_measurement: "cm" + unique_id: automower_cutting_height + state: "{{ states('number.automower_cutting_height_raw')|int(0) * 0.5 + 1.5 }}" + set_value: + - service: number.set_value + target: + entity_id: number.automower_cutting_height_raw + data: + value: "{{ (value - 1.5) * 2 }}" + step: 0.5 + min: 2 + max: 6 + icon: mdi:ruler +``` + +{% endraw %} + ## Legacy binary sensor configuration format diff --git a/source/_integrations/tesla_fleet.markdown b/source/_integrations/tesla_fleet.markdown index 90026d71835c..bade8b038462 100644 --- a/source/_integrations/tesla_fleet.markdown +++ b/source/_integrations/tesla_fleet.markdown @@ -4,6 +4,7 @@ description: Instructions on how to integrate the Tesla Fleet API within Home As ha_category: - Binary sensor - Car + - Climate - Device tracker - Sensor ha_release: 2024.8 @@ -14,9 +15,11 @@ ha_codeowners: ha_domain: tesla_fleet ha_platforms: - binary_sensor + - climate - device_tracker - diagnostics - sensor +ha_quality_scale: gold ha_integration_type: integration --- @@ -26,6 +29,14 @@ The Tesla Fleet API {% term integration %} exposes various sensors from Tesla ve You must have a [Tesla](https://tesla.com) account and a Tesla vehicle, PowerWall, Solar, or Wall Connector. +{% details "Use a custom OAuth application" %} + +The integration has a built-in OAuth application that will be suitable for most users. However, you can [create your own application](https://developer.tesla.com/dashboard) for the Tesla Fleet API and configure it as an [application credential](https://my.home-assistant.io/redirect/application_credentials). When creating the application, you must set `https://my.home-assistant.io/redirect/oauth` as the redirect URL. + +You will be prompted to pick your custom application credential when creating a Tesla Fleet config entry. + +{% enddetails %} + {% include integrations/config_flow.md %} ## Scopes @@ -36,6 +47,10 @@ When connecting your Tesla account to Home Assistant, you **must** select the `V Tesla restricts open-source integrations to the ["Discovery" plan](https://developer.tesla.com/docs/fleet-api/getting-started/subscription-plans) which only allows for 200 vehicle data requests per day. The integration will initially poll every 90 seconds, making vehicle data requests only when the vehicle is awake, and then dynamically slow down polling based on how many vehicle data requests have been made in the last 24 hours. +## Command signing + +Certain vehicles, including all vehicles manufactured since late 2023, require vehicle commands to be encrypted end-to-end and signed with a private key. The Tesla Fleet integration is unable to perform this encryption at this time, so certain features may be disabled or throw an exception when used. + ## Entities These are the entities available in the Tesla Fleet integration. Not all entities are enabled by default, and not all values are always available. @@ -67,6 +82,8 @@ These are the entities available in the Tesla Fleet integration. Not all entitie |Binary sensor|Tire pressure warning rear right|No| |Binary sensor|Trip charging|No| |Binary sensor|User present|Yes| +|Climate|Cabin overheat protection|No| +|Climate|Climate|Yes| |Device tracker|Location|Yes| |Device tracker|Route|Yes| |Sensor|Battery level|Yes| diff --git a/source/_integrations/todoist.markdown b/source/_integrations/todoist.markdown index 1bcda7114226..6aadec01444f 100644 --- a/source/_integrations/todoist.markdown +++ b/source/_integrations/todoist.markdown @@ -190,6 +190,8 @@ Here are two example JSON payloads resulting in the same task: - **project** (*Optional*): The project to put the task in. +- **section** (*Optional*): The section within the project to add the task to. + - **labels** (*Optional*): Any labels you want to add to the task, separated by commas. - **assignee** (*Optional*): A member's username of a shared project to assign this task to. You find the username formatted as bold text in the collaborator menu of a shared project. diff --git a/source/_integrations/totalconnect.markdown b/source/_integrations/totalconnect.markdown index 3c022f584dd6..83236b33fb56 100644 --- a/source/_integrations/totalconnect.markdown +++ b/source/_integrations/totalconnect.markdown @@ -33,6 +33,8 @@ Give the user access to your Location, along with a user code, usually a 4 digit **Auto Bypass Low Battery:** if enabled, TotalConnect zones will immediately be bypassed when they report low battery. This option helps because zones tend to report low battery in the middle of the night. The downside of this option is that when the alarm system is armed, the bypassed zone will not be monitored. +**Require Code:** if enabled, you must enter the user code to disarm the alarm. + ## Automation example ```yaml automation: diff --git a/source/_integrations/touchline_sl.markdown b/source/_integrations/touchline_sl.markdown new file mode 100644 index 000000000000..58b611cb6275 --- /dev/null +++ b/source/_integrations/touchline_sl.markdown @@ -0,0 +1,29 @@ +--- +title: Roth Touchline SL +description: Instructions on how to integrate Roth Touchline SL within Home Assistant. +ha_category: + - Climate +ha_release: 2024.9 +ha_iot_class: Cloud Polling +ha_domain: touchline_sl +ha_platforms: + - climate +ha_integration_type: integration +--- + +The **Roth Touchline SL** climate integration enables you to control [Roth Touchline SL](https://www.roth-uk.com/products/control-systems/roth-touchliner-sl-wireless-system) underfloor heating systems. + +## Prerequisites + +You must have an account registered with the [Roth Touchline SL dashboard](https://roth-touchlinesl.com/login). + +{% include integrations/config_flow.md %} + +## Entities + +The integration will present each Roth Touchline SL zone as a climate entity, which can: + +- Display the current temperature +- Display the current humidity +- Set a target temperature +- Assign to a configured "Global Schedule" using Home Assistant climate entity presets. diff --git a/source/_integrations/unifi.markdown b/source/_integrations/unifi.markdown index 520d77a517ad..a40964d8ec11 100644 --- a/source/_integrations/unifi.markdown +++ b/source/_integrations/unifi.markdown @@ -130,6 +130,10 @@ Entities appear for each port forwarding rule. Entities appear for each WLAN. Changing the state of WLAN will trigger a reconfiguration of affected access points, limiting access to all WLANs exposed by the access point. +### Traffic Rules + +Entities appear for each Traffic Rule. This allows toggling rules on and off. + ## Sensor ### Bandwidth sensor diff --git a/source/_integrations/vallox.markdown b/source/_integrations/vallox.markdown index a4bf430dcf33..d3bd0da0d9af 100644 --- a/source/_integrations/vallox.markdown +++ b/source/_integrations/vallox.markdown @@ -91,3 +91,12 @@ Set the fan speed of the `Boost` profile. | Data attribute | Optional | Description | |------------------------|----------|-------------------------------------------------| | `fan_speed` | no | Fan speed in %. `Integer`, between 0 and 100. | + +### Action `vallox.set_profile` + +Set the profile, and optionally a duration for the profile to be active. + +| Data attribute | Optional | Description | +|----------------|---------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `profile` | no | Profile to set, one of `home`, `away`, `boost`, `fireplace`, or `extra`. | +| `duration` | yes | Duration to activate the profile for; in minutes. `Integer` between 1 and 65535. Only applies to `boost`, `fireplace` or `extra` profiles. 65535 sets the profile without a timeout. | \ No newline at end of file diff --git a/source/_integrations/vesync.markdown b/source/_integrations/vesync.markdown index 2b9649b65019..dda689e0de31 100644 --- a/source/_integrations/vesync.markdown +++ b/source/_integrations/vesync.markdown @@ -62,6 +62,7 @@ This {% term integration %} supports devices controllable by the VeSync App. Th - Core 300S: Smart True HEPA Air Purifier - Core 400S: Smart True HEPA Air Purifier - Core 600S: Smart True HEPA Air Purifier +- EverestAir: Smart Air Purifier - Vital 100S Smart True HEPA Air Purifier (LAP-V102S-WUS) - Vital 200S Smart True HEPA Air Purifier (LAP-V201S-WUS) - LEVOIT Smart Wifi Air Purifier (LV-PUR131S) @@ -97,11 +98,11 @@ itself. Note that prior versions of the {% term integration %} exposed these as ## Fan & air quality sensors All VeSync air purifiers expose the remaining filter lifetime, and some also expose air quality measurements. -| Sensor | Description | Example | -| --------------------------------------- | ------------------------------------------------------------------ | ------- | -| `filter_life` | Remaining percentage of the filter. (LV-PUR131S, Core200S/300s/400s/600s) | 142 | +| Sensor | Description | Example | +| ----------------------- | -------------------------------------------------------------------------------------- | --------- | +| `filter_life` | Remaining percentage of the filter. (LV-PUR131S, Core200S/300s/400s/600s/EverestAir) | 142 | | `air_quality` | The current air quality reading. (LV-PUR131S, Core300s/400s/600s) | excellent | -| `pm2_5` | The current air quality reading. (Core300s/400s/600s) | 8 | +| `pm2_5` | The current air quality reading. (Core300s/400s/600s/EverestAir) | 8 | ## Fan exposed attributes diff --git a/source/_integrations/wallbox.markdown b/source/_integrations/wallbox.markdown index 592d21c333c5..0e12fa7f4464 100644 --- a/source/_integrations/wallbox.markdown +++ b/source/_integrations/wallbox.markdown @@ -25,26 +25,28 @@ The **Wallbox** {% term integration %} pulls data from the [MyWallbox Portal](ht The {% term integration %} adds the following sensors: -- Added energy -- Added range -- Charging power +- Added energy (kWh) +- Added range (km) +- Charging power (kW) - Charging speed - Charging time -- Cost +- Cost ([default currency]) - Current mode -- Depot price -- Energy price -- Max available power -- State of charge +- Depot price ([default currency]/kWh) +- Energy price ([default currency]/kWh) +- Max available power (A) +- State of charge (%) - Status description -- Max charging current +- Max charging current (A) +- Max ICP current (A) ## Number The {% term integration %} adds the following number entities: -- Max charging current -- Energy price +- Max charging current (A) +- Max ICP current; this is the maximum current available for load balancing (A) +- Energy price ([default currency]/kWh) The number {% term entity %} is only loaded if the supplied username has sufficient rights to change the Max. Charging Current. diff --git a/source/_integrations/yale.markdown b/source/_integrations/yale.markdown new file mode 100644 index 000000000000..61a946f7ef4c --- /dev/null +++ b/source/_integrations/yale.markdown @@ -0,0 +1,156 @@ +--- +title: Yale +description: Instructions on how to integrate your Yale devices into Home Assistant. +ha_category: + - Binary sensor + - Button + - Camera + - Doorbell + - Event + - Lock + - Sensor +ha_release: 2024.9 +ha_iot_class: Cloud Push +ha_config_flow: true +ha_codeowners: + - '@bdraco' +ha_domain: yale +ha_dhcp: true +ha_platforms: + - binary_sensor + - button + - camera + - diagnostics + - event + - lock + - sensor +ha_integration_type: integration +--- + +The **Yale** integration allows you to integrate your [Yale](https://www.assaabloy.com/vn/en/solutions/products/yale) devices in Home Assistant. + +The login credentials used to authenticate the integration are the same as the ones used in the Yale Home app. + +{% include integrations/config_flow.md %} + +## Known working devices + +| Device | Requires [Connect Bridge](https://www.yalehome.com/vn/en/products/yale-smart-door-lock/smart-accessories/yale-connect-wi-fi-bridge) or Doorbell | +| --------------------------------- | ------------------------------------| +| Yale Assure Lock | yes | +| Yale Conexis L1 | yes | +| Yale Conexis L2 | yes | +| Yale Doorman L3 | yes | +| Yale Linus | yes | +| Yale Smart Safe | yes | + +Other devices not listed above have not been tested and may not function as expected. + +There is currently support for the following device types within Home Assistant: + +- Doorbell +- Binary sensor +- Button +- Sensor +- Camera +- Lock + +{% note %} +Most devices will need either a Yale Connect Bridge or a Doorbell to connect to Home Assistant. +{% endnote %} + +## Push updates not available for some entities + +While most entities can be updated via the push API, Yale/Yale does not offer a push API for some data, which means these entities will update slower: + +- Doorbell ding sensor (Doorman models only) +- Lock Battery sensor +- Lock Operation sensor + +## Binary sensor + +If you have a Yale Doorbell, once you have enabled the Yale integration, you should see the following sensors: + +- Doorbell ding sensor +- Doorbell motion sensor +- Doorbell online sensor + +If you have a Yale Smart Lock with DoorSense, once you have enabled the Yale integration, you should see the following sensors: + +- Door sensor + +## Button + +Buttons are created to wake locks from a deep sleep. If your lock is not reporting a status, it may be in a deep sleep, and the button can be used to wake it. Locks are not automatically woken from deep sleep to preserve battery life. + +## Event + +If you have a Yale doorbell or lock that has a built-in doorbell, once you have enabled the Yale integration, you should see the following event entities: + +- Doorbell +- Motion + +Not all models include motion sensors and support for locks with built-in doorbells is limited to Yale Doorman models type 7 and 10. + +## Camera + +The `yale` camera platform allows you to view the latest camera image (triggered by motion) by your [Yale](https://yale.com/) device in Home Assistant. + +## Sensor + +If you have a Yale Doorbell with a battery, once you have enabled the Yale integration, you should see the following sensors: + +- Doorbell Battery + +If you have a Yale Smart Lock, once you have enabled the Yale integration, you should see the following sensors: + +- Lock Battery +- Lock Operation + +If you have a Yale Keypad, once you have enabled the Yale integration, you should see the following sensors: + +- Keypad Battery + +## Integration with Yale Access Bluetooth + +Following Assa Abloy, Yale's parent company, purchasing Yale in 2017, most newer devices use the Yale Home branding. + +The [Yale Access Bluetooth](/integrations/yalexs_ble) integration provides local control over Bluetooth of many Yale Home locks that use the same system. + +For locks that support the Yale Access system, the Yale integration can keep your offline access keys up to date to ensure you can operate your lock over Bluetooth. The following requirements must be met for the offline key updates to work: + +- The Yale integration must support the lock. +- The [Yale Access Bluetooth integration](/integrations/yalexs_ble) must support the lock. +- The Bluetooth integration must be active and functional. +- The lock must be discoverable by the [Yale Access Bluetooth integration](/integrations/yalexs_ble). +- The account logged in with the Yale integration must have the offline keys. + +### Troubleshooting offline key updates + +- If you do not know which account has the offline keys, configure Yale integration with each different Owner account until you find the one that holds the keys. You may need to make a new owner account and grant the account access to your lock to force the keys to synchronize with the cloud service. +- Ensure the lock is in range and discoverable by the [Yale Access Bluetooth integration](/integrations/yalexs_ble). + +## Presence detection with lock operation + +Using the lock operation sensors, you can detect when a user operates a lock and is physically present (not remote). The below automation example (added to `automations.yaml`) will trigger when the user named “John Doe” in Yale locks or unlocks the door either from the keypad (if present), via Bluetooth from their phone, or by auto-unlock. The state of the sensor will be the name of the party operating the lock as returned by Yale. + +{% raw %} + +```yaml +- id: "1583706446906" + alias: "joe_doe_front_door_operate" + description: John Doe locks or unlocks the Front Door + trigger: + - entity_id: sensor.front_door_operator + platform: state + to: John Doe + condition: + - condition: template + value_template: "{{ not state_attr('sensor.front_door_operator', 'remote') }}" + action: + - data: {} + entity_id: camera.inside + service: camera.turn_off +``` + +{% endraw %} diff --git a/source/_integrations/yale_home.markdown b/source/_integrations/yale_home.markdown index 9981d222a44b..b874c85a4013 100644 --- a/source/_integrations/yale_home.markdown +++ b/source/_integrations/yale_home.markdown @@ -1,6 +1,6 @@ --- title: Yale Home -description: Connect and control your Yale Home devices using the August integration +description: Connect and control your Yale Home devices using the Yale integration ha_category: - Binary sensor - Button @@ -12,8 +12,8 @@ ha_category: ha_release: 0.64 ha_domain: yale_home ha_integration_type: virtual -ha_supporting_domain: august -ha_supporting_integration: August +ha_supporting_domain: yale +ha_supporting_integration: Yale ha_codeowners: - '@bdraco' ha_config_flow: true diff --git a/source/_integrations/yolink.markdown b/source/_integrations/yolink.markdown index 16589ffdc1e9..cd149290fb03 100644 --- a/source/_integrations/yolink.markdown +++ b/source/_integrations/yolink.markdown @@ -99,6 +99,7 @@ The integration is tested and verified for the following devices from YoLink: - YS5007-UC (FlowSmart Meter) - YS5008-UC (FlowSmart All-in-One) - YS8017-UC (Thermometer) +- YS8008-UC (Float Thermometer) ## Actions diff --git a/source/_integrations/youtube.markdown b/source/_integrations/youtube.markdown index 5e6ab93aba33..27498314ad3a 100644 --- a/source/_integrations/youtube.markdown +++ b/source/_integrations/youtube.markdown @@ -20,6 +20,7 @@ api_link: https://console.cloud.google.com/apis/library/youtube.googleapis.com?p The **YouTube** {% term integration %} allows you to connect YouTube channels to Home Assistant. For every channel you add, it will create sensors for: +- Views count - Subscriber count - The latest uploaded video diff --git a/source/_redirects b/source/_redirects index 30695188cb44..d03b4243895d 100644 --- a/source/_redirects +++ b/source/_redirects @@ -498,6 +498,7 @@ layout: null /integrations/arduino /more-info/removed-integration 301 /integrations/asterisk_cdr /more-info/removed-integration 301 /integrations/asterisk_mbox /more-info/removed-integration 301 +/_docs/asterisk_mbox.markdown /more-info/removed-integration 301 /integrations/bbb_gpio /more-info/removed-integration 301 /integrations/bh1750 /more-info/removed-integration 301 /integrations/binary_sensor.mychevy /more-info/removed-integration 301 diff --git a/source/dashboards/badges.markdown b/source/dashboards/badges.markdown index e4688ab7cc7f..09294582a3fe 100644 --- a/source/dashboards/badges.markdown +++ b/source/dashboards/badges.markdown @@ -66,11 +66,21 @@ show_entity_picture: description: If your entity has a picture, it will replace the icon. type: boolean default: false -display_type: +show_name: required: false - description: Type of display for the badge. It can be either `minimal` (icon only), `standard` (icon and state), or `complete` (icon, state, and name). - type: string - default: standard + description: Show the name + type: boolean + default: "true" +show_icon: + required: false + description: Show the icon + type: boolean + default: "true" +show_state: + required: false + description: Show the state. + type: boolean + default: "false" state_content: required: false description: > diff --git a/source/images/dashboards/badge_configure.png b/source/images/dashboards/badge_configure.png index c0d9942e103e..bef9122b9083 100644 Binary files a/source/images/dashboards/badge_configure.png and b/source/images/dashboards/badge_configure.png differ