This class includes support for the TSL2591 i2c ambient light sensor. More...

#include <tsl2591.h>

Inheritance diagram for esphome::tsl2591::TSL2591Component:

Public Member Functions
void	set_integration_time_and_gain (TSL2591IntegrationTime integration_time, TSL2591Gain gain)
	Set device integration time and gain. More...

void	set_power_save_mode (bool enable)
	Should the device be powered down between readings? More...

void	set_name (const char *name)
	Sets the name for this instance of the device. More...

void	set_device_and_glass_attenuation_factors (float device_factor, float glass_attenuation_factor)
	Sets the device and glass attenuation factors. More...

float	get_calculated_lux (uint16_t full_spectrum, uint16_t infrared)
	Calculates and returns a lux value based on the ADC readings. More...

uint32_t	get_combined_illuminance ()
	Get the combined illuminance value. More...

uint16_t	get_illuminance (TSL2591SensorChannel channel)
	Get an individual sensor channel reading. More...

uint16_t	get_illuminance (TSL2591SensorChannel channel, uint32_t combined_illuminance)
	Get an individual sensor channel reading from combined illuminance. More...

bool	is_adc_valid ()
	Are the device ADC values valid? More...

void	enable ()
	Powers on the TSL2591 device and enables its sensors. More...

void	disable ()
	Powers off the TSL2591 device. More...

void	automatic_gain_update (uint16_t full_spectrum)
	Updates the gain setting based on the most recent full spectrum reading. More...

float	get_actual_gain ()
	Reads the actual gain used. More...

void	set_full_spectrum_sensor (sensor::Sensor *full_spectrum_sensor)
	Used by ESPHome framework. More...

void	set_actual_gain_sensor (sensor::Sensor *actual_gain_sensor)
	Used by ESPHome framework. More...

void	set_infrared_sensor (sensor::Sensor *infrared_sensor)
	Used by ESPHome framework. More...

void	set_visible_sensor (sensor::Sensor *visible_sensor)
	Used by ESPHome framework. More...

void	set_calculated_lux_sensor (sensor::Sensor *calculated_lux_sensor)
	Used by ESPHome framework. More...

void	set_integration_time (TSL2591IntegrationTime integration_time)
	Used by ESPHome framework. More...

void	set_gain (TSL2591ComponentGain gain)
	Used by ESPHome framework. More...

void	setup () override
	Used by ESPHome framework. More...

void	dump_config () override
	Used by ESPHome framework. More...

void	update () override
	Used by ESPHome framework. More...

float	get_setup_priority () const override
	Used by ESPHome framework. More...

Public Member Functions inherited from esphome::PollingComponent
	PollingComponent ()

	PollingComponent (uint32_t update_interval)
	Initialize this polling component with the given update interval in ms. More...

virtual void	set_update_interval (uint32_t update_interval)
	Manually set the update interval in ms for this polling object. More...

void	call_setup () override

virtual uint32_t	get_update_interval () const
	Get the update interval in ms of this sensor. More...

void	start_poller ()

void	stop_poller ()

Public Member Functions inherited from esphome::Component
virtual void	loop ()
	This method will be called repeatedly. More...

float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

virtual float	get_loop_priority () const
	priority of loop(). More...

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

uint32_t	get_component_state () const

virtual void	mark_failed ()
	Mark this component as failed. More...

bool	is_failed () const

bool	is_ready () const

virtual bool	can_proceed ()

bool	status_has_warning () const

bool	status_has_error () const

void	status_set_warning (const char *message="unspecified")

void	status_set_error (const char *message="unspecified")

void	status_clear_warning ()

void	status_clear_error ()

void	status_momentary_warning (const std::string &name, uint32_t length=5000)

void	status_momentary_error (const std::string &name, uint32_t length=5000)

bool	has_overridden_loop () const

void	set_component_source (const char *source)
	Set where this component was loaded from for some debug messages. More...

const char *	get_component_source () const
	Get the integration where this component was declared as a string. More...

