Characteristic Locus
Inheritance System.Object > TSL2561
Implements System.IDisposable
Inherited Members System.Object.ToString() System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.ReferenceEquals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone()
Namespace Meadow.Foundation.Sensors.Light
Assembly TSL2561.dll

Syntax

public class TSL2561 : IDisposable

Remarks

The TSL2561 is alight sensor that is compensated for the presence of infrared light. This compensation allows for the reading to be closer to that experienced by the human eye.

An interrupt pin allows the sensor to generate an interrupt if the sensor reading goes below a lower threshold or exceeds an upper threshold.

The sensor is controlled and data read over the I2C bus.

Purchasing

The TSL2561 is available as a breakout board from the following suppliers:

Examples

Applications using the TSL2561 can operating in two ways:

  • Polled
  • Interrupt driven

Polling Application

A polled application will read the sensor whenever it needs access to a sensor reading. The following application sets the sensor to high gain with an integration cycle of 402 milliseconds. The sensor is then read every 2 seconds:

using System.Threading;
using Meadow;
using Meadow.Foundation.Sensors.Light;

namespace TSL2561_Sample
{
    public class Program
    {
        static IApp _app; 
        public static void Main()
        {
            _app = new App();
        }
    }

    public class App : AppBase<F7Micro, App>
    {
        public App ()
        {
            var tsl2561 = new TSL2561();

            Console.WriteLine("Polled TSL2561 Application.");
            Console.WriteLine("Device ID: " + tsl2561.ID.ToString());

            tsl2561.TurnOff();
            tsl2561.SensorGain = TSL2561.Gain.High;
            tsl2561.Timing = TSL2561.IntegrationTiming.Ms402;
            tsl2561.TurnOn();

            // Wait for at least one integration cycle (set to 402 milliseconds above).
            Thread.Sleep(500);

            // Repeatedly read the light intensity.
            while (true)
            {
                ushort[] adcData = tsl2561.SensorReading;
                Console.WriteLine("Data0: " + adcData[0].ToString() + ", Data1: " + adcData[1].ToString());
                Console.WriteLine("Light intensity: " + tsl2561.Lux.ToString());

                Thread.Sleep(2000);
            }
        }
    }
}

Interrupt Driven Application

In the following application, a threshold window of 100 to 2000 is set. An interrupt will be generated when the light reading on ADC Channel 0 falls below 100 or rises above 2000. In a moderately lit room, covering the sensor will generate a reading below 100 and a low power torch will take the reading above 2000.

using System.Threading;
using Meadow;
using Meadow.Foundation.Sensors.Light;

namespace TSL2561_Sample
{
    public class Program
    {
        static IApp _app; 
        public static void Main()
        {
            _app = new App();
        }
    }

    public class App : AppBase<F7Micro, App>
    {
        public App ()
        {
            var tsl2561 = new TSL2561();

            Console.WriteLine("Testing the TSL2561 Class.");
            Console.WriteLine("Device ID: " + tsl2561.ID.ToString());

            tsl2561.TurnOff();
            tsl2561.SensorGain = TSL2561.Gain.High;
            tsl2561.Timing = TSL2561.IntegrationTiming.Ms402;
            tsl2561.ThresholdLow = 100;
            tsl2561.ThresholdHigh = 2000;
            tsl2561.ReadingOutsideThresholdWindow += tsl2561_ReadingOutsideThresholdWindow;
            tsl2561.SetInterruptMode(TSL2561.InterruptMode.Enable, 1, Pins.GPIO_PIN_D7);
            tsl2561.TurnOn();

            Thread.Sleep(Timeout.Infinite);
        }

        private void tsl2561_ReadingOutsideThresholdWindow(System.DateTime time)
        {
            ushort[] adcData = tsl2561.SensorReading;
            Console.WriteLine("Data0: " + adcData[0].ToString() + ", Data1: " + adcData[1].ToString());
            Console.WriteLine("Light intensity: " + tsl2561.Lux.ToString());
            tsl2561.ClearInterrupt();
        }
    }
}
Example Circuit

The basic configuration of the TSL2561 requires only the data and power connections to be made:

Note that the connection between the Int pin and D9 is only required when using the device in interrupt mode.

Constructors

View Source

TSL2561(II2cBus, Byte, UInt16, Single)

Declaration
public TSL2561(II2cBus i2cBus, byte address = 57, ushort updateInterval = 100, float lightLevelChangeNotificationThreshold = 10F)

Parameters

Type Name Description
II2cBus i2cBus
System.Byte address
System.UInt16 updateInterval
System.Single lightLevelChangeNotificationThreshold

Fields

View Source

MinimumPollingPeriod

Minimum value that should be used for the polling frequency.

Declaration
public const ushort MinimumPollingPeriod = 100

