diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1dccbda21e8..23bf49f1fa8 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -8,9 +8,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out files from GitHub - uses: actions/checkout@v3.5.3 + uses: actions/checkout@v3.6.0 - name: Setting up Node.js - uses: actions/setup-node@v3.7.0 + uses: actions/setup-node@v3.8.1 with: node-version: 16.x cache: "npm" @@ -25,9 +25,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out files from GitHub - uses: actions/checkout@v3.5.3 + uses: actions/checkout@v3.6.0 - name: Setting up Node.js - uses: actions/setup-node@v3.7.0 + uses: actions/setup-node@v3.8.1 with: node-version: 16.x cache: "npm" diff --git a/Gemfile b/Gemfile index 708a0eb762a..2bacd210cee 100644 --- a/Gemfile +++ b/Gemfile @@ -19,8 +19,8 @@ group :jekyll_plugins do gem 'jekyll-toc', '0.18.0' end -gem 'sinatra', '3.0.6' -gem 'nokogiri', '1.15.3' +gem 'sinatra', '3.1.0' +gem 'nokogiri', '1.15.4' # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem # and associated library diff --git a/Gemfile.lock b/Gemfile.lock index 888a2fe9169..506f6f7ccab 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -27,7 +27,7 @@ GEM ffi (1.15.5) ffi (1.15.5-x64-mingw32) forwardable-extended (2.6.0) - google-protobuf (3.23.4) + google-protobuf (3.24.2) http_parser.rb (0.8.0) i18n (1.14.1) concurrent-ruby (~> 1.0) @@ -72,7 +72,7 @@ GEM multi_json (1.15.0) mustermann (3.0.0) ruby2_keywords (~> 0.0.1) - nokogiri (1.15.3) + nokogiri (1.15.4) mini_portile2 (~> 2.8.2) racc (~> 1.4) pathutil (0.16.2) @@ -80,8 +80,8 @@ GEM public_suffix (5.0.3) racc (1.7.1) rack (2.2.8) - rack-protection (3.0.6) - rack + rack-protection (3.1.0) + rack (~> 2.2, >= 2.2.4) rake (13.0.6) rb-fsevent (0.11.2) rb-inotify (0.10.1) @@ -102,15 +102,15 @@ GEM ffi (~> 1.9) sassc (2.1.0-x64-mingw32) ffi (~> 1.9) - sinatra (3.0.6) + sinatra (3.1.0) mustermann (~> 3.0) rack (~> 2.2, >= 2.2.4) - rack-protection (= 3.0.6) + rack-protection (= 3.1.0) tilt (~> 2.0) stringex (2.8.6) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) - tilt (2.1.0) + tilt (2.2.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) tzinfo-data (1.2023.3) @@ -129,11 +129,11 @@ DEPENDENCIES jekyll-paginate (= 1.1.0) jekyll-sitemap (= 1.4.0) jekyll-toc (= 0.18.0) - nokogiri (= 1.15.3) + nokogiri (= 1.15.4) rake (= 13.0.6) sass-globbing (= 1.1.5) sassc (= 2.1.0) - sinatra (= 3.0.6) + sinatra (= 3.1.0) stringex (= 2.8.6) tzinfo (~> 2.0) tzinfo-data diff --git a/_config.yml b/_config.yml index c02ddf7bf9f..eeaaf6a4a5f 100644 --- a/_config.yml +++ b/_config.yml @@ -110,8 +110,8 @@ social: # Home Assistant release details current_major_version: 2023 current_minor_version: 8 -current_patch_version: 1 -date_released: 2023-08-04 +current_patch_version: 4 +date_released: 2023-08-24 # Either # or the anchor link to latest release notes in the blog post. # Must be prefixed with a # and have double quotes around it. @@ -195,7 +195,7 @@ toc: installation: container: "ghcr.io/home-assistant/home-assistant" versions: - python: "3.10" + python: "3.11" types: odroid: board: ODROID diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index 7ac6c619d7d..ae052c397da 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -174,6 +174,79 @@ a.integration-alert { } } +.installation-survey { + box-shadow: none; + border: 1px solid rgba(0, 0, 0, .12); + border-radius: 4px; + padding-bottom: 64px; + + h4 { + margin: 0 0 8px !important; + + a { + text-decoration: none !important; + color: #000; + } + } + + .links a { + font-weight: 400; + text-transform: none; + } +} + + +.survey-button { + padding-top: 8px; + button { + position: relative; + cursor: pointer; + font-size: 14px; + font-weight: bold; + padding: 8px 28px; + color: #fff; + background-color: #03a9f4; + border: none; + border-radius: 4px; + box-shadow: 0 2px 2px 0 rgba(0,0,0,.14), 0 3px 1px -2px rgba(0,0,0,.12), 0 1px 5px 0 rgba(0,0,0,.2); + } + button::before { + content: " "; + position: absolute; + top: 0; + bottom: 0; + left: 0; + right: 0; + opacity: 0.2; + border-radius: 4px; + } + button:hover { + box-shadow: 0 4px 8px 0 rgba(0,0,0,.14), 0 1px 7px 0 rgba(0,0,0,.12), 0 3px 1px -1px rgba(0,0,0,.2); + } + button:hover::before { + background-color: rgba(255,255,255,.8); + } + button:focus { + outline: none; + } + button:focus::before { + background-color: white; + } + button:active::before { + background-color: grey; + } + :host([active]) button { + color: rgba(0, 0, 0, 0.38); + background-color: rgba(0, 0, 0, 0.12); + box-shadow: none; + cursor: unset; + pointer-events: none; + } + .hidden { + display: none; + } +} + .frontpage { .material-card { margin-bottom: 24px; diff --git a/source/_docs/blueprint.markdown b/source/_docs/blueprint.markdown index a6444c141d9..e5609824622 100644 --- a/source/_docs/blueprint.markdown +++ b/source/_docs/blueprint.markdown @@ -1,28 +1,24 @@ --- -title: "Creating blueprints" -description: "Documentation on how to get started creating blueprints." +title: "About blueprints" +description: "Introduction to blueprints." --- -
+This section gives a high-level introduction to blueprints. To view a description of the YAML-schema used to create a valid blueprint, refer to the section [About the blueprint schema](/docs/blueprint/schema/). -If you're looking on how to use blueprints, see the [automation documentation](/docs/automation/using_blueprints/). +## What is a blueprint? -
+A blueprint is a script or automation configuration with certain parts marked as configurable. This allows you to create different scripts or automations based on the same blueprint. -
+Imagine you want to control lights based on motion. A blueprint provides the generic automation framework, while letting you select one specific motion sensor as a trigger, and the exact light to control. This blueprint makes it possible to create two automations. Each automation has their own configuration and act completely independently. Yet, they share some basic automation configuration so that you do not have to set this up every time. -While the tutorial only shows how to create an automation blueprint, scripts also support blueprints in the same way. +Blueprints are shared by the community in the [blueprint community forum][blueprint-forums]. -
+### Related information -A blueprint is a script or automation configuration with certain parts marked as configurable. This allows users to create multiple scripts or automations based on the same blueprint, with each having its own configuration. +- [About the blueprint schema](/docs/blueprint/schema/) +- [About the blueprint selectors](/docs/blueprint/selectors/) +- [Using blueprints in automations](/docs/automation/using_blueprints/) +- [Tutorial: Create an automation blueprint](/docs/blueprint/tutorial/) +- [Blueprint community forum][blueprint-forums] -Imagine a blueprint that controls a light based on motion, that allows you to configure the motion sensor to trigger on, and the light to control. It is now possible to create two automations that each have their own configuration for this blueprint and that act completely independent, yet are based on the same automation configuration. - -
- -This is an advanced feature and requires knowledge of writing [automations](/docs/automation/yaml/) and [scripts](/docs/scripts/) in YAML. - -
- -### [Tutorial: Create an automation blueprint »](/docs/blueprint/tutorial/) +[blueprint-forums]: /get-blueprints \ No newline at end of file diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown index e1a06fdf79b..3b1f7326764 100644 --- a/source/_docs/blueprint/schema.markdown +++ b/source/_docs/blueprint/schema.markdown @@ -1,25 +1,17 @@ --- -title: "Blueprint schema" -description: "The schema for a valid blueprint." +title: "About the blueprint schema" +description: "Introduction to the blueprint schema." --- +## The blueprint schema + The configuration schema of a blueprint consists of 2 parts: -- The blueprint high-level metadata, like its name and a description and - the input the blueprint needs from the user. -- The schema of the thing the blueprint describes. +1. The blueprint's high-level metadata: name, description, the input required from the user. +2. The schema of the thing the blueprint describes. -The first part is referred to as the blueprint schema and contains mainly the -blueprint's metadata. The second part depends on what the blueprint is for. - -For example, in the case of creating a blueprint for an automation, the full -schema for an [automation](/docs/automation/yaml/) applies. - -This page is mainly set up to describe the configuration schema of the -blueprint metadata. Try our [blueprint tutorial](/docs/blueprint/tutorial/) -in case you are interested in creating your first blueprint. - -## The blueprint schema +The first part is referred to as the *blueprint schema*. It contains the +blueprint's metadata. The only requirement for a blueprint is a name. In its most basic form, a blueprint would look like: @@ -30,9 +22,12 @@ blueprint: domain: automation ``` -And this is already a valid blueprint. But typically, one would need -more. For example, user inputs or a description to describe the blueprint's -functionality. +Although this is a valid blueprint, it is not very useful. + +The second part depends on the use case of the blueprint. For example, if you create a blueprint for an automation, the full +schema for an [automation](/docs/automation/yaml/) applies. + +You can add a description of the blueprint's use case and user inputs. This is the full blueprint schema: @@ -44,15 +39,14 @@ name: description: description: > The description of the blueprint. While optional, this field is highly - recommended. For example, to describe what the blueprint does, or tell more - about the options inputs of the blueprint provide. The description can + recommended. Describe what the blueprint does and describe the inputs the blueprint provide. The description can include [Markdown](https://commonmark.org/help/). type: string required: false domain: description: > - The domain name this blueprint provides a blueprint for. Currently, only - `automation` and `script` are supported. + The domain in which this blueprint is used. Currently, only + [`automation`](/docs/automation/yaml/) and `script` are supported. type: string required: true author: @@ -67,7 +61,7 @@ homeassistant: keys: min_version: description: > - Minimum required version of Home Assistant to use the blueprint (e.g. + Minimum required version of Home Assistant to use the blueprint. For example, `2022.4.0`. It is important to set this if the blueprint uses any features introduced in recent releases to head off issues. type: string @@ -104,12 +98,12 @@ input: required: false {% endconfiguration %} -## Blueprint inputs +### Blueprint inputs -As written in the above schema, a blueprint can accept one (or multiple) -inputs from the blueprint consumer. +As described above, a blueprint can accept one (or multiple) +inputs from the blueprint user. -These inputs can be of any type (string, boolean, list, dictionary), can have +These inputs can be of any type (string, boolean, list, dictionary). They can have a default value and also provide a [selector](/docs/blueprint/selectors/) that ensures a matching input field in the user interface. @@ -127,11 +121,11 @@ blueprint: name: Example input ``` -In the above example, `my_input` is the identifier of the input, that can be -referred to later on using the `!input my_input` custom tag. +In the above example, `my_input` is the identifier of the input. It can be +referenced by using the `!input my_input` custom tag. -In this example, no `selector` was provided. In this case, if this blueprint -was used in the user interface, a text input field would be shown to the user. +In this example, no [`selector`](/docs/blueprint/selectors/) was provided. In the user interface, a text input field would be shown to the user. +It is then up to the user to find out what to enter there. Blueprints that come with [selectors](/docs/blueprint/selectors/) are easier to use. A blueprint can have as many inputs as you like. @@ -148,7 +142,7 @@ variables: my_input: !input my_input ``` -## Example blueprints +### Example blueprints The [built-in blueprints][blueprint-built-in] are great examples to get a bit of a feeling of how blueprints work. @@ -207,8 +201,12 @@ action: target: !input light_target ``` -Additional examples, provided by the community, can be found on the -[community forum][blueprint-forums]. +### Related information +- [About blueprints](/docs/blueprint/) +- [Blueprint selectors](/docs/blueprint/selectors/) +- [Using blueprints in automations](/docs/automation/using_blueprints/) +- [Tutorial: Create an automation blueprint »](/docs/blueprint/tutorial/) +- [Blueprint community forum][blueprint-forums] [blueprint-built-in]: https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints -[blueprint-forums]: /get-blueprints +[blueprint-forums]: /get-blueprints \ No newline at end of file diff --git a/source/_docs/blueprint/selectors.markdown b/source/_docs/blueprint/selectors.markdown index 357bab91c9d..e5b5b04ca3d 100644 --- a/source/_docs/blueprint/selectors.markdown +++ b/source/_docs/blueprint/selectors.markdown @@ -383,12 +383,12 @@ is that the constant selector has no value when it's not enabled. The selector's value must be configured, and optionally, a label. ```yaml -boolean: +constant: value: true label: Enabled ``` -The output of this selector is the configured value when the toggle is on, it has not output otherwise. +The output of this selector is the configured value when the toggle is on, it has no output otherwise. ## Conversation agent selector diff --git a/source/_docs/blueprint/tutorial.markdown b/source/_docs/blueprint/tutorial.markdown index 6726192b829..3af7bb7954e 100644 --- a/source/_docs/blueprint/tutorial.markdown +++ b/source/_docs/blueprint/tutorial.markdown @@ -1,5 +1,5 @@ --- -title: "Automation blueprint tutorial" +title: "Creating an automation blueprint" description: "Tutorial on creating an automation blueprint." --- @@ -9,13 +9,23 @@ While the tutorial only shows how to create an automation blueprint, scripts als +## Creating an automation blueprint + In this tutorial, we're going to create an automation blueprint that controls a light based on a motion sensor. We will do this by taking an existing automation and converting it to a blueprint. -For this tutorial, we use a simple automation. The process for converting a complex automation is not any different. +### Prerequisites -## Our automation +- This tutorial assumes knowledge in the following topics: + - [Editing the configuration file](/docs/configuration/) + - [YAML](/docs/configuration/yaml/), and specifically, [YAML used in automations](/docs/automation/yaml/) + - [Scripts](/docs/scripts/) -To create a blueprint, we first need to have a working automation. The automation we're going to use in this tutorial, which controls a light based on a motion sensor, looks like this: +### Creating an automation + +To create a blueprint, we first need to have a working automation. +For this tutorial, we use a simple automation. The process for converting a complex automation is no different. + +The automation we're going to use in this tutorial controls a light based on a motion sensor: {% raw %} @@ -37,13 +47,17 @@ action: {% endraw %} -## Create the blueprint file +The options that can be used with the `trigger` object are listed under [automation trigger variables](/docs/automation/templating/#available-trigger-data). +In this example, a [state trigger](/docs/automation/templating/#state) is used. +`turn_on` and `turn_off` are [`homeassistant` services](/docs/scripts/service-calls/#homeassistant-services). They are not tied to a specific domain. You can use them on lights, switches, and other domains. + +### Creating the blueprint file Automation blueprints are YAML files (with the `.yaml` extension) and live in the `/blueprints/automation/` folder. You can create as many subdirectories in this folder as you want. To get started with our blueprint, we're going to copy the above automation YAML and save it in that directory with the name `motion_light_tutorial.yaml`. -## Add basic blueprint metadata +#### Add basic blueprint metadata Home Assistant needs to know about the blueprint. This is achieved by adding a `blueprint:` section. It should contain the `domain` of the integration it is for (`automation`) and `name`, the name of your blueprint. Optionally, you can also include a `description` for your blueprint. @@ -56,7 +70,7 @@ blueprint: domain: automation ``` -## Define the configurable parts as inputs +#### Define the configurable parts as inputs Now we have to decide what steps we want to make configurable. We want to make it as re-usable as possible, without losing its original intent of turning on a light-based on a motion sensor. @@ -87,7 +101,7 @@ action: {% endraw %} -## Add the inputs to the metadata +#### Add the inputs to the metadata All parts that are marked as inputs need to be added to the metadata. The minimum is that we add their names as used in the automation: @@ -101,7 +115,9 @@ blueprint: target_light: ``` -## Use it via `configuration.yaml` +For more information on blueprint inputs, refer to the documentation of the [blueprint schema](/docs/blueprint/schema/#input) + +## Using your blueprint via `configuration.yaml` With the bare minimum metadata added, your blueprint is ready to use. @@ -117,11 +133,15 @@ automation tutorial: entity_id: light.kitchen ``` -Reload automations and your new automation should popup. Because we configured the exact values as the original automation, they should work exactly the same. +Reload automations and your new automation should pop up. Because we configured the exact values as the original automation, they should work exactly the same. -## Adding user friendly names to the inputs +## Improving the inputs -Blueprints are easier to use if it's easy to see what each field is used for. We can improve this experience by adding names and descriptions to our inputs: +Blueprints are easier to use if it's easy to see what each field is used for. + +### Add a user friendly names to the inputs + +We can improve this experience by adding names and descriptions to our inputs: ```yaml blueprint: @@ -137,7 +157,7 @@ blueprint: description: The lights to keep in sync. ``` -## Describing the inputs +### Describe the inputs Our blueprint doesn't currently describe what the inputs should contain. Without this information, Home Assistant will offer the user an empty text box. @@ -213,9 +233,10 @@ action: {% endraw %} -## Use it via the UI +## Using the blueprint via the UI -To configure it via the UI, go to **{% my config %}** and then **{% my blueprints %}**. Find the "Motion Light Tutorial" blueprint and click on "Create Automation". +1. To configure your blueprint via the UI, go to {% my blueprints title="**Settings** > **Automations & Scenes** > **Blueprints**" %}. +2. Find the **Motion Light Tutorial** blueprint and select **Create Automation**.
Don't forget to reload automations after you make changes to your blueprint to have the UI and the automation integration pick up the latest blueprint changes. @@ -223,7 +244,8 @@ Don't forget to reload automations after you make changes to your blueprint to h ![Screenshot of the blueprint UI](/images/blueprints/tutorial-ui.png) -### Video Tutorial +## Video Tutorial + This video tutorial explains how to create a blueprint that toggles a light on motion when the lux value is below a certain threshold. @@ -232,18 +254,32 @@ This video tutorial explains how to create a blueprint that toggles a light on m The final step is to share this blueprint with others. For this tutorial we're going to share it on GitHub Gists. -### Informal Sharing +### Share informally For this tutorial, we're going to share it on GitHub Gists. This is a good option if you don't want to publish your blueprint to a larger audience. -- Go to [GitHub Gists](https://gist.github.com/) -- Gist description: blueprint tutorial -- Filename including extension: `motion_light_tutorial.yaml` -- Content is the content of the blueprint file. -- Click the "Create Gist" button - -You can now copy the URL of your new Gist and share it with other people. They can import it by going to **Settings** -> **Automations & Scenes** -> **Blueprints** and clicking on the blue "Import Blueprint" button. +1. Go to [GitHub Gists](https://gist.github.com/) + - **Gist description**: blueprint tutorial + - **Filename including extension**: `motion_light_tutorial.yaml` + - **Content** is the content of the blueprint file. +2. Select **Create Gist**. +3. To share your blueprint with other people, copy the URL of your new Gist. They can import it by going to {% my blueprint_import title="**Settings** > **Automations & Scenes** > **Blueprints**" %} and select **Import blueprint**. +4. Celebrate! Cheers to you. You created your first blueprint and helped someone in the community. ### Share on the Blueprint Exchange If you follow the [Rules and format for posting](/get-blueprints), you can share your blueprint on the Home Assistant Blueprint Exchange forum. This option is accessible to the general Home Assistant community but recommended only for your original blueprints. Please don't post this tutorial to the Blueprint Exchange, but instead, remember this as an option for releasing your real blueprints. + +## Related topics + +**Prerequisites** +- [Editing the configuration file](/docs/configuration/) +- [YAML](/docs/configuration/yaml/), and specifically, [YAML used in automations](/docs/automation/yaml/) +- [Scripts](/docs/scripts/) + +**Blueprints** + +- [Blueprint selectors](/docs/blueprint/selectors/) +- [Blueprint schema](/docs/blueprint/schema/) +- [About blueprints](/docs/blueprint/) +- [Using automation blueprints](/docs/automation/using_blueprints/) \ No newline at end of file diff --git a/source/_docs/configuration/troubleshooting.markdown b/source/_docs/configuration/troubleshooting.markdown index d391d374bf5..9d84665e681 100644 --- a/source/_docs/configuration/troubleshooting.markdown +++ b/source/_docs/configuration/troubleshooting.markdown @@ -104,12 +104,7 @@ The first thing you will need before reporting an issue online is debug logs and ### Enabling Debug Logging -To enable debug logging for an integration, go to **Settings -> Devices & Services** and then click the triple dots for the integration giving you trouble and click **Enable Debug Logging**. - -

- Example of Enable Debug Logging - Example of Enable Debug Logging. -

