The sun

Tell HotLoop where the plant is and it knows where the sun is. Sunrise, sunset, dawn, dusk, solar noon, the sun’s height and its bearing, all worked out on the box from a latitude and a longitude. No weather service, no API key, no internet. A site whose uplink died three weeks ago still turns the yard lights on at dusk, which is the whole reason this isn’t a call to somebody’s cloud.

Setting it up

Two variables, decimal degrees, north and east positive:

Variable	Example	Details
HOTLOOP_SITE_LATITUDE	41.4993	north positive
HOTLOOP_SITE_LONGITUDE	-81.6944	east positive, so everywhere in the Americas is negative

In the chart they’re plant.latitude and plant.longitude. Both or neither. Half a location, a number off the planet, or 41°29'58"N stops HotLoop at startup with the variable named, because a sunrise worked out from a typo is hours wrong and looks perfectly reasonable on a screen. Get the numbers off any map: right click, copy the coordinates.

Leave them out and there are no sun entities, and a rule with a sun trigger isn’t armed (the system log says which two variables to set). The Settings screen shows both, read-only. A sunrise is something rules fire on, so it moves with a reviewed deploy.

The entities

Entity	State	Details
binary_sensor.sun_up	on from sunrise to sunset	attributes next_dawn, next_sunrise, next_noon, next_sunset, next_dusk, in the site’s timezone
sensor.sun_elevation	degrees above the horizon, negative below	whole degrees
sensor.sun_azimuth	degrees clockwise from true north, 90 is east	whole degrees

They’re platform sun, they read, and they take no services. sun_up is worked out exactly, so it flips on the same second the sunrise and sunset triggers fire, not off the rounded elevation.

Elevation and azimuth are whole degrees on purpose. The sun moves about a quarter of a degree a minute. At a tenth of a degree that’s a new state, a logbook row and a history point every 24 seconds, all day, every day, per sensor, for precision nobody automates on. A rule that wants “the sun is more than 10 degrees up” gets it to the degree.

Under the midnight sun or in the polar night, the next sunset or sunrise can be weeks away, and the attribute says when. If there isn’t one within a year it says none within a year instead of being quietly left out.

Triggers

{"type": "sun", "event": "sunset", "offsetSec": -1800}

dawn, sunrise, noon, sunset or dusk, moved by offsetSec (negative is before, at most six hours either way). See AUTOMATIONS.md. binary_sensor.sun_up works with an ordinary state trigger too, and with states['binary_sensor.sun_up'] == 'off' in a condition, for “only after dark”.

What the numbers mean

• Sunrise and sunset are when the top edge of the sun is on the horizon, with the standard allowance for the air bending the light: the center 0.833 degrees below the horizon. That’s what every almanac and every phone means by sunrise.
• Dawn and dusk are civil twilight, the center 6 degrees below. It’s the line outdoor lighting is written around: after civil dusk you need lights to work outside.
• Solar noon is when the sun is due south (due north, south of the equator) and highest. It’s rarely 12:00 on the clock; on the western edge of a timezone in summer it’s well after one.
• Elevation is where the sun looks, corrected for refraction. Azimuth is from true north, not magnetic.

The flat-horizon caveat: these are for a sea-level horizon. A plant in a valley loses the sun behind the ridge before sunset, and HotLoop doesn’t know about the ridge. Put an offset on the trigger.

How we know it’s right

The math is NOAA’s: the equations behind the Global Monitoring Laboratory’s solar calculator (gml.noaa.gov/grad/solcalc), which are Jean Meeus’s Astronomical Algorithms. Ported as they are, the odd bit included (NOAA’s solar noon reads the equation of time around midnight UT rather than at noon, worth seconds, and kept so we match NOAA to the second).

internal/sun/testdata holds the sunrise, sunset and solar noon tables NOAA’s calculator published for 2026 at six places, every cell copied as printed: Cleveland and Austin (both sides of a daylight saving change), London (on the meridian), Sydney (southern hemisphere), Quito (on the equator) and Utqiagvik, north of the Arctic Circle, with two months of polar night and nearly three of midnight sun. The test reads all 4,380 sunrise and sunset cells and holds every crossing to the minute NOAA printed, plus two seconds, and every one of the 2,190 noons to within a second. About 97 percent round to exactly the same minute; the rest are a second or so from a half minute, which is two calculators disagreeing in the last digit, not about the sun. Every day NOAA says has no sunrise or no sunset, HotLoop says the same.

NOAA publishes no twilight table, so dawn and dusk are held to their definition instead: at the moment HotLoop says it’s dusk, the same position math puts the sun’s center 6 degrees down, to a fiftieth of a degree.

NOAA says its method is good to about a minute between the polar circles and gets worse toward the poles, where the sun skims the horizon and a tiny error in its height is minutes on the clock. Utqiagvik passes the same bar as everywhere else. At the poles themselves the day-by-day method can miss the one sunrise of the year; if you’re running a plant at the South Pole, put a schedule on it.