Circadian Light Group

What's new in 1.10.x

• 1.10.16 — Flow Doctor can now resolve previously captured Homey device IDs when deleted devices only appear by ID in broken flows.
• 1.10.7 — Multi-device flow cards and the scheduler now write to up to 5 lights in parallel and retry transient mesh timeouts. Conflicting commands (e.g. an "all off" arriving mid-"all on") supersede the running one instead of fighting it.
• 1.10.7 — Group-level actions Turn on all members and Turn off all members.
• 1.10.6 — On/off state is now respected correctly under all paths.
• 1.10.5 — Tuneable lights now correctly become warmer (not cooler) towards evening.
• 1.10.2 — Pre-warm auto-detection during pairing; Turn on light at current circadian level action; smarter candidate filter (Hue/Z2M-bridged sockets and Z-Wave dimmer modules).

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) in your Homey's time zone, including daylight saving time. 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            ← the wake-up ramp 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.

Morning profile (optional)

Day, Evening and Night always have their own values. Morning is optional and is switched on with Own morning profile:

• Off (default) — the night values hold until the Morning anchor, and the ramp to Day starts from them. With the default profile the lights are still dim and red at the Morning anchor and reach full Day values at the Day anchor.
• On — the Morning values apply from the Morning anchor and fade into Day by the Day anchor. The step from night to morning at the anchor uses the normal transition time. The group also reports a morning phase between the Morning anchor and halfway to Day.

In config_json the morning profile is an optional profile.morning block with dim and temperature; a missing field uses the night value. Without the block the group behaves exactly as before the morning profile existed.

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 morning/day/evening/night (morning only with a morning profile).
• And Red mode is active.
• And Is paused — for a Collection, yes when the Collection itself or at least one available member group 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) in your Homey's time zone.
• Then Pause until solar event — pick from the 14 solar events plus an offset.
• Then Resume.
• Then Turn on / Turn off / Toggle and report the result (Advanced Flow) — the same as the device's own On, Off and Toggle cards, but with the result tokens described below. The device's own cards cannot return tokens.
• 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.
• Then Turn on light at current circadian level — pick any member from a dropdown; the action sets temperature/colour and dim, then turns the light on, in one step. Avoids the brief flash at the previous brightness on lamps that don't support pre-warm.
• Then Turn on all members — switch every enabled light in the group on at the current circadian dim/temperature.
• Then Turn off all members — switch every enabled light in the group off.

The multi-device actions and the scheduler push to up to 5 lights in parallel, verify the result afterwards, and retry lights that did not confirm, for example after a Z-Wave / Zigbee timeout. If a conflicting command arrives (e.g. an "all off" right after an "all on"), the new command supersedes the running one — no fighting between flows.

Retries after the card, and the result tokens

Homey stops an app's Flow card after 60 seconds, and the Flow then stops at that card. A light that does not answer can take up to 10 seconds per attempt, so a group with a few dead lights could come close to that limit. To keep the Flow moving:

• A card sends every light its commands, checks each light once, and then lets the Flow continue. This usually takes a few seconds.
• If a light has not confirmed yet, the card checks once more after 1.5 seconds. Lights that still have not confirmed are retried in the background. A newer command for the same group stops those retries.
• If a card is still busy after 50 seconds, the Flow continues anyway and the rest finishes in the background.
• Lights that still fail after the retries are reported by the Error occurred trigger, as before.

The cards Turn on / Turn off / Toggle and report the result give two tokens. Homey shows THEN cards with tokens only in Advanced Flows, so these three cards are Advanced Flow only; the other Circadian cards have no tokens and still work in standard Flows.

• All lights confirmed (yes/no) — yes when every light had confirmed before the Flow continued, or when nothing had to change (for example because the group is paused). No when the Flow continued while lights were still being retried, or when a light did not respond.
• Status (text) — what happened, for example Continued before everything was confirmed. Lights still being retried in the background (1 of 11): Dining room bulb. For a Circadian Light Group Collection the text has one sentence per group when the groups ended differently.

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.
• "All lights confirmed" is often no — the Status token names the lights that do not answer. A light that is unplugged or out of range slows every command down; untick Enabled for that light in the group's light settings until it works again.
• 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.