It's easy to use the TSL2591 sensor with Python and CircuitPython and the Adafruit CircuitPython TSL2591 module. This module allows you to easily write Python code that reads the luminosity and more from the sensor.
You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.
CircuitPython Microcontroller Wiring
First wire up a TSL2591 to your board exactly as shown on the previous pages for Arduino using an I2C connection. Here's an example of wiring a Feather M0 to the sensor with I2C:
-
Board 3V to sensor VIN (red wire on STEMMA QT version)
- Board GND to sensor GND (black wire on STEMMA QT version)
- Board SCL to sensor SCL (yellow wire on STEMMA QT version)
- Board SDA to sensor SDA (blue wire on STEMMA QT version)
Python Computer Wiring
Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.
Here's the Raspberry Pi wired with I2C:
- Pi 3V3 to sensor VIN (red wire on STEMMA QT version)
- Pi GND to sensor GND (black wire on STEMMA QT version)
- Pi SCL to sensor SCK (yellow wire on STEMMA QT version)
- Pi SDA to sensor SDA (blue wire on STEMMA QT version)
CircuitPython Installation of TSL2591
Next you'll need to install the Adafruit CircuitPython TSL2591 library on your CircuitPython board.
First make sure you are running the latest version of Adafruit CircuitPython for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.
Remember for non-express boards like the, you'll need to manually install the necessary libraries from the bundle:
- adafruit_tsl2591.mpy
- adafruit_bus_device
Before continuing make sure your board's lib folder or root filesystem has the adafruit_tsl2591.mpy, and adafruit_bus_device files and folders copied over.
Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.
CircuitPython and Python Usage
To demonstrate the usage of the sensor we'll initialize it and read the luminosity from the board's Python REPL. Run the following code to import the necessary modules and initialize the I2C connection with the sensor:
import board import adafruit_tsl2591 i2c = board.I2C() sensor = adafruit_tsl2591.TSL2591(i2c)
Now you're ready to read values from the sensor using any of these properties:
- lux - The computed light lux value measured by the sensor.
- visible - The visible light level measured by the sensor. This is a 32-bit unsigned value with no units, the higher the number the more visible light.
- infrared - The infrared light level measured by the sensor. This is a 16-bit unsigned value with no units, the higher the number the more infrared light.
- full_spectrum - The visible & infrared light level measured by the sensor as a single 32-bit value with no units. The higher the number the more full spectrum light.
- raw_luminosity - A 2-tuple of raw sensor visible+IR and IR only light levels. Each is a 16-bit value with no units where the higher the value the more light.
print('Light: {0}lux'.format(sensor.lux))
print('Visible: {0}'.format(sensor.visible))
print('Infrared: {0}'.format(sensor.infrared))
In addition you can read and write a few properties to change how the sensor behaves and is configured:
-
gain- Set this to a value below to change the gain of the light sensor:-
adafruit_tsl2591.GAIN_LOW- 1x gain -
adafruit_tsl2591.GAIN_MED- 25x gain (the default) -
adafruit_tsl2591.GAIN_HIGH- 428x gain -
adafruit_tsl2591.GAIN_MAX- 9876x gain
-
-
integration_time- Set the integration time of the sensor to a value of:-
adafruit_tsl2591.INTEGRATIONTIME_100MS- 100ms (the default) -
adafruit_tsl2591.INTEGRATIONTIME_200MS- 200ms -
adafruit_tsl2591.INTEGRATIONTIME_300MS- 300ms -
adafruit_tsl2591.INTEGRATIONTIME_400MS- 400ms -
adafruit_tsl2591.INTEGRATIONTIME_500MS- 500ms -
adafruit_tsl2591.INTEGRATIONTIME_600MS- 600ms
-
sensor.gain = adafruit_tsl2591.GAIN_LOW sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_200MS
That's all there is to using the TSL2591 sensor with CircuitPython!
Below is a complete example that will print the light level every second. Save this as code.py on the board and view the output in the REPL.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
# Simple demo of the TSL2591 sensor. Will print the detected light value
# every second.
import time
import board
import adafruit_tsl2591
# Create sensor object, communicating over the board's default I2C bus
i2c = board.I2C() # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C() # For using the built-in STEMMA QT connector on a microcontroller
# Initialize the sensor.
sensor = adafruit_tsl2591.TSL2591(i2c)
# You can optionally change the gain and integration time:
# sensor.gain = adafruit_tsl2591.GAIN_LOW (1x gain)
# sensor.gain = adafruit_tsl2591.GAIN_MED (25x gain, the default)
# sensor.gain = adafruit_tsl2591.GAIN_HIGH (428x gain)
# sensor.gain = adafruit_tsl2591.GAIN_MAX (9876x gain)
# sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_100MS (100ms, default)
# sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_200MS (200ms)
# sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_300MS (300ms)
# sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_400MS (400ms)
# sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_500MS (500ms)
# sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_600MS (600ms)
# Read the total lux, IR, and visible light levels and print it every second.
while True:
# Read and calculate the light level in lux.
lux = sensor.lux
print("Total light: {0}lux".format(lux))
# You can also read the raw infrared and visible light levels.
# These are unsigned, the higher the number the more light of that type.
# There are no units like lux.
# Infrared levels range from 0-65535 (16-bit)
infrared = sensor.infrared
print("Infrared light: {0}".format(infrared))
# Visible-only levels range from 0-2147483647 (32-bit)
visible = sensor.visible
print("Visible light: {0}".format(visible))
# Full spectrum (visible + IR) also range from 0-2147483647 (32-bit)
full_spectrum = sensor.full_spectrum
print("Full spectrum (IR + visible) light: {0}".format(full_spectrum))
time.sleep(1.0)
Text editor powered by tinymce.
