Adds Example three which demonstrates power save mode.

Author: Elias Santistevan

Examples/Example3_All_Ambient_Features/Example3_All_Ambient_Features.ino

@@ -0,0 +1,111 @@
+/*
+  This example code will walk you through how to enable power save mode on your
+  Ambient Light Sensor. When would you use power save mode? The datasheet
+  specifies that power save mode is perfect when you want to continuously
+  sample ambient light readings from your sensor, as opposed to getting a
+  reading once an hour for example. The benefit of power save mode is lower
+  power consumption, with current draw in the single digit micro-amp range. 
+  Enabling the power save mode decreases the refresh rate of the sensor and so
+  sampling should happen at a slower rate. Last thing, the refresh rate is also
+  dependent on the integration time setting of the sensor. See the hookup guide 
+  for a table showing the correlation of refresh times, current consumption, power 
+  mode, and integration mode settings. 
+
+  SparkFun Electronics
+  Author: Elias Santistevan
+  Date: July 2019
+
+	License: This code is public domain but if you use this and we meet someday, get me a beer! 
+
+	Feel like supporting our work? Buy a board from Sparkfun!
+	https://www.sparkfun.com/products/15436
+
+*/
+
+#include <Wire.h>
+#include "SparkFun_VEML6030_Ambient_Light_Sensor.h"
+
+// Close the jumper on the product to use address 0x10.
+#define AL_ADDR 0x48
+
+SparkFun_Ambient_Light light(AL_ADDR);
+
+// Possible values: .125, .25, 1, 2
+// Both .125 and .25 should be used in most cases except darker rooms.
+// A gain of 2 should only be used if the sensor will be covered by a dark
+// glass.
+float gain = .125;
+
+// Possible integration times in milliseconds: 800, 400, 200, 100, 50, 25
+// Higher times give higher resolutions and should be used in darker light. 
+int time = 100;
+long luxVal = 0; 
+
+// Power save mode, options range from 1-4. 
+// Default is 1.
+int powMode = 2; 
+
+void setup(){
+
+  Wire.begin();
+  Serial.begin(115200);
+
+  if(light.begin())
+    Serial.println("Ready to sense some light!"); 
+  else
+    Serial.println("Could not communicate with the sensor!");
+
+  // Again the gain and integration times determine the resolution of the lux
+  // value, and give different ranges of possible light readings. Check out
+  // hoookup guide for more info. 
+  light.setGain(gain);
+  light.setIntegTime(time);
+
+  Serial.println("Reading settings..."); 
+  Serial.print("Gain: ");
+  float gainVal = light.readGain();
+  Serial.print(gainVal, 3); 
+  Serial.print(" Integration Time: ");
+  int timeVal = light.readIntegTime();
+  Serial.println(timeVal);
+
+  // Power save mode enables low power consumption from your Ambient Light
+  // Sensor. You can set modes from 1-4, four being the highest power saving
+  // option but slowest refresh rate. The sensor's refresh rate is also
+  // dependent on the integration time. For example a setting of 4 with an
+  // integration time of 100ms == 4100ms refresh rate but 2 micro-amps current
+  // draw. Check hookup guide for more info. 
+  light.setPowSavMode(powMode);
+  // Let's see that it was set correctly. 
+  Serial.print("Power Save Mode: "); 
+  int savVal = light.readPowSavMode();
+  Serial.println(savVal);
+  light.enablePowSave();
+  Serial.println("Is power save enabled: ");
+  int enaVal = light.readPowSavEnabled(); 
+
+  if(enaVal)
+    Serial.println("Yes!");
+  else
+    Serial.println("No!");  
+
+  // This will power down the sensor and the sensor will draw 0.5 micro-amps of
+  // power while shutdown. 
+  // light.shutDown();
+  // light.powerOn();
+
+  // Give some time to read your settings. 
+  delay(1000);
+
+}
+
+void loop(){
+
+  luxVal = light.readLight();
+  Serial.print("Ambient Light Reading: ");
+  Serial.print(luxVal);
+  Serial.println(" Lux");  
+  // Sampling at the rate specified in the hookup guide power save mode table. 
+  delay(1100);
+
+}

Examples/Example3_Power_Save_Mode/Example3_Power_Save_Mode.ino

