drivers.TSL2591.adafruit_tsl2591.TSL2591

class drivers.TSL2591.adafruit_tsl2591.TSL2591(i2c: busio.I2C, address: int = _TSL2591_ADDR)

AMS TSL2591 high-dynamic-range ambient light sensor.

Register-level driver exposing photodiode channels 0 (IR + visible) and 1 (IR only). Measures lux via the AMS-recommended formula, full-spectrum luminosity as (channel_1 << 16) | channel_0 and infrared luminosity directly from channel 1. Gain and integration time are software-configurable to span roughly six decades of irradiance.

Variables:

  • gain (int) – Current gain setting; one of GAIN_LOW, GAIN_MED, GAIN_HIGH, GAIN_MAX.

  • integration_time (int) – Current ADC integration time enum; one of INTEGRATIONTIME_100MS … INTEGRATIONTIME_600MS.

  • threshold_low (int) – 16-bit ALS interrupt low threshold.

  • threshold_high (int) – 16-bit ALS interrupt high threshold.

  • nopersist_threshold_low (int) – 16-bit no-persist low threshold.

  • nopersist_threshold_high (int) – 16-bit no-persist high threshold.

  • persist (int) – 0-15 persist filter cycle selector.

  • raw_luminosity (tuple[int, int]) – Channel 0 / channel 1 raw counts.

  • full_spectrum (int) – 32-bit packed luminosity.

  • infrared (int) – 16-bit IR-only luminosity (channel 1).

  • visible (int) – Visible-only luminosity (channel 0 - channel 1).

  • lux (float) – Calculated illuminance in lux.

Example

>>> import board
>>> from drivers.TSL2591 import adafruit_tsl2591
>>> i2c = board.I2C()
>>> sensor = adafruit_tsl2591.TSL2591(i2c)
>>> sensor.gain = adafruit_tsl2591.GAIN_MED
>>> sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_100MS
>>> sensor.lux, sensor.infrared, sensor.visible, sensor.full_spectrum
(42.0, 17, 123, 140)

See also

SensorBase.SensorBase.GenericSensor: Oizom abstract

sensor contract. This backend is not a subclass; it is wrapped by drivers.TSL2591.TSL2591.TSL2591.

drivers.TSL2591.TSL2591.TSL2591: Oizom-facing facade

built on top of this driver.

Initialise and probe the TSL2591 on the supplied I2C bus.

Reads the device-ID register to confirm the part is present, then applies driver defaults (GAIN_MED, INTEGRATIONTIME_100MS) and powers the device on with ALS enabled.

Parameters:

  • i2c – A configured busio.I2C bus instance.

  • address – Optional I2C address override. Defaults to 0x29 (the TSL2591’s fixed address).

Returns:

None.

Raises:

RuntimeError – If the device-ID register does not return the expected 0x50 value (wiring, address or part-fault).

Example

>>> sensor = adafruit_tsl2591.TSL2591(i2c)

Note

The constructor leaves the part enabled. Call disable() to put it back into low-power mode when not in use.

_read_u16LE(address: int) → int

Read a 16-bit little-endian unsigned value from a register pair.

Performs a single combined write-then-read transaction to fetch two consecutive bytes starting at address, then assembles them as (high << 8) | low.

Parameters:

address – 8-bit base register address (without the command bit). The TSL2591 auto-increments to address + 1.

Returns:

The 16-bit unsigned value (0-65535).

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor._read_u16LE(0x14)
12345

Note

Mutates the shared class-level _BUFFER. Not thread-safe.

_read_u8(address: int) → int

Read one unsigned byte from a TSL2591 register.

Issues an I2C write of the command-bit-OR’d register address, then reads a single byte back into the shared scratch buffer.

Parameters:

address – 8-bit register address (without the 0xA0 command bit; the method ORs it in).

Returns:

The 8-bit value read from address (0-255).

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport if the bus transaction fails.

Example

>>> sensor._read_u8(0x12)
80

Note

Mutates the shared class-level _BUFFER and is therefore neither thread-safe nor re-entrant.

_write_u8(address: int, val: int) → None

Write one unsigned byte to a TSL2591 register.

Sends a two-byte transaction: the command-bit-OR’d register address followed by val masked to 8 bits.

Parameters:

  • address – 8-bit register address (the command bit 0xA0 is OR’d in by the method).

  • val – Value to write; only the low 8 bits are transmitted.

Returns:

None.

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor._write_u8(0x01, 0x10)

Note

Mutates the shared class-level _BUFFER. Not thread-safe.

clear_interrupt(operation: int) → None

Clear pending TSL2591 interrupt flags via a special-function command.

Writes the special-function command byte (_TSL2591_SPECIAL_BIT | operation) so the device clears the requested interrupt bits in status register 0x13.

Parameters:

operation – One of CLEAR_INTERRUPT (ALS only), CLEAR_ALL_INTERRUPTS (ALS + no-persist), or CLEAR_PERSIST_INTERRUPT (no-persist only).

Returns:

None.

Raises:

  • AssertionError – If operation is not one of the allowed clear-command constants.

  • OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.clear_interrupt(adafruit_tsl2591.CLEAR_ALL_INTERRUPTS)

