TSL2591 high-dynamic-range digital light sensor (I2C), reading full-spectrum and IR channels to compute lux. More...

#include <TSL2591.h>

Inheritance diagram for RumPi::TSL2591:

Collaboration diagram for RumPi::TSL2591:

Public Member Functions
	TSL2591 (E_TSL2591_IntegrationTime integrationTimeMilliseconds=E_TSL2591_IntegrationTime::ATIME_100MS, E_TSL2591_AmplificationGain amplificationGain=E_TSL2591_AmplificationGain::GAIN_MED)
	Builds a TSL2591 with the given integration time and gain, and default light-level cutoffs. More...

virtual	~TSL2591 ()
	Destroys the sensor. More...

virtual void	TurnOn () override
	Initializes the sensor over I2C, powers on the ALS, applies the timing/gain, and lets the sensor wake up, reporting progress through the AlertManager. More...

virtual void	TurnOff () override
	Turns the sensor off by disabling it over I2C (if it was initialized). More...

virtual void	ProcessRawValues () override
	Reads the raw CH0/CH1 channels, auto-adjusts gain if the reading is saturated or too dark (re-reading after a gain change), and recomputes the cached lux. More...

virtual std::string	ToString () const override
	Serializes the raw CH0/CH1 readings, calculated lux, and current gain to a string. More...

virtual bool	AdjustAndValidateSettings (const uint16_t ch0)
	Auto-adjusts the amplification gain one step down when the channel is flooded (> 62000) or one step up when it is too dark (< 100), pushing any change to the hardware. More...

virtual float	CalculateLux (const uint16_t ch0, const uint16_t ch1)
	Computes lux from the full-spectrum and IR channels, normalizing by counts-per-lux and rejecting IR, with a visible-approximation fallback for high-IR indoor environments; returns -1 on saturation/overflow. More...

virtual float	GetLux () const
	Gets the most recently calculated lux value. More...

virtual E_LightLevel	CalculateLightLevel () const
	Maps the most recent lux reading onto a 0 (pitch dark) to 5 (very bright) level. More...

virtual E_LightLevel	CalculateLightLevel (const float lux) const
	Maps a given lux value onto a light level, treating the negative saturation sentinel as very bright. More...

void	SetLightLevelCutoffs (float dark, float veryDim, float dim, float normal, float bright)
	Sets the ascending lux cutoffs that define the dark/very-dim/dim/normal/bright light-level buckets. More...

virtual std::string	DetermineLightCategory () const
	Gets the short, human-readable light category for the current reading. More...

virtual std::string	DetermineLightCategory (const float lux) const
	Gets the short, human-readable light level for a given lux, for a compact UI label (the Summary tile and the Home scene). More...

virtual void	SetTiming (const E_TSL2591_IntegrationTime integrationTimeMilliseconds, const E_TSL2591_AmplificationGain amplificationGain)
	Writes the combined integration-time and gain byte to the sensor's control register, reporting through the AlertManager (or warning if the device was not initialized). More...

Public Member Functions inherited from RumPi::BaseComponent
	BaseComponent ()
	Builds a base component with an unknown type and an empty name. More...

virtual	~BaseComponent ()
	Virtual destructor so deleting a component through a BaseComponent* also cleans up the concrete subclass. More...

