Tutorial by Tristan Meredith

Spring 2017-Physics 295

Wilbur Wright College

TSL2561 Luminosity Sensor with Arduino Uno

In this tutorial, I will be demonstrating how to connect an Arduino Uno to a Sparkfun

TSL2561 Luminosity Sensor, and showing you how to download sample code to run and test
the sensor. I have provided:
A bill of materials
A step by step guide to setting up the Arduino
A guide for connecting the TSL2561
A guide for downloading and running sample code
Additional information on the sensor
Links to additional guides

Bill of Materials
Arduino Uno
Sparkfun TSL2561 Luminosity Sensor
Necessary items for Arduino Uno
Computer (Windows, Mac, or Linux)
An A B USB cable (you can also find these on most printers and they
occasionally come with the Uno)
Various wires (4 at the least)
Breadboard (Optional)

Getting Started
Step 1: Connecting and downloading software for Arduino
Plug in the Arduino with the A B USB Cable into your computer.
If you havent already, youll want to download the Arduino IDE (Integrated Development
Environment) for Windows, Mac, or Linux and follow the instructions to install the
program.
If you are having trouble installing the program you can either follow this Arduino
guide or this Sparkfun guide for a more in depth installation process.
Optionally you can use the online IDE, where you will have to create a username
and password before getting started.
Once the IDE is downloaded you should change a couple settings.
Open the Arduino IDE program, and click on: Tools > Board > Arduino Uno (Or if
you have a different board you will pick that instead).
Again, click on Tools > Serial Port > COM # (The one you pick usually wont be
COM 1 or 2, but to know for sure which one to pick look at the available ports,
then unplug your Arduino. See which port # disappeared, plug your Arduino back
into that same USB port, in then pick that specific COM #).
 Run the blink sample program to make sure the Arduino is working.
In the IDE click on File > Examples > Basics > Blink. Once the code opens you
simply need to click the Upload button (it looks like an arrow).
Once the program is done uploading to your Arduino, you will get a message in
the black bottom portion of the IDE that says Done Uploading. Then you should
notice the onboard LED blinking steadily.
*Note: Once a sketch is running in Arduino, it will continue to run until it is unplugged from
power. If you want to stop a sketch without unplugging the Arduino, simply open a new sketch
and run the blank sketch.

Step 2: Connecting the Arduino to the TSL2561

Connect your pins as shown below, and leave the INT pin disconnected

Arduino Uno TSL 2561

3.3V 3V3
GND GND
A5 SCL
A4 SDA

*Warning*: Do not connect the TSL 3V3 to the 5V Arduino power supply
Step 3: Download Code for TSL2561
For the TSL2561
The sparkfun code for the TSL2561 is already available through the Arduino IDE.
Open the IDE and click: Sketch > Include Library > Manage Library. This will
open the library manager. Enter in the search bar Sparkfun TSL2561 and this is
what it should look like.
Now click on more info, select the latest version, then click install
Now you will need to close and reopen the IDE before we can use the example in
step 4.
For sensors with no code in the Arduino database (using TSL2561 as example)
To test the sensor, we will need to download some code that Sparkfun has created for
the sensor from here: Luminosity Sensor Arduino Code
To download the code, click on the green Clone or download button then click
on Download ZIP. Do not unzip the folder once it is downloaded.
Now, open the Arduino IDE and click: Sketch > Include Library > Add .ZIP
Library then navigate to the zip file location and choose it.
Now you will need to close and reopen the IDE before we can use the example in
step 4.
There are often multiple ways to install libraries. If you need more
resources on how to install or include libraries you can follow these
tutorials from Arduino or Sparkfun: Arduino Library Installation Guide
Sparkfun Library Installation Guide.

Step 4: Run test code for TSL2561

Now to run the code make sure your Arduino is still plugged in, and your sensor is
hooked up correctly, then navigate to and click on Examples > Sparkfun TSL2561 >
Sparkfun TSL2561example
Once the example sketch has loaded click the upload button to run it. When you see the
Done Uploading you will need to open the Serial Monitor (Magnifying Glass looking
button in the top right corner of the IDE) and you should get an output that looks
something like this
*Note: If the code returns a BAD reading, then you will most likely just need to adjust the
sensitivity of the TSL2561. This typically happens when it is too bright, and the data0 or data1
reading returns 65535 which is the sensors maximum reading.

Step 5: Adjust code for optimal readings

There are two different ways you can adjust the sensor readings. One is through
adjusting the integration time of the sensor, and the other is by adjusting the gain.
The integration time is similar to the shutter speed of a camera. It tells the sensor
how long to soak up light. The default setting is 402ms.
The gain setting is similar to the ISO of a camera, and changes the sensitivity of
the TSL2561. The default setting is X1
If it is very bright (or the sensor returns a BAD reading) you have the option to shorten
the integration time with two other preset times. Change the following in the code to set
the times to 13.7ms or 101ms.
// If time = 0, integration will be 13.7ms
// If time = 1, integration will be 101ms
// If time = 2, integration will be 402ms
// If time = 3, use manual start / stop to perform your own integration

unsigned char time = 2; //This is the number to change to 0 (for 13.7ms) or 1 (for
101ms).
Alternatively, if it is very dark, you can change the integration time back to 402ms, and
you can change the gain setting to X16 in this part of the code:
// If gain = false (0), device is set to low gain (1X)
// If gain = high (1), device is set to high gain (16X)

gain = 0; //Change this to 1 if you want a high (16X) gain

Finally, if none of these settings work for you can set your own integration time by
following the comments in the code.

Additional Information
The TSL2561 Luminosity sensor does not actually specifically measure lux. It takes two
separate measurements; one of the visible light spectrum, and one of infrared light. Both types
of light are necessary to approximate the lux that the human eye experiences during daily
conditions. The amount of lux we experience can range from 0.0001 lux to over 100,000 lux
throughout the day and night, and by adjusting the code for optimal readings we can record this
this large range with the TSL2561.
 Additional Resources
Sparkfun has provided the code for the TSL2561 and also has a great tutorial: Sparkfun
TSL2561 Tutorial
Adafruit also has provided a guide and different code for the TSL2561 here: Adafruit
TSL2561 Tutorial