DOCSEARCHbyAlgolia
Submit Docs

Linus Dashboard for Home Assistant

repository·main·Indexed 41 days ago

https://github.com/thank-you-linus/linus-dashboard

A visual, plug-and-play dashboard for Home Assistant that automatically organizes devices into rooms and functional groups, eliminating the need for manual YAML configuration. It features smart room navigation, device-type views, responsive design, and the ability to embed existing custom dashboards. Version 2.0.0-beta.2 includes activity detection for monitoring room occupancy and presence using existing sensors and media players.

Tokens
32.5K
Snippets
70
Records
150
Agent score
50%

What's inside Linus Dashboard

  1. What is Linus Dashboard?

    main

    Linus Dashboard is a 'Plug n Play' dashboard for Home Assistant that automatically organizes devices into smart sections based on rooms and device types. It is designed to eliminate manual YAML configuration and provide an intuitive interface for all family members.

    Key Capabilities:

    • Smart Room Navigation: Groups lights, sensors, and climate controls by room.
    • Device-Type Views: Allows controlling all devices of a specific type (e.g., all lights, all covers) from a single screen.
    • Responsive Design: Automatically adapts to mobile, tablet, and desktop layouts.
    • Zero YAML: Configuration is handled visually rather than through code editing.
    • Embedded Dashboards: You can embed your existing custom Home Assistant dashboards (like energy monitoring or camera grids) directly into Linus.

  2. Explore the Linus Dashboard Technology Stack

    main

    The project is built using the following technologies:

    Backend (Python)

    • Home Assistant Integration API: Manages config flows and resource registration.
    • Manifest System: Handles integration metadata and dependencies.
    • Static Resource Management: Registers the frontend bundle with cache-busting.

    Frontend (TypeScript)

    • Lit (v3.x): A web components framework used for building the reactive UI.
    • Mushroom Cards: A UI library used to maintain consistent Home Assistant styling.
    • Rspack: A high-performance build tool (5-10x faster than Webpack) used for bundling and hot reloading.
    • TypeScript 5.x: Provides full type safety across the frontend codebase.

  3. What is Activity Detection?

    main

    Activity Detection is a core feature of Linus Dashboard that automatically monitors and displays room occupancy and activity status using existing sensors and media players. It provides real-time tracking of which rooms are occupied and can serve as a foundation for smart automations.

    Feature Tiers

    Standard (Default):

    • Automatic sensor discovery.
    • Displays compatible sensors in each area.
    • Shows current sensor states and last changed time.
    • Provides brightness status (dark/bright based on sun position).

    With Linus Brain (Optional):

    • Advanced activity state calculation (Occupied, Movement, Inactive, Empty).
    • 24-hour activity history graphs.
    • Presence sensor aggregation.
    • Activity duration tracking and time-in-state statistics.

  4. Understand the Linus Dashboard High-Level Architecture

    main

    Linus Dashboard operates as a dual-component system: a Home Assistant integration (Python backend) and a strategy engine (TypeScript frontend).

    1. Backend (Python): Acts as the bridge to Home Assistant, handling configuration flows and registering static frontend resources.
    2. Frontend (TypeScript + Lit): The strategy engine that consumes entity data from Home Assistant via the WebSocket API.
    3. Registry & Strategy: The RegistryManager organizes entity data, which the Strategy Engine then uses to generate a dashboard structure.
    4. UI Layers: The generated dashboard is composed of Views, which contain Cards, which in turn contain interactive Chips.

    This architecture allows for an auto-generated dashboard that requires zero manual configuration of areas or entities, as it reads directly from the Home Assistant state machine.

  5. Understand the automated release workflow

    main

    When you run a create:* script, the system performs the following steps automatically:

    1. Git Check: Verifies that the git working directory is clean.
    2. Changelog Generation: Generates RELEASE_NOTES.md based on your commit history.
    3. User Interaction: Prompts you to edit the generated release notes.
    4. Formatting: Formats the notes for GitHub compatibility.
    5. Validation: Executes smoke tests to ensure stability.
    6. Versioning: Increments the version number following Semantic Versioning (major.minor.patch).
    7. Git Operations: Creates a new git commit and a git tag.
    8. Deployment: Pushes the changes to GitHub.
    9. CI/CD Trigger: Automatically triggers the GitHub Actions workflow.

  6. Configure Chip Styling and Behavior

    main

    Chips in Linus Dashboard use domain-specific icons and colors to provide visual context.

    Icon & Color Mapping

    Icons and colors are mapped to domains (e.g., light, climate, fan). For example, the light domain uses mdi:lightbulb and the amber color.

    State-Based Coloring

    Chips can change color based on the state of the entities they represent. A common pattern is to show the domain's default color if any entity is in an activeState, and grey if all entities are inactive.

    Content Display (Entity Counts)

    By default, chips show only an icon. To display the number of entities controlled by the chip (e.g., for global badges), set show_content: true in the AggregateChip configuration.

    // Example: AggregateChip configuration for a global badge with count
