name: ha-dashboard-create description: | Creates and updates Home Assistant Lovelace dashboards programmatically via WebSocket API with dashboard structure, view configuration, and entity validation. Use when asked to "create HA dashboard", "automate dashboard creation", "WebSocket dashboard API", "programmatic Lovelace", or "validate dashboard entities".

Works with Python websocket-client, WebSocket API authentication, and Lovelace configuration.

Home Assistant Dashboard Creation

Create and update Lovelace dashboards programmatically using the WebSocket API.

CRITICAL: Dashboard URL Path Requirements

Home Assistant requires dashboard URL paths to contain a hyphen:

• ✅ CORRECT: "climate-control", "mobile-app", "energy-monitor"
• ❌ WRONG: "climate", "mobile", "energy"

Rule: Always use kebab-case with at least one hyphen in the url_path field.

When to Use This Skill

Use this skill when you need to:

• Create Home Assistant dashboards programmatically via WebSocket API
• Automate dashboard creation and updates for multiple environments
• Build dashboard generators for dynamic card configurations
• Validate dashboard entities before deployment
• Manage dashboards as code with version control
• Programmatically update existing dashboard configurations

Do NOT use when:

• You can use the Home Assistant UI dashboard editor (simpler for manual changes)
• Building simple static dashboards (UI editor is more intuitive)
• You haven't created a long-lived access token for API authentication

Usage

1. Connect to WebSocket: Authenticate with long-lived access token
2. Check if exists: Query existing dashboards with lovelace/dashboards/list
3. Create dashboard: Use lovelace/dashboards/create with url_path containing hyphen
4. Save configuration: Update config with lovelace/config/save
5. Verify: Check HA UI and system logs for errors

Quick Start

import json
import websocket

HA_URL = "http://192.168.68.123:8123"
HA_TOKEN = os.environ["HA_LONG_LIVED_TOKEN"]

def create_dashboard(url_path: str, title: str, config: dict):
    """Create or update a dashboard.

    Args:
        url_path: Dashboard URL path (must contain hyphen, e.g., "climate-control")
        title: Dashboard display title
        config: Dashboard configuration dict
    """
    # Validate url_path contains hyphen
    if "-" not in url_path:
        raise ValueError(f"url_path must contain hyphen: '{url_path}' -> '{url_path}-view'")

    ws_url = HA_URL.replace("http://", "ws://") + "/api/websocket"
    ws = websocket.create_connection(ws_url)
    msg_id = 1

    # 1. Receive auth_required
    ws.recv()

    # 2. Send auth
    ws.send(json.dumps({"type": "auth", "access_token": HA_TOKEN}))
    ws.recv()  # auth_ok

    # 3. Check if dashboard exists
    ws.send(json.dumps({"id": msg_id, "type": "lovelace/dashboards/list"}))
    msg_id += 1
    response = json.loads(ws.recv())
    exists = any(d["url_path"] == url_path for d in response.get("result", []))

    # 4. Create if doesn't exist
    if not exists:
        ws.send(json.dumps({
            "id": msg_id,
            "type": "lovelace/dashboards/create",
            "url_path": url_path,  # Must contain hyphen!
            "title": title,
            "icon": "mdi:view-dashboard",
            "show_in_sidebar": True,
        }))
        msg_id += 1
        ws.recv()

    # 5. Save configuration
    ws.send(json.dumps({
        "id": msg_id,
        "type": "lovelace/config/save",
        "url_path": url_path,
        "config": config,
    }))
    ws.recv()
    ws.close()

WebSocket Message Types

See references/card-types.md for dashboard configuration structure and common card types.

Error Checking

Validate Dashboard Configuration

# 1. Check system logs for lovelace errors
ws.send(json.dumps({"id": 1, "type": "system_log/list"}))
logs = json.loads(ws.recv())
# Filter for 'lovelace' or 'frontend' errors

# 2. Validate dashboard configuration
ws.send(json.dumps({
    "id": 2,
    "type": "lovelace/config",
    "url_path": "climate-control"  # Must contain hyphen
}))
config = json.loads(ws.recv())

# 3. Validate entity IDs exist
ws.send(json.dumps({"id": 3, "type": "get_states"}))
states = json.loads(ws.recv())
entity_ids = [s["entity_id"] for s in states["result"]]

# 4. Check if entities used in dashboard exist
for card in dashboard_config["views"][0]["cards"]:
    if "entity" in card:
        if card["entity"] not in entity_ids:
            print(f"Warning: Entity {card['entity']} not found")

Common Error Patterns

1. URL path missing hyphen: "url_path": "climate" → Add hyphen: "climate-control"
2. Entity doesn't exist: Check entity ID in Developer Tools → States
3. Custom card not installed: Install via HACS first
4. JavaScript errors: Check browser console (F12) for configuration errors

Entity Validation

Verify entity IDs exist before using them in dashboards.

See references/entity-patterns.md for entity validation functions and common entity patterns.

Supporting Files

• scripts/create_dashboard.py - Complete working example with entity validation
• references/card-types.md - Dashboard configuration structure and card types
• references/entity-patterns.md - Entity validation and common patterns

Workflow

1. Design dashboard - Plan views and card layout
2. Validate entities - Check all entity IDs exist
3. Connect to WebSocket - Authenticate with HA
4. Check if exists - Query existing dashboards
5. Create dashboard - Create if new (ensure url_path has hyphen!)
6. Save configuration - Update dashboard config
7. Verify - Check in HA UI and system logs for errors

URL Path Examples

Troubleshooting

Dashboard not appearing in sidebar

1. Check show_in_sidebar: True in dashboard creation
2. Verify url_path contains hyphen
3. Refresh browser (Ctrl+Shift+R)
4. Check HA logs for errors

Configuration not saving

1. Verify WebSocket authentication succeeded
2. Check url_path matches existing dashboard
3. Validate JSON structure (no syntax errors)
4. Check system logs via system_log/list

Entity not found errors

1. Get all entities: {"type": "get_states"}
2. Compare with entities used in dashboard
3. Fix entity IDs or remove missing entities
4. Ensure entity has proper state_class for sensors

Official Documentation

• Lovelace Dashboards - Home Assistant
• WebSocket API - Home Assistant