adafruit / adafruit/Adafruit_CircuitPython_TSL2591

TSL2591 lux property can return negative values at low light — should clamp to 0

Open Beginner friendly
#33 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
19
Forks
15
PR merge metrics
No merged PRs in 30d

Description

**Summary**
The `lux` property in the CircuitPython `TSL2591` driver can return small negative lux values (e.g. -3.51) in low-light/night conditions. Lux is a physical quantity that should not be negative; at minimum it should be clamped to 0. I encountered negative values while reading the sensor at night.

**Repository / File**
Repository: `Adafruit_CircuitPython_TSL2591`
File: `adafruit_tsl2591.py`
Context: the [lux](vscode-file://vscode-app/usr/share/code-insiders/resources/app/out/vs/code/electron-browser/workbench/workbench.html) calculation computes two candidate lux values ([lux1](vscode-file://vscode-app/usr/share/code-insiders/resources/app/out/vs/code/electron-browser/workbench/workbench.html), [lux2](vscode-file://vscode-app/usr/share/code-insiders/resources/app/out/vs/code/electron-browser/workbench/workbench.html)) and currently returns [max(lux1, lux2)](vscode-file://vscode-app/usr/share/code-insiders/resources/app/out/vs/code/electron-browser/workbench/workbench.html) which can be negative if both candidates are negative due to noise / IR-dominant readings.

**Actual behavior**
`lux` can be negative (e.g. -3.51) under low-light conditions.

**Expected behavior**
`lux` should never be negative. When the computed lux candidates are negative (due to noise, IR-dominant conditions, or small counts), the method should return 0.0 (or otherwise clamp to a non-negative value).

**Suggested fix**
Clamp the returned lux to be non-negative. For example, replace:
```python
lux1 = (channel_0 - (_TSL2591_LUX_COEFB * channel_1)) / cpl
lux2 = ((_TSL2591_LUX_COEFC * channel_0) - (_TSL2591_LUX_COEFD * channel_1)) / cpl
return max(lux1, lux2)
```
with:
```python
# ensure lux is never negative
return max(0.0, lux1, lux2)
```

This is a minimal, backwards-compatible change that avoids reporting non-physical negative lux values.

Contributor guide

No contributing guide indexed for this repository

Research direction

Open adafruit_tsl2591.py and locate the lux property and its lux1/lux2 calculation. Review how the two candidates are selected, then verify that low-light or negative candidates produce a non-negative result. Done means the lux property returns 0.0 when both candidates are negative while preserving positive readings.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
embedded-iot
Issue type
Bug
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.