Note

Interrupt clearing is a special-function transaction; it does not target a register address.

disable() → None

Power down the device into low-power sleep mode.

Clears the ENABLE register, halting ADC conversions and dropping the device into its lowest-power state. Configuration registers retain their values across the sleep cycle.

Parameters:

None.

Returns:

None.

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.disable()

Note

Call enable() to resume measurements. While disabled, ALS data registers will not update.

disable_interrupt(interrupts: int) → None

Disable persist-filtered and/or no-persist ALS interrupts.

Read-modify-writes the ENABLE register, clearing the requested interrupt-enable bits while leaving power/AEN state intact.

Parameters:

interrupts – One of ENABLE_NPIEN, ENABLE_AIEN or ENABLE_NPAIEN (both bits combined).

Returns:

None.

Raises:

  • AssertionError – If interrupts is not one of the allowed interrupt-enable masks.

  • OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.disable_interrupt(adafruit_tsl2591.ENABLE_NPAIEN)

Note

Disabling an interrupt does not clear a latched flag; use clear_interrupt() to reset status bits.

enable() → None

Power the device on and enable the ALS engine.

Writes POWERON | AEN to the ENABLE register (0x00), so the device starts the next ADC integration cycle immediately.

Parameters:

None.

Returns:

None.

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.enable()

Note

The constructor calls this automatically; you only need it after a prior disable().

enable_interrupt(interrupts: int) → None

Enable persist-filtered and/or no-persist ALS interrupts.

Read-modify-writes the ENABLE register, OR’ing in the requested interrupt-enable bits. ENABLE_AIEN asserts only after the persist-filter cycle count is met; ENABLE_NPIEN bypasses the persist filter and asserts immediately on threshold breach.

Parameters:

interrupts – One of ENABLE_NPIEN, ENABLE_AIEN or ENABLE_NPAIEN (both bits combined).

Returns:

None.

Raises:

  • AssertionError – If interrupts is not one of the allowed interrupt-enable masks.

  • OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.enable_interrupt(adafruit_tsl2591.ENABLE_AIEN)

Note

The TSL2591 powers on with thresholds at zero, so enabling interrupts may assert immediately until thresholds are set via threshold_low/threshold_high or the nopersist_threshold_* properties.

_BUFFER

Class-level scratch buffer reused for I2C register transactions to avoid per-call allocations. Not thread-safe.

Type:

bytearray

property full_spectrum: int

Full-spectrum (IR + visible) luminosity packed as a 32-bit number.

Computed as (channel_1 << 16) | channel_0 from raw_luminosity.

Parameters:

None.

Returns:

32-bit unsigned packed luminosity value.

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.full_spectrum
1234

Note

This is a packed convenience value, not a physical lux reading – use lux for calibrated illuminance.

Type:

int

property gain: int

Current gain stage of the sensor.

Reads bits 5:4 of the CONTROL register (0x01). Writing sets the same bits, validates the value, and caches it for later lux-coefficient calculations.

Parameters:

val (int) – One of GAIN_LOW (1x), GAIN_MED (25x), GAIN_HIGH (428x) or GAIN_MAX (9876x).

Returns:

The current gain bitfield, masked to bits 5:4.

Return type:

int

Raises:

  • AssertionError – On set, if val is not a recognised gain enum.

  • OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.gain = adafruit_tsl2591.GAIN_HIGH
>>> sensor.gain == adafruit_tsl2591.GAIN_HIGH
True

Note

Lower gain handles bright environments; higher gain favours low-light. Saturation conditions raise an overflow warning from lux.

Type:

int

property infrared: int

Infrared-only luminosity (channel 1, 16-bit unsigned).

Reads raw_luminosity and returns the channel-1 value.

Parameters:

None.

Returns:

16-bit unsigned IR-only luminosity (0-65535).

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.infrared
56

Note

Channel 1 is the IR-only photodiode; subtract it from channel 0 to estimate visible-only luminosity (or use visible).

Type:

int

property integration_time: int

Current ADC integration time enum.

Reads bits 2:0 of the CONTROL register (0x01). Writing validates the value, updates the same bits, and caches the setting for lux scaling.

Parameters:

val (int) – Integer 0-5, equivalent to one of INTEGRATIONTIME_100MS (100 ms) through INTEGRATIONTIME_600MS (600 ms) in 100 ms steps.

Returns:

The current integration-time bitfield (0-5).

Return type:

int

Raises:

  • AssertionError – On set, if val is outside 0..5.

  • OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_300MS
>>> sensor.integration_time
2

Note

The 100 ms setting uses a tighter saturation ceiling (_TSL2591_MAX_COUNT_100MS = 36863); longer integrations saturate at the full 16-bit count (65535).

Type:

int

property lux: float

Calculated illuminance in lux from both ADC channels.

Combines raw_luminosity with the cached gain and integration-time settings using the AMS-recommended counts-per-lux model:

cpl = (atime * again) / LUX_DF

where atime is the integration time in ms, again is the analog gain factor, and LUX_DF = 408.0. Two candidate lux values are computed with the B/C/D glass-attenuation coefficients and the larger is returned.

