Add support for TSL2561 (#661, #1311)

Add support for TSL2561 (#661, #1311)

lib/TSL2561-Arduino-Library/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,46 @@
+Thank you for opening an issue on an Adafruit Arduino library repository.  To
+improve the speed of resolution please review the following guidelines and
+common troubleshooting steps below before creating the issue:
+
+- **Do not use GitHub issues for troubleshooting projects and issues.**  Instead use
+  the forums at http://forums.adafruit.com to ask questions and troubleshoot why
+  something isn't working as expected.  In many cases the problem is a common issue
+  that you will more quickly receive help from the forum community.  GitHub issues
+  are meant for known defects in the code.  If you don't know if there is a defect
+  in the code then start with troubleshooting on the forum first.
+
+- **If following a tutorial or guide be sure you didn't miss a step.** Carefully
+  check all of the steps and commands to run have been followed.  Consult the
+  forum if you're unsure or have questions about steps in a guide/tutorial.
+
+- **For Arduino projects check these very common issues to ensure they don't apply**:
+
+  - For uploading sketches or communicating with the board make sure you're using
+    a **USB data cable** and **not** a **USB charge-only cable**.  It is sometimes
+    very hard to tell the difference between a data and charge cable!  Try using the
+    cable with other devices or swapping to another cable to confirm it is not
+    the problem.
+
+  - **Be sure you are supplying adequate power to the board.**  Check the specs of
+    your board and plug in an external power supply.  In many cases just
+    plugging a board into your computer is not enough to power it and other
+    peripherals.
+
+  - **Double check all soldering joints and connections.**  Flakey connections
+    cause many mysterious problems.  See the [guide to excellent soldering](https://learn.adafruit.com/adafruit-guide-excellent-soldering/tools) for examples of good solder joints.
+
+  - **Ensure you are using an official Arduino or Adafruit board.** We can't
+    guarantee a clone board will have the same functionality and work as expected
+    with this code and don't support them.
+
+If you're sure this issue is a defect in the code and checked the steps above
+please fill in the following fields to provide enough troubleshooting information.
+You may delete the guideline and text above to just leave the following details:
+
+- Arduino board:  **INSERT ARDUINO BOARD NAME/TYPE HERE**
+
+- Arduino IDE version (found in Arduino -> About Arduino menu):  **INSERT ARDUINO
+  VERSION HERE**
+
+- List the steps to reproduce the problem below (if possible attach a sketch or
+  copy the sketch code in too): **LIST REPRO STEPS BELOW**

lib/TSL2561-Arduino-Library/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+Thank you for creating a pull request to contribute to Adafruit's GitHub code!
+Before you open the request please review the following guidelines and tips to
+help it be more easily integrated:
+
+- **Describe the scope of your change--i.e. what the change does and what parts
+  of the code were modified.**  This will help us understand any risks of integrating
+  the code.
+
+- **Describe any known limitations with your change.**  For example if the change
+  doesn't apply to a supported platform of the library please mention it.
+
+- **Please run any tests or examples that can exercise your modified code.**  We
+  strive to not break users of the code and running tests/examples helps with this
+  process.
+
+Thank you again for contributing!  We will try to test and integrate the change
+as soon as we can, but be aware we have many GitHub repositories to manage and
+can't immediately respond to every request.  There is no need to bump or check in
+on a pull request (it will clutter the discussion of the request).
+
+Also don't be worried if the request is closed or not integrated--sometimes the
+priorities of Adafruit's GitHub code (education, ease of use) might not match the
+priorities of the pull request.  Don't fret, the open source community thrives on
+forks and GitHub makes it easy to keep your changes in a forked repo.
+
+After reviewing the guidelines above you can delete this text from the pull request.

lib/TSL2561-Arduino-Library/README.txt

@@ -0,0 +1,7 @@
+This is an Arduino library for the TSL2561 digital luminosity (light) sensors. 
+
+Pick one up at http://www.adafruit.com/products/439
+
+To download. click the DOWNLOADS button in the top right corner, rename the uncompressed folder TSL2561. Check that the TSL2561 folder contains TSL2561.cpp and TSL2561.h
+
+Place the TSL2561 library folder your <arduinosketchfolder>/libraries/ folder. You may need to create the libraries subfolder if its your first library. Restart the IDE.

lib/TSL2561-Arduino-Library/TSL2561.cpp

@@ -0,0 +1,301 @@
+/**************************************************************************/
+/*! 
+    @file     tsl2561.c
+    @author   K. Townsend (microBuilder.eu / adafruit.com)
+
+    @section LICENSE
+
+    Software License Agreement (BSD License)
+
+    Copyright (c) 2010, microBuilder SARL, Adafruit Industries
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+    1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+    3. Neither the name of the copyright holders nor the
+    names of its contributors may be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
+    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+/**************************************************************************/
+
+#if defined ( ESP8266 )
+  #include <pgmspace.h>
+#else
+  #include <avr/pgmspace.h>
+  #include <util/delay.h>
+#endif
+#include <stdlib.h>
+
+#include "TSL2561.h"
+
+TSL2561::TSL2561(uint8_t addr) {
+  _addr = addr;
+  _initialized = false;
+  _integration = TSL2561_INTEGRATIONTIME_13MS;
+  _gain = TSL2561_GAIN_16X;
+
+  // we cant do wire initialization till later, because we havent loaded Wire yet
+}
+
+boolean TSL2561::begin(void) {
+  Wire.begin();
+
+ // Initialise I2C
+  Wire.beginTransmission(_addr);
+#if ARDUINO >= 100
+  Wire.write(TSL2561_REGISTER_ID);
+#else
+  Wire.send(TSL2561_REGISTER_ID);
+#endif
+  Wire.endTransmission();
+  Wire.requestFrom(_addr, 1);
+#if ARDUINO >= 100
+  int x = Wire.read();
+#else
+  int x = Wire.receive();
+#endif
+  //Serial.print("0x"); Serial.println(x, HEX);
+  if (x & 0x0A ) {
+    //Serial.println("Found TSL2561");
+  } else {
+    return false;
+  }
+  _initialized = true;
+
+  // Set default integration time and gain
+  setTiming(_integration);
+  setGain(_gain);
+  // Note: by default, the device is in power down mode on bootup
+  disable();
+
+  return true;
+}
+
+void TSL2561::enable(void)
+{
+  if (!_initialized) begin();
+
+  // Enable the device by setting the control bit to 0x03
+  write8(TSL2561_COMMAND_BIT | TSL2561_REGISTER_CONTROL, TSL2561_CONTROL_POWERON);
+}
+
+void TSL2561::disable(void)
+{
+  if (!_initialized) begin();
+
+  // Disable the device by setting the control bit to 0x03
+  write8(TSL2561_COMMAND_BIT | TSL2561_REGISTER_CONTROL, TSL2561_CONTROL_POWEROFF);
+}
+
+
+void TSL2561::setGain(tsl2561Gain_t gain) {
+  if (!_initialized) begin();
+
+  enable();
+  _gain = gain;
+  write8(TSL2561_COMMAND_BIT | TSL2561_REGISTER_TIMING, _integration | _gain);  
+  disable();
+}
+
+void TSL2561::setTiming(tsl2561IntegrationTime_t integration)
+{
+  if (!_initialized) begin();
+
+  enable();
+  _integration = integration;
+  write8(TSL2561_COMMAND_BIT | TSL2561_REGISTER_TIMING, _integration | _gain);  
+  disable();
+}
+
+uint32_t TSL2561::calculateLux(uint16_t ch0, uint16_t ch1)
+{
+  unsigned long chScale;
+  unsigned long channel1;
+  unsigned long channel0;
+
+  switch (_integration)
+  {
+    case TSL2561_INTEGRATIONTIME_13MS:
+      chScale = TSL2561_LUX_CHSCALE_TINT0;
+      break;
+    case TSL2561_INTEGRATIONTIME_101MS:
+      chScale = TSL2561_LUX_CHSCALE_TINT1;
+      break;
+    default: // No scaling ... integration time = 402ms
+      chScale = (1 << TSL2561_LUX_CHSCALE);
+      break;
+  }
+
+  // Scale for gain (1x or 16x)
+  if (!_gain) chScale = chScale << 4;
+
+  // scale the channel values
+  channel0 = (ch0 * chScale) >> TSL2561_LUX_CHSCALE;
+  channel1 = (ch1 * chScale) >> TSL2561_LUX_CHSCALE;
+
+  // find the ratio of the channel values (Channel1/Channel0)
+  unsigned long ratio1 = 0;
+  if (channel0 != 0) ratio1 = (channel1 << (TSL2561_LUX_RATIOSCALE+1)) / channel0;
+
+  // round the ratio value
+  unsigned long ratio = (ratio1 + 1) >> 1;
+
+  unsigned int b, m;
+
+#ifdef TSL2561_PACKAGE_CS
+  if ((ratio >= 0) && (ratio <= TSL2561_LUX_K1C))
+    {b=TSL2561_LUX_B1C; m=TSL2561_LUX_M1C;}
+  else if (ratio <= TSL2561_LUX_K2C)
+    {b=TSL2561_LUX_B2C; m=TSL2561_LUX_M2C;}
+  else if (ratio <= TSL2561_LUX_K3C)
+    {b=TSL2561_LUX_B3C; m=TSL2561_LUX_M3C;}
+  else if (ratio <= TSL2561_LUX_K4C)
+    {b=TSL2561_LUX_B4C; m=TSL2561_LUX_M4C;}
+  else if (ratio <= TSL2561_LUX_K5C)
+    {b=TSL2561_LUX_B5C; m=TSL2561_LUX_M5C;}
+  else if (ratio <= TSL2561_LUX_K6C)
+    {b=TSL2561_LUX_B6C; m=TSL2561_LUX_M6C;}
+  else if (ratio <= TSL2561_LUX_K7C)
+    {b=TSL2561_LUX_B7C; m=TSL2561_LUX_M7C;}
+  else if (ratio > TSL2561_LUX_K8C)
+    {b=TSL2561_LUX_B8C; m=TSL2561_LUX_M8C;}
+#else
+  if ((ratio >= 0) && (ratio <= TSL2561_LUX_K1T))
+    {b=TSL2561_LUX_B1T; m=TSL2561_LUX_M1T;}
+  else if (ratio <= TSL2561_LUX_K2T)
+    {b=TSL2561_LUX_B2T; m=TSL2561_LUX_M2T;}
+  else if (ratio <= TSL2561_LUX_K3T)
+    {b=TSL2561_LUX_B3T; m=TSL2561_LUX_M3T;}
+  else if (ratio <= TSL2561_LUX_K4T)
+    {b=TSL2561_LUX_B4T; m=TSL2561_LUX_M4T;}
+  else if (ratio <= TSL2561_LUX_K5T)
+    {b=TSL2561_LUX_B5T; m=TSL2561_LUX_M5T;}
+  else if (ratio <= TSL2561_LUX_K6T)
+    {b=TSL2561_LUX_B6T; m=TSL2561_LUX_M6T;}
+  else if (ratio <= TSL2561_LUX_K7T)
+    {b=TSL2561_LUX_B7T; m=TSL2561_LUX_M7T;}
+  else if (ratio > TSL2561_LUX_K8T)
+    {b=TSL2561_LUX_B8T; m=TSL2561_LUX_M8T;}
+#endif
+
+  unsigned long temp;
+  temp = ((channel0 * b) - (channel1 * m));
+
+  // do not allow negative lux value
+  if (temp < 0) temp = 0;
+
+  // round lsb (2^(LUX_SCALE-1))
+  temp += (1 << (TSL2561_LUX_LUXSCALE-1));
+
+  // strip off fractional portion
+  uint32_t lux = temp >> TSL2561_LUX_LUXSCALE;
+
+  // Signal I2C had no errors
+  return lux;
+}
+
+uint32_t TSL2561::getFullLuminosity (void)
+{
+  if (!_initialized) begin();
+
+  // Enable the device by setting the control bit to 0x03
+  enable();
+
+  // Wait x ms for ADC to complete
+  switch (_integration)
+  {
+    case TSL2561_INTEGRATIONTIME_13MS:
+      delay(14);
+      break;
+    case TSL2561_INTEGRATIONTIME_101MS:
+      delay(102);
+      break;
+    default:
+      delay(403);
+      break;
+  }
+
+  uint32_t x;
+  x = read16(TSL2561_COMMAND_BIT | TSL2561_WORD_BIT | TSL2561_REGISTER_CHAN1_LOW);
+  x <<= 16;
+  x |= read16(TSL2561_COMMAND_BIT | TSL2561_WORD_BIT | TSL2561_REGISTER_CHAN0_LOW);
+
+  disable();
+
+  return x;
+}
+uint16_t TSL2561::getLuminosity (uint8_t channel) {
+
+  uint32_t x = getFullLuminosity();
+
+  if (channel == 0) {
+    // Reads two byte value from channel 0 (visible + infrared)
+    return (x & 0xFFFF);
+  } else if (channel == 1) {
+    // Reads two byte value from channel 1 (infrared)
+    return (x >> 16);
+  } else if (channel == 2) {
+    // Reads all and subtracts out just the visible!
+    return ( (x & 0xFFFF) - (x >> 16));
+  }
+
+  // unknown channel!
+  return 0;
+}
+
+
+uint16_t TSL2561::read16(uint8_t reg)
+{
+  uint16_t x; uint16_t t;
+
+  Wire.beginTransmission(_addr);
+#if ARDUINO >= 100
+  Wire.write(reg);
+#else
+  Wire.send(reg);
+#endif
+  Wire.endTransmission();
+
+  Wire.requestFrom(_addr, 2);
+#if ARDUINO >= 100
+  t = Wire.read();
+  x = Wire.read();
+#else
+  t = Wire.receive();
+  x = Wire.receive();
+#endif
+  x <<= 8;
+  x |= t;
+  return x;
+}
+
+
+
+void TSL2561::write8 (uint8_t reg, uint8_t value)
+{
+  Wire.beginTransmission(_addr);
+#if ARDUINO >= 100
+  Wire.write(reg);
+  Wire.write(value);
+#else
+  Wire.send(reg);
+  Wire.send(value);
+#endif
+  Wire.endTransmission();
+}