Circadian Light Group

What is a Circadian Light Group?

A Circadian Light Group is a single virtual light device that controls a group of real lights in your home. It continuously calculates the "right" brightness and color temperature for the current time of day and applies those values to every light it manages — but only to lights that are already on.

The group does not turn lights on or off. It only adjusts already-on lights so they follow a circadian rhythm. The on/off button on the group itself controls whether the scheduler is active, not the lights.

Use cases: bright cool light during the day, warm dim light in the evening, deep red at night to preserve melatonin and night vision, automatic adjustment based on outdoor light levels, daily routines tied to sunrise/sunset for users at high latitudes.

Pairing

Add the device via Devices → Add Device → Smart (Components) Toolkit → Circadian Light Group.

1. Select scope — pick "Whole house" or specific zones to scan for lights.
2. Select lights — the app lists all devices with class === 'light'. Untick any you don't want included.
3. Configure — a form-based editor lets you set the schedule, light profile, outdoor source and per-light tweaks. The same form is available later via Repair.

All settings can be changed later by long-pressing the device → Repair.

Schedule — Anchor Modes

The schedule has four anchors: Morning, Day, Evening, Night. Each anchor independently picks one of three resolution modes:

Time

A fixed wall-clock time (HH:MM). Best for users near the equator where sunrise/sunset times are stable.

Solar event

A solar event computed from your Homey's geolocation. Each anchor can pick:

• Sunrise / Sunset
• Civil dawn / Civil dusk
• Nautical dawn / Nautical dusk
• Astronomical dawn / Astronomical dusk
• Golden hour (morning end)
• Golden hour (evening start)
• Blue hour (morning)
• Blue hour (evening)
• Solar noon
• Solar midnight

Each solar anchor accepts an offset in minutes (-180 to +180), e.g. "30 minutes before sunset", and a polar fallback time used when the chosen event doesn't occur today (midnight sun or polar night).

Lux sensor

An anchor that fires when a real lux sensor crosses a configurable threshold. You pick the sensor, the threshold value, and the direction:

• Rising — the anchor fires when the sensor goes from below threshold to at-or-above (default for Morning and Day anchors).
• Falling — fires when the sensor goes from above to at-or-below (default for Evening and Night).

Until the threshold has been crossed today, the configured fallback time is used. After a crossing, the time of crossing becomes the anchor for the rest of the day.

Mix and match

Morning: Time 08:00            ← strong white light starts at 8 sharp
Day:     Solar noon             ← peak brightness at solar noon
Evening: Solar sunset           ← evening warmth from actual sunset
Night:   Lux 50 falling         ← night mode when ambient drops below 50 lux

Light Profile

For each phase you set:

• Dim (0–1): brightness for the phase.
• Temperature (0–1, lower = warmer): color temperature target.

Values transition smoothly between anchors using a smoothstep curve. The currently calculated dim and temperature are always shown on the device tile, regardless of whether the scheduler is actively pushing values to the lights.

Red mode threshold

A single slider controls when color-capable lights shift to red:

• When the calculated temperature falls below the threshold, lights with light_hue and light_saturation support switch to red (hue = 0).
• Saturation scales linearly from 0 (at the threshold) to 1 (at temperature 0). The deeper below the threshold, the more saturated the red.
• Set the threshold to 0 to disable red mode entirely.
• Lights without color support continue to follow only light_temperature.
• Per-light toggle Allow red mode excludes specific lights.

Outdoor Light Source

Outdoor brightness can be used to dim group lights up or down depending on how bright it is outside.

Provider options:

• Astronomical — calculated from sun elevation. No external dependencies.
• External value from Flow — a Flow pushes a lux value via the action card "Set outdoor lux".
• Homey lux sensor — read from a chosen sensor with measure_luminance.
• Open-Meteo / MET.no — fetched from weather APIs (radiation-based estimate).

A fallback provider is used when the primary fails. Cache minutes controls how often the provider is queried. Stale after minutes applies to externally pushed values.

Outdoor adjustment

When enabled, the brightness is multiplied by a factor between min dim factor and max dim factor, scaled across the configured min/max lux range.

Per-Light Settings

Each light in the group has its own toggles:

• Enabled — include the light in updates.
• Prewarm before on — set color/temperature on the light while it's still off, so it starts in the right tone when turned on by anything else (a flow, a switch). Disabled automatically for lights that misbehave (e.g. that turn on when capabilities are written).
• Allow red mode — opt the light out of red mode while keeping it in the group.
• Min/Max dim — clamps the dim value sent to that specific light. Useful for lights with a minimum on-level higher than 0.

Flow Cards

Triggers

• When Circadian target changed — fires every scheduler tick. Tokens: phase, dim, temperature, outdoor_lux.
• When Phase changed — fires only on phase transitions. Tokens: phase, previous_phase.
• When Red mode started / ended.
• When Paused / Resumed.
• When Turned on / Turned off.
• When Outdoor light requested — fires when the device wants an external lux value (only for the external provider).
• When Error occurred.
• When Solar event occurred (app-level) — pick any of the 14 solar events plus an offset in minutes; fires daily at that point.

Conditions

• And Is in phase — current phase is day/evening/night.
• And Red mode is active.
• And Is paused.
• And Is on.

Actions

• Then Apply now — recalculate and push values immediately.
• Then Pause — amount + unit (seconds / minutes / hours). Set 0 to pause until manually resumed.
• Then Pause until time — a wall-clock time (HH:MM).
• Then Pause until solar event — pick from the 14 solar events plus an offset.
• Then Resume.
• Then Turn on / Turn off / Toggle.
• Then Set red threshold — permanently changes the configured threshold.
• Then Apply temporary state — push specific dim, temperature, saturation values (any subset) and an optional "force red" flag. Values are temporary and the next scheduler tick (~2 min) restores calculated values. Useful for testing or quick "moods".
• Then Force red mode — on / off / clear, with an optional duration.
• Then Set outdoor lux — for the external value provider, push a lux reading from any Flow.

Examples

Movie mode without breaking circadian rhythm

WHEN: Button "Movie" pressed
THEN: Pause Circadian Light Group for 3 hours
THEN: Apply temporary state — dim 0.15, temperature 0.05, force_red true

When the pause expires, normal circadian values resume.

Wake-up sequence at sunrise

WHEN: Solar event occurred — Sunrise (offset -30)
AND:  Workday today
THEN: Turn on Circadian Light Group
THEN: Turn on bedroom lights

Notify when red mode starts

WHEN: Red mode started (Living Room Circadian)
THEN: Send notification "Wind down — house is in night mode"

Troubleshooting

• A light isn't included in the picker — only devices with class === 'light' show up. Some installations classify smart bulbs incorrectly. You can manually add the light by editing the JSON in the device's settings.
• Lights don't change — make sure the group's on/off is on, that clg_paused is false, and that the lights themselves are on. The group only adjusts already-on lights.
• Polar latitudes — at extreme latitudes, sunrise/sunset may not occur for parts of the year. Each solar anchor has a polar fallback time used when the event doesn't happen today.
• Lux mode doesn't trigger — the anchor only triggers on a true crossing (previous reading on one side of the threshold, current reading on the other). Until the first crossing of the day, the fallback time is used. The first sensor reading after a restart is used as baseline only — no crossing is detected for it.
• Red mode kicks in earlier/later than expected — adjust the red threshold slider. With default profile (evening 0.25, night 0), threshold 0.2 gives red in late night. Raise the threshold to make red appear earlier in the evening.