Scheduling

What This Page Covers

This page explains how the thermostat manages time-based setpoint changes. It covers program modes, schedule objects, hold overrides and the interaction between scheduled automation and manual user control.

Program Modes

The thermostat's master control operates in one of four program modes that determine how the active setpoint is managed over time:

Mode	Behaviour
`PROGRAM`	Follow the configured schedule — setpoints change automatically according to time-based rules
`HOLD_PERMANENT`	Hold the current setpoint indefinitely, ignoring the schedule until manually cancelled
`HOLD_PERIOD`	Hold a setpoint for a defined duration, then resume the schedule
`HOLD_UNTIL`	Hold a setpoint until a specific time, then resume the schedule

The program mode is set via the master control's preset attribute. When in PROGRAM mode, the thermostat evaluates its bound schedule and transitions setpoints automatically. In any hold mode, the schedule is suspended.

Schedule Object

A schedule defines when and how setpoint changes occur. Each schedule is a platform-level object identified by UUID and managed through the Schedules API.

Schedule Properties

Property	Type	Purpose
`active`	Boolean	Whether the schedule is currently enabled
`cronExpression`	String	Cron expression defining when the schedule fires
`duration`	Integer (ms)	How long the scheduled action remains in effect
`activeFrom`	Long (timestamp)	Earliest time the schedule is eligible to fire
`activeUntil`	Long (timestamp)	Latest time the schedule is eligible to fire
`repeatUnit`	Enum	Recurrence granularity
`repeatInterval`	Integer	Number of repeat units between firings

Repeat Units

The schedule's recurrence is governed by repeatUnit:

Value	Meaning
`MINUTELY`	Repeats every N minutes
`HOURLY`	Repeats every N hours
`DAILY`	Repeats every N days
`WEEKLY`	Repeats every N weeks
`MONTHLY`	Repeats every N months
`YEARLY`	Repeats every N years

The repeatInterval determines the multiplier — for example, repeatUnit = DAILY with repeatInterval = 2 fires every two days.

How Scheduling Works

When the thermostat is in PROGRAM mode:

The edge runtime evaluates bound schedules against the current time.
When a schedule's cron expression matches and the current time falls within activeFrom–activeUntil, the schedule fires.
The schedule's action sets a new target setpoint on the thermostat.
The setpoint remains in effect for the configured duration, or until the next schedule fires.
The thermostat's control loop immediately begins regulating toward the new setpoint.

This evaluation runs locally on the Zipabox, so scheduled transitions occur even without cloud connectivity.

Hold Overrides

Hold modes allow users or automation rules to temporarily suspend the schedule:

Permanent Hold

Sets the thermostat to HOLD_PERMANENT mode. The current setpoint is maintained indefinitely. The schedule does not fire until the user manually returns the thermostat to PROGRAM mode.

Period Hold

Sets the thermostat to HOLD_PERIOD mode with a fixed duration. After the hold period elapses, the thermostat automatically returns to PROGRAM mode and resumes following its schedule.

Hold Until

Sets the thermostat to HOLD_UNTIL mode with a target time stored in the master control's holdUntil attribute. When the specified time arrives, the thermostat returns to PROGRAM mode.

Typical Schedule Patterns

Daily Comfort/Economy Cycle

A common residential pattern uses two or more schedules to alternate between comfort and economy setpoints throughout the day:

Schedule "Morning Warmup"
  cronExpression: fires at 06:30 daily
  action: set target to 21.0°C
  repeatUnit: DAILY
  repeatInterval: 1

Schedule "Daytime Economy"
  cronExpression: fires at 09:00 daily (weekdays)
  action: set target to 18.0°C
  repeatUnit: DAILY
  repeatInterval: 1

Schedule "Evening Comfort"
  cronExpression: fires at 17:00 daily
  action: set target to 21.0°C
  repeatUnit: DAILY
  repeatInterval: 1

Schedule "Night Setback"
  cronExpression: fires at 22:30 daily
  action: set target to 17.0°C
  repeatUnit: DAILY
  repeatInterval: 1

Seasonal Active Windows

Use activeFrom and activeUntil to restrict schedules to specific date ranges — for example, a heating schedule that only fires during the heating season (October–April), with a separate cooling schedule active during summer months.

Edge Execution

Schedule evaluation runs on the Zipabox edge runtime. Schedule definitions are synchronized between edge and cloud:

Schedules created or modified via the REST API are synced down to the edge.
The edge evaluates cron expressions and time windows locally.
Setpoint changes from schedule firings are applied immediately on the edge without requiring a cloud round-trip.

This ensures that climate schedules continue to operate during network outages.

Where to Continue

Goal	Page
Understand the thermostat model and operation modes	Overview
Configure actuator parameters (cooldown, hysteresis)	HVAC Configurations
Learn how devices are normalized for thermostat binding	Device Normalization

What This Page Covers​

Program Modes​

Schedule Object​

Schedule Properties​

Repeat Units​

How Scheduling Works​

Hold Overrides​

Permanent Hold​

Period Hold​

Hold Until​

Typical Schedule Patterns​

Daily Comfort/Economy Cycle​

Seasonal Active Windows​

Edge Execution​

Where to Continue​