@@ -80,7 +80,7 @@ float SparkFun_Ambient_Light::readGain(){
 // REG0x00, bits[9:6]
 // This function sets the integration time (the saturation time of light on the
 // sensor) of the ambient light sensor. Higher integration time leads to better
-// resolution but slower refresh times. 
+// resolution but slower sensor refresh times. 
 void SparkFun_Ambient_Light::setIntegTime(uint16_t time){ 
 
   uint16_t bits;
@@ -108,7 +108,7 @@ void SparkFun_Ambient_Light::setIntegTime(uint16_t time){
 // REG0x00, bits[9:6]
 // This function reads the integration time (the saturation time of light on the
 // sensor) of the ambient light sensor. Higher integration time leads to better
-// resolution but slower refresh times. 
+// resolution but slower sensor refresh times. 
 uint16_t SparkFun_Ambient_Light::readIntegTime(){
 
   uint16_t regVal = _readRegister(SETTING_REG); 
@@ -469,9 +469,11 @@ uint32_t SparkFun_Ambient_Light::_calculateLux(uint16_t _lightBits){
 }
 
 
-// This function does the opposite above. I belive the interrupt values are
-// also set with the given gain and intergration times settings, though I don't
-// know because the datasheet doesn't mention anything on the issue.
+// This function does the opposite calculation then the function above. The interrupt
+// threshold values given by the user are dependent on the gain and
+// intergration time settings. As a result the lux value needs to be
+// calculated with the current settings and this function accomplishes
+// that.  
 uint16_t SparkFun_Ambient_Light::_calculateBits(uint32_t _luxVal){
 
   float _luxConv; 

src/SparkFun_VEML6030_Ambient_Light_Sensor.cpp

@@ -13,6 +13,7 @@
 #define INT_LOW       0x02
 #define UNKNOWN_ERROR 0xFF
 
+// 7-Bit address options
 const uint8_t defAddr = 0x48;
 const uint8_t altAddr = 0x10;
 
@@ -29,7 +30,7 @@ enum VEML6030_16BIT_REGISTERS {
 };
 
 enum VEML6030_16BIT_REG_MASKS {
-  
+ 
   THRESH_MASK            = 0x0,
   GAIN_MASK              = 0xE7FF,
   INTEG_MASK             = 0xFC3F,
@@ -56,7 +57,8 @@ enum REGISTER_BIT_POSITIONS {
 
 // Table of lux conversion values depending on the integration time and gain. 
 // The arrays represent the all possible integration times and the index of the
-// arrays represent the register's gain settings. 
+// arrays represent the register's gain settings, which is directly analgous to
+// their bit representations. 
 const float eightHIt[]     = {.0036, .0072, .0288, .0576};
 const float fourHIt[]      = {.0072, .0144, .0576, .1152};
 const float twoHIt[]       = {.0144, .0288, .1152, .2304};
@@ -89,21 +91,23 @@ class SparkFun_Ambient_Light
     // REG0x00, bits[9:6]
     // This function sets the integration time (the saturation time of light on the
     // sensor) of the ambient light sensor. Higher integration time leads to better
-    // resolution but slower refresh times. 
+    // resolution but slower sensor refresh times. 
     void setIntegTime(uint16_t time);
 
     // REG0x00, bits[9:6]
     // This function reads the integration time (the saturation time of light on the
     // sensor) of the ambient light sensor. Higher integration time leads to better
-    // resolution but slower refresh times. 
+    // resolution but slower sensor refresh times. 
     uint16_t readIntegTime();
 
     // REG0x00, bits[5:4]
-    // This function sets the persistence protect number. 
+    // This function sets the persistence protect number i.e. the number of
+    // values needing to crosh the interrupt thresholds.
     void setProtect(uint8_t protVal);
 
     // REG0x00, bits[5:4]
-    // This function reads the persistence protect number. 
+    // This function reads the persistence protect number i.e. the number of 
+    // values needing to crosh the interrupt thresholds.
     uint8_t readProtect();
 
     // REG0x00, bit[1]
@@ -212,9 +216,11 @@ class SparkFun_Ambient_Light
     // the value and returns it.  
     uint32_t _calculateLux(uint16_t _lightBits);
 
-    // This function does the opposite above. I belive the interrupt values are
-    // also set with the given gain and intergration times settings, though I don't
-    // know because the datasheet doesn't mention anything on the issue.
+    // This function does the opposite calculation then the function above. The interrupt
+    // threshold values given by the user are dependent on the gain and
+    // intergration time settings. As a result the lux value needs to be
+    // calculated with the current settings and this function accomplishes
+    // that.  
     uint16_t _calculateBits(uint32_t _luxVal);
 
     // This function writes to a 16 bit register. Paramaters include the register's address, a mask