diff --git a/documentation/_toc.yml b/documentation/_toc.yml index 401cae1a..25534326 100644 --- a/documentation/_toc.yml +++ b/documentation/_toc.yml @@ -13,6 +13,7 @@ parts: chapters: - file: core_extensions - file: enhanced_integrations + - file: helpers - file: other_features - caption: Core extensions @@ -34,6 +35,7 @@ parts: - file: integrations/input_number - file: integrations/input_select - file: integrations/number + - file: integrations/person - file: integrations/recorder - file: integrations/repairs - file: integrations/integration @@ -42,6 +44,10 @@ parts: - file: integrations/switch_as_x - file: integrations/zone + - caption: Helpers + chapters: + - file: helpers/inverse + # - caption: Tutorials # chapters: # - file: ectoplasms diff --git a/documentation/enhanced_integrations.md b/documentation/enhanced_integrations.md index 73fba26e..60b97ea5 100644 --- a/documentation/enhanced_integrations.md +++ b/documentation/enhanced_integrations.md @@ -4,7 +4,7 @@ title: Enhanced integrations subtitle: A little bit of ectoplasm goes a long way. πŸ§ͺ thumbnail: images/social.png description: Spook enhances the following Home Assistant integrations by sprinkling some ectoplasmic goodness on top of them. -date: 2023-08-09T21:29:00+02:00 +date: 2023-09-22T10:47:44+02:00 --- Spook enhances the following {term}`Home Assistant` {term}`integrations ` by sprinkling some {term}`ectoplasmic ` goodness on top of them. @@ -55,6 +55,11 @@ Spook enhances the following {term}`Home Assistant` {term}`integrations `. The helpers allows you to perform calculations or modifications on existing {term}`entities ` and return the result of that as a new entity. + +::::{grid} 1 1 1 1 + +:::{card} Inverse +:footer: πŸ“š [Learn more](helpers/inverse) + +Inverts the behavior of a switch or binary sensor entities. On becomes off, and off becomes on. The world is upside down! + +::: + +:::: diff --git a/documentation/helpers/inverse.md b/documentation/helpers/inverse.md new file mode 100644 index 00000000..704a4675 --- /dev/null +++ b/documentation/helpers/inverse.md @@ -0,0 +1,56 @@ +--- +subject: Helpers +title: Inverse +subtitle: Stranger Things, the upside down πŸ™ƒ +date: 2023-08-21T21:29:00+02:00 +--- + +The inverse {term}`helper ` allows you to invert the behavior of a {term}`switch ` or {term}`binary sensor ` entity. On becomes off, and off becomes on. The world is upside down! + +This can be helpful if you use a switch or binary sensor in a non-standard way, or when the manufacturer of a device has decided to use the opposite logic for the switch or binary sensor (Yeah... they exist... πŸ€¦β€β™‚οΈ). + +It not just inverts the state of the source {term}`entity `, but also does all {term}`service calls ` in reverse. So if you have an automation call the turn on service on a switch, it will instead call the turn off service on the inverted switch. + +## Inverting the behavior of an entity + +The inverse helper can be used to invert the behavior of a switch or binary sensor entity. + +Don't worry! This is really easy and all fully done via the Home Assistant user interface. + +Add one directly to your own instance by selecting the {term}`My Home Assistant` button below: + +[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=spook_inverse) + +Or add one manually, using the following steps: + +1. From the Home Assistant sidebar, select **Settings** and next select **Devices & Services**. +2. Select the **Helpers** tab. +3. On the helpers page, in the bottom right corner, select the **+ Create helper** button. +4. From the list of helpers, select **Inverse πŸ‘»**. + +```{figure} ../images/helpers/inverse/helper_dialog.png +:alt: Screenshot of the add helper dialog, which lists the inverse helper. +:align: center +``` + +5. Select the type of entity you want to invert the behavior of. + +```{figure} ../images/helpers/inverse/select_entity_type.png +:alt: Screenshot of the inverse helper dialog, which allows you to select the type of entity to invert. +:align: center +``` + +6. Provide a name for your new inverted entity this helpers provides, and select the entity you want to invert the behavior of in the **Source entity** field. +7. Turn on **Hide source entity**, if you want to hide the source entity from the Home Assistant interface. + +```{figure} ../images/helpers/inverse/configure.png +:alt: Screenshot of the inverse helper dialog, configuring the new inverted entity. +:align: center +``` + +8. Select **Submit**. Done! πŸŽ‰ + +```{figure} ../images/helpers/inverse/done.png +:alt: Screenshot showing the newly inverted switch, created with the procedure described above. +:align: center +``` diff --git a/documentation/images/helpers/inverse/configure.png b/documentation/images/helpers/inverse/configure.png new file mode 100644 index 00000000..22193076 Binary files /dev/null and b/documentation/images/helpers/inverse/configure.png differ diff --git a/documentation/images/helpers/inverse/done.png b/documentation/images/helpers/inverse/done.png new file mode 100644 index 00000000..c305c9d3 Binary files /dev/null and b/documentation/images/helpers/inverse/done.png differ diff --git a/documentation/images/helpers/inverse/helper_dialog.png b/documentation/images/helpers/inverse/helper_dialog.png new file mode 100644 index 00000000..02ee252f Binary files /dev/null and b/documentation/images/helpers/inverse/helper_dialog.png differ diff --git a/documentation/images/helpers/inverse/select_entity_type.png b/documentation/images/helpers/inverse/select_entity_type.png new file mode 100644 index 00000000..369a3e10 Binary files /dev/null and b/documentation/images/helpers/inverse/select_entity_type.png differ diff --git a/documentation/images/integrations/person/add_device_tracker.png b/documentation/images/integrations/person/add_device_tracker.png new file mode 100644 index 00000000..1da5123a Binary files /dev/null and b/documentation/images/integrations/person/add_device_tracker.png differ diff --git a/documentation/images/integrations/person/example.png b/documentation/images/integrations/person/example.png new file mode 100644 index 00000000..97429275 Binary files /dev/null and b/documentation/images/integrations/person/example.png differ diff --git a/documentation/images/integrations/person/remove_device_tracker.png b/documentation/images/integrations/person/remove_device_tracker.png new file mode 100644 index 00000000..ace81ddd Binary files /dev/null and b/documentation/images/integrations/person/remove_device_tracker.png differ diff --git a/documentation/integrations/person.md b/documentation/integrations/person.md new file mode 100644 index 00000000..c8c804d6 --- /dev/null +++ b/documentation/integrations/person.md @@ -0,0 +1,194 @@ +--- +subject: Enhanced integrations +title: Person +subtitle: Now it gets personal 😱 +thumbnail: ../images/integrations/person/example.png +description: Spook adds some new services to the person integration, which allows you to change device trackers attached to persons in Home Assistant on the fly. +date: 2023-09-22T10:47:44+02:00 +--- + +```{image} https://brands.home-assistant.io/person/logo.png +:alt: The Home Assistant person icon +:width: 250px +:align: center +``` + +

