update LTC2991

libraries/LTC2991/LTC2991.cpp

@@ -1,14 +1,15 @@
 //
 //    FILE: LTC2991.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2021-05-10
 // PURPOSE: Library for LTC2991 temperature and voltage control IC
 //     URL: https://github.com/RobTillaart/LTC2991
 //
 //  HISTORY:
 //  0.1.0   2021-05-10  initial version
-//  
+//  0.1.1   2021-05-16  add trigger_conversion(), set_PWM_fast() 
+//          performance optimizations, some default values, and cleanup.
 
 
 #include "LTC2991.h"
@@ -74,7 +75,7 @@ LTC2991::LTC2991(const int8_t address, TwoWire *wire)
 
 
 #if defined (ESP8266) || defined(ESP32)
-bool LTC2991::begin(uint8_t sda, uint8_t scl)
+bool LTC2991::begin(const uint8_t sda, const uint8_t scl)
 {
   _wire = &Wire;
   _wire->begin(sda, scl);
@@ -134,6 +135,12 @@ bool LTC2991::is_busy()
 //
 // EXTERNAL CHANNELS  (8 voltage or 4 temperature)
 //
+void LTC2991::trigger_conversion_all()
+{
+  _setRegisterMask(STATUS_HIGH, 0xF0);
+}
+
+
 void LTC2991::enable(uint8_t n, bool enable)
 {
   if (enable) _setRegisterMask(STATUS_HIGH, (0x08 << n));
@@ -358,6 +365,16 @@ void LTC2991::set_PWM(uint16_t value)
 }
 
 
+void LTC2991::set_PWM_fast(uint16_t value)
+{
+  if (value > 511) value = 511;
+  _writeRegister(PWM_THRESHOLD_MSB, value >> 1);
+  // last bit is never set, only when value is zero
+  // to be sure there is no dangling bit.
+  if (value == 0) _clrRegisterMask(PWM_THRESHOLD_LSB, 0x80);
+}
+
+
 uint16_t LTC2991::get_PWM()
 {
   uint16_t pwm = _readRegister(PWM_THRESHOLD_MSB);
@@ -521,6 +538,7 @@ uint8_t LTC2991::_readRegister(const uint8_t reg)
   return _wire->read();
 }
 
+
 uint16_t LTC2991::_readRegister16(const uint8_t reg)
 {
   uint16_t x = _readRegister(reg) << 8;
@@ -530,19 +548,26 @@ uint16_t LTC2991::_readRegister16(const uint8_t reg)
   return x;
 }
 
+
 void LTC2991::_setRegisterMask(const uint8_t reg, uint8_t mask)
 {
   uint8_t x = _readRegister(reg);
-  x |= mask;
-  _writeRegister(reg, x);
+  if ((x & mask) != mask)   // if not all bits set, set them
+  {
+    x |= mask;
+    _writeRegister(reg, x);
+  }
 }
 
 
 void LTC2991::_clrRegisterMask(const uint8_t reg, uint8_t mask)
 {
   uint8_t x = _readRegister(reg);
-  x &= ~mask;
-  _writeRegister(reg, x);
+  if (x | mask)         // if any bit of the mask set clear it
+  {
+    x &= ~mask;
+    _writeRegister(reg, x);
+  }
 }
 
 uint8_t LTC2991::_getRegisterMask(const uint8_t reg, uint8_t mask)

libraries/LTC2991/LTC2991.h

@@ -2,7 +2,7 @@
 //
 //    FILE: LTC2991.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2021-05-10
 // PURPOSE: Library for LTC2991 temperature and voltage control IC
 //     URL: https://github.com/RobTillaart/LTC2991
@@ -11,7 +11,7 @@
 #include "Arduino.h"
 #include "Wire.h"
 
-#define LTC2991_LIB_VERSION         (F("0.1.0"))
+#define LTC2991_LIB_VERSION         (F("0.1.1"))
 
 
 class LTC2991
@@ -20,58 +20,56 @@ public:
   explicit LTC2991(const int8_t address, TwoWire *wire = &Wire);
 
 #if defined (ESP8266) || defined(ESP32)
-  bool    begin(uint8_t sda, uint8_t scl);
+  bool    begin(const uint8_t sda, const uint8_t scl);
 #endif
 
   bool    begin();
   bool    isConnected();
 
 
-  // REGISTER 0x00 .. 0x01
   // channel = 1..8
   bool    new_data(uint8_t channel);  // external
   bool    new_temperature();          // internal
   bool    new_voltage();              // VCC
   bool    is_busy();
 
+
   //
-  // EXTERNAL CHANNELS  (8 voltage or 4 temperature)
+  // EXTERNAL CHANNELS  (8 voltage, 4 differentials or 4 temperature)
   //
   // n = 1 ==> V1 V2  T1
   // n = 2 ==> V3 V4  T2
   // n = 3 ==> V5 V6  T3
   // n = 4 ==> V7 V8  T4
+  void    trigger_conversion(uint8_t n) { enable(n, true); };
+  void    trigger_conversion_all();
   void    enable(uint8_t n, bool enable);
   bool    is_enabled(uint8_t n);
 
-  // REGISTER 0x06 .. 0x07
+
   //    n: 1..4
   void    enable_filter(uint8_t n, bool enable);
   bool    is_enabled_filter(uint8_t n);
-  void    set_Kelvin(uint8_t n);  // implicit set_mode_temperature
-  void    set_Celsius(uint8_t n); // implicit set_mode_temperature
-  void    set_temp_scale(uint8_t n, bool Kelvin = true);  // MIGHT BECOME OBSOLETE ?
-  //      returns 'C' or 'K'
-  char    get_temp_scale(uint8_t n);
+  void    set_Kelvin(uint8_t n);      // implicit set_mode_temperature
+  void    set_Celsius(uint8_t n);     // implicit set_mode_temperature
+  void    set_temp_scale(uint8_t n, bool Kelvin = true);
+  char    get_temp_scale(uint8_t n);         // returns 'C' or 'K'
   void    set_mode_temperature(uint8_t n);
   void    set_mode_voltage_differential(uint8_t n);
   void    set_mode_voltage_normal(uint8_t n);
-  uint8_t get_operational_mode(uint8_t n);
+  uint8_t get_operational_mode(uint8_t n);          // enumeration?
   uint8_t get_differential_mode(uint8_t n);
-
-  // REGISTER 0x0A .. 0x19
-  float    get_value(uint8_t channel);      // chan = 1..8
-
+  float   get_value(uint8_t channel);      // chan = 1..8
 
 
   //
   // PWM
   //
-  // REGISTER 0x08 .. 0x09
   // value = 0..511
-  void     set_PWM(uint16_t value);
+  void     set_PWM(uint16_t value = 0);
+  void     set_PWM_fast(uint16_t value = 0);   // less resolution
   uint16_t get_PWM();
-  void     invert_PWM(bool invert);
+  void     invert_PWM(bool invert = false);
   bool     is_inverted_PWM();
   void     enable_PWM(bool enable);
   bool     is_enabled_PWM();
@@ -95,11 +93,8 @@ public:
   void     set_Kelvin_Tintern()   { set_temp_scale_Tintern(true); };
   void     set_Celsius_Tintern()  { set_temp_scale_Tintern(false); };
   void     set_temp_scale_Tintern(bool Kelvin = true);
-  //      returns 'C' or 'K'
-  char     get_temp_scale_Tintern();
-  // REGISTER 0x1A .. 0x1B
+  char     get_temp_scale_Tintern();         // returns 'C' or 'K'
   float    get_Tintern();
-  // REGISTER 0x1C .. 0x1D
   float    get_VCC();
 
 

libraries/LTC2991/README.md

@@ -11,9 +11,9 @@ Arduino library for an LTC2991 temperature and voltage control IC
 
 ## Description
 
-Experimental - not tested yet
+Experimental - not tested myself, (no hardware)
 
-LTC2991 is an experimental library for the LTC2991 IC which is typically used to control temperature and voltage lines.
+LTC2991 is an experimental library for the LTC2991 IC which is typically used to monitor temperature and voltage. It also has a PWM out to control e.g. a fan.
 
 The IC supports normal voltage measurement (8 lines), differential voltage measurements (4 pairs) and temperature measurements (4 pairs). These can be combined in a mix. As the IC has only 8 inputs available one has to choose what. 
 
@@ -26,12 +26,12 @@ Read the datasheet for the details.
 ### Constructor and setup
 
 - **LTC2991(const int8_t address, TwoWire \*wire = Wire);**
-- **bool begin(uint8_t sda, uint8_t scl)** ESP32 ea initializes the class.
+- **bool begin(const uint8_t sda, const uint8_t scl)** for ESP32 and ESP8266;  initializes the class.
 sets I2C pins.
-returns true if the LTC2991 is on the I2C bus.
+returns true if the LTC2991 address is on the I2C bus.
 - **bool begin()** UNO ea. initializes the class. 
-returns true if the LTC2991 is on the I2C bus.
-- **bool isConnected()** returns true if the LTC2991 is on the I2C bus.
+returns true if the LTC2991 address is on the I2C bus.
+- **bool isConnected()** returns true if the LTC2991 address is on the I2C bus.
 
 
 ### Status functions
@@ -53,15 +53,17 @@ The following functions work on pairs
 |   3  | V5 V6  T3 |
 |   4  | V7 V8  T4 |
 
-- **void enable(uint8_t n, bool enable)** enable or disable an external line. 
+- **void trigger_conversion(uint8_t n)** wrapper around enable(n, true), better naming.
+- **void trigger_conversion_all()** triggers conversions for all 4 channels/pairs.
+- **void enable(uint8_t n, bool enable)** enable or disable an external line. disable can be used to stop the repeat mode.
 - **bool is_enabled(uint8_t n)** idem
-- **void enable_filter(uint8_t n, bool enable)** not investigated 
+- **void enable_filter(uint8_t n, bool enable)** enable filter - not investigated.
 - **bool is_enabled_filter(uint8_t n)** idem
 - **void set_Kelvin(uint8_t n)** sets temperature mode to Kelvin, 
 implicit set_mode_temperature(), 
 - **void set_Celsius(uint8_t n)** sets temperature mode to Celsius,
 implicit set_mode_temperature
-- **void set_temp_scale(uint8_t n, bool Kelvin = true)** obsolete?
+- **void set_temp_scale(uint8_t n, bool Kelvin = true)** used to switch between Kelvin and Celsius.
 - **char get_temp_scale(uint8_t n)** returns 'K' or 'C'
 - **void set_mode_temperature(uint8_t n)** sets operational mode
 - **void set_mode_voltage_differential(uint8_t n)** sets operational mode
@@ -75,7 +77,7 @@ depending on the operational mode it returns the temperature or the
 
 ### Internal measurements
 
-- **void enable_Tintern_Vcc(bool enable)** enable internal temperature sensor
+- **void enable_Tintern_Vcc(bool enable)** enable internal temperature measurements
 - **bool is_enabled_Tintern_Vcc()** idem
 - **void enable_filter_Tintern(bool enable)** enable filter - not investigated
 - **bool is_enabled_filter_Tintern()**
@@ -89,14 +91,15 @@ depending on the operational mode it returns the temperature or the
 
 ### Configuration
 - **void set_acquisition_repeat()** set continuous measurement mode
-- **void set_acquisition_single()** set single shot mode
+- **void set_acquisition_single()** set single shot mode. Note that before a measurement one needs to call trigger_conversion();
 - **uint8_t get_acquisition_mode()** return mode set (0,1)
 
 
 ### PWM functions
 
-- **void set_PWM(uint16_t value)** value is 0..511
-- **uint16_t get_PWM()** idem
+- **void set_PWM(uint16_t value = 0)** value is 0..511
+- **void set_PWM(uint16_t value = 0)** value is 0..511, less resolution (256 steps)
+- **uint16_t get_PWM()** returns the value from the PWM register, when using PWM_fast this can differ 1.
 - **void invert_PWM(bool invert)** idem
 - **bool is_inverted_PWM()** idem
 - **void enable_PWM(bool enable)** idem
@@ -116,14 +119,19 @@ See examples..
 
 ### TODO
 
+#### must
 - get hardware to 
 - test test test
-- elaborate on the documentation
-- more examples
 
-COULD
-- cache all registers or
+
+#### could
+- cache registers (which) or
 - cache a number of flags to speed up retrieving data
 - optimize multibyte read / write
+- add Fahrenheit 
+  - do low level in Kelvin and convert to KFC as needed.
+  - would simplify get_value
+  - need an enum
 - look for code optimizations
-- 
+
+

libraries/LTC2991/keywords.txt

@@ -13,10 +13,15 @@ new_temperature	KEYWORD2
 new_voltage	KEYWORD2
 is_busy	KEYWORD2
 
+
+trigger_conversion	KEYWORD2
+trigger_conversion_all	KEYWORD2
 enable	KEYWORD2
 is_enabled	KEYWORD2
 enable_filter	KEYWORD2
 is_enabled_filter	KEYWORD2
+
+
 set_Kelvin	KEYWORD2
 set_Celsius	KEYWORD2
 get_temp_scale	KEYWORD2
@@ -29,6 +34,7 @@ get_value	KEYWORD2
 
 
 set_PWM	KEYWORD2
+set_PWM_fast	KEYWORD2
 get_PWM	KEYWORD2
 invert_PWM	KEYWORD2
 is_inverted_PWM	KEYWORD2

libraries/LTC2991/library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/LTC2991.git"
   },
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*"

libraries/LTC2991/library.properties

@@ -1,5 +1,5 @@
 name=LTC2991
-version=0.1.0
+version=0.1.1
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for LTC2991