DOCSEARCHbyAlgolia
Submit Docs

Battery Notes

repository·main·Indexed 19 days ago

https://github.com/andrew-codechimp/ha-battery-notes

A Home Assistant integration for tracking battery health, types, and replacement history. It features automatic device discovery via a community-driven library, provides sensors and events for dashboarding and automation, and includes actions to check for low battery status, overdue replacements, and missing reports. It also supports tracking non-smart batteries via the HA-Fake-Devices companion integration.

Tokens
14.9K
Snippets
33
Records
54
Agent score
77%

What's inside ha-battery-notes

  1. Configure a Battery Percentage Template

    main

    If a device does not provide a standard battery percentage (e.g., it provides voltage, a string, or a boolean), you can specify a template to create a battery+ sensor. The template must return a percentage value between 0 and 100.

    Note: If a percentage template is specified, it will be used to trigger low battery events and thresholds.

    # Example: Voltage sensor with 3V max capacity (linear 0-100%)
{% set v = states('sensor.my_sensor_voltage') %}
{{ 
  (v | float / 3 * 100) | round(0)
  if v not in ['unknown','unavailable'] else 'unknown'
}}

  2. Configure a Battery Low Template

    main

    For legacy use or specific logic where you want to define exactly when a battery is considered 'low' (returning a boolean true or false), you can use a Battery Low Template.

    Important: If a Battery Low Template is specified, the Battery Percentage template will be ignored when evaluating thresholds and increased events.

    # Example: Check a sensor state
{{ states('sensor.mysensor_battery_low') }}

# Example: Check a string value
{{ states('sensor.mysensor_battery_level') == "Low" }}

# Example: Check voltage threshold
{{ states('sensor.mysensor_battery_voltage') | float(5) < 1 }}

  3. The `battery_notes_battery_not_replaced` event

    main

    The battery_notes_battery_not_replaced event is triggered by the check_battery_last_replaced action for devices that have exceeded the specified replacement interval (provided raise_events is set to true).

    Key Behaviors

    • Excluding Devices: To prevent this event from firing for specific devices (e.g., rechargeable batteries), disable the battery_last_replaced sensor entity for that device.
    • Automation Concurrency: Because this action can fire multiple events in rapid succession, always use mode: queued in your Home Assistant automations to ensure all events are processed.
    • Manual Execution: This event cannot be triggered manually via the Home Assistant UI because it relies on event triggers.

  4. How Battery Notes works

    main

    Battery Notes is an integration for Home Assistant that adds battery tracking to devices or entities. It uses a battery library to automatically discover and identify battery types for supported devices.

    Key Features:

    • Automatic Discovery: Automatically identifies battery types when a device is in the library.
    • Tracking: Monitors battery type, replacement dates, low battery status (based on device or global thresholds), and 'not reported' status (when a device stops communicating).
    • Dashboard Integration: Provides a battery+ sensor with useful attributes for easy dashboard display. The standard battery sensor can be optionally hidden.
    • Automation Support: Exposes battery low, replaced, and not reported states via events and actions, allowing you to create custom notifications or automations.

  5. Filter Outliers for battery events

    main
    If a device occasionally reports erroneous, very low battery levels that trigger false 'low battery' events, enable the Filter Outliers option. When enabled, battery low events for that device will be delayed until the device has reported three consistently low states.

  6. Handle Battery Replacements

    main

    When a battery level increases, the system raises a battery_notes_battery_increased event. You can use this to automate marking a battery as replaced.

    Prerequisites:

    Automating Replacement Marking: Use the battery_notes.set_battery_replaced action with the device_id and source_entity_id provided in the event data.

    Tip: Getting device_id from an entity trigger: If you are triggering an automation from an entity change, use the following template to extract the device_id:

    actions:
  - action: battery_notes.set_battery_replaced
    data:
      device_id: "{{ device_id(trigger.entity_id) }}"
    alias: Battery Replaced
description: Battery Replaced
mode: queued
triggers:
  - trigger: event
    event_type: battery_notes_battery_increased
conditions: []
actions:
  - action: battery_notes.set_battery_replaced
    data:
      device_id: "{{ trigger.event.data.device_id }}"
      source_entity_id: "{{ trigger.event.data.source_entity_id }}"

  7. Use the Battery Not Reported blueprint

    main

    The Battery Not Reported blueprint triggers notifications or custom actions when a 'battery not reported' event is fired.

    Important Requirement: You must trigger the check_battery_not_reported action via a separate automation to raise these events. Refer to the 'Check Battery Last Reported Daily' guide for setup.

    To use this blueprint, click the 'Install blueprint' link below to import it into your Home Assistant instance.

    [Install blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fraw.githubusercontent.com%2Fandrew-codechimp%2FHA-Battery-Notes%2Fmain%2Fdocs%2Fblueprints%2Fbattery_notes_battery_not_reported.yaml)

  8. How to contribute to existing translations

    main

    Battery Notes uses Crowdin for managing translations. To update or add to an existing language, follow these steps:

    1. Join the project: Create a Crowdin account at https://crowdin.com and join the Battery Notes Crowdin project page.
    2. Translate strings:
      • Select your target language from the Crowdin dashboard.
      • Click Translate All.
      • Locate strings marked in red (indicating missing translations).
      • Enter the translation and click Save.

    Note on deployment: Battery Notes automatically pulls the latest Crowdin translations daily and creates a Pull Request. Once a maintainer reviews the PR, the changes are included in the next release.

  10. Create a battery percentage template

    main

    If your device lacks a native battery percentage sensor, you can create one using a template. Test your template in the Home Assistant Developer Tools > Template section before applying it to the Battery Notes configuration.

    Example: Linear voltage to percentage

    For a sensor where 3V = 100% and 0V = 0%:

    {% set v = states('sensor.my_sensor_voltage') %}
{{ 
  (v | float / 3 * 100) | round(0)
  if v not in ['unknown','unavailable'] else 'unknown'
}}

    Example: Non-linear voltage to percentage

    For a sensor where 3V = 100% but 2V = 10%:

    {% set v = states('sensor.my_sensor_voltage') %}
{{ 
  (((v | float - 2) / (3 - 2)) * 90 + 10) | round(0)
  if v not in ['unknown','unavailable'] else 'unknown'
}}

    Example: Binary low sensor

    If a binary sensor indicates low battery (returning 100% or 9%):

    {{ 9 if states('binary_sensor.my_sensor_low') == true else 100 }}
    {% set v = states('sensor.my_sensor_voltage') %}
{{ 
  (v | float / 3 * 100) | round(0)
  if v not in ['unknown','unavailable'] else 'unknown'
}}

{% set v = states('sensor.my_sensor_voltage') %}
{{ 
  (((v | float - 2) / (3 - 2)) * 90 + 10) | round(0)
  if v not in ['unknown','unavailable'] else 'unknown'
}}

{{ 9 if states('binary_sensor.my_sensor_low') == true else 100 }}

  11. Enable debug logging for Battery Notes

    main

    If you need to analyze issues with your installation, you can enable debug logging using one of two methods:

    Method 1: Via the UI

    1. Open your Home Assistant instance and navigate to the Battery Notes integration page.
    2. Click the Enable debug logging button.

    Method 2: Via configuration.yaml

    Add the following configuration to your configuration.yaml file:

    logger:
  default: warning
  logs:
    custom_components.battery_notes: debug