Public Member Functions inherited from esphome::i2c::I2CDevice
	I2CDevice ()=default
	we use the C++ default constructor More...

void	set_i2c_address (uint8_t address)
	We store the address of the device on the bus. More...

void	set_i2c_bus (I2CBus *bus)
	we store the pointer to the I2CBus to use More...

I2CRegister	reg (uint8_t a_register)
	calls the I2CRegister constructor More...

I2CRegister16	reg16 (uint16_t a_register)
	calls the I2CRegister16 constructor More...

ErrorCode	read (uint8_t *data, size_t len)
	reads an array of bytes from the device using an I2CBus More...

ErrorCode	read_register (uint8_t a_register, uint8_t *data, size_t len, bool stop=true)
	reads an array of bytes from a specific register in the I²C device More...

ErrorCode	read_register16 (uint16_t a_register, uint8_t *data, size_t len, bool stop=true)
	reads an array of bytes from a specific register in the I²C device More...

ErrorCode	write (const uint8_t *data, size_t len, bool stop=true)
	writes an array of bytes to a device using an I2CBus More...

ErrorCode	write_register (uint8_t a_register, const uint8_t *data, size_t len, bool stop=true)
	writes an array of bytes to a specific register in the I²C device More...

ErrorCode	write_register16 (uint16_t a_register, const uint8_t *data, size_t len, bool stop=true)
	write an array of bytes to a specific register in the I²C device More...

bool	read_bytes (uint8_t a_register, uint8_t *data, uint8_t len)
	Compat APIs All methods below have been added for compatibility reasons. More...

bool	read_bytes_raw (uint8_t *data, uint8_t len)

template<size_t N>
optional< std::array< uint8_t, N > >	read_bytes (uint8_t a_register)

template<size_t N>
optional< std::array< uint8_t, N > >	read_bytes_raw ()

bool	read_bytes_16 (uint8_t a_register, uint16_t *data, uint8_t len)

bool	read_byte (uint8_t a_register, uint8_t *data, bool stop=true)

optional< uint8_t >	read_byte (uint8_t a_register)

bool	read_byte_16 (uint8_t a_register, uint16_t *data)

bool	write_bytes (uint8_t a_register, const uint8_t *data, uint8_t len, bool stop=true)

bool	write_bytes (uint8_t a_register, const std::vector< uint8_t > &data)

template<size_t N>
bool	write_bytes (uint8_t a_register, const std::array< uint8_t, N > &data)

bool	write_bytes_16 (uint8_t a_register, const uint16_t *data, uint8_t len)

bool	write_byte (uint8_t a_register, uint8_t data, bool stop=true)

bool	write_byte_16 (uint8_t a_register, uint16_t data)

Protected Member Functions
void	disable_if_power_saving_ ()

void	process_update_ ()

void	interval_function_for_update_ ()

Protected Member Functions inherited from esphome::Component
virtual void	call_loop ()

virtual void	call_dump_config ()

void	set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a unique name. More...

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const std::string &name)
	Cancel an interval function. More...

void	set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
	Set an retry function with a unique name. More...

void	set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)

bool	cancel_retry (const std::string &name)
	Cancel a retry function. More...

void	set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a unique name. More...

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const std::string &name)
	Cancel a timeout function. More...

void	defer (const std::string &name, std::function< void()> &&f)
	Defer a callback to the next loop() call. More...

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call. More...

bool	cancel_defer (const std::string &name)
	Cancel a defer callback using the specified name, name must not be empty. More...

Protected Attributes
const char *	name_

sensor::Sensor *	full_spectrum_sensor_ {nullptr}

sensor::Sensor *	infrared_sensor_ {nullptr}

sensor::Sensor *	visible_sensor_ {nullptr}

sensor::Sensor *	calculated_lux_sensor_ {nullptr}

sensor::Sensor *	actual_gain_sensor_ {nullptr}

TSL2591IntegrationTime	integration_time_

TSL2591ComponentGain	component_gain_

