2.3 release (#1627)

* Docs & blueprints

* Update docs

* Docs

Author: andrew-codechimp

README.md

@@ -6,8 +6,8 @@
 [![License][license-shield]](LICENSE)
 [![hacs][hacsbadge]][hacs]
 
-Integration to add battery notes to a device, 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 device hasn't reported a battery for a while.  
+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.  
 
 A battery+ sensor provides useful attributes for easy use in dashboards, the standard battery can optionally be hidden.  
 

docs/blueprints/battery_notes_battery_not_reported.yaml

@@ -19,7 +19,7 @@ blueprint:
         device:
           multiple: true
           entity:
-            - integration: battery_notes          
+            - integration: battery_notes
     user_actions:
       name: User Actions
       description: User actions to run on battery not reported.
@@ -49,7 +49,7 @@ action:
         }} days {{ ''\n'' -}} Its last reported level was {{ trigger.event.data.battery_last_reported_level
         }}% {{ ''\n'' -}} You need {{ trigger.event.data.battery_quantity }}× {{ trigger.event.data.battery_type
         }}'
-      notification_id: 'battery_notes_not_reported {{ trigger.event.data.device_id }}'
+      notification_id: 'battery_notes_not_reported {{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}'
   - alias: Run user actions
     choose: []
     default: !input user_actions

docs/blueprints/battery_notes_battery_replaced.yaml

@@ -23,6 +23,7 @@ action:
   - service: battery_notes.set_battery_replaced
     data:
       device_id: "{{ trigger.event.data.device_id }}"
+      source_entity_id: "{{ trigger.event.data.source_entity_id }}"
   - alias: "Run user on replaced actions"
     choose: []
     default: !input 'on_replaced_actions'

docs/blueprints/battery_notes_battery_threshold.yaml

@@ -26,7 +26,7 @@ blueprint:
         device:
           multiple: true
           entity:
-            - integration: battery_notes        
+            - integration: battery_notes
     on_low_actions:
       name: On Low Actions
       description: User actions to run on battery low. Use any event data via trigger.event.data.xxx
@@ -38,7 +38,7 @@ blueprint:
       description: User actions to run on battery returning from low. Use any event data via trigger.event.data.xxx
       default: []
       selector:
-        action:   
+        action:
 
 variables:
   low_notification: !input low_notification
@@ -79,7 +79,7 @@ action:
                 data:
                   title: |
                     {{ trigger.event.data.device_name }} Battery Low
