Sun
The Sun integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] calculates sun-related times such as sunrise, sunset, dawn, and dusk based on your configured home location. This means that all time-based calculations and triggers will be accurate for your specific location, as defined in your basic configuration.
The sun integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] will use the location as configured in your Home Assistant configuration to track if the sun is above or below the horizon. The sun can be used within automations as a trigger with an optional offset to simulate dawn/dusk or as a condition with an optional offset to test if the sun has already set or risen.
Configured by default
This integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] is configured and installed by default, so you don’t need
to set it up yourself, unless you’ve disabled or removed the
default_config: line from your
YAML configuration.
If that is the case, follow the steps below to set it up.
Configuration
To add the Sun service to your Home Assistant instance, use this My button:
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
Go to
Settings > Devices & services . -
In the bottom right corner, select the
Add Integration button. -
From the list, select Sun.
-
Follow the instructions on screen to complete the setup.
YAML configuration
Alternatively, you can configure and set up this integration manually via YAML.
To enable the sun integration in your installation, add the
following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes.
# Example configuration.yaml entry
sun:
Automation trigger
Home Assistant provides a set of dedicated sun triggers for sunrise, sunset, dawn, dusk, solar noon, solar midnight, and the sun’s elevation. See the list of triggers below for the full set.
The classic sun trigger described here is still supported and is the one to use when you need a fixed time offset before or after sunrise or sunset.
The sun’s event listener performs the action when the sun rises or sets, with an optional offset.
The sun trigger needs the trigger type sun, an event (sunset or sunrise), and an optional offset:
triggers:
- trigger: sun
event: sunrise
# Fire one hour before sunrise.
offset: "-01:00:00"
The following keys are available:
-
event: Required. Eithersunriseorsunset. -
offset: Optional. A time offset relative to the sun event, specified as a number of seconds or inHH:MM:SSformat. A negative value fires the trigger before the sun event, a positive value fires it after.
For example, if sunrise is at 06:00 and you set offset: "-01:00:00", the automation runs at 05:00. With offset: "01:00:00", it runs at 07:00. The same rule applies to sunset.
Because the duration of twilight varies throughout the year, a fixed offset is not always the best way to trigger automations around dawn or dusk. For more precise dawn or dusk automations, use a sun elevation trigger instead.
Maintains entity sun.sun
| Possible state | Description |
|---|---|
above_horizon |
When the sun is above the horizon. |
below_horizon |
When the sun is below the horizon. |
List of triggers
The Sun integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following triggers. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.
-
Dawn (
sun.dawn) Triggers at dawn, when civil, nautical, or astronomical twilight begins. -
Dusk (
sun.dusk) Triggers at dusk, when civil, nautical, or astronomical twilight ends. -
Sun elevation changed (
sun.elevation_changed) Triggers whenever the sun’s elevation changes, optionally limited to a threshold or range you set. -
Sun elevation crossed threshold (
sun.elevation_crossed_threshold) Triggers when the sun’s elevation crosses a threshold you set. -
Solar midnight (
sun.solar_midnight) Triggers when the sun reaches its lowest point. -
Solar noon (
sun.solar_noon) Triggers when the sun reaches its highest point. -
Sunrise (
sun.sunrise) Triggers when the sun rises. -
Sunset (
sun.sunset) Triggers when the sun sets.
For an overview of every trigger across all integrations, see the triggers reference.
List of conditions
The Sun integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following conditions. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.
-
Sun elevation (
sun.elevation) Tests the sun’s elevation against a threshold you set. -
Sun is ascending (
sun.is_ascending) Tests if the sun is ascending. -
Sun is descending (
sun.is_descending) Tests if the sun is descending. -
It is evening twilight (
sun.is_evening_twilight) Tests if it is evening twilight, optionally of a specific type. -
It is morning twilight (
sun.is_morning_twilight) Tests if it is morning twilight, optionally of a specific type. -
It is night (
sun.is_night) Tests if it is night. -
Sun is set (
sun.is_set) Tests if the sun is set. -
Sun is up (
sun.is_up) Tests if the sun is up.
For an overview of every condition across all integrations, see the conditions reference.
Sensors
The sensors are also available as attributes on the sun.sun entity for backward compatibility.
| Sensors | Description |
|---|---|
| Next rising | Date and time of the next sun rising (in UTC). |
| Next setting | Date and time of the next sun setting (in UTC). |
| Next dawn | Date and time of the next dawn (in UTC). |
| Next dusk | Date and time of the next dusk (in UTC). |
| Next noon | Date and time of the next solar noon (in UTC). |
| Next midnight | Date and time of the next solar midnight (in UTC). |
| Elevation | Solar elevation. This is the angle between the sun and the horizon. Negative values mean the sun is below the horizon. |
| Azimuth | Solar azimuth. The angle is shown clockwise from north. |
Binary sensors
The binary sensors are also available as attributes on the sun.sun entity for backward compatibility.
| Sensors | Description |
|---|---|
| Solar rising |
on when the sun is currently rising (after solar midnight and before solar noon). |