HCTSL2561 - Library for TSL2561 Lumin Sensor (HCMODU0102)

Useful guides, libraries, and example sketches to support our Arduino based products.
Post Reply
admin
Site Admin
Posts: 725
Joined: Sun Aug 05, 2012 4:02 pm

HCTSL2561 - Library for TSL2561 Lumin Sensor (HCMODU0102)

Post by admin » Fri May 27, 2016 10:34 am

[IMAGE TBA]



Arduino library for the TSL2561 light to digital converter IC / Module. Currently supported products:

TSL2561 Luminosity Sensor Module (HCMODU0102) available from hobbycomponents.com

This Arduino library can be used to obtain measurements from both photodiode sensors cotained withing the TSL2561. Additionally it can use the information from both sensors to perform a calculated Lux measurement as
perceived by the human eye.


You will need to download (please log in to download the library) and unzip this library to the Arduino development environments library area.

On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

Linux:
Usually found within the users home area under /Arduino/libraries/


Using the TSL2561 library

To use the library just include the HCTSL2561.h header file and then create an instance of the library. E.g:

Code: Select all

#include "HCTSL2561.h"
HCTSL2561 HCTSL2561(TSL2561_I2C_ADD_FLOAT);
TSL2561 and our module can be set to one of 3 I2C address which is dependent on the state of the sensors address select pin (ADDR SEL), or the address selection pads on the HCMODU0102. This can be in one of three states, Low, floating, or high:

TSL2561_I2C_ADD_LOW (I2C address: 0x29)
TSL2561_I2C_ADD_FLOAT (I2C address: 0x39)
TSL2561_I2C_ADD_HIGH (I2C address: 0x49)

By default the HCARDU0102 module is set to TSL2561_I2C_ADD_FLOAT.


To initialise the library add the following line to the setup() section of your sketch:

Code: Select all

HCTSL2561.Init();


The following functions are available with this library:

Code: Select all

HCTSL2561.PowerOn(state);
Powers the sensor up or down where:

state is the power up/down state of the sensor. Valid values are:
false (the sensor is powered down)
true (the sensor is powered up)



Code: Select all

Lux = HCTSL2561.GetLux(iType);
Gets a compensated Lux value by taking a measurement from both sensors and correcting for the IR component where:

iType is the package type of the sensor. Valid values are:
TSL2561_Package_T (T, FN, and CL Package - used by HCMODU0102)
TSL2561_Package_CS (CS package)

For HCMODU0102 use option TSL2561_Package_T for iType.

Returns and unsigned integer containing the light level in Lux.


Code: Select all

Ch0 = HCTSL2561.Get_Chan_0();
Gets the result from channel 0 (visible + IR).

Returns an unsigned integer value containing the measurement result


Code: Select all

Ch1 = HCTSL2561.Get_Chan_1();
Gets the result from channel 1 (IR).

Returns an unsigned integer value containing the measurement result.


Code: Select all

HCTSL2561.SetGain(Gain);
Sets the measurement gain for both sensors where:

Gain is the measurement gain. Valid values are:
TSL2561_GAIN_X1 (gain is set to x1)
TSL2561_GAIN_X16 (gain is set to x16)


Code: Select all

HCTSL2561.SetIntegrationTime(Integ);
Sets the measurement integration time for both sensors where:
Integ is the integration setting. Valid values are:
TSL2561_INTEG_13_7 0 (13.7 ms)
TSL2561_INTEG_101_0 1 (101 ms)
TSL2561_INTEG_402_0 2 (402 ms)


Code: Select all

Lux = HCTSL2561.CalculateLux(ch0, ch1, iType);
Takes the measurements from both sensors and performs a Lux calculation where:

ch0 is the result returned by the Get_Chan_0() library function.
ch1 is the result returned by the Get_Chan_1() library function.
iType is the package type of the sensor. Valid values are:
TSL2561_Package_T (T, FN, and CL Package - used by HCMODU0102)
TSL2561_Package_CS (CS package)

Returns and unsigned integer containing the light level in Lux.



Image

Code: Select all

/* FILE:    HCTSL2561_Example
   DATE:    26/05/16
   VERSION: 0.1
   AUTHOR:  Andrew Davies

   Created by Hobby Components Ltd (HOBBYCOMPONENTS.COM)
   
26/05/16 version 0.1: Original version

   
This Arduino sketch demonstrates how to use the HCTSL2561 library to interface to the
TSL2561 light to digital interface sensor. Although this library and sketch should work with
any module using this sensor it has been written particularly for the Hobby Components
TSL2561 (GY-2561) light to digital interface sensor (HCMODU0102).

The sketch will take measurements from both channels on the sensor: 

Channel 0 is a visible light + IR sensor.
Channel 1 is an IR only sensor. 

The library can also use the results from the two sensors to perform a calculated 
Lux measurement that approximates the human eye response.

To use the module connect it to your Arduino as follows:


TSL2561....Uno/Nano

VCC.......+5V (for HCMODU00102) for other TSL2561 modules check for correct supply voltage.
GND.......GND
SCL.......A5
SDA.......A4


You may copy, alter and reuse this code in any way you like, but please leave
reference to HobbyComponents.com in your comments if you redistribute this code.
This software may not be used directly for the purpose of selling products that
directly compete with Hobby Components Ltd's own range of products.

THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES, WHETHER
EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OR LACK OF NEGLIGENCE.
HOBBY COMPONENTS SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR ANY DAMAGES,
INCLUDING, BUT NOT LIMITED TO, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR ANY
REASON WHATSOEVER.
*/


/* Include the HCTSL2561 library */
#include "HCTSL2561.h"

/* Create an instance of the library */
HCTSL2561 HCTSL2561(TSL2561_I2C_ADD_FLOAT);

void setup() 
{
  /* Initialise the HCTSL2561 library and the serial interface */
  Serial.begin(9600);
  HCTSL2561.Init();
}


void loop() 
{
  unsigned int Ch0, Ch1, Lux;

  /* Take a measurement from channel 0 (visible + IR) */
  Ch0 = HCTSL2561.Get_Chan_0();
  /* Take a measurement from channel 1 (IR) */
  Ch1 = HCTSL2561.Get_Chan_1();

  /* Take a measurement from both channels and calculate the Lux level 
     TSL2561_Package_T is the package type used on the HCMODU0102 */
  Lux = HCTSL2561.GetLux(TSL2561_Package_T);

  /* Output the results to the serial interface */
  Serial.print("Channel 0 (visible + IR):\t");
  Serial.println(Ch0);
  Serial.print("Channel 1 (IR): \t\t");
  Serial.println(Ch1);
  Serial.print("Calculated Lux level:\t\t");
  Serial.println(Lux);
  
  Serial.println();
  delay(1000);
}


Image
HCTSL2561.zip
You do not have the required permissions to view the files attached to this post.

Post Reply