Control Overlay - Embedding Home Assistant Cards

Use any Home Assistant card as an MSD overlay Embed interactive HA cards with full functionality and line connector support

Overview
Quick Start
Basic Configuration
Card Types
Positioning & Sizing
Line Connections
Advanced Examples
Common Patterns
Troubleshooting
Best Practices

Overview

The control overlay type allows you to embed any Home Assistant card (custom or built-in) directly into your MSD canvas. These embedded cards work exactly like they would standalone, but with the added benefit of precise positioning, line connections, and integration with MSD features.

What You Can Embed

✅ LCARdS Cards - All LCARdS card types
✅ Custom Cards - mini-graph-card, apexcharts-card, etc.
✅ Built-in HA Cards - button, light, entities, gauge, etc.
✅ Complex Cards - picture-elements, grid, conditional, etc.

Key Features

Quick Start

Minimal Example

yaml

type: custom:lcards-msd-card
  msd:
    overlays:
      - type: control
        id: my_light_control
        card:
          type: button
          entity: light.living_room
          name: "Living Room"
          show_icon: true
          tap_action:
            action: toggle
        position: [100, 100]
        size: [200, 100]

Result: A standard Home Assistant button card positioned at coordinates (100, 100) with size 200×100.

Alternative: Nested Config

You can also nest card properties inside a config key (both patterns work):

yaml

- type: control
  id: my_light_control
  card:
    type: button
    config:
      entity: light.living_room
      name: "Living Room"
      show_icon: true
      tap_action:
        action: toggle
  position: [100, 100]
  size: [200, 100]

Note: Both flat and nested card property patterns are valid HA patterns. Use whichever you prefer.

❌ NOT Supported Patterns

The following patterns are NOT supported and will cause validation errors:

❌ Flat/Direct Pattern (WRONG)

yaml

# ❌ WRONG - Do not use card type directly as overlay type
overlays:
  - type: custom:lcards-button    # ❌ Wrong
    id: my_button
    entity: light.kitchen
    position: [100, 100]
    size: [200, 100]

Error: type must be control, not a card type.

Fix: Use the nested card property:

yaml

# ✅ CORRECT
overlays:
  - type: control                  # ✅ Correct
    id: my_button
    card:
      type: custom:lcards-button   # Card type goes here
      entity: light.kitchen
    position: [100, 100]
    size: [200, 100]

❌ Legacy card_config Pattern (WRONG)

yaml

# ❌ WRONG - Legacy field names not supported
- type: control
  id: my_control
  card_config:      # ❌ Wrong - deprecated
    type: button
    entity: light.kitchen

Error: Field card_config is deprecated.

Fix: Use card instead:

yaml

# ✅ CORRECT
- type: control
  id: my_control
  card:             # ✅ Correct
    type: button
    entity: light.kitchen

❌ Legacy cardConfig Pattern (WRONG)

yaml

# ❌ WRONG - camelCase variant not supported
- type: control
  id: my_control
  cardConfig:       # ❌ Wrong - deprecated
    type: button
    entity: light.kitchen

Error: Field cardConfig is deprecated.

Fix: Use card instead (same as above).

Basic Configuration

Configuration Structure

Note: Card properties can be flat (e.g., entity: light.example) or nested under config:. Both patterns work.

Required Properties

Property	Type	Description	Example
`type`	string	Must be `control`	`control`
`id`	string	Unique identifier	`light_control_1`
`card`	object	Card definition	See below
`position`	array	`[x, y]` coordinates	`[100, 200]`
`size`	array	`[width, height]` dimensions	`[200, 150]`

Optional Properties

Property	Type	Description	Default
`z_index`	number	Layering order	`1000`
`visible`	boolean	Show/hide overlay	`true`

Card Types

LCARdS Cards

Embed any LCARdS button or custom card:

yaml

- type: control
  id: lcars_button
  card:
    type: custom:lcards-button
    entity: switch.warp_drive
    preset: lozenge
    text:
      label:
        content: "WARP DRIVE"
    tap_action:
      action: toggle
  position: [1200, 120]
  size: [200, 180]

Benefits of LCARdS Cards:

Perfect styling match with LCARS theme
Advanced features like multi-tap actions
Custom shapes and effects

Built-in Home Assistant Cards

Use standard HA cards with simplified syntax (both flat and nested patterns work):

yaml

# Button Card (flat properties)
- type: control
  id: button_control
  card:
    type: button
    entity: light.bedroom
    name: "Bedroom"
    icon: mdi:lightbulb
    show_name: true
    show_icon: true
    tap_action:
      action: toggle
  position: [400, 200]
  size: [150, 80]

