Add extended configuration parameters and flags

- Updated to version 1.0.2
- Added ability to configure DesingEnergy, TaperRate and TerminationVoltage for more accurate gauging
- Added ability to monitor ITPOR flag so configuration can be applied only when needed
- Added ability to monitor discharge and full charge flags
- Added example sketch demonstrating all of the above

Author: keton

examples/BQ27441_Extended_Configuration/BQ27441_Extended_Configuration.ino

@@ -0,0 +1,103 @@
+#include <SparkFunBQ27441.h>
+
+// Set BATTERY_CAPACITY to the design capacity of your battery in mAh.
+const uint16_t BATTERY_CAPACITY = 2850;
+
+//lowest operational voltage in mV
+const uint16_t TERMINATE_VOLTAGE = 3000;
+
+//current at which charger stops charging battery in mA
+//in case of Sparkfun Battery Babysitter board:
+// 100mA charge current --> 12mA
+// 500mA charge current --> 60mA
+const uint16_t TAPER_CURRENT = 60;
+
+void setup()
+{
+    Serial.begin(115200);
+
+    if (!lipo.begin()) // begin() will return true if communication is successful
+    {
+        // If communication fails, print an error message and loop forever.
+        Serial.println("Error: Unable to communicate with BQ27441.");
+        Serial.println("  Check wiring and try again.");
+        Serial.println("  (Battery must be plugged into Battery Babysitter!)");
+        while (1)
+            ;
+    }
+    Serial.println("Connected to BQ27441!");
+
+    if (lipo.itporFlag()) //write config parameters only if needed
+    {
+        Serial.println("Writing gague config");
+
+        lipo.enterConfig();                 // To configure the values below, you must be in config mode
+        lipo.setCapacity(BATTERY_CAPACITY); // Set the battery capacity
+
+        /*
+            Design Energy should be set to be Design Capacity × 3.7 if using the bq27441-G1A or Design
+            Capacity × 3.8 if using the bq27441-G1B
+        */
+        lipo.setDesignEnergy(BATTERY_CAPACITY * 3.7f);
+
+        /*
+            Terminate Voltage should be set to the minimum operating voltage of your system. This is the target
+            where the gauge typically reports 0% capacity
+        */
+        lipo.setTerminateVoltage(TERMINATE_VOLTAGE);
+
+        /*
+            Taper Rate = Design Capacity / (0.1 * Taper Current)
+        */
+        lipo.setTaperRate(10 * BATTERY_CAPACITY / TAPER_CURRENT);
+
+        lipo.exitConfig(); // Exit config mode to save changes
+    }
+    else
+    {
+        Serial.println("Using existing gague config");
+    }
+}
+
+void printBatteryStats()
+{
+    // Read battery stats from the BQ27441-G1A
+    unsigned int soc = lipo.soc();                   // Read state-of-charge (%)
+    unsigned int volts = lipo.voltage();             // Read battery voltage (mV)
+    int current = lipo.current(AVG);                 // Read average current (mA)
+    unsigned int fullCapacity = lipo.capacity(FULL); // Read full capacity (mAh)
+    unsigned int capacity = lipo.capacity(REMAIN);   // Read remaining capacity (mAh)
+    int power = lipo.power();                        // Read average power draw (mW)
+    int health = lipo.soh();                         // Read state-of-health (%)
+
+    // Assemble a string to print
+    String toPrint = "[" + String(millis() / 1000) + "] ";
+    toPrint += String(soc) + "% | ";
+    toPrint += String(volts) + " mV | ";
+    toPrint += String(current) + " mA | ";
+    toPrint += String(capacity) + " / ";
+    toPrint += String(fullCapacity) + " mAh | ";
+    toPrint += String(power) + " mW | ";
+    toPrint += String(health) + "%";
+
+    //fast charging allowed
+    if (lipo.chgFlag())
+        toPrint += " CHG";
+
+    //full charge detected
+    if (lipo.fcFlag())
+        toPrint += " FC";
+
+    //battery is discharging
+    if (lipo.dsgFlag())
+        toPrint += " DSG";
+
+    // Print the string
+    Serial.println(toPrint);
+}
+
+void loop()
+{
+    printBatteryStats();
+    delay(1000);
+}

library.properties

@@ -1,5 +1,5 @@
 name=SparkFun BQ72441 LiPo Fuel Gauge Arduino Library
-version=1.0.1
+version=1.0.2
 author=SparkFun Electronics
 maintainer=SparkFun Electronics
 sentence=An Arduino library for interfacing with the BQ72441-G1 LiPo Fuel Gauge

src/SparkFunBQ27441.cpp

@@ -53,12 +53,58 @@ bool BQ27441::setCapacity(uint16_t capacity)
 	// Write to STATE subclass (82) of BQ27441 extended memory.
 	// Offset 0x0A (10)
 	// Design capacity is a 2-byte piece of data - MSB first