TSL2591Gain	gain_

bool	power_save_mode_enabled_

float	device_factor_

float	glass_attenuation_factor_

uint64_t	interval_start_

uint64_t	interval_timeout_

Protected Attributes inherited from esphome::PollingComponent
uint32_t	update_interval_

Protected Attributes inherited from esphome::Component
uint32_t	component_state_ {0x0000}
	State of this component. More...

float	setup_priority_override_ {NAN}

const char *	component_source_ {nullptr}

Protected Attributes inherited from esphome::i2c::I2CDevice
uint8_t	address_ {0x00}
	store the address of the device on the bus More...

I2CBus *	bus_ {nullptr}
	pointer to I2CBus instance More...

Detailed Description

This class includes support for the TSL2591 i2c ambient light sensor.

The device has two distinct sensors. One is for visible light plus infrared light, and the other is for infrared light. They are reported as separate sensors, and the difference between the values is reported as a third sensor as a convenience for visible light only.

Definition at line 67 of file tsl2591.h.

Member Function Documentation

◆ automatic_gain_update()

void esphome::tsl2591::TSL2591Component::automatic_gain_update ( uint16_t full_spectrum )

Updates the gain setting based on the most recent full spectrum reading.

Calculates and updates the sensor gain setting, trying to keep the full spectrum counts near the middle of the range.

This gets called on update and tries to keep the ADC readings in the middle of the range

It's hard to tell how far down to turn the gain when it's at the top of the scale, so decrease the gain by up to 2 steps if it's near the top to be sure we get a good reading next time. Increase gain by max 2 steps per reading.

If integration time is 100 MS, divide the upper thresholds by 2 to account for ADC saturation

Parameters

full_spectrum The ADC reading for TSL2591 channel 0.

1/3 FS = 21,845

Definition at line 420 of file tsl2591.cpp.

◆ disable()

void esphome::tsl2591::TSL2591Component::disable ( )

Powers off the TSL2591 device.

You can call this from an ESPHome script if you are explicitly controlling TSL2591 power consumption. The device starts enabled in ESPHome unless power save mode is enabled.

Definition at line 33 of file tsl2591.cpp.

◆ disable_if_power_saving_()

void esphome::tsl2591::TSL2591Component::disable_if_power_saving_ ( )

protected

Definition at line 39 of file tsl2591.cpp.

◆ dump_config()

void esphome::tsl2591::TSL2591Component::dump_config ( )

overridevirtual

Used by ESPHome framework.

Reimplemented from esphome::Component.

Definition at line 87 of file tsl2591.cpp.

◆ enable()

void esphome::tsl2591::TSL2591Component::enable ( )

Powers on the TSL2591 device and enables its sensors.

You only need to call this if you have disabled the device. The device starts enabled in ESPHome unless power save mode is enabled.

Definition at line 26 of file tsl2591.cpp.

◆ get_actual_gain()

float esphome::tsl2591::TSL2591Component::get_actual_gain ( )

Reads the actual gain used.

Useful for exposing the real gain used when configured in "auto" gain mode

Definition at line 465 of file tsl2591.cpp.

◆ get_calculated_lux()

float esphome::tsl2591::TSL2591Component::get_calculated_lux	(	uint16_t	full_spectrum,
		uint16_t	infrared
	)

Calculates and returns a lux value based on the ADC readings.

Calculates a lux value from the two TSL2591 physical sensor ADC readings.

Parameters

full_spectrum	The ADC reading for the full spectrum sensor.
infrared	The ADC reading for the infrared sensor.

The lux calculation is copied from the Adafruit TSL2591 library. There is some debate about whether it is the correct lux equation to use. We use that lux equation because (a) it helps with a transition from using that Adafruit library to using this ESPHome integration, and (b) we don't have a definitive better idea.

Since the raw ADC readings are available, you can ignore this method and implement your own lux equation.

Parameters

full_spectrum	The ADC reading for TSL2591 channel 0.
infrared	The ADC reading for TSL2591 channel 1.

