adafruit / adafruit_circuitpython_tsl2591

CircuitPython module for the TSL2591 high precision light sensor.

Introduction

CircuitPython module for the TSL2591 high precision light sensor.

Dependencies

This driver depends on:

• Adafruit CircuitPython
• Bus Device

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-tsl2591

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-tsl2591

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install adafruit-circuitpython-tsl2591

Usage Example

See examples/tsl2591_simpletest.py for a demo of the usage.

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

adafruit_circuitpython_tsl2591's Issues

RuntimeError: Overflow reading light channels! could maybe suggest lowering the gain

Sample code is at 25x gain so a decent flashlight will exceed the light level pretty easily and crash the program with the error https://learn.adafruit.com/adafruit-tsl2591/python-circuitpython#full-example-code-2997857-15
Perhaps the error could let the user know to lower the gain?

Equation for Lux calculation does not reflect Library

The calculations in this project (CircuitPython) reference the AdatFruit_TSL2591_Library, but the equations do not match.

https://github.com/adafruit/Adafruit_TSL2591_Library/blob/master/Adafruit_TSL2591.cpp#L220

This project does take into account the max_count for saturation and sensor overflow, but the source project does not.

TSL2591 overflows under direct sunlight despite GAIN_LOW INTEGRATIONTIME_100MS options set

The error message discussed here is helpful, but my tsl2591 is under direct sunlight with GAIN_LOW and INTEGRATIONTIME_100MS and the code keeps crashing... With this configuration isn't this sensor supposed to work even under these extreme light conditions? I'm copying my code below for reference.

import board
import adafruit_tsl2591
import time
import requests
i2c = board.I2C()
sensor = adafruit_tsl2591.TSL2591(i2c)
sensor.gain = adafruit_tsl2591.GAIN_LOW
sensor.integration_time = adafruit_tsl2591.INTEGRATIONTIME_100MS
READING_DELAY = 1
time.sleep(READING_DELAY)
print(sensor.lux)

AttributeError: 'SMBus' object has no attribute 'write_bytes'

Hi, I wrote the following code in the light of your example tsl2591_simpletest.py. It's working fine. But if I call the method getTSL2591Data() from another Python file, I faced an error: AttributeError: 'SMBus' object has no attribute 'write_bytes'

I have Python3 enviroment in RPi 3.

This works fine by self, getTSL2591.py:

import json
import board
import busio
import adafruit_tsl2591

def getTSL2591Data():
	# Initialize the I2C bus.
	i2c = busio.I2C(board.SCL, board.SDA)

	# Initialize the sensor.
	sensor = adafruit_tsl2591.TSL2591(i2c)
	
	measurementArr = {}
	try:
		# Read the total lux, IR, and visible light levels
		measurementArr = {'lux': round(sensor.lux,2), 'infrared': round(sensor.infrared,2), 'visible': round(sensor.visible,2), 'full_spectrum': round(sensor.full_spectrum,2)}
	except RuntimeError as e:
		print("Reading from TSL2591 failure: ",e.args)
	except NameError:
		print("NameError")
	finally:
		return json.dumps(measurementArr, sort_keys=True)

try:
	if __name__ == "__main__":
		print(getTSL2591Data())
    
except KeyboardInterrupt:
	print("Exit!")

The file getTele.py: I call getTSL2591.getTSL2591Data() method in this file

import time
import datetime
import json
import getTSL2591

def getTelemetryData():
	TSL2591Data = json.loads(getTSL2591.getTSL2591Data())

	dateTimeNow = datetime.datetime.now()
	dateTimeNow = dateTimeNow.strftime("%d.%m.%Y %H:%M:%S")
	measurementArr = {}

	measurementArr = {'measuringTime': dateTimeNow, 'lux': TSL2591Data['lux'], 'infrared': TSL2591Data['infrared'], 'visible': TSL2591Data['visible'], 'full_spectrum': TSL2591Data['full_spectrum'] }

	return json.dumps(measurementArr, sort_keys=True)

