{"id":13585981,"url":"https://github.com/pnbruckner/ha-sun2","last_synced_at":"2025-12-26T17:14:33.725Z","repository":{"id":37077083,"uuid":"192782243","full_name":"pnbruckner/ha-sun2","owner":"pnbruckner","description":"Home Assistant Sun2 Sensor","archived":false,"fork":false,"pushed_at":"2025-12-18T15:30:46.000Z","size":527,"stargazers_count":283,"open_issues_count":5,"forks_count":23,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-12-18T21:27:01.677Z","etag":null,"topics":["home-assistant","home-automation","homeassistant-custom-component","homeassistant-sensor","sun"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pnbruckner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-06-19T18:10:54.000Z","updated_at":"2025-12-17T14:35:07.000Z","dependencies_parsed_at":"2023-10-25T22:34:49.303Z","dependency_job_id":"8f3d5840-8cc3-499e-a53d-e5d5aebd791d","html_url":"https://github.com/pnbruckner/ha-sun2","commit_stats":null,"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"purl":"pkg:github/pnbruckner/ha-sun2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnbruckner%2Fha-sun2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnbruckner%2Fha-sun2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnbruckner%2Fha-sun2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnbruckner%2Fha-sun2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pnbruckner","download_url":"https://codeload.github.com/pnbruckner/ha-sun2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnbruckner%2Fha-sun2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28057282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-26T02:00:06.189Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-assistant","home-automation","homeassistant-custom-component","homeassistant-sensor","sun"],"created_at":"2024-08-01T15:05:15.364Z","updated_at":"2025-12-26T17:14:33.711Z","avatar_url":"https://github.com/pnbruckner.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# \u003cimg src=\"https://brands.home-assistant.io/sun2/icon.png\" alt=\"Sun2 Sensor\" width=\"50\" height=\"50\"/\u003e Sun2 Sensor\n\nCreates sensors that provide information about various sun related events.\n\nFollow the installation instructions below.\nThen add one or more locations with desired sensors either via YAML, the UI or both.\n\n## Installation\n\n\u003cdetails\u003e\n\u003csummary\u003eWith HACS\u003c/summary\u003e\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://hacs.xyz/)\n\nYou can use HACS to manage the installation and provide update notifications.\n\n1. Add this repo as a [custom repository](https://hacs.xyz/docs/faq/custom_repositories/).\n   It should then appear as a new integration. Click on it. If necessary, search for \"sun2\".\n\n   ```text\n   https://github.com/pnbruckner/ha-sun2\n   ```\n   Or use this button:\n   \n   [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=pnbruckner\u0026repository=ha-sun2\u0026category=integration)\n\n\n1. Download the integration using the appropriate button.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eManual\u003c/summary\u003e\n\nPlace a copy of the files from [`custom_components/sun2`](custom_components/sun2)\nin `\u003cconfig\u003e/custom_components/sun2`,\nwhere `\u003cconfig\u003e` is your Home Assistant configuration directory.\n\n\u003e__NOTE__: When downloading, make sure to use the `Raw` button from each file's page.\n\n\u003c/details\u003e\n\nAfter it has been downloaded you will need to restart Home Assistant.\n\n### Versions\n\nThis custom integration supports HomeAssistant versions 2024.8.3 or newer.\n\n## Services\n\n### `sun2.reload`\n\nReloads Sun2 from the YAML-configuration. Also adds `SUN2` to the Developers Tools -\u003e YAML page.\n\n### `sun2.get_location`\n\nResponds with the current location configuration options (latitude, etc.) of the specified location.\nTakes just one parameter, `location`, which is the name of the location, and is also the name of the corresponding integration entry.\n\n### `sun2.update_location`\n\nUpdates one or more parts of the location configuration options of the specified location.\nTakes one required parameter, `location`. (Same as `sun2.get_location` service.)\nCan also take location parameters (`latitude`, `longitude` \u0026 `time_zone`), which if any are specified, they must all be specified.\nCan also take observer elevation parameters (`observer_elevation`).\nThese parameters are the same as specified below in the YAML configuration section.\n\n## Configuration\n\nOne or more \"locations\" can be added for this integration.\nEach location is defined by a set of parameters (latitude, etc.)\nSensors will be created for each location that provide sun related data for that location.\nA location can be added either via the UI or YAML.\n\nTo add a location via the UI, you can use this My Button:\n\n[![add integration](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start?domain=sun2)\n\nAlternatively, go to Settings -\u003e Devices \u0026 services and click the **`+ ADD INTEGRATION`** button.\nFind or search for \"sun2\", click on it, then follow the prompts.\n\nThe remainder of this section defines the list of YAML configuration options for each location.\n\nKey | Optional | Description\n-|-|-\n`unique_id` | no | Unique identifier for location. This allows any of the remaining options to be changed without looking like a new location.\n`location` | yes* | Name of location\n`latitude` | yes* | The location's latitude (in degrees)\n`longitude` | yes* | The location's longitude (in degrees)\n`time_zone` | yes* | The location's time zone. (See the \"TZ database name\" column at http://en.wikipedia.org/wiki/List_of_tz_database_time_zones.)\n`observer_elevation` | yes | What affects sunrise \u0026 sunset as defined [here](#observer-elevation)\n`binary_sensors` | yes | Binary sensor configurations as defined [here](#binary-sensor-configurations)\n`sensors` | yes | Sensor configurations as defined [here](#sensor-configurations)\n\n\\* These must all be used together. If not used, the default is Home Assistant's location, time zone \u0026 name configuration.\n\n### Observer Elevation\n\nThe easterly sun events (sunrise, dawn, etc.) and westerly sun events (sunset, dusk, etc.)\ncan be viewed at either the horizon, or at the top of some obstruction, such as a mountain.\n(For more details, see [Effect of Elevation](https://sffjunkie.github.io/astral/#effect-of-elevation).)\nThis configuration option describes which apply at the specified location.\n\nThere are two basic choices. The first is that the sun events are seen at the horizon in both directions.\nIn this case, a simple number may be given which defines the observer's elevation above _ground_ level (not sea level) in meters.\nIf this option is not specified, then the elevation from the system's general configuration will be used.\n\n\u003e NOTE: [Settings -\u003e System -\u003e General -\u003e Elevation](https://www.home-assistant.io/integrations/homeassistant/) is defined as \"Altitude above **sea** level in meters. Impacts sunrise data.\"\n\u003e \n\u003e This is, and always has been, defined incorrectly.\n\u003e It should be defined as altitude above _ground_ level, not sea level.\n\u003e Therefore, if the optional `observer_elevation` is not specified, and your system's general elevation contains your home's altitude above _sea_ level,\n\u003e then this integration will get the _wrong_ elevation value, resulting in incorrect sensor values.\n\u003e This situation should be avoided.\n\u003e Therefore, if it occurs, a WARNING will be generated to bring it to your attention.\n\nThe second choice is specifying an obstruction in one or both directions (`sunrise_obstruction` and/or `sunset_obstruction`).\nFor each used, the horizontal distance to the obstruction (`distance`),\nand the height of the top of the obstruction, relative to the observer (`relative_height`), must be specified.\nNote that the relative height can be negative (e.g., the observer is on an even taller mountain.)\nIf only one is used, then the observer's elevation above ground level (`above_ground`) must also be specified (for the other direction.)\n\nHere are some examples:\n\n```yaml\nobserver_elevation: 5\n\nobserver_elevation:\n  sunrise_obstruction: {distance: 10000, relative_height: 2000}\n  sunset_obstruction: {distance: 5000, relative_height: -100}\n\nobserver_elevation:\n  above_ground: 0\n  sunrise_obstruction: {distance: 10000, relative_height: 2000}\n```\n\n\u003e Note that this replaces the `elevation` option used in previous versions.\n\n### Binary Sensor Configurations\n\nA list of one or more of the following.\n\n#### `elevation`\n\n`'on'` when sun's elevation is above threshold, `'off'` when at or below threshold.\n\nKey | Optional | Description\n-|-|-\n`unique_id` | no | Unique identifier for entity. Must be unique within set of binary sensors for location. This allows any of the remaining options to be changed without looking like a new entity.\n`elevation` | no | Elevation threshold (in degrees) or `horizon`\n`name` | yes | Entity friendly name\n\nFor example, this:\n\n```yaml\n- unique_id: bs1\n  elevation: horizon\n```\n\nWould be equivalent to:\n\n```yaml\n- unique_id: bs1\n  elevation: -0.833\n  name: Above horizon\n```\n\n### Sensor Configurations\n\nA list of one or more of the following.\n\n#### Time at Elevation Sensor\n\nKey | Optional | Description\n-|-|-\n`unique_id` | no | Unique identifier for entity. Must be unique within set of sensors for location. This allows any of the remaining options to be changed without looking like a new entity.\n`time_at_elevation` | no | Elevation (in degrees)\n`direction` | yes | `rising` (default) or `setting`\n`icon` | yes | Default is `mdi:weather-sunny`\n`name` | yes | Entity friendly name\n\nFor example, this:\n\n```yaml\n- unique_id: s1\n  time_at_elevation: -0.833\n```\n\nWould be equivalent to:\n\n```yaml\n- unique_id: s1\n  time_at_elevation: -0.833\n  direction: rising\n  icon: mdi:weather-sunny\n  name: Rising at minus 0.833 °\n```\n\n#### Elevation at Time Sensor\n\nKey | Optional | Description\n-|-|-\n`unique_id` | no | Unique identifier for entity. Must be unique within set of sensors for location. This allows any of the remaining options to be changed without looking like a new entity.\n`elevation_at_time` | no | Time string or `input_datetime` entity ID\n`name` | yes | Entity friendly name\n\nWhen using an `input_datetime` entity it must have the time component. The date component is optional.\nIf the date is not present, the result will be the sun's elevation at the given time on the current date.\nIf 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.\nAlso in this case, the `sensor` entity will not have `yesterday`, `today` and `tomorrow` attributes.\n\n## Aditional Sensors\n\nBesides the sensors described above, the following will also be created automatically. Simply enable or disable these entities as desired.\n\n### Point in Time Sensors\n\nSome of these will be enabled by default. The rest will be disabled by default.\n\nType | Enabled | Description\n-|-|-\nSolar Midnight | yes | The time when the sun is at its lowest point closest to 00:00:00 of the specified date; i.e. it may be a time that is on the previous day.\nAstronomical Dawn | no | The time in the morning when the sun is 18 degrees below the horizon\nNautical Dawn | no | The time in the morning when the sun is 12 degrees below the horizon\nDawn | yes | The time in the morning when the sun is 6 degrees below the horizon\nRising | yes | AKA Sunrise. The time in the morning when the sun is 0.833 degrees below the horizon. This is to account for refraction.\nSolar Noon | yes | The time when the sun is at its highest point\nSetting | yes | AKA Sunset. The time in the evening when the sun is 0.833 degrees below the horizon. This is to account for refraction.\nDusk | yes | The time in the evening when the sun is a 6 degrees below the horizon\nNautical Dusk | no | The time in the evening when the sun is a 12 degrees below the horizon\nAstronomical Dusk | no | The time in the evening when the sun is a 18 degrees below the horizon\n\n### Length of Time Sensors (in hours)\n\nThese are all disabled by default.\n\nType | Description\n-|-\nDaylight | The amount of time between sunrise and sunset\nCivil Daylight | The amount of time between dawn and dusk\nNautical Daylight | The amount of time between nautical dawn and nautical dusk\nAstronomical Daylight | The amount of time between astronomical dawn and astronomical dusk\nNight | The amount of time between sunset and sunrise of the next day\nCivil Night | The amount of time between dusk and dawn of the next day\nNautical Night | The amount of time between nautical dusk and nautical dawn of the next day\nAstronomical Night | The amount of time between astronomical dusk and astronomical dawn of the next day\n\n### Other Sensors\n\nThese are also all disabled by default.\n\nType | Description\n-|-\nAzimuth | The sun's azimuth (degrees)\nRising Azimuth | The sun's azimuth at sunrise (degrees)\nSetting Azimuth | The sun's azimuth at sunset (degrees)\nElevation | The sun's elevation (degrees)\nMinimum Elevation | The sun's elevation at solar midnight (degrees)\nmaximum Elevation | The sun's elevation at solar noon (degrees)\ndeCONZ Daylight | Emulation of [deCONZ Daylight Sensor](https://www.home-assistant.io/integrations/deconz/#deconz-daylight-sensor)\nPhase | See [Sun Phase Sensor](#sun-phase-sensor)\n\n##### Sun Phase Sensor\n\n###### Possible states\n\nState | Description\n-|-\nNight | Sun is below -18°\nAstronomical Twilight | Sun is between -18° and -12°\nNautical Twilight | Sun is between -12° and -6°\nCivil Twilight | Sun is between -6° and -0.833°\nDay | Sun is above -0.833°\n\n###### Attributes\n\nAttribute | Description\n-|-\n`rising` | `True` if sun is rising\n`blue_hour` | `True` if sun is between -6° and -4°\n`golden_hour` | `True` if sun is between -4° and 6°\n\n## Example Full Configuration\n\n```yaml\nsun2:\n  - unique_id: home\n    binary_sensors:\n      - unique_id: bs1\n        elevation: horizon\n      - unique_id: bs2\n        elevation: 3\n      - unique_id: bs3\n        elevation: -6\n        name: Above Civil Dawn\n    sensors:\n      - unique_id: s1\n        time_at_elevation: 10\n      - unique_id: s2\n        time_at_elevation: -10\n        direction: setting\n        icon: mdi:weather-sunset-down\n        name: Setting past 10 deg below horizon\n      - unique_id: s3\n        elevation_at_time: '12:00'\n        name: Elv @ noon\n      - unique_id: s4\n        elevation_at_time: input_datetime.test\n        name: Elv @ test var\n\n  - unique_id: london\n    location: London\n    latitude: 51.50739529645933\n    longitude: -0.12767666584664272\n    time_zone: Europe/London\n    elevation: 0\n    binary_sensors:\n      - unique_id: bs1\n        elevation: horizon\n      - unique_id: bs2\n        elevation: 3\n      - unique_id: bs3\n        elevation: -6\n        name: Above Civil Dawn\n    sensors:\n      - unique_id: s1\n        time_at_elevation: 10\n      - unique_id: s2\n        time_at_elevation: -10\n        direction: setting\n        icon: mdi:weather-sunset-down\n        name: Setting past 10 deg below horizon\n      - unique_id: s3\n        elevation_at_time: '12:00'\n        name: Elv @ noon\n      - unique_id: s4\n        elevation_at_time: input_datetime.test\n        name: Elv @ test var\n```\n\nAll \"simple\" sensor options (e.g., `dawn`, `daylight`, etc.) will be created automatically.\nSome will be enabled by default, but most will not.\nSimply go to the Settings -\u003e Devices \u0026 services page, click on Sun2, then entities, and enable/disable the entities as desired.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnbruckner%2Fha-sun2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpnbruckner%2Fha-sun2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnbruckner%2Fha-sun2/lists"}