Sun2 Sensor

Creates sensors that provide information about various sun related events.

Follow the installation instructions below. Then add one or more locations with desired sensors either via YAML, the UI or both.

Installation

After it has been downloaded you will need to restart Home Assistant.

Versions

This custom integration supports HomeAssistant versions 2023.4.0 or newer.

Services

sun2.reload

Reloads Sun2 from the YAML-configuration. Also adds SUN2 to the Developers Tools -> YAML page.

sun2.get_location

Responds with the current location configuration options (latitude, etc.) of the specified location. Takes just one parameter, location, which is the name of the location, and is also the name of the corresponding integration entry.

sun2.update_location

Updates one or more parts of the location configuration options of the specified location. Takes one required parameter, location. (Same as sun2.get_location service.) Can also take location parameters (latitude, longitude & time_zone), which if any are specified, they must all be specified. Can also take observer elevation parameters (obeserver_elevation). These parameters are the same as specified below in the YAML configuration section.

Configuration

One or more "locations" can be added for this integration. Each location is defined by a set of parameters (latitude, etc.) Sensors will be created for each location that provide sun related data for that location. A location can be added either via the UI or YAML.

To add a location via the UI, you can use this My Button:

Alternatively, go to Settings -> Devices & services and click the + ADD INTEGRATION button. Find or search for "sun2", click on it, then follow the prompts.

The remainder of this section defines the list of YAML configuration options for each location.

* These must all be used together. If not used, the default is Home Assistant's location, time zone & name configuration.

Observer Elevation

The easterly sun events (sunrise, dawn, etc.) and westerly sun events (sunset, dusk, etc.) can be viewed at either the horizon, or at the top of some obstruction, such as a mountain. (For more details, see Effect of Elevation.) This configuration option describes which apply at the specified location.

There are two basic choices. The first is that the sun events are seen at the horizon in both directions. In this case, a simple number may be given which defines the observer's elevation above ground level (not sea level) in meters. If this option is not specified, then the elevation from the system's general configuration will be used.

NOTE: Settings -> System -> General -> Elevation is defined as "Altitude above sea level in meters. Impacts sunrise data."

This is, and always has been, defined incorrectly. It should be defined as altitude above ground level, not sea level. Therefore, if the optional observer_elevation is not specified, and your system's general elevation contains your home's altitude above sea level, then this integration will get the wrong elevation value, resulting in incorrect sensor values. This situation should be avoided. Therefore, if it occurs, a WARNING will be generated to bring it to your attention.

The second choice is specifying an obstruction in one or both directions (sunrise_obstruction and/or sunset_obstruction). For each used, the horizontal distance to the obstruction (distance), and the height of the top of the obstruction, relative to the observer (relative_height), must be specified. Note that the relative height can be negative (e.g., the observer is on an even taller mountain.) If only one is used, then the observer's elevation above ground level (above_ground) must also be specified (for the other direction.)

Here are some examples:

observer_elevation: 5

observer_elevation:
  sunrise_obstruction: {distance: 10000, relative_height: 2000}
  sunset_obstruction: {distance: 5000, relative_height: -100}

observer_elevation:
  above_ground: 0
  sunrise_obstruction: {distance: 10000, relative_height: 2000}

Note that this replaces the elevation option used in previous versions.

Binary Sensor Configurations

A list of one or more of the following.

elevation

'on' when sun's elevation is above threshold, 'off' when at or below threshold.

For example, this:

- unique_id: bs1
  elevation: horizon

Would be equivalent to:

- unique_id: bs1
  elevation: -0.833
  name: Above horizon

Sensor Configurations

A list of one or more of the following.

Time at Elevation Sensor

For example, this:

- unique_id: s1
  time_at_elevation: -0.833

Would be equivalent to:

- unique_id: s1
  time_at_elevation: -0.833
  direction: rising
  icon: mdi:weather-sunny
  name: Rising at minus 0.833 °

Elevation at Time Sensor

When using an input_datetime entity it must have the time component. The date component is optional. If the date is not present, the result will be the sun's elevation at the given time on the current date. If the date is present, it will be used and the result will be the sun's elevation at the given time on the given date. Also in this case, the sensor entity will not have yesterday, today and tomorrow attributes.

Aditional Sensors

Besides the sensors described above, the following will also be created automatically. Simply enable or disable these entities as desired.

Point in Time Sensors

Some of these will be enabled by default. The rest will be disabled by default.

Length of Time Sensors (in hours)

These are all disabled by default.

Other Sensors

These are also all disabled by default.

Sun Phase Sensor

Possible states

Attributes

Example Full Configuration

sun2:
  - unique_id: home
    binary_sensors:
      - unique_id: bs1
        elevation: horizon
      - unique_id: bs2
        elevation: 3
      - unique_id: bs3
        elevation: -6
        name: Above Civil Dawn
    sensors:
      - unique_id: s1
        time_at_elevation: 10
      - unique_id: s2
        time_at_elevation: -10
        direction: setting
        icon: mdi:weather-sunset-down
        name: Setting past 10 deg below horizon
      - unique_id: s3
        elevation_at_time: '12:00'
        name: Elv @ noon
      - unique_id: s4
        elevation_at_time: input_datetime.test
        name: Elv @ test var

  - unique_id: london
    location: London
    latitude: 51.50739529645933
    longitude: -0.12767666584664272
    time_zone: Europe/London
    elevation: 0
    binary_sensors:
      - unique_id: bs1
        elevation
      - unique_id: bs2
        elevation: 3
      - unique_id: bs3
        elevation: -6
        name: Above Civil Dawn
    sensors:
      - unique_id: s1
        time_at_elevation: 10
      - unique_id: s2
        time_at_elevation: -10
        direction: setting
        icon: mdi:weather-sunset-down
        name: Setting past 10 deg below horizon
      - unique_id: s3
        elevation_at_time: '12:00'
        name: Elv @ noon
      - unique_id: s4
        elevation_at_time: input_datetime.test
        name: Elv @ test var

All "simple" sensor options (e.g., dawn, daylight, etc.) will be created automatically. Some will be enabled by default, but most will not. Simply go to the Settings -> Devices & services page, click on Sun2, then entities, and enable/disable the entities as desired.