core Misconception concerning "elevation" between Home Assistant configuration and the sun integration

The problem

I think there is currently a major misconception concerning the term "elevation" in Home Assistant:

In the Home Asisstant core configuration the parameter "elevation" is defined as "Altitude above sea level in meters. Impacts sunrise data.": https://www.home-assistant.io/integrations/homeassistant/#elevation
This value is used by the sun integration to configure the Observer data from the Astral package https://github.com/home-assistant/core/blob/1f7cc5f5ece588d7d8d1b57e85b3b76e2d9333c1/homeassistant/helpers/sun.py#L40
However in the Astral package, the term "elevation" in the way used by Home Assistant is described as "A float that is the elevation in metres above a location, if the nearest obscuring feature is the horizon": https://astral.readthedocs.io/en/latest/package.html#astral.Observer

So in Home Assistant "elevation" is the elevation above sea level, while in the Astral package it is the elevation above ground level. However, the sun integration uses them as if they were the same which results in wrong calculated sun data.

What version of Home Assistant Core has the issue?

core-2024.10.2

What was the last working version of Home Assistant Core?

No response

What type of installation are you running?

Home Assistant Supervised

Integration causing the issue

sun

Link to integration documentation on our website

https://www.home-assistant.io/integrations/sun

Diagnostics information

No response

Example YAML snippet

No response

Anything in the logs that might be useful for us?

No response

Additional information

No response

Oct 14 '24 12:10 Triple-S

Hey there @home-assistant/core, mind taking a look at this issue as it has been labeled with an integration (homeassistant) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of homeassistant can trigger bot actions by commenting:

@home-assistant close Closes the issue.
@home-assistant rename Awesome new title Renames the issue.
@home-assistant reopen Reopen the issue.
@home-assistant unassign homeassistant Removes the current integration label and assignees on the issue, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the issue.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the issue.

_{^{(message by CodeOwnersMention)}}

homeassistant documentation homeassistant source _{^{(message by IssueLinks)}}

Oct 14 '24 12:10 home-assistant[bot]

Hey there @swamp-ig, mind taking a look at this issue as it has been labeled with an integration (sun) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of sun can trigger bot actions by commenting:

@home-assistant close Closes the issue.
@home-assistant rename Awesome new title Renames the issue.
@home-assistant reopen Reopen the issue.
@home-assistant unassign sun Removes the current integration label and assignees on the issue, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the issue.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the issue.

_{^{(message by CodeOwnersMention)}}

sun documentation sun source _{^{(message by IssueLinks)}}

Oct 14 '24 12:10 home-assistant[bot]

@Triple-S Actual the Elevation calculated by the Sun integration is an angle above the horizon. Just like Azimuth is the angle from the North direction.

https://github.com/home-assistant/core/blob/c460e1bbbef67392a877007ef4d19570b883d435/homeassistant/components/sun/strings.json#L27-L28

They show up on the Sun service page:

