Service Calls

Configure and execute Home Assistant service calls through entity interactions

The Home Assistant Plasmoid allows you to call Home Assistant services directly from entity interactions. Services are actions like turning on lights, adjusting thermostats, or triggering automations.

Service Call Configuration

Each entity can have two types of service actions:

• default_action: Triggered when you click an entity
• scroll_action: Triggered when you scroll on an active entity

Configuration Structure

Actions are configured in the entity settings with the following fields:

{
    domain: "light",              // Service domain
    service: "turn_on",           // Service name
    target: {                     // Service target
        entity_id: "light.bedroom"
    },
    data_field: "brightness"      // Optional: field for scroll actions
}

The domain and target.entity_id are automatically inferred from the entity’s entity_id if not specified.

Action Validation

The plasmoid validates and normalizes action configurations:

function addActionProperty(o, name) {
    Object.defineProperty(o, name, {
        enumerable: true,
        get: function() { return o[Symbol.for(name)] },
        set: function(action) {
            o[Symbol.for(name)] = !action?.service ? null : { 
                service: action.service,
                domain: action.domain || o.domain,
                target: action.target || { entity_id: o.entity_id },
                data_field: action.data_field
            }
        }
    })
}

Validation Rules:

• Actions without a service are set to null (disabled)
• Missing domain defaults to the entity’s domain
• Missing target defaults to the entity itself

Domain Compatibility Check

When an entity’s ID changes, actions are validated to ensure domain compatibility:

function updateAction(o, name) {
    if (!o[name]) return
    if (o.domain !== o[name].domain) return o[name] = null
    o[name].target.entity_id = o.entity_id    
}

If an action’s domain doesn’t match the entity’s domain, the action is automatically disabled.

Default Actions (Click)

Default actions are executed when you click an entity tile.

Implementation

From Entity.qml:

Loader {
    active: !!default_action
    sourceComponent: Component {
        Connections {
            readonly property string tip: `Click to ${format(default_action.service)}`
            target: control
            function onClicked() {
                ha.callService(default_action)
            }
        }
    }
}

Example Configurations

Toggle Light

{
  "entity_id": "light.living_room",
  "name": "Living Room",
  "icon": "mdi:lightbulb",
  "default_action": {
    "service": "toggle"
  }
}

This calls light.toggle on light.living_room when clicked.

Turn On with Brightness

{
  "entity_id": "light.bedroom",
  "name": "Bedroom Light",
  "default_action": {
    "service": "turn_on",
    "domain": "light"
  }
}

Activate Scene

{
  "entity_id": "scene.movie_time",
  "name": "Movie Mode",
  "icon": "mdi:movie",
  "default_action": {
    "service": "turn_on"
  }
}

Control Cover

{
  "entity_id": "cover.garage_door",
  "name": "Garage Door",
  "default_action": {
    "service": "toggle"
  }
}

The callService Method

Service calls are executed through the WebSocket client in Client.qml:

function callService({ domain, service, target } = {}, data) {
    return commandAsync({
        "type": "call_service",
        "domain": domain,
        "service": service,
        "service_data": data,
        "target": target
    })
}

Method Signature

Parameters:

• action (Object): Action configuration
  • domain (String): Service domain (e.g., “light”)
  • service (String): Service name (e.g., “turn_on”)
  • target (Object): Target entities
    • entity_id (String): Target entity ID
• data (Object): Optional service data (used by scroll actions)

Returns: Promise that resolves when the service call completes

WebSocket Message Format

The service call is sent to Home Assistant as:

{
  "id": 42,
  "type": "call_service",
  "domain": "light",
  "service": "turn_on",
  "service_data": {
    "brightness": 200
  },
  "target": {
    "entity_id": "light.bedroom"
  }
}

Service Discovery

The plasmoid fetches available services and their field definitions on startup:

function fetchFieldsInfo() {
    if (!items.length) return
    ha.getServices().then(s => {
        fields = items.reduce((a, i) => {
            if (i.scroll_action) {
                const field = i.scroll_action.data_field
                const key = i.scroll_action.domain + i.scroll_action.service + field
                const serviceFields = s[i.scroll_action.domain][i.scroll_action.service].fields
                a[key] = (serviceFields[field] || serviceFields.advanced_fields.fields[field])?.selector
            }
            return a
        },{})
    })
}

This information is used to:

• Validate scroll action data fields
• Determine min/max values for numeric fields
• Configure appropriate selectors

UI Feedback

Entities display tooltips showing available actions:

PlasmaComponents3.ToolTip {
    visible: control.hovered && text
    text: actions.map(c => c.item.tip).join("\n")
}

Example tooltip:

Click to toggle
Scroll to adjust brightness

Action Availability

Entities are only clickable if they have configured actions:

PlasmaComponents3.Button {
    enabled: !!actions.length
    readonly property var actions: actionLoaders.filter(c => c.item)
}

Use descriptive service names like “toggle” or “turn_on” as they appear in tooltips with underscores converted to spaces (e.g., “turn_on” → “Click to turn on”).

Common Service Examples

Lights

{
  "default_action": {
    "service": "toggle"
  }
}

Switches

{
  "default_action": {
    "service": "turn_on"
  }
}

Media Players

{
  "default_action": {
    "service": "media_play_pause"
  }
}

Climate

{
  "default_action": {
    "service": "set_temperature",
    "domain": "climate"
  }
}

Scripts and Automations

{
  "entity_id": "script.morning_routine",
  "name": "Morning Routine",
  "default_action": {
    "service": "turn_on"
  }
}

For scripts, scenes, and automations, use the turn_on service to activate them.