Comments en masse. Library clean up.

Author: Jim Lindblom

examples/BQ27441_Basic/BQ27441_Basic.ino

@@ -1,33 +1,62 @@
+/******************************************************************************
+BQ27441_Basic
+BQ27441 Library Basic Example
+Jim Lindblom @ SparkFun Electronics
+May 9, 2016
+https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library
+
+Demonstrates how to set up the BQ27441 and read state-of-charge (soc),
+battery voltage, average current, remaining capacity, average power, and
+state-of-health (soh).
+
+After uploading, open up the serial monitor to 115200 baud to view your 
+battery's stats.
+
+Hardware Resources:
+- Arduino Development Board
+- SparkFun Battery Babysitter
+
+Development environment specifics:
+Arduino 1.6.7
+SparkFun Battery Babysitter v1.0
+Arduino Uno (any 'duino should do)
+******************************************************************************/
 #include <SparkFunBQ27441.h>
 
+// Set BATTERY_CAPACITY to the design capacity of your battery.
 const unsigned int BATTERY_CAPACITY = 850; // e.g. 850mAh battery
-unsigned int fullCapacity;
+
 void setupBQ27441(void)
 {
-  if (!lipo.begin())
+  // Use lipo.begin() to initialize the BQ27441-G1A and confirm that it's
+  // connected and communicating.
+  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!");
 
+  // Uset lipo.setCapacity(BATTERY_CAPACITY) to set the design capacity
+  // of your battery.
   lipo.setCapacity(BATTERY_CAPACITY);
-  fullCapacity = lipo.capacity(FULL);
-  Serial.print("Full charge capacity set to: ");
-  Serial.println(String(fullCapacity) + " mAh");
 }
 
 void printBatteryStats()
 {
-  unsigned int soc = lipo.soc();
-  unsigned int volts = lipo.voltage();
-  int current = lipo.current(AVG);
-  unsigned int capacity = lipo.capacity(REMAIN);
-  int power = lipo.power();
-  int health = lipo.soh();
+  // 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 (%)
 
+  // Now print out those values:
   String toPrint = String(soc) + "% | ";
   toPrint += String(volts) + " mV | ";
   toPrint += String(current) + " mA | ";

examples/BQ27441_GPOUT_BAT_LOW/BQ27441_GPOUT_BAT_LOW.ino

@@ -1,36 +1,81 @@
+/******************************************************************************
+BQ27441_GPOUT_BAT_LOW
+BQ27441 Library GPOUT Example - Battery low Mode
+Jim Lindblom @ SparkFun Electronics
+May 9, 2016
+https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library
+
+Demonstrates how to use the BQ27441's BAT_LOW function on GPOUT. In this mode
+GPOUT will become active whenever the battery goes below a set threshold.
+
+In addition to I2C, connect GPOUT to pin 2 of your Arduino.
+
+After uploading, open up the serial monitor to 115200 baud to view your 
+battery's stats. They should only print when the percentage goes up or down
+by 1%.
+
+Hardware Resources:
+- Arduino Development Board
+- SparkFun Battery Babysitter
+
+Development environment specifics:
+Arduino 1.6.7
+SparkFun Battery Babysitter v1.0
+Arduino Uno (any 'duino should do)
+******************************************************************************/
 #include <SparkFunBQ27441.h>
 
+// Set BATTERY_CAPACITY to the design capacity of your battery.
 const unsigned int BATTERY_CAPACITY = 850; // e.g. 850mAh battery
-unsigned int fullCapacity;
+
+const byte SOCI_SET = 15; // Interrupt set threshold at 20%
+const byte SOCI_CLR = 20; // Interrupt clear threshold at 25%
+const byte SOCF_SET = 5; // Final threshold set at 5%
+const byte SOCF_CLR = 10; // Final threshold clear at 10%
+
+// Arduino pin connected to BQ27441's GPOUT pin
+const int GPOUT_PIN = 2;
 
 void setupBQ27441(void)
 {
-  if (!lipo.begin())
+  pinMode(GPOUT_PIN, INPUT_PULLUP); // Set the GPOUT pin as an input w/ pullup
+  
+  // Use lipo.begin() to initialize the BQ27441-G1A and confirm that it's
+  // connected and communicating.
+  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!");
 
-  lipo.enterConfig();
-  lipo.setGPOUTPolarity(HIGH); // active-high
-  lipo.setGPOUTFunction(BAT_LOW); // BAT_LOW mode
-  lipo.setSOC1Thresholds(20, 25);
-  lipo.setSOCFThresholds(5, 10);
+  // In this example, we'll manually enter and exit config mode. By controlling
+  // config mode manually, you can set the chip up faster -- completing all of
+  // the set up in a single config mode sweep.
+  lipo.enterConfig(); // To configure the values below, you must be in config mode
+  lipo.setCapacity(BATTERY_CAPACITY); // Set the battery capacity
+  lipo.setGPOUTPolarity(LOW); // Set GPOUT to active-high
+  lipo.setGPOUTFunction(BAT_LOW); // Set GPOUT to BAT_LOW mode
+  lipo.setSOC1Thresholds(SOCI_SET, SOCI_CLR); // Set SOCI set and clear thresholds
+  lipo.setSOCFThresholds(SOCF_SET, SOCF_CLR); // Set SOCF set and clear thresholds
   lipo.exitConfig();
 
+  // Use lipo.GPOUTPolarity to read from the chip and confirm the changes
   if (lipo.GPOUTPolarity())
     Serial.println("GPOUT set to active-HIGH");
   else
     Serial.println("GPOUT set to active-LOW");
 
+  // Use lipo.GPOUTFunction to confirm the functionality of GPOUT
   if (lipo.GPOUTFunction())
     Serial.println("GPOUT function set to BAT_LOW");
   else
     Serial.println("GPOUT function set to SOC_INT");
 
+  // Read the set and clear thresholds to make sure they were set correctly
   Serial.println("SOC1 Set Threshold: " + String(lipo.SOC1SetThreshold()));
   Serial.println("SOC1 Clear Threshold: " + String(lipo.SOC1ClearThreshold()));
   Serial.println("SOCF Set Threshold: " + String(lipo.SOCFSetThreshold()));
@@ -39,25 +84,26 @@ void setupBQ27441(void)
 
 void printBatteryStats()
 {
-  unsigned int soc = lipo.soc();
-  unsigned int volts = lipo.voltage();
-  int current = lipo.current(AVG);
-  unsigned int capacity = lipo.capacity(REMAIN);
-  int power = lipo.power();
-  int health = lipo.soh();
-  fullCapacity = lipo.capacity(FULL);
+  // 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(soc) + "% | ";
   toPrint += String(volts) + " mV | ";
   toPrint += String(current) + " mA | ";
   toPrint += String(capacity) + " / ";
   toPrint += String(fullCapacity) + " mAh | ";
   toPrint += String(power) + " mW | ";
   toPrint += String(health) + "%";
-
-  toPrint += " | 0x" + String(lipo.status(), HEX) + " | ";
-  toPrint += "0x" + String(lipo.flags(), HEX) + " | ";
+  toPrint += " | 0x" + String(lipo.flags(), HEX);
 
+  // Print the string
   Serial.println(toPrint);
 }
 
@@ -70,5 +116,15 @@ void setup()
 void loop() 
 {
   printBatteryStats();
+  
+  // If the GPOUT interrupt is active (low)
+  if (!digitalRead(GPOUT_PIN))
+  {
+    // Check which of the flags triggered the interrupt
+    if (lipo.socfFlag()) 
+      Serial.println("<!-- WARNING: Battery Dangerously low -->");
+    else if (lipo.socFlag())
+      Serial.println("<!-- WARNING: Battery Low -->");
+  }
   delay(1000);
-}
+}

examples/BQ27441_GPOUT_SOC_INT/BQ27441_GPOUT_SOC_INT.ino

@@ -1,47 +1,92 @@
+/******************************************************************************
+BQ27441_GPOUT_SOC_INT
+BQ27441 Library GPOUT Example - State-of-charge interval mode
+Jim Lindblom @ SparkFun Electronics
+May 9, 2016
+https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library
+
+Demonstrates how to use the BQ27441's SOC_INT function on GPOUT. In this mode
+GPOUT will pulse every time the state-of-charge (soc) goes up or down by a 
+set percentage integer.
+
+In addition to I2C, connect GPOUT to pin 2 of your Arduino.
+
+After uploading, open up the serial monitor to 115200 baud to view your 
+battery's stats. They should only print when the percentage goes up or down
+by 1%.
+
+Hardware Resources:
+- Arduino Development Board
+- SparkFun Battery Babysitter
+
+Development environment specifics:
+Arduino 1.6.7
+SparkFun Battery Babysitter v1.0
+Arduino Uno (any 'duino should do)
+******************************************************************************/
 #include <SparkFunBQ27441.h>
 
+// Set BATTERY_CAPACITY to the design capacity of your battery.
 const unsigned int BATTERY_CAPACITY = 850; // e.g. 850mAh battery
 
+// Arduino pin connected to BQ27441's GPOUT pin
 const int GPOUT_PIN = 2;
 
+// Set the integer percentage change that triggers an interrupt
+const int PERCENTAGE_INTERVAL = 1;
+
 void setupBQ27441(void)
 {
-  if (!lipo.begin())
+  pinMode(GPOUT_PIN, INPUT_PULLUP); // Set the GPOUT pin as an input w/ pullup
+  
+  // Use lipo.begin() to initialize the BQ27441-G1A and confirm that it's
+  // connected and communicating.
+  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!");
 
-  lipo.enterConfig();
-  lipo.setCapacity(BATTERY_CAPACITY);
-  lipo.setGPOUTPolarity(LOW); // active-low
-  lipo.setGPOUTFunction(SOC_INT); // SOC_INT mode
-  lipo.setSOCIDelta(1);
-  lipo.exitConfig();
+  // In this example, we'll manually enter and exit config mode. By controlling
+  // config mode manually, you can set the chip up faster -- completing all of
+  // the set up in a single config mode sweep.
+  lipo.enterConfig(); // To configure the values below, you must be in config mode
+  lipo.setCapacity(BATTERY_CAPACITY); // Set the battery capacity
+  lipo.setGPOUTPolarity(LOW); // Set GPOUT to active-low
+  lipo.setGPOUTFunction(SOC_INT); // Set GPOUT to SOC_INT mode
+  lipo.setSOCIDelta(PERCENTAGE_INTERVAL); // Set percentage change integer
+  lipo.exitConfig(); // Exit config mode to save changes
 
+  // Use lipo.GPOUTPolarity to read from the chip and confirm the changes
   if (lipo.GPOUTPolarity())
     Serial.println("GPOUT set to active-HIGH");
   else
     Serial.println("GPOUT set to active-LOW");
 
+  // Use lipo.GPOUTFunction to confirm the functionality of GPOUT
   if (lipo.GPOUTFunction())
     Serial.println("GPOUT function set to BAT_LOW");
   else
     Serial.println("GPOUT function set to SOC_INT");
-
+  
+  // Read lipo.sociDelta() to confirm the integer change value
   Serial.println("SOCI Delta: " + String(lipo.sociDelta()));
   Serial.println();
 
+  // Use lipo.pulseGPOUT() to trigger a pulse on GPOUT. This only works
+  // in SOC_INT mode.
   Serial.println("Testing GPOUT Pulse");
   lipo.pulseGPOUT();
-  int timeout = 10000;
+  int timeout = 10000; // The pulse can take a while to occur. Set max to 10s
   while ((digitalRead(GPOUT_PIN)) && timeout--)
-    delay(1);
+    delay(1); // Wait for GPOUT to go high, or timeout to occur
   if (timeout > 0) 
   {
+	// If GPOUT pulsed, print success message.
     Serial.print("GPOUT test successful!");
     Serial.println("(" + String(10000 - timeout) + ")");
     Serial.print("GPOUT will pulse whenever the SoC ");
@@ -52,6 +97,8 @@ void setupBQ27441(void)
   }
   else
   {
+	// If GPOUT didn't pulse, something went wrong. Print error message
+	// and loop forever.
     Serial.println("GPOUT didn't pulse.");
     Serial.print("Make sure it's connected to pin ");
     Serial.print(GPOUT_PIN);
@@ -62,14 +109,16 @@ void setupBQ27441(void)
 
 void printBatteryStats()
 {
-  unsigned int soc = lipo.soc();
-  unsigned int volts = lipo.voltage();
-  int current = lipo.current(AVG);
-  unsigned int capacity = lipo.capacity(REMAIN);
-  int power = lipo.power();
-  int health = lipo.soh();
-  unsigned int fullCapacity = lipo.capacity(FULL);
+  // 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 | ";
@@ -78,25 +127,23 @@ void printBatteryStats()
   toPrint += String(fullCapacity) + " mAh | ";
   toPrint += String(power) + " mW | ";
   toPrint += String(health) + "%";
-
-  toPrint += " | 0x" + String(lipo.status(), HEX) + " | ";
-  toPrint += "0x" + String(lipo.flags(), HEX) + " | ";
 
+  // Print the string
   Serial.println(toPrint);
 }
 
 void setup()
 {
-  Serial.begin(115200);
-  pinMode(GPOUT_PIN, INPUT_PULLUP);
-  
+  Serial.begin(115200);  
   setupBQ27441();
 }
 
 void loop() 
 {
+  // The interrupt is set to active-low. If the GPOUT pin goes low...
   if (digitalRead(GPOUT_PIN) == LOW)
   {
+	// ...SOC_INT occurred. Print battery stats.
     printBatteryStats();
   }
 }