Fix #14, round => truncate

.github/FUNDING.yml

@@ -1,4 +1,4 @@
 # These are supported funding model platforms
 
 github: RobTillaart
-
+custom: "https://www.paypal.me/robtillaart"

.github/workflows/arduino-lint.yml

@@ -6,7 +6,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: arduino/arduino-lint-action@v1
         with:
           library-manager: update

.github/workflows/arduino_test_runner.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

.github/workflows/jsoncheck.yml

@@ -10,7 +10,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: json-syntax-check
         uses: limitusus/json-syntax-check@v1
         with:

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.3.0] - 2024-03-15
+- Fix #14, change round to truncate.
+- update GitHub action to v4
+- update readme.md
+- minor edits
+
+----
+
 ## [0.2.1] - 2024-01-17
 - add **bool setBusResolution(bits)**
 - add **bool setBusSamples(value)**
@@ -18,7 +26,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - update keywords.txt
 - update readme.md
 
-
 ## [0.2.0] - 2023-12-04
 - Fix #8, refactor API - support ESP32-S3
 - update readme.md

INA219.cpp

@@ -1,6 +1,6 @@
 //    FILE: INA219.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.3.0
 //    DATE: 2021-05-18
 // PURPOSE: Arduino library for INA219 voltage, current and power sensor
 //     URL: https://github.com/RobTillaart/INA219
@@ -205,7 +205,7 @@ bool INA219::setBusResolution(uint8_t bits)
 }
 
 
-//  value = 0..7, always 12 bit resolution, 
+//  value = 0..7, always 12 bit resolution
 bool INA219::setBusSamples(uint8_t value)
 {
   if (value > 7) return false;
@@ -259,7 +259,7 @@ bool INA219::setShuntResolution(uint8_t bits)
 }
 
 
