Sankey Chart Card

A Home Assistant lovelace card to display a sankey chart. For example for energy/power/water consumption.

This card is intended to display connections between entities with numeric state. It is not a general graph card.

Installation

Install through HACS

Options

Sections object

Entities object

Children object

Reconcile config

Entity types

• entity - The default value, representing an entity from HA
• passthrough - Used for connecting entities across sections, passing through intermediate sections. The card creates such passtroughs automatically when needed but you can create them manually in order to have the connection pass through a specific place. See issue #9. Here is an example passthrough config:

- entity_id: sensor.child_sensor
  type: passthrough
  # Note that passthrough entities have no children as they always connect to their own entity_id in the next section

• remaining_parent_state - Used for representing the unaccounted state from this entity's parent. Formerly known as the remaining configuration. Useful for displaying the unmeasured state as "Other". See issue #2 & #28. Only 1 is allowed per group. If you add 2, the state will not be split between them but an error will appear. Obviously it must be listed in some prior entity's children. Example:

- entity_id: whatever # as long as it is unique
  type: remaining_parent_state
  name: Other

• remaining_child_state - Used for representing the unaccounted state in this entity's children. Like remaining_parent_state but in reverse. Useful for displaying discrepancies where the children add up to more than the parent. See issue #2 & #15. Example:

- entity_id: whatever # as long as it is unique
  type: remaining_child_state
  name: Discrepancy
  children:
    # the relevant child entities

Autoconfig

This card supports automatic configuration generation based on the HA energy dashboard. It will set default values for some config parameters and populate the sections param. This is meant to show energy data and assumes you have configured your Energy Dashboard in HA. Use it like this:

- type: energy-date-selection # you can put this anywhere you want but it is required for energy dashboard integration
- type: custom:sankey-chart
  # ...any other options
  autoconfig:
    print_yaml: false # optional
    # any additional autoconfig options (listed below)

or like this:

- type: custom:sankey-chart
  autoconfig: true
  time_period_from: "now/d" # today

Time Period

The time_period_from and time_period_to options allow you to specify a custom time period for data retrieval. The format is based on Grafana's time range format.

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years)

Note that while seconds and minutes are supported, there is a delay in the statistics data in HA of up to 1 hour, so showing small periods like the last 30 mins probably won't work.

Examples:

• now-5m: 5 minutes ago
• now-1h: 1 hour ago
• now-1d: 1 day ago
• now-1w: 1 week ago
• now-1M: 1 month ago
• now/d: Start of the current day
• now/w: Start of the current week
• now/M: Start of the current month
• now/y: Start of the current year
• now-1d/d: Start of the previous day

If time_period_to is not specified, it defaults to now.

Example configurations:

type: custom:sankey-chart
title: Last 7 days up to the current moment
time_period_from: "now-7d"

type: custom:sankey-chart
title: Yesterday
time_period_from: "now-1d/d"
time_period_to: "now/d"

Examples

Simple

- type: custom:sankey-chart
  show_names: true
  sections:
    - entities:
      - entity_id: sensor.power
        children:
          - sensor.washing_machine_power
          - sensor.other_power
    - entities:
      - sensor.washing_machine_power
      - sensor.other_power

Energy use

- type: custom:sankey-chart
  show_names: true
  unit_prefix: k
  round: 1
  wide: true
  sections:
    - entities:
        - entity_id: sensor.solar
          color: var(--warning-color)
          children:
            - sensor.total_energy
        - entity_id: sensor.grid
          children:
            - sensor.total_energy
        - entity_id: sensor.battery
          color: var(--success-color)
          children:
            - sensor.total_energy
    - entities:
        - entity_id: sensor.total_energy
          children:
            - sensor.floor1
            - sensor.floor2
            - sensor.garage
    - entities:
        - entity_id: sensor.garage
          color: purple
          children:
            - sensor.ev_charger
            - garage_other
        - entity_id: sensor.floor1
          children:
            - sensor.living_room
            - entity_id: sensor.washer
              connection_entity_id: sensor.washer_energy_net
        - entity_id: sensor.floor2
    - entities:
        - entity_id: sensor.ev_charger
          tap_action:
            action: toggle
        - entity_id: garage_other
          type: remaining_parent_state
          name: Other
        - sensor.living_room
        - sensor.washer

Reconcile state

Example config where the state of the children must not exceed their parent. reconcile_to: max means to take the bigger of the two values. In other words, if the sum of the children is more than the state of the parent, the parent state will be set to the sum of its children within the card. reconcile_to: min would do the opposite and reduce the state of the children so they fully fit within the parent. latest just takes whichever value was updated last.

- type: custom:sankey-chart
  show_names: true
  sections:
    - entities:
      - entity_id: sensor.power
        children_sum:
          should_be: equal_or_less
          reconcile_to: max
        children:
          - sensor.washing_machine_power
          - sensor.other_power
    - entities:
      - sensor.washing_machine_power
      - sensor.other_power

You can find more examples and help in the HA forum https://community.home-assistant.io/t/anyone-using-the-sankey-chart-card/423125

Energy Dashboard

This card supports partial Energy dashboard integration. You still need to specify the entities and connections for now. See energy_date_selection option.

Currently this chart just shows historical data based on a energy-date-selection card. It doesn't know/care if your entities are in the default energy dashboard.

FAQ

Q: Do my entities need to be added to the energy dashboard first?

A: This card doesn't know/care if an entity is in the energy dashboard. Unless you use autoconfig because that relies entirely on the energy dashboard.

Q: How do I get total [daily] energy?

A: There isn't a general Consumed Energy sensor in the HA Energy dashboard AFAIK. HA calculates it based on all the in/out kWh values. I can't tell you exactly how to calculate it because it depends on what values you can monitor. Some people already have a Total Consumption sensor, others have a Current Consumption and create an integration sensor from that, etc.

Q: Can I group/sum entities in the chart?

A: The easiest way is to do it with a template sensor in HA. However it can be done in the chart without a new HA entity. If you have an entity with type: remaining_parent_state and it is the only child of its parents, it will just be a sum of all the parents. Similarly if you have an entity with type: remaining_child_state and it is the only parent of all its children, it will be a sum of all the children.

Q: How do I zoom back out after using the zoom action?

A: Tap the same (currently top level) entity again to reset the zoom level.

Q: My (template) sensor doesn't work with energy_date_selection!?

A: Sensors should have a proper state_class in order for statistics to work. Most commonly state_class: total. See https://developers.home-assistant.io/docs/core/entity/sensor/#long-term-statistics

Q: Can you add feature X, so I don't have to create template entities in HA?

A: Most probably no. There is nothing wrong with template entities and they should be the prefered approach instead of duplicating HA functionality in every card. I do make exceptions for often required features like remaining_parent_state but prefer to rely on HA functionality whenever I can.

Q: My entities are not rendered where I expected

A: By default entities are displayed in the order in which they appear in the config. You can rearrange them in the YAML or use the sorting options.

Development

1. npm i
2. npm start
3. The compiled .js file will be accessible on http://127.0.0.1:3000/ha-sankey-chart.js.
4. On a running Home Assistant installation add this to your Lovelace resources:

- url: 'http://127.0.0.1:3000/ha-sankey-chart.js'
  type: module