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