Circadian Lighting Module

The Circadian module on Aida Controller adjusts interior lighting color temperature (CCT) and dim level throughout the day based on solar position at your site. It runs continuously on the controller — not as a one-shot schedule — and respects operator manual overrides the same way firmware daylight harvest does on the wall.

Overview

This module provides:

• Sun-aware CCT and dim curves — warmer and dimmer near sunrise/sunset; cooler and brighter at midday
• Facility-wide site location — latitude, longitude, and timezone from Settings → System (shared with Solaris and Dusk/Dawn schedules)
• Flexible targeting — zones, clusters, or individual devices
• 24-hour preview — chart or table before you commit changes
• Manual override — timed pause on wall-station and Control-page actions; latched suspend on off / vacancy until lights turn back on
• Automation integration — builtin task circadian-lighting reconciles every minute when the module is enabled

:::note Where Circadian lives Operator configuration is on the controller UI (Modules → Circadian). Circadian does not use the legacy Schedules wizard type circadian for new deployments — use the module + automation task instead. :::

How it works

Each reconcile cycle:

1. Loads site coordinates and the module curve (CCT min/max, dim min/max).
2. Resolves targets from scope (zones → clusters → devices).
3. Skips any target with an active manual override.
4. Sends CCT and dim commands to remaining targets.

Setpoints issued by Circadian are not treated as manual events — the module will not suspend itself.

Prerequisites

Before enabling Circadian, ensure you have:

• Aida Controller 2.0 installed and reachable on the building LAN
• Commissioned devices grouped into clusters (and optionally facility zones)
• Lighting fixtures that support dim and tunable-white (CCT) commands on the selected targets
• Operator access to the controller UI with permission to edit modules and system settings

Setup process

Step 1: Set site location

Circadian reads latitude and longitude from global controller settings — it does not store coordinates in the module config.

1. Open the controller UI and go to Settings → System.
2. Set Latitude (−90 to 90) and Longitude (−180 to 180) for the building.
3. Confirm Timezone matches local civil time (used for solar day boundaries and active-day filtering).
4. Save preferences.

:::tip Required for solar features Latitude and longitude are required when Circadian (or Solaris glare) is enabled. The module page shows a warning until site location is complete. :::

Step 2: Enable the Circadian module

1. Go to Modules and open the Circadian card (or navigate to Modules → Circadian).
2. Toggle the module Enabled.
3. Confirm the builtin automation task circadian-lighting is present under Automation → Tasks and enabled.

Step 3: Configure the curve

On the Circadian module page, adjust the curve sliders:

Setting	Typical use
CCT min / max	Warm evening (~2700–3000 K) to cool midday (~5000–6500 K)
Dim min / max	Lowest comfortable level at night; full output at peak day
Time step	How often setpoints are applied (1–60 minutes; default 1 min)
Pregenerate days	How many days of curves are precomputed (default 7)

Click Save after changing tunables.

Step 4: Choose targets

Use the Targets picker to define scope:

Mode	When to use
Zones	Circadian follows facility zone membership (recommended for floor/area control)
Clusters	Direct cluster list or All clusters (0) for whole-building
Devices	Single-fixture or small exceptions

Select at least one target in the chosen mode before saving.

Step 5: Active days

Choose which weekdays Circadian runs (ISO Monday = 1 through Sunday = 7). Uncheck days when the space is unoccupied or manual-only.

Step 6: Verify operation

1. Open the 24h preview chart or table for today — confirm CCT and dim follow the expected solar curve.
2. Click Pregenerate curves after large curve or location changes.
3. Click Apply now to run one reconcile immediately (useful after commissioning).
4. Check Automation → Logs for circadian-lighting runs — status should be success or skipped (when overrides are active), not repeated failed.

Manual override

Circadian must not fight operators who adjust lights from the wall or Control page.

Behaviour

Operator action	Effect on Circadian
on, up, down, scenes (s1–s3), flash	Timed pause — automation skips that target until the timeout expires (default 30 min; extendable on repeat events)
off, vacancy (vac)	Latched off — automation skips until on or motion (mot)
Circadian apply / automation	No suspend — normal operation continues

Module settings

Setting	Default	Description
Manual override enabled	On	When off, Circadian ignores operator events (not recommended in occupied spaces)
Auto-resume timeout	30 min	Duration of timed pause after manual dim/scene (1–60 min)

Active overrides table

The Circadian module page lists active suspends: target, mode (timed or latched), resume time, reason, and last update. When overrides are active, reconcile runs may show skipped_targets in automation logs — this is expected.

Configuration reference

Global (Settings → System)

Field	Used by
Latitude, longitude	Solar position for the entire site
Timezone	Local solar day and active-day boundaries

Module (Modules → Circadian)

Section	Purpose
Curve	CCT and dim bounds
Runtime	Apply interval, pregenerate horizon
Manual override	Enable + auto-resume timeout
Targets	Zones, clusters, or devices
Active days	Weekday filter

Automation task

The builtin circadian-lighting task runs on a 1-minute interval and calls module.circadian.apply. You normally do not edit this task — tune the module instead. Use Run now on the task card for a one-off reconcile.

Coordinating with Solaris

Circadian controls CCT + dim vs time. The Solaris module controls dim vs ALS (harvest) and shade vs sun angle (glare).

Module	Output	Conflict risk
Circadian	CCT + dim (time curve)	Same fixture if both target identical clusters
Solaris harvest	Dim (lux loop)	Same fixture if harvest zone overlaps Circadian scope

Recommendation: separate zones so Circadian and Solaris harvest do not target the same fixtures without a deliberate coordination policy. Shade glare zones are independent of Circadian lighting targets.

Monitoring and troubleshooting

Automation task status

Under Automation → Tasks, the circadian-lighting card shows:

• Running — module enabled, no blocking overrides on all targets
• Paused (timed) — at least one target in timed manual override
• Paused (off) — at least one target latched off

Common issues

Module enabled but lights do not change

• Confirm site latitude/longitude are set in Settings → System.
• Verify targets include the fixtures you expect (zone membership vs cluster list).
• Check Active overrides — manual pause or latched off blocks apply for that target.
• Confirm fixtures support both dim and CCT commands on the controller.
• Review Automation → Logs for failed steps or empty applied_targets.

Preview shows a flat or empty curve

• Site location missing or invalid.
• Active days exclude today.
• Pregenerate may be stale — click Pregenerate curves.

Circadian fights manual adjustments

• Ensure Manual override is enabled on the module page.
• Confirm wall-station events reach the controller (INX ingest / event log).
• Increase Auto-resume timeout if operators need longer manual control.

Legacy schedule type circadian still present

• Older rows under Schedules may still execute. For new sites, disable legacy circadian schedules and use the module path only.

Related documentation

• Solaris module — daylight harvesting and glare control (complementary)
• Aida Controller overview — install and architecture
• Controller Public API — programmatic control (separate from module automation)