-                  notification_id: "battery_notes_threshold {{ trigger.event.data.device_id }}"
+                  notification_id: "battery_notes_threshold {{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}"
                   message: >
                     The device has a battery level of {{
                     trigger.event.data.battery_level }}% {{ '\n' -}} You need {{
@@ -99,7 +99,7 @@ action:
             then:
               - service: persistent_notification.dismiss
                 data:
-                  notification_id: "battery_notes_threshold {{ trigger.event.data.device_id }}"
+                  notification_id: "battery_notes_threshold {{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}"
           - alias: "Run user on high actions"
             choose: []
             default: !input 'on_high_actions'

docs/community.md

@@ -55,7 +55,7 @@ action:
             data:
               title: |
                 {{ trigger.event.data.device_name }} Battery Low
-              notification_id: "{{ trigger.event.data.device_id }}"
+              notification_id: "{{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}"
               message: >
                 The device has a battery level of {{
                 trigger.event.data.battery_level }}% {{ '\n' -}} You need {{
@@ -68,7 +68,7 @@ action:
         sequence:
           - service: persistent_notification.dismiss
             data:
-              notification_id: "{{ trigger.event.data.device_id }}"
+              notification_id: "{{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}"
 mode: queued
 ```
 
@@ -122,6 +122,7 @@ action:
   - service: battery_notes.set_battery_replaced
     data:
       device_id: "{{ trigger.event.data.device_id }}"
+      source_entity_id: "{{ trigger.event.data.source_entity_id }}"
 mode: queued
 ```
 
@@ -226,4 +227,4 @@ It is extended from the example Battery Not Reported automation yaml above for t
 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.
 
 ## 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.
+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.

docs/entities.md

@@ -23,6 +23,7 @@ See how to use this entity in the [community contributions](./community.md)
 | `battery_last_reported_level` | `float` | The level when the battery was last reported |
 | `device_id` | `string` | The device_id of the device |
 | `device_name` | `string` | The name of the device |
+| `source_entity_id` | `string` | The entity_id the battery note is associated with |
 
 ## Battery Type
 `sensor.{{device_name}}_battery_type`

docs/events.md

@@ -12,6 +12,7 @@ You can use this to send notifications in your preferred method.  An example aut
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `device_id` | `string` | The device id of the device. |
+| `source_entity_id` | `string` | The entity id of the sensor associated with the battery note. |
 | `device_name` | `string` | The device name (or associated sensor name if no device). |
 | `battery_low` | `bool` | Returns true if the battery has gone below the threshold, false when the battery has returned above the threshold. **Your automations will almost certainly want to examine this value and set/clear notifications or other indicators.** |
 | `battery_type_and_quantity` | `string` | Battery type & quantity. |
@@ -53,7 +54,7 @@ action:
             data:
               title: |
                 {{ trigger.event.data.device_name }} Battery Low
-              notification_id: "{{ trigger.event.data.device_id }}"
+              notification_id: "{{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}"
               message: >
                 The device has a battery level of {{
                 trigger.event.data.battery_level }}% {{ '\n' -}} You need {{
@@ -66,7 +67,7 @@ action:
         sequence:
           - service: persistent_notification.dismiss
             data:
-              notification_id: "{{ trigger.event.data.device_id }}"
+              notification_id: "{{ trigger.event.data.device_id }}-{{ trigger.event.data.source_entity_id }}"
 mode: queued
 ```
 
@@ -81,6 +82,7 @@ An example automation below shows how to update the battery_replaced.
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `device_id` | `string` | The device id of the device. |
+| `source_entity_id` | `string` | The entity id of the sensor associated with the battery note. |
 | `device_name` | `string` | The device name (or associated sensor name if no device). |
 | `battery_low` | `bool` | Returns true if the battery has gone below the threshold, false when the battery has returned above the threshold. |
 | `battery_type_and_quantity` | `string` | Battery type & quantity. |
@@ -104,6 +106,7 @@ action:
   - service: battery_notes.set_battery_replaced
     data:
       device_id: "{{ trigger.event.data.device_id }}"
+      entity_id: "{{ trigger.event.data.source_entity_id }}"
 mode: queued
 ```
 
@@ -117,7 +120,7 @@ The service can raise multiple events quickly so when using with an automation i
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `device_id` | `string` | The device id of the device. |
-| `entity_id` | `string` | The entity id of the sensor associated with the battery note. (BETA ONLY)|
+| `source_entity_id` | `string` | The entity id of the sensor associated with the battery note. |
 | `device_name` | `string` | The device name (or associated sensor name if no device). |
 | `battery_type_and_quantity` | `string` | Battery type & quantity. |
 | `battery_type` | `string` | Battery type. |

docs/index.md

@@ -1,7 +1,7 @@
 # Battery Notes for Home Assistant
 
-Integration to add battery notes to a device, with automatic discovery via a growing [battery library](https://github.com/andrew-codechimp/HA-Battery-Notes/blob/main/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 device hasn't reported a battery for a while.  
+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).  
 
 *Please :star: this repo on [GitHub](https://github.com/andrew-codechimp/HA-Battery-Notes) if you find it useful*  
@@ -28,7 +28,8 @@ Once you have [installed the integration](https://github.com/andrew-codechimp/HA
 ## To add a battery note manually
 * Go to Settings/Integrations and click Add Integration.
 * Select Battery Notes.
-* Choose your device from the drop down and click next.
+* Choose Device or Entity and click next. Device will automatically detect a battery and will work for most common devices, you should use entity if your device has multiple batteries or when an entity does not have a device.
+* Choose your device or entity from the drop down and click next.
 * Enter the battery type and quantity and optionally a battery low threshold and click submit.
 
 !!! info

docs/services.md

@@ -9,6 +9,7 @@ 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. |
 | `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.
@@ -36,4 +37,3 @@ The service will raise a seperate [battery_threshold](./events.md/#battery_thres
 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)
-