Field Value

Type Description
System.UInt16

Properties

View Source

ID

ID of the sensor.

Declaration
public byte ID { get; }

Property Value

Type Description
System.Byte

Remarks

The ID register (page 16 of the datasheet) gives two pieces of the information: Part Number: bits 4-7 (0000 = TSL2560, 0001 = TSL2561) Revision number: bits 0-3

View Source

LightLevelChangeNotificationThreshold

Changes in light level greater than this value will generate an interrupt in auto-update mode.

Declaration
public float LightLevelChangeNotificationThreshold { get; set; }

Property Value

Type Description
System.Single
View Source

Luminosity

Luminosity reading from the TSL2561 sensor.

Declaration
public float Luminosity { get; set; }

Property Value

Type Description
System.Single
View Source

SensorGain

Gain of the sensor. The sensor gain can be set to high or low.

Declaration
public TSL2561.Gain SensorGain { get; set; }

Property Value

Type Description
TSL2561.Gain

Remarks

The sensor Gain bit can be found in the Timing Register. This allows the gain to be set to High (16x) or Low (1x). See page 14 of the datasheet.

View Source

SensorReading

Get the sensor reading

Declaration
public ushort[] SensorReading { get; }

Property Value

Type Description
System.UInt16[]

Sensor data.

Remarks

This can be used to get the raw sensor data from the TSL2561.

View Source

ThresholdHigh

High interrupt threshold.

Declaration
public ushort ThresholdHigh { get; set; }

Property Value

Type Description
System.UInt16

Remarks

Get or se the upper interrupt threshold. Any readings above this value may trigger an interrupt SetInterruptMode(IIODevice, TSL2561.InterruptMode, Byte, IPin) See page 14/15 of the datasheet.

View Source

ThresholdLow

Lower interrupt threshold.

Declaration
public ushort ThresholdLow { get; set; }

Property Value

Type Description
System.UInt16

Remarks

Get or se the lower interrupt threshold. Any readings below this value may trigger an interrupt SetInterruptMode(IIODevice, TSL2561.InterruptMode, Byte, IPin) See page 14/15 of the datasheet.

View Source

Timing

Integration timing for the sensor reading.

Declaration
public TSL2561.IntegrationTiming Timing { get; set; }

Property Value

Type Description
TSL2561.IntegrationTiming

Methods

View Source

ClearInterrupt()

Clear the interrupt flag. Se Command Register on page 13 of the datasheet.

Declaration
public void ClearInterrupt()

Remarks

According to the datasheet, writing a 1 into bit 6 of the command register will clear any pending interrupts.

View Source

Dispose()

Implement IDisposable interface.

Declaration
public void Dispose()
View Source

ManualStart()

Put the sensor into manual integration mode.

Declaration
public void ManualStart()
View Source

ManualStop()

Turn off manual integration mode.

Declaration
public void ManualStop()
View Source

SetInterruptMode(IIODevice, TSL2561.InterruptMode, Byte, IPin)

Turn interrupts on or off and set the conversion trigger count.

Declaration
public void SetInterruptMode(IIODevice device, TSL2561.InterruptMode mode, byte conversionCount, IPin pin = null)

Parameters

Type Name Description
IIODevice device
TSL2561.InterruptMode mode
System.Byte conversionCount

Number of conversions that must be outside of the threshold before an interrupt is generated.

IPin pin

GPIO pin connected to the TSL2561 interrupt pin. Set to null to use the previously supplied pin.

Remarks

The conversion count is the number of conversions that must be outside of the upper and lower limits before and interrupt is generated. See Interrupt Control Register on page 15 and 16 of the datasheet.

View Source

TurnOff()

Turn the TSL2561 off.

Declaration
public void TurnOff()

Remarks

Reset the power bits in the control register (page 13 of the datasheet).

View Source

TurnOn()

Turn the TSL2561 on.

Declaration
public void TurnOn()

Remarks

Set the power bits in the control register (page 13 of the datasheet).

View Source

Update()

Update the Luminosity reading.

Declaration
public void Update()

Events

View Source

LightLevelChanged

Event raised when the temperature change is greater than the TemperatureChangeNotificationThreshold value.

Declaration
public event EventHandler<float> LightLevelChanged

Event Type

Type Description
System.EventHandler<System.Single>
View Source

ReadingOutsideThresholdWindow

Interrupt generated when the reading is outside of the threshold window.

Declaration
public event TSL2561.ThresholdInterrupt ReadingOutsideThresholdWindow

Event Type

Type Description
TSL2561.ThresholdInterrupt

Remarks

This interrupt requires the threshold window to be defined SetInterruptMode(IIODevice, TSL2561.InterruptMode, Byte, IPin) and for the interrupts to be enabled.