+ +The person {term}`integration ` in {term}`Home Assistant` allows you to track the location of people in your household. It is a collection of device trackers that are grouped together to represent the current location of a person. Additionally, a person may have a user account attached to it, which allows the person to log in to the Home Assistant. + +Spook adds some new services to the person {term}`integration `, that allows you to dynamically change the device trackers attached to a person in Home Assistant. + +```{figure} ../images/integrations/person/example.png +:name: example +:alt: Screenshot of the developer service tools, listing the new services for persons. +:align: center + +Spook adds some new services to the person integration. +``` + +## Devices & entities + +Spook does not provide any new devices or entities for this integration. + +## Services + +Spook adds the following new service to your Home Assistant instance: + +### Add a device tracker + +Adds a device tracker to a person. + +```{figure} ../images/integrations/person/add_device_tracker.png +:alt: Screenshot of the person add device tracker service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Person: Add a device tracker πŸ‘» +* - {term}`Service name` + - `person.add_device_tracker` +* - {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=person.add_device_tracker) + [![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=person.add_device_tracker) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `entity_id` + - {term}`string ` + - Yes + - `person.frenck` +* - `device_tracker` + - {term}`string ` | {term}`list of strings ` + - Yes + - `device_tracker.iphone` +``` + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: person.add_device_tracker +data: + entity_id: person.frenck + device_tracker: device_tracker.iphone +``` + +To add multiple device trackers at once, use a list: + +```{code-block} yaml +:linenos: +service: person.add_device_tracker +data: + entity_id: person.frenck + device_tracker: + - device_tracker.iphone + - device_tracker.ipad +``` + +::: + +### Remove a device tracker + +Removes a device tracker from a person. + +```{figure} ../images/integrations/person/remove_device_tracker.png +:alt: Screenshot of the person remove device tracker service call in the developer tools. +:align: center +``` + +```{list-table} +:header-rows: 1 +* - Service properties +* - {term}`Service` + - Person: Remove a device tracker πŸ‘» +* - {term}`Service name` + - `person.remove_device_tracker` +* - {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=person.remove_device_tracker) + [![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=person.remove_device_tracker) +``` + +```{list-table} +:header-rows: 2 +* - Service call data +* - Attribute + - Type + - Required + - Default / Example +* - `entity_id` + - {term}`string ` + - Yes + - `person.frenck` +* - `device_tracker` + - {term}`string ` | {term}`list of strings ` + - Yes + - `device_tracker.iphone` +``` + +:::{seealso} Example {term}`service call ` in {term}`YAML` +:class: dropdown + +```{code-block} yaml +:linenos: +service: person.remove_device_tracker +data: + entity_id: person.frenck + device_tracker: device_tracker.iphone +``` + +To remove multiple device trackers at once, use a list: + +```{code-block} yaml +:linenos: +service: person.remove_device_tracker +data: + entity_id: person.frenck + device_tracker: + - device_tracker.iphone + - device_tracker.ipad +``` + +::: + +## Repairs + +Spook has no repair detections for this integration. + +## Uses cases + +Some use cases for the enhancements Spook provides for this integration: + +- Adding/removing temporary device trackers that represent a location of a person. For example, if you have a tracker in a car, you could temporary attach it to a person if you know that person took that car. + +## 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/support.md b/documentation/support.md index db2a8493..525ab1b3 100644 --- a/documentation/support.md +++ b/documentation/support.md @@ -4,7 +4,7 @@ title: Support subtitle: Getting directions in this rollercoaster theme park. 🎒 thumbnail: /images/support.png description: Spook is not supported by the Home Assistant project, however, there are still quite a few places where you can get help. This place guides you to the right place. -date: 2023-08-09T21:29:00+02:00 +date: 2023-09-22T10:38:47+02:00 --- Spook is provided as-is, without any warranty or any real support, and above all: Is absolutely **unsupported** by the {term}`Home Assistant` project. However, if you run into issues, where should you go? @@ -22,6 +22,11 @@ Spook is provided as-is, without any warranty or any real support, and above all - [The Home Assistant Reddit](https://www.reddit.com/r/homeassistant/) - [The Home Assistant Facebook group](https://www.facebook.com/groups/homeassistant/) +There are also some language-specific communities: + +- [Dutch Domotics Discord chat server](https://discord.gg/Ee5X7T7) +- [CommunautΓ© Francophone Discord chat server](https://discord.hacf.fr/) + ## I'm sure I've found a bug! Great! πŸŽ‰ Well, not really, but at least it means we can look into fixing it, so others won't experience the same issue.