Illuminance Sensor

Creates a sensor entity that estimates outdoor illuminance based on either sun elevation or time of day. In either case, the value can be further adjusted based on current weather conditions or cloud coverage obtained from another, existing entity.

Modes of operation

Three modes are available: normal, irradiance & simple.

Normal/Irradiance modes - Sun elevation

These modes use an algorithm from the US Naval Observatory[^1] for estimating sun illuminance or irradiance based on the sun's elevation (aka altitude.) The maximum illuminance value is about 150,000 lx, and the maximum irradiance value is about 1,250 Watts/M². Below is an example of what the illuminance might look like over a three day period.

[^1]: 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

Simple mode - Time of day

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. For historical reasons, the maximum value is 10,000 lx. Below is an example of what that might look like over a three day period.

Supported weather sources

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 | weather ecobee | Meteorologisk institutt (Met.no) | weather OpenWeatherMap | weather; cloud_coverage & condition sensor

Installation

The integration software must first be installed as a custom component. You can use HACS to manage the installation and provide update notifications. Or you can manually install the software.

With HACS

• Add this repo as a custom repository:

It should then appear as a new integration. Click on it. If necessary, search for "illuminance". ``text https://github.com/pnbruckner/ha-illuminance ` Or use this button:

• Download the integration using the appropriate button.

Manual Installation

Place a copy of the files from custom_components/illuminance in /custom_components/illuminance, where is your Home Assistant configuration directory.

>__NOTE__: When downloading, make sure to use the Raw button from each file's page.

Post Installation

After it has been downloaded you will need to restart Home Assistant.

Versions

This custom integration supports HomeAssistant versions 2024.8.3 or newer.

Services

illuminance.reload

Reloads Illuminance from the YAML-configuration. Also adds ILLUMINANCE to the Developers Tools -> YAML page.

Configuration variables

A list of configuration options for one or more sensors. Each sensor is defined by the following options.

Note: This defines configuration via YAML. However, the same sensors can be added in the UI.

Key | Optional | Description -|-|- unique_id | no | Unique identifier for sensor. This allows any of the remaining options to be changed without looking like a new sensor. (Only required for YAML-based configuration.) entity_id | yes | Entity ID of another entity that indicates current weather conditions or cloud coverage percentage fallback | yes | Illuminance divisor to use when weather data is not available. Must be in the range of 1 (clear) through 10 (dark.) Default is 10 if entity_id is used, or 1 if not. mode | yes | Mode of operation. Choices are normal (default) which uses sun elevation, simple which uses time of day and irradiance which is the same as normal, except the value is expressed as irradiance in Watts/M². name | yes | Name of the sensor. Default is Illuminance. scan_interval` | yes | Update interval. Minimum is 30 seconds. Default is 5 minutes.

Releases Before 2.1.0

See https://github.com/pnbruckner/homeassistant-config/blob/master/docs/illuminance.md.

--- Tranlated By Open Ai Tx | Last indexed: 2025-12-28 ---