Skip to content

MIGRATION.md

Latest commit

 

History

History
284 lines (244 loc) · 6.82 KB

MIGRATION.md

File metadata and controls

284 lines (244 loc) · 6.82 KB
Raw

Migration Guide: v3 to v4 Config Format

Note: If you use the visual card editor, your config will be automatically converted to v4 format when you save. This guide is for users who edit their configuration in YAML mode only.

This guide explains how to manually convert your existing v3 configuration to the new v4 format.

Overview of Changes

The v4 format separates the config into three distinct parts:

v3 Format v4 Format
sections[].entities[] nodes[] - flat list of all entities
entity.children[] links[] - connections between nodes
entity_id id
connection_entity_id value (in links)
color_on_state, color_limit, color_above, color_below color object with ranges

Step-by-Step Migration

Step 1: Extract nodes from sections

In v3, entities were nested inside sections. In v4, all nodes are in a flat nodes[] array with a section index.

v3:

sections:
  - entities:
      - entity_id: sensor.power
        name: Total Power
      - entity_id: sensor.solar
  - entities:
      - entity_id: sensor.device1
      - entity_id: sensor.device2

v4:

nodes:
  - id: sensor.power        # entity_id -> id
    section: 0              # first section = index 0
    name: Total Power
  - id: sensor.solar
    section: 0
  - id: sensor.device1
    section: 1              # second section = index 1
  - id: sensor.device2
    section: 1

Step 2: Convert children to links

In v3, parent-child relationships were defined via children[] on each entity. In v4, these become entries in the links[] array.

v3:

sections:
  - entities:
      - entity_id: sensor.power
        children:
          - sensor.device1
          - sensor.device2
  - entities:
      - sensor.device1
      - sensor.device2

v4:

nodes:
  - id: sensor.power
    section: 0
  - id: sensor.device1
    section: 1
  - id: sensor.device2
    section: 1
links:
  - source: sensor.power
    target: sensor.device1
  - source: sensor.power
    target: sensor.device2

Step 3: Convert connection entities

If you used connection_entity_id to specify how much flows between nodes, use the value property in links.

v3:

- entity_id: sensor.floor1
  children:
    - entity_id: sensor.washer
      connection_entity_id: sensor.washer_energy

v4:

links:
  - source: sensor.floor1
    target: sensor.washer
    value: sensor.washer_energy

Step 4: Convert color ranges (optional)

If you used color_on_state with color_limit, color_above, and color_below, convert to the new color object format.

v3:

- entity_id: sensor.temperature
  color_on_state: true
  color_limit: 25
  color_above: red
  color_below: green

v4:

- id: sensor.temperature
  color:
    red:
      from: 25    # red when >= 25
    green:
      to: 25      # green when < 25

The new format is more flexible and supports multiple ranges:

color:
  red:
    from: 30      # red when >= 30
  orange:
    from: 20
    to: 30        # orange when >= 20 and < 30
  green:
    to: 20        # green when < 20

Step 5: Update passthrough nodes

In v3, passthrough entities reused the entity_id of the entity they passed flow to — the card inferred the chain by matching ids. v4 requires every node id to be unique, and passthroughs are ordinary nodes in the links graph. Give each passthrough a unique id and connect it with explicit links.

v3:

sections:
  - entities:
      - entity_id: sensor.grid
        children:
          - sensor.house
  - entities:
      - entity_id: sensor.house
        type: passthrough
  - entities:
      - entity_id: sensor.house
        children:
          - sensor.kitchen
  - entities:
      - entity_id: sensor.kitchen

v4:

nodes:
  - id: sensor.grid
    section: 0
  - id: sensor.house__passthrough_1   # any unique id; this is the pattern the auto-migration uses
    section: 1
    type: passthrough
  - id: sensor.house
    section: 2
  - id: sensor.kitchen
    section: 3
links:
  - source: sensor.grid
    target: sensor.house__passthrough_1   # parent links into the passthrough, not the distant entity
  - source: sensor.house__passthrough_1
    target: sensor.house                  # passthrough links out to the real entity
  - source: sensor.house
    target: sensor.kitchen

If you link across a section gap without declaring a passthrough, the card auto-inserts one (and rewrites the link into an explicit chain) so you don't have to do this manually for every hop.

Step 6: Move section config (if any)

Section-level settings like sort_by, sort_dir, and min_width stay in the sections[] array, but without entities.

v3:

sections:
  - entities:
      - sensor.a
      - sensor.b
    sort_by: state
    min_width: 200

v4:

nodes:
  - id: sensor.a
    section: 0
  - id: sensor.b
    section: 0
sections:
  - sort_by: state
    min_width: 200

Complete Example

Before (v3)

type: custom:sankey-chart
show_names: true
sections:
  - entities:
      - entity_id: sensor.grid
        children:
          - sensor.house
      - entity_id: sensor.solar
        color: orange
        children:
          - sensor.house
  - entities:
      - entity_id: sensor.house
        children:
          - sensor.hvac
          - entity_id: sensor.washer
            connection_entity_id: sensor.washer_power
          - other
      - entity_id: other
        type: remaining_parent_state
        name: Other
  - entities:
      - sensor.hvac
      - sensor.washer

After (v4)

type: custom:sankey-chart
show_names: true
nodes:
  # Section 0 - Sources
  - id: sensor.grid
    section: 0
  - id: sensor.solar
    section: 0
    color: orange
  # Section 1 - House
  - id: sensor.house
    section: 1
  - id: other
    section: 1
    type: remaining_parent_state
    name: Other
  # Section 2 - Consumers
  - id: sensor.hvac
    section: 2
  - id: sensor.washer
    section: 2
links:
  - source: sensor.grid
    target: sensor.house
  - source: sensor.solar
    target: sensor.house
  - source: sensor.house
    target: sensor.hvac
  - source: sensor.house
    target: sensor.washer
    value: sensor.washer_power
  - source: sensor.house
    target: other

Tips

  1. Section indices are 0-based - first section is 0, second is 1, etc.
  2. Links define the flow - the order of links doesn't matter, but nodes are rendered in the order they appear
  3. Passthrough nodes can use a custom id now but their links have to be defined with that id