Adafruit Light Sensor TSL2591

This project is an example on how to use the Adafruit light sensor TSL2591 in Raspberry PI and Windows 10 IoT Core.

What is this sensor?

https://www.adafruit.com/products/1980

The TSL2591 luminosity sensor is an advanced digital light sensor, ideal for use in a wide range of light situations. This sensor is very precise, allowing for exact lux calculations and can be configured for different gain/timing ranges to detect light ranges from 188 uLux up to 88,000 Lux on the fly.

How to connect this sensor into Raspberry PI?

To connect this sensor to Raspberry PI you need 4 wires. Two of the wires used for voltage Vin (+3V from Raspberry) and ground GND and remaining two are used for data. As this is digital sensor, it uses I2C protocol to communicate with the Raspberry. For I2C we need two wires, Data (SDA) and Clock (SCL). Connect sensor SDA and SCL pins accordingly to Raspberry SDA and SCL pins.

How do I write the code?

I made it very simple for you. You just need to add NuGet package RobootikaCOM.TSL2591 to your project and you are almost done :)

Right-click in your project name and then "Manage NuGet packages"

Open "Browse" tab, write "robootika" in search-window and then install RobootikaCOM.TSL2591 package into your project.

After adding this NuGet package, you just need to write 3 lines of code.

1. Add reference to this module

using RobootikaCOM.TSL2591;

2. Create an object for sensor:

        private TSL2591 TSL2591Sensor = new TSL2591();

3. Write a while-loop, to read data from the sensor in every 1 sec.

            while (true)
            {
                double currentLux = TSL2591Sensor.GetLux();
                Task.Delay(1000).Wait();
            }

Final code looks like this. If you run it, you do not see anything, because it just reads the data, but it doesnt show it anywhere. You need to integrate this project with my other example, where I teach how to send this data into Azure.

using Windows.ApplicationModel.Background;
using System.Threading.Tasks;
using RobootikaCOM.TSL2591;

namespace LessonLightSensorTSL2591
{
    public sealed class StartupTask : IBackgroundTask
    {
        private TSL2591 TSL2591Sensor = new TSL2591();

        public void Run(IBackgroundTaskInstance taskInstance)
        {
            while (true)
            {
                double currentLux = TSL2591Sensor.GetLux();
                Task.Delay(1000).Wait();
            }
        }
    }
}

Advanced sensor tuning: timing and gain

This sensor support five different timing and three gain options.

• Timing: this means how many samples the sensor will take before calculating the light level. Changing the integration time gives you a longer time over which to sense light. Longer timelines are slower, but are good in very low light situtations! This sensor has three parameters for timing.
  • 100ms the shortest measure time, use in bright light
  • 200ms average measure time, use in medium light (default)
  • 300ms average measure time, use in medium light
  • 400ms long measure time, use in dim light
  • 500ms long measure time, use in dim light

        TSL2591.INT_TIME_100MS;
        TSL2591.INT_TIME_200MS;
        TSL2591.INT_TIME_300MS;
        TSL2591.INT_TIME_400MS;
        TSL2591.INT_TIME_500MS;

• Gain: You can change the gain on the fly, to adapt to brighter/dimmer light situations.
  • TSL2591.GAIN_LOW: use in bright light
  • TSL2591.GAIN_MED: use in average light (default)
  • TSL2591.GAIN_HIGH: use in very dim light
  • TSL2591.GAIN_MAX: use in darkness

Tu use timing and gain, you need to write one additional line of code. First parameter for method SetTiming is gain and second parameter is timing. For example, setting gain MAX and timing maximum (500ms), you can measure almost complete darkness.

        public void Run(IBackgroundTaskInstance taskInstance)
        {
            TSL2591Sensor.SetGain(TSL2591.GAIN_HIGH, TSL2591.INT_TIME_500MS);
            while (true)
            {
                double currentLux = TSL2591Sensor.GetLux();
                Task.Delay(1000).Wait();
            }
        }

Can I change I2C address?

I2C address is used to communicate with the sensor. Many sensors have I2C address hardcoded, and this sensor exactly this. You cannot change I2C address, it is fixed to 0x29

Sensor technical Details

• Extremely wide dynamic range 600,000,000:1
• Lux Range: 188 uLux sensitivity, up to 88,000 Lux input measurements.
• Temperature range: -30 to 80 *C
• Voltage range: 3.3-5V into onboard regulator
• Interface: I2C
• This board/chip uses I2C 7-bit address 0x29 (fixed)

Indoor and outdoor lighting conditions

Illuminance	Example
0.002 lux	Moonless clear night sky
0.2 lux	Design minimum for emergency lighting (AS2293).
0.27 - 1 lux	Full moon on a clear night
3.4 lux	Dark limit of civil twilight under a clear sky
50 lux	Family living room
80 lux	Hallway/toilet
100 lux	Very dark overcast day
300 - 500 lux	Sunrise or sunset on a clear day. Well-lit office area.
1,000 lux	Overcast day; typical TV studio lighting
10,000 - 25,000 lux	Full daylight (not direct sun)
32,000 - 130,000 lux	Direct sunlight