# Light Card (flat properties)
- type: control
  id: light_control
  card:
    type: light
    entity: light.kitchen
    name: "Kitchen Light"
  position: [600, 200]
  size: [200, 120]

# Entities Card (flat properties)
- type: control
  id: entities_control
  card:
    type: entities
    entities:
      - light.living_room
      - light.bedroom
      - light.kitchen
    title: "All Lights"
  position: [100, 400]
  size: [300, 200]

Custom Cards

Embed popular custom cards:

yaml

# mini-graph-card (flat properties)
- type: control
  id: temp_graph
  card:
    type: custom:mini-graph-card
    entities:
      - sensor.temperature
    hours_to_show: 24
    line_width: 2
    font_size: 75
  position: [800, 100]
  size: [400, 250]

# apexcharts-card (flat properties)
- type: control
  id: power_chart
  card:
    type: custom:apexcharts-card
    graph_span: 24h
    series:
      - entity: sensor.power_consumption
        name: Power
    apex_config:
      chart:
        height: 200
  position: [100, 700]
  size: [500, 250]

Positioning & Sizing

Coordinate System

Control overlays use the MSD viewBox coordinate system (typically 1920×1080):

Position Guidelines

yaml

# Top area
position: [100, 100]    # Top-left
position: [960, 100]    # Top-center
position: [1700, 100]   # Top-right

# Middle area
position: [100, 500]    # Middle-left
position: [960, 500]    # Center
position: [1700, 500]   # Middle-right

# Bottom area
position: [100, 900]    # Bottom-left
position: [960, 900]    # Bottom-center
position: [1700, 900]   # Bottom-right

Sizing Best Practices

Card Type	Recommended Size	Notes
Button	`[150, 80]`	Standard button
Button (large)	`[200, 120]`	Larger touch target
Light	`[200, 120]`	With brightness slider
Entities (3-5)	`[300, 200]`	Small entity list
Entities (6-10)	`[300, 350]`	Medium list
Graph	`[400, 250]`	Readable chart
LCARdS Button	`[200, 180]`	LCARS lozenge

Line Connections

9-Point Attachment System

Control overlays support the same 9-point attachment system as other overlays:

Connecting Lines to Controls

yaml

overlays:
  # Control overlay
  - type: control
    id: light_control
    card:
      type: button
      entity: light.bedroom
      name: "Bedroom"
    position: [400, 200]
    size: [150, 80]

  # Text label
  - type: text
    id: label
    text: "LIGHTING"
    position: [200, 200]
    size: [150, 40]

  # Line connecting label to control
  - type: line
    id: connector
    anchor_to: label
    anchor_side: middle-right
    attach_to: light_control
    attach_side: middle-left
    style:
      stroke: var(--lcars-blue)
      stroke_width: 2

Result: A line connects from the right side of the "LIGHTING" label to the left side of the button card.

Multiple Connections Example

yaml

overlays:
  # Central control
  - type: control
    id: main_control
    card:
      type: entities
      entities:
        - light.living_room
        - light.bedroom
        - light.kitchen
      title: "Light Control"
    position: [800, 400]
    size: [300, 200]

  # Status indicators
  - type: text
    id: status_1
    text: "ACTIVE"
    position: [500, 450]

  - type: text
    id: status_2
    text: "ON"
    position: [500, 500]

  - type: text
    id: status_3
    text: "DIM"
    position: [500, 550]

  # Lines from indicators to control
  - type: line
    anchor_to: status_1
    anchor_side: middle-right
    attach_to: main_control
    attach_side: middle-left

  - type: line
    anchor_to: status_2
    anchor_side: middle-right
    attach_to: main_control
    attach_side: middle-left

  - type: line
    anchor_to: status_3
    anchor_side: middle-right
    attach_to: main_control
    attach_side: middle-left

Advanced Examples

Dashboard Panel with Graph and Controls

yaml

