### Example JSON Entry for a New Device

Source: https://github.com/andrew-codechimp/ha-battery-notes/wiki/Contributing-to-the-Battery-Library

This is an example of how to format a JSON entry for a new device in the library. Ensure manufacturer and model match Home Assistant's display, and follow specific guidelines for battery_type and battery_quantity.

```json
{
    "manufacturer": "Philips",
    "model": "Hue motion sensor (9290012607)",
    "battery_type": "AAA",
    "battery_quantity": 2
}
```

--------------------------------

### Example Device Definition JSON

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/library.md

This JSON structure represents a device definition for the library. Include optional fields like 'model_id', 'hw_version', and 'battery_quantity' only if they are present and relevant for your device. The 'model_match_method' is used for devices with unique identifiers.

```json
{
    "manufacturer": "Philips",
    "model": "Hue motion sensor",
    "model_id": "9290012607", 
    "hw_version": "1", 
    "battery_type": "AAA",
    "battery_quantity": 2,  
    "model_match_method": "startswith|endswith|contains"
}
```

--------------------------------

### Create Battery Percentage Template (Non-Linear)

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/faq.md

Use this template for non-linear battery percentage calculation where specific voltage thresholds correspond to certain percentages. This example assumes 3 volts is 100% and 2 volts is 10%.

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

--------------------------------

### Battery Low Template: Voltage Threshold

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/index.md

This template checks if a battery voltage sensor's value falls below a specified threshold (1 volt in this example). It defaults to 5 if the state is unknown or unavailable.

```yaml
{{ states('sensor.mysensor_battery_voltage') | float(5) < 1 }}
```

--------------------------------

### Enable Debug Logging in Home Assistant

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

Add this configuration to your configuration.yaml to enable debug logging for the Battery Notes integration. This is helpful for analyzing issues.

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

--------------------------------

### Basic Configuration Options for Battery Notes

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

Add these options to your Home Assistant configuration.yaml under the battery_notes property to change default behavior. A restart is required for changes to take effect.

```yaml
battery_notes:
  enable_autodiscovery: true
  show_all_devices: false
  enable_replaced: true
```

--------------------------------

### Create Battery Low Template (Binary Sensor)

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/faq.md

This template returns 100% or 9% based on the state of a binary sensor, useful for simple low battery indicators.

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

--------------------------------

### Create Battery Percentage Template (Linear)

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/faq.md

Use this template to calculate battery percentage linearly based on voltage, assuming 3 volts is 100% and 0 volts is 0%. It handles unknown or unavailable states.

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

--------------------------------

### Markdown Summary of Battery Quantities

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

Generate a markdown table summarizing battery types and their counts by iterating through entities integrated with 'battery_notes'.

```yaml
{% set ns_batteries = namespace(batteries={}) %}
{% for entity_id in integration_entities('battery_notes') if entity_id is search('_battery_type$', ignorecase=False) -%}
 {% set battery_type = states[entity_id].state %}
 {% set battery_split = battery_type.split('×') %}
 {% if battery_split | length > 1 %}
 {% set battery_type = battery_split[-1] | trim %}
 {% set battery_count = battery_split[0] | int(1) %}
 {% else %}
 {% set battery_count = 1 %}
 {% endif %}
 {% if battery_type not in ns_batteries.batteries %}
 {% set ns_batteries.batteries = dict(ns_batteries.batteries, **{battery_type: battery_count}) %}
 {% else %}
 {% set ns_batteries.batteries = dict(ns_batteries.batteries, **{battery_type: ns_batteries.batteries[battery_type] + battery_count})
 %}
 {% endif %}
{% endfor %}  | Type | Count |
| :-- | --: |
{% for bt in ns_batteries.batteries | dictsort(False, 'value') | reverse -%}
 | {{ bt[0] }} | {{ [bt][0][1] }} |
{% endfor %}
```

--------------------------------

### Check Battery Status Templates

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/faq.md

These templates can be used to check the battery status of a sensor. They cover direct state reading, comparing to a 'Low' string, and checking voltage thresholds.

```jinja
{{ states('sensor.mysensor_battery_low') }}
```

```jinja
{{ states('sensor.mysensor_battery_level') == "Low" }}
```

```jinja
{{ states('sensor.mysensor_battery_voltage') | float(5) < 1 }}
```

--------------------------------

### Battery Percentage Template: Binary Sensor

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/index.md

Use this template for binary sensors that indicate battery status. It returns 100% if the sensor is not low, and 9% if it is low.

```yaml
{% if states('binary_sensor.my_sensor_low') == true %}9{% else %}100{% endif %}
```

--------------------------------

### Battery Low Template: String Comparison

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/index.md

Use this template to check if a battery level sensor's state is equal to the string 'Low'.

```yaml
{{ states('sensor.mysensor_battery_level') == "Low" }}
```

--------------------------------

### Search Devices by Battery Type

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

Display a list of devices matching a battery type entered into an input_text helper. It supports exact matches for shorter terms and fuzzy matching for longer terms.

