Skip to content

Part of upcoming release in 2025!

The ProgPath tool

4.0.1 · Output

The progress path tool is an advanced tool that can display a sensor value on different path types like: line, spiral, rectangle and circle. Each type can have its own variants and specific functionality.

This tool is still beta / highly experimental

Some examples:

  • Sensor with ProgPath "Spiral/Helix"

    A sensor card with a progpath showing the actual power usage using a smooth colorstop.

    Swiss Army Knife Progpath Tool Spiral/Helix Swiss Army Knife Progpath Tool Spiral/Helix

    Spiral Usage

  • Sensor with ProgPath "Spiral/Spiral"

    A sensor card with a progpath showing the actual power usage using a smooth colorstop.

    Swiss Army Knife Progpath Tool Spiral/Spiral Swiss Army Knife Progpath Tool Spiral/Spiral

    Spiral Usage

  • Sensor with ProgPath "Line"

    A sensor card with a progpath showing the actual power usage using a stepped colorstop.

    Swiss Army Knife Progpath Tool Line Swiss Army Knife Progpath Tool Line

    Line Usage

  • Sensor with ProgPath "Circle"

    A sensor card with a progpath showing the actual power usage using a stepped colorstop.

    Swiss Army Knife Progpath Tool Circle Swiss Army Knife Progpath Tool Circle

    Circle Usage

  • Sensor with ProgPath "Rectangle"

    A sensor card with a progpath showing the actual power usage using a stepped colorstop.

    Swiss Army Knife Progpath Tool Rectangle Swiss Army Knife Progpath Tool Rectangle

    Rectangle Usage

  • Sensor with ProgPath "Rectangle"

    A sensor card with a progpath showing the actual power usage using a single color for the active path.

    Swiss Army Knife Progpath Tool Rectangle Swiss Army Knife Progpath Tool Rectangle

    Rectangle Usage

Basic Usage

The ProgPath tool needs at least a path_type and some other show field settings:

Basic show config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- type: progpath
  progpath:
    show:
      path_type: spiral
      variant: arch_helix
      viz:
        linecap: round_start_end # butt, round_start_end, butt_start_end
      background: true
      track: none
      marker: navigation #none #pan-vertical #navigation
      active_track: true
      mask: true
      scale: none
Field Value Description
path_type spiral, line, circle, rectangle The type of Progress Path
variant depends on path_type See specific type for possible variants

Main show fields that enable/disable/set the various components of the ProgPath tool:

show field Value Description
background true,false Add background track yes/no
track none, colorstops, dashes How to display the track
active_track true, false TBD
marker none, pan-vertical, navigation, etc. Type of marker @ current position
mask true, false TBD
scale none, colorstops Show scale as colorstops, or no scale

Configuration of separate components like background, track, marker, etc.

Basic show config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
- type: progpath
    # Background config
    background:
      width: 5

    # Track config
    track:
      width: 3

    # Active Track config
    active_track:
      width: 3
      color:
        smooth: true      

    # Marker config
    marker:
      size: 12
      offset: 0   # offset sets the marker on/above/below the track
                  # seen from the center/inside of the tool
                  # A negative value like -36, sets the marker at
                  # the inside of the track
                  # 0 means centered on the track!
      color:      # A marker can have a color depending
                  # on the sensor value/colorstop
        animate: interior # outline, interior, both, none
        smooth: false

Styling

The ProgPath tool has support for the following forms of styling:

Method Support Description
classes Using SAK or User defined class definitions
styles Using inline SVG and CSS styles

ProgPath - Spiral

Basic definition

path_type variant Description
spiral arch_spiral A true spiral from inside to outside
spiral arch_helix A helix with configurable angle and offsets

Specific spiral and arch_helix definitions

Basic show config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- type: progpath
    spiral:
      points: 360     # Number of points used to draw the spiral/helix
                      # More points give a smoother spiral/helix
      degrees: 1800   # Number of turns in degrees: 1800 = 5 turns
      helix:
        hw_ratio: 0
        iso_angle: 90
        offset_y: 40
        offset_x: 0
        adjust_height: true
Field Value Description
points number Number of points (or segments) used to draw the spiral/helix. More points give smoother curves. Too many will hamper performance. Experiment!
degrees degrees Total number of turns for the spiral/helix. A full turn is 360 degrees. So 1800 is 5 turns.
Helix Fields Value Description
hw_ratio number Defaults to 0. Determines the viewing angle. 0.5 gives you overlapping turns, and a view from above...
iso_angle degrees Default to 90 for vertical helix
offset_y number Vertical space between helix turns.
offset_x number Horizontal adjustment bottom of helix. A positive value will move the bottom side to the right, a negative value to the left. It determines the relative position of the bottom in relation to the top.

Examples with different hw_ratio, y and x

  • Helix, hw=0.5, y=10, x=0

    Swiss Army Knife Progpath Tool Spiral/Helix Swiss Army Knife Progpath Tool Spiral/Helix

  • Helix, hw=0.75, y=10, x=0

    Swiss Army Knife Progpath Tool Spiral/Helix Swiss Army Knife Progpath Tool Spiral/Helix

  • Helix, hw=0.25, y=20, x=0

    Swiss Army Knife Progpath Tool Spiral/Helix Swiss Army Knife Progpath Tool Spiral/Helix

  • Helix, hw=0, y=40, x=10

    Swiss Army Knife Progpath Tool Spiral/Helix Swiss Army Knife Progpath Tool Spiral/Helix

