diff --git a/README.md b/README.md index 5352d6e4f..9b689fe33 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Track the battery type, when the battery was replaced, when a battery is low bas A battery+ sensor provides useful attributes for easy use in dashboards, the standard battery can optionally be hidden. -Battery low, replaced and not reported are all via events and services, you have the option of creating your own automations for these or using the predefined ones in [community](https://andrew-codechimp.github.io/HA-Battery-Notes/community). +Battery low, replaced and not reported are all via events and actions, you have the option of creating your own automations for these or using the predefined ones in [community](https://andrew-codechimp.github.io/HA-Battery-Notes/community). *Please :star: this repo if you find it useful* *If you want to show your support please* @@ -56,7 +56,7 @@ battery_notes: ## Docs -To get full use of the integration, read the documentation. It contains community quick starts as well as details on all the services, events and entities. +To get full use of the integration, read the documentation. It contains community quick starts as well as details on all the actions, events and entities. [!["Documentation"](https://raw.githubusercontent.com/andrew-codechimp/ha-battery-notes/main/docs/assets/documentation.png)](https://andrew-codechimp.github.io/HA-Battery-Notes/) diff --git a/docs/actions.md b/docs/actions.md new file mode 100644 index 000000000..7bc4eb20c --- /dev/null +++ b/docs/actions.md @@ -0,0 +1,39 @@ +# Actions + +## battery_notes.set_battery_replaced + +For updating the [battery replaced date](./entities.md#battery-replaced). This allows you to change the date a battery was replaced. + +See how to use this action in the [community contributions](./community.md) + +| Data attribute | Optional | Description | +| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | +| `device_id` | `yes` | The device id that you want to change the battery replaced date for. | +| `source_entity_id` | `yes` | The entity id that you want to change the battery replaced date for (only used for entity associated battery notes). | +| `datetime_replaced` | `yes` | The optional datetime that you want to set the battery replaced to, if omitted the current date/time will be used. | + +You must specify either a device_id or entity_id, entity_id will be used in preference if both are specified. This allows the action to work with battery notes associated with both a device and also an individual entity, whether it is part of a device or not. + +## battery_notes.check_battery_last_reported + +For raising events for devices that haven't reported their battery level. + +The action will raise a seperate [battery_not_reported](./events.md/#battery_not_reported) event for each device where its last reported date is older than the number of days specified. + +You can use this action to schedule checks on batteries that is convenient to you, e.g. when you wake up, once a week etc. + +See how to use this action in the [community contributions](./community.md) + +| Data attribute | Optional | Description | +| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | +| `days_last_reported` | `no` | The number of days since a device last reported its battery level. | + +## battery_notes.check_battery_low + +For raising events for devices that have a battery low status. + +The action will raise a seperate [battery_threshold](./events.md/#battery_threshold) event for each device that have a battery low status. + +You can use this action as a reminder that is convenient to you, e.g. when you wake up, once a week etc. The event has a boolean data item `reminder` to determine if the event was raised by this action or the device battery going to a low state. + +See how to use this action in the [community contributions](./community.md) diff --git a/docs/community.md b/docs/community.md index 7f9b020f1..22264a367 100644 --- a/docs/community.md +++ b/docs/community.md @@ -73,7 +73,7 @@ mode: queued ``` ### Check Battery Low daily reminder -Call the check battery low service every day to raise events for those that are still low. +Call the check battery low action every day to raise events for those that are still low. To be used in conjunction with a [Battery Low Notification](community.md/#battery-low-notification) or similar. ```yaml @@ -146,7 +146,7 @@ mode: queued ``` ### Check Battery Last Reported Daily -Call the check battery last reported service every day to raise events for those not reported in the last two days. +Call the check battery last reported action every day to raise events for those not reported in the last two days. To be used in conjunction with a Battery Not Reported automation. ```yaml @@ -164,7 +164,7 @@ mode: single ``` ### Battery Not Reported -Respond to events raised by the check_battery_last_reported service and create notifications. +Respond to events raised by the check_battery_last_reported action and create notifications. Note this cannot be run manually as it examines event triggers, use it with the [Check Battery Last Reported Daily](community.md/#check-battery-last-reported-daily) or similar. @@ -193,7 +193,7 @@ max: 30 ## Automation Tips -To call the battery replaced service from an entity trigger you will need the device_id, here's an easy way to get this +To call the battery replaced action from an entity trigger you will need the device_id, here's an easy way to get this ```yaml action: @@ -224,7 +224,7 @@ It is extended from the example Battery Replaced automation yaml above for those This blueprint will allow notifications to be raised and/or custom actions to be performed when the battery not reported event is fired. It is extended from the example Battery Not Reported automation yaml above for those who'd prefer an easy way to get started. -You must trigger the check_battery_not_reported service via an automation to raise events, see [Check Battery Last Reported Daily](community.md/#check-battery-last-reported-daily) above. +You must trigger the check_battery_not_reported action via an automation to raise events, see [Check Battery Last Reported Daily](community.md/#check-battery-last-reported-daily) above. ## Contributing If you want to contribute then [fork the repository](https://github.com/andrew-codechimp/HA-Battery-Notes), edit this page which is in the docs folder and submit a pull request. \ No newline at end of file diff --git a/docs/events.md b/docs/events.md index 99f92d8f5..72c402fbd 100644 --- a/docs/events.md +++ b/docs/events.md @@ -20,7 +20,7 @@ You can use this to send notifications in your preferred method. An example aut | `battery_quantity` | `int` | Battery quantity. | | `battery_level` | `float` | Battery level % of the device. | | `previous_battery_level` | `float` | Previous battery level % of the device. | -| `reminder` | `bool` | Returns true if the event was raised by a service call, false if it's from a device event. | +| `reminder` | `bool` | Returns true if the event was raised by an action, false if it's from a device event. | ### Automation Example @@ -113,9 +113,9 @@ mode: queued ## Battery Not Reported `battery_notes_battery_not_reported` -This is fired from the [check_battery_last_reported](./services.md/#check_battery_last_reported) service call for each device that has not reported its battery level for the number of days specified in the service call. +This is fired from the [check_battery_last_reported](./actions.md/#check_battery_last_reported) action call for each device that has not reported its battery level for the number of days specified in the action call. -The service can raise multiple events quickly so when using with an automation it's important to use the `mode: queued` to handle these. +The action can raise multiple events quickly so when using with an automation it's important to use the `mode: queued` to handle these. | Attribute | Type | Description | |-----------|------|-------------| diff --git a/docs/index.md b/docs/index.md index 33aeaa81d..83bf7e65c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ Integration to add battery notes to a device or entity, with automatic discovery via a growing [battery library](library.md) for devices. Track the battery type, when the battery was replaced, when a battery is low based on device or global thresholds and also when a battery hasn't been reported for a while. -Battery low, replaced and not reported are all via events and services, you have the option of creating your own automations for these or using the predefined ones in [community](./community.md). +Battery low, replaced and not reported are all via events and actions, you have the option of creating your own automations for these or using the predefined ones in [community](./community.md). *Please :star: this repo on [GitHub](https://github.com/andrew-codechimp/HA-Battery-Notes) if you find it useful* *If you want to show your support please* @@ -17,7 +17,7 @@ The integration will add additional diagnostic entities to your device. ![device example](./assets/screenshot-device.png) * [Entities](./entities.md) -* [Services](./services.md) +* [Actions](./actions.md) * [Events](./events.md) ## How to use Battery Notes diff --git a/docs/services.md b/docs/services.md deleted file mode 100644 index c259d419a..000000000 --- a/docs/services.md +++ /dev/null @@ -1,39 +0,0 @@ -# Services - -## battery_notes.set_battery_replaced - -For updating the [battery replaced date](./entities.md#battery-replaced). This allows you to change the date a battery was replaced. - -See how to use this service in the [community contributions](./community.md) - -| Parameter | Optional | Description | -| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `data.device_id` | `yes` | The device id that you want to change the battery replaced date for. | -| `data.source_entity_id` | `yes` | The entity id that you want to change the battery replaced date for (only used for entity associated battery notes). | -| `data.datetime_replaced` | `yes` | The optional datetime that you want to set the battery replaced to, if omitted the current date/time will be used. | - -You must specify either a device_id or entity_id, entity_id will be used in preference if both are specified. This allows the service to work with battery notes associated with both a device and also an individual entity, whether it is part of a device or not. - -## battery_notes.check_battery_last_reported - -For raising events for devices that haven't reported their battery level. - -The service will raise a seperate [battery_not_reported](./events.md/#battery_not_reported) event for each device where its last reported date is older than the number of days specified. - -You can use this service call to schedule checks on batteries that is convenient to you, e.g. when you wake up, once a week etc. - -See how to use this service in the [community contributions](./community.md) - -| Parameter | Optional | Description | -| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `data.days_last_reported` | `no` | The number of days since a device last reported its battery level. | - -## battery_notes.check_battery_low - -For raising events for devices that have a battery low status. - -The service will raise a seperate [battery_threshold](./events.md/#battery_threshold) event for each device that have a battery low status. - -You can use this service call as a reminder that is convenient to you, e.g. when you wake up, once a week etc. The event has a boolean data item `reminder` to determine if the event was raised by this service or the device battery going to a low state. - -See how to use this service in the [community contributions](./community.md) diff --git a/mkdocs.yml b/mkdocs.yml index 92e729657..d982ec328 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,7 +7,7 @@ nav: - Home: index.md - Entities: entities.md - Events: events.md - - Services: services.md + - Actions: actions.md - Library: library.md - Configuration: configuration.md - Community: community.md