larsbaum/battery_brain: an open-source tool on GitHub for self-hosters

type: entities
title: Battery Brain
entities:
  - entity: sensor.battery_brain_batteries_critical
    name: Critical
    icon: mdi:battery-alert
  - entity: sensor.battery_brain_batteries_warning
    name: Warning
    icon: mdi:battery-low
  - entity: sensor.battery_brain_batteries_normal
    name: Normal
    icon: mdi:battery
  - entity: sensor.battery_brain_all_batteries
    name: Total Monitored
    icon: mdi:battery-heart

Three columns side by side — critical, warning, normal — each with mushroom cards showing value, archetype, and confidence. Tap any card to open the entity details.

type: horizontal-stack
cards:
  - type: vertical-stack
    cards:
      - type: custom:mushroom-title-card
        title: Critical
        subtitle: "{{ states('sensor.battery_brain_batteries_critical') }} batteries"
        title_tap_action:
          action: more-info
          entity: sensor.battery_brain_batteries_critical
        card_mod:
          style: |
            ha-card { --title-color: var(--error-color, #db4437); }
      - type: custom:auto-entities
        card:
          type: grid
          columns: 1
          square: false
        card_param: cards
        filter:
          template: >
            {%- set ent = 'sensor.battery_brain_batteries_critical' -%} {%- set
            ns = namespace(cards=[]) -%} {%- for n in states[ent].attributes -%}
              {%- set d = states[ent].attributes[n] -%}
              {%- if d is mapping and d.source_entity is defined -%}
                {%- set ns.cards = ns.cards + [{'type': 'tile', 'entity': d.source_entity, 'color': 'red'}] -%}
              {%- endif -%}
            {%- endfor -%} {{ ns.cards }}
        sort:
          method: friendly_name
          ignore_case: true
        show_empty: false
  - type: vertical-stack
    cards:
      - type: custom:mushroom-title-card
        title: Warning
        subtitle: "{{ states('sensor.battery_brain_batteries_warning') }} batteries"
        title_tap_action:
          action: more-info
          entity: sensor.battery_brain_batteries_warning
        card_mod:
          style: |
            ha-card { --title-color: var(--warning-color, #ffa726); }
      - type: custom:auto-entities
        card:
          type: grid
          columns: 1
          square: false
        card_param: cards
        filter:
          template: >
            {%- set ent = 'sensor.battery_brain_batteries_warning' -%} {%- set
            ns = namespace(cards=[]) -%} {%- for n in states[ent].attributes -%}
              {%- set d = states[ent].attributes[n] -%}
              {%- if d is mapping and d.source_entity is defined -%}
                {%- set ns.cards = ns.cards + [{'type': 'tile', 'entity': d.source_entity, 'color': 'orange'}] -%}
              {%- endif -%}
            {%- endfor -%} {{ ns.cards }}
        sort:
          method: friendly_name
          ignore_case: true
        show_empty: false
  - type: vertical-stack
    cards:
      - type: custom:mushroom-title-card
        title: Normal
        subtitle: "{{ states('sensor.battery_brain_batteries_normal') }} batteries"
        title_tap_action:
          action: more-info
          entity: sensor.battery_brain_batteries_normal
        card_mod:
          style: |
            ha-card { --title-color: var(--success-color, #43a047); }
      - type: custom:auto-entities
        card:
          type: grid
          columns: 1
          square: false
        card_param: cards
        filter:
          template: >
            {%- set ent = 'sensor.battery_brain_batteries_normal' -%} {%- set ns
            = namespace(cards=[]) -%} {%- for n in states[ent].attributes -%}
              {%- set d = states[ent].attributes[n] -%}
              {%- if d is mapping and d.source_entity is defined -%}
                {%- set ns.cards = ns.cards + [{'type': 'tile', 'entity': d.source_entity, 'color': 'green'}] -%}
              {%- endif -%}
            {%- endfor -%} {{ ns.cards }}
        sort:
          method: friendly_name
          ignore_case: true
        show_empty: false
grid_options:
  columns: 24
  rows: auto

Requires HACS frontend cards: auto-entities and mushroom.

BatteryBrain discovers batteries in three ways:

• Sensors with device_class: battery
• Sensors with device_class: voltage in the 0.3 V – 20 V range
• Binary sensors with device_class: battery

If a battery is missing:

1. Check that the entity has the correct device_class set
2. Enable "Scan for battery_level attributes" in the integration options — some integrations report battery level as an attribute rather than a dedicated sensor
3. Make sure the entity is not in the excluded entities list
4. Wait for the next scan cycle (every 5 minutes)

Classification improves over time as more data becomes available. Confidence levels:

• default — less than 7 days of data, using fallback thresholds
• low — 7–14 days
• medium — 14–30 days
• high — 30+ days of data

If a battery is still misclassified after 30+ days, please report it as an issue (see Reporting Issues below).

This can happen when:

• The battery reports very low percentages but is still functional (common with some Zigbee devices). BatteryBrain should eventually classify this as low_stable and stop alerting.
• The battery has stopped sending updates and is marked as stale. Check if the device is still online.

If the issue persists, please report it.

BatteryBrain runs a second discovery pass after Home Assistant is fully started, because some integrations (Mobile App, Zigbee2MQTT, etc.) load after BatteryBrain. If batteries are still missing after a few minutes, try restarting Home Assistant once more.

Every 5 minutes, BatteryBrain scans all entities for:

1. sensor entities with device_class: battery
2. sensor entities with device_class: voltage and values between 0.3 V – 20 V (filters out mains voltage sensors)
3. binary_sensor entities with device_class: battery
4. Optionally: any entity with a battery_level attribute

• On first discovery, imports up to 365 days of history from the HA recorder (Long-Term Statistics first, raw states as fallback)
• Stores the last 30 days of raw data points (hourly resolution)
• Aggregates older data into daily summaries (up to 365 days)
• All data is stored locally in .storage/battery_brain — independent of the HA recorder

Batteries are classified after 7+ days of data. The classification algorithm checks archetypes in this order (first match wins):

1. Binary — is it a binary sensor?
2. Voltage — does it report in volts?
3. Rechargeable — are there gradual charge/discharge cycles?
4. Low-Stable — is it stuck at a low value with minimal variation?
5. Plateau-Cliff — does it stay near max and then drop sharply?
6. Linear — is it steadily declining?
7. Unknown — fallback

Reclassification runs automatically every hour.

Each archetype has its own thresholds: