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.

The Home Assistant Plasmoid can send desktop notifications when entity states change, allowing you to stay informed of important events without keeping the widget open.

​
Notification System

Notifications are implemented using KDE’s notification system in Notifications.qml: 
import org.kde.notification

BaseObject {
    Component {
        id: notificationComponent
        Notification {
            componentName: "plasma_workspace"
            eventId: "notification"
            title: plasmoid.title
            iconName: plasmoid.icon
            autoDelete: true
        }
    }

    function createNotification(text) {        
        notificationComponent.createObject(root, { text })?.sendEvent()
    }
}

​
Notification Properties

  • Component: plasma_workspace - Integrates with KDE Plasma notifications
  • Title: Uses the plasmoid’s configured title
  • Icon: Shows the Home Assistant logo
  • Auto-delete: Notifications are automatically removed after display

​
Enabling Notifications

Notifications are configured per entity using the notify field: 
{
  "entity_id": "binary_sensor.front_door",
  "name": "Front Door",
  "icon": "mdi:door",
  "notify": true
}
Set notify: true to enable notifications for an entity’s state changes.

​
Notification Triggers

Notifications are triggered when an entity’s display value changes. From main.qml: 
function updateState(state) {
    for(let id in state) {
        const itemIdx = items.findIndex(i => i.entity_id === id)
        const change = state[id]['+']  // Only changed properties
        const item = itemModel.get(itemIdx)
        const newItem = new Model.Entity(item, change)
        const oldValue = item.value
        itemModel.set(itemIdx, newItem)
        
        // Notification check
        if (items[itemIdx].notify && oldValue !== newItem.value) {
            notifications.createNotification(newItem.name + " " + newItem.value)
        }
    }
}

​
Trigger Conditions

A notification is sent when all of these conditions are met:
  1. The entity has notify: true in its configuration
  2. The entity’s display value has changed
  3. The change comes from a real state update (not initial load)
Notifications are only triggered when the display value changes, not when attributes change. The display value is determined by the entity’s configured attribute or state.

​
Notification Content

Notifications display the entity name and its new value: 
notifications.createNotification(newItem.name + " " + newItem.value)

​
Content Examples

Binary sensor (door): 
Front Door open
Light with brightness: 
Living Room Light 75%
Temperature sensor: 
Outdoor Temperature 23.5 °C
Switch: 
Coffee Maker on
Cover: 
Garage Door closed

​
Configuration Examples

​
Door/Window Sensors

Notify when doors or windows open: 
[
  {
    "entity_id": "binary_sensor.front_door",
    "name": "Front Door",
    "icon": "mdi:door",
    "notify": true
  },
  {
    "entity_id": "binary_sensor.garage_door",
    "name": "Garage Door",
    "icon": "mdi:garage",
    "notify": true
  }
]

​
Motion Sensors

{
  "entity_id": "binary_sensor.hallway_motion",
  "name": "Hallway Motion",
  "icon": "mdi:motion-sensor",
  "notify": true
}

​
Appliance Status

Get notified when appliances finish: 
[
  {
    "entity_id": "sensor.washing_machine",
    "name": "Washing Machine",
    "icon": "mdi:washing-machine",
    "notify": true
  },
  {
    "entity_id": "sensor.dryer",
    "name": "Dryer",
    "icon": "mdi:tumble-dryer",
    "notify": true
  }
]

​
Security Alerts

{
  "entity_id": "binary_sensor.smoke_detector",
  "name": "Smoke Detector",
  "icon": "mdi:smoke-detector",
  "notify": true
}

​
Climate Changes

Monitor significant temperature changes: 
{
  "entity_id": "sensor.freezer_temperature",
  "name": "Freezer",
  "icon": "mdi:fridge",
  "unit": "°C",
  "notify": true
}
For sensors with frequently changing values (like power consumption), notifications can become overwhelming. Use notifications primarily for discrete state changes or significant events.

​
Display Value vs State

Notifications use the display value, which follows this priority:
  1. Custom attribute (if configured)
  2. State with unit
  3. Empty string

​
Example: Displaying Brightness Instead of State

{
  "entity_id": "light.bedroom",
  "name": "Bedroom Light",
  "attribute": "brightness",
  "notify": true
}
This will notify with brightness changes (e.g., “Bedroom Light 200”) rather than on/off state.

​
Example: Default State Notification

{
  "entity_id": "switch.coffee_maker",
  "name": "Coffee Maker",
  "notify": true
}
This will notify with state changes (e.g., “Coffee Maker on” or “Coffee Maker off”).

​
Notification Behavior

​
Initial Load

Notifications are not triggered during the initial state load: 
function initState(state) {
    itemModel.clear()
    items.forEach((i, idx) => {
        const entityData = state[i.entity_id]
        itemModel.insert(idx, new Model.Entity(i, entityData))
    })
    initialized = true
}
The updateState function is only called for subsequent changes, preventing notification spam on startup.

​
Real-Time Updates

Notifications are triggered immediately when Home Assistant sends state updates through the WebSocket connection: 
function processData(event) {
    if (event.a) initState(event.a)      // Initial state, no notifications
    if (event.c) updateState(event.c)    // Changes, trigger notifications
}

​
Duplicate Prevention

The value comparison prevents duplicate notifications: 
if (items[itemIdx].notify && oldValue !== newItem.value) {
    notifications.createNotification(newItem.name + " " + newItem.value)
}
If an entity receives an update but the display value hasn’t changed, no notification is sent.
For entities with binary states (on/off, open/closed), every state transition will trigger a notification. For numeric sensors, notifications only occur when the displayed value changes.

​
System Integration

Notifications appear in the KDE Plasma notification area and:
  • Follow system notification settings
  • Can be dismissed individually
  • Support Do Not Disturb mode
  • Are logged in the notification history
  • Auto-delete after display (don’t persist)

​
Best Practices

  1. Use sparingly: Only enable notifications for important state changes
  2. Descriptive names: Use clear entity names since they appear in notifications
  3. Binary sensors: Ideal for door/window sensors, motion detectors
  4. Discrete states: Better for on/off than continuous numeric values
  5. Security first: Enable for security-related entities (doors, alarms, smoke detectors)
The autoDelete: true property ensures notifications don’t clutter the persistent notification history. They’re displayed momentarily and then removed automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us