try:
    if __name__ == "__main__":
        time.sleep(1)
        print(getTelemetryData())
    
except KeyboardInterrupt:
    print("Exit!")

And then, the following error occurs:

Traceback (most recent call last):
  File "getTele.py", line 20, in <module>
    print(getTelemetryData())
  File "getTele.py", line 7, in getTelemetryData
    TSL2591Data = json.loads(getTSL2591.getTSL2591Data())
  File "/var/www/html/python/getTSL2591.py", line 12, in getTSL2591Data
    sensor = adafruit_tsl2591.TSL2591(i2c)
  File "/usr/local/lib/python3.5/dist-packages/adafruit_circuitpython_tsl2591-1.1.1.dev8+g8a9647b-py3.5.egg/adafruit_tsl2591.py", line 113, in __init__
  File "/usr/local/lib/python3.5/dist-packages/adafruit_circuitpython_busdevice-2.2.5-py3.5.egg/adafruit_bus_device/i2c_device.py", line 64, in __init__
  File "/usr/local/lib/python3.5/dist-packages/Adafruit_Blinka-0.2.3-py3.5.egg/busio.py", line 63, in writeto
  File "/usr/local/lib/python3.5/dist-packages/Adafruit_Blinka-0.2.3-py3.5.egg/adafruit_blinka/microcontroller/raspi_23/i2c.py", line 38, in writeto
AttributeError: 'SMBus' object has no attribute 'write_bytes'

ATime not accounted for in Overflow Detection

Adafruit_CircuitPython_TSL2591/adafruit_tsl2591.py

Line 252 in 0fa3c2e

if channel_0 == 0xFFFF or channel_1 == 0xFFFF:

This should use the ATime reference to determine the resolution for Overflow. If 100 ms, this is >= 36863 counts for an overflow.

37889 observed for saturation in the VIR channel, which exceeds the datasheet value of 36863 (0x8FFF)

Missing Type Annotations

There are missing type annotations for some functions in this library.

The typing module does not exist on CircuitPython devices so the import needs to be wrapped in try/except to catch the error for missing import. There is an example of how that is done here:

try:
    from typing import List, Tuple
except ImportError:
    pass

Once imported the typing annotations for the argument type(s), and return type(s) can be added to the function signature. Here is an example of a function that has had this done already:

def wrap_text_to_pixels(
    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
) -> List[str]:

If you are new to Git or Github we have a guide about contributing to our projects here: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

There is also a guide that covers our CI utilities and how to run them locally to ensure they will pass in Github Actions here: https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/check-your-code In particular the pages: Sharing docs on ReadTheDocs and Check your code with pre-commit contain the tools to install and commands to run locally to run the checks.

If you are attempting to resolve this issue and need help, you can post a comment on this issue and tag both @FoamyGuy and @kattni or reach out to us on Discord: https://adafru.it/discord in the #circuitpython-dev channel.

The following locations are reported by mypy to be missing type annotations:

• adafruit_tsl2591.py:121
• adafruit_tsl2591.py:134
• adafruit_tsl2591.py:145
• adafruit_tsl2591.py:156
• adafruit_tsl2591.py:191
• adafruit_tsl2591.py:216

DisplayIO Example Wanted

Add a Basic DisplayIO Based Example

We would like to have a basic displayio example for this library. The example should be written for microcontrollers with a built-in display. At a minimum it should show a Label on the display and update it with live readings from the sensor.

The example should not be overly complex, it's intended to be a good starting point for displayio based projects that utilize this sensor library. Try to keep all visual content as near to the top left corner as possible in order to best fascilitate devices with small built-in display resolutions.

The new example should follow the naming convention examples/libraryname_displayio_simpletest.py with "libraryname" being replaced by the actual name of this library.

You can find an example of a Pull Request that adds this kind of example here: adafruit/Adafruit_CircuitPython_BME680#72

We have a guide that covers the process of contributing with git and github: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

If you're interested in contributing but need additional help, or just want to say hi, feel free to join the Discord server to ask questions: https://adafru.it/discord