Home Assistant Solar Azimuth Times

Note

This information is actually obsolete, as the Home Assistant system already contains solar azimuth and elevation attributes as part of the sun Entity. I didn’t realize these were already available as a standard part of the Home Assistant installation when I embarked on my Claude-coding escapade, though I have to say I enjoyed the adventure, and am keeping this posted here just for Claude-coding informational purposes. But you don’t need to use the Claude-coded Python module discussed below to have Home Assistant triggers based on solar azimuth – they’re built-in.

Background

I acquired some automated Hunter-Douglas roller shades (dual-lite, with both sheer and blackout shades) for some high south-southeast facing windows in our bedroom, and programmed them using the Hunter-Douglas-supplied app to open and close based on sunrise and sunset times:

Close the sheer shade during the day, to allow light in but block direct sunlight from bleaching our furnishings
Open fully after the sun set so we could see the sky, and keep the shades open through the night
Close the shades an hour before sunrise to keep the sun from waking us up

The Hunter-Douglas software permits automating open and close operations relative to sunrise and sunset times, including fixed times before and after sunrise and sunset, and automatically adjusts the times based on the day of the year as the sunset and sunrise times change. The above setup worked well enough, but I’m picky, and realized that the shades could be fully opened earlier than sunset. Once the sun had gotten to an angle where it was parallel to the wall with the windows, it wouldn’t shine into the room any more, even though it had not yet set. Unfortunately, this isn’t a feature of the Hunter-Douglas software. However, the open-source Home Assistant home-automation system has very broad capabilities, including user-defined functionality, so I decided to try this to control the shades to see if it could support this sun-at-specific-angle use case. The Home Assistant system requires an auxiliary server to operate; I used a Raspberry Pi. I won’t go into detail in how I set this up or how to use Home Assistant in general – there’s tons of info on the project website.

I then turned to researching how I might be able to determine the time at which the sun reached a particular azimuth (angle from north) based on the day of the year. Our windows faced south-southeast at compass orientation 157 degrees (determined with a cellphone compass), so the sun would no longer shine in the window when it reached an azimuth angle of 247 degrees (157 + 90); actually, I determined the orientation angle of the wall to be 247 degrees using the cellphone compass with the cellphone held against the wall, and then subtracted 90 to get the window-facing orientation. But it’s the 247 degrees that we want in the first place.

The time of day when the sun reaches a particular azimuth angle is unfortunately not straightforward to figure out. It depends on your longitude and latitude, and varies throughout the year; and for some locations, in the winter the sun sets before it gets to 247 degrees. Since this involves some tricky spherical geometry, I wasn’t relishing the task (even though I generally like math-based coding). Then I thought, why not have Claude do it? A previous experiment had left me extremely impressed with what Claude could produce with a short amount of prompting.

My first thought was to create a table that gave for my location and each day of the year the time that the sun reached an azimuth of 247 degrees (or sunset time if the sun sets before reaching 247 degrees), and use this table in the Home Assistant automation system to open the shades at the appropriate time. However, in working with Claude to develop this, I noticed that Claude came up with the table using a Python program, and Home Assistant supports execution of user-supplied Python modules, so I skipped the table and went right to the Python routine. The first Python module that Claude provided incorporated a sophisticated astronomical geometry library called ephem that gave precise timings for the azimuth based on longitude, latitude and date. However, Home Assistant limits importation of third-party libraries for security reasons, so it would be a bit awkward to use this code. Claude had mentioned during the development conversation that there was another approximate method that didn’t use the ephem library, so I had it provide this alternate code and used it for the Home Assistant Python module. I eventually modified this to incorporate Home Assistant-specific functionality (the ability to directly use some Home Assistant-specific variable types).

The azimuth time finding Python module is available at the link below.

Python azimuth finder module

Here’s the conversation I had with Claude to get the azimuth table and Python code.

Claude conversation to create the module

Home Assistant Application

Overview

The main functionality is provided by the Python module sun_azimuth_time_finder.py. This provides several Home Assistant services (functions that can be used in automations) that determine various sun azimuth times.

set_entity_to_azimuth_time_or_sunset

Arguments: entity_id, azimuth

Sets the supplied entity to the local time when the sun reaches azimuth on the current date for the latitude and longitude configured in zone.home. If the sun never reaches that azimuth above the horizon, sets the entity to the sunset time.

set_entity_to_azimuth_time_or_sunrise

Arguments: entity_id, azimuth

The following auxiliary service is also provided, though its primary use is in the implementation of the two preceding main services.

set_entity_to_azimuth_time

Arguments: entity_id, azimuth, latitude=None, longitude=None, date=None

Sets the supplied entity to the local time when the sun reaches azimuth on date reference_date. If values not supplied for latitude or longitude, uses those from zone.home. If date not supplied, uses current date. If the sun never reaches that azimuth above the horizon, leaves entity unchanged.

Home Assistant Integration

The following steps are needed to utilize the azimuth module in Home Assistant.

Python module

The azimuth-finder Python module requires the optional Home Assistant PyScript component, available for installation into your Home Assistant system from the Home Assistant Community Store (HACS).

The Python module should then be uploaded to the pyscript directory in the Home Assistant filesystem (create this directory if there isn’t one). Restarting the Home Assistant system will make the services in the module available.

Home Assistant Setup

After the Python module has been installed, the services in it can be used to drive automations using Home Assistant’s built-in functionality. Here’s how I automated my shades to open when the sun passed the windows.

Create an input_datetime Entity (variable) that will hold the opening (or closing) time for the shades – mine is called shade_opening_time
Create an Automation that updates the value of this variable using the Python library; mine is called “Update shade opening time”. When run, this automation calls the function set_entity_to_azimuth_time_or_sunset that’s defined in the Python module. It has two required arguments:
entity_id: the variable to update
azimuth: the desired azimuth value
The picture below shows this automation in the Home Assistant web interface.
Create an automation that opens the shades at the updated time each day (mine is called “Open shades when sun passes”), using the input_datetime Entity shade_opening_time as the trigger and the scene “Main Bedroom Open” as the action. (This scene was previously defined in the Hunter-Douglas app and seamlessly pulled in by Home Assistant when it was installed).

At this point the Home Assistant system should be set to open shades based on the time the sun reaches the specified azimuth. You will of course want to test to make sure it’s actually doing what you want.

Jonathan Sevy