Automations

An automation reacts to a trigger by writing parameters on one or more nodes — "when the door sensor opens, turn on the hall light". Automations belong to a group, and ESPRMNeoAutomation represents one. Its conditions are references to triggers that already exist on nodes, so define those first.

Triggers live on nodes and are created separately. See Triggers.

Create an automation

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

createAutomation(input) returns Promise<ESPRMNeoAutomation>. The server mints the ID, so any id you include is stripped before sending.

CreateAutomationInput takes:

Field	Contents
name	Display name, required
conditions	{ and: [triggerId, …] }, required
actions	{ targets: [ActionTarget, …] }, required
status	"enabled" or "disabled", defaults to enabled
retrigger	Whether it may fire again

It throws ESPAPICallValidationError when name, conditions or actions is missing.

conditions.and holds trigger IDs, and the only combinator is and, every referenced trigger must be satisfied. There is no or.

Each ActionTarget is { node, path, value }, where path is a dotted device-and-parameter path such as Light.Power.

Read automations

const automations = await home.getAutomations();
const one = await home.getAutomation("<automation-id>");

getAutomations() returns Promise<ESPRMNeoAutomation[]> and getAutomation(automationId) returns a single Promise<ESPRMNeoAutomation>.

An instance carries id, groupId, name, conditions, actions, status and retrigger. Constructing one requires an ID, a name, conditions and actions; the class throws ESPAPICallValidationError if the cloud returns an automation missing any of them.

Update

await automation.update({ name: "Hall light", status: "disabled" });

update(updates) takes a Partial<CreateAutomationInput> and returns Promise<ESPAPIResponse>. id cannot be changed.

update applies to the instance before the request

Unlike the add and remove helpers below, update() writes the changed fields onto the instance first and then sends the whole automation. If the request fails, the instance is left carrying values the cloud never accepted; re-read it with getAutomation() after a failed update rather than trusting what you hold.

Because the request always sends the full automation, update() is also what the helpers below use internally.

Add and remove conditions

await automation.addCondition("<trigger-id>");
await automation.removeCondition("<trigger-id>");

Both return Promise<ESPAPIResponse> and throw ESPAPICallValidationError when the trigger ID is missing or empty. Each mutates the instance only after the request succeeds, so a failure leaves your object untouched.

Add and remove actions

await automation.addAction({ node: "<node-id>", path: "Light.Brightness", value: 40 });
await automation.removeAction(0);

addAction(target) throws ESPAPICallValidationError when the target is missing a node or a path. Note that value is not validated; an action target with no value is accepted.

removeAction(index) removes by position in actions.targets, and throws when the index is out of range. Read the current array before choosing an index; there is no remove-by-match.

Both mutate the instance only after the request succeeds.

Delete

await automation.delete();

Returns Promise<ESPAPIResponse>. The instance is stale afterwards; discard it.

Method summary

Method	Returns
group.createAutomation(input)	ESPRMNeoAutomation
group.getAutomations()	ESPRMNeoAutomation[]
group.getAutomation(automationId)	ESPRMNeoAutomation
automation.update(updates)	ESPAPIResponse
automation.addCondition(triggerId)	ESPAPIResponse
automation.removeCondition(triggerId)	ESPAPIResponse
automation.addAction(target)	ESPAPIResponse
automation.removeAction(index)	ESPAPIResponse
automation.delete()	ESPAPIResponse

Related

• Triggers — the conditions an automation references
• Schedules — time-based actions instead of event-based
• Groups — the scope automations belong to
• Automations — the platform feature
• Types — CreateAutomationInput and ActionTarget