battery_gauge_bq35100.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017 u-blox
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef BATTERY_GAUGE_BQ35100_H
00018 #define BATTERY_GAUGE_BQ35100_H
00019 
00020 /**
00021  * @file battery_gauge_bq35100.h
00022  * This file defines the API to the TI BQ35100 battery gauge chip.
00023  */
00024 
00025 /* ----------------------------------------------------------------
00026  * COMPILE-TIME MACROS
00027  * -------------------------------------------------------------- */
00028 
00029 /** Device I2C address. */
00030 #define BATTERY_GAUGE_BQ35100_ADDRESS 0x55
00031 
00032 /** I2C clock frequency.
00033  * NOTE: the battery shield board on the C030 platform will not work
00034  * at the default I2C clock frequency.
00035  */
00036 #define I2C_CLOCK_FREQUENCY 100
00037 
00038 /** Settling time after gaugeEnable is set high */
00039 #define GAUGE_ENABLE_SETTLING_TIME_MS 10
00040 
00041 /** The default seal codes (step 1 in the higher word, step 2 the lower word), NOT byte reversed. */
00042 #define SEAL_CODES_DEFAULT 0x04143672
00043 
00044 /** The default full access codes (step 1 in the higher word, step 2 the lower word). */
00045 #define FULL_ACCESS_CODES_DEFAULT 0xFFFFFFFF
00046 
00047 /* ----------------------------------------------------------------
00048  * CLASSES
00049  * -------------------------------------------------------------- */
00050 
00051 /** BQ35100 battery gauge driver. */
00052 class BatteryGaugeBq35100 {
00053 public:
00054 
00055     /** The security mode of the BQ35100 chip. */
00056     typedef enum {
00057         SECURITY_MODE_UNKNOWN = 0x00,
00058         SECURITY_MODE_FULL_ACCESS = 0x01, //!< Allows writes to all of memory.
00059         SECURITY_MODE_UNSEALED = 0x02, //!< Allows writes to all of memory apart from the security codes area.
00060         SECURITY_MODE_SEALED = 0x03 //!< Normal operating mode, prevents accidental writes.
00061     } SecurityMode;
00062 
00063     /** Constructor. */
00064     BatteryGaugeBq35100(void);
00065     /** Destructor. */
00066     ~BatteryGaugeBq35100(void);
00067 
00068     /** Initialise the BQ35100 chip.  Once initialised
00069      * the chip is put into its lowest power state.  Any API call
00070      * will awaken the chip from this state and then return it once
00071      * more to the lowest possible power state.
00072      * @param pI2c a pointer to the I2C instance to use.
00073      * @param gaugeEnable the gauge enable pin (will be set high to enable the chip).
00074      * @param address 7-bit I2C address of the battery gauge chip.
00075      * @param sealCodes the two 16 bit seal codes (step 1 in the higher word, step 2 in the
00076      *                  lower word, NOT byte reversed) that will unseal the device if it is sealed.
00077      * @return true if successful, otherwise false.
00078      */
00079     bool init(I2C * pI2c, PinName gaugeEnable = NC, uint8_t address = BATTERY_GAUGE_BQ35100_ADDRESS,
00080               uint32_t sealCodes = SEAL_CODES_DEFAULT);
00081     
00082     /** Switch on the battery gauge.  Battery gauging must be switched on
00083      * for the battery capacity and percentage readings to be valid. The
00084      * chip will consume more when battery gauging is switched on.
00085      * @param nonVolatile if set to true then the chip will add the
00086      *                    accumulated capacity values to those taken
00087      *                    previously in non-volatile memory when
00088      *                    disableGauge() is called.
00089      * @return true if successful, otherwise false.
00090      */
00091     bool enableGauge(bool nonVolatile = false);
00092 
00093     /** Switch off the battery gauge.  If gauging to non-volatile
00094      * memory was switched on, the accumulated capacity values
00095      * will be stored in non-volatile memory.  Please see the warning
00096      * in section 5.1.1 of the TI BQ35100 technical reference manual
00097      * concerning how frequently this should be done.
00098      * @return true if successful, otherwise false.
00099      */
00100     bool disableGauge(void);
00101 
00102     /** Check whether battery gauging is enabled or not.
00103      * @return true if battery gauging is enabled, otherwise false.
00104      */
00105     bool isGaugeEnabled(void);
00106 
00107     /** Set the designed capacity of the cell.
00108      * @param capacityMAh the capacity.
00109      * @return true if successful, otherwise false.
00110      */
00111     bool setDesignCapacity(uint32_t capacityMAh);
00112 
00113     /** Get the designed capacity of the cell.
00114      * @param pCapacityMAh a place to put the capacity.
00115      * @return true if successful, otherwise false.
00116      */
00117     bool getDesignCapacity(uint32_t *pCapacityMAh);
00118 
00119     /** Read the temperature of the BQ35100 chip.
00120      * @param pTemperatureC place to put the temperature reading.
00121      * @return true if successful, otherwise false.
00122      */
00123     bool getTemperature(int32_t *pTemperatureC);
00124 
00125     /** Read the voltage of the battery.
00126      * @param pVoltageMV place to put the voltage reading.
00127      * @return true if successful, otherwise false.
00128      */
00129     bool getVoltage(int32_t *pVoltageMV);
00130 
00131     /** Read the current flowing from the battery.
00132      * @param pCurrentMA place to put the current reading.
00133      * @return true if successful, otherwise false.
00134      */
00135     bool getCurrent(int32_t *pCurrentMA);
00136 
00137     /** Read the battery capacity used in uAh (NOT mAh).
00138      * @param pCapacityUAh place to put the capacity reading.
00139      * @return true if successful, otherwise false.
00140      */
00141     bool getUsedCapacity(uint32_t *pCapacityUAh);
00142 
00143     /** Get the remaining battery capacity in uAh (NOT mAh).
00144     * NOTE: this relies on the Design Capacity of the battery
00145     * having been set correctly.
00146     * @param pCapacityUAh place to put the capacity reading.
00147     * @return true if successful, otherwise false.
00148     */
00149     bool getRemainingCapacity(uint32_t *pCapacityUAh);
00150 
00151     /** Get the remaining battery capacity in percent.
00152      * NOTE: this relies on the Design Capacity of the battery
00153      * having been set correctly.
00154      * @param pBatteryPercentage place to put the reading.
00155      * @return true if successful, otherwise false.
00156      */
00157     bool getRemainingPercentage(int32_t *pBatteryPercentage);
00158 
00159     /** Indicate that a new battery has been inserted.
00160      * @param capacityMAh the capacity of the battery.
00161      * @return true if successful, otherwise false.
00162      */
00163     bool newBattery(uint32_t capacityMAh);
00164 
00165     /** An advanced function to read configuration data from the BQ35100 chip memory.
00166      * Please refer to the TI BQ35100 technical reference manual for details of the
00167      * address space.This function will unseal the device (using the seal codes
00168      * passed into init()) in order to perform the read from data flash and will
00169      * restore the previous security state afterwards.
00170      * @param address the address of the data within the class.
00171      * @param pData a place to put the read data.
00172      * @param length the size of the place to put the data block.
00173      * @return true if successful, otherwise false.
00174      */
00175     bool advancedGetConfig(int32_t address, char * pData, int32_t length);
00176 
00177     /** An advanced function to write configuration data to the BQ35100 chip memory.
00178      * Please refer to the TI BQ35100 technical reference manual for details of the
00179      * address space.  This function will unseal the device (using the seal codes
00180      * passed into init()) in order to perform the write to data flash and will
00181      * restore the previous security state afterwards.  However, if the write
00182      * operation requires full access (e.g. to change the seal codes) then
00183      * the security mode of the device must be changed (through a call to
00184      * advancedGetSecurityMode()) first.  If this function is used to change the seal
00185      * or full access codes for the chip then init() should be called once more to
00186      * update the codes used by this driver.
00187      * @param address the address to write to.
00188      * @param pData a pointer to the data to be written.
00189      * @param length the size of the data to be written.
00190      * @return true if successful, otherwise false.
00191      */
00192     bool advancedSetConfig(int32_t address, const char * pData, int32_t length);
00193 
00194     /** Send a control word (see section 11.1 of the BQ35100 technical reference manual).
00195      * @param controlWord the control word to send.
00196      * @param pDataReturned a place to put the word of data that could be returned,
00197      *        depending on which control word is used (may be NULL).
00198      * @return true if successful, otherwise false.
00199      */
00200     bool advancedSendControlWord(uint16_t controlWord, uint16_t *pDataReturned);
00201     
00202     /** Read two bytes starting at a given address on the chip.
00203      * See sections 11.3 to 11.18 of the BQ35100 technical reference manual for the list
00204      * of addresses.
00205      * NOTE: this is not a read from data flash, for that you need the advancedGetConfig()
00206      * method.
00207      * @param address the start address to read from.  For instance, for temperature this is 0x06.
00208      * @param pDataReturned a place to put the word of data returned.
00209      * @return true if successful, otherwise false.
00210      */
00211     bool advancedGet(uint8_t address, uint16_t *pDataReturned);
00212 
00213     /** Advanced function to get the security mode of the chip.
00214      * @return the security mode.
00215      */
00216     SecurityMode advancedGetSecurityMode(void);
00217 
00218     /** Advanced function to set the security mode of the chip.
00219      * SECURITY_MODE_UNSEALED mode allows writes to the chip and read access to
00220      * certain proteced areas while SECURITY_MODE_FULL_ACCESS, in addition,
00221      * allows the security codes to be updated.  All of the functions in this
00222      * class are able to work with a SEALED chip, provided the correct codes
00223      * are provided to the init() function.
00224      * NOTE: it is only possible to move to SECURITY_MODE_FULL_ACCESS from
00225      * SECURITY_MODE_UNSEALED.
00226      * @return true if successful, otherwise false.
00227      */
00228     bool advancedSetSecurityMode(SecurityMode securityMode);
00229     
00230     /** Advanced function to perform a hard reset of the chip, reinitialising RAM
00231      * data to defaults from ROM.
00232      * Note: the security mode of the chip is unaffected.
00233      * @return true if successful, otherwise false.
00234      */
00235     bool advancedReset(void);
00236     
00237 protected:
00238     /** Pointer to the I2C interface. */
00239     I2C * gpI2c;
00240     /** The address of the device. */
00241     uint8_t gAddress;
00242     /** The gauge enable pin. */
00243     DigitalOut *pGaugeEnable;
00244     /** The seal codes for the device (step 1 in the higher word, step 2 the lower word), NOT byte reversed. . */
00245     uint32_t gSealCodes;
00246     /** The full access codes for the device (step 1 in the higher word, step 2 the lower word), NOT byte reversed. . */
00247     uint32_t gFullAccessCodes;
00248     /** Flag to indicate device is ready. */
00249     bool gReady;
00250     
00251     /** Read two bytes starting at a given address.
00252      * Note: gpI2c should be locked before this is called.
00253      * @param registerAddress the register address to start reading from.
00254      * @param pBytes place to put the two bytes.
00255      * @return true if successful, otherwise false.
00256      */
00257     bool getTwoBytes(uint8_t registerAddress, uint16_t *pBytes);
00258     
00259     /** Compute the checksum of a block of memory in the chip.
00260      * @param pData a pointer to the data block.
00261      * @parm length the length over which to compute the checksum.
00262      * @return the checksum value.
00263      */
00264     uint8_t computeChecksum(const char * pData, int32_t length);
00265 
00266     /** Read data of a given length and class ID.
00267      * Note: gpI2c should be locked before this is called.
00268      * @param address the address of the data within the class.
00269      * @param pData a place to put the read data.
00270      * @param length the size of the place to put the data block.
00271      * @return true if successful, otherwise false.
00272      */
00273     bool readExtendedData(int32_t address, char * pData, int32_t length);
00274     
00275     /** Write an extended data block.
00276      * Note: gpI2c should be locked before this is called.
00277      * @param address the address to write to.
00278      * @param pData a pointer to the data to be written.
00279      * @param length the size of the data to be written.
00280      * @return true if successful, otherwise false.
00281      */
00282     bool writeExtendedData(int32_t address, const char * pData, int32_t length);
00283 
00284     /** Get the security mode of the chip.
00285      * Note: gpI2c should be locked before this is called.
00286      * @return the security mode.
00287      */
00288     SecurityMode getSecurityMode(void);
00289 
00290     /** Set the security mode of the chip.
00291      * Note: gpI2c should be locked before this is called.
00292      * @param securityMode the security mode to set.
00293      * @return true if successful, otherwise false.
00294      */
00295     bool setSecurityMode(SecurityMode securityMode);
00296     
00297     /** Make sure that the chip is awake and has taken a reading.
00298     * Note: the function does its own locking of gpI2C so that it isn't
00299     * held for the entire time we wait for ADC readings to complete.
00300     * @return true if successful, otherwise false.
00301     */
00302     bool makeAdcReading(void);
00303 };
00304 
00305 #endif
00306 
00307 /* End Of File */