Definition at line 356 of file tsl2591.cpp.

◆ get_combined_illuminance()

uint32_t esphome::tsl2591::TSL2591Component::get_combined_illuminance ( )

Get the combined illuminance value.

This is encoded into a 32 bit value. The high 16 bits are the value of the infrared sensor. The low 16 bits are the sum of the combined sensor values.

If power saving mode is enabled, there can be a delay (up to the value of the integration time) while waiting for the device ADCs to signal that values are valid.

Definition at line 264 of file tsl2591.cpp.

◆ get_illuminance() [1/2]

uint16_t esphome::tsl2591::TSL2591Component::get_illuminance ( TSL2591SensorChannel channel )

Get an individual sensor channel reading.

This gets an individual light sensor reading. Since it goes through the entire component read cycle to get one value, it's not optimal if you want to get all possible channel values. If you want that, first call get_combined_illuminance() and pass that value to the companion method with a different signature.

If power saving mode is enabled, there can be a delay (up to the value of the integration time) while waiting for the device ADCs to signal that values are valid.

Parameters

channel The sensor channel of interest.

Definition at line 321 of file tsl2591.cpp.

◆ get_illuminance() [2/2]

uint16_t esphome::tsl2591::TSL2591Component::get_illuminance	(	TSL2591SensorChannel	channel,
		uint32_t	combined_illuminance
	)

Get an individual sensor channel reading from combined illuminance.

This gets an individual light sensor reading from a combined illuminance value, which you would obtain from calling getCombinedIlluminance(). This method does not communicate with the sensor at all. It's strictly local calculations, so it is efficient if you call it multiple times.

Parameters

channel	The sensor channel of interest.
combined_illuminance	The previously obtained combined illuminance value.

Definition at line 326 of file tsl2591.cpp.

◆ get_setup_priority()

float esphome::tsl2591::TSL2591Component::get_setup_priority ( ) const

overridevirtual

Used by ESPHome framework.

Reimplemented from esphome::Component.

Definition at line 253 of file tsl2591.cpp.

◆ interval_function_for_update_()

void esphome::tsl2591::TSL2591Component::interval_function_for_update_ ( )

protected

Definition at line 172 of file tsl2591.cpp.

◆ is_adc_valid()

bool esphome::tsl2591::TSL2591Component::is_adc_valid ( )

Are the device ADC values valid?

Useful for scripting. This should be checked before calling update(). It asks the TSL2591 if the ADC has completed an integration cycle and has reliable values in the device registers. If you call update() before the ADC values are valid, you may cause a general delay in the ESPHome update loop.

It should take no more than the configured integration time for the ADC values to become valid after the TSL2591 device is enabled.

Definition at line 255 of file tsl2591.cpp.

◆ process_update_()

void esphome::tsl2591::TSL2591Component::process_update_ ( )

protected

Definition at line 138 of file tsl2591.cpp.

◆ set_actual_gain_sensor()

void esphome::tsl2591::TSL2591Component::set_actual_gain_sensor ( sensor::Sensor * actual_gain_sensor )

Used by ESPHome framework.

Definition at line 217 of file tsl2591.cpp.

◆ set_calculated_lux_sensor()

void esphome::tsl2591::TSL2591Component::set_calculated_lux_sensor ( sensor::Sensor * calculated_lux_sensor )

Used by ESPHome framework.

Definition at line 213 of file tsl2591.cpp.

◆ set_device_and_glass_attenuation_factors()

void esphome::tsl2591::TSL2591Component::set_device_and_glass_attenuation_factors	(	float	device_factor,
		float	glass_attenuation_factor
	)

Sets the device and glass attenuation factors.

