Diff: battery_gauge_bq35100.h

Revision:

1:ee7cc8d75283

Parent:

0:cec745c014b7

Child:

2:4c699a813451

--- a/battery_gauge_bq35100.h	Mon Jul 03 16:12:22 2017 +0000
+++ b/battery_gauge_bq35100.h	Thu Nov 09 22:55:13 2017 +0000
@@ -29,8 +29,20 @@
 /** Device I2C address. */
 #define BATTERY_GAUGE_BQ35100_ADDRESS 0x55
 
-/** The default seal code. */
-#define SEAL_CODE_DEFAULT 0x8000
+/** I2C clock frequency.
+ * NOTE: the battery shield board on the C030 platform will not work
+ * at the default I2C clock frequency.
+ */
+#define I2C_CLOCK_FREQUENCY 250
+
+/** Settling time after gaugeEnable is set high */
+#define GAUGE_ENABLE_SETTLING_TIME_MS 10
+
+/** The default seal codes (step 1 in the higher word, step 2 the lower word), NOT byte reversed. */
+#define SEAL_CODES_DEFAULT 0x04143672
+
+/** The default full access codes (step 1 in the higher word, step 2 the lower word). */
+#define FULL_ACCESS_CODES_DEFAULT 0xFFFFFFFF
 
 /* ----------------------------------------------------------------
  * CLASSES
@@ -40,6 +52,14 @@
 class BatteryGaugeBq35100 {
 public:
 
+    /** The security mode of the BQ35100 chip. */
+    typedef enum {
+        SECURITY_MODE_UNKNOWN = 0x00,
+        SECURITY_MODE_FULL_ACCESS = 0x01, //!< Allows writes to all of memory.
+        SECURITY_MODE_UNSEALED = 0x02, //!< Allows writes to all of memory apart from the security codes area.
+        SECURITY_MODE_SEALED = 0x03 //!< Normal operating mode, prevents accidental writes.
+    } SecurityMode;
+
     /** Constructor. */
     BatteryGaugeBq35100(void);
     /** Destructor. */
@@ -50,30 +70,174 @@
     * 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 sealCode the 16 bit seal code that will unseal the device if it is sealed.
+    * @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,
+              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);
+
+    /** Switch off the battery gauge.
+    * @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.
+    */
+    bool isGaugeEnabled(void);
+
+    /** Set the designed capacity of the cell.
+    * @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.
+    */
+    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.
+    */
+    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.
     */
-    bool init (I2C * pI2c, uint8_t address = BATTERY_GAUGE_BQ35100_ADDRESS, uint16_t sealCode = SEAL_CODE_DEFAULT);
+    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.
+    */
+    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.
+    */
+    bool getUsedCapacity(uint32_t *pCapacityUAh);
+
+    /** Get the remaining battery capacity in uAh (NOT mAh).
+    * NOTE: this relies on the Design Capacity of the battery
+    * having been set correctly.
+    * @param pCapacityUAh place to put the capacity reading.
+    * @return true if successful, otherwise false.
+    */
+    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.
+    */
+    bool getRemainingPercentage(int32_t *pBatteryPercentage);
+
+    /** Advanced function to get the security mode of the chip.
+    * @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.
+    */
+    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.
+    */
+    bool advancedReset(void);
     
 protected:
     /** Pointer to the I2C interface. */
     I2C * gpI2c;
     /** The address of the device. */
     uint8_t gAddress;
-    /** The seal code for the device. */
-    uint16_t gSealCode;
+    /** The gauge enable pin. */
+    DigitalOut *pGaugeEnable;
+    /** The seal codes for the device (step 1 in the higher word, step 2 the lower word), NOT byte reversed. . */
+    uint32_t gSealCodes;
+    /** The full access codes for the device (step 1 in the higher word, step 2 the lower word), NOT byte reversed. . */
+    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.
-    * @param registerAddress the register address to start reading from.
-    * @param pBytes place to put the two bytes.
+     * Note: gpI2c should be locked before this is called.
+     * @param registerAddress the register address to start reading from.
+     * @param pBytes place to put the two bytes.
+     * @return true if successful, otherwise false.
+     */
+    bool getTwoBytes(uint8_t registerAddress, uint16_t *pBytes);
+    
+    /** Compute the checksum of a block of memory in the chip.
+     * @param pData a pointer to the data block.
+     * @parm length the length over which to compute the checksum.
+     * @return the checksum value.
+     */
+    uint8_t computeChecksum(const char * pData, int32_t length);
+
+    /** Read data of a given length and class ID.
+     * Note: gpI2c should be locked before this is called.
+     * @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 readExtendedData(int32_t address, int32_t length, char * pData);
+    
+    /** Write an extended data block.
+     * Note: gpI2c should be locked before this is called.
+     * @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 writeExtendedData(int32_t address, int32_t length, const char * pData);
+
+    /** Get the security mode of the chip.
+     * Note: gpI2c should be locked before this is called.
+     * @return the security mode.
+     */
+    SecurityMode getSecurityMode(void);
+
+    /** Set the security mode of the chip.
+     * Note: gpI2c should be locked before this is called.
+     * @param securityMode the security mode to set.
+     * @return true if successful, otherwise false.
+     */
+    bool setSecurityMode(SecurityMode securityMode);
+    
+    /** Make sure that the chip is awake and has taken a reading.
+    * Note: the function does its own locking of gpI2C so that it isn't
+    * held for the entire time we wait for ADC readings to complete.
     * @return true if successful, otherwise false.
     */
-    bool getTwoBytes (uint8_t registerAddress, uint16_t *pBytes);
-
+    bool makeAdcReading(void);
 };
 
 #endif