ProgPath - Line

Basic definition

path_type variant Description
line none A line is a line...

Specific line

Basic show config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- type: progpath
  progpath:
    show:
      path_type: line
      viz:
        linecap: round_start_end # butt, round_start_end, butt_start_end
      background: true
      track: colorstops #dashes
      marker: none #pan-vertical #navigation
      active_track: false
      mask: true
      scale: colorstops

And then the line and scale config:

Line and Scale config
1
2
3
4
5
6
7
8
9
- type: progpath
  progpath:
    scale:
      width: 3
      offset: -10 # Negative value means: below line graph
    line:
      margin:
        left: 5
        right: 5

ProgPath - Circle

Basic definition

path_type variant Description
circle none A circle is a circle...

Specific circle

Basic show config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- type: progpath
  progpath:
    show:
      path_type: circle
      viz:
        linecap: round_start_end                        
      background: false
      track: none
      marker: sak-clock-hand-ring-small # Specific hand!!
      active_track: false
      mask: true
      scale: colorstops

And then the circle, scale and marker definitions:

Circle, Scale and Marker config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
- type: progpath
  progpath:
    circle:
      start_angle: 100
      stop_angle: 260
      direction: ccw      # Counter clock wise
    scale:
      width: 24
      offset: -20
    track:
      width: 5
    marker:
      size: 40
      offset: 0
      attach_to: center # or circumference
      color:
        animate: none
        smooth: true

ProgPath - Rectangle

Basic definition

path_type variant Description
rectangle none A rectangle is a rectangle...

Specific rectangle

Basic show config
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- type: progpath
  progpath:
    show:
      path_type: rectangle
      viz:
        linecap: round_start_end                         
      background: true
      track: colorstops #dashes none
      marker: navigation
      active_track: false
      mask: false

Example card and definition

Swiss Army Knife Progpath Tool Rectangle Swiss Army Knife Progpath Tool Rectangle

Full definition of example card 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
- type: 'custom:swiss-army-knife-card'
  entities:
    - entity: sensor.dsmr_reading_electricity_currently_delivered
      name: 'Electricity'
      area: 'House'
  dev:
    real: true
  layout:
    aspectratio: 2/1
    toolsets:
      # ==============================================================================
      - toolset: circle-with-icon
        position:
          cx: 100
          cy: 50
        tools:
          # ------------------------------------------------------------
          - type: progpath
            position:
              cx: 50
              cy: 50
              width: 180
              height: 80
            entity_index: 0
            progpath:
              show:
                path_type: rectangle
                viz:
                  linecap: round_start_end                         
                background: true
                track: colorstops #dashes
                marker: navigation
                active_track: false #true
                mask: false #true
              rectangle:
                start:
                  side: left
                  position: -30 # 30 below center of graph
                  d: cw         # clock-wise draw
                stop:
                  side: top
                  position: 85 # 85 right of center of graph
                radius:
                  tl: 10      # Top left = 10
                  tr: 0       # Top right
                  br: 0       # Bottom right
                  bl: 0       # Bottom left
              background:
                width: 8      # Background is wider than track
              track:
                width: 5
              marker:
                size: 12      # Size of marker
                offset: -36   # Marker on inside of graph
                color:
                  animate: both # outline, interior, both, none
                  smooth: true  # Use gradients for colorstops
              colorstops:
                template:
                  name: sak_colorstops_energy_4kw_v2
                  variables:
                    - sak_colorstops_gap: 1
            styles:
              marker:
                fill: none
                stroke: var(--ha-card-background,var(--card-background-color,#fff))
                stroke-width: 0.4em
                stroke-linejoin: round    # Use smooth edges for
                stroke-linecap: round     # ..the navigation marker
                scale: 0.7 1              # Adjust marker size in width/height
                transform-origin: center  # Scale from center of marker

          # ------------------------------------------------------------
          - type: icon
            position:
              cx: 50
              cy: 32.5
              align: center
              icon_size: 20
            entity_index: 0

          # ------------------------------------------------------------
          - type: state
            position:
              cx: 50
              cy: 52.5
            entity_indexes:
              - entity_index: 0
            show:
              uom: bottom
            styles:
              tool:
              state:
                text-anchor: middle
                font-size: 16em
                font-weight: 600
                # fill: var(--primary-background-color)
                transition: opacity 0.5s linear

Haptics

See: https://companion.home-assistant.io/docs/integrations/haptics/ for devices that support haptics

The tool supports haptic feedback through user_actions/ tap_action definition

Action Haptic Description
Click haptic Uses the haptic property defined in the user_actions definition of the tool. If not specified, a default of medium is used 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
  tools:
    - type: icon
      position:
        cx: 10
        cy: 10
        align: center
        icon_size: 15
      entity_index: 0
      user_actions:
        tap_action:
          haptic: success
          actions:
            - action: more-info

Possible values for haptic feedback:

Haptic Description
success Indicates that a task or action has completed.
warning Indicates that a task or action has produced a warning of some kind.
failure Indicates that a task or action has failed.
light Provides a physical metaphor that complements the visual experience.
medium Provides a physical metaphor that complements the visual experience.
heavy Provides a physical metaphor that complements the visual experience.
selection Indicates that the selection is actively changing.