Add more triggers and conditions on the sun domain

[nielsrowinbik]

As part of this roadmap opportunity, we would like to introduce various new triggers and conditions on the sun domain. The exact reasoning behind this proposal is documented in the roadmap opportunity (I don't want to maintain the reasoning in two places), but the short version is that the current sun triggers and conditions are far too limiting.

The list of proposed triggers and conditions (pasted from the opportunity, which will be the source of truth) follows below. Some notes:

• These triggers and conditions would not support custom targeting configurations, and since there is only ever one target (the sun entity), they don't need support for the behaviour option.
• Some triggers and conditions (specifically the numerical ones with threshold support) should have support for for.
• Because of the high specificity of these triggers, I am assuming there no longer is a need for time based offsets within the triggers. I am open to feedback on this.
• Some of the proposed triggers/conditions overlap. I've intentionally left them in because, semantically, they're different. For example, "golden hour ended" and "blue hour started" describe the same moment, but from different perspectives.
• There are no sun.is_solar_noon / sun.is_solar_midnight conditions. These are instantaneous moments, not states that can be meaningfully tested.
• There are no sun.is_dawn / sun.is_dusk conditions. Dawn and dusk are instantaneous moments, not durations, so there is nothing to test as a sustained state. See the note on phases vs. moments below.

Phases vs. moments (dawn, dusk, and twilight)

These terms are easy to conflate, so to be precise about how they map to triggers and conditions here:

• Twilight is a phase. It is a duration during which the sun sits in a band below the horizon. Each band has three types: civil (-0.833° to -6°), nautical (-6° to -12°), and astronomical (-12° to -18°). Because a phase has duration, it is testable as a condition: sun.is_twilight with the type option.
• Dawn and dusk are moments. They are the instants at which the sun crosses a band's boundary. Dawn is the morning (rising) crossing, dusk is the evening (descending) crossing. So "civil dawn" is the instant the sun reaches -6° while rising, and "civil dusk" is the instant it reaches -6° while descending. Because a moment has no duration, it is exposed as a trigger: sun.dawn / sun.dusk with the type option.
  There is no phase called "civil dawn" or "civil dusk"; the phase is civil twilight, and dawn/dusk are simply the names for its morning and evening edges. This is why dawn/dusk appear only as triggers and twilight appears only as a condition.

Deliberate naming convention deviations

The sun domain does not fit the trigger/condition naming convention cleanly, and we are deviating on purpose:

• Trigger titles. The convention expects [Entity type] [past-tense event]. Sun events are named moments ("Sunrise", "Dawn"), not verb-able transitions. Forcing the pattern ("Sun reached sunrise") reads poorly, so we keep the natural names.
• Condition titles. The convention requires the entity type in every title. "It is night" and "It is twilight" omit it on purpose. Nobody describes the sun as being "below astronomical twilight", so forcing "Sun" in would read unnaturally.

Triggers and conditions

Higher priority

Triggers

Key	Title	Description	Spec	Options
sun.sunrise	Sunrise	Triggers when the sun rises.	Elevation reaches -0.833° while rising.	—
sun.sunset	Sunset	Triggers when the sun sets.	Elevation reaches -0.833° while descending.	—
sun.solar_noon	Solar noon	Triggers when the sun reaches its highest.	Elevation reaches its peak.	—
sun.solar_midnight	Solar midnight	Triggers when the sun reaches its lowest point below the horizon.	Elevation reaches its lowest point.	—
sun.elevation_crossed_threshold	Sun elevation crossed threshold	Triggers when the sun's elevation crosses a threshold you set.	Fires once when the threshold or range set by the user is reached.	Reuses the common threshold options for crossed_threshold triggers.
sun.elevation_changed	Sun elevation changed	Triggers whenever the sun's elevation changes, optionally limited to a threshold or range you set.	Fires on every elevation change, with an optional threshold or range.	Reuses the common threshold options for crossed_threshold triggers.
sun.dawn	Dawn	Triggers at dawn, when civil, nautical, or astronomical twilight begins.	Elevation reaches a configurable threshold while rising.	type: civil (-6°, default), nautical (-12°), astronomical (-18°).
sun.dusk	Dusk	Triggers at dusk, when civil, nautical, or astronomical twilight ends.	Elevation reaches a configurable threshold while descending.	type: civil (-6°, default), nautical (-12°), astronomical (-18°).

Conditions

Key	Title	Description	Spec	Options
sun.is_up	Sun is up	Tests if the sun is up.	Elevation >= -0.833°.	—
sun.is_set	Sun is set	Tests if the sun is set.	Elevation < -0.833°.	—
sun.is_rising	Sun is rising	Tests if the sun is rising.	Elevation increasing (evaluated from trend, because reading the raw value could introduce noise around solar noon and solar midnight).	—
sun.is_setting	Sun is setting	Tests if the sun is setting.	Elevation decreasing (evaluated from trend, because reading the raw value could introduce noise around solar noon and solar midnight).	—
sun.elevation	Sun elevation	Tests the sun's elevation against a threshold you set.	Elevation compared against the user-set threshold.	Reuses the common threshold selector (above/below and value).
sun.is_night	It is night	Tests if it is night.	Elevation <= -18°.	—
sun.is_morning_twilight	It is morning twilight	Tests if it is morning twilight, optionally of a specific type.	Elevation within the band for the chosen type.	type: any (-18° to -0.833°, default), civil (-6° to -0.833°), nautical (-12° to -6°), astronomical (-18° to -12°).
sun.is_evening_twilight	It is evening twilight	Tests if it is evening twilight, optionally of a specific type.	Elevation within the band for the chosen type.	type: any (-18° to -0.833°, default), civil (-6° to -0.833°), nautical (-12° to -6°), astronomical (-18° to -12°).

Lower priority (add later)

Triggers

Key	Title	Description	Spec	Options
sun.golden_hour_started	Golden hour started	Triggers when golden hour starts, in the morning, the evening, or either.	Morning: elevation reaches -4° while rising. Evening: elevation reaches 6° while descending. With any, fires at both crossings.	period: any (default), morning, evening
sun.golden_hour_ended	Golden hour ended	Triggers when golden hour ends, in the morning, the evening, or either.	Morning: elevation reaches 6° while rising. Evening: elevation reaches -4° while descending. With any, fires at both crossings.	period: any (default), morning, evening
sun.blue_hour_started	Blue hour started	Triggers when blue hour starts, in the morning, the evening, or either.	Morning: elevation reaches -6° while rising. Evening: elevation reaches -4° while descending. With any, fires at both crossings.	period: any (default), morning, evening
sun.blue_hour_ended	Blue hour ended	Triggers when blue hour ends, in the morning, the evening, or either.	Morning: elevation reaches -4° while rising. Evening: elevation reaches -6° while descending. With any, fires at both crossings.	period: any (default), morning, evening
sun.midnight_sun_started	Midnight sun started	Triggers when the midnight sun period starts and the sun stops setting.	Sun stops setting; stays above the horizon for 24h.	—
sun.midnight_sun_ended	Midnight sun ended	Triggers when the midnight sun period ends and the sun sets again.	Sun sets again after a midnight sun period.	—
sun.polar_night_started	Polar night started	Triggers when the polar night period starts and the sun stops rising.	Sun stops rising; stays below the horizon for 24h.	—
sun.polar_night_ended	Polar night ended	Triggers when the polar night period ends and the sun rises again.	Sun rises again after a polar night period.	—

Conditions

Key	Title	Description	Spec	Options
sun.is_golden_hour	It is golden hour	Tests if it is golden hour.	Elevation between -4° and 6°.	period: any (default), morning, evening
sun.is_blue_hour	It is blue hour	Tests if it is blue hour.	Elevation between -6° and -4°.	period: any (default), morning, evening
sun.is_midnight_sun	It is midnight sun	Tests if it is midnight sun.	Sun stays above the horizon for 24h.	—
sun.is_polar_night	It is polar night	Tests if it is polar night.	Sun stays below the horizon for 24h.	—

Changelog

23-6-2024

• Consolidated sun.civil_dawn, sun.nautical_dawn, sun.astronomical_dawn → sun.dawn (with type option)
• Consolidated sun.civil_dusk, sun.nautical_dusk, sun.astronomical_dusk → sun.dusk (with type option)
• Added sun.midnight_sun_started, sun.midnight_sun_ended, sun.polar_night_started, and sun.polar_night_ended triggers.
• Added UI titles and descriptions for all new and remaining elements to match naming convention.
• Added notes on phases versus moments (triggers vs equivalent conditions)
• Added notes on deliberate exclusions

[abmantis]

Hey @nielsrowinbik ! I don't think this requires an architecture proposal here, since there is no architecture changes or changes to the entity models.

EDIT: oh, is it because its a change to the sun component? Yeah, that's a weird legacy one 😅

[gjohansson-ST]

Besides sun.sun it follows practice so I don't think this requires a decision either to get more triggers etc in as wanted by the roadmap.

[mib1185]

-> OpenHomeFoundation/roadmap#96 (comment) 😬

[emontnemery]

Feedback from core meeting May 21st:

• We suggest to implement the high priority cases first
• Suggest to split twilight conditions in two to mirror the triggers
• Suggest to make civil / nautical / astronomical options for the triggers and conditions instead of adding all as individual triggers and conditions. This could also be relevant for the photography related triggers and conditions.

[Markus98]

I also added some additional notes in my comment below. It includes some of the things we also talked about in the meeting.

[nielsrowinbik]

I want to spend little to no OHF resources on this project/proposal at this point, and so the prioritisation is to help contributors figure out which things we think should be added first, but they are free to ignore this and add the ones they deem necessary.

Incorporated the other feedback through @Markus98' extensive proposal (thanks a bunch for that, really helpful!).

[nielsrowinbik]

BTW @emontnemery, does this mean any blockages for this proposal have been lifted? There doesn't seem to be any objection other than a few suggestions (which have now been incorporated)?

[Markus98]

I personally want to see these implemented. A couple things worth revising though. I've added an appendix with the revised triggers and conditions at the end of this comment.

Conditions

• Consider adding sun.is_rising. Needed for directionality checks. Using the time to infer this is not enough since solar noon/midnight moments vary. We could also consider having a separate sun.is_setting condition for user convenience. This would read better when writing automations as well.
• Document polar-latitude behaviour. At high/low latitudes (e.g. Finland) sun.is_night, etc. can stay true or false for weeks. Users will write automations assuming daily state changes. We could add a conditions like sun.is_midnight_sun and sun.is_polar_midnight for time periods when the sun will never rise/set.
• These need sun.is_rising so they can be used with an AND block in automations. These could alternatively be split into morning/evening ones, but I prefer the AND.
  • sun.is_nautical_twilight
  • sun.is_astronomical_twilight
  • sun.is_golden_hour
  • sun.is_blue_hour

Triggers

• The term "twilight" does not consider directionality. We should use "dusk" instead for when the sun is setting:
  • sun.civil_twilight --> sun.civil_dusk
  • sun.nautical_twilight --> sun.nautical_dusk
  • sun.astronomical_twilight --> sun.astronomical_dusk
• Some triggers maybe need to consider directionality. Either the user needs to combine these with the sun.is_rising condition or we should allow configuration for these to trigger either when it's rising, setting, or both. Another option would also just to split these into two separate triggers each.
  • sun.elevation_crossed_threshold
  • sun.golden_hour, sun.golden_hour_ended, sun.blue_hour, sun.blue_hour_ended.
    • These are also inconsistent in the current proposal. For example sun.golden_hour_ended only fires in the evening, not morning. (sun.blue_hour and sun.blue_hour_ended same inconsistency)
• Due to overlap, we should consider sun.night --> sun.astronomical_dusk and sun.night_ended --> sun.astronomical_dawn. Or then we can add these terms in the description of the trigger.
• I would argue that time-based offset triggers ARE needed for the sun events. For example, if I want to have 30 minutes of time to do before something before it gets too dark, I would want to use time offsets for these.
• The "started" suffix reads oddly for instant events. Dawn/dusk are moments, not durations:
  • sun.civil_dawn (drop "started")
  • sun.nautical_dawn, sun.astronomical_dawn likewise

Numbers

• sun.astronomical_twilight (--> sun.astronomical_dusk) should be -18°, is -12° in proposal
• Sunrise/sunset use 0° but the astronomical convention is -0.833° (accounts for solar radius and atmospheric refraction). Affects:
  • sun.sunrise, sun.sunset
  • sun.above_horizon, sun.below_horizon

Appendix: Revised complete list of triggers and conditions with my feedback applied

Revised complete list of conditions and triggers, courtesy of Claude

Higher priority

Triggers

• Sunrise (elevation reaches -0.833° while rising) — sun.sunrise
• Sunset (elevation reaches -0.833° while descending) — sun.sunset
• Solar noon (elevation reaches its peak) — sun.solar_noon
• Solar midnight (elevation reaches its lowest point) — sun.solar_midnight
• Sun elevation threshold crossed (once when thresholds/range set by user is reached; user-configurable to trigger on rising, descending, or both) — sun.elevation_crossed_threshold
• Sun elevation changed (on every elevation change, but with optional thresholds/range set by user) — sun.elevation_changed
• Civil dawn (elevation reaches -6° while rising) — sun.civil_dawn
• Civil dusk (elevation reaches -6° while descending) — sun.civil_dusk
• Astronomical dawn (elevation reaches -18° while rising) — sun.astronomical_dawn
• Astronomical dusk (elevation reaches -18° while descending) — sun.astronomical_dusk

Conditions

• Sun is up (elevation >= -0.833°) — sun.above_horizon
• Sun is down (elevation < -0.833°) — sun.below_horizon
• Sun is rising (elevation increasing) — sun.is_rising
• Sun is descending (elevation decreasing) — sun.is_descending
• It is night (elevation <= -18°) — sun.is_night
• It is twilight (elevation between -18° and -0.833°) — sun.is_twilight
• It is civil twilight (elevation between -6° and -0.833°) — sun.is_civil_twilight
• It is midnight sun (sun stays above the horizon for 24h) — sun.is_midnight_sun
• It is polar night (sun stays below the horizon for 24h) — sun.is_polar_night

Lower priority

Triggers

• Nautical dawn (elevation reaches -12° while rising) — sun.nautical_dawn
• Nautical dusk (elevation reaches -12° while descending) — sun.nautical_dusk
• Photography light windows
  • Golden hour
    • Morning
      • Start (elevation reaches -4° while rising) — sun.golden_hour_started_morning
      • End (elevation reaches 6° while rising) — sun.golden_hour_ended_morning
    • Evening
      • Start (elevation reaches 6° while descending) — sun.golden_hour_started_evening
      • End (elevation reaches -4° while descending) — sun.golden_hour_ended_evening
  • Blue hour
    • Morning
      • Start (elevation reaches -6° while rising) — sun.blue_hour_started_morning
      • End (elevation reaches -4° while rising) — sun.blue_hour_ended_morning
    • Evening
      • Start (elevation reaches -4° while descending) — sun.blue_hour_started_evening
      • End (elevation reaches -6° while descending) — sun.blue_hour_ended_evening

Conditions

• It is nautical twilight (elevation between -12° and -6°) — sun.is_nautical_twilight
• It is astronomical twilight (elevation between -18° and -12°) — sun.is_astronomical_twilight
• It is golden hour (elevation between -4° and 6°) — sun.is_golden_hour
• It is blue hour (elevation between -6° and -4°) — sun.is_blue_hour

Notes

• All elevation values are sun-center elevation. The -0.833° threshold for sunrise/sunset/horizon corresponds to the sun's upper limb touching the horizon when accounting for atmospheric refraction and solar radius.
• Inequality strictness is documented per condition; boundary elevations resolve consistently to one side (e.g. -0.833° is "up", -18° is "night").
• Directional twilight conditions are intentionally not split into morning/evening variants. Users needing directionality can combine the relevant is_* condition with sun.is_rising or sun.is_descending.
• Photography light windows overlap with twilight bands by design (e.g. blue hour sits entirely within civil twilight; golden hour straddles civil twilight and day). Multiple is_* conditions can therefore be true simultaneously.

[frenck]

My main issue with the revised list: it enumerates every level instead of treating them as one concept with a parameter.

The dawn/dusk and twilight levels are all separate entries now: civil_dawn, nautical_dawn, astronomical_dawn, the dusks, plus is_civil_twilight / is_nautical_twilight / is_astronomical_twilight. That's a lot of surface on the sun domain for one concept, and it locks us in. Every refinement means another trigger.

I'd rather have:

• sun.dawn / sun.dusk triggers with a phase option (civil | nautical | astronomical). Dawn vs. dusk already carries the direction.
• One sun.is_twilight condition with the same phase option, defaulting to "any".

Same applies to golden/blue hour, which shouldn't be eight triggers. sun.golden_hour / sun.blue_hour with a phase: start | end option does the job.

sunrise, sunset, solar_noon and solar_midnight stay as dedicated triggers, since those are distinct moments people reach for by name.

One naming nit: the conditions mix styles. above_horizon / below_horizon have no prefix, but is_rising, is_night, is_twilight do. Let's pick one rule. I'd go is_ on all of them.

../Frenck

                       

Blogging my personal ramblings at frenck.dev

[nielsrowinbik]

The proposal now also contains a list with a few consolidated triggers/conditions, pending some more feedback on this to make either definitive.

[emontnemery]

The proposal was approved by the core architecture meeting 2026-06-18 with these remarks:

• Approve the consolidated version, with splitting twilight condition into dusk and dawn (morning twilight and evening twilight)

Note "consolidated version" refers to:

Consolidated sun.civil_dawn, sun.nautical_dawn, sun.astronomical_dawn → sun.dawn (with type option)
Consolidated sun.civil_dusk, sun.nautical_dusk, sun.astronomical_dusk → sun.dusk (with type option)