Skip to content

TSL2591

Works with

Any CircuitPython board with I2C

What it does

The TSL2591 is a high dynamic range light sensor capable of measuring from 188 µlux (near darkness) all the way to 88,000 lux (bright sunlight) — a range of roughly 600 million to one. It has two photodiodes: one for visible plus infrared light and one for infrared only, letting you calculate visible-only light by subtraction. Common uses include automatic brightness control, data logging, and any application where lighting spans very different conditions.

Installing the library

Download adafruit_tsl2591.mpy from the Adafruit CircuitPython Bundle and copy it to the lib/ folder on your board.

Quick start

import board
import busio
import adafruit_tsl2591

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_tsl2591.TSL2591(i2c)

print(f"Lux: {sensor.lux}")
print(f"Visible: {sensor.visible}")
print(f"Infrared: {sensor.infrared}")
print(f"Full spectrum: {sensor.full_spectrum}")

Key things you can do

What you want How to do it
Read lux sensor.lux
Read visible light only sensor.visible
Read infrared only sensor.infrared
Read full spectrum (visible + IR) sensor.full_spectrum
Set gain sensor.gain = adafruit_tsl2591.GAIN_LOW — options: GAIN_LOW, GAIN_MED, GAIN_HIGH, GAIN_MAX
Set integration time sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_100MS — range: 100ms to 600ms
Check for overflow sensor.lux returns 0 if the sensor is saturated — reduce gain or integration time

Reading the official docs

Full API reference: https://docs.circuitpython.org/projects/tsl2591/en/latest/

Key things to look up:

  • Gain and integration time both affect sensitivity — in bright conditions use low gain and short integration time; in dark conditions use high gain and long integration time
  • full_spectrum is a 32-bit value combining both channels; visible and infrared are derived from it
  • Overflow (saturation) returns lux = 0 — this is a sentinel value, not a real reading

Projects using this library