-//  value = 0..7, always 12 bit resolution, 
+//  value = 0..7, always 12 bit resolution
 bool INA219::setShuntSamples(uint8_t value)
 {
   if (value > 7) return false;
@@ -326,16 +326,15 @@ uint8_t INA219::getMode()
 bool INA219::setMaxCurrentShunt(float maxCurrent, float shunt)
 {
   // #define PRINTDEBUG
-  uint16_t calib = 0;
-
   if (maxCurrent < 0.001) return false;
   if (shunt < 0.001) return false;
 
   //  _current_LSB = maxCurrent / 32768;
   _current_LSB = maxCurrent * 3.0517578125e-5;
   _maxCurrent = maxCurrent;
   _shunt = shunt;
-  calib = round(0.04096 / (_current_LSB * shunt));
+
+  uint16_t calib = uint16_t(0.04096 / (_current_LSB * shunt));
   uint16_t wrrv = _writeRegister(INA219_CALIBRATION, calib);
 
   #ifdef PRINTDEBUG

INA219.h

@@ -1,7 +1,7 @@
 #pragma once
 //    FILE: INA219.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.3.0
 //    DATE: 2021-05-18
 // PURPOSE: Arduino library for INA219 voltage, current and power sensor
 //     URL: https://github.com/RobTillaart/INA219
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define INA219_LIB_VERSION              (F("0.2.1"))
+#define INA219_LIB_VERSION              (F("0.3.0"))
 
 
 class INA219
@@ -36,20 +36,19 @@ class INA219
   bool     getConversionFlag();    //  02
 
 
-  //  SCALE HELPERS - milli range
-  float    getBusVoltage_mV()   { return getBusVoltage() * 1e3; };
+  //  Scale helpers milli range
+  float    getBusVoltage_mV()   { return getBusVoltage()   * 1e3; };
   float    getShuntVoltage_mV() { return getShuntVoltage() * 1e3; };
-  float    getCurrent_mA()      { return getCurrent() * 1e3; };
-  float    getPower_mW()        { return getPower() * 1e3; };
-
-  //  SCALE HELPERS - micro range
-  float    getBusVoltage_uV()   { return getBusVoltage() * 1e6; };
+  float    getCurrent_mA()      { return getCurrent()      * 1e3; };
+  float    getPower_mW()        { return getPower()        * 1e3; };
+  //  Scale helpers micro range
+  float    getBusVoltage_uV()   { return getBusVoltage()   * 1e6; };
   float    getShuntVoltage_uV() { return getShuntVoltage() * 1e6; };
-  float    getCurrent_uA()      { return getCurrent() * 1e6; };
-  float    getPower_uW()        { return getPower() * 1e6; };
+  float    getCurrent_uA()      { return getCurrent()      * 1e6; };
+  float    getPower_uW()        { return getPower()        * 1e6; };
 
 
-  //  CONFIGURATION
+  //  Configuration
   //  need improvement API wise.
   bool     reset();
   //  voltage = 16, 32  (values below 32 are rounded to 16 or 32)
@@ -73,20 +72,7 @@ class INA219
   bool     setShuntADC(uint8_t mask = 0x03);  //  uses a mask, check datasheet
   uint8_t  getShuntADC();
 
-  // Operating mode = 0..7
-  bool     setMode(uint8_t mode = 7);
-  uint8_t  getMode();
-  bool     shutDown()                  { return setMode(0); };
-  bool     setModeShuntTrigger()       { return setMode(1); };
-  bool     setModeBusTrigger()         { return setMode(2); };
-  bool     setModeShuntBusTrigger()    { return setMode(3); };
-  bool     setModeADCOff()             { return setMode(4); };
-  bool     setModeShuntContinuous()    { return setMode(5); };
-  bool     setModeBusContinuous()      { return setMode(6); };
-  bool     setModeShuntBusContinuous() { return setMode(7); };  //  default.
-
-
-  //  CALIBRATION
+  //  Calibration
   //  mandatory to set these! read datasheet.
   //  maxCurrent >= 0.001
   //  shunt      >= 0.001
@@ -95,12 +81,25 @@ class INA219
 
   bool     isCalibrated()     { return _current_LSB != 0.0; };
 
-  //  these return zero if not calibrated!
-  float    getCurrentLSB()    { return _current_LSB; };
+  //  These functions return zero if not calibrated!
+  float    getCurrentLSB()    { return _current_LSB;       };
   float    getCurrentLSB_mA() { return _current_LSB * 1e3; };
   float    getCurrentLSB_uA() { return _current_LSB * 1e6; };
-  float    getShunt()         { return _shunt; };
-  float    getMaxCurrent()    { return _maxCurrent; };
+  float    getShunt()         { return _shunt;             };
+  float    getMaxCurrent()    { return _maxCurrent;        };
+
+
+  //  Operating mode = 0..7
+  bool     setMode(uint8_t mode = 7);  //  default ModeShuntBusContinuous
+  uint8_t  getMode();
+  bool     shutDown()                  { return setMode(0); };
+  bool     setModeShuntTrigger()       { return setMode(1); };
+  bool     setModeBusTrigger()         { return setMode(2); };
+  bool     setModeShuntBusTrigger()    { return setMode(3); };
+  bool     setModeADCOff()             { return setMode(4); };
+  bool     setModeShuntContinuous()    { return setMode(5); };
+  bool     setModeBusContinuous()      { return setMode(6); };
+  bool     setModeShuntBusContinuous() { return setMode(7); };  //  default.
 
 
   //  DEBUG
@@ -111,14 +110,12 @@ class INA219
 
   uint16_t _readRegister(uint8_t reg);
   uint16_t _writeRegister(uint8_t reg, uint16_t value);
-
   float    _current_LSB;
   float    _shunt;
   float    _maxCurrent;
 
   uint8_t   _address;
   TwoWire * _wire;
-
 };
 
 

README.md

@@ -24,22 +24,14 @@ Read datasheet for details.
 **USE WITH CARE**
 
 The INA219 is a voltage, current and power measurement device. 
-Maxima, see datasheet, chapter 7, esp 7.5
+A few important maxima, see datasheet, chapter 7, esp 7.5
 
 |   description   |  max  |   unit  |  notes  |
 |:----------------|------:|--------:|:--------|
 |  bus voltage    |  32   |  Volt   |  depends on BRNG setting
 |  shunt voltage  |  320  |  mVolt  |  depends on PGA setting
 
 
-#### Related
-
-- https://www.ti.com/product/INA219#tech-docs
-- https://www.ti.com/product/INA219#params
-- https://www.ti.com/document-viewer/INA219/datasheet
-- https://github.com/RobTillaart/INA219
-- https://github.com/RobTillaart/INA226
-
 
 #### 0.2.0 Breaking change
 
@@ -59,6 +51,7 @@ before calling **begin()**.
 #### Related
 
 - https://www.ti.com/product/INA219#tech-docs
+- https://www.ti.com/product/INA219#params
 - https://www.ti.com/document-viewer/INA219/datasheet
 - https://github.com/RobTillaart/INA219
 - https://github.com/RobTillaart/INA226
@@ -102,8 +95,9 @@ use **INA219_test_I2C.ino**
 
 #### Constructor
 
-- **INA219(const uint8_t address, TwoWire \*wire = Wire)** Constructor to set address and optional Wire interface.
-- **bool begin()** UNO ea. initializes the class. 
+- **INA219(const uint8_t address, TwoWire \*wire = Wire)** Constructor to set
+the address and optional Wire interface.
+- **bool begin()** initializes the class.
 Returns true if the INA219 address (set in the constructor) is on the I2C bus.
 - **bool isConnected()** Returns true if the INA219 address (set in the constructor) is on the I2C bus.
 - **uint8_t getAddress()** Returns the INA219 address set in the constructor.
@@ -114,26 +108,26 @@ Returns true if the INA219 address (set in the constructor) is on the I2C bus.
 Note the power and the current are not meaningful without calibrating the sensor. 
 Also the value is not meaningful if there is no shunt connected.
 
-- **float getShuntVoltage()** idem.
-- **float getBusVoltage()** idem. Max 32 Volt.
-- **float getPower()** returns the current times BusVoltage in Watt.
+- **float getShuntVoltage()** idem, in volts.
+- **float getBusVoltage()** idem. in volts. Max 32 Volt.
 - **float getCurrent()** returns the current through the shunt in Ampere.
+- **float getPower()** returns the current x BusVoltage in Watt.
 
 The library has helper functions to convert above output to a more appropriate scale of units.
 
-Helper functions for the milli-scale.
+Helper functions for the milli scale.
 
-- **float getBusVoltage_mV()** idem, returns millivolts.
+- **float getBusVoltage_mV()** idem, in milliVolts.
 Note: returns -100 if the math overflow bit is set.
-- **float getShuntVoltage_mV()** idem, returns millivolts.
-- **float getCurrent_mA()** idem in milliAmpere.
-- **float getPower_mW()** idem in milliWatt.
+- **float getShuntVoltage_mV()** idem, in milliVolts.
+- **float getCurrent_mA()** idem, in milliAmpere.
+- **float getPower_mW()** idem, in milliWatt.
 
-Helper functions for the micro-scale.
+Helper functions for the micro scale.
 
-- **float getBusVoltage_uV()** idem microVolt.
-- **float getShuntVoltage_uV()** idem microVolt.
-- **float getCurrent_uA()** idem in microAmpere.
+- **float getBusVoltage_uV()** idem, in microVolts.
+- **float getShuntVoltage_uV()** idem, in microVolts.
+- **float getCurrent_uA()** idem, in microAmpere.
 - **float getPower_uW()** idem, in microWatt.
 
 
@@ -165,12 +159,12 @@ Returns false if it could not write settings to device.
 #### Configuration BUS and SHUNT
 
 **Note:**
-The internal conversions runs in the background in the INA219.
+The internal conversions runs in the background in the device.
 If a conversion is finished the measured value is stored in the appropriate register. 
 The last obtained values can always be read from the registers, so they will not block.
 Result can be that you get the very same value if no new data is available yet.
 This is especially true if you increase the number of samples.
-(See also discussion in #11).
+(See also discussion in INA219 issue 11).
 
 Using more samples reduces the noise level, but one will miss the faster 
 changes in voltage or current.
@@ -265,9 +259,9 @@ Descriptive mode functions (convenience wrappers around **setMode()**).
 
 #### Calibration
 
-See details datasheet.
+See datasheet.
 
-Calibration is mandatory for **getCurrent()** and **getPower()** to work.
+Calibration is mandatory to get **getCurrent()** and **getPower()** to work.
 
 - **bool setMaxCurrentShunt(float ampere = 20.0, float ohm = 0.002)** 
 set the calibration register based upon the shunt and the max ampere. 
@@ -279,9 +273,9 @@ Returns false if parameter out of range.
 Returns false if it could not write settings to device.
 - **bool isCalibrated()** returns true if CurrentLSB has been calculated by **setMaxCurrentShunt()**. 
 - **float getCurrentLSB()** returns the LSB in Ampere == precision of the calibration.
-- **float getCurrentLSB_mA()** returns the LSB in milliampere.
-- **float getCurrentLSB_uA()** returns the LSB in microampere.
-- **float getShunt()** returns the value set for the shunt.
+- **float getCurrentLSB_mA()** returns the LSB in milliAmpere.
+- **float getCurrentLSB_uA()** returns the LSB in microAmpere.
+- **float getShunt()** returns the value set for the shunt in Ohm.
 - **float getMaxCurrent()** returns the value for the maxCurrent which can be corrected.
 
 To print these values one might use https://github.com/RobTillaart/printHelpers 
@@ -313,7 +307,7 @@ Meant for debugging only, reg = 0..5. Check datasheet for the details.
 - update documentation
 
 
-#### Should 
+#### Should
 
 - sync INA226 where meaningful
 - improve error handling
@@ -325,10 +319,12 @@ Meant for debugging only, reg = 0..5. Check datasheet for the details.
 - write and verify examples
 - add a **setCurrentLSB(uint16_t mA)** function ?
   - maxAmpere as derived value
-
+- disconnected load.
+  - can it be recognized? => current drop?
 
 #### Could
 
+- clean up magic numbers in the code
 - calibration
   - autocorrect \_current_LSB  round number
   - maxCurrent? how much?
@@ -337,8 +333,7 @@ Meant for debugging only, reg = 0..5. Check datasheet for the details.
     - less iterations?
     - local var for current_lsb?
     - does this matter as it is often a one time action?
-- disconnected load, 
-  - can it be recognized? => current drop?
+
 - cache configuration ? ==> 2 bytes
   - what is gained? both getting and setting is faster.
     a few milliseconds per call?
@@ -361,4 +356,3 @@ donate through PayPal or GitHub sponsors.
 
 Thank you,
 
-