TSL2561 Ambient Light Sensor

The TSL2561 sensor allows you to use your TSL2561 i2c-enabled ambient light sensor with esphomelib (datasheet, Adafruit). It requires i2c to be setup to work.

Example Usage

// Basic
auto tsl2561 = App.make_tsl2561_sensor("TSL2561 Illuminance Sensor");

// Advanced settings
// set the time the sensor will take for value accumulation, default: 402 ms
// set a higher gain for low light conditions, default: 1x

See Application::make_tsl2561_sensor().

API Reference

class TSL2561Sensor : public sensor::PollingSensorComponent, public I2CDevice

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

Public Functions

sensor::TSL2561Sensor::TSL2561Sensor(I2CComponent * parent, const std::string & name, uint8_t address = 0x39, uint32_t update_interval = 15000)
void set_integration_time(TSL2561IntegrationTime integration_time)

Set the time that sensor values should be accumulated for.

Longer means more accurate, but also mean more power consumption.

Possible values are:

  • sensor::TSL2561_INTEGRATION_14MS
  • sensor::TSL2561_INTEGRATION_101MS
  • sensor::TSL2561_INTEGRATION_402MS (default)

  • integration_time: The new integration time.

void set_gain(TSL2561Gain gain)

Set the internal gain of the sensor.

Can be useful for low-light conditions

Possible values are:

  • sensor::TSL2561_GAIN_1X (default)
  • sensor::TSL2561_GAIN_16X

  • gain: The new gain.

void set_is_cs_package(bool package_cs)

The “CS” package of this sensor has a slightly different formula for converting the raw values.

Use this setting to indicate that this is a CS package. Defaults to false (not a CS package)

  • package_cs: Is this a CS package.

void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

void dump_config()
void update()
std::string unit_of_measurement()

Override this to set the Home Assistant unit of measurement for this sensor.

Return “” to disable this feature.

The icon of this sensor, for example “°C”.

std::string icon()

Override this to set the Home Assistant icon for this sensor.

Return “” to disable this feature.

The icon of this sensor, for example “mdi:battery”.

int8_t accuracy_decimals()

Return the accuracy in decimals for this sensor.

float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

The setup priority of this component

bool tsl2561_read_byte(uint8_t register_, uint8_t *value)
bool tsl2561_read_uint(uint8_t register_, uint16_t *value)
bool tsl2561_write_byte(uint8_t register_, uint8_t value)

Protected Functions

float get_integration_time_ms_()
void read_data_()
float calculate_lx_(uint16_t ch0, uint16_t ch1)

Protected Attributes

TSL2561IntegrationTime integration_time_ = {TSL2561_INTEGRATION_402MS}
TSL2561Gain gain_ = {TSL2561_GAIN_1X}
bool package_cs_ = {false}
enum sensor::TSL2561IntegrationTime

Enum listing all conversion/integration time settings for the TSL2561.

Higher values mean more accurate results, but will take more energy/more time.


TSL2561_INTEGRATION_101MS = 0b01
TSL2561_INTEGRATION_402MS = 0b10
enum sensor::TSL2561Gain

Enum listing all gain settings for the TSL2561.

Higher values are better for low light situations, but can increase noise.


TSL2561_GAIN_1X = 0
TSL2561_GAIN_16X = 1