Documentation

Author: ArminJo

README.md

@@ -20,8 +20,8 @@ Download and extract the repository. In the Arduino IDE open the sketch with Fil
 ## Identifying the right connection
 Valuable information about battery pinout can also be found [here](https://www.laptopu.ro/community/laptop-battery-pinout/) or [here](https://powercartel.com/projects/packprobe/battery-connection/).<br/>
 The minimal connector layout is: | GROUND | THERMISTOR (103AT) | CLOCK | DATA | VCC (11 or 14 volt) | (clock and data my be switched).
-- The **thermistor** connection has 10 kOhm to ground at 25 degree celsius.
-- **Clock** und data connectors have the same resistance (around 0.3 to 1 MOhm) to ground and are next to each other.
+- The **thermistor** connection has 10 k&ohm; to ground at 25 degree celsius.
+- **Clock** und data connectors have the same resistance (around 0.3 to 1 M&ohm;) to ground and are next to each other.
 - **VCC** may not be enabled. Sometimes it gets enabled when *Host Present* is connected to ground or clock and data are pulled high to 3.3 or 5 volt.
 
 Some packs (e.g.for IBM-T41 with bq29310) require once an external voltage (e.g. 11 volt) at the VCC connector to initially get alive after full discharge condition.
@@ -37,7 +37,7 @@ Examples:
 After startup, the program scans for a connected I2C device.<br/>
 In version 4.0 a voltage and resistance measurement by means of 4 additional resistors is integrated **to identify the I2C pins**.
 It measures voltage or resistance to ground (if voltage is zero).<br/>
-**The I2c pins have around 300 kOhm to 1000 kOhm**, the thermistor 10 kOhm (sometimes up to 40 kOhm).
+**The I2c pins have around 300 k&ohm; to 1000 k&ohm;**, the thermistor 10 k&ohm; (sometimes up to 40 k&ohm;).
 
 You can try different I2C pin combinations until led stops blinking and `Found I2C device attached at address: 0x0B` is printed.
 If you connect clock or data  with the thermistor connector or ground, the scanning stops.<br/>
@@ -80,7 +80,7 @@ Basiert auf https://github.com/PowerCartel/PackProbe von Power Cartel http://pow
 
 ## Finden der Anschlüsse.
 In der Version 4.0 ist eine Spannungs und Widerstandsmessung mittels 4 Widerständen integriert, um die I2C Pins zu identifizieren.
-Die Clock und Data Eingänge waren bei meinen Packs die Anschlüsse mit einem Widerstand von ca. 300 k bis 1 MOhm nach Masse.
+Die Clock und Data Eingänge waren bei meinen Packs die Anschlüsse mit einem Widerstand von ca. 300 k bis 1 M&ohm; nach Masse.
 Nach dem Booten sucht das Programm nach einem angeschlossenen I2C Device.
 Man kann also alle möglichen Pinkombinationen von Clock und Data am Battery Pack ausprobieren.
 Bei der Richtigen hört das Blinken der Led auf und es kommt sofort die Ausgabe `Found I2C device attached at address: 0x0B` und direkt danach werden die Daten ausgegeben.
@@ -90,7 +90,7 @@ Wenn mehr als 5 Kontakte vorhanden waren, waren sie wie folgt belegt:
 - Masse und Plus doppelt. z.B. + | + | Thermistor | Data | Clock | - | -
 - Ein Enable (nur im Laptop mit Masse verbunden) und eine Signal Anschluss (nur im Battery Pack mit Masse verbunden). z.B. VCC | VCC | CLOCK | DATA | Signal | Enable | THERMISTOR | GROUND | GROUND |
 
-Der Thermo-Sensor Anschluss war uneinheitlich, mal nicht messbar beschaltet, mal 1 MOhm, mal 1,6 Volt, mal 10 kOhm nach Masse.
+Der Thermo-Sensor Anschluss war uneinheitlich, mal nicht messbar beschaltet, mal 1 M&ohm;, mal 1,6 Volt, mal 10 k&ohm; nach Masse.
 
 Zur Verbindung mit den Kontakten habe ich normales 1,5 qmm Kupferkabel aus der Hausinstallation genommen, dessen eines Ende ich mit einem Hammer etwas plattgeklopft hab. Stecknadeln oder Breadboard Wires gehen auch.
 
@@ -169,7 +169,7 @@ Cell 4 Voltage                      0x0
 
 *** CHANGED VALUES ***
 
---- Next values are from another Pack! I connected 22 Ohm Resistor -> 699 mA discharging
+--- Next values are from another Pack! I connected 22 ohm Resistor -> 699 mA discharging
 
 Voltage                             15.788 V
 Average current of last minute      -187 mA

SBMInfo/ADCUtils.h

@@ -1,7 +1,7 @@
 /*
  * ADCUtils.h
  *
- *  Copyright (C) 2016-2021  Armin Joachimsmeyer
+ *  Copyright (C) 2016-2022  Armin Joachimsmeyer
  *  Email: [email protected]
  *
  *  This file is part of Arduino-Utils https://github.com/ArminJo/Arduino-Utils.
@@ -17,12 +17,12 @@
  *  GNU General Public License for more details.
  *
  *  You should have received a copy of the GNU General Public License
- *  along with this program.  If not, see <http://www.gnu.org/licenses/gpl.html>.
+ *  along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
  *
  */
 
-#ifndef SRC_ADCUTILS_H_
-#define SRC_ADCUTILS_H_
+#ifndef _ADC_UTILS_H
+#define _ADC_UTILS_H
 
 #if defined(__AVR__) && (!defined(__AVR_ATmega4809__))
 #include <Arduino.h>
@@ -47,14 +47,6 @@
 #define ADC_PRESCALE ADC_PRESCALE128
 #endif
 
-/*
- * By replacing this value with the voltage you measured a the AREF pin after a conversion
- * with INTERNAL you can calibrate your ADC readout. For my Nanos I measured e.g. 1060 mV and 1093 mV.
- */
-#ifndef ADC_INTERNAL_REFERENCE_MILLIVOLT
-#define ADC_INTERNAL_REFERENCE_MILLIVOLT 1100L    // Value measured at the AREF pin
-#endif
-
 /*
  * Reference shift values are complicated for ATtinyX5 since we have the extra register bit REFS2
  * in ATTinyCore, this bit is handled programmatical and therefore the defines are different.
@@ -122,7 +114,7 @@
 uint16_t readADCChannel(uint8_t aChannelNumber);
 uint16_t readADCChannelWithReference(uint8_t aChannelNumber, uint8_t aReference);
 uint16_t waitAndReadADCChannelWithReference(uint8_t aChannelNumber, uint8_t aReference);
-uint16_t waitAndReadADCChannelWithReferenceAndRestoreADMUX(uint8_t aChannelNumber, uint8_t aReference);
+uint16_t waitAndReadADCChannelWithReferenceAndRestoreADMUXAndReference(uint8_t aChannelNumber, uint8_t aReference);
 uint16_t readADCChannelWithOversample(uint8_t aChannelNumber, uint8_t aOversampleExponent);
 void setADCMultiplexerAndReferenceForNextConversion(uint8_t aChannelNumber, uint8_t aReference);
 uint16_t readADCChannelWithReferenceOversample(uint8_t aChannelNumber, uint8_t aReference, uint8_t aOversampleExponent);
@@ -150,6 +142,4 @@ float getTemperature(void);
 
 #endif // defined(ADATE)
 #endif //  defined(__AVR__)
-#endif /* SRC_ADCUTILS_H_ */
-
-#pragma once
+#endif // _ADC_UTILS_H

SBMInfo/ADCUtils.cpp SBMInfo/ADCUtils.hppSBMInfo/ADCUtils.cpp renamed to SBMInfo/ADCUtils.hpp

@@ -1,9 +1,9 @@
 /*
- * ADCUtils.cpp
+ * ADCUtils.hpp
  *
  * ADC utility functions. Conversion time is defined as 0.104 milliseconds for 16 MHz Arduinos in ADCUtils.h.
  *
- *  Copyright (C) 2016-2020  Armin Joachimsmeyer
+ *  Copyright (C) 2016-2022  Armin Joachimsmeyer
  *  Email: [email protected]
  *
  *  This file is part of Arduino-Utils https://github.com/ArminJo/Arduino-Utils.
@@ -19,11 +19,23 @@
  *  GNU General Public License for more details.
  *
  *  You should have received a copy of the GNU General Public License
- *  along with this program.  If not, see <http://www.gnu.org/licenses/gpl.html>.
+ *  along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
  */
 
+
+#ifndef _ADC_UTILS_HPP
+#define _ADC_UTILS_HPP
+
 #include "ADCUtils.h"
-#if defined(__AVR__) && defined(ADATE)
+#if defined(__AVR__) && defined(ADCSRA) && defined(ADATE)
+
+/*
+ * By replacing this value with the voltage you measured a the AREF pin after a conversion
+ * with INTERNAL you can calibrate your ADC readout. For my Nanos I measured e.g. 1060 mV and 1093 mV.
+ */
+#if !defined(ADC_INTERNAL_REFERENCE_MILLIVOLT)
+#define ADC_INTERNAL_REFERENCE_MILLIVOLT    1100L    // Value measured at the AREF pin. If value > real AREF voltage, measured values are > real values
+#endif
 
 // Union to speed up the combination of low and high bytes to a word
 // it is not optimal since the compiler still generates 2 unnecessary moves
@@ -92,7 +104,7 @@ uint16_t waitAndReadADCChannelWithReference(uint8_t aChannelNumber, uint8_t aRef
  * Conversion time is defined as 0.104 milliseconds by ADC_PRESCALE in ADCUtils.h.
  * Restores ADMUX after reading
  */
-uint16_t waitAndReadADCChannelWithReferenceAndRestoreADMUX(uint8_t aChannelNumber, uint8_t aReference) {
+uint16_t waitAndReadADCChannelWithReferenceAndRestoreADMUXAndReference(uint8_t aChannelNumber, uint8_t aReference) {
     uint8_t tOldADMUX = checkAndWaitForReferenceAndChannelToSwitch(aChannelNumber, aReference);
     uint16_t tResult = readADCChannelWithReference(aChannelNumber, aReference);
     checkAndWaitForReferenceAndChannelToSwitch(tOldADMUX & MASK_FOR_ADC_CHANNELS, tOldADMUX >> SHIFT_VALUE_FOR_REFERENCE);
@@ -331,13 +343,6 @@ uint16_t readUntil4ConsecutiveValuesAreEqual(uint8_t aChannelNumber, uint8_t aDe
     return (tMax + tMin) / 2;
 }
 
-/*
- * !!! Resolution is only 20 millivolt !!!
- */
-float getVCCVoltage(void) {
-    return (getVCCVoltageMillivolt() / 1000.0);
-}
-
 /*
  * !!! Function without handling of switched reference and channel.!!!
  * Use it ONLY if you only call getVCCVoltageSimple() or getVCCVoltageMillivoltSimple() in your program.
@@ -372,6 +377,13 @@ uint16_t getVCCVoltageReadingFor1_1VoltReference(void) {
     return ((1023L * 1023L) / tVCC);
 }
 
+/*
+ * !!! Resolution is only 20 millivolt !!!
+ */
+float getVCCVoltage(void) {
+    return (getVCCVoltageMillivolt() / 1000.0);
+}
+
 /*
  * Read value of 1.1 volt internal channel using VCC (DEFAULT) as reference.
  * Handles reference and channel switching by introducing the appropriate delays.
@@ -435,8 +447,11 @@ float getTemperature(void) {
     return (tTemp / 1.22);
 #endif
 }
-#elif defined(ARDUINO_ARCH_APOLLO3)
+
+#elif defined(ARDUINO_ARCH_APOLLO3) // defined(__AVR__) && defined(ADATE)
     void ADCUtilsDummyToAvoidBFDAssertions(){
         ;
     }
-#endif // defined(__AVR__)
+#endif // defined(__AVR__) && defined(ADATE)
+
+#endif // _ADC_UTILS_HPP

SBMInfo/MeasureVoltageAndResistance.hpp

@@ -1,7 +1,7 @@
 /*
  *  MeasureVoltageAndResistance.hpp
  *
- *  Measures voltage and resistance with 1 mV and 2 Ohm resolution at the lower end.
+ *  Measures voltage and resistance with 1 mV and 2 ohm resolution at the lower end.
  *  First voltage is measured. If voltage is zero, then resistance to ground is measured using 5 volt (VCC) and 10 kOhm or 100 kOhm supply.
  *
  *  Copyright (C) 2021  Armin Joachimsmeyer
@@ -20,7 +20,7 @@
  *  GNU General Public License for more details.
  *
  *  You should have received a copy of the GNU General Public License
- *  along with this program.  If not, see <http://www.gnu.org/licenses/gpl.html>.
+ *  along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
  *
  */
 
@@ -58,9 +58,13 @@
  *      Rx = R1 * x / (1023-x)
  *
  */
+
+#ifndef _MEASURE_VOLTAGE_AND_RESISTANCE_HPP
+#define _MEASURE_VOLTAGE_AND_RESISTANCE_HPP
+
 #include <Arduino.h>
 
-#include "ADCUtils.h"
+#include "ADCUtils.hpp"
 
 //#define NO_PRINT_OF_RESISTOR_MEASURMENT_VOLTAGE // enables print of voltage at resistor under measurement (0 to VCC).
 
@@ -79,15 +83,15 @@
 #endif
 
 // Fixed attenuator for voltage measurement
-#ifndef RESISTOR_TO_VOLTAGE_PIN_KOHM
+#if !defined(RESISTOR_TO_VOLTAGE_PIN_KOHM)
 #define RESISTOR_TO_VOLTAGE_PIN_KOHM   100 // R1
 #endif
-#ifndef RESISTOR_FROM_VOLTAGE_PIN_TO_GROUND_PIN_KOHM
+#if !defined(RESISTOR_FROM_VOLTAGE_PIN_TO_GROUND_PIN_KOHM)
 #define RESISTOR_FROM_VOLTAGE_PIN_TO_GROUND_PIN_KOHM  22 // R2
 #endif
 
 // fixed resistors for resistor measurement
-#ifndef RESISTOR_2_TO_VCC_KOHM
+#if !defined(RESISTOR_2_TO_VCC_KOHM)
 #define RESISTOR_2_TO_VCC_KOHM    10 // R3
 #endif
 #define RESISTOR_1_TO_VCC_KOHM    RESISTOR_TO_VOLTAGE_PIN_KOHM // R1
@@ -152,7 +156,7 @@ uint16_t measureVoltage(uint16_t tVCCVoltageMillivolt) {
         }
     }
 #pragma GCC diagnostic pop
-#ifdef DEBUG
+#if defined(DEBUG)
         Serial.print(F("Raw="));
         Serial.println(tInputVoltageRaw);
 #endif
@@ -182,7 +186,7 @@ bool measureResistance(uint16_t aVCCVoltageMillivolt, ResistanceMeasurementResul
     if (tInputVoltage > REFERENCE_SWITCHING_VOLTAGE_THRESHOLD_MILLIVOLT) {
         if (tReadingAtVCC > tInputReading) {
             tRxOhm = (RESISTOR_1_TO_VCC_KOHM * 1000L * tInputReading) / (tReadingAtVCC - tInputReading);
-            // Here we have a resolution of 160 to 350 Ohm at 1 MOhm
+            // Here we have a resolution of 160 to 350 ohm at 1 MOhm
             // Clip at 10 MOhm
             if (tRxOhm > 9999999) {
                 tRxOhm = 9999999;
@@ -197,7 +201,7 @@ bool measureResistance(uint16_t aVCCVoltageMillivolt, ResistanceMeasurementResul
         /*
          * Switch to 1.1 volt reference increasing the resolution by around 4
          * This happens at around 28 kOhm (at 4.7 volt) depending on the current value of VCC
-         * Here we have a resolution of 24 to 37 Ohm
+         * Here we have a resolution of 24 to 37 ohm
          */
         tInputReading = waitAndReadADCChannelWithReference(OHM_CHANNEL, INTERNAL);
 
@@ -208,16 +212,16 @@ bool measureResistance(uint16_t aVCCVoltageMillivolt, ResistanceMeasurementResul
 
         /*
          * Formula is: (for 5 V and 1050 mV, in order to get a constant value)
-         * Rx = Rvcc * 1.050 V / 3.95 V = 2416 Ohm
-         * Here we have a resolution of 2 to 6 Ohm
+         * Rx = Rvcc * 1.050 V / 3.95 V = 2416 ohm
+         * Here we have a resolution of 2 to 6 ohm
          */
         const uint16_t tResistanceForThresholdVoltage = (RESISTOR_1_TO_VCC_KOHM * RESISTOR_2_TO_VCC_KOHM
                 * REFERENCE_SWITCHING_VOLTAGE_THRESHOLD_MILLIVOLT * 1000)
                 / ((RESISTOR_1_TO_VCC_KOHM + RESISTOR_2_TO_VCC_KOHM) * (5000 - REFERENCE_SWITCHING_VOLTAGE_THRESHOLD_MILLIVOLT));
         if (tRxOhm < tResistanceForThresholdVoltage) {
-#ifdef DEBUG
+#if defined(DEBUG)
     Serial.print(tResistanceForThresholdVoltage);
-    Serial.print(F(" Ohm "));
+    Serial.print(F(" ohm "));
 #endif
 //        tResistanceRange = 2;
             /*
@@ -237,7 +241,7 @@ bool measureResistance(uint16_t aVCCVoltageMillivolt, ResistanceMeasurementResul
          */
         tInputVoltage = tInputReading * 1100L / 1023;
     }
-#ifdef DEBUG
+#if defined(DEBUG)
     Serial.print(tInputReading);
     Serial.println(F(" LSB"));
 #endif
@@ -266,7 +270,7 @@ void MeasureVoltageAndResistance() {
     // to enable discharge of stray capacitance
     pinMode(VOLTAGE_MEASUREMENT_PIN, OUTPUT);
     digitalWrite(VOLTAGE_GROUND_PIN, LOW);
-#ifdef DEBUG
+#if defined(DEBUG)
     uint16_t tVCCVoltageMillivolt = printVCCVoltageMillivolt(&Serial);
 #else
     uint16_t tVCCVoltageMillivolt = getVCCVoltageMillivolt();
@@ -289,7 +293,7 @@ void MeasureVoltageAndResistance() {
 #  if defined(USE_2004_LCD)
         myLCD.setCursor(0, 3);
         myLCD.print(tStringForPrint);
-#    ifndef NO_PRINT_OF_RESISTOR_MEASURMENT_VOLTAGE
+#    if !defined(NO_PRINT_OF_RESISTOR_MEASURMENT_VOLTAGE)
         myLCD.print(F(" V          ")); // clears old resistor output
 #    else
         myLCD.print(F(" V ")); // clears old resistor output
@@ -329,7 +333,7 @@ void MeasureVoltageAndResistance() {
         myLCD.print(F(" k\xF4    "));
 #  endif
 #endif
-#ifndef NO_PRINT_OF_RESISTOR_MEASURMENT_VOLTAGE
+#if !defined(NO_PRINT_OF_RESISTOR_MEASURMENT_VOLTAGE)
         Serial.print(F(" at: "));
         Serial.print(tResistanceMeasurementResult.VoltageAtResistor, 3);
         Serial.println(F(" V"));
@@ -388,3 +392,5 @@ void printVoltageAndResistanceUsage() {
     Serial.println(F(" mV resolution is 5 mV, below 1050 mV resolution is 1 mV"));
     Serial.println();
 }
+
+#endif // _MEASURE_VOLTAGE_AND_RESISTANCE_HPP