DOCSEARCHbyAlgolia
Submit Docs

Powercalc Documentation

repository·master·Indexed 23 days ago

https://github.com/bramstroker/homeassistant-powercalc

A custom Home Assistant integration designed to estimate energy consumption for devices without physical smart plugs. Powercalc uses device-specific profiles and state-based modeling to create virtual power, energy, and cost sensors. It includes a profile library, utility meters for usage breakdown, and experimental tools like Powercalc Measure for creating custom power profiles directly from Home Assistant entities.

Tokens
62.4K
Snippets
152
Records
324
Agent score
81%

What's inside Powercalc

  1. What is Powercalc?

    master

    Powercalc is a Home Assistant custom component that enables energy monitoring for devices that lack built-in power metering (such as lights, fans, and smart speakers). It achieves this by creating virtual sensors that estimate power consumption.

    Key Capabilities

    • Device Estimation: Uses specific strategies for lights (calculating based on brightness, hue/saturation, and color temperature) and generic attribute-based calculations for other devices.
    • Energy Tracking: Automatically creates cost sensors to track spending and utility meters to aggregate usage by day, week, or month.
    • Aggregation: Creates group sensors to combine the energy usage of specific devices, rooms, or an entire home into a single total.

  2. Overview of PowerCalc

    master

    PowerCalc is a Home Assistant integration that estimates energy consumption for devices that lack native power measurement capabilities (e.g., lights, fans, media players). Instead of requiring physical smart plugs, it uses smart models and a built-in profile library to create virtual power sensors.

    Key features include:

    • Virtual Power Sensors: Estimates power based on device states like brightness, color, or fan speed.
    • Cost Sensors: Tracks energy spending.
    • Utility Meters: Breaks down usage by day, week, or month.
    • Group Sensors: Aggregates usage for devices, rooms, or entire homes.

  4. Overview of Powercalc Measure

    master

    Powercalc Measure is an experimental tool that allows you to create device power profiles directly from Home Assistant entities (such as lights, speakers, fans, or charging robots) via an authenticated Ingress UI. It works by controlling the selected device during a measurement period to capture its power consumption profile.

    Note: This is an experimental first release and is currently only supported on Home Assistant OS for amd64 and aarch64 architectures.

  5. Group power sensors using Powercalc

    master

    Powercalc allows you to aggregate multiple individual power and energy sensors into a single sensor that represents their sum. This is useful for monitoring the total consumption of specific categories, such as all lights in a house.

    Available group types include:

    • Custom group: Create a group with a specific name by manually adding individual power and energy sensors. These groups can be nested to create a hierarchy.
    • Domain group: Automatically create a group for all power entities belonging to a specific Home Assistant domain (e.g., light or media_player).
    • Subtract group: Calculate the difference by subtracting the power of one or more entities from a target entity.
    • Tracked/Untracked group: Sum all power sensors that are marked as 'tracked' or 'untracked'.
    • Standby group: A default group that sums the power consumption of all devices when they are in standby mode.

  6. What is the Playbook strategy?

    master

    The playbook strategy allows you to record power consumption patterns over time and replay them in Home Assistant. This is ideal for program-based devices (like washing machines or dishwashers) that have predictable power cycles.

    Playbooks can be:

    • Generated using the Powercalc measure tool.
    • Created manually as CSV files.

    They allow you to simulate realistic power models for devices that lack built-in power monitoring or to trigger specific power profiles based on device states.

  7. Overview of Virtual Power Strategies

    master
    Powercalc uses 'strategies' to provide different calculation methods for virtual power sensors. A strategy determines how power consumption is estimated based on the state or input of a device. Common use cases include fixed power consumption, linear scaling (for dimmable devices), lookup tables (LUT) for complex mappings, and composite strategies that combine multiple methods.

  8. Understand utility meter naming conventions

    master

    Utility meters follow a specific naming pattern based on the parent energy sensor. They share the same base name as the energy sensor but are extended by the meter cycle.

    Example Pattern: If your energy sensor is sensor.floorlamp_livingroom_energy, the automatically created utility meters will be:

    • sensor.floorlamp_livingroom_energy_daily
    • sensor.floorlamp_livingroom_energy_weekly
    • sensor.floorlamp_livingroom_energy_monthly

  9. Define power per entity state with states_power

    master

    The states_power setting allows you to specify different power consumption levels based on the current state of the entity. This is useful for devices like media players that consume different amounts of power when playing vs idle.

    Rules for states_power:

    • If no match is found in states_power, the configured power value is used.
    • Warning: The states off, not_home, standby, and unavailable are considered "off" by Powercalc. For these states, you should use standby_power instead of defining them in states_power.
    • You can use state attributes by using the | delimiter (e.g., attribute|value).
    # Example using states
powercalc:
  sensors:
    - entity_id: media_player.sonos_living
      fixed:
        states_power:
          playing: 8.3
          paused: 2.25
          idle: 1.5

# Example using state attributes
powercalc:
  sensors:
    - entity_id: media_player.sonos_living
      fixed:
        power: 12
        states_power:
          media_content_id|Spotify: 5
          media_content_id|Youtube: 10

  10. Cost sensors for utility meters

    master

    If you have enabled utility meters in Powercalc, the system automatically creates an additional cost sensor for every utility meter created.

    This allows you to track the cost per cycle (e.g., daily, weekly, monthly) in addition to the total cost sensor. These per-meter cost sensors reset simultaneously with their corresponding utility meter.

    Example: For a light light.floorlamp_livingroom with daily and monthly meters enabled, you will get:

    • sensor.floorlamp_livingroom_cost (total cost)
    • sensor.floorlamp_livingroom_energy_daily_cost
    • sensor.floorlamp_livingroom_energy_monthly_cost

  12. How the Powercalc profile library works

    master

    Powercalc includes a large library of predefined power profiles for various devices.

    Discovery & Setup

    • Automatic Discovery: At startup, Powercalc scans your Home Assistant installation to match entities against the library. If a match is found, it provides a discovery flow for setup.
    • Manual Setup: You can manually set up Powercalc sensors for an entity using the Virtual power library.

    Library Management

    • On-demand Downloads: Since version 1.12.0, profiles are downloaded from the internet on demand rather than being bundled with the component. This allows for library updates without requiring a component update.
    • Internet Requirement: Because the library is hosted on GitHub, an internet connection is required to download profiles unless the download feature is disabled.