Parameters:

None.

Returns:

Estimated illuminance in lux (uncalibrated).

Return type:

float

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.lux
42.0

Note

The returned value is not factory-calibrated. If either channel saturates (over _TSL2591_MAX_COUNT_100MS at 100 ms, or _TSL2591_MAX_COUNT otherwise) an overflow warning is printed and the result becomes unreliable – reduce gain.

Type:

float

property nopersist_threshold_high: int

16-bit no-persist ALS high threshold (registers 0x0A-0x0B).

Read returns the assembled 16-bit value; write splits across the NPAIHTL/NPAIHTH register pair.

Parameters:

val (int) – 16-bit unsigned threshold (0-65535).

Returns:

Currently configured no-persist high threshold.

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.nopersist_threshold_high = 60000

Note

Bypasses the persist filter – asserts a no-persist interrupt immediately when the ALS reading exceeds it.

Type:

int

property nopersist_threshold_low: int

16-bit no-persist ALS low threshold (registers 0x08-0x09).

Read returns the assembled 16-bit value; write splits across the NPAILTL/NPAILTH register pair.

Parameters:

val (int) – 16-bit unsigned threshold (0-65535).

Returns:

Currently configured no-persist low threshold.

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.nopersist_threshold_low = 200

Note

Bypasses the persist filter – breach of this threshold asserts a no-persist interrupt immediately.

Type:

int

property persist: int

Interrupt persist filter cycle selector (4-bit code).

The number of consecutive out-of-range ALS cycles required to generate a persist-filtered interrupt. Stored in the low four bits of the persist filter register (0x0C).

Parameters:

val (int) –

Integer 0-15 (inclusive). Mapping:

  • 0 - every ALS cycle generates an interrupt.

  • 1 - any value outside of threshold range.

  • 2 - 2 consecutive out-of-range values.

  • 3 - 3 consecutive out-of-range values.

  • 4 - 5 consecutive out-of-range values.

  • 5 - 10 consecutive out-of-range values.

  • 6 - 15 consecutive out-of-range values.

  • 7 - 20 consecutive out-of-range values.

  • 8 - 25 consecutive out-of-range values.

  • 9 - 30 consecutive out-of-range values.

  • 10 - 35 consecutive out-of-range values.

  • 11 - 40 consecutive out-of-range values.

  • 12 - 45 consecutive out-of-range values.

  • 13 - 50 consecutive out-of-range values.

  • 14 - 55 consecutive out-of-range values.

  • 15 - 60 consecutive out-of-range values.

Returns:

The current 4-bit persist code (0-15).

Return type:

int

Raises:

  • AssertionError – On set, if val is outside 0..15.

  • OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.persist = 3
>>> sensor.persist
3

Note

Only affects ENABLE_AIEN (persist-filtered) interrupts; no-persist interrupts ignore this setting entirely.

Type:

int

property raw_luminosity: tuple[int, int]

Raw channel 0 and channel 1 counts.

Reads the two ADC channel registers (0x14/0x15 for channel 0, 0x16/0x17 for channel 1) and returns them as a (channel_0, channel_1) tuple. Channel 0 captures IR + visible light; channel 1 captures IR only.

Parameters:

None.

Returns:

(channel_0, channel_1) 16-bit unsigned counts (each in the range 0-65535).

Return type:

tuple[int, int]

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.raw_luminosity
(1234, 56)

Note

Saturation caps depend on integration time – channel counts reaching _TSL2591_MAX_COUNT_100MS (at 100 ms) or _TSL2591_MAX_COUNT indicate overflow.

Type:

tuple[int, int]

property threshold_high: int

16-bit ALS interrupt high threshold (registers 0x06-0x07).

Read returns the assembled 16-bit value; write splits and writes the AIHTL/AIHTH register pair.

Parameters:

val (int) – 16-bit unsigned threshold (0-65535).

Returns:

Currently configured high threshold.

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.threshold_high = 50000
>>> sensor.threshold_high
50000

Note

Tied to ENABLE_AIEN; uses the persist filter cycle count before raising an interrupt.

Type:

int

property threshold_low: int

16-bit ALS interrupt low threshold (registers 0x04-0x05).

Read returns the assembled 16-bit value; write splits the value into low and high bytes and writes AILTL/AILTH.

Parameters:

val (int) – 16-bit unsigned threshold (0-65535).

Returns:

Currently configured low threshold.

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.threshold_low = 100
>>> sensor.threshold_low
100

Note

Applies only when persist-filtered ENABLE_AIEN interrupts are enabled; breaches must persist for the configured persist cycles before asserting.

Type:

int

property visible: int

Visible-only luminosity (full spectrum minus IR).

Computes ((channel_1 << 16) | channel_0) - channel_1 from raw_luminosity.

Parameters:

None.

Returns:

Visible-light luminosity as a 32-bit unsigned number.

Return type:

int

Raises:

OSError – Propagated from the underlying I2C transport.

Example

>>> sensor.visible
1178

Note

This is the upstream Adafruit convention – a packed full-spectrum value with the IR channel arithmetically subtracted, not a physical lux value.

Type:

int