overlays:
  # Panel title
  - type: text
    id: panel_title
    text: "ENVIRONMENTAL CONTROL"
    position: [100, 50]
    style:
      font_size: 24
      color: var(--lcars-orange)

  # Temperature graph
  - type: control
    id: temp_graph
    card:
      type: custom:mini-graph-card
      entities:
        - sensor.temperature
        - sensor.humidity
      hours_to_show: 12
      line_width: 2
      animate: true
    position: [100, 100]
    size: [600, 300]

  # Climate control card
  - type: control
    id: climate_control
    card:
      type: thermostat
      entity: climate.living_room
    position: [750, 100]
    size: [300, 300]

  # Quick buttons
  - type: control
    id: fan_button
    card:
      type: button
      entity: switch.fan
      name: "Fan"
      icon: mdi:fan
      tap_action:
        action: toggle
    position: [1100, 100]
    size: [150, 100]

  - type: control
    id: humidifier_button
    card:
      type: button
      entity: switch.humidifier
      name: "Humidifier"
      icon: mdi:air-humidifier
      tap_action:
        action: toggle
    position: [1100, 220]
    size: [150, 100]

  # Connecting lines
  - type: line
    anchor_to: panel_title
    anchor_side: bottom-center
    attach_to: temp_graph
    attach_side: top-center

  - type: line
    anchor_to: temp_graph
    anchor_side: middle-right
    attach_to: climate_control
    attach_side: middle-left

LCARS-Style Control Panel

yaml

overlays:
  # Section header
  - type: button
    id: header
    text: "SHIP SYSTEMS"
    position: [100, 100]
    size: [300, 80]
    style_preset: lcars-header

  # LCARdS control buttons
  - type: control
    id: warp_control
    card:
      type: custom:lcards-button
      entity: switch.warp_drive
      preset: lozenge
      text:
        label:
          content: "WARP DRIVE"
      tap_action:
        action: toggle
    position: [100, 200]
    size: [200, 180]

  - type: control
    id: shields_control
    card:
      type: custom:lcards-button
      entity: switch.shields
      preset: lozenge
      text:
        label:
          content: "SHIELDS"
      tap_action:
        action: toggle
    position: [320, 200]
    size: [200, 180]

  - type: control
    id: weapons_control
    card:
      type: custom:lcards-button
      entity: switch.weapons
      preset: lozenge
      text:
        label:
          content: "WEAPONS"
      tap_action:
        action: toggle
    position: [540, 200]
    size: [200, 180]

  # Status display
  - type: control
    id: status_entities
    card:
      type: entities
      entities:
        - entity: sensor.warp_speed
          name: "Warp Speed"
        - entity: sensor.shield_strength
          name: "Shield Strength"
        - entity: sensor.weapon_charge
          name: "Weapon Charge"
      title: "System Status"
    position: [100, 400]
    size: [640, 200]

Common Patterns

Pattern 1: Label with Control

yaml

- type: text
  id: label
  text: "BEDROOM LIGHT"
  position: [100, 200]

- type: control
  id: control
  card:
    type: button
    entity: light.bedroom
  position: [300, 200]
  size: [150, 80]

- type: line
  anchor_to: label
  attach_to: control

Pattern 2: Control Grid

yaml

# Title
- type: text
  id: title
  text: "LIGHTING CONTROL"
  position: [100, 50]

# Row 1
- type: control
  id: light_1
  card: { type: button, entity: light.room_1 }
  position: [100, 120]
  size: [150, 80]

- type: control
  id: light_2
  card: { type: button, entity: light.room_2 }
  position: [270, 120]
  size: [150, 80]

- type: control
  id: light_3
  card: { type: button, entity: light.room_3 }
  position: [440, 120]
  size: [150, 80]

# Row 2
- type: control
  id: light_4
  card: { type: button, entity: light.room_4 }
  position: [100, 220]
  size: [150, 80]

- type: control
  id: light_5
  card: { type: button, entity: light.room_5 }
  position: [270, 220]
  size: [150, 80]

- type: control
  id: light_6
  card: { type: button, entity: light.room_6 }
  position: [440, 220]
  size: [150, 80]

Pattern 3: Graph with Status Indicators

yaml

# Main graph
- type: control
  id: main_graph
  card:
    type: custom:mini-graph-card
    entities: [sensor.temperature]
  position: [100, 100]
  size: [600, 300]

# Min indicator
- type: text
  id: min_label
  text: "MIN"
  position: [750, 150]

- type: line
  anchor_to: min_label
  attach_to: main_graph
  attach_side: bottom-left

# Max indicator
- type: text
  id: max_label
  text: "MAX"
  position: [750, 250]

- type: line
  anchor_to: max_label
  attach_to: main_graph
  attach_side: top-left

# Current indicator
- type: text
  id: current_label
  text: "NOW"
  position: [750, 350]

- type: line
  anchor_to: current_label
  attach_to: main_graph
  attach_side: middle-right

Troubleshooting

Common Issues

Issue	Cause	Solution
Card not appearing	Custom card not loaded	Check card is installed in HACS
Card not interactive	HASS context not applied	Check browser console for errors
Wrong position	Coordinates outside viewBox	Use values within 0-1920, 0-1080
Card cut off	Size too small	Increase `size` dimensions
Lines not connecting	Wrong overlay ID	Verify `attach_to` matches control `id`
Card styling issues	Theme conflicts	Check card's theme compatibility