+To enable debug logging for an integration, go to **Settings** > **Devices & Services** and select the integration. Select the triple dots for the integration giving you trouble and select **Enable Debug Logging**. ### Disable Debug Logging and Download Logs diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index 78e94865803..8a4e2ece122 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -110,7 +110,7 @@ {% active_link /docs/blueprint/ Blueprints %} diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index f640dd7e062..6470455cbb3 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -4,6 +4,7 @@ @@ -28,6 +29,7 @@
diff --git a/source/_includes/common-tasks/define_custom_polling.md b/source/_includes/common-tasks/define_custom_polling.md new file mode 100644 index 00000000000..780ce1764d7 --- /dev/null +++ b/source/_includes/common-tasks/define_custom_polling.md @@ -0,0 +1,32 @@ + + +If you want to define a specific interval at which your device is being polled for data, you can disable the default polling interval and create your own polling service. + +1. Go to {% my integrations title="**Settings** > **Devices & Services**" %}, and select your integration. +2. On the integration entry, select the three dots. + - Then, select **System options** and toggle the button to disable polling. + ![Disable polling for updates](/images/screenshots/custom_polling_01.png) +3. To define your custom polling interval, create an automation. + - Go to {% my automations title="**Settings** > **Automations & Scenes**" %} and create a new automation. + - Define any trigger and condition you like. + - Under action, select **Call service** and use the [`homeassistant.update_entity` service](/integrations/homeassistant/#service-homeassistantupdate_entity). + ![Update entity](/images/screenshots/custom_polling_02.png) + - Example in YAML. + + ```yaml + automation: + - alias: "Only update weather information every 20 minutes when I'm home" + trigger: + - platform: time_pattern + minutes: "/20" + condition: + - condition: state + entity_id: device_tracker.cynthia + state: home + action: + - service: homeassistant.update_entity + target: + entity_id: weather.home + ``` + +4. Save your new automation to poll for data. diff --git a/source/_includes/common-tasks/enable_entities.md b/source/_includes/common-tasks/enable_entities.md index 8ab1aa5f956..25981da8629 100644 --- a/source/_includes/common-tasks/enable_entities.md +++ b/source/_includes/common-tasks/enable_entities.md @@ -8,5 +8,5 @@ Some entities are disabled by default. To enable them, follow these steps: ![Select entity from list](/images/screenshots/enable_entities_01.png) 4. In the pop-up, select the cogwheel. 5. Toggle the **Enabled** button. - ![Enable entities](/images/screenshots/enable_entities_03.png) + ![Enable entities](/images/screenshots/enable_entities_03.png) 6. To save the changes, select **Update**. diff --git a/source/_includes/common-tasks/flashing_n2_otg.md b/source/_includes/common-tasks/flashing_n2_otg.md index 17341baa8b4..d6f46f80d00 100644 --- a/source/_includes/common-tasks/flashing_n2_otg.md +++ b/source/_includes/common-tasks/flashing_n2_otg.md @@ -64,6 +64,7 @@ This will configure the ODROID-N2+ and OTG to act as a memory card reader: 1. Connect the ODROID-N2+ to your PC via the micro-USB port at the front of the ODROID-N2+. 2. When the ODROID-N2 is recognized as a USB connected storage device, you can flash the eMMC with [Etcher](https://www.balena.io/etcher/). - Use the latest stable version of Home Assistant OS for the [ODROID-N2+](https://github.com/home-assistant/operating-system/releases/download/{{site.data.version_data.hassos['odroid-n2']}}/haos_odroid-n2-{{site.data.version_data.hassos['odroid-n2']}}.img.xz) (haos_odroid-n2-{{site.data.version_data.hassos['odroid-n2']}}.img.xz). + - In Balena, use **Flash from file**. **Flash from URL** does not work on all systems. 3. When the flash process is complete, disconnect the ODROID-N2+ from your PC. - Remove the power cable. diff --git a/source/_includes/installation/container/alternative.md b/source/_includes/installation/container/alternative.md index fb2d89db91a..d69f22beba4 100644 --- a/source/_includes/installation/container/alternative.md +++ b/source/_includes/installation/container/alternative.md @@ -4,11 +4,11 @@ As Synology within DSM now supports Docker (with a neat UI), you can simply inst The steps would be: -- Install "Docker" package on your Synology NAS -- Launch Docker-app and move to "Registry"-section +- Install Docker "Container Manager" package on your Synology NAS +- Launch Container Manager-app and move to "Registry"-section - Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "stable" tag. - Wait for some time until your NAS has pulled the image -- Move to the "Image"-section of the Docker-app +- Move to the "Image"-section of the "Container Manager"-app - Click on "Launch" - Within "Network" select "Use same network as Docker Host" and click Next - Choose a container-name you want (e.g., "homeassistant") @@ -48,8 +48,8 @@ Complete the remainder of the Z-Wave configuration by [following the instruction Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following: -- Go to the Docker-app and move to "Registry"-section -- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "stable" tag. +- Go to the "Container Manager"-app and move to "Image"-section +- Find "homeassistant/home-assistant" within Image and click on "Update". - Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar) - Move to "Container"-section - Stop your container if it's running @@ -58,7 +58,7 @@ Remark: to update your Home Assistant on your Docker within Synology NAS, you ju Remark: to restart your Home Assistant within Synology NAS, you just have to do the following: -- Go to the Docker-app and move to "Container"-section +- Go to the "Container Manager"-app and move to "Container"-section - Right-click on it and select "Action"->"Restart".
diff --git a/source/_includes/installation/operating_system.md b/source/_includes/installation/operating_system.md index f9cb5633e20..11ee5885369 100644 --- a/source/_includes/installation/operating_system.md +++ b/source/_includes/installation/operating_system.md @@ -121,10 +121,9 @@ sudo apt install libfuse2 If you are using a [Home Assistant Blue](/blue) or ODROID N2+, you can [attach your device directly](/common-tasks/os/#flashing-an-odroid-n2). {% endif %} 2. Download and start Balena Etcher. You may need to run it with administrator privileges on Windows. -3. Select **Flash from URL**. -![Screenshot of the Etcher software showing flash from URL selected.](/images/installation/etcher1.png) - -4. Copy the URL for the image. If there are multiple links below, make sure to select the correct link for your version of {{site.installation.types[page.installation_type].board}}: +3. Download the image to your computer. + - Copy the URL for the image. + - If there are multiple links below, make sure to select the correct link for your version of {{site.installation.types[page.installation_type].board}}. {% if site.installation.types[page.installation_type].variants.size > 1 %} {% tabbed_block %} {% for variant in site.installation.types[page.installation_type].variants %} @@ -155,17 +154,20 @@ sudo apt install libfuse2 _Select and copy the URL or use the "copy" button that appear when you hover it._ -5. Paste the URL for the {{site.installation.types[page.installation_type].board}} image into Balena Etcher and select **OK**. -![Screenshot of the Etcher software showing the URL bar with a URL pasted in.](/images/installation/etcher2.png) -6. When Balena Etcher has downloaded the image, click **Select target**. -[Screenshot of the Etcher software showing the select target button highlighted.](/images/installation/etcher3.png) + +4. Paste the URL into your browser to start the download. +5. Select **Flash from file** and select the image you just downloaded. + - **Flash from URL** does not work on some systems. + + ![Screenshot of the Etcher software showing flash from URL selected.](/images/installation/etcher1_file.png) +6. **Select target**. +![Screenshot of the Etcher software showing the select target button highlighted.](/images/installation/etcher3.png) 7. Select the boot medium ({{site.installation.types[page.installation_type].installation_media}}) you want to use for your installation. ![Screenshot of the Etcher software showing teh targets available.](/images/installation/etcher4.png) 8. Select **Flash!** to start writing the image. ![Screenshot of the Etcher software showing the Flash button highlighted.](/images/installation/etcher5.png) 9. When Balena Etcher has finished writing the image, you will see a confirmation. ![Screenshot of the Etcher software showing that the installation has completed.](/images/installation/etcher6.png) - - If you are having issues with Balena Etcher, rather than installing from URL, download the file. Then, install from file. ### Start up your {{site.installation.types[page.installation_type].board}} @@ -267,10 +269,11 @@ _All these can be extended if your usage calls for more resources._
By default, VirtualBox does not free up unused disk space. To automatically shrink the vdi disk image - the `discard` option must be enabled: + the `discard` option must be enabled using your host machine's terminal: ```bash VBoxManage storageattach --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on ``` + More details can be found about the command can be found [here](https://www.virtualbox.org/manual/ch08.html#vboxmanage-storageattach).
{% unless page.installation_type == 'macos' %} @@ -360,6 +363,8 @@ _All these can be extended if your usage calls for more resources._ {% endif %} +{% include installation_survey.html %} + With the Home Assistant Operating System installed and accessible, you can continue with onboarding. {% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} diff --git a/source/_includes/installation_survey.html b/source/_includes/installation_survey.html new file mode 100644 index 00000000000..e7d9065798c --- /dev/null +++ b/source/_includes/installation_survey.html @@ -0,0 +1,11 @@ +
+

Help us improve Home Assistant

+ Have you just installed Home Assistant? The Home Assistant team is looking to talk to you to understand how the installation went. +
+ +
+
+

diff --git a/source/_integrations/androidtv_remote.markdown b/source/_integrations/androidtv_remote.markdown index 6b233ddcbf2..d85192c60a9 100644 --- a/source/_integrations/androidtv_remote.markdown +++ b/source/_integrations/androidtv_remote.markdown @@ -20,7 +20,7 @@ ha_platforms: ha_integration_type: device --- -The Android TV Remote integration allows you to control an Android TV and launching apps. For this to work the Android TV device needs to have [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service) which is pre-installed on most devices. +The Android TV Remote integration allows you to control an Android TV and launching apps. For this to work the Android TV device needs to have [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service) which is pre-installed on most devices (Fire TV devices are a notable exception). For a quick introduction on how to get started with Android TV Remote, check out this video: @@ -36,16 +36,17 @@ Using the `media_player.play_media` service, you can launch applications via `De ### Launching apps -You can pass any URL to the device to open it in the built-in browser. Using `Deep Links` you can launch some applications. +You can pass any URL to the device. Using `Deep Links`, you can launch some applications. Examples of some `Deep Links` for popular applications: | App | URL | | --- | --- | -| YouTube | https://www.youtube.com -| Netflix | https://www.netflix.com/title -| Prime Video | https://app.primevideo.com -| Disney+ | https://www.disneyplus.com +| YouTube | `https://www.youtube.com` or `vnd.youtube://` or `vnd.youtube.launch://` +| Netflix | `https://www.netflix.com/title` or `netflix://` +| Prime Video | `https://app.primevideo.com` +| Disney+ | `https://www.disneyplus.com` +| Plex | `plex://` Examples: @@ -157,6 +158,7 @@ Other: - BUTTON_MODE - EXPLORER - MENU +- HOME - INFO - GUIDE - TV_TELETEXT @@ -169,8 +171,6 @@ Other: {% enddetails %} -For a full list see [here](https://github.com/tronikos/androidtvremote2/blob/main/src/androidtvremote2/remotemessage.proto#L90). - If `activity` is specified in `remote.turn_on` it will open the specified URL in the associated app. See [Launching apps section](#launching-apps). Examples of service calls: @@ -220,9 +220,11 @@ Below is an example for you to start with. Many of the buttons support long pres ![Screenshot Android TV Remote example](/images/integrations/androidtv_remote/lovelace_example.png) -{% details "Lovelace example" %} +{% details "YAML Lovelace example" %} +Add a Manual card with the following code. Replace all instances of `living_room_tv` with your entity ID. + - To use the `replace all` functionality, inside the code editor, press `ctrl+F` (or `command+F` on Mac). ```yaml type: vertical-stack @@ -484,3 +486,14 @@ cards: ``` {% enddetails %} + + +## Limitations and known issues + +- The integration doesn't work with Fire TV devices because they are missing the [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service). Attempts to sideload it haven't been successful. +- If you cannot use the Google TV mobile app or the Google Home mobile app to send commands to the device, you cannot send commands with this integration either. +- Commands don't work on Netflix. They don't work from the Google TV mobile app or the Google Home mobile app either. +- Some devices, like Xiaomi, become unavailable after they are turned off and can't be turned on with this integration. +- Some devices experience disconnects every 15 seconds. This is typically resolved by rebooting the Android TV device after the initial setup of the integration. +- If you are not able to connect to the Android TV device, or are asked to pair it again and again, try force-stopping the Android TV Remote Service and clearing its storage. On the Android TV device, go to **settings** > **Apps** > **Show system apps**. Then, select **Android TV Remote Service** > **Storage** > **Clear storage**. You will have to pair again. +- Some onscreen keyboards enabled by TV manufacturers do not support concurrent virtual and onscreen keyboard use. This presents whenever a text field is selected, such as "search" where a constant **use the keyboard on your mobile device** will show, preventing you from opening the onscreen keyboard to type. This can be overcome by either disabling your 3rd party keyboard and using the default Gboard keyboard or by unselecting **Enable IME** in the **Configure** page of the integration. diff --git a/source/_integrations/dsmr.markdown b/source/_integrations/dsmr.markdown index c323a6627b2..51e605caf86 100644 --- a/source/_integrations/dsmr.markdown +++ b/source/_integrations/dsmr.markdown @@ -58,6 +58,7 @@ This integration is known to work for: - Landis+Gyr E350 (DMSR 4) - Landis+Gyr ZCF110 / ZM F110 (DSMR 4.2) - Kaifa E0026 +- Kaifa MA304C (DSMR 4.2) - Kamstrup 382JxC (DSMR 2.2) - Sagemcom XS210 ESMR5 - Sagemcom T211 diff --git a/source/_integrations/goodwe.markdown b/source/_integrations/goodwe.markdown index f940e488780..8791943191c 100644 --- a/source/_integrations/goodwe.markdown +++ b/source/_integrations/goodwe.markdown @@ -38,7 +38,7 @@ The best supported are the inverters of ET/EH families, where the sensors `Meter For the other inverter families, if such sensors are not directly available by the inverter, they can be calculated from existing sensors. [Template Sensor](/integrations/template/) can be used to separate buy and sell power values and [Riemann Sum](/integrations/integration/) can be used to convert these instant power (W) values into cumulative energy values (Wh), which then can be used within the energy dashboard. -## Inverter polling frequency +## Inverter polling interval The integration will poll the inverter for new values every 10 seconds. If you wish to receive fresh inverter data less (or more) frequently, you can disable the automatic refresh in the integration's system options (Enable polling for updates) and create your own automation with your desired polling frequency. @@ -58,3 +58,9 @@ The integration will poll the inverter for new values every 10 seconds. If you w
It has been observed in some rare situations that frequent polling conflicts with updates to the Goodwe SEMS cloud portal and do not receive any updates anymore. Reducing polling frequency to 30 seconds or 1 minute seems to help in such cases.
+ +For more detailed steps on how to define a custom polling interval, follow the procedure below. + +### Defining a custom polling interval + +{% include common-tasks/define_custom_polling.md %} \ No newline at end of file diff --git a/source/_integrations/google_travel_time.markdown b/source/_integrations/google_travel_time.markdown index 160fff7f99f..089f673b8f6 100644 --- a/source/_integrations/google_travel_time.markdown +++ b/source/_integrations/google_travel_time.markdown @@ -30,9 +30,6 @@ Notes: - Origin and Destination can be the address or the GPS coordinates of the location (GPS coordinates have to be separated by a comma). You can also enter an entity ID that provides this information in its state, an entity ID with latitude and longitude attributes, or zone friendly name (case sensitive). -## Manual Polling - -Using automatic polling can lead to calls that exceed your API limit, especially when you are tracking multiple travel times using the same API key. To use more granular polling, disable automated polling in your config entry's System Options. To manually trigger a polling request, call the [`homeassistant.update_entity` service](/integrations/homeassistant/#service-homeassistantupdate_entity) as needed, either manually or via automations. ## Dynamic Configuration @@ -65,7 +62,9 @@ Destination: Eddies House ## Updating sensors on-demand using Automation -You can also use the `homeassistant.update_entity` service to update the sensor on-demand. For example, if you want to update `sensor.morning_commute` every 2 minutes on weekday mornings, you can use the following automation: +Using automatic polling can lead to calls that exceed your API limit, especially when you are tracking multiple travel times using the same API key. To use more granular polling, disable automated polling. + +You can use the `homeassistant.update_entity` service to update the sensor on-demand. For example, if you want to update `sensor.morning_commute` every 2 minutes on weekday mornings, you can use the following automation: ```yaml - id: update_morning_commute_sensor @@ -90,3 +89,9 @@ You can also use the `homeassistant.update_entity` service to update the sensor target: entity_id: sensor.morning_commute ``` + +For more detailed steps on how to define a custom polling interval, follow the procedure below. + +### Defining a custom polling interval + +{% include common-tasks/define_custom_polling.md %} \ No newline at end of file diff --git a/source/_integrations/image.mqtt.markdown b/source/_integrations/image.mqtt.markdown index f2fa9c9ee6e..6d6b19c75bc 100644 --- a/source/_integrations/image.mqtt.markdown +++ b/source/_integrations/image.mqtt.markdown @@ -25,14 +25,8 @@ To enable this image in your installation, add the following to your `configurat ```yaml # Example configuration.yaml entry mqtt: - image: - - topic: zanzito/shared_locations/my-device -``` - -The sample configuration above can be tested by publishing an image to the topic from the console: - -```shell -mosquitto_pub -h -t zanzito/shared_locations/my-device -f + - image: + url_topic: mynas/status/url ``` {% configuration %} @@ -73,7 +67,7 @@ availability_topic: required: false type: string content_type: - description: The content type of and image data message received on `image_topic`. This option cannot be used with the `from_url_topic` because the content type is derived when downloading the image. + description: The content type of and image data message received on `image_topic`. This option cannot be used with the `url_topic` because the content type is derived when downloading the image. required: false type: string default: image/jpeg @@ -180,7 +174,7 @@ url_topic: type: string {% endconfiguration %} -### Example receiving images from from a URL +### Example receiving images from a URL Add the configuration below to your `configuration.yaml`. @@ -195,8 +189,30 @@ mosquitto_pub -h -t mynas/status/url -m "https://design.home-assis ```yaml # Example configuration.yaml entry mqtt: - image: - - from_url_topic: mynas/status/url + - image: + url_topic: mynas/status/url +``` + +{% endraw %} + +### Example receiving images from a file + +Add the configuration below to your `configuration.yaml`. + +To test it, publish an image URL to the topic from the console: + +```shell +mosquitto_pub -h -t mynas/status/file -f +``` + +{% raw %} + +```yaml +# Example configuration.yaml entry +mqtt: + - image: + image_topic: mynas/status/file + content_type: image/png ``` {% endraw %} diff --git a/source/_integrations/inkbird.markdown b/source/_integrations/inkbird.markdown index 6ad2bb41fc2..2dacbd1c3ef 100644 --- a/source/_integrations/inkbird.markdown +++ b/source/_integrations/inkbird.markdown @@ -20,6 +20,7 @@ Integrates [INKBIRD](https://www.inkbird.com/) devices into Home Assistant. ## Supported devices - [INKBIRD Bluetooth Thermometer IBS-TH1](https://inkbird.com/products/bluetooth-thermometer-ibs-th1) +- [INKBIRD Bluetooth Pool Thermometer IBS-P01B](https://inkbird.com/products/bluetooth-pool-thermometer-ibs-p01b) - [INKBIRD Temperature and humidity Hygrometer IBS-TH2](https://inkbird.com/products/hygrometer-ibs-th2) - [INKBIRD Bluetooth Smart Sensor ITH-12S](https://inkbird.com/products/bluetooth-smart-sensor-ith-12s) - [INKBIRD Bluetooth BBQ Thermometer IBT-6XS](https://inkbird.com/products/bluetooth-bbq-thermometer-ibt-6xs) diff --git a/source/_integrations/landisgyr_heat_meter.markdown b/source/_integrations/landisgyr_heat_meter.markdown index f2001e244fb..d34ddf2dbd0 100644 --- a/source/_integrations/landisgyr_heat_meter.markdown +++ b/source/_integrations/landisgyr_heat_meter.markdown @@ -68,8 +68,6 @@ Either heat usage or volume usage can be used as "Gas" on the energy dashboard. Polling is by default done only once per day (and once right after adding the integration). Every time the Heat Meter values are read, battery time of the device will (supposedly) go down by about 30 minutes. -For detailed control on polling and time of polling, consider disabling polling in the integration panel and poll manually. For instructions, see below. - ### Polling manually (optional) For detailed control on when the device is polled, disable the default polling for this integration and create an automation that will update one of the entities (the other entities will be updated as well) @@ -86,3 +84,9 @@ action: target: entity_id: sensor.heat_meter_heat_usage_gj ``` + +For more detailed steps on how to define a custom polling interval, follow the procedure below. + +#### Defining a custom polling interval + +{% include common-tasks/define_custom_polling.md %} \ No newline at end of file diff --git a/source/_integrations/light.markdown b/source/_integrations/light.markdown index 51de2262b40..9afd06bcc89 100644 --- a/source/_integrations/light.markdown +++ b/source/_integrations/light.markdown @@ -113,6 +113,7 @@ Turns one or multiple lights off. | ---------------------- | -------- | ----------- | | `entity_id` | no | String or list of strings that point at `entity_id`s of lights. To target all lights, set `entity_id` to `all`. | `transition` | yes | Integer that represents the time the light should take to transition to the new state in seconds. +| `flash` | yes | Tell light to flash, can be either value `short` or `long`. ### Service `light.toggle` diff --git a/source/_integrations/minecraft_server.markdown b/source/_integrations/minecraft_server.markdown index d2954c9d843..fedf5c1f1a6 100644 --- a/source/_integrations/minecraft_server.markdown +++ b/source/_integrations/minecraft_server.markdown @@ -17,10 +17,14 @@ ha_platforms: ha_integration_type: integration --- -Minecraft servers allow players to play the sandbox video game [Minecraft](https://www.minecraft.net/en-us) by Mojang AB online or via a local area network with other players. The `Minecraft Server` integration lets you retrieve information from a Minecraft server (Java edition) within Home Assistant. +Minecraft servers allow players to play the sandbox video game [Minecraft](https://www.minecraft.net/en-us) by Mojang Studios online or via a local area network with other players. The `Minecraft Server` integration lets you retrieve information from a Minecraft server within Home Assistant.
-The server must be version 1.7 or higher, since older versions don't expose any information. +Minecraft Java edition servers must be version 1.7 or newer, since older versions don't expose any information. +
+ +
+Minecraft Bedrock edition servers are not supported yet.
{% include integrations/config_flow.md %} @@ -35,9 +39,14 @@ This integration provides a binary sensor for the following information from a M This integration provides sensors for the following information from a Minecraft server: -- Latency time +- Latency - Version - Protocol version -- Number of online players (player names are available in state attributes) +- Number of online players + - Including player names list in the state attributes, if available (see note below). - Number of maximum players - World Message / Message of the Day (MOTD) + +
+Depending on the server, the player names list may not be shown completely. Some servers and plugins limit or completely hide this list or even replace the player names with fake ones to show some custom messages there. +
diff --git a/source/_integrations/modbus.markdown b/source/_integrations/modbus.markdown index 3c317c224c5..c027153a2f5 100644 --- a/source/_integrations/modbus.markdown +++ b/source/_integrations/modbus.markdown @@ -1,6 +1,6 @@ --- -title: Modbus -description: Instructions on how to integrate Modbus and platforms. +title: modbus +description: Instructions on how to integrate modbus and platforms. ha_category: - Hub ha_release: pre 0.7 @@ -22,54 +22,52 @@ ha_quality_scale: gold ha_integration_type: integration --- -[Modbus](http://www.modbus.org/) is a serial communication protocol to control PLCs (Programmable Logic Controller) and RTUs (Remote Terminal Unit). The integration adheres strictly to the [protocol specification](https://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf). -Modbus supports all devices adhering to the Modbus standard. The communication between the device(s) can be serial (rs-485), TCP, or UDP connections. The Modbus integration allows multiple communications e.g. serial combined with TCP or different TCP connected devices. +[modbus](http://www.modbus.org/) is a communication protocol to control PLCs (Programmable Logic Controller) and RTUs (Remote Terminal Unit). -# Configuring Modbus +The integration adheres strictly to the [protocol specification](https://modbus.org/docs/modbus_Application_Protocol_V1_1b3.pdf) using [pymodbus](https://github.com/pymodbus-dev/pymodbus) for the actual protocol implmentation. -First, you define how to communicate with your Modbus devices and after that you define the information being exchanged. The Modbus integration allows you to use multiple connections. +The modbus integration supports all devices adhering to the modbus standard. The communication to the device/devices can be serial (rs-485), TCP, or UDP connections. The modbus integration allows multiple communication channels e.g. a serial port connection combined with one or more TCP connections. -## Configuring Modbus common parameters +# Configuring modbus communication -Part of the configuration is common for all types of communication. Add the following to your `configuration.yaml` file: +Configure the modbus communication with modbus devices. This is a general setup needed establish access to the device. -```yaml -modbus: - - name: "hub1" - close_comm_on_error: true - delay: 5 - timeout: 5 - type: tcp -``` +The modbus integration allows you to use multiple connections each with multiple sensors etc. + +The modbus integration provides a number of parameters to help communicate with "difficult" devices, these parameters are independent of the type of communication. {% configuration %} close_comm_on_error: - description: Determines if the device connection is closed when an error occurs, default is true. Some serial-rs485 adapters deliver garble when opened, this leads to a disconnect and a new connect, which can continue. If in a running communication the debug log contains a message from pymodbus, with the text "cleaning....", then try this parameter. + description: "Close connection when an error occurs. + Some serial-rs485 adapters deliver garble when opened, this leads to a disconnect and a new connect, which can continue. + If the log contains a message from pymodbus, with the text 'cleaning....', then try this parameter." required: false default: true type: boolean delay: - description: "Time to delay sending messages in seconds after connecting. Some Modbus devices need a delay of typically 1-2 seconds after established connection to prepare the communication. If a device does not respond to messages after connecting, this parameter might help. Remark: the delay is solely between connect and the first message." + description: "Time to delay sending messages in seconds after connecting. + Some modbus devices need a delay of typically 1-2 seconds after connection is established to prepare the communication. + If a device does not respond to messages after connecting, then try this parameter. + **Remark:** solely affect the first message." required: false default: 0 type: integer message_wait_milliseconds: - description: Time to wait in milliseconds between requests. + description: "Time to wait in milliseconds between requests." required: false - default: 30 for serial connection, 0 for everything else. + default: 30 for serial connection, 0 for all other connections. type: integer name: - description: Name for this hub. Must be unique, so it is required when setting up multiple instances. - required: false - default: "modbus_hub" + description: "Name of this hub. Must be unique." + required: true type: string retries: - description: Number of times to retry a request. + description: "Number of times to retry a request." required: false default: 3 type: integer retry_on_empty: - description: Retry request, when receiving and empty message. + description: "Retry request, when receiving an empty message." required: false default: false type: boolean @@ -79,317 +77,666 @@ timeout: default: 5 type: integer type: - description: Type of communication. Possible values are `tcp` Modbus messages with Modbus TCP frame on TCP/IP, `udp` Modbus messages with Modbus TCP frame on UDP, `rtuovertcp` Modbus messages with a wrapper TCP/IP simulating a serial line, `serial` Modbus serial (RS485). + description: "Type of modbus." required: true - type: string + type: list + keys: + tcp: + description: "TCP/IP connection with socket framer, used with Ethernet enabled devices." + udp: + description: "UDP connection with socket framer, rarely used." + rtuovertcp: + description: "TCP/IP connection with rtu framer, used when connection to modbus forwarders." + serial: + description: "Serial connection with RTU framer, used with TTY port or USB rs485 converter." + {% endconfiguration %} -## Configuring network connection +## Configuring tcp connection -For a network (type: `tcp`/`udp`/`rtuovertcp`) connection, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-modbus-common-parameters): +`type: tcp` is required. Used for devices providing a TCP/IP interface directly. + +{% configuration %} +host: + description: "IP address or name of your modbus device, e.g., `192.168.1.1`." + required: true + type: string +port: + description: "Network port for the communication." + required: true + type: integer + +{% endconfiguration %} + +### Example: typical tcp configuration ```yaml -# Example configuration.yaml entry for a TCP connection +# Example yaml: typical tcp connection modbus: - - name: "hub1" + - name: modbus_hub type: tcp host: IP_ADDRESS port: 502 ``` +### Example: full tcp configuration + +```yaml +# Example yaml: full tcp connection +modbus: + - name: modbus_hub + type: tcp + host: IP_ADDRESS + port: 502 + + close_comm_on_error: true + delay: 0 + message_wait_milliseconds: 30 + retries: 3 + retry_on_empty: false + timeout: 5 +``` + +## Configuring a TCP-RTU connection + +`type: rtuovertcp` is required. Used for devices providing a TCP/IP interface directly. + +This is typically used, when communicating with a modbus-forwarder, a device that +has a TCP/IP connection upwards, and one or more serial connections downwards. lets also +write more here, to see if the error moves. + {% configuration %} host: - description: The IP address of your Modbus device, e.g., `192.168.1.1`. + description: "IP address or name of your modbus device, e.g., `192.168.1.1`." required: true type: string port: - description: The network port for the communication. + description: "Network port for the communication." required: true type: integer -type: - description: "Type of the connection to Modbus, needs to be `tcp` or `udp` or `rtuovertcp` for this setup." + +{% endconfiguration %} + +### Example: typical TCP-RTU configuration + +```yaml +# Example yaml: typical tcp-rtu connection +modbus: + - name: modbus_hub + type: rtuovertcp + host: IP_ADDRESS + port: 502 +``` + +### Example: full TCP-RTU configuration + +```yaml +# Example yaml: full tcp-rtu connection +modbus: + - name: modbus_hub + type: rtuovertcp + host: IP_ADDRESS + port: 502 + + close_comm_on_error: true + delay: 0 + message_wait_milliseconds: 30 + retries: 3 + retry_on_empty: false + timeout: 5 +``` + +## Configuring a UDP connection + +`type: udp` is required. This is rarely used, and only for very special configurations. + +{% configuration %} +host: + description: "IP address or name of your modbus device, e.g., `192.168.1.1`." required: true type: string +port: + description: "Network port for the communication." + required: true + type: integer + {% endconfiguration %} +### Example: typical udp configuration + +```yaml +# Example yaml: typical udp connection +modbus: + - name: modbus_hub + type: udp + host: IP_ADDRESS + port: 502 +``` + +### Example: full UDP configuration + +```yaml +# Example yaml: full udp connection +modbus: + - name: modbus_hub + type: udp + host: IP_ADDRESS + port: 502 + + close_comm_on_error: true + delay: 0 + message_wait_milliseconds: 30 + retries: 3 + retry_on_empty: false + timeout: 5 +``` + ## Configuring serial connection -For a serial connection, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-modbus-common-parameters): +`type: serial` is required. This is used for devices providing a serial rs485 interface. + +The physical interface is typically a USB serial-rs485 converter or an rs232-rs485 connected to a serial port. + +{% configuration %} +baudrate: + description: "Speed of the serial connection, higher speed gives better performance." + required: true + type: integer +bytesize: + description: "Data size in bits of each byte." + required: true + type: list + keys: + "5": + description: "5 bit for data, rarely used." + "6": + description: "6 bit for data, rarely used." + "7": + description: "7 bit for data, used for very old devices." + "8": + description: "8 bit for data, standard." +method: + description: "Method of the connection to modbus." + required: true + type: list + keys: + rtu: + description: "Binary data transmission preceded by slave id and followed by a crc, standard." + ascii: + description: "ASCII data transmission preceded by slave id and followed by a crc, used for few devices." +parity: + description: "Parity of the data bytes." + required: true + type: list + keys: + E: + description: "Even parity bit." + O: + description: "Odd parity bit." + N: + description: "No parity bit, standard." +port: + description: "Serial port or USB device where your modbus device is connected to your Home Assistant host." + required: true + type: string +stopbits: + description: "Stopbits of the data bytes." + required: true + type: list + keys: + '1': + description: "1 stop bit." + '2': + description: "2 stop bits, standard." + +{% endconfiguration %} + +### Example: typical serial configuration ```yaml -# Example configuration.yaml entry for a serial connection +# Example yaml: typical serial connection modbus: - - name: hub1 + - name: modbus_hub type: serial + port: /dev/ttyUSB0 baudrate: 9600 bytesize: 8 method: rtu parity: E - port: /dev/ttyUSB0 stopbits: 1 ``` -{% configuration %} -baudrate: - description: The speed for the serial connection. - required: true - type: integer -bytesize: - description: "The bytesize for the serial connection; can be `5`, `6`, `7` or `8`." - required: true - type: integer -method: - description: "Method of the connection to Modbus, either `rtu` or `ascii`." - required: true - type: string -parity: - description: "The parity for the serial connection; can be `E`, `O` or `N`." - required: true - type: string -port: - description: The port where your Modbus device is connected to your Home Assistant host. - required: true - type: string -stopbits: - description: "The stopbits for the serial connection, either `1` or `2`." - required: true - type: integer -type: - description: "Type of the connection to Modbus, needs to be `serial` for this setup." - required: true - type: string -{% endconfiguration %} +### Example: full serial configuration + +```yaml +# Example yaml: full udp connection +modbus: + - name: modbus_hub + type: serial + port: /dev/ttyUSB0 + baudrate: 9600 + bytesize: 8 + method: rtu + parity: E + stopbits: 1 + + close_comm_on_error: true + delay: 0 + message_wait_milliseconds: 30 + retries: 3 + retry_on_empty: false + timeout: 5 +``` + ## Configuring multiple connections -Multiple connections are possible with identical/different `type:`. +Multiple connections can freely mix different communications: ```yaml -# Example configuration.yaml entry for multiple TCP connections +# Example yaml: multiple tcp connections modbus: - - type: tcp + - name: modbus_hub + type: tcp host: IP_ADDRESS_1 port: 2020 - name: "hub1" - - type: udp + - name: modbus_hub2 + type: tcp host: IP_ADDRESS_2 - port: 501 - name: hub2 + port: 502 ``` -Remark: `name:`is required for multiple connections, because it needs to be unique. - -## Modbus services - -The Modbus integration provides two generic write services in addition to the platform-specific services. - -| Service | Description | -| ------- | ----------- | -| modbus.write_register | Write register or registers | -| modbus.write_coil | Write coil or coils | - -Description: - -| Attribute | Description | -| --------- | ----------- | -| hub | Hub name (defaults to 'modbus_hub' when omitted) | -| unit | Slave address (0-255), alternative to slave | -| slave | Slave address (0-255), alternative to unit | -| address | Address of the Register (e.g. 138) | -| value | (write_register) A single value or an array of 16-bit values. Single value will call modbus function code 0x06. Array will call modbus function code 0x10. Values might need reverse ordering. E.g., to set 0x0004 you might need to set `[4,0]`, this depend on the byte order of your CPU | -| state | (write_coil) A single boolean or an array of booleans. Single boolean will call modbus function code 0x05. Array will call modbus function code 0x0F | - -The Modbus integration also provides communication stop/restart services. These services will not do any reconfiguring, but simply stop/start the modbus communication layer. - -| Service | Description | -| ------- | ----------- | -| modbus.stop | Stop communication | -| modbus.restart | Restart communication (Stop first if running) | - -Description: - -| Attribute | Description | -| --------- | ----------- | -| hub | Hub name (defaults to 'modbus_hub' when omitted) | - -### Example: writing a float32 type register - -To write a float32 datatype register use network format like `10.0` == `0x41200000` (network order float hexadecimal). ```yaml -service: modbus.write_register -data: - address: - unit: - hub: - value: [0x4120, 0x0000] -``` - -# configure Modbus platforms - -Modbus platform entities are configured within the Modbus configuration. - -## Configuring platform common parameters - -All modbus platforms share a set of common parameters. - -```yaml -# Example configuration.yaml entry for platform common parameters +# Example yaml: tcp connection and serial connection modbus: - - type: tcp + - name: modbus_hub + type: tcp host: IP_ADDRESS_1 port: 2020 - name: "hub1" - sensors: - - name: sensor1 - scan_interval: 999 - slave: 0 + + - name: modbus_hub2 + type: serial + port: /dev/ttyUSB0 + baudrate: 9600 + bytesize: 8 + method: rtu + parity: E + stopbits: 1 ``` +# Configuring modbus entities + +modbus entities are grouped below each modbus communication entry. + +All modbus entities have the following parameters: + {% configuration %} +address: + description: "Address of coil/register." + required: true + type: integer lazy_error_count: - description: Number of messages with error received before setting entity to unavailable. This parameter can be used to prevent spontaneous errors to ruin statistic graphs. + description: "Number of errors before entity becomes unavailable. + Is used to prevent spontaneous errors affecting statistic graphs. + A succesfull request resets the error count." required: false type: integer default: 0 name: - description: Name for the platform entity which must be unique within the platform. + description: "Name of the entity which must be unique within the entity type." required: true type: string scan_interval: - description: Defines the update interval of the entity in seconds, if scan_interval = 0 polling is stopped. Entities are unavailable until the first response is received, except for entities with scan_interval = 0, these entities are available from startup. + description: "Update interval in seconds. + scan_interval = 0 for no polling. + Entities are unavailable until the first scan interval is passed, + except for entities with scan_interval = 0, which are read at startup and not updated." required: false type: integer default: 15 slave: - description: The number of the slave. + description: "Id of the device. Used to address multiple devices on a rs485 bus or devices connected to a modbus repeater." required: false type: integer default: 0 unique_id: - description: An ID that uniquely identifies this sensor. Slaves will be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception. + description: "ID that uniquely identifies this entity. + Slaves will be given a unique_id of <>_<>. + If two enities have the same unique ID, Home Assistant will raise an exception." required: false type: string + {% endconfiguration %} -### Configuring data_type and struct - -Climate and Sensor share setup of data_type and struct. +## Example: entities grouping ```yaml -# Example configuration.yaml entry for platform common parameters +# Example yaml: entities grouping modbus: - type: tcp host: IP_ADDRESS_1 port: 2020 - name: "hub1" + name: "modbus_hub" + binary_sensors: + - name: binary_sensor1 + address: 100 + climates: + - name: "Watlow F4T" + address: 200 + covers: + - name: Door1 + address: 300 + fans: + - name: Fan1 + address: 400 + lights: + - name: light1 + address: 500 sensors: - name: sensor1 - data_type: int + address: 600 + switches: + - name: Switch1 + address: 700 ``` -{% configuration %} -data_type: - description: Response representation (int8, int16, int32, int64, uint8, uint16, uint32, uint64, float16, float32, float64, string). `int/uint`are silently converted to `int16/uint16`. - required: false - type: string - default: int16 -offset: - description: Final offset (output = scale * value + offset). - required: false - type: float - default: 0 -precision: - description: Number of valid decimals. - required: false - type: integer - default: 0 -scale: - description: Scale factor (output = scale * value + offset). - required: false - type: float - default: 1 -structure: - description: "If `data_type` is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: `>i`." - required: false - type: string - default: ">f" -swap: - description: "Swap the order of bytes/words, options are `none`, `byte`, `word`, `word_byte`." - required: false - default: none - type: string -unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string -{% endconfiguration %} +The different types of entities are detailed in the following. -## Configuring platform binary sensor +## Configuring binary sensor entities The Modbus binary sensor allows you to gather data from coils which as per standard have state ON/OFF. -To use your Modbus binary sensors in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters): +Normally, a register contains 16 coils, giving different addresses depending on the request used. ```yaml -# Example configuration.yaml entry for binary_sensor configuration +Register 512: Coil 1 - 16 +Register 513: Coil 17 - 32 +``` + +`input_type: coils` would use addresses from 1 through 32, while `input_type: input` would use addresses 512 and 513. +For that reason, many devices (especially older ones) do not share the coil address space with the register address space, +and this `input` would read from a different address space than `coil`. The problem is present in devices with +shared address space and are a frequent cause of problems when configuring entities. + + +{% configuration %} +binary_sensors: + description: "A list of all binary sensors configured for this connection." + required: false + type: map + keys: + device_class: + description: "The [type/class](/integrations/binary_sensor/#device-class) to be used for the UI." + required: false + type: string + input_type: + description: "Type of request `discrete_input`, `coil`, `holding` or `input`" + required: false + default: coil + type: string + slave_count: + description: "Generate count+1 binary sensors (master + slaves). + Addresses are automatically incremented. + The parameter simplifies configuration and provides a much better performance by not using count+1 requests but a single request." + required: false + type: integer + unique_id: + description: "ID that uniquely identifies the entity. Slaves will automatically be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception." + required: false + type: string + +{% endconfiguration %} + +### Example: typical binary sensor configuration + +```yaml +# Example yaml: typical binary_sensor modbus: - name: hub1 type: tcp host: IP_ADDRESS port: 502 binary_sensors: - - name: "binary_sensor1" + - name: my_relay address: 100 - scan_interval: 20 slave: 1 - - name: "binary_sensor2" - address: 110 - device_class: door - input_type: discrete_input - - name: "binary_sensor3" - address: 120 - slave: 2 - device_class: running - scan_interval: 10 - input_type: input ``` + +### Example: full binary sensor configuration + +```yaml +# Example yaml: binary_sensor with all options +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + binary_sensors: + - name: my_relay + address: 100 + device_class: door + input_type: coil + lazy_error_count: 0 + scan_interval: 15 + slave: 1 + slave_count: 0 + unique_id: my_relay +``` + +### Example: multiple identical binary sensor configuration + +```yaml +# Example of 10 identical binary_sensor +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + binary_sensors: + - name: my_relay + address: 100 + slave: 1 + slave_count: 10 + unique_id: my_relay +``` + +This configuration will poll coil addresses 100 to 110 every 15 seconds and update the binary_sensors: `my_relay` +and `my_relay_1` to `my_relay_10`. + +The master configuration like device_class are automatically copied to the slaves. + +## Configuring climate entities + +The Modbus climate platform allows you to monitor a thermostat or heaters as well as set a target temperature. + {% configuration %} -binary_sensors: - description: A list of all binary_sensors available in this modbus instance, omit if there are no binary_sensors. +climates: + description: "A list of all climate entities in this modbus instance." required: false - type: [map] + type: map keys: - address: - description: Address of the Register. + count: + description: "Number of registers to read. + **only valid for `data_type: custom` and `data_type: string`**, for other data types count is automatically calculated." + required: false + type: integer + data_type: + description: "Response representation." + required: false + default: int16 + type: list + keys: + custom: + description: "user defined format, `structure:` and `count:` must be configured." + float16: + description: "16 bit signed float (1 register holds 1 value)." + float32: + description: "32 bit signed float (2 registers holds 1 value)." + float64: + description: "64 bit signed float (4 register holds 1 value)." + int: + description: "**DEPRECATED** is silently converted to `int16`" + int8: + description: "8 bit signed integer (1 register holds 1 value in lower byte)." + int16: + description: "16 bit signed integer (1 register holds 1 value)." + int32: + description: "32 bit signed integer (2 registers holds 1 value)." + int64: + description: "64 bit signed integer (4 registers holds 1 value)." + string: + description: "set of 8 bit characters, `count:` must be configured." + uint: + description: "**DEPRECATED** is silently converted to `uint16`" + uint8: + description: "8 bit unsigned integer (1 register holds 1 value in lower byte)." + uint16: + description: "16 bit unsigned integer (1 register holds 1 value)." + uint32: + description: "32 bit unsigned integer (2 registers holds 1 value)." + uint64: + description: "64 bit unsigned integer (4 registers holds 1 value)." + hvac_mode_register: + description: "Configuration of register for HVAC mode" + required: false + type: map + keys: + address: + description: "Address of HVAC mode register." + required: true + type: integer + write_registers: + description: "Request type, use `write_registers` if true else `write_register`." + required: false + type: boolean + default: false + values: + description: "Mapping between the register values and HVAC modes" + required: true + type: map + keys: + state_off: + description: "Value corresponding to HVAC Off mode." + required: false + type: integer + state_heat: + description: "Value corresponding to HVAC Heat mode." + required: false + type: integer + state_cool: + description: "Value corresponding to HVAC Cool mode." + required: false + type: integer + state_auto: + description: "Value corresponding to HVAC Auto mode." + required: false + type: integer + state_dry: + description: "Value corresponding to HVAC Dry mode." + required: false + type: integer + state_fan_only: + description: "Value corresponding to HVAC Fan only mode." + required: false + type: integer + state_heat_cool: + description: "Value corresponding to HVAC Heat/Cool mode." + required: false + type: integer + hvac_onoff_register: + description: "Address of On/Off state. + When zero is read from this register, the HVAC state is set to Off, otherwise the `hvac_mode_register` + dictates the state of the HVAC. If no such register is defined, it defaults to Auto. + When the HVAC mode is set to Off, the value 0 is written to the register, otherwise the + value 1 is written." + required: false + type: integer + input_type: + description: Modbus register type for current temperature. + required: false + default: holding + type: list + keys: + holding: + description: "Holding register." + input: + description: "Input register." + max_temp: + description: "Maximum setpoint temperature." + required: false + type: integer + default: 35 + min_temp: + description: "Minimum setpoint temperature." + required: false + type: integer + default: 5 + offset: + description: "Final offset (output = scale * value + offset)." + required: false + type: float + default: 0 + precision: + description: "Number of valid decimals." + required: false + type: integer + default: 0 + scale: + description: "Scale factor (output = scale * value + offset)." + required: false + type: float + default: 1 + structure: + description: "If `data_type: custom` is specified a double-quoted Python struct is expected, + to format the string to unpack the value. See Python documentation for details. + Example: `>i`." + required: false + type: string + default: ">f" + swap: + description: "Swap the order of bytes/words, **not valid with `custom` and `datatype: string`**" + required: false + default: none + type: list + keys: + none: + description: "No swapping." + byte: + description: "Swap bytes AB -> BA." + word: + description: "Swap word ABCD -> CDAB, **not valid with data types: `int8`, `uint8`, `int16`, `uint16`**" + word_byte: + description: "Swap word ABCD -> DCBA, **not valid with data types: `int8`, `uint8`, `int16`, `uint16`**" + target_temp_register: + description: "Register address for target temperature (Setpoint)." required: true type: integer - device_class: - description: The [type/class](/integrations/binary_sensor/#device-class) to be used for the UI (e.g. "door"). + temp_step: + description: "Step size target temperature." required: false - type: string - input_type: - description: type of address (discrete_input/coil/holding/input) + type: float + default: 0.5 + temperature_unit: + description: "Temperature unit reported by current_temp_register. C or F." required: false - default: coil - type: string - unique_id: - description: An ID that uniquely identifies this sensor. Slaves will be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception. + default: C + type: list + keys: + C: + description: "Celsius" + F: + description: "Fahrenheit" + write_registers: + description: "Request type, use `write_registers` if true else `write_register`." required: false - type: string - slave_count: - description: Generates x-1 slave binary sensors, allowing read of multiple coils with a single read messsage. - required: false - type: integer + type: boolean + default: false {% endconfiguration %} -## Configuring platform climate - -The Modbus climate platform allows you to monitor your thermostat as well as set a target temperature. - -To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters) and [response regresentation](#configuring-data_type-and-struct): +### Example: climate configuration ```yaml # Example configuration.yaml entry @@ -414,152 +761,9 @@ modbus: target_temp_register: 2782 temp_step: 1 temperature_unit: C - - name: "Bedroom Air Condition" - address: 10 - target_temp_register: 10 - hvac_mode_register: - address: 11 - values: - state_auto: 0 - state_cool: 1 - state_heat: 2 - state_fan_only: 3 - state_dry: 4 - state_off: 5 - write_registers: true - hvac_onoff_register: 11 - write_registers: true ``` -{% details "Previous configuration format" %} - -The configuration format of `hvac_mode_register` has changed. The old format uses keys such as `off`, `auto`, `cool` instead of `state_off`, `state_auto` and `state_cool` that is currently used. The old keys should no longer be used and is deprecated. - -{% enddetails %} - -{% configuration %} -climates: - description: A list of all climates available in this modbus instance. - required: false - type: [map] - keys: - address: - description: Register address for current temperature (process value). - required: true - type: integer - count: - description: Number of registers to read. - required: false - type: integer - default: 1 or calculated if data_type is not `struct`. - input_type: - description: Modbus register type (`holding`, `input`) for current temperature. - required: false - type: string - default: holding - max_temp: - description: Maximum setpoint temperature. - required: false - type: integer - default: 35 - min_temp: - description: Minimum setpoint temperature. - required: false - type: integer - default: 5 - target_temp_register: - description: Register address for target temperature (Setpoint). - required: true - type: integer - temp_step: - description: The supported step size a target temperature can be increased/decreased. - required: false - type: float - default: 0.5 - temperature_unit: - description: Temperature unit reported by the current_temp_register. C or F - required: false - type: string - default: C - hvac_mode_register: - description: Definition of a register holding and controlling an HVAC mode - required: false - type: [map] - keys: - address: - description: The address of the HVAC mode register. - required: true - type: integer - write_registers: - description: if true use write_registers - required: false - type: boolean - default: false - values: - description: A mapping between the register values and HVAC modes - required: true - type: [map] - keys: - state_off: - description: The register value corresponding to HVAC Off mode. - required: false - type: integer - state_heat: - description: The register value corresponding to HVAC Heat mode. - required: false - type: integer - state_cool: - description: The register value corresponding to HVAC Cool mode. - required: false - type: integer - state_auto: - description: The register value corresponding to HVAC Auto mode. - required: false - type: integer - state_dry: - description: The register value corresponding to HVAC Dry mode. - required: false - type: integer - state_fan_only: - description: The register value corresponding to HVAC Fan only mode. - required: false - type: integer - state_heat_cool: - description: The register value corresponding to HVAC Heat/Cool mode. - required: false - type: integer - hvac_onoff_register: - description: Address of a register holding and controlling the On/Off state of the climate device. - When zero is read from this register, the HVAC state is set to Off, otherwise the `hvac_mode_register` - dictates the state of the HVAC. If no such register is defined, it defaults to Auto. - When the HVAC mode is set to Off, the value 0 is written to the register, otherwise the - value 1 is written. - required: false - type: integer - write_registers: - description: if true use write_registers for hvac_onoff. - required: false - type: boolean - default: false - unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string -{% endconfiguration %} - -### Service `modbus.set-temperature` - -| Service | Description | -| ------- | ----------- | -| set_temperature | Set Temperature. Requires `value` to be passed in, which is the desired target temperature. `value` should be in the same type as `data_type` | - -### Service `modbus.set_hvac_mode` - -| Service | Description | -| ------- | ----------- | -| set_hvac_mode | Set HVAC mode. Requires `value` to be passed in, which is the desired mode. `value` should be a valid HVAC mode. A mapping between the desired state and the value to be written to the HVAC mode register must exist. Calling this service will also set the On/Off register to an appropriate value, if such a register is defined. | - -## Configuring platform cover +## Configuring cover entities The `modbus` cover platform allows you to control covers (such as blinds, a roller shutter, or a garage door). @@ -567,9 +771,73 @@ At the moment, platform cover support the opening and closing of a cover. You ca Cover that uses `input_type: coil` is not able to determine intermediary states such as opening and closing. Coil stores only two states — "0" means cover closed, and "1" implies cover open. To allow detecting intermediary states, there is an optional `status_register` attribute. It will enable you to write your command (e.g., to open a cover) into a coil, and read current cover status back through the register. Additionally, you can specify values for `state_open`, `state_opening`, `state_closed`, and `state_closing` attributes. These will be matched with the value read from the `status_register`. -If your cover uses ìnput_type: holding` (default) to send commands, it can also read the intermediary states. To adjust which value represents what state, you can fine-tune the optional state attributes, like `state_open`. These optional state values are also used for specifying values written into the register. If you specify an optional status_register attribute, cover states will be read from status_register instead of the register used for sending commands. +If your cover uses `input_type: holding` (default) to send commands, it can also read the intermediary states. To adjust which value represents what state, you can fine-tune the optional state attributes, like `state_open`. These optional state values are also used for specifying values written into the register. If you specify an optional status_register attribute, cover states will be read from status_register instead of the register used for sending commands. -To use Modbus covers in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters): +{% configuration %} +covers: + description: "A list of all cover entities configured for this connection." + required: true + type: map + keys: + device_class: + description: "The [type/class](/integrations/cover/#device-class) of the cover to set the icon in the frontend." + required: false + type: device_class + default: None + input_type: + description: "Cover register type." + default: holding + required: false + type: list + keys: + holding: + description: "Holding register." + input: + description: "Input register." + state_open: + description: "A value in `status_register` or `register` representing an open cover. + If your configuration uses the `register` attribute, this value will be written into the holding register to open the cover." + required: false + default: 1 + type: integer + state_closed: + description: "A value in `status_register` or `register` representing a closed cover. + If your configuration uses the `register` attribute, this value will be written into the holding register to close the cover." + required: false + default: 0 + type: integer + state_opening: + description: "A value in `status_register` or `register` representing an opening cover. + Note that this state should be also supported on your connected Modbus cover. + If it won't report the state, this state won't be detected." + required: false + default: 2 + type: integer + state_closing: + description: "A value in `status_register` or `register` representing a closing cover. + Note that this state should be also supported on your connected Modbus cover. + If it will not report the state, this state won't be detected." + required: false + default: 3 + type: integer + status_register: + description: "Address of register, from which all the cover states will be read. + If you specified `register` attribute, and not `status_register` attribute, + your main register will also be used as a status register." + required: false + type: integer + status_register_type: + description: Cover status register type (holding, input), default holding. + required: false + type: list + keys: + holding: + description: "Holding register." + input: + description: "Input register." +{% endconfiguration %} + +### Example: Modbus cover ```yaml # Example configuration.yaml entry @@ -593,59 +861,6 @@ modbus: address: 118 ``` -{% configuration %} -covers: - description: The array contains a list of all your Modbus covers. - required: true - type: map - keys: - address: - description: Address of `coil` / `register`. - required: true - type: integer - device_class: - description: The [type/class](/integrations/cover/#device-class) of the cover to set the icon in the frontend. - required: false - type: device_class - default: None - input_type: - description: Modbus register type (holding, input), default holding. - default: holding - required: false - type: string - state_open: - description: A value in `status_register` or `register` representing an open cover. If your configuration uses the `register` attribute, this value will be written into the holding register to open the cover. - required: false - default: 1 - type: integer - state_closed: - description: A value in `status_register` or `register` representing a closed cover. If your configuration uses the `register` attribute, this value will be written into the holding register to close the cover. - required: false - default: 0 - type: integer - state_opening: - description: A value in `status_register` or `register` representing an opening cover. Note that this state should be also supported on your connected Modbus cover. If it won't report the state, this state won't be detected. - required: false - default: 2 - type: integer - state_closing: - description: A value in `status_register` or `register` representing a closing cover. Note that this state should be also supported on your connected Modbus cover. If it won't reeport the state, this state won't be detected. - required: false - default: 3 - type: integer - status_register: - description: An address of a register, from which all the cover states will be read. If you specified `register` attribute, and not `status_register` attribute, your main register will also be used as a status register. - required: false - type: integer - status_register_type: - description: Modbus register type (holding, input), default holding. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string -{% endconfiguration %} ### Example: Modbus cover controlled by a coil @@ -739,13 +954,85 @@ modbus: state_closed: 0 ``` - - -## Configuring platform fan +## Configuring fan entities The `modbus` fan platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. -To use your Modbus fans in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters): + +{% configuration %} +fans: + description: "A list of all fan entities in this modbus instance." + required: true + type: map + keys: + command_on: + description: "Value to write to turn on the fan." + required: false + default: 0x01 + type: integer + command_off: + description: "Value to write to turn off the fan." + required: false + default: 0x00 + type: integer + write_type: + description: Type of write request. + required: false + default: holding + type: list + keys: + holding: + description: "write_register is called." + holdings: + description: "write_registers is called." + coil: + description: "write_coil is called." + coils: + description: "write_coils is called." + verify: + description: "Read from Modbus device to verify fan. + If used without attributes, it uses the toggle register configuration. + If omitted, no verification is done, but the state of the fan is set with each toggle." + required: false + type: map + keys: + address: + description: "Address to read from." + required: false + default: write address + type: integer + delay: + description: "Delay between write and verify." + required: false + default: 0 + type: integer + input_type: + description: Type of address. + required: false + default: same as `write_type` + type: list + keys: + coil: + description: "Coil (1bit relay)." + discrete: + description: "Discret input (1bit relay)." + holding: + description: "Holding register." + input: + description: "Input register." + state_on: + description: "Value when the fan is on." + required: false + default: same as `command_on` + type: integer + state_off: + description: "Value when the fan is off." + required: false + default: same as `command_off` + type: integer +{% endconfiguration %} + +### Example: fan configuration ```yaml # Example configuration.yaml entry @@ -773,44 +1060,51 @@ modbus: state_off: 1 ``` +## Configuring light entities + +The `modbus` light platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. + {% configuration %} -fans: - description: The array contains a list of all your Modbus fans. +lights: + description: "A list of all light entities in this modbus instance." required: true type: map keys: - address: - description: Coil number or register. - required: true - type: integer command_on: - description: Value to write to turn on the fan. + description: "Value to write to turn on the light." required: false default: 0x01 type: integer command_off: - description: Value to write to turn off the fan. + description: "Value to write to turn off the light." required: false default: 0x00 type: integer write_type: - description: Type of address (holding/coil or holdings/coils for array call). + description: "Type of write request." required: false default: holding - type: string - name: - description: Name of the fan. - required: true - type: string + type: list + keys: + holding: + description: "write_register is called." + holdings: + description: "write_registers is called." + coil: + description: "write_coil is called." + coils: + description: "write_coils is called." verify: - description: Read from Modbus device to verify fan. If used without attributes it uses the toggle register configuration. If omitted no verification is done, but the state of the fan is set with each toggle. + description: "Read from Modbus device to verify the light. + If used without attributes, it uses the toggle register configuration. + If omitted no verification, is done, but the state of the light is set with each toggle." required: false type: map keys: address: - description: Address to read from. + description: "Address to read from." required: false - default: write address + default: "Same as `address`" type: integer delay: description: delay between write and verify. @@ -820,29 +1114,31 @@ fans: input_type: description: Type of address (holding/coil/discrete/input). required: false - default: write_type - type: integer + default: "Same as `write_type`" + type: list + keys: + coil: + description: "Coil (1bit relay)." + discrete: + description: "Discrete inout (1bit relay)." + holding: + description: "Holding register." + input: + description: "Input register." state_on: - description: Value when the fan is on. + description: "Value when the light is on." required: false - default: same as command_on + default: "Same as `command_on`" type: integer state_off: - description: Value when the fan is off. + description: "Value when the light is off." required: false - default: same as command_off + default: "Same as `command_off`" type: integer - unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string + {% endconfiguration %} -## Configuring platform light - -The `modbus` light platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. - -To use your Modbus lights in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters): +### Example: light configuration ```yaml # Example configuration.yaml entry @@ -870,72 +1166,154 @@ modbus: state_off: 1 ``` -{% configuration %} -lights: - description: The array contains a list of all your Modbus lights. - required: true - type: map - keys: - address: - description: Coil number or register. - required: true - type: integer - command_on: - description: Value to write to turn on the fan. - required: false - default: 0x01 - type: integer - command_off: - description: Value to write to turn off the light. - required: false - default: 0x00 - type: integer - write_type: - description: Type of address (holding/coil or holdings/coils for array call). - required: false - default: holding - type: string - verify: - description: Read from Modbus device to verify the light. If used without attributes it uses the toggle register configuration. If omitted no verification is done, but the state of the light is set with each toggle. - required: false - type: map - keys: - address: - description: Address to read from. - required: false - default: write address - type: integer - delay: - description: delay between write and verify. - required: false - default: 0 - type: integer - input_type: - description: Type of address (holding/coil/discrete/input). - required: false - default: write_type - type: integer - state_on: - description: Value when the light is on. - required: false - default: same as command_on - type: integer - state_off: - description: Value when the light is off. - required: false - default: same as command_off - type: integer - unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string -{% endconfiguration %} - -## Configuring platform sensor +## Configuring sensor entities The `modbus` sensor allows you to gather data from [Modbus](http://www.modbus.org/) registers. -To use your Modbus sensors in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters) and [response regresentation](#configuring-data_type-and-struct): + +{% configuration %} +sensors: + description: "A list of all sensors in this modbus instance." + required: true + type: map + keys: + count: + description: "Number of registers to read. + **only valid for `data_type: custom` and `data_type: string`**, for other data types count is automatically calculated." + required: false + type: integer + data_type: + description: "Response representation." + required: false + default: int16 + type: list + keys: + custom: + description: "user defined format, `structure:` and `count:` must be configured." + float16: + description: "16 bit signed float (1 register holds 1 value)." + float32: + description: "32 bit signed float (2 registers holds 1 value)." + float64: + description: "64 bit signed float (4 register holds 1 value)." + int: + description: "**DEPRECATED** is silently converted to `int16`" + int8: + description: "8 bit signed integer (1 register holds 1 value in lower byte)." + int16: + description: "16 bit signed integer (1 register holds 1 value)." + int32: + description: "32 bit signed integer (2 registers holds 1 value)." + int64: + description: "64 bit signed integer (4 registers holds 1 value)." + string: + description: "set of 8 bit characters, `count:` must be configured." + uint: + description: "**DEPRECATED** is silently converted to `uint16`" + uint8: + description: "8 bit unsigned integer (1 register holds 1 value in lower byte)." + uint16: + description: "16 bit unsigned integer (1 register holds 1 value)." + uint32: + description: "32 bit unsigned integer (2 registers holds 1 value)." + uint64: + description: "64 bit unsigned integer (4 registers holds 1 value)." + device_class: + description: "The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend." + required: false + type: device_class + default: None + input_type: + description: "Modbus register type for sensor." + required: false + default: holding + type: list + keys: + holding: + description: "Holding register." + input: + description: "Input register." + min_value: + description: "The minimum allowed value of a sensor. If value < min_value --> min_value. Can be float or integer" + required: false + type: float + max_value: + description: "The maximum allowed value of a sensor. If value > max_value --> max_value. Can be float or integer" + required: false + type: float + nan_value: + description: If a Modbus sensor has a defined NaN value, this value can be set as a hex string starting with `0x` containing one or more bytes (for example, `0xFFFF` or `0x80000000`) or provided as an integer directly. If triggered, the sensor becomes `unavailable`. Please note that the hex to int conversion for `nan_value` does currently not obey home-assistants Modbus encoding using the `data_type`, `structure`, or `swap` arguments. + required: false + type: string + zero_suppress: + description: Suppress values close to zero. If -zero_suppress <= value <= +zero_suppress --> 0. Can be float or integer + required: false + type: float + offset: + description: "Final offset (output = scale * value + offset)." + required: false + type: float + default: 0 + precision: + description: "Number of valid decimals." + required: false + type: integer + default: 0 + scale: + description: "Scale factor (output = scale * value + offset)." + required: false + type: float + default: 1 + slave_count: + description: "Generates x+1 sensors (master + slaves), allowing read of multiple registers with a single read messsage." + required: false + type: integer + state_class: + description: "The [state_class](https://developers.home-assistant.io/docs/core/entity/sensor#available-state-classes) of the sensor." + required: false + type: string + structure: + description: "If `data_type: custom` is specified a double-quoted Python struct is expected, + to format the string to unpack the value. See Python documentation for details. + Example: `>i`." + required: false + type: string + default: ">f" + slave_count: + description: Generates x-1 slave sensors, allowing read of multiple registers with a single read message. + required: false + type: integer + swap: + description: "Swap the order of bytes/words, **not valid with `custom` and `datatype: string`**" + required: false + default: none + type: list + keys: + none: + description: "No swapping." + byte: + description: "Swap bytes AB -> BA." + word: + description: "Swap word ABCD -> CDAB, **not valid with data types: `int8`, `uint8`, `int16`, `uint16`**" + word_byte: + description: "Swap word ABCD -> DCBA, **not valid with data types: `int8`, `uint8`, `int16`, `uint16`**" + unit_of_measurement: + description: "Unit to attach to value." + required: false + type: string + zero_suppress: + description: "Suppress values close to zero. If -zero_suppress <= value <= +zero_suppress --> 0. Can be float or integer" + required: false + type: float +{% endconfiguration %} + +
+ +If you specify scale or offset as floating point values, double precision floating point arithmetic will be used to calculate final value. This can cause loss of precision for values that are larger than 2^53. + +
+ +### Example: sensor configuration ```yaml # Example configuration.yaml entry @@ -964,84 +1342,8 @@ modbus: precision: 2 ``` -{% configuration %} -sensors: - description: The array contains a list of all your Modbus sensors. - required: true - type: map - keys: - address: - description: Register number. - required: true - type: integer - count: - description: Number of registers to read. - required: false - type: integer - default: 1 or calculated if data_type is not `struct`. - device_class: - description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend. - required: false - type: device_class - default: None - input_type: - description: Modbus register type (holding, input), default holding. - required: false - type: string - name: - description: Name of the sensor. - required: true - type: string - scan_interval: - description: Defines the update interval of the sensor in seconds. - required: false - type: integer - default: 15 - slave: - description: The number of the slave (Optional for tcp and upd Modbus). - required: true - type: integer - unit_of_measurement: - description: Unit to attach to value. - required: false - type: string - min_value: - description: The minimum allowed value of a sensor. If value < min_value --> min_value. Can be float or integer - required: false - type: float - max_value: - description: The maximum allowed value of a sensor. If value > max_value --> max_value. Can be float or integer - required: false - type: float - nan_value: - description: If a Modbus sensor has a defined NaN value, this value can be set as a hex string starting with `0x` containing one or more bytes (for example, `0xFFFF` or `0x80000000`) or provided as an integer directly. If triggered, the sensor becomes `unavailable`. Please note that the hex to int conversion for `nan_value` does currently not obey home-assistants Modbus encoding using the `data_type`, `structure`, or `swap` arguments. - required: false - type: string - zero_suppress: - description: Suppress values close to zero. If -zero_suppress <= value <= +zero_suppress --> 0. Can be float or integer - required: false - type: float - state_class: - description: The [state_class](https://developers.home-assistant.io/docs/core/entity/sensor#available-state-classes) of the sensor. - required: false - type: string - unique_id: - description: An ID that uniquely identifies this sensor. Slaves will be given a unique_id of <>_<>. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string - slave_count: - description: Generates x-1 slave sensors, allowing read of multiple registers with a single read message. - required: false - type: integer -{% endconfiguration %} -
- -If you specify scale or offset as floating point values, double precision floating point arithmetic will be used to calculate final value. This can cause loss of precision for values that are larger than 2^53. - -
- -### Full example +### Example: sensor full configuration Example temperature sensor with a default scan interval: @@ -1065,11 +1367,85 @@ modbus: data_type: integer ``` -## Configuring platform switch +## Configuring switch entities The `modbus` switch platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. -To use your Modbus switches in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-platform-common-parameters): +{% configuration %} +switches: + description: "A list of all switches in this modbus instance." + required: true + type: map + keys: + command_on: + description: "Value to write to turn on the switch." + required: false + default: 0x01 + type: integer + command_off: + description: "Value to write to turn off the switch." + required: false + default: 0x00 + type: integer + write_type: + description: Type of write request. + required: false + default: holding + type: list + keys: + holding: + description: "write_register is called." + holdings: + description: "write_registers is called." + coil: + description: "write_coil is called." + coils: + description: "write_coils is called." + verify: + description: "Read from Modbus device to verify fan. + If used without attributes, it uses the toggle register configuration. + If omitted, no verification is done, but the state of the fan is set with each toggle." + required: false + type: map + keys: + address: + description: "Address to read from." + required: false + default: "Same as `write address`" + type: integer + delay: + description: "Delay between write and verify." + required: false + default: 0 + type: integer + input_type: + description: Type of address. + required: false + default: same as `write_type` + type: list + keys: + coil: + description: "Coil (1bit relay)." + discrete: + description: "Discret input (1bit relay)." + holding: + description: "Holding register." + input: + description: "Input register." + state_on: + description: "Value when switch is on." + required: false + default: "Same as `command_on`" + type: integer + state_off: + description: "Value when switch is off." + required: false + default: "Same as `command_off`" + type: integer + +{% endconfiguration %} + +### Example: switch configuration ```yaml # Example configuration.yaml entry @@ -1097,72 +1473,114 @@ modbus: state_off: 1 ``` -{% configuration %} -switches: - description: The array contains a list of all your Modbus switches. - required: true - type: map - keys: - address: - description: Coil number or register - required: true - type: integer - command_on: - description: Value to write to turn on the switch. - required: false - default: 0x01 - type: integer - command_off: - description: Value to write to turn off the switch. - required: false - default: 0x00 - type: integer - write_type: - description: type of address (holding/coil or holdings/coils for array call) - required: false - default: holding - type: string - verify: - description: Read from modbus device to verify switch. If used without attributes it uses the toggle register configuration. If omitted no verification is done, but the state of the switch is set with each toggle. - required: false - type: map - keys: - address: - description: Address to read from. - required: false - default: write address - type: integer - delay: - description: delay between write and verify. - required: false - default: 0 - type: integer - input_type: - description: type of address (holding/coil/discrete/input or holdings/coils for array call) - required: false - default: write_type - type: integer - state_on: - description: value when switch is on. - required: false - default: same as command_on - type: integer - state_off: - description: value when switch is off. - required: false - default: same as command_off - type: integer - unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string -{% endconfiguration %} -## Opening an issue +### Example: switch full configuration + +```yaml +# Example configuration.yaml entry +modbus: + - type: tcp + host: IP_ADDRESS + port: 502 + switches: + - name: Switch1 + address: 13 + write_type: coil + - name: Switch2 + slave: 2 + address: 14 + write_type: coil + verify: + - name: Register1 + address: 11 + command_on: 1 + command_off: 0 + verify: + input_type: holding + address: 127 + state_on: 25 + state_off: 1 +``` + +## Parameters usage matrix: + +Some parameters exclude other parameters, the following tables show what can be combined: + +| Datatype: | custom | string | 16 | 32 | 64 | +| --------------- | ------ | ------ | -------- | -------- | -------- | +| count | Yes | Yes | No | No | No | +| structure | Yes | No | No | No | No | +| slave_count | No | No | Yes | Yes | Yes | +| swap: none | Yes | Yes | Yes | Yes | Yes | +| swap: byte | No | No | Yes | Yes | Yes | +| swap: word | No | No | No | Yes | Yes | +| swap: word_byte | No | No | No | Yes | Yes | + + +# modbus services + +The modbus integration provides two generic write services in addition to the platform-specific services. + +| Service | Description | +| --------------------- | --------------------------- | +| modbus.write_register | Write register or registers | +| modbus.write_coil | Write coil or coils | + +Description: + +| Attribute | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| hub | Hub name (defaults to 'modbus_hub' when omitted) | +| unit | Slave address (0-255), alternative to slave | +| slave | Slave address (0-255), alternative to unit | +| address | Address of the Register (e.g. 138) | +| value | (write_register) A single value or an array of 16-bit values. Single value will call modbus function code 0x06. Array will call modbus function code 0x10. Values might need reverse ordering. E.g., to set 0x0004 you might need to set `[4,0]`, this depend on the byte order of your CPU | +| state | (write_coil) A single boolean or an array of booleans. Single boolean will call modbus function code 0x05. Array will call modbus function code 0x0F | + +The modbus integration also provides communication stop/restart services. These services will not do any reconfiguring, but simply stop/start the modbus communication layer. + +| Service | Description | +| -------------- | --------------------------------------------- | +| modbus.stop | Stop communication | +| modbus.restart | Restart communication (Stop first if running) | + +Description: + +| Attribute | Description | +| --------- | ------------------------------------------------ | +| hub | Hub name (defaults to 'modbus_hub' when omitted) | + +## Example: writing a float32 type register + +To write a float32 datatype register use network format like `10.0` == `0x41200000` (network order float hexadecimal). + +```yaml +service: modbus.write_register +data: + address: + unit: + hub: + value: [0x4120, 0x0000] +``` + +## Service `modbus.set-temperature` + +| Service | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| set_temperature | Set temperature. Requires `value` to be passed in, which is the desired target temperature. `value` should be in the same type as `data_type` | + +## Service `modbus.set_hvac_mode` + +| Service | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| set_hvac_mode | Set HVAC mode. Requires `value` to be passed in, which is the desired mode. `value` should be a valid HVAC mode. A mapping between the desired state and the value to be written to the HVAC mode register must exist. Calling this service will also set the On/Off register to an appropriate value, if such a register is defined. | + + +# Opening an issue When opening an issue, please add your current configuration (or a scaled down version), with at least: - - the Modbus configuration lines + - the modbus configuration lines - the entity (sensor, etc.) lines In order for the developers better to identify the problem, please add the @@ -1178,12 +1596,12 @@ logger: and restart Home Assistant, reproduce the problem, and include the log in the issue. -## Building on top of Modbus +# Building on top of modbus - - [Modbus Binary Sensor](#configuring-platform-binary-sensor) - - [Modbus Climate](#configuring-platform-climate) - - [Modbus Cover](#configuring-platform-cover) - - [Modbus Fan](#configuring-platform-fan) - - [Modbus Light](#configuring-platform-light) - - [Modbus Sensor](#configuring-platform-sensor) - - [Modbus Switch](#configuring-platform-switch) + - [modbus Binary Sensor](#configuring-platform-binary-sensor) + - [modbus Climate](#configuring-platform-climate) + - [modbus Cover](#configuring-platform-cover) + - [modbus Fan](#configuring-platform-fan) + - [modbus Light](#configuring-platform-light) + - [modbus Sensor](#configuring-platform-sensor) + - [modbus Switch](#configuring-platform-switch) diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 0d7d8ad4078..d78be66412b 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -617,15 +617,19 @@ A motion detection device which can be represented by a [binary sensor](/integra - Configuration topic: `homeassistant/binary_sensor/garden/config` - State topic: `homeassistant/binary_sensor/garden/state` -- Configuration payload: `{"name": "garden", "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}` +- Configuration payload with derived device name: `{"name": null, "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}` - Retain: The -r switch is added to retain the configuration topic in the broker. Without this, the sensor will not be available after Home Assistant restarts. -It is also a good idea to add a `unique_id` to allow changes to the entity and a `device` mapping so we can group all sensors of a device together. +It is also a good idea to add a `unique_id` to allow changes to the entity and a `device` mapping so we can group all sensors of a device together. We can set "name" to `null` if we want to inherit the device name for the entity. If we set an entity name, the `friendly_name` will be a combination of the device and entity name. If `name` is left away and a `device_class` is set, the entity name part will be derived from the `device_class`. -To create a new sensor manually: +- Example configuration payload with no name set and derived `device_class` name: `{"device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}` + +If no name is set, a default name will be set by MQTT ([see the MQTT platform documentation](#mqtt-discovery)). + +To create a new sensor manually and with the name set to `null` to derive the device name "Garden": ```bash -mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": "garden", "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}' +mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": null, "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}' ``` Update the state: @@ -647,9 +651,9 @@ For more details please refer to the [MQTT testing section](/integrations/mqtt/# Setting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions. - Configuration topic no1: `homeassistant/sensor/sensorBedroomT/config` -- Configuration payload no1: `{"device_class": "temperature", "name": "Temperature", "state_topic": "homeassistant/sensor/sensorBedroom/state", "unit_of_measurement": "°C", "value_template": "{% raw %}{{ value_json.temperature}}{% endraw %}","unique_id": "temp01ae", "device": {"identifiers": ["bedroom01ae"], "name": "Bedroom" }}` +- Configuration payload no1: `{"device_class": "temperature", "state_topic": "homeassistant/sensor/sensorBedroom/state", "unit_of_measurement": "°C", "value_template": "{% raw %}{{ value_json.temperature}}{% endraw %}","unique_id": "temp01ae", "device": {"identifiers": ["bedroom01ae"], "name": "Bedroom" }}` - Configuration topic no2: `homeassistant/sensor/sensorBedroomH/config` -- Configuration payload no2: `{"device_class": "humidity", "name": "Humidity", "state_topic": "homeassistant/sensor/sensorBedroom/state", "unit_of_measurement": "%", "value_template": "{% raw %}{{ value_json.humidity}}{% endraw %}","unique_id": "hum01ae", "device": {"identifiers": ["bedroom01ae"], "name": "Bedroom" } }` +- Configuration payload no2: `{"device_class": "humidity", "state_topic": "homeassistant/sensor/sensorBedroom/state", "unit_of_measurement": "%", "value_template": "{% raw %}{{ value_json.humidity}}{% endraw %}","unique_id": "hum01ae", "device": {"identifiers": ["bedroom01ae"], "name": "Bedroom" } }` - Common state payload: `{ "temperature": 23.20, "humidity": 43.70 }` #### Entities with command topics @@ -664,7 +668,7 @@ Setting up a light, switch etc. is similar but requires a `command_topic` as men ```bash mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \ - -m '{"name": "garden", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state", "unique_id": "irr01ad", "device": {"identifiers": ["garden01ad"], "name": "Garden" }}}' + -m '{"name": "Irrigation", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state", "unique_id": "irr01ad", "device": {"identifiers": ["garden01ad"], "name": "Garden" }}}' ``` Set the state: @@ -938,25 +942,33 @@ definition as a template. Make sure you escape the template blocks as like in the example below. Home Assistant will convert the result to a string and will pass it to the MQTT publish service. +The example below shows how to publish a temperature sensor 'Bathroom Temperature'. +The `device_class` is set, so it is not needed to set the "name" option. The entity +will inherit the name from the `device_class` set and also support translations. +If you set "name" in the payload the entity name will start with the device name. + +{% raw %} + ```yaml service: mqtt.publish data: topic: homeassistant/sensor/Acurite-986-1R-51778/config payload: >- {"device_class": "temperature", - "name": "Acurite-986-1R-51778-T", "unit_of_measurement": "\u00b0C", - "value_template": "{% raw %}{% raw %}{{ value|float }}{%{% endraw %} endraw %}", + "value_template": "{{ value|float }}", "state_topic": "rtl_433/rtl433/devices/Acurite-986/1R/51778/temperature_C", "unique_id": "Acurite-986-1R-51778-T", "device": { "identifiers": "Acurite-986-1R-51778", - "name": "Acurite-986-1R-51778", + "name": "Bathroom", "model": "Acurite-986", "manufacturer": "rtl_433" } } ``` +{% endraw %} + Example of how to use `qos` and `retain`: ```yaml diff --git a/source/_integrations/notify.tts.markdown b/source/_integrations/notify.tts.markdown index ca0e3c11517..267b50a05df 100644 --- a/source/_integrations/notify.tts.markdown +++ b/source/_integrations/notify.tts.markdown @@ -9,23 +9,19 @@ ha_quality_scale: internal ha_domain: notify --- -The notify TTS platform lets you use the TTS integration [Service Say](/integrations/tts/#service-say) and a [media_player](/integrations/media_player) to alert you of important events. This integration provides a simple interface to use in your automations and alerts. +The notify TTS platform lets you use the TTS integration [speak](/integrations/tts/#service-speak) or legacy [say](/integrations/tts/#service-say-legacy) service and a [media_player](/integrations/media_player) to alert you of important events. This integration provides a simple interface to use in your automations and alerts. In order to use this integration, you must already have a TTS platform installed and configured, and a media_player working with the TTS platform. -To enable this platform in your installation, consider the following example using [google_translate](/integrations/google_translate/) and an example `media_player.living_room`. +To enable this platform in your installation, consider the following example using [google_translate](/integrations/google_translate/) and an example `media_player.living_room`. In your `configuration.yaml` file type: ```yaml -tts: - - platform: google_translate - service_name: google_translate_say - notify: - platform: tts name: in_the_living_room - tts_service: tts.google_translate_say + entity_id: tts.google_en_com media_player: media_player.living_room ``` @@ -36,16 +32,20 @@ Please note that the `tts_service` parameter, must match the `service_name` defi description: The name of the notify service. required: true type: string + entity_id: + description: "The `entity_id` of the TTS entity to target. Either use `entity_id` or `tts_service` to target a TTS platform." + required: exclusive + type: string tts_service: - description: "The `service_name` of a TTS platform." - required: true + description: "The `service_name` of a TTS platform. Either use `entity_id` or `tts_service` to target a TTS platform." + required: exclusive type: string media_player: description: "The `entity_id` of a media_player." required: true type: string language: - description: "The `language` to be passed to the TTS `Service Say`" + description: "The `language` to be passed to the TTS `speak` or `say` service." required: false type: string {% endconfiguration %} diff --git a/source/_integrations/openai_conversation.markdown b/source/_integrations/openai_conversation.markdown index b75f389fc97..ef4cd485fdd 100644 --- a/source/_integrations/openai_conversation.markdown +++ b/source/_integrations/openai_conversation.markdown @@ -87,6 +87,15 @@ to generate a new image of New York in the current weather state. The resulting image entity can be used in, for example, a card on your dashboard. +The *config_entry* is installation specific. To get the value, make sure the integration has been installed. +Then, go to {% my developer_services title="**Developer Tools** > **Services**" %}. Ensure you are in UI mode and enter the following below: + +![Open AI Conversation UI Mode](/images/integrations/openai_conversation/openai_developer_tools_ui.png) + +Select **YAML Mode** to reveal the *config_entry* value to be used in the below example automation. + +![Open AI Conversation YAML Mode](/images/integrations/openai_conversation/openai_developer_tools_yaml.png) + {% raw %} ```yaml automation: @@ -99,10 +108,10 @@ automation: service: openai_conversation.generate_image response_variable: generated_image data: - config_entry: f29e6b8696a15e107b4bd843de722249 - size: 512 + config_entry: abce6b8696a15e107b4bd843de722249 + size: "512" prompt: >- - New York when the weather is {{ state("weather.home") }}" + New York when the weather is {{ states("weather.home") }}" - alias: "Send out a manual event to update the image entity" event: new_weather_image diff --git a/source/_integrations/opensky.markdown b/source/_integrations/opensky.markdown index fa741967db3..da43e4a121e 100644 --- a/source/_integrations/opensky.markdown +++ b/source/_integrations/opensky.markdown @@ -18,6 +18,17 @@ The OpenSky integration allows one to track overhead flights in a given region. {% include integrations/config_flow.md %} +{% configuration_basic %} +latitude: + description: The latitude of the center of the area to track. +longitude: + description: The latitude of the center of the area to track. +radius: + description: The radius in meters around the latitude/longitude point to track. +altitude: + description: The maximum altitude in meters in which the planes are tracked. No input (or 0) means all planes in the area are tracked. +{% endconfiguration_basic %} + ## Events - **opensky_entry**: Fired when a flight enters the region. diff --git a/source/_integrations/opower.markdown b/source/_integrations/opower.markdown index 376c208a9b6..76061b8852d 100644 --- a/source/_integrations/opower.markdown +++ b/source/_integrations/opower.markdown @@ -32,11 +32,13 @@ More than 175 utilities use Opower. Currently only the following ones are suppor To add this integration to your installation, you will need your login username and password for your utility website. Two-factor authentication is not supported. +When using Opower with any of the Exelon subsidiaries, you need to actively disable two-factor authentication. Log onto the website, select **Don't use 2FA** and **Don't ask me again**. If you have already enabled 2FA, disable it. + {% include integrations/config_flow.md %} ## Sensors -The integration adds the following sensors: +The integration adds the following sensors only if your utility provides forecasted usage/cost: For electricity: @@ -60,7 +62,12 @@ Note the unit for gas is CCF (centum cubic feet). 1 CCF is one hundred cubic fee ## Energy -Because utilities only release usage/cost data with a 48-hour delay, the integration inserts data into statistic objects. At the initial setup, the integration pulls historical monthly usage/cost since the account activation, daily usage/cost for the past 3 years, and for electricity hourly usage/cost for the past 2 months. After the initial setup, the integration keeps pulling hourly data for electricity and daily data for gas for the past 30 days to allow for any corrections in the data from the utilities. +Because utilities only release usage/cost data with a 48-hour delay, the integration inserts data into statistic objects. +You can find the statistics in {% my developer_statistics title="**Developer Tools** > **Statistics**"%} and search for "opower". +**This delay means that there will be no data in the energy dashboard for today and likely yesterday** (depending on time of day you are checking). + +At the initial setup, the integration pulls historical monthly usage/cost since the account activation. If the utility provides more granular data, it pulls daily usage/cost for the past 3 years and hourly usage/cost for the past 2 months (note: typically, utilities provide only monthly or daily data for gas). +After the initial setup, the integration keeps pulling data (twice per day) for the past 30 days to allow for any corrections in the data from the utilities. In the configuration of the energy dashboard (**{% my config_energy title="Settings > Dashboards > Energy" %}**): @@ -71,9 +78,19 @@ For electricity: 3. Select the radio button to **Use an entity tracking the total costs**. 4. Select **Opower {utility name} elec {account number} cost** for the **entity with the total costs**. +Your **Configure grid consumption** should now look like this: +![Screenshot configure grid consumption](/images/integrations/opower/configure_grid_consumption.png) + For gas: 1. Select **Add gas source** for the **Gas consumption**. 2. Select **Opower {utility name} gas {account number} consumption** for the **gas usage**. 3. Select the radio button to **Use an entity tracking the total costs**. 4. Select **Opower {utility name} gas {account number} cost** for the **entity with the total costs**. + +Your **Configure gas consumption** should now look like this: +![Screenshot configure gas consumption](/images/integrations/opower/configure_gas_consumption.png) + +With the above changes your (**{% my config_energy title="Settings > Dashboards > Energy" %}**) page should now look like this: + +![Screenshot Energy Configuration](/images/integrations/opower/energy_config.png) diff --git a/source/_integrations/profiler.markdown b/source/_integrations/profiler.markdown index 8dce2096093..1c78faa4a86 100644 --- a/source/_integrations/profiler.markdown +++ b/source/_integrations/profiler.markdown @@ -16,7 +16,9 @@ The Profiler integration provides a profile which is a set of statistics that id {% include integrations/config_flow.md %} -### Service {% my developer_call_service service="profiler.start" %} +### Service profiler.start + +{% my developer_call_service badge service="profiler.start" %} Start the profiler for the specified number of seconds. @@ -51,7 +53,9 @@ dot callgrind.dot -Tpng -o callgrind.png gprof2dot -f pstats profile.1234567890123456.cprof | dot -Tsvg -o profile.svg ``` -### Service {% my developer_call_service service="profiler.memory" %} +### Service profiler.memory + +{% my developer_call_service badge service="profiler.memory" %} Start the memory profiler for the specified number of seconds. @@ -69,7 +73,9 @@ from guppy import hpy hpy().pb() ``` -### Service {% my developer_call_service service="profiler.start_log_objects" %} +### Service profiler.start_log_objects + +{% my developer_call_service badge service="profiler.start_log_objects" %} Start logging the growth of objects in memory. @@ -79,11 +85,15 @@ Start logging the growth of objects in memory. Periodically log the growth of new objects in memory. This service's primary use case is finding memory leaks. This service can be run for long periods to find slow leaks. For finding fast leaks, `profiler.start_log_object_sources` is preferred; however, it is much more CPU intensive. -### Service {% my developer_call_service service="profiler.stop_log_objects" %} +### Service profiler.stop_log_objects + +{% my developer_call_service badge service="profiler.stop_log_objects" %} Stop logging the growth of objects in memory. -### Service {% my developer_call_service service="profiler.start_log_object_sources" %} +### Service profiler.start_log_object_sources + +{% my developer_call_service badge service="profiler.start_log_object_sources" %} Start logging the growth of objects in memory and attempt to find the source of the new objects. @@ -96,11 +106,15 @@ Periodically log the growth of new objects in memory. This service's primary use This service is similar to `start_log_objects` except that it is much more CPU intensive since it will attempt to locate the source of each new object up to `max_objects` each time it logs. -### Service {% my developer_call_service service="profiler.stop_log_object_sources" %} +### Service profiler.stop_log_object_sources + +{% my developer_call_service badge service="profiler.stop_log_object_sources" %} Stop logging the growth of objects with sources in memory. -### Service {% my developer_call_service service="profiler.dump_log_objects" %} +### Service profiler.dump_log_objects + +{% my developer_call_service badge service="profiler.dump_log_objects" %} | Service data attribute | Optional | Description | | ---------------------- | -------- | -------------------------------------- | @@ -121,7 +135,9 @@ data: type: Template ``` -### Service {% my developer_call_service service="profiler.log_thread_frames" %} +### Service profiler.log_thread_frames + +{% my developer_call_service badge service="profiler.log_thread_frames" %} To help discover run away threads, why the executor is overloaded, or other threading problems, the current frames for each running thread will be logged when this service is called. @@ -156,7 +172,9 @@ An example is below: sock.connect(address) ``` -### Service {% my developer_call_service service="profiler.log_event_loop_scheduled" %} +### Service profiler.log_event_loop_scheduled + +{% my developer_call_service badge service="profiler.log_event_loop_scheduled" %} Log what is scheduled in the event loop. This can be helpful in tracking down integrations that do not stop listeners when Home Assistant stops or do not have sufficient locking to avoid scheduling updates before the previous update is finished. @@ -164,6 +182,8 @@ Each upcoming scheduled item is logged similar to the below example: `[homeassistant.components.profiler] Scheduled: .run_action(>>) at /usr/src/homeassistant/homeassistant/helpers/event.py:1175>` -### Service {% my developer_call_service service="profiler.lru_stats" %} +### Service profiler.lru_stats + +{% my developer_call_service badge service="profiler.lru_stats" %} Logs statistics from [lru_cache](https://docs.python.org/3/library/functools.html#functools.lru_cache) and [lru-dict](https://pypi.org/project/lru-dict/) to help tune Home Assistant and locate memory leaks. diff --git a/source/_integrations/roborock.markdown b/source/_integrations/roborock.markdown index d6075b5d2a5..1466c99f98b 100644 --- a/source/_integrations/roborock.markdown +++ b/source/_integrations/roborock.markdown @@ -34,6 +34,60 @@ Once you log in with your Roborock account, the integration will automatically d {% include integrations/config_flow.md %} + +## Entities + +Roborock devices have a variety of features that are supported on some devices but not on others. Only entities that your device supports will be added to your integration. + +### Vacuum + +The vacuum entity holds the ability to control most things the vacuum can do, such as start a clean, return to the dock, or set the fan speed. + +### Select + +Mop mode - Describes how to mop the floor. On some firmware, it is called 'mop route'. + +Mop intensity - How hard you would like your vacuum to mop. + +### Sensor + +Cleaning area - How much area the vacuum has cleaned in its current run. If the vacuum is not currently cleaning, how much area it has cleaned during its last run. + +Cleaning time - How long the vacuum has been cleaning for. If the vacuum is not currently cleaning, how long it cleaned for in its last run. + +Main brush time left - How much time is left before Roborock recommends you replace your main brush. + +Side brush time left - How much time is left before Roborock recommends you replace your side brush. + +Filter time left - How much time is left before Roborock recommends you replace your vacuum's air filter. + +Status - The current status of your vacuum. This typically describes the action that is currently being run. For example, 'spot_cleaning' or 'docking'. + +Total cleaning time - The lifetime cleaning duration of your vacuum. + +Total cleaning area - The lifetime cleaning area of your vacuum. + +Vacuum error - The current error with your vacuum, if there is one. + +### Time + +Do not disturb begin - When _Do not disturb_ is enabled, the vacuum does not run or speak after this point. + +Do not disturb end - When _Do not disturb_ is enabled, the vacuum does not run or speak before this point. + +### Switch + +Child lock - This disables the buttons on the vacuum. Nothing happens when the buttons are pushed. + +Status indicator light - This is the LED on the top of your vacuum. The color changes depending on the status of your vacuum. + +Do not disturb - This enables _Do not disturb_ during the time frame you have set in the app or on the time entity. When _Do not disturb_ is enabled, the vacuum does not run or speak. + +### Number + +Volume - This allows you to control the volume of the robot's voice. For example, when it states "Starting cleaning". This allows you to set the volume to 0%, while the app limits it to 20%. + + ## FAQ ### Can I use the Mi home app with this integration? diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index a2205e2dd56..27c42e575b9 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -51,9 +51,20 @@ Generation 1 devices use the `CoIoT` protocol to communicate with the integratio We recommend using `unicast` for communication. To enable this, enter the local IP address of the Home Assistant server and port `5683` into the **CoIoT peer** field and push **SAVE** button. **This is mandatory for battery operated devices**. After changing the **CoIoT peer**, the Shelly device needs to be manually restarted. +Home Assistant will display a repair issue for the Shelly device if push updates from this device do not reach the Home Assistant server. + +The list below will help you diagnose and fix the problem: + +- Check if your Shelly devices have a properly configured `CoIoT peer`. +- If you can't find the `CoIoT peer` settings in the device's web panel, it's probably using an ancient firmware version, and you should update it to the current one. +- If Shelly devices are in a different subnet than the Home Assistant server, you should ensure communication on `UDP` port `5683` between these subnets. +- If Home Assistant is running as a virtual machine or service on an operating system other than Home Assistant OS, you should open `UDP` port `5683` on the device's firewall and/or ensure that communication from this port is redirected to the Home Assistant service. +- The missing push updates may be related to the WiFi network range. If using a WiFi network with several access points, enable **Internet & Security** >> **WiFi Client AP Roaming** option. Consider moving Shelly device closer to the WiFi access point. Consider adding another WiFi access point, which will improve the connection quality with the device. +- If you think your Shelly devices are working correctly and don't want to change your network/configuration, you can ignore the repair issue. Still, you must know you are giving up the best experience of using first-generation Shelly devices with Home Assistant. + ## Shelly device configuration (generation 2) -Generation 2 devices use the `RPC` protocol to communicate with the integration. Battery powered devices 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 devices use the `RPC` protocol to communicate with the integration. **Battery powered devices** 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: `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. diff --git a/source/_integrations/solax.markdown b/source/_integrations/solax.markdown index 33b2cbde8f4..a0ef45d337d 100644 --- a/source/_integrations/solax.markdown +++ b/source/_integrations/solax.markdown @@ -17,8 +17,6 @@ ha_integration_type: integration The `solax` integration connects Home Assistant to Solax solar power inverters. Solax inverters may be connected to a home Wi-Fi network and expose a REST API. This integration retrieves information such as photovoltaic power production, battery levels and power, and how much power is being fed back into the grid. -## Configuration - {% include integrations/config_flow.md %} ### Optional template sensor diff --git a/source/_integrations/speedtestdotnet.markdown b/source/_integrations/speedtestdotnet.markdown index 43abb8a4a4f..b22769ebd72 100644 --- a/source/_integrations/speedtestdotnet.markdown +++ b/source/_integrations/speedtestdotnet.markdown @@ -24,6 +24,8 @@ Most Speedtest.net servers require TCP port 8080 outbound to function. Without t By default, a speed test will be run every hour. You can disable polling using system options and use the `update_entity` service to automate the speed test frequency. +{% include common-tasks/define_custom_polling.md %} + ## Integration Sensors The following sensors are added by the integration: diff --git a/source/_integrations/sql.markdown b/source/_integrations/sql.markdown index 5c9debc3927..831a9f265c2 100644 --- a/source/_integrations/sql.markdown +++ b/source/_integrations/sql.markdown @@ -227,9 +227,10 @@ Keep in mind that, depending on the update frequency of your sensor and other fa #### Postgres ```sql -SELECT (pg_database_size('dsmrreader')/1024/1024) as db_size; +SELECT pg_database_size('dsmrreader')/1024/1024 as db_size; ``` Use `db_size` as column for value. +Replace `dsmrreader` with the correct name of your database. #### MariaDB/MySQL diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index aa911fd80e9..525977b99e4 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -248,7 +248,19 @@ mqtt: retain: true ``` -For a check, you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your switch manually: +For a check, you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your switch manually. First, we can simulate the availability message sent for the switch: + +```bash +mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1/available -m "online" +``` + +We can simulate the switch being turned on by publishing the "ON" command message: + +```bash +mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1/set -m "ON" +``` + +Finally, we can simulate the switch reporting back the changed state to Home Assistant: ```bash mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1 -m "ON" diff --git a/source/_integrations/unifi.markdown b/source/_integrations/unifi.markdown index 6175d013140..d784e58baee 100644 --- a/source/_integrations/unifi.markdown +++ b/source/_integrations/unifi.markdown @@ -102,11 +102,9 @@ Clean up clients on the UniFi Network application that has only been associated Allow control of network access to clients configured in the integration options by adding MAC addresses. Items in this list will have a Home Assistant switch created, using the UniFi Device name, allowing for blocking and unblocking. -### Control clients powered by POE +### PoE port control -Entities appear automatically for each connected POE client. If no POE client device is in operation, no entity will be visible. Note: UniFi infrastructure devices such as access points and other switches are not (yet) supported, even if they are powered over ethernet themselves. - -Note that POE control actually configures the network port of the switch which the client is connected to. +Provides per-port PoE control. Entities are disabled by default. This feature requires admin privileges. ### Control DPI Traffic Restrictions @@ -120,7 +118,7 @@ Entities appear for each WLAN. Changing the state of WLAN will trigger a reconfi ### Bandwidth sensor -Get entities reporting receiving and transmitting bandwidth per network client. +Get entities reporting receiving and transmitting bandwidth per network client. These sensors are disabled by default. To enable the bandwidth sensors, on the UniFi integration page, select **Configure**, go to page 3/3 and enable the bandwidth sensors. ### Wlan clients sensor diff --git a/source/_integrations/waze_travel_time.markdown b/source/_integrations/waze_travel_time.markdown index 7aac703e9ff..7166acb8659 100644 --- a/source/_integrations/waze_travel_time.markdown +++ b/source/_integrations/waze_travel_time.markdown @@ -25,9 +25,9 @@ Notes: - The string inputs for `Substring *` allow you to force the integration to use a particular route or avoid a particular route in its time travel calculation. These inputs are case insensitive and matched against the description of the route. - When using the `Avoid Toll Roads?`, `Avoid Subscription Roads?` and `Avoid Ferries?` options, be aware that Waze will sometimes still route you over toll roads or ferries if a valid vignette/subscription is assumed. Default behavior is that Waze will route you over roads having subscription options. It is therefor best is to set both `Avoid Toll Roads?` and `Avoid Subscription Roads?` or `Avoid Ferries?` if needed and experiment to ensure the desired outcome. -## Manual Polling +## Defining a custom polling interval -Some users want more control over polling intervals. To use more granular polling, you can disable automated polling. Go to {% my integrations title="**Settings** > **Devices & Services**" %}, and select the **Waze Travel Time** integration. On the integration entry, select the three dots. Then, select **System options** and toggle the button to disable polling. To manually trigger a polling request, call the [`homeassistant.update_entity` service](/integrations/homeassistant/#service-homeassistantupdate_entity) as needed, either manually or via automations. +{% include common-tasks/define_custom_polling.md %} ## Example using dynamic destination diff --git a/source/_integrations/zha.markdown b/source/_integrations/zha.markdown index 1d096ce7359..2e7161f54bf 100644 --- a/source/_integrations/zha.markdown +++ b/source/_integrations/zha.markdown @@ -316,10 +316,10 @@ To add new devices to the network, call the `permit` service on the `zha` domain This service opens network for joining new devices. -| Data | Optional | Description | -| ---------- | -------- | ------------------------------------------------------ | -| `duration` | yes | For how long to allow new devices to join, default 60s | -| `ieee` | yes | allow new devices to join via an existing device | +| Data | Optional | Description | +| ---------- | -------- | ------------------------------------------------------------------------------ | +| `duration` | yes | For how long to allow new devices to join, default 60s | +| `ieee` | yes | The IEEE address of an existing device via which the new device is to be added | To join a new device using an install code (ZB3 devices) use the following data attributes (must use parameters only from the same group: @@ -495,7 +495,7 @@ Before continuing with this section: If a device does not join/pair at all, read Tip to new Zigbee users: Checkout [blakadder's unofficial Zigbee Device Compatibility Repository](https://zigbee.blakadder.com). Anyone can help maintain the site by submitting device compatibility information to it. The repository contains independent community member's reports or device-specific pairing tips for several home automation gateway/bridge/hub software, including open-source Zigbee implementations, such as ZHA, Zigbee2MQTT, and Tasmota (Zigbee2Tasmota). -#### How to add support for new and unsupported devices +### How to add support for new and unsupported devices If your Zigbee device pairs/joins successfully with the ZHA integration but does not show all of the expected entities: 1. Try to re-pair/re-join the device several times. @@ -581,6 +581,29 @@ Since all Zigbee Coordinator radio adapters are very sensitive/susceptible to al - Place your Zigbee Coordinator away from any Wi-Fi access points and all other sources of WiFi. - Wi-Fi frequency ranges can overlap with Zigbee, see the section above on defining Zigbee channel use. +### Zigbee network visualization in ZHA UI + +The ZHA configuration UI has a tab to visualize device links in your Zigbee network topology. + +The network visualization can help to identify devices with poor connection (that is, low values on the link). You will need to look at the ZHA logs to find more detailed information required for troubleshooting. + +The visualization shows multi-hop connections between your paired devices and their reported cumulative values of Received Signal Strength Indicator (RSSI) and Link Quality Indication (LQI). + +The exact method in which these values are reported depends on the Zigbee network stack used on each device. LQI values can be modified at each step as the message propagates through the mesh networking matrix. + +#### How to interpret RSSI and LQI values + +Interpreting RSSI and LQI values is complex. Unless you are a Zigbee specialist yourself or are guided by one, please ignore those values. They can be misleading. If you delve into this, it is important to understand not to judge RSSI or LQI values on their own. When troubleshooting Zigbee messages that are being dropped, you must interpret the combination of both RSSI and LQI. + +RSSI (Received Signal Strength Indicator) values are an indicator value of the raw signal strength between two devices. RSSI values are negative numbers in -dBm format (0 to -100 power ratio in decibels of the measured power referenced to one milliwatt). Lower negative values indicate less interference and a good signal. RSSI information is only between the endpoint device and the first hop from that device. As such, it may not necessarily show signal strength to the Zigbee Coordinator but instead could be showing signal strength to the nearest Zigbee Router device. + +- Generally, anything -60 and above (meaning -50, -40, etc.) in RSSI should be considered a strong signal (not losing messages). +- Anything at -80 and below (meaning -85, -90, etc.) should be considered a noise environment and you risk losing messages. + +LQI (Link Quality Index) values can be hard to interpret for Zigbee. This is because the Zigbee specifications and the (IEEE 802.15.4 specification) do not standardize how to perform LQI measurements. LQI values are shown as positive numbers on a scale. But because the value provided by the Zigbee devices is not measured using unified standards from all device manufacturers and Zigbee stacks, the values can not always be trusted. For example, Zigbee devices based on Silicon Labs EmberZNet stack use positive display numbers for LQI, where higher is better and lower is worse. The Texas Instruments Z-Stack computes LQI for each received packet from the raw “received signal strength index” (RSSI) by linearly scaling it between the minimum and maximum defined RF power levels for the radio that more or less just provides an LQI value that, based on the strength of the received signal. This can be misleading in case the user has a noisy environment with interference within the same frequency range (as the RSSI value may be shown as increased even though the true link quality decreases). Other manufacturers and Zigbee stacks measure and calculate LQI values in another way. + +- In theory, an LQI value of 255 means a zero error rate in theory. In general, a positive high LQI value is better and a lower LQI value is worse. However, depending on your devices, that might not be the reality. + ### Reporting issues When reporting issues, please provide the following information in addition to information requested by issue template: diff --git a/source/_posts/2023-08-02-release-20238.markdown b/source/_posts/2023-08-02-release-20238.markdown index 17d511c1a56..c3d91f3e950 100644 --- a/source/_posts/2023-08-02-release-20238.markdown +++ b/source/_posts/2023-08-02-release-20238.markdown @@ -46,12 +46,16 @@ Enjoy the release! - [Introducing the event entity](#introducing-the-event-entity) - [Improving the first experience with Home Assistant](#improving-the-first-experience-with-home-assistant) - [Add items to your shopping list using Assist](#add-items-to-your-shopping-list-using-assist) -- [Wildcard support for sentence triggers](#wildcard-support-for-sentence-triggers) - [Generate an image with OpenAI's DALL-E](#generate-an-image-with-openais-dall-e) +- [Wildcard support for sentence triggers](#wildcard-support-for-sentence-triggers) - [Condition selector](#condition-selector) - [Other noteworthy changes](#other-noteworthy-changes) - [New integrations](#new-integrations) - [Integrations now available to set up from the UI](#integrations-now-available-to-set-up-from-the-ui) +- [Release 2023.8.1 - August 4](#release-202381---august-4) +- [Release 2023.8.2 - August 11](#release-202382---august-11) +- [Release 2023.8.3 - August 18](#release-202383---august-18) +- [Release 2023.8.4 - August 24](#release-202384---august-24) - [Need help? Join the community!](#need-help-join-the-community) - [Breaking changes](#breaking-changes) - [Farewell to the following](#farewell-to-the-following) @@ -334,7 +338,7 @@ The following integrations are now available via the Home Assistant UI: - **[OpenSky]**, done by [@joostlek] - **[Zodiac]**, done by [@joostlek] -[@joostlek]: https://github.com/jooostlek +[@joostlek]: https://github.com/joostlek [OpenSky]: /integrations/opensky [Zodiac]: /integrations/zodiac @@ -460,6 +464,263 @@ The following integrations are now available via the Home Assistant UI: [zeroconf docs]: /integrations/zeroconf/ [zha docs]: /integrations/zha/ +## Release 2023.8.2 - August 11 + +- Handle Alert exception on notification failure ([@karwosts] - [#93632]) +- Add yeelight class to fix superclass issue ([@joostlek] - [#97649]) +- Fix metoffice visibility range sensor device class ([@MrHarcombe] - [#97763]) +- Don't assume that `battery_level` value is always present in Tractive `hw_info` ([@bieniu] - [#97766]) +- Improve counting of UniFi WLAN Clients sensor ([@Kane610] - [#97785]) +- Integration tado bump ([@erwindouna] - [#97791]) +- Ensure webhooks take HA cloud into account ([@frenck] - [#97801]) +- Bump aiohomekit to 2.6.13 ([@bdraco] - [#97820]) +- Fix Samsung syncthru device info ([@joostlek] - [#97843]) +- Fallback to get_hosts_info on older Fritz!OS in AVM Fritz!Tools ([@mib1185] - [#97844]) +- Fix Command Line template error when data is None ([@gjohansson-ST] - [#97845]) +- Bump Omada API version to fix #96193 ([@MarkGodwin] - [#97848]) +- Bump pysensibo to 1.0.33 ([@gjohansson-ST] - [#97853]) +- Add missing translation key to Gardena Bluetooth ([@joostlek] - [#97855]) +- Bump bimmer_connected to 0.13.9, fix notify ([@rikroe] - [#97860]) +- Do not fire homekit_controller events from IP polling ([@bdraco] - [#97869]) +- Avoid polling event characteristic in homekit_controller ([@bdraco] - [#97877]) +- Fix handling HomeKit events when the char is in error state ([@bdraco] - [#97884]) +- Bump python-roborock to 0.32.2 ([@Lash-L] - [#97907]) +- modbus: Adjust read count by slave_count ([@janiversen] - [#97908]) +- Bump pyatv to 0.13.4 ([@bdraco] - [#97932]) +- Bump yeelight to v0.7.13 ([@alexyao2015] - [#97933]) +- Android TV Remote: Fix missing key and cert when adding a device via IP address ([@tronikos] - [#97953]) +- Fix tomorrowio integration for new users ([@lymanepp] - [#97973]) +- Bump ZHA dependency bellows to 0.35.9 ([@puddly] - [#97976]) +- Bump `pyairvisual` to 2023.08.1 ([@bachya] - [#97999]) +- Bump aiohomekit to 2.6.15 ([@bdraco] - [#98005]) +- Add translation keys to Tuya cover ([@joostlek] - [#98040]) +- Remove trailing . from melcloud service descriptions ([@reedy] - [#98053]) +- Bump AIOAladdinConnect to 0.1.57 ([@mkmer] - [#98056]) +- Bump pynina to 0.3.2 ([@DeerMaximum] - [#98070]) +- Bump opower to 0.0.24 ([@tronikos] - [#98091]) +- Improve UniFi control PoE mode ([@Kane610] - [#98119]) +- Add missing translation key in Tuya ([@joostlek] - [#98122]) +- Correct unit of rain pause ([@elupus] - [#98131]) +- Make gardena closing sensor unavailable when closed ([@elupus] - [#98133]) +- Bump opower to 0.0.26 ([@tronikos] - [#98141]) +- Opower: Add gas sensors for utilities that report CCF ([@tronikos] - [#98142]) +- Get Opower accounts from the customer endpoint ([@tronikos] - [#98144]) +- Update aioairzone to v0.6.5 ([@Noltari] - [#98163]) +- Use explicit device name in Broadlink ([@joostlek] - [#98229]) +- Bump pynws 1.5.1; fix regression for precipitation probability ([@MatthewFlamm] - [#98237]) +- Bump pymazda to 0.3.11 ([@bdr99] - [#98084]) + +[#93632]: https://github.com/home-assistant/core/pull/93632 +[#97609]: https://github.com/home-assistant/core/pull/97609 +[#97649]: https://github.com/home-assistant/core/pull/97649 +[#97763]: https://github.com/home-assistant/core/pull/97763 +[#97766]: https://github.com/home-assistant/core/pull/97766 +[#97772]: https://github.com/home-assistant/core/pull/97772 +[#97785]: https://github.com/home-assistant/core/pull/97785 +[#97791]: https://github.com/home-assistant/core/pull/97791 +[#97801]: https://github.com/home-assistant/core/pull/97801 +[#97820]: https://github.com/home-assistant/core/pull/97820 +[#97843]: https://github.com/home-assistant/core/pull/97843 +[#97844]: https://github.com/home-assistant/core/pull/97844 +[#97845]: https://github.com/home-assistant/core/pull/97845 +[#97848]: https://github.com/home-assistant/core/pull/97848 +[#97853]: https://github.com/home-assistant/core/pull/97853 +[#97855]: https://github.com/home-assistant/core/pull/97855 +[#97860]: https://github.com/home-assistant/core/pull/97860 +[#97869]: https://github.com/home-assistant/core/pull/97869 +[#97877]: https://github.com/home-assistant/core/pull/97877 +[#97884]: https://github.com/home-assistant/core/pull/97884 +[#97907]: https://github.com/home-assistant/core/pull/97907 +[#97908]: https://github.com/home-assistant/core/pull/97908 +[#97932]: https://github.com/home-assistant/core/pull/97932 +[#97933]: https://github.com/home-assistant/core/pull/97933 +[#97953]: https://github.com/home-assistant/core/pull/97953 +[#97973]: https://github.com/home-assistant/core/pull/97973 +[#97976]: https://github.com/home-assistant/core/pull/97976 +[#97999]: https://github.com/home-assistant/core/pull/97999 +[#98005]: https://github.com/home-assistant/core/pull/98005 +[#98040]: https://github.com/home-assistant/core/pull/98040 +[#98053]: https://github.com/home-assistant/core/pull/98053 +[#98056]: https://github.com/home-assistant/core/pull/98056 +[#98070]: https://github.com/home-assistant/core/pull/98070 +[#98084]: https://github.com/home-assistant/core/pull/98084 +[#98091]: https://github.com/home-assistant/core/pull/98091 +[#98119]: https://github.com/home-assistant/core/pull/98119 +[#98122]: https://github.com/home-assistant/core/pull/98122 +[#98131]: https://github.com/home-assistant/core/pull/98131 +[#98133]: https://github.com/home-assistant/core/pull/98133 +[#98141]: https://github.com/home-assistant/core/pull/98141 +[#98142]: https://github.com/home-assistant/core/pull/98142 +[#98144]: https://github.com/home-assistant/core/pull/98144 +[#98163]: https://github.com/home-assistant/core/pull/98163 +[#98229]: https://github.com/home-assistant/core/pull/98229 +[#98237]: https://github.com/home-assistant/core/pull/98237 +[@DeerMaximum]: https://github.com/DeerMaximum +[@Kane610]: https://github.com/Kane610 +[@Lash-L]: https://github.com/Lash-L +[@MarkGodwin]: https://github.com/MarkGodwin +[@MatthewFlamm]: https://github.com/MatthewFlamm +[@MrHarcombe]: https://github.com/MrHarcombe +[@Noltari]: https://github.com/Noltari +[@alexyao2015]: https://github.com/alexyao2015 +[@bachya]: https://github.com/bachya +[@bdr99]: https://github.com/bdr99 +[@bdraco]: https://github.com/bdraco +[@bieniu]: https://github.com/bieniu +[@elupus]: https://github.com/elupus +[@erwindouna]: https://github.com/erwindouna +[@frenck]: https://github.com/frenck +[@gjohansson-ST]: https://github.com/gjohansson-ST +[@janiversen]: https://github.com/janiversen +[@joostlek]: https://github.com/joostlek +[@karwosts]: https://github.com/karwosts +[@lymanepp]: https://github.com/lymanepp +[@mib1185]: https://github.com/mib1185 +[@mkmer]: https://github.com/mkmer +[@puddly]: https://github.com/puddly +[@reedy]: https://github.com/reedy +[@rikroe]: https://github.com/rikroe +[@tronikos]: https://github.com/tronikos + +## Release 2023.8.3 - August 18 + +- Fix ness alarm armed_home state appearing as disarmed/armed_away ([@nickw444] - [#94351]) +- Correct modbus config validator: slave/swap ([@janiversen] - [#97798]) +- Fix Opower utilities that have different ReadResolution than previously assumed ([@tronikos] - [#97823]) +- modbus config: count and slave_count can normally not be mixed. ([@janiversen] - [#97902]) +- Create abstraction for Generic YeeLight ([@joostlek] - [#97939]) +- modbus: Repair swap for slaves ([@janiversen] - [#97960]) +- Use Local Timezone for Withings Integration ([@VidFerris] - [#98137]) +- Bump pyrainbird to 4.0.0 ([@allenporter] - [#98271]) +- Bump Python-Roborock to 0.32.3 ([@Lash-L] - [#98303]) +- Bump flux-led to 1.0.2 ([@bdraco] - [#98312]) +- Use default translations by removing names from tplink descriptions ([@joostlek] - [#98338]) +- Fix tts notify config validation ([@MartinHjelmare] - [#98381]) +- Fix GoGoGate2 configuration URL when remote access is disabled ([@oyvindwe] - [#98387]) +- Handle missing keys in Honeywell ([@mkmer] - [#98392]) +- Bump Reolink_aio to 0.7.7 ([@starkillerOG] - [#98425]) +- Update rokuecp to 0.18.1 ([@ctalkington] - [#98432]) +- Update pyipp to 0.14.3 ([@ctalkington] - [#98434]) +- Fix inconsistent lyric temperature unit ([@lscorcia] - [#98457]) +- Bump aiohomekit to 2.6.16 ([@bdraco] - [#98490]) +- Bump opower to 0.0.29 ([@tronikos] - [#98503]) +- Revert "Integration tado bump" ([@erwindouna] - [#98505]) +- Fix the availability condition for Shelly N current sensor ([@bieniu] - [#98518]) +- Correct number of registers to read for sensors for modbus ([@janiversen] - [#98534]) +- Pin setuptools to 68.0.0 ([@frenck] - [#98582]) +- Bump ESPHome recommended BLE version to 2023.8.0 ([@bdraco] - [#98586]) +- Verisure unpack ([@niro1987] - [#98605]) +- Update frontend to 20230802.1 ([@bramkragten] - [#98616]) + +[#94351]: https://github.com/home-assistant/core/pull/94351 +[#97609]: https://github.com/home-assistant/core/pull/97609 +[#97772]: https://github.com/home-assistant/core/pull/97772 +[#97798]: https://github.com/home-assistant/core/pull/97798 +[#97823]: https://github.com/home-assistant/core/pull/97823 +[#97902]: https://github.com/home-assistant/core/pull/97902 +[#97939]: https://github.com/home-assistant/core/pull/97939 +[#97960]: https://github.com/home-assistant/core/pull/97960 +[#98137]: https://github.com/home-assistant/core/pull/98137 +[#98255]: https://github.com/home-assistant/core/pull/98255 +[#98271]: https://github.com/home-assistant/core/pull/98271 +[#98303]: https://github.com/home-assistant/core/pull/98303 +[#98312]: https://github.com/home-assistant/core/pull/98312 +[#98338]: https://github.com/home-assistant/core/pull/98338 +[#98381]: https://github.com/home-assistant/core/pull/98381 +[#98387]: https://github.com/home-assistant/core/pull/98387 +[#98392]: https://github.com/home-assistant/core/pull/98392 +[#98425]: https://github.com/home-assistant/core/pull/98425 +[#98432]: https://github.com/home-assistant/core/pull/98432 +[#98434]: https://github.com/home-assistant/core/pull/98434 +[#98457]: https://github.com/home-assistant/core/pull/98457 +[#98490]: https://github.com/home-assistant/core/pull/98490 +[#98503]: https://github.com/home-assistant/core/pull/98503 +[#98505]: https://github.com/home-assistant/core/pull/98505 +[#98518]: https://github.com/home-assistant/core/pull/98518 +[#98534]: https://github.com/home-assistant/core/pull/98534 +[#98582]: https://github.com/home-assistant/core/pull/98582 +[#98586]: https://github.com/home-assistant/core/pull/98586 +[#98605]: https://github.com/home-assistant/core/pull/98605 +[#98616]: https://github.com/home-assistant/core/pull/98616 +[@Lash-L]: https://github.com/Lash-L +[@MartinHjelmare]: https://github.com/MartinHjelmare +[@VidFerris]: https://github.com/VidFerris +[@allenporter]: https://github.com/allenporter +[@bdraco]: https://github.com/bdraco +[@bieniu]: https://github.com/bieniu +[@bramkragten]: https://github.com/bramkragten +[@ctalkington]: https://github.com/ctalkington +[@erwindouna]: https://github.com/erwindouna +[@frenck]: https://github.com/frenck +[@janiversen]: https://github.com/janiversen +[@joostlek]: https://github.com/joostlek +[@lscorcia]: https://github.com/lscorcia +[@mkmer]: https://github.com/mkmer +[@nickw444]: https://github.com/nickw444 +[@niro1987]: https://github.com/niro1987 +[@oyvindwe]: https://github.com/oyvindwe +[@starkillerOG]: https://github.com/starkillerOG +[@tronikos]: https://github.com/tronikos +[esphome docs]: /integrations/esphome/ +[flux_led docs]: /integrations/flux_led/ +[frontend docs]: /integrations/frontend/ +[gogogate2 docs]: /integrations/gogogate2/ +[homekit_controller docs]: /integrations/homekit_controller/ +[honeywell docs]: /integrations/honeywell/ +[ipp docs]: /integrations/ipp/ +[lyric docs]: /integrations/lyric/ +[modbus docs]: /integrations/modbus/ +[ness_alarm docs]: /integrations/ness_alarm/ +[opower docs]: /integrations/opower/ +[rainbird docs]: /integrations/rainbird/ +[reolink docs]: /integrations/reolink/ +[roborock docs]: /integrations/roborock/ +[roku docs]: /integrations/roku/ +[shelly docs]: /integrations/shelly/ +[tado docs]: /integrations/tado/ +[tplink docs]: /integrations/tplink/ +[tts docs]: /integrations/tts/ +[verisure docs]: /integrations/verisure/ +[withings docs]: /integrations/withings/ +[yeelight docs]: /integrations/yeelight/ + +## Release 2023.8.4 - August 24 + +- Fix octoprint down every two minutes ([@markusressel] - [#90001]) +- modbus: slave is allowed with custom ([@janiversen] - [#98644]) +- Bump opowerto 0.0.30 ([@tronikos] - [#98660]) +- Correct modbus swap/datatype error message ([@janiversen] - [#98698]) +- Bump opower to 0.0.31 ([@tronikos] - [#98716]) +- Reduce Freebox router Raid warning to one occurence ([@fthiery] - [#98740]) +- Remove repair issue for MQTT discovered items ([@frenck] - [#98768]) +- Bump androidtvremote2 to 0.0.14 ([@tronikos] - [#98801]) +- Bump pylitterbot to 2023.4.4 ([@natekspencer] - [#98414]) +- Bump pylitterbot to 2023.4.5 ([@natekspencer] - [#98854]) +- Bump reolink-aio to 0.7.8 ([@starkillerOG] - [#98942]) + +[#90001]: https://github.com/home-assistant/core/pull/90001 +[#97609]: https://github.com/home-assistant/core/pull/97609 +[#97772]: https://github.com/home-assistant/core/pull/97772 +[#98255]: https://github.com/home-assistant/core/pull/98255 +[#98414]: https://github.com/home-assistant/core/pull/98414 +[#98623]: https://github.com/home-assistant/core/pull/98623 +[#98644]: https://github.com/home-assistant/core/pull/98644 +[#98660]: https://github.com/home-assistant/core/pull/98660 +[#98698]: https://github.com/home-assistant/core/pull/98698 +[#98716]: https://github.com/home-assistant/core/pull/98716 +[#98740]: https://github.com/home-assistant/core/pull/98740 +[#98768]: https://github.com/home-assistant/core/pull/98768 +[#98801]: https://github.com/home-assistant/core/pull/98801 +[#98854]: https://github.com/home-assistant/core/pull/98854 +[#98942]: https://github.com/home-assistant/core/pull/98942 +[@frenck]: https://github.com/frenck +[@fthiery]: https://github.com/fthiery +[@janiversen]: https://github.com/janiversen +[@markusressel]: https://github.com/markusressel +[@natekspencer]: https://github.com/natekspencer +[@starkillerOG]: https://github.com/starkillerOG +[@tronikos]: https://github.com/tronikos + ## Need help? Join the community! Home Assistant has a great community of users who are all more than willing @@ -535,6 +796,24 @@ superseded by three single actions `start`, `stop` and `return_to_base`. {% enddetails %} +{% details "Google Nest" %} + +The legacy Works With Nest API is no longer supported. You must manually take +action to use the SDM API by removing the Nest configuration from `configuration.yaml` +and restarting Home Assistant. Then add the Nest integration following the +instructions. Please review the documentation for information about which +devices are supported. + +Additionally, as a reminder, the legacy Works With Nest API is [shutting down](https://developers.nest.com/) +in September 2023. + +([@allenporter] - [#96111]) ([documentation](/integrations/nest)) + +[@allenporter]: https://github.com/allenporter +[#96111]: https://github.com/home-assistant/core/pull/96111 + +{% enddetails %} + {% details "MQTT" %} It's no longer allowed for an MQTT RGB light without a `brighness_state_topic` diff --git a/source/common-tasks/general.markdown b/source/common-tasks/general.markdown index 08405a79f43..251b9d7d019 100644 --- a/source/common-tasks/general.markdown +++ b/source/common-tasks/general.markdown @@ -5,4 +5,8 @@ installation_name: "Installation independent" --- This section provides tasks that do not depend on a specific Home Assistant installation type or a specific integration. They may be referenced in other procedures. -{% include common-tasks/enable_entities.md %} \ No newline at end of file +{% include common-tasks/enable_entities.md %} + +## Defining a custom polling interval + +{% include common-tasks/define_custom_polling.md %} \ No newline at end of file diff --git a/source/dashboards/badges.markdown b/source/dashboards/badges.markdown index 801ff4f1389..e64048c79ed 100644 --- a/source/dashboards/badges.markdown +++ b/source/dashboards/badges.markdown @@ -42,11 +42,6 @@ show_name: description: Show name. type: boolean default: "true" -show_icon: - required: false - description: Show icon. - type: boolean - default: "true" {% endconfiguration %} ## Entity Filter Badge diff --git a/source/getting-started/concepts-terminology.markdown b/source/getting-started/concepts-terminology.markdown index 27de91c3e7e..056d9df83a3 100644 --- a/source/getting-started/concepts-terminology.markdown +++ b/source/getting-started/concepts-terminology.markdown @@ -6,29 +6,33 @@ Now you're in Home Assistant, let's go over important parts of Home Assistant an ## Dashboards -Customizable pages to display information connected to and available in Home Assistant. By default there are two Dashboards, Overview and Energy. The Overview dashboard is the first thing you see after the [onboarding process](/getting-started/onboarding). More details can be found [here](/dashboards). +Dashboards are customizable pages to display information in Home Assistant. By default there are two Dashboards: **Overview** and **Energy**. The **Overview** dashboard is the first thing you see after the [onboarding process](/getting-started/onboarding). The image below shows a customized example of the **Overview** dashboard. If you just onboarded, yours will be nearly empty. To learn how to customize your dashboards, refer to the [dashboard](/dashboards) documentation. ![Dashboard](/images/getting-started/lovelace.png) + ## Integrations -Software that allows Home Assistant to connect to other software and platforms. For example, a product by Philips called Hue would use the Philips Hue integration and allow Home Assistant to talk to the hardware controller Hue Bridge. Any connected and Home Assistant compatible devices to the Hue Bridge would appear in Home Assistant as [devices](#devices--entities). +Integrations are pieces of software that allow Home Assistant to connect to other software and platforms. For example, a product by Philips called Hue would use the Philips Hue integration and allow Home Assistant to talk to the hardware controller Hue Bridge. Any Home Assistant compatible devices connected to the Hue Bridge would appear in Home Assistant as [devices](#devices--entities). ![Integrations](/images/getting-started/integrations-new.png) -A full list of compatible integrations can be found [here](/integrations). +For a full list of compatible integrations, refer to the [integrations](/integrations) documentation. Once an integration has been added, the hardware and/or data are represented in Home Assistant as [devices and entities](#devices--entities). -## Devices & Entities +## Devices & entities -Devices are a logical grouping for one or more entities. A device may represent a physical device and the device may have one or more sensors which appear as entities associated to the device. For example, a motion sensor is represented as a device and the motion may provide motion detection, temperature and light levels as entities. Entities have states such as on when motion is detected and off when there is no motion. +Devices are a logical grouping for one or more entities. A {% term device %} may represent a physical device which can have one or more sensors. The sensors appear as entities associated to the device. For example, a motion sensor is represented as a device. It may provide motion detection, temperature, and light levels as entities. Entities have states such as *detected* when motion is detected and *clear* when there is no motion. + +![Home Assistant Device](/images/getting-started/home-assistant-device_01.png) Devices and entities are used throughout Home Assistant. To name a few examples: -- [Dashboards](#dashboards) can show a state of an entity like if a light bulb is on or off as well as buttons that interact with devices like turning a light bulb on or off. -- An [automation](#automations) can be triggered from a state change on an entity e.g. a light turning on and control another device or entity. -- A predefined setting for light device saved as a [scene](#scenes). -![Home Assistant Device](/images/getting-started/home-assistant-device.png) +- [Dashboards](#dashboards) can show a state of an entity. For example, if a light is on or off. +- An [automation](#automations) can be triggered from a state change on an entity. For example, a motion sensor detects motion and triggers a light to turn on. +- A predefined color and brightness setting for a light saved as a [scene](#scenes). + +![Home Assistant Device](/images/getting-started/home-assistant-device_02.png) ## Automations @@ -37,23 +41,27 @@ A set of repeatable actions that can be set up to run automatically. Automations 2. Conditions - optional tests that must be met before continuing to running actions. For example, if someone is home. 3. Actions - interact with devices such as turn on a light. -More details can be found [here](/docs/automation/basics/) or try creating an [automation](/getting-started/automation). +To learn the basics about automations, refer to the [automation basics](/docs/automation/basics/) page or try [creating an automation](/getting-started/automation) yourself. ![Automations](/images/getting-started/automation-editor.png) ## Scripts -Similar to automations, repeatable actions that can be run. The difference between scripts and automations is that scripts do not have triggers like automations. This means that scripts cannot automatically run unless they are used in an automation. Scripts are particularly useful if you perform the same actions in different automations or trigger them from a dashboard. More details can be found [here](/integrations/script/). +Similar to automations, repeatable actions that can be run. The difference between scripts and automations is that scripts do not have triggers like automations. This means that scripts cannot automatically run unless they are used in an automation. Scripts are particularly useful if you perform the same actions in different automations or trigger them from a dashboard. For information on how to create scripts, refer to the [scripts](/integrations/script/) documentation. + +![Scripts](/images/getting-started/script_01.png) ## Scenes -Scenes allow you to create predefined settings for your devices. Likened to driving mode on phones, driver profiles in cars, it can change an environment to suit you. For example, your environment for watching films may have dimmer lighting, TV is switched on and higher volume. This can be saved as a scene and used without having to set individual devices every time. +Scenes allow you to create predefined settings for your devices. Similar to a driving mode on phones, or driver profiles in cars, it can change an environment to suit you. For example, your *watching films* scene may dim the lighting, switch on the TV and increase its volume. This can be saved as a scene and used without having to set individual devices every time. -Further details can be found [here](/integrations/scene/). +To learn how to use scenes, refer to the [scene](/integrations/scene/) documentation. + +![Scenes](/images/getting-started/scene_02.png) ## Add-ons -Depending on your [installation type](/installation), you may have the ability to install third party add-ons. Add-ons are usually apps that can be run with Home Assistant but provide a quick and easy way to install, configure, and run within Home Assistant. Add-ons provide additional functionality whereas integrations connect Home Assistant to other apps. +Depending on your [installation type](/installation), you can install third party add-ons. Add-ons are usually apps that can be run with Home Assistant but provide a quick and easy way to install, configure, and run within Home Assistant. Add-ons provide additional functionality whereas integrations connect Home Assistant to other apps. ![Add-ons](/images/getting-started/add-ons.png) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 32f08ab71cd..6ebe6f8ede8 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -7,6 +7,7 @@ show_title: true {% include getting-started/next_step.html step="Installation" link="/installation/" %} {% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} +{% include getting-started/next_step.html step="Edit the dashboard" link="/getting-started/onboarding_dashboard/" %} {% include getting-started/next_step.html step="Concepts and terminology" link="/getting-started/concepts-terminology/" %} {% include getting-started/next_step.html step="Integration" link="/getting-started/integration/" %} {% include getting-started/next_step.html step="Automation" link="/getting-started/automation/" %} diff --git a/source/getting-started/onboarding_dashboard.markdown b/source/getting-started/onboarding_dashboard.markdown new file mode 100644 index 00000000000..7ee492894c1 --- /dev/null +++ b/source/getting-started/onboarding_dashboard.markdown @@ -0,0 +1,50 @@ +--- +title: "Edit the dashboard" +description: "Instructions on editing the dashboard for the first time" +--- + +## First contact with the Overview dashboard + +The procedure below is optional. The idea is to learn some basics on changing the dashboard. + +### To change a card on the Overview dashboard + +1. To view your dashboard, go to **Overview**. + - Your dashboard might not have much on it yet. + - If you have smart home devices in your home, some may have been connected automatically. + - In this example, some Bluetooth temperature sensors and an AV receiver connected automatically. + - Some cards are there by default, such as the weather, a card for the person who set up the system, and the text-to-speech service. + + ![Dashboard after onboarding a new device](/images/getting-started/onboarding_dashboard_01.png) +2. To view the weather forecast for the next few days, select the weather card. + + ![Weather details](/images/getting-started/weather_card_details_01.png) + +3. To change the units used on the card, select the cogwheel. + - Change the units if you like. + - Do not change any of the other settings for now. + - Once you are done, select **Update**. + ![Weather details](/images/getting-started/onboarding_card_settings_01.png) + +4. To change the type of dashboard card, select the three-dots, then **Device info**. + - Under **Sensors**, select **Add to dashboard**, then **Pick different card**. + ![Dashboard - change the card type](/images/getting-started/onboarding_pick_different_card_01.png) + +5. From the list, select **Weather forecast**. +6. Select the details to be shown on the card. + ![Dashboard - change the card details](/images/getting-started/onboarding_card_settings_02.png) + - **Save** your changes + - You now see the forecast card on the dashboard. + +7. Now let's delete the other weather card. + - In the top right corner, select the three-dot menu, then select **Edit dashboard**. + ![Dashboard - edit the dashboard](/images/getting-started/onboarding_edit_dashboard_01.png) + - On the card, select the three-dot menu and select **Delete**. + ![Dashboard - delete card](/images/getting-started/onboarding_dashboard_delete_card.png) +8. Finally, we want to move the weather card to the top left corner. + - On the bottom of the card, select the number or use the minus button to enter `1`. + - Repeat this on other cards, if you want to move them around. + - When you are done, in the top right corner, select **Done**. +9. Congratulations! You have completed your first dashboard customization. + +{% include getting-started/next_step.html step="Concepts & Terminology" link="/getting-started/concepts-terminology/" %} \ No newline at end of file diff --git a/source/images/assist/blueprint_daily_summary_notification_01.png b/source/images/assist/blueprint_daily_summary_notification_01.png new file mode 100644 index 00000000000..c89bd6e0e07 Binary files /dev/null and b/source/images/assist/blueprint_daily_summary_notification_01.png differ diff --git a/source/images/assist/calendar_01.png b/source/images/assist/calendar_01.png new file mode 100644 index 00000000000..0a143c85357 Binary files /dev/null and b/source/images/assist/calendar_01.png differ diff --git a/source/images/docs/configuration/enable-debug-logging.gif b/source/images/docs/configuration/enable-debug-logging.gif deleted file mode 100644 index 72f98317009..00000000000 Binary files a/source/images/docs/configuration/enable-debug-logging.gif and /dev/null differ diff --git a/source/images/getting-started/automation-editor.png b/source/images/getting-started/automation-editor.png index d9b475add62..21ab66254f8 100644 Binary files a/source/images/getting-started/automation-editor.png and b/source/images/getting-started/automation-editor.png differ diff --git a/source/images/getting-started/home-assistant-device.png b/source/images/getting-started/home-assistant-device.png deleted file mode 100644 index 41b8233855e..00000000000 Binary files a/source/images/getting-started/home-assistant-device.png and /dev/null differ diff --git a/source/images/getting-started/home-assistant-device_01.png b/source/images/getting-started/home-assistant-device_01.png new file mode 100644 index 00000000000..766950b4025 Binary files /dev/null and b/source/images/getting-started/home-assistant-device_01.png differ diff --git a/source/images/getting-started/home-assistant-device_02.png b/source/images/getting-started/home-assistant-device_02.png new file mode 100644 index 00000000000..b89595ac2f8 Binary files /dev/null and b/source/images/getting-started/home-assistant-device_02.png differ diff --git a/source/images/getting-started/lovelace.png b/source/images/getting-started/lovelace.png index 9971afde817..f7e33107e81 100644 Binary files a/source/images/getting-started/lovelace.png and b/source/images/getting-started/lovelace.png differ diff --git a/source/images/getting-started/onboarding_card_settings_01.png b/source/images/getting-started/onboarding_card_settings_01.png new file mode 100644 index 00000000000..ca0187c12e9 Binary files /dev/null and b/source/images/getting-started/onboarding_card_settings_01.png differ diff --git a/source/images/getting-started/onboarding_card_settings_02.png b/source/images/getting-started/onboarding_card_settings_02.png new file mode 100644 index 00000000000..4dba5f0c91d Binary files /dev/null and b/source/images/getting-started/onboarding_card_settings_02.png differ diff --git a/source/images/getting-started/onboarding_dashboard_01.png b/source/images/getting-started/onboarding_dashboard_01.png new file mode 100644 index 00000000000..6a1f4d0dc4e Binary files /dev/null and b/source/images/getting-started/onboarding_dashboard_01.png differ diff --git a/source/images/getting-started/onboarding_dashboard_delete_card.png b/source/images/getting-started/onboarding_dashboard_delete_card.png new file mode 100644 index 00000000000..a1d0c3f28e4 Binary files /dev/null and b/source/images/getting-started/onboarding_dashboard_delete_card.png differ diff --git a/source/images/getting-started/onboarding_edit_dashboard_01.png b/source/images/getting-started/onboarding_edit_dashboard_01.png new file mode 100644 index 00000000000..6ca5e50328f Binary files /dev/null and b/source/images/getting-started/onboarding_edit_dashboard_01.png differ diff --git a/source/images/getting-started/onboarding_integrations_01.png b/source/images/getting-started/onboarding_integrations_01.png new file mode 100644 index 00000000000..4b34a9f0577 Binary files /dev/null and b/source/images/getting-started/onboarding_integrations_01.png differ diff --git a/source/images/getting-started/onboarding_pick_different_card_01.png b/source/images/getting-started/onboarding_pick_different_card_01.png new file mode 100644 index 00000000000..c8683525bc1 Binary files /dev/null and b/source/images/getting-started/onboarding_pick_different_card_01.png differ diff --git a/source/images/getting-started/onboarding_preparing_01.png b/source/images/getting-started/onboarding_preparing_01.png index c7e50ce044e..f42b6b2d505 100644 Binary files a/source/images/getting-started/onboarding_preparing_01.png and b/source/images/getting-started/onboarding_preparing_01.png differ diff --git a/source/images/getting-started/scene_02.png b/source/images/getting-started/scene_02.png new file mode 100644 index 00000000000..3a05f457cc3 Binary files /dev/null and b/source/images/getting-started/scene_02.png differ diff --git a/source/images/getting-started/script_01.png b/source/images/getting-started/script_01.png new file mode 100644 index 00000000000..e2ae4ce3471 Binary files /dev/null and b/source/images/getting-started/script_01.png differ diff --git a/source/images/getting-started/weather_card_details_01.png b/source/images/getting-started/weather_card_details_01.png new file mode 100644 index 00000000000..0bfccd1a9ff Binary files /dev/null and b/source/images/getting-started/weather_card_details_01.png differ diff --git a/source/images/installation/etcher1.png b/source/images/installation/etcher1.png deleted file mode 100644 index 2f972a2a2d1..00000000000 Binary files a/source/images/installation/etcher1.png and /dev/null differ diff --git a/source/images/installation/etcher1_file.png b/source/images/installation/etcher1_file.png new file mode 100644 index 00000000000..7a4faf8dfd8 Binary files /dev/null and b/source/images/installation/etcher1_file.png differ diff --git a/source/images/integrations/openai_conversation/openai_developer_tools_ui.png b/source/images/integrations/openai_conversation/openai_developer_tools_ui.png new file mode 100644 index 00000000000..d272148c1fb Binary files /dev/null and b/source/images/integrations/openai_conversation/openai_developer_tools_ui.png differ diff --git a/source/images/integrations/openai_conversation/openai_developer_tools_yaml.png b/source/images/integrations/openai_conversation/openai_developer_tools_yaml.png new file mode 100644 index 00000000000..b96d5eb6913 Binary files /dev/null and b/source/images/integrations/openai_conversation/openai_developer_tools_yaml.png differ diff --git a/source/images/integrations/opower/configure_gas_consumption.png b/source/images/integrations/opower/configure_gas_consumption.png new file mode 100644 index 00000000000..c6e01c9e9e3 Binary files /dev/null and b/source/images/integrations/opower/configure_gas_consumption.png differ diff --git a/source/images/integrations/opower/configure_grid_consumption.png b/source/images/integrations/opower/configure_grid_consumption.png new file mode 100644 index 00000000000..51031130a43 Binary files /dev/null and b/source/images/integrations/opower/configure_grid_consumption.png differ diff --git a/source/images/integrations/opower/energy_config.png b/source/images/integrations/opower/energy_config.png new file mode 100644 index 00000000000..3374aeead11 Binary files /dev/null and b/source/images/integrations/opower/energy_config.png differ diff --git a/source/images/screenshots/custom_polling_01.png b/source/images/screenshots/custom_polling_01.png new file mode 100644 index 00000000000..95eb69c4cb7 Binary files /dev/null and b/source/images/screenshots/custom_polling_01.png differ diff --git a/source/images/screenshots/custom_polling_02.png b/source/images/screenshots/custom_polling_02.png new file mode 100644 index 00000000000..d3c7363cd83 Binary files /dev/null and b/source/images/screenshots/custom_polling_02.png differ diff --git a/source/installation/index.html b/source/installation/index.html index 4f6b53b64be..70670646b31 100644 --- a/source/installation/index.html +++ b/source/installation/index.html @@ -6,6 +6,7 @@ show_title: true toc: true --- +{% include installation_survey.html %}

diff --git a/source/installation/raspberrypi.markdown b/source/installation/raspberrypi.markdown index 4b5d682d34f..797b2597bc4 100644 --- a/source/installation/raspberrypi.markdown +++ b/source/installation/raspberrypi.markdown @@ -67,6 +67,8 @@ If you are running an older Windows version or have a stricter network configura Congratulations! You finished the Raspberry Pi setup! +{% include installation_survey.html %} + With the Home Assistant Operating System installed and accessible, you can now continue with onboarding. {% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} @@ -80,10 +82,10 @@ Use this procedure if Raspberry Pi Imager is not supported by your platform. 1. Insert the SD card into the computer. Note: the contents of the card will be overwritten. 2. Download and start Balena Etcher. You may need to run it with administrator privileges on Windows. -3. Select **Flash from URL**. -![Screenshot of the Etcher software showing flash from URL selected.](/images/installation/etcher1.png) -4. Copy the correct URL for the Raspberry Pi 3 or 4 (Note: there are 2 different links below!): +3. Download the image to your computer. + - Copy the correct URL for the Raspberry Pi 3 or 4 (Note: there are 2 different links below!): + {% tabbed_block %} {% for variant in site.installation.types[page.installation_type].variants %} @@ -99,15 +101,18 @@ Use this procedure if Raspberry Pi Imager is not supported by your platform. _Select and copy the URL or use the "copy" button that appear when you hover it._ -1. Paste the URL for the image into Balena Etcher and select **OK**. -![Screenshot of the Etcher software showing the URL bar with a URL pasted in.](/images/installation/etcher2.png) -2. When Balena Etcher has downloaded the image, select **Select target**. +4. Paste the URL into your browser to start the download. +5. Select **Flash from file** and select the image you just downloaded. + - **Flash from URL** does not work on some systems. + + ![Screenshot of the Etcher software showing flash from URL selected.](/images/installation/etcher1_file.png) +6. **Select target**. ![Screenshot of the Etcher software showing the select target button highlighted.](/images/installation/etcher3.png) -3. Select the SD card you want to use for your installation. +7. Select the SD card you want to use for your installation. ![Screenshot of the Etcher software showing teh targets available.](/images/installation/etcher4.png) -4. Select **Flash!** to start writing the image. +8. Select **Flash!** to start writing the image. ![Screenshot of the Etcher software showing the Flash button highlighted.](/images/installation/etcher5.png) -5. Once Balena Etcher has finished writing the image, you will see a confirmation. +9. Once Balena Etcher has finished writing the image, you will see a confirmation. ![Screenshot of the Etcher software showing that the installation has completed.](/images/installation/etcher6.png) diff --git a/source/skyconnect/index.html b/source/skyconnect/index.html index c7c76d27ceb..9de0b55affc 100644 --- a/source/skyconnect/index.html +++ b/source/skyconnect/index.html @@ -149,19 +149,23 @@ frontpage_image: /images/skyconnect/skyconnect-cover.png

-

Components

+

Product details

+ +
Model No.
+
HASKYCNCT
+
Radio Chipset
-
Silabs EFR32MG21
+
Silicon Labs Multiprotocol EFR32MG21
Frequency
-
2.4GHz
+
2.4 GHz
TX Power
-
up to +20dBm
+
up to +20 dBm
Protocols
-
Zigbee, Thread (Matter)
+
Zigbee 3.0;
Thread (Matter) via firmware update
USB
@@ -169,7 +173,7 @@ frontpage_image: /images/skyconnect/skyconnect-cover.png
Supply
-
5V DC / up to 150mA
+
5 V DC / up to 150 mA
@@ -178,13 +182,13 @@ frontpage_image: /images/skyconnect/skyconnect-cover.png

Form Factor

Width
-
18 mm/0.7 inch
+
18 mm / 0.7 inch
Height
-
4.5 mm/1.4 inch
+
4.5 mm / 0.18 inch
Depth
-
38.5 mm/1.5 inch
+
38.5 mm / 1.5 inch
Weight
-
4 g/0.14 oz
+
4 g / 0.14 oz
diff --git a/source/voice_control/assist_create_open_ai_personality.markdown b/source/voice_control/assist_create_open_ai_personality.markdown new file mode 100644 index 00000000000..22eef608128 --- /dev/null +++ b/source/voice_control/assist_create_open_ai_personality.markdown @@ -0,0 +1,36 @@ +--- +title: "Create a personality with OpenAI" +--- + +You can give your voice assistant personality by using OpenAI. This requires an OpenAI account. For what we do in this tutorial, the free trial option is sufficient. No need to leave your credit card information. + +## Prerequisites + +This tutorial assumes you have a few things set up already: + +- [Home Assistant Cloud](https://www.nabucasa.com) or a manually configured [Assist Pipeline](/integrations/assist_pipeline) + +### Creating an OpenAI voice assistant personality + +Using OpenAI requires an OpenAI account. For this tutorial, the free trial option is sufficient. No need to leave your credit card information. + +1. [Set up an OpenAI account and install the OpenAI conversation](/integrations/openai_conversation/) integration. +2. Create a Mario personality. + - Once you installed the OpenAI Conversation integration, go to {% my integrations title="**Settings** > **Devices & Services**" %}. In the OpenAI Conversation integration, select **Configure**. + + ![Configure the OpenAI integration](/images/assist/assistant-openai-mario-config.png) + - In the **Prompt template** field, enter the following text: + + `You are Super Mario from Mario Bros. Be funny.` and select **Submit**. + + ![Add prompt for Mario personality](/images/assist/assistant-openai-mario-02.png) + + - Give your personality a name. Select the three-dots menu, select **Rename** and change the name to `OpenAI Mario`. + +3. Create a Mario assistant: + - Under {% my voice_assistants title="**Settings** > **Voice assistants**" %}, select **Add assistant**. + - Give it a name, select a language, and under **Conversation agent**, select the Mario OpenAI Conversation integration. + ![Add a new assistant](/images/assist/assistant-openai-mario-04.png) + - Leave the other settings unchanged and select **Create**. +4. You can repeat this with other OpenAI personalities. You can add as many OpenAI Conversation integrations as you would like. + - To add a new personality, you need to create a new API key. Then, add a new OpenAI Conversation integration with that API key. diff --git a/source/voice_control/assist_daily_summary.markdown b/source/voice_control/assist_daily_summary.markdown new file mode 100644 index 00000000000..9b75d0e2854 --- /dev/null +++ b/source/voice_control/assist_daily_summary.markdown @@ -0,0 +1,83 @@ +--- +title: "Daily summary by Assist" +--- + +In this tutorial, we are creating an automation that has Assist send you a daily summary. Assist will tell you about the weather and your calendar events today. It will also send you the summary to your messenger. + +We will be using OpenAI, which requires an OpenAI account. For what we do in this tutorial, the free trial option is sufficient. No need to leave your credit card information. + +## Prerequisites + +This tutorial assumes you have a few things set up already: + +- [Home Assistant Cloud](https://www.nabucasa.com) or a manually configured [Assist Pipeline](/integrations/assist_pipeline) + +This tutorial was done using the **Local calendar**, the **Meteorologisk institutt**, and the **Telegram** integrations. It has not been tested with other integrations of the notifications or calendar category. + +### Adding a calendar + +Skip this if you're already using a calendar. + +1. Go to the [integrations page](/integrations/) and select the calendar **Calendar** filter. +2. Pick a calendar you like and install it as described in the documentation. +3. If you just want to follow along with this tutorial, install the [local calendar](/integrations/local_calendar/) integration. + - When prompted for a name, call it `Local calendar`. + - In the navigation bar on the left, you should now see a new entry for the calendar. Open it. + + ![Calendar](/images/assist/calendar_01.png) + - Add a few events for today and the next few days. + +### Adding a weather integration + +Skip this if you're already using a weather integration. + +1. Go to the [integrations page](/integrations/) and select the **Weather** filter. +2. Pick a calendar you like and install it as described in the documentation. +3. If unsure, select **Meteorologisk institutt** and add the integration. + - When prompted, enter the latitude and longitude of your home. + - The coordinates allow the integration to show the weather forecast for your location. + +### Connect Home Assistant to a messenger service + +Skip this if you're already using a notification integration. + +1. Go to the [integrations page](/integrations/) and select the **Notifications** filter. +2. Pick a messenger service you like and install it as described in the documentation. +3. If unsure, select **Telegram** and add the integration. +4. If you don't have it already, install Telegram on your phone. +5. To get started with Telegram on Home Assistant, follow the [set up instruction](/integrations/telegram/#setup-example) step by step. + - Make sure not to copy and paste the following values from the example. Enter the real values: + - `api_key` + - `allowed_chat_ids` + - `name` + - `chat_id` + - `service` +6. You now have a working **Notification** integration. Home Assistant can now send messages to you. + +### Creating an OpenAI voice assistant personality + +The OpenAI personality gives the messages a special touch. +Using OpenAI requires an OpenAI account. For this tutorial, the free trial option is sufficient. No need to leave your credit card information. + +- [Create a Mario personality](/voice_control/assist_create_open_ai_personality/). + +### Creating an automation from a blueprint + +We are using a blueprint (courtesy of [@allenporter]) that polls calendar events and collects weather information. It then asks ChatGPT to summarize it and ships that response to your phone. + +1. To import the blueprint, select the button below: + + {% my blueprint_import badge blueprint_url="https://www.home-assistant.io/blueprints/blog/2023-07/notify_agent_agenda.yaml" %} +2. Select **Preview**, then select **Import blueprint**. +3. Select the blueprint **Conversation agent agenda notification** from the list. +4. Enter the values for each category. + ![Add prompt for Mario personality](/images/assist/blueprint_daily_summary_notification_01.png) + - Under **Notify service name**, make sure not to leave the default but to use the one you set up previously. For example `notify.nina`. + - **Save** your changes. + - In the dialog, enter a name for your new automation. For example, `Daily summary by Mario`. +5. To view the automation, go to {% my automations title="**Settings** > **Automations & Scenes**" %}. +6. To test the automation, select the three dots on your automation, and select **Run**. + - You should now receive a notification from Assist in your messenger app. + + +[@allenporter]: https://github.com/allenporter \ No newline at end of file diff --git a/source/voice_control/worlds-most-private-voice-assistant.markdown b/source/voice_control/worlds-most-private-voice-assistant.markdown index ca33544d8bf..49fc00e5542 100644 --- a/source/voice_control/worlds-most-private-voice-assistant.markdown +++ b/source/voice_control/worlds-most-private-voice-assistant.markdown @@ -75,29 +75,12 @@ To reproduce this example, follow these steps: Note: this procedure requires an OpenAI account. To just run the example, the free trial option is sufficient. No need to leave your credit card information. -1. [Set up an OpenAI account and install the OpenAI conversation](/integrations/openai_conversation/) integration. -2. Create a Mario personality. - - Once you installed the OpenAI Conversation integration, go to {% my integrations title="**Settings** > **Devices & Services**" %} and in OpenAI Conversation integration, the select **Configure**. - - ![Configure the OpenAI integration](/images/assist/assistant-openai-mario-config.png) - - In the **Prompt template** field, enter the following text: - - `You are Super Mario from Mario Bros. Be funny.` and select **Submit**. - - ![Add prompt for Mario personality](/images/assist/assistant-openai-mario-02.png) +1. [Create a Mario personality](/voice_control/assist_create_open_ai_personality/). +2. In the **Voice over IP** integration, under **Configuration**, select the Mario assistant you just created. - - Give your personality a name. Select the three-dots menu, select **Rename** and change the name to `OpenAI Mario`. - -3. Create a Mario assistant: - - Under {% my voice_assistants title="**Settings** > **Voice assistants**" %}, select **Add assistant**. - - Give it a name, select a language and under **Conversation agent**, select the Mario OpenAI Conversation integration. - ![Add a new assistant](/images/assist/assistant-openai-mario-04.png) - - Leave the other settings unchanged and select **Create**. -4. In the **Voice over IP** integration, under **Configuration**, select the Mario assistant you just created. - - ![VoIP: select OpenAI](/images/assist/assistant-openai-mario-03.png) -5. That's it! Pick up your phone and ask Mario a question. -6. You can repeat this with other OpenAI personalities. You can add as many OpenAI Conversation integrations as you would like. + ![VoIP: select OpenAI](/images/assist/assistant-openai-mario-03.png) +3. That's it! Pick up your phone and ask Mario a question. +4. You can repeat this with other OpenAI personalities. You can add as many OpenAI Conversation integrations as you would like. - To add a new personality, you need to create a new API key. Then, add a new OpenAI Conversation integration with that API key. ## Troubleshoot Grandstream diff --git a/source/yellow/index.html b/source/yellow/index.html index c305f40d4a8..7a288f242be 100644 --- a/source/yellow/index.html +++ b/source/yellow/index.html @@ -373,7 +373,7 @@ frontpage_image: /images/frontpage/yellow-frontpage.jpg
🇩🇰
RaspberryPi.dk
-
Located in Denmark
+
Located in Denmark. Also sells CM4 modules.
🇨🇳
Seeed Studio
-
Located in China
+
Located in China. Also sells CM4 modules.