Diff: battery_gauge_bq35100.h

Revision:

2:4c699a813451

Parent:

1:ee7cc8d75283

diff -r ee7cc8d75283 -r 4c699a813451 battery_gauge_bq35100.h
--- a/battery_gauge_bq35100.h	Thu Nov 09 22:55:13 2017 +0000
+++ b/battery_gauge_bq35100.h	Fri Nov 10 17:07:06 2017 +0000
@@ -33,7 +33,7 @@
  * NOTE: the battery shield board on the C030 platform will not work
  * at the default I2C clock frequency.
  */
-#define I2C_CLOCK_FREQUENCY 250
+#define I2C_CLOCK_FREQUENCY 100
 
 /** Settling time after gaugeEnable is set high */
 #define GAUGE_ENABLE_SETTLING_TIME_MS 10
@@ -66,70 +66,78 @@
     ~BatteryGaugeBq35100(void);
 
     /** Initialise the BQ35100 chip.  Once initialised
-    * the chip is put into its lowest power state.  Any API call
-    * will awaken the chip from this state and then return it once
-    * more to the lowest possible power state.
-    * @param pI2c a pointer to the I2C instance to use.
-    * @param gaugeEnable the gauge enable pin (will be set high to enable the chip).
-    * @param address 7-bit I2C address of the battery gauge chip.
-    * @param sealCodes the two 16 bit seal codes (step 1 in the higher word, step 2 in the
-    *                  lower word, NOT byte reversed) that will unseal the device if it is sealed.
-    * @return true if successful, otherwise false.
-    */
-    bool init(I2C * pI2c, PinName gaugeEnable, uint8_t address = BATTERY_GAUGE_BQ35100_ADDRESS,
+     * the chip is put into its lowest power state.  Any API call
+     * will awaken the chip from this state and then return it once
+     * more to the lowest possible power state.
+     * @param pI2c a pointer to the I2C instance to use.
+     * @param gaugeEnable the gauge enable pin (will be set high to enable the chip).
+     * @param address 7-bit I2C address of the battery gauge chip.
+     * @param sealCodes the two 16 bit seal codes (step 1 in the higher word, step 2 in the
+     *                  lower word, NOT byte reversed) that will unseal the device if it is sealed.
+     * @return true if successful, otherwise false.
+     */
+    bool init(I2C * pI2c, PinName gaugeEnable = NC, uint8_t address = BATTERY_GAUGE_BQ35100_ADDRESS,
               uint32_t sealCodes = SEAL_CODES_DEFAULT);
     
     /** Switch on the battery gauge.  Battery gauging must be switched on
-    * for the battery capacity and percentage readings to be valid. The
-    * chip will consume more when battery gauging is switched on.
-    * @return true if successful, otherwise false.
-    */
-    bool enableGauge(void);
+     * for the battery capacity and percentage readings to be valid. The
+     * chip will consume more when battery gauging is switched on.
+     * @param nonVolatile if set to true then the chip will add the
+     *                    accumulated capacity values to those taken
+     *                    previously in non-volatile memory when
+     *                    disableGauge() is called.
+     * @return true if successful, otherwise false.
+     */
+    bool enableGauge(bool nonVolatile = false);
 
-    /** Switch off the battery gauge.
-    * @return true if successful, otherwise false.
-    */
+    /** Switch off the battery gauge.  If gauging to non-volatile
+     * memory was switched on, the accumulated capacity values
+     * will be stored in non-volatile memory.  Please see the warning
+     * in section 5.1.1 of the TI BQ35100 technical reference manual
+     * concerning how frequently this should be done.
+     * @return true if successful, otherwise false.
+     */
     bool disableGauge(void);
 
     /** Check whether battery gauging is enabled or not.
-    * @return true if battery gauging is enabled, otherwise false.
-    */
+     * @return true if battery gauging is enabled, otherwise false.
+     */
     bool isGaugeEnabled(void);
 
     /** Set the designed capacity of the cell.
-    * @param capacityMAh the capacity.
-    * @return true if successful, otherwise false.
-    */
+     * @param capacityMAh the capacity.
+     * @return true if successful, otherwise false.
+     */
     bool setDesignCapacity(uint32_t capacityMAh);
 
     /** Get the designed capacity of the cell.
-    * @param pCapacityMAh a palce to put the capacity.
-    * @return true if successful, otherwise false.
-    */
+     * @param pCapacityMAh a place to put the capacity.
+     * @return true if successful, otherwise false.
+     */
     bool getDesignCapacity(uint32_t *pCapacityMAh);
 
     /** Read the temperature of the BQ35100 chip.
-    * @param pTemperatureC place to put the temperature reading.
-    * @return true if successful, otherwise false.
-    */
+     * @param pTemperatureC place to put the temperature reading.
+     * @return true if successful, otherwise false.
+     */
     bool getTemperature(int32_t *pTemperatureC);
 
     /** Read the voltage of the battery.
-    * @param pVoltageMV place to put the voltage reading.
-    * @return true if successful, otherwise false.
-    */
+     * @param pVoltageMV place to put the voltage reading.
+     * @return true if successful, otherwise false.
+     */
     bool getVoltage(int32_t *pVoltageMV);
 
     /** Read the current flowing from the battery.
-    * @param pCurrentMA place to put the current reading.
-    * @return true if successful, otherwise false.
-    */
+     * @param pCurrentMA place to put the current reading.
+     * @return true if successful, otherwise false.
+     */
     bool getCurrent(int32_t *pCurrentMA);
 
     /** Read the battery capacity used in uAh (NOT mAh).
-    * @param pCapacityUAh place to put the capacity reading.
-    * @return true if successful, otherwise false.
-    */
+     * @param pCapacityUAh place to put the capacity reading.
+     * @return true if successful, otherwise false.
+     */
     bool getUsedCapacity(uint32_t *pCapacityUAh);
 
     /** Get the remaining battery capacity in uAh (NOT mAh).
@@ -141,33 +149,89 @@
     bool getRemainingCapacity(uint32_t *pCapacityUAh);
 
     /** Get the remaining battery capacity in percent.
-    * NOTE: this relies on the Design Capacity of the battery
-    * having been set correctly.
-    * @param pBatteryPercentage place to put the reading.
-    * @return true if successful, otherwise false.
-    */
+     * NOTE: this relies on the Design Capacity of the battery
+     * having been set correctly.
+     * @param pBatteryPercentage place to put the reading.
+     * @return true if successful, otherwise false.
+     */
     bool getRemainingPercentage(int32_t *pBatteryPercentage);
 
+    /** Indicate that a new battery has been inserted.
+     * @param capacityMAh the capacity of the battery.
+     * @return true if successful, otherwise false.
+     */
+    bool newBattery(uint32_t capacityMAh);
+
+    /** An advanced function to read configuration data from the BQ35100 chip memory.
+     * Please refer to the TI BQ35100 technical reference manual for details of the
+     * address space.This function will unseal the device (using the seal codes
+     * passed into init()) in order to perform the read from data flash and will
+     * restore the previous security state afterwards.
+     * @param address the address of the data within the class.
+     * @param pData a place to put the read data.
+     * @param length the size of the place to put the data block.
+     * @return true if successful, otherwise false.
+     */
+    bool advancedGetConfig(int32_t address, char * pData, int32_t length);
+
+    /** An advanced function to write configuration data to the BQ35100 chip memory.
+     * Please refer to the TI BQ35100 technical reference manual for details of the
+     * address space.  This function will unseal the device (using the seal codes
+     * passed into init()) in order to perform the write to data flash and will
+     * restore the previous security state afterwards.  However, if the write
+     * operation requires full access (e.g. to change the seal codes) then
+     * the security mode of the device must be changed (through a call to
+     * advancedGetSecurityMode()) first.  If this function is used to change the seal
+     * or full access codes for the chip then init() should be called once more to
+     * update the codes used by this driver.
+     * @param address the address to write to.
+     * @param pData a pointer to the data to be written.
+     * @param length the size of the data to be written.
+     * @return true if successful, otherwise false.
+     */
+    bool advancedSetConfig(int32_t address, const char * pData, int32_t length);
+
+    /** Send a control word (see section 11.1 of the BQ35100 technical reference manual).
+     * @param controlWord the control word to send.
+     * @param pDataReturned a place to put the word of data that could be returned,
+     *        depending on which control word is used (may be NULL).
+     * @return true if successful, otherwise false.
+     */
+    bool advancedSendControlWord(uint16_t controlWord, uint16_t *pDataReturned);
+    
+    /** Read two bytes starting at a given address on the chip.
+     * See sections 11.3 to 11.18 of the BQ35100 technical reference manual for the list
+     * of addresses.
+     * NOTE: this is not a read from data flash, for that you need the advancedGetConfig()
+     * method.
+     * @param address the start address to read from.  For instance, for temperature this is 0x06.
+     * @param pDataReturned a place to put the word of data returned.
+     * @return true if successful, otherwise false.
+     */
+    bool advancedGet(uint8_t address, uint16_t *pDataReturned);
+
     /** Advanced function to get the security mode of the chip.
-    * @return the security mode.
-    */
+     * @return the security mode.
+     */
     SecurityMode advancedGetSecurityMode(void);
 
-    /** Set the security mode of the chip.  SECURITY_MODE_UNSEALED mode allows
-    * writes to the chip and read access to certain proteced areas while
-    * SECURITY_MODE_FULL_ACCESS, in addition, allows the security codes
-    * to be updated.  All of the functions in this class are able to work with a
-    * SEALED chip, provided the correct codes are provided to the init() function.
-    * NOTE: it is only possible to move to SECURITY_MODE_FULL_ACCESS from
-    * SECURITY_MODE_UNSEALED.
-    * @return true if successful, otherwise false.
-    */
+    /** Advanced function to set the security mode of the chip.
+     * SECURITY_MODE_UNSEALED mode allows writes to the chip and read access to
+     * certain proteced areas while SECURITY_MODE_FULL_ACCESS, in addition,
+     * allows the security codes to be updated.  All of the functions in this
+     * class are able to work with a SEALED chip, provided the correct codes
+     * are provided to the init() function.
+     * NOTE: it is only possible to move to SECURITY_MODE_FULL_ACCESS from
+     * SECURITY_MODE_UNSEALED.
+     * @return true if successful, otherwise false.
+     */
     bool advancedSetSecurityMode(SecurityMode securityMode);
     
-    /** Do a hard reset of the chip, reinitialising RAM data to defaults from ROM.
-    * Note: the security mode of the chip is unaffected.
-    * @return true if successful, otherwise false.
-    */
+    /** Advanced function to perform a hard reset of the chip, reinitialising RAM
+     * data to defaults from ROM.
+     * Note: the security mode of the chip is unaffected.
+     * @return true if successful, otherwise false.
+     */
     bool advancedReset(void);
     
 protected:
@@ -183,8 +247,6 @@
     uint32_t gFullAccessCodes;
     /** Flag to indicate device is ready. */
     bool gReady;
-    /** Flag to indicate that monitor mode is active. */
-    bool gGaugeOn;
     
     /** Read two bytes starting at a given address.
      * Note: gpI2c should be locked before this is called.
@@ -208,7 +270,7 @@
      * @param length the size of the place to put the data block.
      * @return true if successful, otherwise false.
      */
-    bool readExtendedData(int32_t address, int32_t length, char * pData);
+    bool readExtendedData(int32_t address, char * pData, int32_t length);
     
     /** Write an extended data block.
      * Note: gpI2c should be locked before this is called.
@@ -217,7 +279,7 @@
      * @param length the size of the data to be written.
      * @return true if successful, otherwise false.
      */
-    bool writeExtendedData(int32_t address, int32_t length, const char * pData);
+    bool writeExtendedData(int32_t address, const char * pData, int32_t length);
 
     /** Get the security mode of the chip.
      * Note: gpI2c should be locked before this is called.