Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/korapp/plasma-homeassistant/llms.txt

Use this file to discover all available pages before exploring further.

Before you can use the Home Assistant Plasmoid, you need to configure the connection to your Home Assistant instance. This involves setting up the Home Assistant URL and creating a Long-Lived Access Token for authentication.

​
Configuration Interface

The connection settings are found in the API section of the plasmoid configuration dialog (ConfigGeneral.qml:33-76).
1
Step 1: Enter Home Assistant URL
2
The Home Assistant URL field is an editable combo box that stores your Home Assistant instance URL.
3
  • The URL must include the protocol (http:// or https://) and port number
  • Trailing slashes and extra whitespace are automatically removed
  • Previously used URLs are available in the dropdown for quick selection
    • 4
    Valid URL formats:
    5
    http://homeassistant.local:8123
https://example.duckdns.org
http://192.168.1.100:8123
    6
    Make sure the URL includes the protocol and port. For example:
    • http://homeassistant.local:8123
    • https://example.duckdns.org
    7
    Step 2: Create Long-Lived Access Token
    8
    You need to generate a Long-Lived Access Token from your Home Assistant profile page.
    9
  • Navigate to your Home Assistant profile security page:
    • Click the link that appears below the Token field (e.g., http://homeassistant.local:8123/profile/security)
    • Or manually go to your Home Assistant instance and navigate to Profile → Security
  • Scroll to the Long-Lived Access Tokens section
  • Click Create Token
  • Give your token a descriptive name (e.g., “KDE Plasma Widget”)
  • Copy the generated token
    • 10
    The configuration dialog provides a direct link to your Home Assistant security page (ConfigGeneral.qml:73-76). The link appears once you’ve entered a valid URL.
    11
    Step 3: Enter Access Token
    12
    Paste the Long-Lived Access Token into the Token field in the configuration dialog.

    ​
    KDE Wallet Integration

    The plasmoid uses KDE Wallet to securely store your access token (ConfigGeneral.qml:15-31). This provides several security benefits:
    • Tokens are encrypted and stored separately from the plasmoid configuration
    • Multiple Home Assistant instances can be managed with different tokens
    • Tokens persist across plasmoid updates and configuration changes
    KDE Wallet must be active for the plasmoid to function. The wallet integration automatically:
    • Saves tokens when you apply the configuration (ConfigGeneral.qml:90)
    • Retrieves tokens when switching between different URLs
    • Lists previously configured URLs in the dropdown

    ​
    Token Management

    When you change the Home Assistant URL:
    • The plasmoid automatically attempts to retrieve the associated token from KDE Wallet
    • If no token is found, the Token field is cleared
    • Each URL has its own token stored securely
    This allows you to manage multiple Home Assistant instances without re-entering credentials.

    ​
    Additional Settings

    ​
    Flat Entities Display

    The Look section (ConfigGeneral.qml:78-86) includes a Flat entities checkbox:
    • Checked: Entities are displayed in a flat list layout
    • Unchecked: Entities may be displayed with visual hierarchy or grouping
    This setting affects how entities appear in the plasmoid widget on your desktop or panel.

    ​
    Validation

    The configuration form performs automatic validation:
    • URL normalization: Removes trailing slashes and whitespace (ConfigGeneral.qml:53)
    • Auto-save: Changes are saved when the field loses focus or Enter is pressed
    • Token persistence: Tokens are only saved to KDE Wallet when you click Apply
    After configuring your connection, proceed to Adding Entities to start monitoring your Home Assistant devices.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us