The lux equation, used to calculate the lux from the ADC readings, involves a scaling coefficient that is the product of a device factor (specific to the type of device being used) and a glass attenuation factor (specific to whatever glass or plastic cover is installed in front of the light sensors.

AMS does not publish the device factor for the TSL2591. In the datasheet for the earlier TSL2571 and in application notes, they use the value 53, so we use that as the default.

The glass attenuation factor depends on factors external to the TSL2591 and is best obtained through experimental measurements. The Adafruit TSL2591 library use a value of ~7.7, which we use as a default. Waveshare uses a value of ~14.4. Presumably, those factors are appropriate to the breakout boards from those vendors, but we have not verified that.

Parameters

device_factor	The device factor.
glass_attenuation_factor	The glass attenuation factor.

Definition at line 227 of file tsl2591.cpp.

◆ set_full_spectrum_sensor()

void esphome::tsl2591::TSL2591Component::set_full_spectrum_sensor ( sensor::Sensor * full_spectrum_sensor )

Used by ESPHome framework.

Definition at line 209 of file tsl2591.cpp.

◆ set_gain()

void esphome::tsl2591::TSL2591Component::set_gain ( TSL2591ComponentGain gain )

Used by ESPHome framework.

Does NOT actually set the value on the device.

Definition at line 225 of file tsl2591.cpp.

◆ set_infrared_sensor()

void esphome::tsl2591::TSL2591Component::set_infrared_sensor ( sensor::Sensor * infrared_sensor )

Used by ESPHome framework.

Definition at line 203 of file tsl2591.cpp.

◆ set_integration_time()

void esphome::tsl2591::TSL2591Component::set_integration_time ( TSL2591IntegrationTime integration_time )

Used by ESPHome framework.

Does NOT actually set the value on the device.

Definition at line 221 of file tsl2591.cpp.

◆ set_integration_time_and_gain()

void esphome::tsl2591::TSL2591Component::set_integration_time_and_gain	(	TSL2591IntegrationTime	integration_time,
		TSL2591Gain	gain
	)

Set device integration time and gain.

These are set as a single I2C transaction, so you must supply values for both.

Longer integration times provides more accurate values, but also means more power consumption. Higher gain values are useful for lower light intensities but are also subject to more noise. The device might use a slightly different gain multiplier than those indicated; see the datasheet for details.

Possible values for integration_time (from enum TSL2591IntegrationTime) are:

Possible values for gain (from enum TSL2591Gain) are:

esphome::tsl2591::TSL2591_GAIN_LOW (1x)
esphome::tsl2591::TSL2591_GAIN_MED (25x)
esphome::tsl2591::TSL2591_GAIN_HIGH (400x)
esphome::tsl2591::TSL2591_GAIN_MAX (9500x)

Parameters

integration_time	The new integration time.
gain	The new gain.

Definition at line 232 of file tsl2591.cpp.

◆ set_name()

void esphome::tsl2591::TSL2591Component::set_name ( const char * name )

Sets the name for this instance of the device.

Parameters

name	The user-friendly name.

Definition at line 251 of file tsl2591.cpp.

◆ set_power_save_mode()

void esphome::tsl2591::TSL2591Component::set_power_save_mode ( bool enable )

Should the device be powered down between readings?

The disadvantage of powering down the device between readings is that you have to wait for the ADC to go through an integration cycle before a reliable reading is available. This happens during ESPHome's update loop, so waiting slows down the entire ESP device. You should only enable this if you need to minimize power consumption and you can tolerate that delay. Otherwise, keep the default of disabling power save mode.

Parameters

enable Enable or disable power save mode.

Definition at line 249 of file tsl2591.cpp.

◆ set_visible_sensor()

void esphome::tsl2591::TSL2591Component::set_visible_sensor ( sensor::Sensor * visible_sensor )

Used by ESPHome framework.

Definition at line 207 of file tsl2591.cpp.

◆ setup()

void esphome::tsl2591::TSL2591Component::setup ( )

overridevirtual

Used by ESPHome framework.

Reimplemented from esphome::Component.

Definition at line 45 of file tsl2591.cpp.

◆ update()

void esphome::tsl2591::TSL2591Component::update ( )

overridevirtual

Used by ESPHome framework.

Implements esphome::PollingComponent.

Definition at line 186 of file tsl2591.cpp.

Field Documentation

◆ actual_gain_sensor_

sensor::Sensor* esphome::tsl2591::TSL2591Component::actual_gain_sensor_ {nullptr}

protected

Definition at line 261 of file tsl2591.h.

◆ calculated_lux_sensor_

sensor::Sensor* esphome::tsl2591::TSL2591Component::calculated_lux_sensor_ {nullptr}

protected

Definition at line 260 of file tsl2591.h.

◆ component_gain_

TSL2591ComponentGain esphome::tsl2591::TSL2591Component::component_gain_

protected

Definition at line 263 of file tsl2591.h.

◆ device_factor_

float esphome::tsl2591::TSL2591Component::device_factor_

protected

Definition at line 266 of file tsl2591.h.

◆ full_spectrum_sensor_

sensor::Sensor* esphome::tsl2591::TSL2591Component::full_spectrum_sensor_ {nullptr}

protected

Definition at line 257 of file tsl2591.h.

◆ gain_

TSL2591Gain esphome::tsl2591::TSL2591Component::gain_

protected

Definition at line 264 of file tsl2591.h.

◆ glass_attenuation_factor_

float esphome::tsl2591::TSL2591Component::glass_attenuation_factor_

protected

Definition at line 267 of file tsl2591.h.

◆ infrared_sensor_

sensor::Sensor* esphome::tsl2591::TSL2591Component::infrared_sensor_ {nullptr}

protected

Definition at line 258 of file tsl2591.h.

◆ integration_time_

TSL2591IntegrationTime esphome::tsl2591::TSL2591Component::integration_time_

protected

Definition at line 262 of file tsl2591.h.

◆ interval_start_

uint64_t esphome::tsl2591::TSL2591Component::interval_start_

protected

Definition at line 268 of file tsl2591.h.

◆ interval_timeout_

uint64_t esphome::tsl2591::TSL2591Component::interval_timeout_

protected

Definition at line 269 of file tsl2591.h.

◆ name_

const char* esphome::tsl2591::TSL2591Component::name_

protected

Definition at line 256 of file tsl2591.h.

◆ power_save_mode_enabled_

bool esphome::tsl2591::TSL2591Component::power_save_mode_enabled_

protected

Definition at line 265 of file tsl2591.h.

◆ visible_sensor_

sensor::Sensor* esphome::tsl2591::TSL2591Component::visible_sensor_ {nullptr}

protected

Definition at line 259 of file tsl2591.h.

The documentation for this class was generated from the following files:

/opt/build/esphome/esphome/components/tsl2591/tsl2591.h
/opt/build/esphome/esphome/components/tsl2591/tsl2591.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ automatic_gain_update()

◆ disable()

◆ disable_if_power_saving_()

◆ dump_config()

◆ enable()

◆ get_actual_gain()

◆ get_calculated_lux()

◆ get_combined_illuminance()

◆ get_illuminance() [1/2]

◆ get_illuminance() [2/2]

◆ get_setup_priority()

◆ interval_function_for_update_()

◆ is_adc_valid()

◆ process_update_()

◆ set_actual_gain_sensor()

◆ set_calculated_lux_sensor()

◆ set_device_and_glass_attenuation_factors()

◆ set_full_spectrum_sensor()

◆ set_gain()

◆ set_infrared_sensor()

◆ set_integration_time()

◆ set_integration_time_and_gain()

◆ set_name()

◆ set_power_save_mode()

◆ set_visible_sensor()

◆ setup()

◆ update()

Field Documentation

◆ actual_gain_sensor_

◆ calculated_lux_sensor_

◆ component_gain_

◆ device_factor_

◆ full_spectrum_sensor_

◆ gain_

◆ glass_attenuation_factor_

◆ infrared_sensor_

◆ integration_time_

◆ interval_start_

◆ interval_timeout_

◆ name_

◆ power_save_mode_enabled_

◆ visible_sensor_