Events

Events are discrete named occurrences that your plugin emits to signal that something happened — a device changed state, a threshold was crossed, a connection dropped.

What is an event?

An event is a one-shot notification your plugin fires over MQTT. Once the plugin is installed, each declared event becomes available as a trigger in the automation builder — users can build rules like “when plug state changed → set plug state on another device.”

Unlike telemetry, events are not stored as a continuous time-series. They fire once, the automation engine evaluates any matching automations, and the occurrence is not persisted to the event history. If no automation is configured to watch an event, it is silently ignored.

Declaring events in the manifest

Add an events array to your plugin.json. Hiclaro registers all declared events when the plugin is installed — no runtime registration step is needed.

"events": [
  { "key": "plug_state_changed", "label": "Plug State Changed", "hasPayload": true,  "valueType": "string" },
  { "key": "device_offline",     "label": "Device Went Offline", "hasPayload": false }
]

Set hasPayload: true when the event carries a meaningful value (e.g. the new state after a toggle). Set it to false for presence-only events where the occurrence itself is what matters. See the Plugin Manifest reference for the full field list.

Dispatching an event

Publish a JSON message to:

eims/events/<plugin_key>/<event_key>

For events with hasPayload: true, include a value field in the payload. For events without a payload, publish an empty object.

import json
import paho.mqtt.client as mqtt

def publish_event(mqtt_client: mqtt.Client, plugin_key: str, event_key: str, value=None):
    payload = {"value": value} if value is not None else {}
    mqtt_client.publish(f"eims/events/{plugin_key}/{event_key}", json.dumps(payload))

# Dispatch with a string payload
publish_event(mqtt_client, "my-plugin", "plug_state_changed", "on")

# Dispatch without a payload
publish_event(mqtt_client, "my-plugin", "device_offline")

Using the event payload in automations

When an event has a payload, the automation engine makes it available in two places inside the triggered automation:

Conditions — a condition can use event payload as its input and compare it against a fixed value (e.g. “event payload equals on”). This lets you branch: only continue if the state changed to a specific value.

Action value templates — when configuring an action's value in the automation builder, you can reference the payload using the {{ event.payload }} template token. The engine substitutes the raw payload string before dispatching the action.

// Action value template — forward the event payload to another plugin action:
Set plug state → {{ event.payload }}

// The event payload is the raw value field from the MQTT message.
// It is always coerced to a string inside the template engine.

Events vs telemetry

Use telemetry for measurements you want to chart over time — power draw, temperature, battery SOC. Use events for discrete things that happened — a state change, an alarm, a connection drop.

A plug turning on is an event. The power draw of the plug after it turns on is telemetry. You will often publish both: fire the event for the state change so automations can react, and continue publishing telemetry so the dashboard stays current.