add getCurrentDivisorRatio()

CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.2.1] - 2024-05-17
+- add **getCurrentDivisorRatio()**
+- add **getAddress()** convenience
+- add **max44007_performance.ino**.
+- add **max44007_test_manual_mode.ino**.
+- update readme.md
+- update keywords.txt
+- minor edits.
+
 ## [0.2.0] - 2023-10-02
 - refactor constructor around I2C interface (simpler)
 - remove **configure()**

Max44007.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: Max44007.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.0
+// VERSION: 0.2.1
 //    DATE: 2022-01-04
 // PURPOSE: library for Max44007 lux sensor Arduino
 //     URL: https://github.com/RobTillaart/MAX44007
@@ -32,6 +32,12 @@ bool Max44007::isConnected()
 }
 
 
+uint8_t Max44007::getAddress()
+{
+  return _address;
+}
+
+
 float Max44007::getLux(void)
 {
   uint8_t datahigh = read(MAX44007_LUX_READING_HIGH);
@@ -141,7 +147,7 @@ void Max44007::clrContinuousMode()
 
 void Max44007::setManualMode(uint8_t CDR, uint8_t TIM)
 {
-  if (CDR !=0) CDR = 1;    //  only 0 or 1 
+  if (CDR !=0) CDR = 1;    //  only 0 or 1
   if (TIM > 7) TIM = 7;
   uint8_t config = read(MAX44007_CONFIGURATION);
   config |= MAX44007_CFG_MANUAL;
@@ -151,6 +157,22 @@ void Max44007::setManualMode(uint8_t CDR, uint8_t TIM)
 }
 
 
+int Max44007::getCurrentDivisorRatio()
+{
+  uint8_t CDR = read(MAX44007_CONFIGURATION) & 0x08;
+  return CDR >> 3;
+}
+
+
+int Max44007::getIntegrationTime()
+{
+  uint8_t TIM = read(MAX44007_CONFIGURATION) & 0x07;
+  return 800 >> TIM;
+}
+
+
+//  datahigh = [eeee mmmm]
+//  datalow  = [     mmmm]
 float Max44007::convertToLux(uint8_t datahigh, uint8_t datalow)
 {
   uint8_t  exponent = datahigh >> 4;
@@ -169,7 +191,8 @@ bool Max44007::setThreshold(const uint8_t reg, const float value)
   //  CHECK RANGE OF VALUE
   if ((value < 0.0) || (value > MAX44007_MAX_LUX)) return false;
 
-  uint32_t mantissa = round(value * (1.0 / MAX44007_MIN_LUX));     //  compile time optimized.
+  //  compile time optimized.
+  uint32_t mantissa = round(value * (1.0 / MAX44007_MIN_LUX));
   uint8_t exponent = 0;
   while (mantissa > 255)
   {
@@ -186,7 +209,8 @@ bool Max44007::setThreshold(const uint8_t reg, const float value)
 float Max44007::getThreshold(uint8_t reg)
 {
   uint8_t datahigh = read(reg);
-  float lux = convertToLux(datahigh, 0x08);  //  0x08 = correction for lost bits 
+  //  0x08 = correction for lost bits
+  float lux = convertToLux(datahigh, 0x08);
   return lux;
 }
 
@@ -198,12 +222,12 @@ uint8_t Max44007::read(uint8_t reg)
   _error = _wire->endTransmission();
   if (_error != MAX44007_OK)
   {
-    return _data;       //  last value
+    return _data;           //  last value
   }
   if (_wire->requestFrom(_address, (uint8_t) 1) != 1)
   {
     _error = MAX44007_ERROR_WIRE_REQUEST;
-    return _data;       //  last value
+    return _data;           //  last value
   }
   _data = _wire->read();
   return _data;

Max44007.h

@@ -2,13 +2,13 @@
 
 //    FILE: Max44007.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.0
+// VERSION: 0.2.1
 //    DATE: 2022-01-04
 // PURPOSE: library for Max44007 lux sensor Arduino
 //     URL: https://github.com/RobTillaart/MAX44007
 
 
-//       breakout MAX44007
+//      breakout MAX44007
 //
 //          +--------+
 //      VCC |o       |
@@ -18,8 +18,8 @@
 //          +--------+
 //
 //  ADDRESS:
-//  0 = 0x4A
-//  1 = 0x4B
+//  0 = 0x5A
+//  1 = 0x5B
 //
 //  INT:
 //  Connect the INT pin to an pull up resistor
@@ -33,7 +33,7 @@
 #include "Arduino.h"
 
 
-#define MAX44007_LIB_VERSION                  (F("0.2.0"))
+#define MAX44007_LIB_VERSION                  (F("0.2.1"))
 
 #define MAX44007_DEFAULT_ADDRESS              0x5A
 #define MAX44007_ALT_ADDRESS                  0x5B
@@ -72,41 +72,49 @@ class Max44007
   Max44007(const uint8_t address = MAX44007_DEFAULT_ADDRESS, TwoWire *wire = &Wire);
 
   bool    isConnected();
+  uint8_t getAddress();
+
+
   float   getLux();
   int     getError();
 
-  //  threshold must be between 0 and 188006
+
+  //      threshold must be between 0 and 188006
   bool    setHighThreshold(const float value);       //  returns false if value out of range
   float   getHighThreshold(void);
   bool    setLowThreshold(const float value);        //  returns false if value out of range
   float   getLowThreshold(void);
   void    setThresholdTimer(const uint8_t value);    //  2 seems practical minimum
   uint8_t getThresholdTimer();
 
+
   void    enableInterrupt()    { write(MAX44007_INTERRUPT_ENABLE, 1); };
   void    disableInterrupt()   { write(MAX44007_INTERRUPT_ENABLE, 0); };
   bool    interruptEnabled()   { return read(MAX44007_INTERRUPT_ENABLE) & 0x01; };
   uint8_t getInterruptStatus() { return read(MAX44007_INTERRUPT_STATUS) & 0x01; };
 
+
   //  check datasheet for detailed behaviour
   void    setConfiguration(uint8_t);
   uint8_t getConfiguration();
   void    setAutomaticMode();
   void    setContinuousMode();    //  uses more power
   void    clrContinuousMode();    //  uses less power
-  //  CDR = Current Divisor Ratio
-  //  CDR = 1 ==> only 1/8th is measured
-  //  TIM = Time Integration Measurement (table)
-  //  000   800ms
-  //  001   400ms
-  //  010   200ms
-  //  011   100ms
-  //  100    50ms       manual only
-  //  101    25ms       manual only
-  //  110    12.5ms     manual only
-  //  111     6.25ms    manual only
+  //      CDR = Current Divisor Ratio
+  //      CDR = 1 ==> only 1/8th is measured
+  //      TIM = Time Integration Measurement (table)
+  //      000   800ms
+  //      001   400ms
+  //      010   200ms
+  //      011   100ms
+  //      100    50ms       manual only
+  //      101    25ms       manual only
+  //      110    12.5ms     manual only
+  //      111     6.25ms    manual only
   void    setManualMode(uint8_t CDR, uint8_t TIM);
-  int     getIntegrationTime() { return 800 >> (getConfiguration() & 0x07); };  //  ms
+  int     getCurrentDivisorRatio();  //  CDR 0/1
+  int     getIntegrationTime();      //  TIM in ms (rounded)
+
 
   //  TEST the math
   float   convertToLux(uint8_t datahigh, uint8_t datalow);
@@ -127,5 +135,5 @@ class Max44007
 };
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

README.md

@@ -57,6 +57,51 @@ Note: version 0.2.0 simplified the constructor interface and removed **configure
 //
 ```
 
+## I2C
+
+#### Address
+
+The MAX44009 can have 2 addresses:
+
+- 0x5A = **MAX44009_DEFAULT_ADDRESS**
+- 0x5B = **MAX44009_ALT_ADDRESS**
+
+See schema above.
+
+
+#### I2C multiplexing
+
+Sometimes you need to control more devices than possible with the default
+address range the device provides.
+This is possible with an I2C multiplexer e.g. TCA9548 which creates up
+to eight channels (think of it as I2C subnets) which can use the complete
+address range of the device.
+
+Drawback of using a multiplexer is that it takes more administration in
+your code e.g. which device is on which channel.
+This will slow down the access, which must be taken into account when
+deciding which devices are on which channel.
+Also note that switching between channels will slow down other devices
+too if they are behind the multiplexer.
+
+- https://github.com/RobTillaart/TCA9548
+
+
+#### I2C Performance
+
+Performance of the getLux function in microseconds.
+
+|  Clock   |   UNO   |  ESP32  |  Notes  |
+|:--------:|:-------:|:-------:|:-------:|
+|  100000  |         |         |
+|  200000  |         |         |
+|  300000  |         |         |
+|  400000  |         |         |
+|  500000  |         |         |
+|  600000  |         |         |
+
+TODO fill table.
+
 
 ## Interface
 
@@ -69,6 +114,7 @@ Note: version 0.2.0 simplified the constructor interface and removed **configure
 - **Max44007(const uint8_t address = MAX44007_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)** Constructor.
 Optional address and optional I2C interface.\
 - **bool isConnected()** returns true if the device address configured is available on I2C bus.
+- **uint8_t getAddress()** returns device address. Convenience function.
 
 NOTE: The user must call **Wire.begin()** or **Wire.begin(SDA, SCL)** in **setup()**.
 
@@ -126,9 +172,9 @@ check datasheet for details
 
 ### Configure sample mode
 
-Check datasheet for details
+Check datasheet for details.
 
-CCR = Current Divisor Ratio.
+CDR = Current Divisor Ratio.
 
 TIM = Integration time.
 
@@ -139,7 +185,10 @@ Advantage is that the latest data is always available fast.
 - **void clrContinuousMode()** uses less power so better for LOW power configurations.
 - **void setManualMode(uint8_t CDR, uint8_t TIM)** Set the Current Divisor Ratio and the
 integration time manually. Effectively disable automatic mode.
-- **int getIntegrationTime()** returns the set integration time in milliseconds
+- **int getIntegrationTime()** returns the set integration time in milliseconds.
+Note these are rounded down (12 == 12.5 and 6 == 6.25) to minimize math.
+- **int getCurrentDivisorRatio()** returns the set Current Divisor Ratio.
+This is either 0 (full intensity) or 1 (1/8th intensity).
 
 ```
     CDR = Current Divisor Ratio
@@ -160,7 +209,7 @@ integration time manually. Effectively disable automatic mode.
 ### Test functions
 
 Function for the conversion math, not meant to be used directly,
-but by making them public they become testable.
+but by making it public the math becomes testable.
 
 - **float convertToLux(uint8_t dataHigh, uint8_t dataLow)** convert intern register
 format to a LUX value.
@@ -194,12 +243,18 @@ Pull ups on I2C bus are recommended.
 #### Must
 
 - follow MAX44009
+- improve documentation
+- buy hardware
 
 #### Should
 
+- run performance test on UNO and ESP32.
+
 #### Could
 
 - merge MAX44007 / MAX44009 library in the future. (shared base class?)
+- read data high and low in one call?
+- convertToLux() overflow test, when exponent == 15.
 
 #### Wont
 

examples/max44007_interrupt/max44007_interrupt.ino

@@ -2,12 +2,12 @@
 //    FILE: Max44007_interrupt.ino
 //  AUTHOR: Rob Tillaart
 // PURPOSE: demo of Max44007 library
-//    DATE: 2022-01-04
+//     URL: https://github.com/RobTillaart/MAX44007
 
 
-#include "Wire.h"
 #include "Max44007.h"
 
+
 Max44007 myLux(0x5A);
 
 uint32_t lastDisplay = 0;
@@ -19,8 +19,10 @@ void setup()
   Serial.println(__FILE__);
   Serial.print("MAX44007_LIB_VERSION: ");
   Serial.println(MAX44007_LIB_VERSION);
+  Serial.println();
 
   Wire.begin();
+
   myLux.setContinuousMode();
 
   myLux.setHighThreshold(30);
@@ -44,22 +46,29 @@ void loop()
   {
     lastDisplay += interval;
     float lux = myLux.getLux();
-    int err = myLux.getError();
-    int st = myLux.getInterruptStatus();
-    if (err != 0)
+    int error = myLux.getError();
+    int status = myLux.getInterruptStatus();
+    if (error != 0)
     {
       Serial.print("Error:\t");
-      Serial.println(err);
+      Serial.println(error);
     }
     else
     {
       Serial.print("lux:\t");
       Serial.print(lux);
-      if (st == 1) Serial.println("\tIRQ occurred");
-      else Serial.println();
+      if (status == 1) 
+      {
+        Serial.println("\tIRQ occurred");
+      }
+      else 
+      {
+        Serial.println();
+      }
     }
   }
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
+