+	// Unit: mAh
 	uint8_t capMSB = capacity >> 8;
 	uint8_t capLSB = capacity & 0x00FF;
 	uint8_t capacityData[2] = {capMSB, capLSB};
 	return writeExtendedData(BQ27441_ID_STATE, 10, capacityData, 2);
 }
 
+// Configures the design energy of the connected battery.
+bool BQ27441::setDesignEnergy(uint16_t energy)
+{
+	// Write to STATE subclass (82) of BQ27441 extended memory.
+	// Offset 0x0C (12)
+	// Design energy is a 2-byte piece of data - MSB first
+	// Unit: mWh
+	uint8_t enMSB = energy >> 8;
+	uint8_t enLSB = energy & 0x00FF;
+	uint8_t energyData[2] = {enMSB, enLSB};
+	return writeExtendedData(BQ27441_ID_STATE, 12, energyData, 2);
+}
+
+// Configures the terminate voltage.
+bool BQ27441::setTerminateVoltage(uint16_t voltage)
+{
+	// Write to STATE subclass (82) of BQ27441 extended memory.
+	// Offset 0x0F (16)
+	// Termiante voltage is a 2-byte piece of data - MSB first
+	// Unit: mV
+	// Min 2500, Max 3700
+	if(voltage<2500) voltage=2500;
+	if(voltage>3700) voltage=3700;
+	
+	uint8_t tvMSB = voltage >> 8;
+	uint8_t tvLSB = voltage & 0x00FF;
+	uint8_t tvData[2] = {tvMSB, tvLSB};
+	return writeExtendedData(BQ27441_ID_STATE, 16, tvData, 2);
+}
+
+// Configures taper rate of connected battery.
+bool BQ27441::setTaperRate(uint16_t rate)
+{
+	// Write to STATE subclass (82) of BQ27441 extended memory.
+	// Offset 0x1B (27)
+	// Termiante voltage is a 2-byte piece of data - MSB first
+	// Unit: 0.1h
+	// Max 2000
+	if(rate>2000) rate=2000;
+	uint8_t trMSB = rate >> 8;
+	uint8_t trLSB = rate & 0x00FF;
+	uint8_t trData[2] = {trMSB, trLSB};
+	return writeExtendedData(BQ27441_ID_STATE, 27, trData, 2);
+}
+
 /*****************************************************************************
  ********************** Battery Characteristics Functions ********************
  *****************************************************************************/
@@ -296,6 +342,38 @@ bool BQ27441::socfFlag(void)
 
 }
 
+// Check if the ITPOR flag is set
+bool BQ27441::itporFlag(void)
+{
+	uint16_t flagState = flags();
+	
+	return flagState & BQ27441_FLAG_ITPOR;
+}
+
+// Check if the FC flag is set
+bool BQ27441::fcFlag(void)
+{
+	uint16_t flagState = flags();
+	
+	return flagState & BQ27441_FLAG_FC;
+}
+
+// Check if the CHG flag is set
+bool BQ27441::chgFlag(void)
+{
+	uint16_t flagState = flags();
+	
+	return flagState & BQ27441_FLAG_CHG;
+}
+
+// Check if the DSG flag is set
+bool BQ27441::dsgFlag(void)
+{
+	uint16_t flagState = flags();
+	
+	return flagState & BQ27441_FLAG_DSG;
+}
+
 // Get the SOC_INT interval delta
 uint8_t BQ27441::sociDelta(void)
 {

src/SparkFunBQ27441.h

@@ -96,6 +96,24 @@ class BQ27441 {
 	*/
 	bool setCapacity(uint16_t capacity);
 
+	/**
+	    Configures the design energy of the connected battery.
+		
+		@param energy of battery (unsigned 16-bit value)
+		@return true if energy successfully set.
+	*/
+	bool setDesignEnergy(uint16_t energy);
+
+	/**
+	    Configures terminate voltage (lowest operational voltage of battery powered circuit)
+		
+		@param voltage of battery (unsigned 16-bit value)
+		@return true if energy successfully set.
+	*/
+	bool setTerminateVoltage(uint16_t voltage);
+
+	bool setTaperRate(uint16_t rate);
+
 	/////////////////////////////
 	// Battery Characteristics //
 	/////////////////////////////
@@ -244,6 +262,35 @@ class BQ27441 {
 	*/
 	bool socfFlag(void);
 
+	/**
+	    Check if the ITPOR flag is set in flags()
+		
+		@return true if flag is set
+	*/
+	bool itporFlag(void);
+
+	/**
+	    Check if the FC flag is set in flags()
+		
+		@return true if flag is set
+	*/
+	bool fcFlag(void);
+
+	/**
+	    Check if the CHG flag is set in flags()
+		
+		@return true if flag is set
+	*/
+	bool chgFlag(void);
+
+	/**
+	    Check if the DSG flag is set in flags()
+		
+		@return true if flag is set
+	*/
+	bool dsgFlag(void);
+
+
 	/**
 	    Get the SOC_INT interval delta