Debug Steps

Check Browser Console
```
Look for: [MsdControlsRenderer] logs
```

Verify Card Loading

javascript

// In browser console
customElements.get('mini-graph-card')  // Should return constructor

Inspect Control Element

javascript

// In browser console
window.lcards.debug.msd.systems.controlsRenderer.controlElements

Check HASS Context

javascript

// In browser console
window.lcards.debug.msd.systems.controlsRenderer.hass

View Attachment Points
- Enable debug mode
- Look for red dots showing attachment points

Best Practices

✅ Do's

✅ Use descriptive IDs (temp_graph not control1)
✅ Group related controls visually
✅ Use consistent sizing for similar controls
✅ Test interactivity after adding controls
✅ Use line connections to show relationships
✅ Choose appropriate card types for your data
✅ Keep control sizes reasonable (not too small)

❌ Don'ts

❌ Don't overlap controls (unless intentional)
❌ Don't make controls too small to interact with
❌ Don't use complex cards for simple tasks
❌ Don't forget to set entity in card config
❌ Don't use identical IDs for different controls
❌ Don't position controls outside viewBox
❌ Don't skip testing tap actions

Performance Tips

Keep control count reasonable (<20 per canvas)
Use simpler cards when possible
Avoid heavy animations in embedded cards
Test on target devices (mobile, tablets)
Monitor memory usage with many controls

Summary

Control overlays provide a powerful way to integrate Home Assistant cards into your MSD canvas. Key points:

Any HA Card Works - Custom or built-in
Precise Positioning - ViewBox coordinate system
Full Interactivity - All actions work normally
Line Connections - 9-point attachment system
Easy Configuration - Familiar card syntax

Start with simple button cards, then progress to graphs, entities, and complex layouts as you become comfortable with positioning and connections.

Related Documentation:

Line Overlay - Connecting overlays with lines
Button Overlay - Native MSD buttons
Text Overlay - Labels and indicators
Architecture: Control System - Technical details

← Back to Overlays | Configuration →

Control Overlay - Embedding Home Assistant Cards ​

Table of Contents ​

Overview ​

What You Can Embed ​

Key Features ​

Quick Start ​

Minimal Example ​

Alternative: Nested Config ​

❌ NOT Supported Patterns ​

❌ Flat/Direct Pattern (WRONG) ​

❌ Legacy card_config Pattern (WRONG) ​

❌ Legacy cardConfig Pattern (WRONG) ​

Basic Configuration ​

Configuration Structure ​

Required Properties ​

Optional Properties ​

Card Types ​

LCARdS Cards ​

Built-in Home Assistant Cards ​

Custom Cards ​

Positioning & Sizing ​

Coordinate System ​

Position Guidelines ​

Sizing Best Practices ​

Line Connections ​

9-Point Attachment System ​

Connecting Lines to Controls ​

Multiple Connections Example ​

Advanced Examples ​

Dashboard Panel with Graph and Controls ​

LCARS-Style Control Panel ​

Common Patterns ​

Pattern 1: Label with Control ​

Pattern 2: Control Grid ​

Pattern 3: Graph with Status Indicators ​

Troubleshooting ​

Common Issues ​

Debug Steps ​

Best Practices ​

✅ Do's ​

❌ Don'ts ​

Performance Tips ​

Summary ​

Control Overlay - Embedding Home Assistant Cards

Table of Contents

Overview

What You Can Embed

Key Features

Quick Start

Minimal Example

Alternative: Nested Config

❌ NOT Supported Patterns

❌ Flat/Direct Pattern (WRONG)

❌ Legacy card_config Pattern (WRONG)

❌ Legacy cardConfig Pattern (WRONG)

Basic Configuration

Configuration Structure

Required Properties

Optional Properties

Card Types

LCARdS Cards

Built-in Home Assistant Cards

Custom Cards

Positioning & Sizing

Coordinate System

Position Guidelines

Sizing Best Practices

Line Connections

9-Point Attachment System

Connecting Lines to Controls

Multiple Connections Example

Advanced Examples

Dashboard Panel with Graph and Controls

LCARS-Style Control Panel

Common Patterns

Pattern 1: Label with Control

Pattern 2: Control Grid

Pattern 3: Graph with Status Indicators

Troubleshooting

Common Issues

Debug Steps

Best Practices

✅ Do's

❌ Don'ts

Performance Tips

Summary