virtual void	TurnOn ()=0
	Turns the component on (e.g. More...

virtual void	TurnOff ()=0
	Turns the component off. More...

virtual std::string	ToString () const =0
	Serializes the component's current readings to a string (usually JSON). More...

virtual void	ProcessRawValues ()=0
	Reads and processes the component's latest raw values (called once per poll). More...

virtual EComponentType	GetComponentType () const
	Gets the component's type. More...

const std::string &	GetName () const
	Gets the component's unique per-instance name. More...

void	SetName (const std::string &name)
	Sets the component's unique per-instance name. More...

Static Public Member Functions
static float	ConvertIntegrationTimeToDecimalMilliseconds (const E_TSL2591_IntegrationTime integrationTimeMilliseconds)
	Converts an integration-time enum to its value in milliseconds. More...

static E_TSL2591_IntegrationTime	ConvertDecimalMillisecondsToIntegrationTime (const float decimalMilliseconds)
	Converts a millisecond value to the closest integration-time enum at or below it. More...

static float	ConvertAmplificationGainToDecimalMultiplier (const E_TSL2591_AmplificationGain amplificationGain)
	Converts an amplification-gain enum to its decimal multiplier. More...

static E_TSL2591_AmplificationGain	ConvertDecimalMultiplierToAmplificationGain (const float decimalMultiplier)
	Converts a decimal gain multiplier to the closest amplification-gain enum at or below it. More...

Static Public Member Functions inherited from RumPi::BaseComponent
static std::string	ComponentTypeToString (const EComponentType theComponentTypeToConvert)
	Maps an EComponentType to its string name. More...

static EComponentType	StringToComponentType (const std::string &theComponentTypeName)
	Maps a type name back to its EComponentType (the inverse of ComponentTypeToString), so the client can turn the type carried on the wire back into a value it can look an icon up with. More...

Private Attributes
int	myFileDescriptor
	The open i2c device file descriptor. More...

uint16_t	myRawChannel0Reading
	The most recent raw full-spectrum (CH0) reading. More...

uint16_t	myRawChannel1Reading
	The most recent raw infrared (CH1) reading. More...

float	myCalculatedLux
	The most recently calculated lux value. More...

E_TSL2591_IntegrationTime	myIntegrationTimeMilliseconds
	How long the sensor integrates each reading. More...

E_TSL2591_AmplificationGain	myAmplificationGain
	The current amplification gain. More...

float	myLightCutoffDark
	Upper lux bound of the "Dark" bucket. More...

float	myLightCutoffVeryDim
	Upper lux bound of the "Very Dim" bucket. More...

float	myLightCutoffDim
	Upper lux bound of the "Dim" bucket. More...

float	myLightCutoffNormal
	Upper lux bound of the "Normal" bucket. More...

float	myLightCutoffBright
	Upper lux bound of the "Bright" bucket. More...

Additional Inherited Members
Protected Attributes inherited from RumPi::BaseComponent
EComponentType	myComponentType
	The kind of component this is (set by each concrete subclass). More...

std::string	myName
	A unique per-instance name, assigned when the component is added to the manager. More...

Detailed Description

TSL2591 high-dynamic-range digital light sensor (I2C), reading full-spectrum and IR channels to compute lux.

Author: Eddie O'Hagan

Date: 8/13/2026

Constructor & Destructor Documentation

◆ TSL2591()

RumPi::TSL2591::TSL2591	(	E_TSL2591_IntegrationTime	integrationTimeMilliseconds = `E_TSL2591_IntegrationTime::ATIME_100MS`,
		E_TSL2591_AmplificationGain	amplificationGain = `E_TSL2591_AmplificationGain::GAIN_MED`
	)

Builds a TSL2591 with the given integration time and gain, and default light-level cutoffs.

Author: Eddie O'Hagan

Date: 8/13/2026

TSL2591 lightSensor;

RumPi::TSL2591::TSL2591

TSL2591(E_TSL2591_IntegrationTime integrationTimeMilliseconds=E_TSL2591_IntegrationTime::ATIME_100MS, E_TSL2591_AmplificationGain amplificationGain=E_TSL2591_AmplificationGain::GAIN_MED)

Builds a TSL2591 with the given integration time and gain, and default light-level cutoffs.

Definition: TSL2591.cpp:20

Parameters

[in]	integrationTimeMilliseconds	How long the sensor integrates each reading.
[in]	amplificationGain	The amplification gain to start with.

◆ ~TSL2591()

RumPi::TSL2591::~TSL2591 ( )

virtual

Destroys the sensor.

Author: Eddie O'Hagan

Date: 8/13/2026

TSL2591* lightSensor = new TSL2591();

delete lightSensor;

Member Function Documentation

◆ AdjustAndValidateSettings()

bool RumPi::TSL2591::AdjustAndValidateSettings ( const uint16_t ch0 )

virtual

Auto-adjusts the amplification gain one step down when the channel is flooded (> 62000) or one step up when it is too dark (< 100), pushing any change to the hardware.

Author: Eddie O'Hagan

Date: 8/13/2026

bool changed = lightSensor.AdjustAndValidateSettings(rawCh0);

Parameters

[in] ch0 The most recent raw full-spectrum (CH0) reading.

Returns: True if the gain was changed (so the next read should be re-taken), false otherwise.

◆ CalculateLightLevel() [1/2]

E_LightLevel RumPi::TSL2591::CalculateLightLevel ( ) const

virtual

Maps the most recent lux reading onto a 0 (pitch dark) to 5 (very bright) level.

The category name and anything that wants a numeric level both derive from this, so the thresholds live in exactly one place.

Author: Eddie O'Hagan

Date: 8/13/2026

E_LightLevel level = lightSensor.CalculateLightLevel();

RumPi::E_LightLevel

E_LightLevel

How much light the sensor is seeing, darkest to brightest.

Definition: SensorLevels.h:17

Returns: The categorized light level for the current reading.

◆ CalculateLightLevel() [2/2]

E_LightLevel RumPi::TSL2591::CalculateLightLevel ( const float lux ) const

virtual

Maps a given lux value onto a light level, treating the negative saturation sentinel as very bright.

Author: Eddie O'Hagan

Date: 8/13/2026

E_LightLevel level = lightSensor.CalculateLightLevel(250.0f);

Parameters

[in] lux The lux value to categorize.

Returns: The categorized light level.

◆ CalculateLux()

float RumPi::TSL2591::CalculateLux	(	const uint16_t	ch0,
		const uint16_t	ch1
	)

virtual

Computes lux from the full-spectrum and IR channels, normalizing by counts-per-lux and rejecting IR, with a visible-approximation fallback for high-IR indoor environments; returns -1 on saturation/overflow.

Author: Eddie O'Hagan

Date: 8/13/2026

float lux = lightSensor.CalculateLux(rawCh0, rawCh1);

Parameters

[in]	ch0	The raw full-spectrum (CH0) reading.
[in]	ch1	The raw infrared (CH1) reading.

Returns: The calculated lux, 0 in total darkness, or -1 on saturation/overflow.

◆ ConvertAmplificationGainToDecimalMultiplier()

float RumPi::TSL2591::ConvertAmplificationGainToDecimalMultiplier ( const E_TSL2591_AmplificationGain amplificationGain )

static

Converts an amplification-gain enum to its decimal multiplier.

Author: Eddie O'Hagan

Date: 8/13/2026

float gain = TSL2591::ConvertAmplificationGainToDecimalMultiplier(E_TSL2591_AmplificationGain::GAIN_MED);

RumPi::TSL2591::ConvertAmplificationGainToDecimalMultiplier

static float ConvertAmplificationGainToDecimalMultiplier(const E_TSL2591_AmplificationGain amplificationGain)

Converts an amplification-gain enum to its decimal multiplier.

Definition: TSL2591.cpp:539

RumPi::E_TSL2591_AmplificationGain::GAIN_MED

@ GAIN_MED

Output: 25

Parameters

[in] amplificationGain The amplification-gain enum to convert.

Returns: The gain as a decimal multiplier.

◆ ConvertDecimalMillisecondsToIntegrationTime()

E_TSL2591_IntegrationTime RumPi::TSL2591::ConvertDecimalMillisecondsToIntegrationTime ( const float decimalMilliseconds )

static

Converts a millisecond value to the closest integration-time enum at or below it.

Author: Eddie O'Hagan

Date: 8/13/2026

E_TSL2591_IntegrationTime time = TSL2591::ConvertDecimalMillisecondsToIntegrationTime(300.0f);

RumPi::TSL2591::ConvertDecimalMillisecondsToIntegrationTime

static E_TSL2591_IntegrationTime ConvertDecimalMillisecondsToIntegrationTime(const float decimalMilliseconds)

Converts a millisecond value to the closest integration-time enum at or below it.

Definition: TSL2591.cpp:498

RumPi::E_TSL2591_IntegrationTime

E_TSL2591_IntegrationTime

This represents how long the sensor looks at the light in a reading.

Definition: TSL2591.h:32

Parameters

[in] decimalMilliseconds The integration time, in milliseconds.

Returns: The matching integration-time enum.

◆ ConvertDecimalMultiplierToAmplificationGain()

E_TSL2591_AmplificationGain RumPi::TSL2591::ConvertDecimalMultiplierToAmplificationGain ( const float decimalMultiplier )

static

Converts a decimal gain multiplier to the closest amplification-gain enum at or below it.

Author: Eddie O'Hagan

Date: 8/13/2026

E_TSL2591_AmplificationGain gain = TSL2591::ConvertDecimalMultiplierToAmplificationGain(25.0f);

RumPi::TSL2591::ConvertDecimalMultiplierToAmplificationGain

static E_TSL2591_AmplificationGain ConvertDecimalMultiplierToAmplificationGain(const float decimalMultiplier)

Converts a decimal gain multiplier to the closest amplification-gain enum at or below it.

Definition: TSL2591.cpp:571

RumPi::E_TSL2591_AmplificationGain

E_TSL2591_AmplificationGain

This represents the amplification level, helpful for low/high light situations.

Definition: TSL2591.h:48

Parameters

[in] decimalMultiplier The gain as a decimal multiplier.

Returns: The matching amplification-gain enum.

◆ ConvertIntegrationTimeToDecimalMilliseconds()

float RumPi::TSL2591::ConvertIntegrationTimeToDecimalMilliseconds ( const E_TSL2591_IntegrationTime integrationTimeMilliseconds )

static

Converts an integration-time enum to its value in milliseconds.

Author: Eddie O'Hagan

Date: 8/13/2026

float ms = TSL2591::ConvertIntegrationTimeToDecimalMilliseconds(E_TSL2591_IntegrationTime::ATIME_100MS);

RumPi::TSL2591::ConvertIntegrationTimeToDecimalMilliseconds

static float ConvertIntegrationTimeToDecimalMilliseconds(const E_TSL2591_IntegrationTime integrationTimeMilliseconds)

Converts an integration-time enum to its value in milliseconds.

Definition: TSL2591.cpp:479

RumPi::E_TSL2591_IntegrationTime::ATIME_100MS

@ ATIME_100MS

Output: 100

Parameters

[in] integrationTimeMilliseconds The integration-time enum to convert.

Returns: The integration time, in milliseconds.

◆ DetermineLightCategory() [1/2]

std::string RumPi::TSL2591::DetermineLightCategory ( ) const

virtual

Gets the short, human-readable light category for the current reading.

Author: Eddie O'Hagan

Date: 8/13/2026

std::string category = lightSensor.DetermineLightCategory();

Returns: The light category (e.g. "Dark", "Normal", "Very Bright").

◆ DetermineLightCategory() [2/2]

std::string RumPi::TSL2591::DetermineLightCategory ( const float lux ) const

virtual

Gets the short, human-readable light level for a given lux, for a compact UI label (the Summary tile and the Home scene).

Author: Eddie O'Hagan

Date: 8/13/2026

std::string category = lightSensor.DetermineLightCategory(250.0f);

Parameters

[in] lux The lux value to categorize.

Returns: The light category (e.g. "Dark", "Normal", "Very Bright").

◆ GetLux()

float RumPi::TSL2591::GetLux ( ) const

virtual

Gets the most recently calculated lux value.

Author: Eddie O'Hagan

Date: 8/13/2026

float lux = lightSensor.GetLux();

Returns: The calculated lux.

◆ ProcessRawValues()

void RumPi::TSL2591::ProcessRawValues ( )

overridevirtual

Reads the raw CH0/CH1 channels, auto-adjusts gain if the reading is saturated or too dark (re-reading after a gain change), and recomputes the cached lux.

Author: Eddie O'Hagan

Date: 8/13/2026

lightSensor.ProcessRawValues();

Implements RumPi::BaseComponent.

◆ SetLightLevelCutoffs()

void RumPi::TSL2591::SetLightLevelCutoffs	(	float	dark,
		float	veryDim,
		float	dim,
		float	normal,
		float	bright
	)

Sets the ascending lux cutoffs that define the dark/very-dim/dim/normal/bright light-level buckets.

Author: Eddie O'Hagan

Date: 8/13/2026

lightSensor.SetLightLevelCutoffs(1.0f, 10.0f, 50.0f, 200.0f, 1000.0f);

Parameters

[in]	dark	Upper lux bound of the "Dark" bucket.
[in]	veryDim	Upper lux bound of the "Very Dim" bucket.
[in]	dim	Upper lux bound of the "Dim" bucket.
[in]	normal	Upper lux bound of the "Normal" bucket.
[in]	bright	Upper lux bound of the "Bright" bucket.

◆ SetTiming()

void RumPi::TSL2591::SetTiming	(	const E_TSL2591_IntegrationTime	integrationTimeMilliseconds,
		const E_TSL2591_AmplificationGain	amplificationGain
	)

virtual

Writes the combined integration-time and gain byte to the sensor's control register, reporting through the AlertManager (or warning if the device was not initialized).

Author: Eddie O'Hagan

Date: 8/13/2026

lightSensor.SetTiming(E_TSL2591_IntegrationTime::ATIME_100MS, E_TSL2591_AmplificationGain::GAIN_MED);

Parameters

[in]	integrationTimeMilliseconds	The integration time to set.
[in]	amplificationGain	The amplification gain to set.

◆ ToString()

std::string RumPi::TSL2591::ToString ( ) const

overridevirtual

Serializes the raw CH0/CH1 readings, calculated lux, and current gain to a string.

Author: Eddie O'Hagan

Date: 8/13/2026

std::string data = lightSensor.ToString();

Returns: A multi-line string describing the sensor's reading.

Implements RumPi::BaseComponent.

◆ TurnOff()

void RumPi::TSL2591::TurnOff ( )

overridevirtual

Turns the sensor off by disabling it over I2C (if it was initialized).

Author: Eddie O'Hagan

Date: 8/13/2026

lightSensor.TurnOff();

Implements RumPi::BaseComponent.

◆ TurnOn()

void RumPi::TSL2591::TurnOn ( )

overridevirtual

Initializes the sensor over I2C, powers on the ALS, applies the timing/gain, and lets the sensor wake up, reporting progress through the AlertManager.

Author: Eddie O'Hagan

Date: 8/13/2026

lightSensor.TurnOn();

Implements RumPi::BaseComponent.

Member Data Documentation

◆ myAmplificationGain

E_TSL2591_AmplificationGain RumPi::TSL2591::myAmplificationGain

private

The current amplification gain.

◆ myCalculatedLux

float RumPi::TSL2591::myCalculatedLux

private

The most recently calculated lux value.

◆ myFileDescriptor

int RumPi::TSL2591::myFileDescriptor

private

The open i2c device file descriptor.

◆ myIntegrationTimeMilliseconds

E_TSL2591_IntegrationTime RumPi::TSL2591::myIntegrationTimeMilliseconds

private

How long the sensor integrates each reading.

◆ myLightCutoffBright

float RumPi::TSL2591::myLightCutoffBright

private

Upper lux bound of the "Bright" bucket.

◆ myLightCutoffDark

float RumPi::TSL2591::myLightCutoffDark

private

Upper lux bound of the "Dark" bucket.

◆ myLightCutoffDim

float RumPi::TSL2591::myLightCutoffDim

private

Upper lux bound of the "Dim" bucket.

◆ myLightCutoffNormal

float RumPi::TSL2591::myLightCutoffNormal

private

Upper lux bound of the "Normal" bucket.

◆ myLightCutoffVeryDim

float RumPi::TSL2591::myLightCutoffVeryDim

private

Upper lux bound of the "Very Dim" bucket.

◆ myRawChannel0Reading

uint16_t RumPi::TSL2591::myRawChannel0Reading

private

The most recent raw full-spectrum (CH0) reading.

◆ myRawChannel1Reading

uint16_t RumPi::TSL2591::myRawChannel1Reading

private

The most recent raw infrared (CH1) reading.

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

Source/Headers/RumPi/Components/TSL2591.h
Source/Implementations/RumPi/Components/TSL2591.cpp

Public Member Functions

Static Public Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TSL2591()

◆ ~TSL2591()

Member Function Documentation

◆ AdjustAndValidateSettings()

◆ CalculateLightLevel() [1/2]

◆ CalculateLightLevel() [2/2]

◆ CalculateLux()

◆ ConvertAmplificationGainToDecimalMultiplier()

◆ ConvertDecimalMillisecondsToIntegrationTime()

◆ ConvertDecimalMultiplierToAmplificationGain()

◆ ConvertIntegrationTimeToDecimalMilliseconds()

◆ DetermineLightCategory() [1/2]

◆ DetermineLightCategory() [2/2]

◆ GetLux()

◆ ProcessRawValues()

◆ SetLightLevelCutoffs()

◆ SetTiming()

◆ ToString()

◆ TurnOff()

◆ TurnOn()

Member Data Documentation

◆ myAmplificationGain

◆ myCalculatedLux

◆ myFileDescriptor

◆ myIntegrationTimeMilliseconds

◆ myLightCutoffBright

◆ myLightCutoffDark

◆ myLightCutoffDim

◆ myLightCutoffNormal

◆ myLightCutoffVeryDim

◆ myRawChannel0Reading

◆ myRawChannel1Reading