update LTC2991

Author: RobTillaart

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 @@ class LTC2991
  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 @@ class LTC2991
  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