---
name: home-assistant
description: Create, update, and manage Home Assistant dashboards (Lovelace) programmatically via WebSocket API. Use when the user asks to create/update HA dashboards, add dashboard views, modify Lovelace configurations, or work with Home Assistant UI components. Supports the modern sections-based dashboard format (HA 2026+) and legacy card-based layouts.
---

# Home Assistant Dashboard Manager

Manage Home Assistant dashboards (Lovelace) programmatically via WebSocket API.

## Quick Start

### Create a Dashboard

```bash
scripts/ha_dashboard.py create \
  "wss://ha.example.com/api/websocket" \
  "YOUR_TOKEN" \
  dashboard-config.yaml \
  "Network Dashboard" \
  "network" \
  "mdi:network"
```

### List Dashboards

```bash
scripts/ha_dashboard.py list \
  "wss://ha.example.com/api/websocket" \
  "YOUR_TOKEN"
```

### Update Dashboard

```bash
scripts/ha_dashboard.py update \
  "wss://ha.example.com/api/websocket" \
  "YOUR_TOKEN" \
  "network" \
  updated-config.yaml
```

### Delete Dashboard

```bash
scripts/ha_dashboard.py delete \
  "wss://ha.example.com/api/websocket" \
  "YOUR_TOKEN" \
  "network"
```

## Workflow

1. **Understand requirements** - What entities, layout, and organization does the dashboard need?

2. **Check available entities** - Query HA REST API to get available sensors, switches, etc.:
   ```bash
   curl -H "Authorization: Bearer TOKEN" \
     https://ha.example.com/api/states | grep entity_id
   ```

3. **Design dashboard structure** - Plan sections and cards based on:
   - Related functionality (e.g., network monitoring, climate control)
   - User priorities (most important info first)
   - Device groupings (e.g., by room, by type)

4. **Create YAML configuration** - Use modern sections format (see references/dashboard-config.md)

5. **Execute with script** - Run `ha_dashboard.py create` with the config

6. **Verify** - Check the dashboard in HA web interface

7. **Iterate** - Update as needed with `ha_dashboard.py update`

## Dashboard Structure (2026+)

Modern HA dashboards use a sections-based layout:

```yaml
views:
  - type: sections
    title: My Dashboard
    path: my-dashboard
    sections:
      - type: grid
        cards:
          - type: heading
            heading: Section Title
          - type: entity
            entity: sensor.example
          - type: gauge
            entity: sensor.cpu
            min: 0
            max: 100
            severity:
              green: 0
              yellow: 60
              red: 80
```

**Key principles:**
- Group related entities in sections
- Use headings to label sections clearly
- Place most important info at the top
- Use appropriate card types (gauge for metrics, entity for status, etc.)

## Common Patterns

### Network Monitoring Dashboard
- System status (CPU, RAM, uptime)
- Interface states (eth ports, WiFi)
- Connected devices
- Traffic graphs
- Internet speed tests

### Home Automation Dashboard
- Climate controls (temperature, humidity)
- Lighting controls
- Security (doors, cameras, alarms)
- Energy monitoring

### Device-Specific Dashboard
- Single device focus (router, server, appliance)
- Detailed metrics
- Configuration controls
- Status indicators

## References

- **Dashboard configuration syntax:** references/dashboard-config.md
- **WebSocket API details:** references/websocket-api.md

Read references when:
- Creating complex card layouts
- Working with conditional visibility
- Using advanced card features
- Troubleshooting WebSocket connection issues

## Script Details

### ha_dashboard.py

Zero-dependency Python script that implements WebSocket client from scratch. Works without installing `websockets` or other external packages.

**Capabilities:**
- Create dashboards with YAML configs
- Update existing dashboards
- List all dashboards
- Delete dashboards
- Handles authentication automatically
- Parses YAML if PyYAML available, falls back to plain text

**Requirements:**
- Python 3.7+ (uses asyncio)
- PyYAML (optional, for YAML parsing)

**WebSocket URL format:**
- `wss://hostname/api/websocket` for HTTPS instances
- `ws://hostname/api/websocket` for HTTP instances (local only)

**Token:** Use a Long-Lived Access Token from HA:
1. Go to Profile → Security → Long-Lived Access Tokens
2. Create token
3. Copy and save securely

## Tips

1. **Test entity IDs first** - Verify entities exist before adding to dashboard
2. **Start simple** - Create basic structure, then add complexity
3. **Use sections wisely** - Group by function, not just device
4. **Mobile-first** - Avoid wide horizontal stacks (3 cards max)
5. **Icon consistency** - Use mdi: icons for visual clarity
6. **Save configs** - Keep YAML files for version control and iteration
7. **Iterate quickly** - Update command is fast, experiment freely

## Limitations

- Only works with storage mode (default HA setup, UI-managed dashboards)
- Script requires network access to HA instance
- WebSocket connection requires valid token
- Large configs (>1MB) may timeout

## Troubleshooting

**Authentication failed:**
- Verify token is valid and not expired
- Check token has proper permissions

**Dashboard not found:**
- Use `list` command to see available dashboards
- Check url_path matches exactly

**Config save fails:**
- Validate YAML syntax
- Check entity IDs exist
- Ensure card types are supported

**WebSocket connection issues:**
- Verify URL format (wss:// vs ws://)
- Check network connectivity
- Ensure HA is running and accessible