```yaml
type: vertical-stack
cards:
  - type: entities
    entities:
      - entity: input_text.battery_search
        name: Search by battery type
        icon: mdi:magnify
        secondary_info: none
    state_color: false
  - type: markdown
    content: |-
      {% set search_term = states('input_text.battery_search') | upper | trim %}
      {% if search_term != "" %}     
        {% set devices = states | selectattr('attributes.battery_type', 'defined') 
                                  | selectattr('entity_id', 'search', '_battery_type$') | list %}
        {% if search_term | count < 7 %}
          {% set matching_devices = devices | selectattr('attributes.battery_type', 'string')
                                              | selectattr('attributes.battery_type', 'eq', search_term) 
                                              | map(attribute='name') | unique | list %}
        {% else %}
          {% set matching_devices = devices | selectattr('attributes.battery_type', 'string')
                                              | selectattr('attributes.battery_type', 'search', search_term, ignorecase=true) 
                                              | map(attribute='name') | unique | list %}  
        {% endif %}
        {% if matching_devices | length > 0 %}
          {{ matching_devices | join('\n') }}
        {% else %}
          No devices with such battery type
        {% endif %}
      {% else %}
        Search result
      {% endif %}
```

--------------------------------

### Add Devices Not Replaced to Maintenance List

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

This script calls the check_battery_last_replaced action and adds devices not replaced in the last 365 days to a todo list. It uses a response variable to store the results of the action.

```yaml
sequence:
  - action: battery_notes.check_battery_last_replaced
    data:
      days_last_replaced: 365
      raise_events: false
    response_variable: response
  - repeat:
      for_each: "{{ response.get('check_battery_last_replaced', []) }}"
      sequence:
        - action: todo.add_item
          metadata: {}
          data:
            item: >-
              {{ repeat.item.device_name }} - {{ 
              repeat.item.battery_type_and_quantity }}
          target:
            entity_id: todo.maintenance_list
alias: Add not replaced to maintenance list 
description: ""
```

--------------------------------

### Set Battery Replaced Using Device ID

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

This action snippet demonstrates how to call the set_battery_replaced action using the device_id obtained from an entity trigger.

```yaml
actions:
  - action: battery_notes.set_battery_replaced
    data:
      device_id: "{{ device_id(trigger.entity_id) }}"
```

--------------------------------

### battery_notes.check_battery_low

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/actions.md

Checks devices for a low battery status and can raise events for automation.

```APIDOC
## battery_notes.check_battery_low

### Description
Checks devices for a low battery status and can raise events for automation. The action will raise a separate `battery_threshold` event for each device that has a battery low status.

### Parameters
#### Data attributes
- **raise_events** (boolean) - Yes - Raise events for each matching device for use in automation triggers (default true).

### Notes
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.
```

--------------------------------

### Battery State Card Configuration

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

Configure the Battery State Card to display devices with low battery thresholds. It allows filtering and renaming of devices.

```yaml
type: custom:battery-state-card
secondary_info: "{attributes.battery_type_and_quantity}"
round: 0
filter:
  include:
    - name: entity_id
      value: "*_battery_plus"
  exclude:
    - name: attributes.battery_low
      value: false
bulk_rename:
  - from: "Battery+"
sort:
  - state
```

--------------------------------

### Monthly Check for Battery Not Replaced

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

This automation runs on the first day of each month to check for batteries not replaced in the last 365 days. It raises events for use with a Battery Not Replaced automation.

```yaml
alias: Monthly Battery Not Replaced Check
description: Check when a battery was last replaced
mode: single
triggers:
  - platform: template
    value_template: "{{ now().day == 1 }}"
conditions: []
actions:
  - action: battery_notes.check_battery_last_replaced
    data:
      days_last_replaced: 365
```

--------------------------------

### Battery Replaced Event Automation

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

Marks a battery as replaced when a battery_notes_battery_increased event is triggered. This automation helps track battery status changes.

```yaml
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 }}"
```

--------------------------------

### Weekly Battery Low Check Automation

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

Calls the check_battery_low action weekly, triggered by a Home Assistant schedule helper. This automation is useful for ensuring batteries are checked regularly, especially when combined with a low battery notification.

```yaml
alias: Battery Low Check
description: Check whether a battery is low
mode: single
triggers:
  - trigger: state
    entity_id:
      - schedule.maintenance
    to: "on"
conditions: []
actions:
  - action: battery_notes.check_battery_low
    data: {}
```

--------------------------------

### Automation for Battery Replaced Event

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/events.md

This automation triggers when a battery is replaced. It creates a persistent notification with details about the device and battery type. Use this to track battery replacements and potentially add them to inventory or shopping lists.

```yaml
alias: Battery Replaced
description: Battery replaced
mode: queued
max: 30
triggers:
  - trigger: event
    event_type: battery_notes_battery_replaced
conditions: []
actions:
  - action: persistent_notification.create
    data:
      title: |
        {{ trigger.event.data.device_name }} Battery Replaced
      message: >
        You just used {{ trigger.event.data.battery_type_and_quantity }} batteries
```

--------------------------------

### Battery Low Template: Direct State

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/index.md

This template directly uses the state of another sensor to determine if the battery is low. Useful for sensors that explicitly report 'Low'.

```yaml
{{ states('sensor.mysensor_battery_low') }}
```

--------------------------------

### Daily Battery Low Check Automation

Source: https://github.com/andrew-codechimp/ha-battery-notes/blob/main/docs/community.md

Calls the check_battery_low action every day at 9 AM to raise events for batteries that are still low. This is intended to be used with a low battery notification system.

```yaml
alias: Daily Battery Low Check
description: Check whether a battery is low
mode: single
triggers:
  - trigger: time
    at: "09:00:00"
conditions: []
actions:
  - action: battery_notes.check_battery_low
```