(It's in German as we currently have a bug that the entity names don't follow the user's language but the system language instead)

I have just submitted this bug https://github.com/home-assistant/frontend/issues/22508 to address this from the other end and better explain the Elevation setting in Settings > General.

Oct 24 '24 07:10 NoRi2909

@NoRi2909 This is yet another elevation than the ones I am talking about:

In the sun integration the corresponding variable has the name "solar_elevation" and its unit is degree: https://github.com/home-assistant/core/blob/1f7cc5f5ece588d7d8d1b57e85b3b76e2d9333c1/homeassistant/components/sun/entity.py#L115

The elevation I am taking about is the one which has also the variable name "elevation": https://github.com/home-assistant/core/blob/1f7cc5f5ece588d7d8d1b57e85b3b76e2d9333c1/homeassistant/components/sun/entity.py#L108

This variable is not exposed to the user, but is internally used by the astral package to perform the calculations. The issue I see is that the astral package according to its documentation expects an "elevation above ground", however Homeassistant passes the "elevation above sea level" which would result in wrong calculations by the astral package.

Oct 24 '24 07:10 Triple-S

For the German localization I just took your bug report and changed this to "Höhe über NN" to clarify this:

Screenshot 2024-10-24 09 26 52

It is referenced as a common term from several integrations like Starlink, OpenUV, Met etc. so this has some effect beyond the core setup. So this fixes it for German speakers, at least. 😄

Oct 24 '24 07:10 NoRi2909

Thank you @NoRi2909 but renaming will not change anything. I understand that the elevation defined in the Homeassistant configuration is the "height above sea level" or "Höhe über NN" in German and this is part of the issue:

The astral package uses the term elevation in yet a third way: Neighter as "height above sea level" nor as "angle between sun and horizon": In its documentation (https://astral.readthedocs.io/en/latest/package.html#astral.Observer) this third way of using elevation is described as "A float that is the elevation in metres above a location, if the nearest obscuring feature is the horizon". It makes sense that this is NOT the "height above sea level" because the earth radius is so much larger that it will always be negligible when it comes to calculating the time the sun passes the horizon. However, what is relevant is in which height the oberver is in comparison to its local horizon: Imagine standing on a tower or a mountain top, you will be able to see further and so the sun appears to rise earlier and set later. In the opposite way sitting in a vally, the mountains block the sun longer, so it appears to riste later and set earlier. This effect is what the astral package compensates for with this elevation parameter. Homeassistant passes the "height above sea level" for this parameter which is simply wrong because in most cases the horizon of an observer will be approximately the same height as the observer, so 0 should be passed as elevation to the astral package and NOT the "height above sea level".

Oct 24 '24 07:10 Triple-S

Understood, thanks @Triple-S for clearing this up. You already helped me figure out a fix for "Elevation" being just "Höhe" till now in German in two places.

Difficult to properly compensate for a home location's elevation above or below the horizon as this may be quite different going from East to South to West. But you are right, the astral package should at least not mess this up.

Oct 24 '24 07:10 NoRi2909

I (as a end-user) am very confused of what I have to enter in „Settings -> System -> General -> Elevation“ to be reflected in my sunrise/set times correctly. Is it:

My current locations level above ground, i.e. if my house is built on a 2 meter hill, I enter 2
The absolute value of my current locations height above sea level
The delta between what the sea level of the location I entered in my HA instance of what I want it to be (e.g. sea level says I am 200 meter above ground, but I am 202, so I enter 2?)
Or (as I am German) do I have to calculate my „Normalnull“ level somehow?! And is this setting a delta towards the „ Normalnull“ of my location (e.g. Normalnull plus 2, so I enter 2), or do I have to enter the absolute „Normalnull“ level of my location? And do I need to take the deprecated definition that is no longer in use since 1992 (which Wikipedia quotes is a synonym to sealevel somehow?!) or the newer „NHN“ definition?!

I don‘t know why I needed to learn about „Normalnull“ now… why isn‘t it just called sea level?! So if I enter the absolute height above sea level of my location will I be fine? Is it at all bound to the location of my HA instance?

Sorry for making this more complicated than it may actually is, but as an end-user the different descriptions yield a lot of confusion.

Dec 28 '24 19:12 kristian

@kristian The field you are talking about was named just "Elevation" until November 20 when we changed that to "Elevation above sea level" after I personally created PR 22919 for this issue. This should already answer all your questions today.

Regarding the German translation this was called just "Höhe" ("height") till October when I changed this to "Höhe über NN" in advance of the above PR to clarify that field. Thanks to pointing out that "NN" is no longer the correct reference point in German, and we should use "NHN" instead. The difference between these two reference points, however, is just 12 to 15 centimeters.

So I really don't understand how this matters in regards to the discussion here and your problem of figuring out the correct value for the elevation of your home. The difference between the ground floor and first floor is already more than 20 times higher than that difference between "NN" and "NHN".

I will change the German translation to "Höhe über Meeresspiegel" to avoid any further confusion about "NHN".

Dec 28 '24 19:12 NoRi2909

@NoRi2909 thanks for the quick answer 👍. It all made sense, after I read into it (here in this thread, but also on Wikipedia). I tried to deliberately write about my confusion to bring my point across. So it is not about "NN" vs. "NHN" vs. "sea level", the sole point of my confusion was, that I needed to first read up about "NN" and "NHN" and "sea level" on Wikipedia, as I was not into the topic at all. Most articles then went into detail of when "NN" was defined, how it was differently defined in that there are reference points etc. etc., however that essentially all values are more or less "the same" (at least when it comes to as you say, the use-cases in home assistant), took quite a bunch of reading to understand!... I had never heard about "NN" or "NHN" before, so I started to Google "determine NN for my current location" which started to lead me down that rabbit hole!

Thanks for clearing things up and I think renaming it to "Höhe über Meeresspiegel" makes it as clear as it gets! 👍 Thanks!

Dec 28 '24 20:12 kristian

There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved with the latest updates. Please make sure to update to the latest Home Assistant version and check if that solves the issue. Let us know if that works for you by adding a comment 👍 This issue has now been marked as stale and will be closed if no further activity occurs. Thank you for your contributions.

Mar 28 '25 23:03 issue-triage-workflows[bot]