battery_charger_bq24295.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_CHARGER_BQ24295_H
00018 #define BATTERY_CHARGER_BQ24295_H
00019 
00020 /**
00021  * @file battery_charger_bq24295.h
00022  * This file defines the API to the TI BQ24295 battery charger chip.
00023  */
00024 
00025 /* ----------------------------------------------------------------
00026  * COMPILE-TIME MACROS
00027  * -------------------------------------------------------------- */
00028 
00029 /** Device I2C address. */
00030 #define BATTERY_CHARGER_BQ24295_ADDRESS 0x6B
00031 
00032 /* ----------------------------------------------------------------
00033  * CLASSES
00034  * -------------------------------------------------------------- */
00035 
00036 /** BQ27441 battery charger driver. */
00037 class BatteryChargerBq24295 {
00038 public:
00039     /** Charger state. */
00040     typedef enum {
00041         CHARGER_STATE_UNKNOWN,
00042         CHARGER_STATE_DISABLED,
00043         CHARGER_STATE_NO_EXTERNAL_POWER,
00044         CHARGER_STATE_NOT_CHARGING,
00045         CHARGER_STATE_PRECHARGE,
00046         CHARGER_STATE_FAST_CHARGE,
00047         CHARGER_STATE_COMPLETE,
00048         MAX_NUM_CHARGER_STATES
00049     } ChargerState;
00050 
00051     /** Charger faults as a bitmap that matches the chip REG09 definitions. */
00052     typedef enum {
00053         CHARGER_FAULT_NONE = 0x00,
00054         CHARGER_FAULT_THERMISTOR_TOO_HOT = 0x01,
00055         CHARGER_FAULT_THERMISTOR_TOO_COLD = 0x02,
00056         // Value 0x04 is reserved
00057         CHARGER_FAULT_BATTERY_OVER_VOLTAGE = 0x08,
00058         CHARGER_FAULT_INPUT_FAULT = 0x10,          //!< Note that the value of CHARGER_FAULT_CHARGE_TIMER_EXPIRED overlaps this, be careful when testing the bitmap.
00059         CHARGER_FAULT_THERMAL_SHUTDOWN = 0x20,     //!< Note that the value of CHARGER_FAULT_CHARGE_TIMER_EXPIRED overlaps this, be careful when testing the bitmap.
00060         CHARGER_FAULT_CHARGE_TIMER_EXPIRED = 0x30, //!< This looks odd as it overlaps the two above but it matches the register meaning as defined by the chip.
00061         CHARGER_FAULT_OTG = 0x40,
00062         CHARGER_FAULT_WATCHDOG_EXPIRED = 0x80,
00063         MAX_NUM_CHARGER_FAULTS
00064     } ChargerFault;
00065 
00066     /** Constructor. */
00067     BatteryChargerBq24295(void);
00068     /** Destructor. */
00069     ~BatteryChargerBq24295(void);
00070 
00071     /** Initialise the BQ24295 chip.
00072     * After initialisation the chip will be put into its lowest
00073     * power state and should be configured if the default settings
00074     * are not satisfactory.
00075     * Note: the BQ24295 charging chip will automonously charge a
00076     * LiPo cell that is connected to it, without host interaction.
00077     * This class is only required where the configuration of the
00078     * chip needs to be changed or the charger state is to be monitored.
00079     * @param pI2c a pointer to the I2C instance to use.
00080     * @param address 7-bit I2C address of the battery charger chip.
00081     * @return true if successful, otherwise false.
00082     */
00083     bool init (I2C * pI2c, uint8_t address = BATTERY_CHARGER_BQ24295_ADDRESS);
00084 
00085     /** Get the charger state.
00086     * Note: on a u-blox C030 board with no battery connected this will report
00087     *       CHARGER_STATE_COMPLETE or CHARGER_STATE_FAST_CHARGE rather than
00088     *       CHARGER_STATE_NOT_CHARGING.
00089     * @return the charge state.
00090     */
00091     ChargerState getChargerState(void);
00092 
00093     /** Get whether external power is present or not.
00094     * @return true if external power is present, otherwise false.
00095     */
00096     bool isExternalPowerPresent(void);
00097 
00098     /** Enable charging.
00099     * Default is disabled.
00100     * @return true if successful, otherwise false.
00101     */
00102     bool enableCharging (void);
00103 
00104     /** Disable charging.
00105     * Default is disabled.
00106     * @return true if successful, otherwise false.
00107     */
00108     bool disableCharging (void);
00109 
00110     /** Get the state of charging (enabled or disabled).
00111     * @return true if charging is enabled, otherwise false.
00112     */
00113     bool isChargingEnabled (void);
00114 
00115     /** Enable OTG charging.
00116     * Default is enabled.
00117     * @return true if successful, otherwise false.
00118     */
00119     bool enableOtg (void);
00120 
00121     /** Disable OTG charging.
00122     * Default is enabled.
00123     * @return true if successful, otherwise false.
00124     */
00125     bool disableOtg (void);
00126 
00127     /** Determine whether OTG charging is enabled or not.
00128     * @return true if OTG charging is enabled, otherwise false.
00129     */
00130     bool isOtgEnabled (void);
00131 
00132     /** Set the system voltage (the voltage which the
00133     * chip will attempt to maintain the system at).
00134     * @param voltageMV the voltage limit, in milliVolts.
00135     *        Range is 3000 mV to 3700 mV, default 3500 mV.
00136     * @return true if successful, otherwise false.
00137     */
00138     bool setSystemVoltage (int32_t voltageMV);
00139 
00140     /** Get the system voltage.
00141     * @param pVoltageMV a place to put the system voltage limit.
00142     * @return true if successful, otherwise false.
00143     */
00144     bool getSystemVoltage (int32_t *pVoltageMV);
00145 
00146     /** Set the fast charging current limit.
00147     * @param currentMA the fast charging current limit, in milliAmps.
00148     *        Range is 512 mA to 3008 mA, default 1024 mA.
00149     * @return true if successful, otherwise false.
00150     */
00151     bool setFastChargingCurrentLimit (int32_t currentMA);
00152 
00153     /** Get the fast charging current limit.
00154     * @param pCurrentMA a place to put the fast charging current limit.
00155     * @return true if successful, otherwise false.
00156     */
00157     bool getFastChargingCurrentLimit (int32_t *pCurrentMA);
00158 
00159     /** Set the fast charging safety timer.
00160     * @param timerHours the charging safety timer value.
00161     *        Use a value of 0 to indicate that the timer should be disabled.
00162     *        Timer values will be translated to the nearest (lower) value
00163     *        out of 5, 8, 12, and 20 hours, default 12 hours.
00164     * @return true if successful, otherwise false.
00165     */
00166     bool setFastChargingSafetyTimer (int32_t timerHours);
00167 
00168     /** Get the fast charging safety timer value.
00169     * @param pTimerHours a place to put the charging safety timer value.
00170     *        Returned value is zero if the fast charging safety timer is disabled.
00171     * @return true if charging termination is enabled, otherwise false.
00172     */
00173     bool getFastChargingSafetyTimer (int32_t *pTimerHours);
00174 
00175     /** Set ICHG/IPRECH margin (see section 8.3.3.5 of the chip data sheet).
00176     * Default is disabled.
00177     * @return true if successful, otherwise false.
00178     */
00179     bool enableIcghIprechMargin (void);
00180 
00181     /** Clear the ICHG/IPRECH margin (see section 8.3.3.5 of the chip data sheet).
00182     * Default is disabled.
00183     * @return true if successful, otherwise false.
00184     */
00185     bool disableIcghIprechMargin (void);
00186     
00187     /** Check if the ICHG/IPRECH margin is set (see section 8.3.3.5 of
00188     *  the chip data sheet).
00189     * @return true if the ICHG/IPRECH margin is enabled, otherwise false.
00190     */
00191     bool isIcghIprechMarginEnabled (void);
00192     
00193     /** Set the charging termination current.
00194     * @param currentMA the charging termination current, in milliAmps.
00195     *        Range is 128 mA to 2048 mA, default is 256 mA.
00196     * @return true if successful, otherwise false.
00197     */
00198     bool setChargingTerminationCurrent (int32_t currentMA);
00199 
00200     /** Get the charging termination current.
00201     * @param pCurrentMA a place to put the charging termination current.
00202     * @return true if successful, otherwise false.
00203     */
00204     bool getChargingTerminationCurrent (int32_t *pCurrentMA);
00205 
00206     /** Enable charging termination.
00207     * Default is enabled.
00208     * @return true if successful, otherwise false.
00209     */
00210     bool enableChargingTermination (void);
00211 
00212     /** Disable charging termination.
00213     * Default is enabled.
00214     * @return true if successful, otherwise false.
00215     */
00216     bool disableChargingTermination (void);
00217 
00218     /** Get the state of charging termination (enabled or disabled).
00219     * @return true if charging termination is enabled, otherwise false.
00220     */
00221     bool isChargingTerminationEnabled (void);
00222 
00223     /** Set the pre-charging current limit.
00224     * @param currentMA the pre-charging current limit, in milliAmps.
00225     *        Range is 128 mA to 2048 mA, default is 256 mA.
00226     * @return true if successful, otherwise false.
00227     */
00228     bool setPrechargingCurrentLimit (int32_t currentMA);
00229 
00230     /** Get the pre-charging current limit.
00231     * @param pCurrentMA a place to put the pre-charging current limit.
00232     * @return true if successful, otherwise false.
00233     */
00234     bool getPrechargingCurrentLimit (int32_t *pCurrentMA);
00235 
00236     /** Set the charging voltage limit.
00237     * @param voltageMV the charging voltage limit, in milliVolts.
00238     *        Range is 3504 mV to 4400 mV, default is 4208 mV.
00239     * @return true if successful, otherwise false.
00240     */
00241     bool setChargingVoltageLimit (int32_t voltageMV);
00242 
00243     /** Get the charging voltage limit.
00244     * @param pVoltageMV a place to put the charging voltage limit,
00245     *        in milliVolts.
00246     * @return true if successful, otherwise false.
00247     */
00248     bool getChargingVoltageLimit (int32_t *pVoltageMV);
00249 
00250     /** Set the pre-charge to fast-charge voltage threshold.
00251     * @param voltageMV the threshold, in milliVolts.
00252     *        Values will be translated to the nearest (highest)
00253     *        voltage out of 2800 mV and 3000 mV, default is 3000 mV.
00254     * @return true if successful, otherwise false.
00255     */
00256     bool setFastChargingVoltageThreshold (int32_t voltageMV);
00257 
00258     /** Get the pre-charge to fast-charge voltage threshold.
00259     * @param pVoltageMV a place to put the threshold, in milliVolts.
00260     * @return true if successful, otherwise false.
00261     */
00262     bool getFastChargingVoltageThreshold (int32_t *pVoltageMV);
00263 
00264     /** Set the recharging voltage threshold.
00265     * @param voltageMV the recharging voltage threshold, in milliVolts.
00266     *        Values will be translated to the nearest (highest)
00267     *        voltage out of 100 mV and 300 mV, default is 100 mV.
00268     * @return true if successful, otherwise false.
00269     */
00270     bool setRechargingVoltageThreshold (int32_t voltageMV);
00271 
00272     /** Get the recharging voltage threshold.
00273     * @param pVoltageMV a place to put the charging voltage threshold, in milliVolts.
00274     * @return true if successful, otherwise false.
00275     */
00276     bool getRechargingVoltageThreshold (int32_t *pVoltageMV);
00277 
00278     /** Set the boost voltage.
00279     * @param voltageMV the boost voltage, in milliVolts.
00280     *        Range is 4550 mV to 5510 mV, default is 5126 mV.
00281     * @return true if successful, otherwise false.
00282     */
00283     bool setBoostVoltage (int32_t voltageMV);
00284 
00285     /** Get the boost voltage.
00286     * @param pVoltageMV a place to put the boost voltage, in milliVolts.
00287     * @return true if successful, otherwise false.
00288     */
00289     bool getBoostVoltage (int32_t *pVoltageMV);
00290 
00291     /** Set the boost mode upper temperature limit.
00292     * @param temperatureC the temperature in C.
00293     *        Values will be translated to the nearest (lower)
00294     *        of 55 C, 60 C and 65 C (disabled by default).
00295     * @return true if successful, otherwise false.
00296     */
00297     bool setBoostUpperTemperatureLimit (int32_t temperatureC);
00298 
00299     /** Get the boost mode upper temperature limit.
00300     * If the boost mode upper temperature limit is not
00301     * enabled then pTemperatureC will remain untouched and false
00302     * will be returned.
00303     * @param pTemperatureC a place to put the temperature.
00304     * @return true if successful and a limit was set, otherwise false.
00305     */
00306     bool getBoostUpperTemperatureLimit (int32_t *pTemperatureC);
00307     
00308     /** Check whether the boost mode upper temperature limit is enabled.
00309     * @return true if successful, otherwise false.
00310     */
00311     bool isBoostUpperTemperatureLimitEnabled (void);
00312 
00313     /** Disable the boost mode upper temperature limit.
00314     * Default is disabled.
00315     * @return true if successful, otherwise false.
00316     */
00317     bool disableBoostUpperTemperatureLimit (void);
00318 
00319     /** Set the boost mode low temperature limit.
00320     * @param temperatureC the temperature in C.
00321     *        Values will be translated to the nearest (higher)
00322     *        of -10 C and -20 C, default is -10 C.
00323     * @return true if successful, otherwise false.
00324     */
00325     bool setBoostLowerTemperatureLimit (int32_t temperatureC);
00326 
00327     /** Get the boost mode low temperature limit.
00328     * @param pTemperatureC a place to put the temperature.
00329     * @return true if successful, otherwise false.
00330     */
00331     bool getBoostLowerTemperatureLimit (int32_t *pTemperatureC);
00332     
00333     /** Set the input voltage limit.  If the input falls below
00334     * this level then charging will be ramped down.  The limit
00335     * does not take effect until enableInputLimits() is called
00336     * (default setting is disabled).
00337     * @param voltageMV the input voltage limit, in milliVolts.
00338     *        Range is 3880 mV to 5080 mV, default is 4760 mV.
00339     * @return true if successful, otherwise false.
00340     */
00341     bool setInputVoltageLimit (int32_t voltageMV);
00342 
00343     /** Get the input voltage limit.
00344     * @param pVoltageMV a place to put the input voltage limit.
00345     * @return true if successful, otherwise false.
00346     */
00347     bool getInputVoltageLimit (int32_t *pVoltageMV);
00348 
00349     /** Set the input current limit.  If the current drawn
00350     * goes above this limit then charging will be ramped down.
00351     * The limit does not take effect until enableInputLimits()
00352     * is called (default setting is disabled).
00353     * @param currentMA the input current limit, in milliAmps.
00354     *        Range is 100 mA to 3000 mA, default depends upon
00355     *        hardware configuration, see section 8.3.1.4.3 of
00356     *        the data sheet.
00357     * @return true if successful, otherwise false.
00358     */
00359     bool setInputCurrentLimit (int32_t currentMA);
00360 
00361     /** Get the input current limit.
00362     * @param pCurrentMA a place to put the input current limit.
00363     * @return true if successful, otherwise false.
00364     */
00365     bool getInputCurrentLimit (int32_t *pCurrentMA);
00366 
00367     /** Enable input voltage and current limits.
00368     * Default is disabled.
00369     * @return true if successful, otherwise false.
00370     */
00371     bool enableInputLimits (void);
00372 
00373     /** Remove any input voltage or current limits.
00374     * Default is disabled.
00375     * @return true if successful, otherwise false.
00376     */
00377     bool disableInputLimits (void);
00378 
00379     /** Check whether input limits are enabled.
00380     * @return true if input limits are enabled, otherwise false.
00381     */
00382     bool areInputLimitsEnabled (void);
00383 
00384     /** Set the thermal regulation threshold for the chip.
00385     * @param temperatureC the temperature in C.
00386     *        Values will be translated to the nearest (lower)
00387     *        of 60 C, 80 C, 100 C and 120 C, default 120 C.
00388     * @return true if successful, otherwise false.
00389     */
00390     bool setChipThermalRegulationThreshold (int32_t temperatureC);
00391 
00392     /** Get the thermal regulation threshold for the chip.
00393     * @param pTemperatureC a place to put the temperature.
00394     * @return true if successful, otherwise false.
00395     */
00396     bool getChipThermalRegulationThreshold (int32_t *pTemperatureC);
00397     
00398     /** Get the charger faults.
00399     * Note: as with all the other API functions here, this should
00400     * not be called from an interrupt function as the comms with the
00401     * chip over I2C will take too long.
00402     * @return a bit-map of that can be tested against ChargerFault.
00403     */
00404     char getChargerFaults(void);
00405     
00406     /** Feed the watchdog timer.
00407     * Use this if it is necessary to keep the BQ24295 chip in Host
00408     * mode (see section 8.4.1 of the data sheet for details).
00409     * @return true if successful, otherwise false.
00410     */
00411     bool feedWatchdog(void);
00412     
00413     /** Get the watchdog timer of the BQ24295 chip.
00414     * @param pWatchdogS a place to put the watchdog timer (in seconds).
00415     * @return true if successful, otherwise false.
00416     */
00417     bool getWatchdog (int32_t *pWatchdogS);
00418     
00419     /** Set the watchdog timer of the BQ24295 chip.
00420     * @param watchdogS the watchdog timer (in seconds), 0 to disable,
00421     *                  max 160 seconds.
00422     * @return true if successful, otherwise false.
00423     */
00424     bool setWatchdog (int32_t watchdogS);
00425     
00426     /** Enable shipping mode.
00427     * In shipping mode the battery is disconnected from the system
00428     * to avoid leakage.  Default is disabled.
00429     * @return true if successful, otherwise false.
00430     */
00431     bool enableShippingMode (void);
00432 
00433     /** Disable shipping mode.
00434     * In shipping mode the battery is disconnected from the system
00435     * to avoid leakage.  Default is disabled.
00436     * @return true if successful, otherwise false.
00437     */
00438     bool disableShippingMode (void);
00439 
00440     /** Check whether shipping mode is enabled.
00441     * @return true if input limits are enabled, otherwise false.
00442     */
00443     bool isShippingModeEnabled (void);
00444 
00445     /** Advanced function to read a register on the chip.
00446     * @param address the address to read from.
00447     * @param pValue a place to put the returned value.
00448     * @return true if successful, otherwise false.
00449     */
00450     bool advancedGet(char address, char *pValue);
00451 
00452     /** Advanced function to set a register on the chip.
00453     * @param address the address to write to.
00454     * @param value the value to write.
00455     * @return true if successful, otherwise false.
00456     */
00457     bool advancedSet(char address, char value);
00458 
00459 protected:
00460     /** Pointer to the I2C interface. */
00461     I2C * gpI2c;
00462     /** The address of the device. */
00463     uint8_t gAddress;
00464     /** Flag to indicate device is ready */
00465     bool gReady;
00466 
00467     /** Read a register.
00468     * Note: gpI2c should be locked before this is called.
00469     * @param address the address to read from.
00470     * @param pValue a place to put the returned value.
00471     * @return true if successful, otherwise false.
00472     */
00473     bool getRegister(char address, char *pValue);
00474 
00475     /** Set a register.
00476     * Note: gpI2c should be locked before this is called.
00477     * @param address the address to write to.
00478     * @param value the value to write.
00479     * @return true if successful, otherwise false.
00480     */
00481     bool setRegister(char address, char value);
00482 
00483     /** Set a mask of bits in a register.
00484     * Note: gpI2c should be locked before this is called.
00485     * @param address the address to write to.
00486     * @param mask the mask of bits to set.
00487     * @return true if successful, otherwise false.
00488     */
00489     bool setRegisterBits(char address, char mask);
00490 
00491     /** Clear a mask of bits in a register.
00492     * Note: gpI2c should be locked before this is called.
00493     * @param address the address to write to.
00494     * @param mask the mask of bits to clear.
00495     * @return true if successful, otherwise false.
00496     */
00497     bool clearRegisterBits(char address, char mask);
00498 };
00499 
00500 #endif
00501 
00502 /* End Of File */