Creates a sensor
entity that estimates outdoor illuminance based on either sun elevation or time of day.
In either case, the value is adjusted based on current weather conditions obtained from another, existing entity.
Two modes are available: normal & simple. The desired mode is selected via the configuration.
This mode uses an algorithm from the US Naval Observatory1 for estimating sun illuminance based on the sun's elevation (aka altitude.) The maximum value is about 150,000 lx. Below is an example of what that might look like over a three day period.
At night the value is 10 lx. From a little before sunrise to a little after the value is ramped up to whatever the current conditions indicate. The same happens around sunset, except the value is ramped down. The maximum value is 10,000 lx. Below is an example of what that might look like over a three day period.
Any weather entity that uses the standard list of conditions, or that provides a cloud coverage percentage, should work with this integration. The following sources of weather data are known to be supported:
Integration | Notes |
---|---|
AccuWeather | weather |
Buienradar Sensor | Condition sensor |
ecobee | |
Meteorologisk institutt (Met.no) | weather |
OpenWeatherMap | weather ; cloud_coverage & condition sensor |
Follow the installation instructions below. Then add the desired configuration. Here is an example of a typical configuration:
sensor:
- platform: illuminance
# Name of new sensor entity
name: Home Outdoor Illuminance
# Existing entity that provides current weather conditions
entity_id: weather.home
You can use HACS to manage the installation and provide update notifications.
- Add this repo as a custom repository:
https://github.com/pnbruckner/ha-illuminance
- Install the integration using the appropriate button on the HACS Integrations page. Search for "illuminance".
Place a copy of:
__init__.py
at <config>/custom_components/illuminance/__init__.py
sensor.py
at <config>/custom_components/illuminance/sensor.py
manifest.json
at <config>/custom_components/illuminance/manifest.json
where <config>
is your Home Assistant configuration directory.
NOTE: Do not download the file by using the link above directly. Rather, click on it, then on the page that comes up use the
Raw
button.
This custom integration supports HomeAssistant versions 2021.12 or newer, using Python 3.9 or newer.
- entity_id: Entity ID of another entity that indicates current weather conditions.
- mode (Optional): Mode of operation. Choices are
normal
(default) which uses sun elevation, andsimple
which uses time of day. - name (Optional): Name of the sensor. Default is
Illuminance
. - scan_interval (Optional): Update interval. Minimum is 5 minutes. Default is 5 minutes.
- fallback (Optional): Illuminance divisor to use when weather data is not available. Must be in the range of 1 (clear) through 10 (dark.) Default is 10.
See https://github.com/pnbruckner/homeassistant-config/blob/master/docs/illuminance.md.
Footnotes
-
Janiczek, P. M., and DeYoung, J. A. Computer Programs for Sun and Moon Illuminance With Contingent Tables and Diagrams. Circular No. 171. Washington, D. C.: United States Naval Observatory, 1987 Google Scholar ↩