Triggers

A trigger watches a value on a node and fires when a comparison becomes true — "when Light.Power equals true". A trigger on its own does nothing; it is the condition an automation references to decide when to act. Create triggers first, then reference their IDs from an automation.

Triggers live on nodes and follow the same replace-all pattern as schedules.

Create a trigger

const trigger = await node.createTrigger({
  id: "door-opened",
  type: "param",
  path: "Door.Open",
  operator: "eq",
  value: true,
  enabled: true,
});

createTrigger() is overloaded exactly like createSchedule():

Argument	Behaviour	Returns
One TriggerItem	Appends, preserving existing	ESPRMNeoTrigger
TriggerItem[]	Replaces all in one request	ESPRMNeoTrigger[]
[]	Clears every trigger	ESPRMNeoTrigger[]

A single item requires an id and throws ESPAPICallValidationError when it is missing or already used on this node.

Appending is two round trips and is not safe under concurrency; two simultaneous appends read the same list and the later request wins. Build the array locally when adding several.

Trigger fields

Field	Contents
id	Unique within the node's trigger list
type	Source category, "param" for a parameter
path	Dotted path, such as Light.Power
operator	Comparison to apply
value	Right-hand side of the comparison
enabled	Whether armed; defaults to true server-side

Operators have exactly six spellings

operator must be one of eq, ne, gt, lt, ge or le. The cloud stores triggers verbatim, so a spelling like "==" reaches the device unchanged and makes the firmware reject the node's entire trigger list, not just the bad entry. TypeScript catches this if you type the object as TriggerItem; a plain object literal will not be checked.

Read triggers

const triggers = await node.getTriggers();

Returns Promise<ESPRMNeoTrigger[]>. Each instance carries id, nodeId, groupId, type, path, operator, value and enabled.

Two helpers on the instance: getNode() returns the parent node if its weak reference is still alive, and toTriggerItem() converts the instance back to a plain TriggerItem for building a payload by hand.

Update, enable, delete

await trigger.update({ value: false });
await trigger.enable(false);
await trigger.delete();

All three return Promise<ESPAPIResponse> and send a full trigger-list request underneath.

update(updates) takes a Partial<TriggerItem> and mutates the instance only after the request succeeds; if the request fails, your object still matches the cloud.

Each throws ESPAPICallValidationError when the node or the trigger can no longer be resolved.

Remove by ID

await node.removeTrigger("door-opened");
await node.removeAllTriggers();

removeTrigger(triggerId) fetches, filters and sends the remainder, throwing when nothing matches. removeAllTriggers() clears them in a single request.

Removing a trigger does not update automations that reference it. Clean up the automation's conditions yourself. See Automations.

Using a trigger in an automation

const automation = await home.createAutomation({
  name: "Hall light on door open",
  conditions: { and: [trigger.id] },
  actions: {
    targets: [{ node: node.nodeId, path: "Light.Power", value: true }],
  },
});

Triggers are per-node; automations are per-group. An automation may reference triggers from several nodes in its group, and its conditions.and requires all of them.

Method summary

Method	Returns
node.createTrigger(trigger | triggers)	ESPRMNeoTrigger or array
node.getTriggers()	ESPRMNeoTrigger[]
node.removeTrigger(triggerId)	ESPAPIResponse
node.removeAllTriggers()	ESPAPIResponse
trigger.update(updates)	ESPAPIResponse
trigger.enable(enabled)	ESPAPIResponse
trigger.delete()	ESPAPIResponse
trigger.toTriggerItem()	TriggerItem

Related

• Automations — what consumes trigger IDs
• Schedules — time-based instead of condition-based
• Device control — the parameters a trigger watches
• Types — TriggerItem and TriggerOperator
• Schedules and automations — the firmware side