const aggregateChip = new AggregateChip({
  domain: this.domain,
  area_slug: "global",
  translationKey: "cover",
  activeStates: ["open", "opening"],
  features: [],
  show_content: true, // Enables the entity count display
});

  7. Chip Ordering in AreaView and HomeAreaCard

    main

    Linus Dashboard enforces specific ordering for chips (badges) to ensure the most important contextual information is seen first.

    AreaView Badge Order

    1. Activity Detection / Area State (Position 0): Shows ActivityDetectionChip if Linus Brain is configured, otherwise AreaStateChip.
    2. Area-Specific Chips (Position 1+): Custom chips from AREA_EXPOSED_CHIPS (e.g., Climate, Light, Fan).
    3. Unavailable Chip: Shows count of unavailable entities (only if they exist).
    4. LinusBrain Configuration Chip: Cyan icon (mdi:brain) that opens LinusBrainAreaPopup.
    5. Magic Areas Configuration Chip: Amber icon (mdi:magic-staff) for Magic Areas device configuration.

    HomeAreaCard Badge Order

    1. Activity Detection / Area State
    2. Health Aggregate
    3. Window Aggregate
    4. Door Aggregate
    5. Cover Aggregate
    6. Climate Chip
    7. Fan Chip
    8. Light Chips (conditional ON/OFF)
    9. Light Control Switch

  8. How Discord Release Notifications Work

    main

    The project uses GitHub Actions workflows and a notification script to route release information to Discord based on the release type.

    Beta Releases (Pre-releases)

    • Trigger: Triggered by .github/workflows/prerelease.yml.
    • Command: bash scripts/notify-discord.sh prerelease "<version>" "<release_url>".
    • Webhook Used: DISCORD_WEBHOOK_URL.
    • Template: .github/templates/discord-prerelease.md.
    • Message Format: 🚨 **Beta Release <version>** 🚨.

    Stable Releases

    • Trigger: Triggered by .github/workflows/release.yml.
    • Command: bash scripts/notify-discord.sh release "<version>" "<release_url>".
    • Webhook Used: DISCORD_WEBHOOK_STABLE_URL.
    • Template: .github/templates/discord-release.md.
    • Message Format: 🎉 **New Stable Release | Nouvelle Version Stable** 🎉.

    Note: If DISCORD_WEBHOOK_STABLE_URL is not configured, the system will fallback to using DISCORD_WEBHOOK_URL, which may result in stable releases being posted to the beta channel.

    # Example Beta Release call
bash scripts/notify-discord.sh prerelease "1.4.1-beta.3" "https://github.com/.../releases/tag/1.4.1-beta.3"

# Example Stable Release call
bash scripts/notify-discord.sh release "1.4.1" "https://github.com/.../releases/tag/1.4.1"

  9. Understand the difference between Linus Dashboard and Linus Brain

    main

    Linus Dashboard and Linus Brain are distinct components:

    • Linus Dashboard: A standalone component that provides organized smart home visualization and management.
    • Linus Brain: An optional upgrade that provides advanced AI-driven activity detection and automation capabilities.

  10. Chip display rules and domain restrictions

    main

    The dashboard follows specific rules regarding which domains are allowed to display control chips to prevent UI clutter.

    Allowed Domains

    The following domains always support chips:

    • light, climate, cover, fan, switch, media_player

    Restricted Domains

    The following domains never show chips because they have too many device_class variants, which would overwhelm the UI:

    • sensor (57 device classes)
    • binary_sensor (24 device classes)

    Automatic Disabling Scenarios

    Chips are automatically disabled if:

    1. The domain is sensor or binary_sensor.
    2. The area is UNDISCLOSED (hidden entities).
    3. The domain is explicitly configured to hide controls (e.g., camera or scene in configurationDefaults.ts).

  11. Chip display locations in the UI

    main

    Chips are rendered in three primary locations depending on their scope:

    • View Badges: Found at the top-right of views. This area contains Global control chips and a centered Refresh chip.
    • Floor Title Cards: Found in section headers. These contain Floor-level control chips that act on all entities of a domain on that floor.
    • Area Title Cards: Found in subsection headers. These contain Area-level control chips that act on all entities of a domain in that specific area.

  12. Understand the Chip System architecture

    main

    The Chip System provides compact, interactive controls that appear next to titles throughout the Linus Dashboard. These 'Chips' are small buttons with icons, colors, and optional content (like entity counts) that allow users to control groups of entities (e.g., turning on all lights in a specific room) without navigating to detailed views.

    Chip Types

    • Control Chips: Domain-specific buttons used to control groups of entities (e.g., lights, covers, fans).
    • Aggregate Chips: Specialized chips that aggregate multiple entities and display their counts.
    • Global Chips: Control all entities of a specific domain across the entire home.
    • Floor Chips: Control all entities of a domain on a specific floor.
    • Area Chips: Control all entities of a domain within a specific area.