keybuk/homebridge-sun-position

Homebridge plugin to expose the position of the sun for automation

homebridge-sun-position

This is a plugin for Homebridge to create a HomeKit accessory representing the position of the sun in the sky.

The intended use is with automation rules when combined with accessories such as window coverings, to adjust their position based on the true position of the sun.

You can download it from npm.

Installation

1. Install and setup Homebridge.

2. Install this plugin:

npm install -g homebridge-sun-position

3. Add a SunPosition accessory to your Homebridge config.json, providing the latitude and longitude of your location:

    "accessories" : [
        {   
            "accessory" : "SunPosition",
            "name" : "Sun",
            "location" : {
            	"lat" : 37.2343,
            	"long" : -115.8067
            }
        }
    ]

Screenshots

A single "Sun" accessory is added to your home, represented as a Light Sensor; the lux values are somewhat arbitrary and are based on the current phase of the day. HomeKit requires a recognized service for automation, and this seemed like the closest thing.

To use the Altitude and Azimuth characteristics, you will need an app such as Matthias Hochgatterer's Home - Smart Home Automation app. Using this app you can see the current position of the sun, and create automations based on it:

Usage

To use this plugin you need to be reasonably comfortable with HomeKit automation, and understand the differences between Triggers and Conditions, and their limitations.

As of iOS 11.3, Threshold Range Event triggers do not seem to work with custom characteristics. Fortunately you can still check for Any Change, and combine that with conditions to verify the range.

If your HomeKit Automation app does not allow you to set two different conditions for the same characteristic, simply create two Sun accessories (Sun A and Sun B) in your config.json.

In addition, a trigger's End Event only seems to support Time Events, and not full characteristics as documented. You will need a second automation to "undo" the first, use a dummy switch such as from homebridge-dummy to track the state.

Here is an example of rules to close window blinds when the sun shines through a South-facing window, and open them again once it passes:

Close Blinds

Triggers:
Sun Azimuth Any Change

Conditions:
Sun Azimuth ≥ 115.0°
Sun Azimuth < 235.0°

Actions:
Set Scene blinds down
Set Dummy Switch on

Open Blinds

Triggers:
Sun Azimuth Any Change

Conditions:
Sun Azimuth ≥ 235.0°
Dummy Switch = on

Actions:
Set Scene blinds up
Set Dummy Switch off

More advanced rules can be created by combing the azimuth and altitude of the sun, and by combing weather information such as from homebridge-weather-extended.

He is an example for west-facing blinds that, only on a sunny day, come down in two phases based on the altitude of the sun, and go back up again once it's behind the houses or hills.

Half-close Blinds

Triggers:
Sun Azimuth Any Change

Conditions:
Weather Condition Category = 0
Sun Azimuth ≥ 220.0°
Sun Altitude ≤ 50.0°
Sun Altitude > 30.0°

Actions:
Set Scene blinds half down
Set Dummy Switch on

Fully-close Blinds

Triggers:
Sun Azimuth Any Change

Conditions:
Weather Condition Category = 0
Sun Azimuth ≥ 220.0°
Sun Altitude ≤ 30.0°
Sun Altitude > 10.0°

Actions:
Set Scene blinds fully down
Set Dummy Switch on

Open Blinds at Sunset

Triggers:
Sun Azimuth Any Change

Conditions:
Sun Azimuth ≥ 220.0°
Sun Altitude ≤ 10.0°
Dummy Switch = on

Actions:
Set Scene blinds up
Set Dummy Switch off

Open Blinds when Cloudy

Triggers:
Weather Condition Category Any Change

Conditions:
Weather Condition Category > 0
Dummy Switch = on

Actions:
Set Scene blinds up
Set Dummy Switch off