Skip to main content
The Home Assistant Plasmoid is built using Qt Quick (QML) and follows a modular component architecture. This page provides an overview of the major components and how they work together.

​
Component Hierarchy

The plasmoid follows a typical Plasma widget structure with these main layers: 
main.qml (PlasmoidItem)
├── CompactRepresentation.qml (system tray/panel view)
├── FullRepresentation.qml (expanded view)
│   └── EntityDelegateTile.qml (entity tiles)
├── Client.qml (WebSocket client)
├── ClientFactory.qml (singleton for client management)
└── Configuration Pages
    ├── ConfigGeneral.qml
    ├── ConfigItems.qml
    └── ConfigItem.qml

​
Core Components

​
Main Plasmoid (main.qml)

The root component that orchestrates all functionality:
  • Type: PlasmoidItem
  • Location: package/contents/ui/main.qml
  • Responsibilities:
    • Manages client connection lifecycle
    • Subscribes to entity state updates
    • Maintains entity data model (itemModel)
    • Handles notifications for entity changes
    • Provides context menu actions
Key Properties:
  • url: Home Assistant server URL from configuration
  • items: Array of configured entities (from plasmoid.configuration.items)
  • itemModel: ListModel containing live entity data
  • ha: Client instance from ClientFactory
  • initialized: Boolean indicating if initial data has loaded

​
Client Factory (ClientFactory.qml)

  • Type: Singleton QML object
  • Location: package/contents/ui/ClientFactory.qml
  • Purpose: Creates and manages shared Client instances
  • Key Features:
    • Reuses client instances across consumers with the same URL
    • Integrates with KDE Wallet via Secrets component
    • Handles component lifecycle and cleanup
    • Reports client creation errors
Main Method: 
function getClient(consumer, baseUrl)

​
WebSocket Client (Client.qml)

  • Type: BaseObject wrapping QtWebSockets.WebSocket
  • Location: package/contents/ui/Client.qml
  • Purpose: Handles Home Assistant WebSocket API communication
  • Features:
    • Automatic authentication with token
    • Ping/pong keepalive mechanism (30s interval)
    • Automatic reconnection on timeout
    • Promise-based async API
    • Entity subscription management
See the Client API documentation for detailed usage.

​
Representation Components

​
Compact Representation (CompactRepresentation.qml)

  • Location: package/contents/ui/CompactRepresentation.qml
  • Purpose: Shows plasmoid icon in system tray or panel
  • Behavior: Toggles expanded view on click
  • Display: Home Assistant MDI icon

​
Full Representation (FullRepresentation.qml)

  • Location: package/contents/ui/FullRepresentation.qml
  • Purpose: Displays entity grid in expanded popup or desktop widget
  • Layout: Dynamic grid that adapts to available width
  • Features:
    • Responsive column count based on width
    • Minimum item width: Kirigami.Units.iconSizes.enormous
    • Shows status indicator for errors
    • Displays placeholder when not configured
    • Shows configuration button when required
Grid Configuration: 
cellWidth: dynamicCellWidth
cellHeight: minItemWidth / 2
delegate: Entity { contentItem: EntityDelegateTile {} }

​
Entity Delegate Tile (EntityDelegateTile.qml)

  • Location: package/contents/ui/EntityDelegateTile.qml
  • Purpose: Renders individual entity display
  • Layout: 2-column grid with icon and text
  • Display Logic:
    • Icon: Uses entity icon or MDI icon
    • Top-right: Entity value (if available)
    • Bottom-right: Entity name
    • Bold value text when entity has data
See UI Components for detailed documentation.

​
Data Model Components

​
Entity Model (model.mjs)

  • Location: package/contents/code/model.mjs
  • Type: JavaScript ES Module
  • Exports:
    • Entity: Runtime entity data with state
    • ConfigEntity: Configuration entity with actions
    • getDisplayValue: Value formatting function
See Entity Model for complete API reference.

​
Configuration Components

​
General Configuration (ConfigGeneral.qml)

  • Purpose: Configure Home Assistant connection
  • Settings:
    • Server URL (with autocomplete from saved servers)
    • Access token (stored in KDE Wallet)
    • Flat entities display option
  • Integration: Uses Secrets component for secure token storage

​
Items Configuration (ConfigItems.qml)

  • Purpose: Manage displayed entities
  • Features:
    • Add/edit/delete entities
    • Reorder with drag handles
    • Import/export entity configuration
    • Auto-backup to file
    • Live entity data from Home Assistant

​
Item Configuration (ConfigItem.qml)

  • Purpose: Edit individual entity settings
  • Fields:
    • Entity ID (with autocomplete)
    • Display attribute selector
    • Custom name and icon
    • Notification on change
    • Click action (service call)
    • Scroll action (for number fields)
See UI Components for detailed documentation.

​
Component Communication Flow

​
Initialization Flow

  1. main.qml loads and reads configuration
  2. ClientFactory.getClient() creates or retrieves Client instance
  3. Client connects WebSocket to Home Assistant
  4. Client authenticates with token from Secrets
  5. main.qml subscribes to configured entities
  6. Initial entity states populate itemModel
  7. FullRepresentation displays entity grid

​
State Update Flow

  1. Home Assistant sends state change event
  2. Client receives WebSocket message
  3. Client calls subscription callback with event data
  4. main.qml.processData() updates itemModel
  5. Entity model creates new Entity instance
  6. UI automatically updates via model binding
  7. Notification shown if entity has notify enabled

​
Service Call Flow

  1. User interacts with entity tile (click/scroll)
  2. Entity component calls root.ha.callService()
  3. Client sends WebSocket command with promise
  4. Home Assistant executes service
  5. Client receives result and resolves promise
  6. State update follows normal update flow

​
Helper Components

The components/ directory contains reusable utilities:
  • BaseObject: Base QML object with common properties
  • DynamicIcon: Renders MDI or Plasma icons
  • MdiIcon: Material Design Icons renderer
  • Notifications: KDE notification integration
  • Secrets: KDE Wallet integration for token storage
  • StatusIndicator: Error indicator overlay
  • File: File dialog wrapper
  • Autocompletion: TextField autocomplete popup

​
Threading and Async Operations

The plasmoid uses JavaScript Promises for asynchronous operations:
  • WebSocket commands: All API calls return promises
  • Token retrieval: Secrets component uses promises
  • Service calls: callService(), getServices(), getStates() are async
Promises are managed internally by the Client component using a Map of promise resolvers.

​
Error Handling

Error handling occurs at multiple levels:
  1. Client Component: Emits error signal with message string
  2. Main Plasmoid: Sets errorString property
  3. UI: StatusIndicator shows error overlay
  4. Configuration: InlineMessage displays connection errors
  5. ClientFactory: Reports QML component creation errors

​
Performance Considerations

  • Shared Clients: ClientFactory ensures one client per URL
  • Lazy Loading: FullRepresentation grid loads only when initialized
  • Efficient Updates: Only changed entities update model
  • Filtered Subscriptions: Only configured entities are subscribed
  • Keepalive: 30-second ping/pong prevents unnecessary reconnections

​
Next Steps