homebridge-sun-facade

A Homebridge platform plugin that exposes one HomeKit contact sensor per facade. A sensor reports open while the sun illuminates that facade — determined purely from your location and the time of day (azimuth range + minimum altitude). An optional season gate keeps every facade closed outside the warm months. No network, no weather service, no API key.

Use the sensors as triggers in the iOS Home app: map each facade sensor to a scene or shutter automation yourself. Whether it is actually worth shading right now — cloud cover, outdoor temperature — is deliberately left to a separate sensor; the companion plugin homebridge-metar-cloud provides exactly that (see Combining with cloud cover).

Installation

Requires Homebridge (1.8 or 2.x) running on Node.js 18 or newer.

Homebridge Config UI X (recommended)

In the Plugins tab, search for Sun Facade (homebridge-sun-facade), click Install, then fill in the settings form (see Configuration).

Command line

sudo npm install -g homebridge-sun-facade
sudo hb-service restart

From source (latest / unreleased build)

git clone https://github.com/cduvenhorst/homebridge-sun-facade.git
cd homebridge-sun-facade
npm install          # compiles dist/ via the prepare hook
sudo npm install -g .
sudo hb-service restart

After installation, add the SunFacade platform to your Homebridge config and restart.

Configuration

| Field | Meaning | | --- | --- | | latitude / longitude | Your location in decimal degrees. In Google Maps a place's coordinates appear as latitude, longitude (in that order). Latitude is −90…90 (positive = north); longitude is −180…180 (positive = east). | | updateIntervalSeconds | Evaluation interval (default 60). | | updateMode | onChange (default) writes only on state change; always writes every tick. | | noonAltitudeMin | Optional season gate: facades are only active on days when the sun reaches at least this altitude at solar noon. Leave out to disable. | | facades[] | name, azimuthMin, azimuthMax (0=N, 90=E, 180=S, 270=W; may overlap and wrap across 0/360), altitudeMin (degrees above horizon, default 0). |

Example

{
  "platform": "SunFacade",
  "latitude": 52.37,
  "longitude": 9.74,
  "updateIntervalSeconds": 60,
  "updateMode": "onChange",
  "noonAltitudeMin": 45,
  "facades": [
    { "name": "East", "azimuthMin": 60, "azimuthMax": 135, "altitudeMin": 10 },
    { "name": "South", "azimuthMin": 135, "azimuthMax": 225, "altitudeMin": 5 }
  ]
}

Overlapping ranges mean several sensors are open at once (e.g. around noon both East and South). Wire East/South to your shading scenes in the Home app.

Shading season

You usually want shading only in the warm months and the low winter sun for warmth. Rather than picking calendar dates, set a minimum noon altitude: on any day the sun does not climb that high at solar noon, every facade stays closed. The threshold depends on the date and your latitude only, so it adapts to wherever you live and leaves altitudeMin free to control the time of day.

"noonAltitudeMin": 45

Reference for Hannover (52 N): the noon sun reaches about 14° in mid-winter, 38° at the equinox and 61° in mid-summer, so 45 covers roughly late April to late August.

Wrap-around ranges

When azimuthMin > azimuthMax the range wraps across the 0°/360° boundary, which is useful for north-facing facades:

{ "name": "North", "azimuthMin": 315, "azimuthMax": 45, "altitudeMin": 0 }

This matches azimuths from 315° (NW) through 0° (N) to 45° (NE).

Worldwide use

Sun position is computed for any location and date, in both hemispheres — no time-zone setting is needed (the plugin works from your coordinates and the current time). Azimuth is always measured clockwise from true north (0°=N, 90°=E, 180°=S, 270°=W), so the configuration is identical everywhere; only the ranges you choose differ. Note that in the southern hemisphere the midday sun stands in the north, so a sun-facing facade there uses a range around 0°/360° — e.g. a sun-facing (north) window: azimuthMin: 315, azimuthMax: 45.

Combining with cloud cover

This plugin only answers where the sun is. Whether shading is worth it right now is a different question — on an overcast day, or on a clear but cool spring morning, you want the sun in. homebridge-metar-cloud answers that with a single occupancy sensor that reads detected when it is cloudy or too cool, from free airport weather data.

Put the two together in one automation:

When the facade sensor opens (the sun reaches that wall) and the METAR Cloud sensor is not detected (clear and warm enough) then run the shading scene for that facade.

The two plugins are kept separate on purpose: sun position is pure geometry and never needs the network, while cloud cover is a weather observation. Each stays simple, and you can use either one on its own.

Note that the native Home app only supports a second sensor as a condition to a limited degree. For a reliable "and" across two sensors, build the automation in the Eve app or as a Shortcuts automation.

How it works

Every updateIntervalSeconds the plugin computes the sun's compass azimuth and altitude for your coordinates and the current time (using the suncalc library — no network). A facade's contact sensor is open when all of the following hold:

• the azimuth lies within the facade's azimuthMin…azimuthMax range (wrapping across 0°/360° if azimuthMin > azimuthMax),
• the altitude is at or above the facade's altitudeMin, and
• if noonAltitudeMin is set, today's noon altitude reaches it (the season gate).

Otherwise the sensor is closed. In HomeKit terms, open is CONTACT_NOT_DETECTED and closed is CONTACT_DETECTED. With updateMode: "onChange" (the default) a sensor is only written when its state actually changes; "always" rewrites it every tick.

There is no hysteresis and none is needed: the sun's path is smooth and monotonic, so each threshold is crossed once on the way in and once on the way out — nothing to flap.