From 02101738f56622e658c5c7e335bb567e7294e5bf Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 30 Apr 2024 20:36:13 +0200 Subject: [PATCH] Add documentation for v3.0 features (#745) --- documentation/_toc.yml | 4 +- documentation/areas.md | 7 +- documentation/floors.md | 612 ++++++++++++++ documentation/glossary.md | 13 + documentation/images/floors/add_alias.png | Bin 0 -> 98943 bytes documentation/images/floors/add_area.png | Bin 0 -> 102836 bytes documentation/images/floors/create.png | Bin 0 -> 122223 bytes documentation/images/floors/delete.png | Bin 0 -> 90528 bytes documentation/images/floors/example.png | Bin 0 -> 110371 bytes documentation/images/floors/remove_alias.png | Bin 0 -> 99545 bytes documentation/images/floors/remove_area.png | Bin 0 -> 97229 bytes documentation/images/floors/set_aliases.png | Bin 0 -> 105076 bytes documentation/images/labels/add_to_area.png | Bin 0 -> 90948 bytes documentation/images/labels/add_to_device.png | Bin 0 -> 106358 bytes documentation/images/labels/add_to_entity.png | Bin 0 -> 105202 bytes documentation/images/labels/create.png | Bin 0 -> 119400 bytes documentation/images/labels/delete.png | Bin 0 -> 89489 bytes documentation/images/labels/example.png | Bin 0 -> 126991 bytes .../images/labels/remove_from_area.png | Bin 0 -> 106924 bytes .../images/labels/remove_from_device.png | Bin 0 -> 92771 bytes .../images/labels/remove_from_entity.png | Bin 0 -> 107335 bytes documentation/labels.md | 777 ++++++++++++++++++ documentation/services.md | 90 ++ 23 files changed, 1501 insertions(+), 2 deletions(-) create mode 100644 documentation/floors.md create mode 100644 documentation/images/floors/add_alias.png create mode 100644 documentation/images/floors/add_area.png create mode 100644 documentation/images/floors/create.png create mode 100644 documentation/images/floors/delete.png create mode 100644 documentation/images/floors/example.png create mode 100644 documentation/images/floors/remove_alias.png create mode 100644 documentation/images/floors/remove_area.png create mode 100644 documentation/images/floors/set_aliases.png create mode 100644 documentation/images/labels/add_to_area.png create mode 100644 documentation/images/labels/add_to_device.png create mode 100644 documentation/images/labels/add_to_entity.png create mode 100644 documentation/images/labels/create.png create mode 100644 documentation/images/labels/delete.png create mode 100644 documentation/images/labels/example.png create mode 100644 documentation/images/labels/remove_from_area.png create mode 100644 documentation/images/labels/remove_from_device.png create mode 100644 documentation/images/labels/remove_from_entity.png create mode 100644 documentation/labels.md diff --git a/documentation/_toc.yml b/documentation/_toc.yml index 7347ee49..63a53b11 100644 --- a/documentation/_toc.yml +++ b/documentation/_toc.yml @@ -19,9 +19,11 @@ parts: - caption: Core extensions chapters: - file: integrations + - file: labels + - file: floors + - file: areas - file: devices - file: entities - - file: areas - file: devices_entities - file: template_engine sections: diff --git a/documentation/areas.md b/documentation/areas.md index 1e2360a4..2ab60f0a 100644 --- a/documentation/areas.md +++ b/documentation/areas.md @@ -7,7 +7,7 @@ date: 2023-08-09T21:29:00+02:00 {term}`Areas ` in {term}`Home Assistant` is a logical grouping of {term}`devices ` and {term}`entities ` that are meant to match the areas (or rooms) in the physical world: your home. -Spook provides {term}`services ` that allows you to manage and {term}`automate ` the areas in Home Assisatant programatically. Great for creating "dynamic" areas, or for creating areas on the fly. +Spook provides {term}`services ` that allows you to manage and {term}`automate ` the areas in Home Assistant programatically. Great for creating "dynamic" areas, or for creating areas on the fly. ```{figure} ./images/areas/example.png :alt: Screenshot of the developer service tools, listing the new services to manage areas. @@ -56,6 +56,10 @@ Adds a new area to your Home Assistant instance. - {term}`string ` - Yes - `Living room` +* - `icon` + - {term}`string ` + - No + - `mdi:sofa` * - `aliases` - {term}`string ` | {term}`list of strings ` - No @@ -72,6 +76,7 @@ The use of `aliases` is helpful if you want to create an area with multiple name service: homeassistant.create_area data: name: "Living room" + icon: "mdi:sofa" aliases: - "Lounge" - "Sitting area" diff --git a/documentation/floors.md b/documentation/floors.md new file mode 100644 index 00000000..66d29e3b --- /dev/null +++ b/documentation/floors.md @@ -0,0 +1,612 @@ +--- +subject: Core extensions +title: Floors management +subtitle: Floors brings Home Assistant to a whole new level ðŸĪŠ +date: 2024-04-04T08:44:57+02:00 +--- + +{term}`Floors ` in {term}`Home Assistant` is a logical grouping of {term}`areas ` that are meant to match floors (or levels) in the physical world: your home. Floors are used to group areas together that are on the same floor in your home. Floors give a better overview of your home and can be used to target {term}`service calls ` to a specific floor, like turning off all the lights on the first floor. + +Spook provides {term}`services ` that allows you to manage and {term}`automate ` the floors in Home Assistant programatically. Great for creating "dynamic" floors, or for creating floors on the fly. + +```{figure} ./images/floors/example.png +:alt: Screenshot of the developer service tools, listing the new services to manage floors. +:align: center +``` + +## Services + +Spook adds the following new service to your Home Assistant instance: + +### Create a floor + +Adds a new floor to your Home Assistant instance. + +```{figure} ./images/floors/create.png +:alt: Screenshot of the create floor service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Create a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.create_floor` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.create_floor) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.create_floor) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `name` + - {term}`string ` + - Yes + - `First floor` +* - `icon` + - {term}`string ` + - No + - `mdi:floor-1` +* - `level` + - {term}`integer ` + - No + - `1` +* - `aliases` + - {term}`string ` | {term}`list of strings ` + - No + - `["ground floor", "downstairs"]` +``` + +The use of `aliases` is helpful if you want to create an floor with multiple names. For example, if you want to create an floor called "First floor", but also want to be able to refer to it as "Ground floor" or "Downstairs", you can add those names as aliases. This is used by Home Assistant Assist. + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.create_floor +data: + name: "First floor" + icon: "mdi:floor-1" + level: 1 + aliases: + - "Ground floor" + - "Downstairs" +``` + +::: + +### Delete a floor + +Delete a floor from your Home Assistant instance. + +```{figure} ./images/floors/delete.png +:alt: Screenshot of the delete flor service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Delete a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.delete_floor` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.delete_floor) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.delete_floor) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `floor_id` + - {term}`string ` + - Yes + - `first_floor` +``` + +:::{tip} Getting an floor ID from a floor name +:class: dropdown + +Not sure what the `floor_id` of a floor is? The `floor_id` field also accepts templates. You can use this template to use the floor's name instead: + +```yaml +floor_id: "{{ floor_id('First floor') }}" +``` + +That template will find the floor ID of the floor with the name "First floor". +::: + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.delete_floor +data: + floor_id: "first_floor" +``` + +Same example, but using the floor's name instead of the floor ID: + +```{code-block} yaml +:linenos: +service: homeassistant.delete_floor +data: + floor_id: "{{ floor_id('First floor') }}" +``` + +::: + +### Add an alias to a floor + +Adds one or more aliases to an existing floor. This service does not remove existing aliases, but adds the new ones to the existing ones. + +As floor aliases are used by voice assistants, you could add (and also remove) aliases to a floor using {term}`automations `, which allows you to make them available/unavailable programatically. + +```{figure} ./images/floors/add_alias.png +:alt: Screenshot of the add an alias to a floor service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Add an alias to a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.add_alias_to_floor` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.add_alias_to_floor) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.add_alias_to_floor) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `floor_id` + - {term}`string ` + - Yes + - `first_floor` +* - `aliases` + - {term}`string ` | {term}`list of strings ` + - Yes + - `["Ground floor", "Downstairs"]` +``` + +:::{tip} Getting an floor ID from a floor name +:class: dropdown + +Not sure what the `floor_id` of a floor is? The `floor_id` field also accepts templates. You can use this template to use the floor's name instead: + +```yaml +floor_id: "{{ floor_id('First floor') }}" +``` + +That template will find the floor ID of the floor with the name "First floor". +::: + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.add_alias_to_floor +data: + floor_id: "first_floor" + aliases: + - "Ground floor" + - "Downstairs" +``` + +Same example, but using the floor's name instead of the floor ID: + +```{code-block} yaml +:linenos: +service: homeassistant.add_alias_to_floor +data: + floor_id: "{{ floor_id('First floor') }}" + aliases: + - "Ground floor" + - "Downstairs" +``` + +::: + +### Remove an alias from a floor + +Removes one or more aliases from an existing floor. This service will leave the other aliases intact. + +As floor aliases are used by voice assistants, you could remove (and also add) aliases to a floor using {term}`automations `, which allows you to make them available/unavailable programatically. + +```{figure} ./images/floors/remove_alias.png +:alt: Screenshot of the remove an alias to a floor service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Add an alias to a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.remove_alias_from_floor` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.remove_alias_from_floor) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.remove_alias_from_floor) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `floor_id` + - {term}`string ` + - Yes + - `first_floor` +* - `aliases` + - {term}`string ` | {term}`list of strings ` + - Yes + - `["Ground floor", "Downstairs"]` +``` + +:::{tip} Getting an floor ID from a floor name +:class: dropdown + +Not sure what the `floor_id` of a floor is? The `floor_id` field also accepts templates. You can use this template to use the floor's name instead: + +```yaml +floor_id: "{{ floor_id('First floor') }}" +``` + +That template will find the floor ID of the floor with the name "First floor". +::: + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.remove_alias_from_floor +data: + floor_id: "first_floor" + aliases: + - "Ground floor" + - "Downstairs" +``` + +Same example, but using the floor's name instead of the floor ID: + +```{code-block} yaml +:linenos: +service: homeassistant.remove_alias_from_floor +data: + floor_id: "{{ floor_id('First floor') }}" + aliases: + - "Ground floor" + - "Downstairs" +``` + +::: + +### Set aliases for a floor + +Sets the aliases for a floor. This service will overwrite/remove all existing aliases. + +As floor aliases are used by voice assistants, you could remove (and also add) aliases to a floor using {term}`automations `, which allows you to make them available/unavailable programatically. + +```{figure} ./images/floors/set_aliases.png +:alt: Screenshot of the set aliases to for a floor service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Sets aliases for a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.set_floor_aliases` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.set_floor_aliases) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.set_floor_aliases) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `floor_id` + - {term}`string ` + - Yes + - `first_floor` +* - `aliases` + - {term}`string ` | {term}`list of strings ` + - Yes + - `["Ground floor", "Downstairs"]` +``` + +:::{tip} Getting an floor ID from a floor name +:class: dropdown + +Not sure what the `floor_id` of a floor is? The `floor_id` field also accepts templates. You can use this template to use the floor's name instead: + +```yaml +floor_id: "{{ floor_id('First floor') }}" +``` + +That template will find the floor ID of the floor with the name "First floor". +::: + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.set_floor_aliases +data: + floor_id: "first_floor" + aliases: + - "Ground floor" + - "Downstairs" +``` + +Same example, but using the floor's name instead of the floor ID: + +```{code-block} yaml +:linenos: +service: homeassistant.set_floor_aliases +data: + floor_id: "{{ floor_id('First floor') }}" + aliases: + - "Ground floor" + - "Downstairs" +``` + +::: + +### Add an area to a floor + +Adds one or more area(s) to a floor. This service will leave the other areas on the floor untouched. + +```{figure} ./images/floors/add_area.png +:alt: Screenshot of the add an area to a floor service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Add an area to a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.add_area_to_floor` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.add_area_to_floor) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.add_area_to_floor) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `floor_id` + - {term}`string ` + - Yes + - `first_floor` +* - `area_id` + - {term}`string ` | {term}`list of strings ` + - Yes + - `living_room` +``` + +:::{tip} Getting an floor ID from a floor name +:class: dropdown + +Not sure what the `floor_id` of a floor is? The `floor_id` field also accepts templates. You can use this template to use the floor's name instead: + +```yaml +floor_id: "{{ floor_id('First floor') }}" +``` + +That template will find the floor ID of the floor with the name "First floor". +::: + +:::{tip} Getting an area ID from an area name +:class: dropdown + +Not sure what the `area_id` of an area is? The `area_id` field also accepts templates. You can use this template to use the area's name instead: + +```yaml +area_id: "{{ area_id('Living room') }}" +``` + +That template will find the area ID of the area with the name "Living room". +::: + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.add_area_to_floor +data: + floor_id: "first_floor" + area_id: "living_room" +``` + +Same example, but using the floor's and area's name instead of their IDs: + +```{code-block} yaml +:linenos: +service: homeassistant.add_area_to_floor +data: + floor_id: "{{ floor_id('First floor') }}" + area_id: "{{ area_id('Living room') }}" +``` + +To add multiple areas at once, use a list of area IDs: + +```{code-block} yaml +:linenos: +service: homeassistant.add_area_to_floor +data: + floor_id: "first_floor" + area_id: + - "living_room" + - "kitchen" +``` + +::: + +### Remove an area from a floor + +Removes one or more area(s) from a floor. This service will leave the other area on the floor untouched. + +```{figure} ./images/floors/remove_area.png +:alt: Screenshot of the add a device to an area service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Remove an area from a floor ðŸ‘ŧ +* - {term}`Service name` + - `homeassistant.remove_area_from_floor` +* - {term}`Service targets` + - No +* - {term}`Service response` + - No response +* - {term}`Spook's influence ` + - Newly added service +* - {term}`Developer tools` + - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.remove_area_from_floor) + [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.remove_area_from_floor) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `area_id` + - {term}`string ` | {term}`list of strings ` + - Yes + - `living_room` +``` + +:::{note} This service does not need a floor ID +:class: dropdown + +While this service is floor related, it does not need to know the floor ID. An are can only be on a single floor at a time, so it will remove the area from the floor it is in. Hence, it only needs to know the are you want to remove from a floor. +::: + +:::{tip} Getting an area ID from an area name +:class: dropdown + +Not sure what the `area_id` of an area is? The `area_id` field also accepts templates. You can use this template to use the area's name instead: + +```yaml +area_id: "{{ area_id('Living room') }}" +``` + +That template will find the area ID of the area with the name "Living room". +::: + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: homeassistant.remove_area_from_floor +data: + area_id: "living_room" +``` + +To remove multiple areas at once, use a list of area IDs: + +```{code-block} yaml +:linenos: +service: homeassistant.remove_area_from_floor +data: + area_id: + - "living_room" + - "kitchen" +``` + +::: + +## Blueprints & tutorials + +There are currently no known {term}`blueprints ` or tutorials for the enhancements Spook provides for this integration. If you created one or stumbled upon one, [please let us know in our discussion forums](https://github.com/frenck/spook/discussions). + +## Features requests, ideas, and support + +If you have an idea on how to further enhance this integration, for example, by adding a new service, entity, or repairs detection; feel free to [let us know in our discussion forums](https://github.com/frenck/spook/discussions). + +Are you stuck using these new features? Or maybe you've run into a bug? Please check the [](../support) page on where to go for help. diff --git a/documentation/glossary.md b/documentation/glossary.md index 0f1d1de7..70e33059 100644 --- a/documentation/glossary.md +++ b/documentation/glossary.md @@ -31,6 +31,7 @@ Action :::{glossary} Area : An area in {term}`Home Assistant` is a logical grouping of {term}`devices ` and {term}`entities ` that are meant to match areas (or rooms) in the physical world: your home. Areas are used to group devices and entities together in, for example, the living room. Areas give a better overview of your home and can be used to target {term}`service calls ` to a specific area, like turning off all the lights in the living room. +: [Learn more about areas in the official Home Assistant documentation](https://www.home-assistant.io/docs/organizing/areas/) ::: :::{glossary} @@ -103,6 +104,12 @@ Float : Floats are often confused with {term}`integers `. They look very much alike; the difference is that floats can have a decimal point, while integers cannot. This also means that all integers are floats, but not all floats are integers. ::: +:::{glossary} +Floor +: A floor in {term}`Home Assistant` is a logical grouping of {term}`areas ` that are meant to match floors (or levels) in the physical world: your home. Floors are used to group areas together that are on the same floor in your home. Floors give a better overview of your home and can be used to target {term}`service calls ` to a specific floor, like turning off all the lights on the first floor. +: [Learn more about floors in the official Home Assistant documentation](https://www.home-assistant.io/docs/organizing/floors/) +::: + :::{glossary} Helper : A helper in {term}`Home Assistant` is an {term}`integration` that provides a user input (for example, an input number, input boolean, input select, etc.) or consumes an existing {term}`entity` (or entities) as a data source to perform calculations with and return the result of that calculation as a new entity. @@ -144,6 +151,12 @@ a {term}`device ` or {term}`service ` with your Home Assistant : Spook ðŸ‘ŧ is a custom integration for Home Assistant that is available via {term}`HACS`. ::: +:::{glossary} +Label +: A label in {term}`Home Assistant` can be freely created / be made up by you and used to create your own organizational structure by tagging {term}`devices `, {term}`entities `, or {term}`areas ` with one or more labels. Labels can be used to filter items shows in tables in the user interface, or to target {term}`service calls ` in for example {term}`automations `, or {term}`scripts