Skip to main content

Schedules

A schedule writes parameters on a node at a time you choose — "turn the porch light on at 18:30 on weekdays". Schedules live on a node, ESPRMNeoSchedule represents one, and a group-level helper creates them across several nodes at once.

The underlying API is replace-all, which shapes every method on this page.

Create a schedule​

const schedule = await node.createSchedule({
  id: "porch-evening",
  name: "Porch light",
  enabled: true,
  triggers: [{ m: 1110, d: 62 }],
  action: { Light: { Power: true } },
});

createSchedule() is overloaded:

ArgumentBehaviourReturns
One ScheduleItemAppends, preserving existingESPRMNeoSchedule
ScheduleItem[]Replaces all in one requestESPRMNeoSchedule[]
[]Clears every scheduleESPRMNeoSchedule[]

Passing a single item requires an id, and throws ESPAPICallValidationError when it is missing or already used on this node. Passing an array does not; the array is sent as given.

Schedule sA is gone. B read the list before A wrote it, so B's PUT overwrote A's addition.

Single-item append is two round trips and is not concurrency-safe

Appending fetches the current list, merges, and sends the whole set back, as above. Two appends running at once both read the same list, and the later request wins; silently dropping the other. When adding several schedules, build the full array yourself and pass it once.

Trigger fields​

ScheduleTrigger is compact, matching what firmware expects:

FieldMeaning
mMinutes since midnight
dDay-of-week bitmask
ddDay of month
mmMonth bitmask
yyYear
rsecRelative seconds from now

action is a { deviceName: { paramId: value } } map; the same shape as a parameter write. validity optionally bounds the schedule with start and end.

Read schedules​

const schedules = await node.getSchedules();

Returns Promise<ESPRMNeoSchedule[]>. Each instance carries id, name, nodeId, groupId, enabled, triggers, action and validity, and can resolve its own node with await schedule.getNode().

Update, enable, delete​

await schedule.update({ name: "Porch", action: { Light: { Power: false } } });
await schedule.enable(false);
await schedule.delete();

All three return Promise<ESPAPIResponse> and all three send a full replace-all request underneath.

update(updates) takes a Partial<ScheduleItem> and commits to the instance only after the request succeeds; a failed update leaves your object matching the cloud. enable(enabled) is the same operation for the enabled flag alone.

Each throws ESPAPICallValidationError when the schedule's node cannot be resolved, or when no schedule with this ID exists on the node any more.

Remove by ID​

await node.removeSchedule("porch-evening");
await node.removeAllSchedules();

removeSchedule(scheduleId) fetches the list, filters, and sends the remainder; two round trips, with the same concurrency caveat as appending. It throws when no schedule matches.

removeAllSchedules() clears every schedule in a single request.

Group-wide schedules​

const created = await home.createSchedule([
  { nodeId: "<node-a>", schedules: [scheduleA] },
  { nodeId: "<node-b>", schedules: [scheduleB] },
]);

await home.getSchedules();
await home.deleteAllSchedules();

The group-level createSchedule(nodeSchedules) takes an array of { nodeId, schedules } and returns Promise<ESPRMNeoSchedule[]> across all nodes. It is a replace-all per node, not an append, and it throws when a listed node is not in the group.

group.getSchedules() aggregates every node's schedules; group.deleteAllSchedules() clears them all. Both work node by node underneath, so cost grows with group size.

Method summary​

MethodReturns
node.createSchedule(schedule | schedules)ESPRMNeoSchedule or array
node.getSchedules()ESPRMNeoSchedule[]
node.removeSchedule(scheduleId)ESPAPIResponse
node.removeAllSchedules()ESPAPIResponse
schedule.update(updates)ESPAPIResponse
schedule.enable(enabled)ESPAPIResponse
schedule.delete()ESPAPIResponse
group.createSchedule(nodeSchedules)ESPRMNeoSchedule[]
group.getSchedules()ESPRMNeoSchedule[]
group.deleteAllSchedules()ESPAPIResponse