Library to interface to the TI BQ27441, a fuel gauge monitor

Dependents:   rcCar

Fork of battery-gauge-bq27441 by u-blox

Committer:
rob.meades@u-blox.com
Date:
Tue Jun 06 15:58:21 2017 +0100
Revision:
3:ebd56471d57c
Parent:
2:93310a83401a
Child:
5:63b325f2c21a
Add API to check if battery gauging is enabled.  Remove old UTM board pin-outs.  Remove unused Doxyfile.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rob.meades@u-blox.com 1:566163f17cde 1 /* mbed Microcontroller Library
rob.meades@u-blox.com 1:566163f17cde 2 * Copyright (c) 2017 u-blox
rob.meades@u-blox.com 1:566163f17cde 3 *
rob.meades@u-blox.com 1:566163f17cde 4 * Licensed under the Apache License, Version 2.0 (the "License");
rob.meades@u-blox.com 1:566163f17cde 5 * you may not use this file except in compliance with the License.
rob.meades@u-blox.com 1:566163f17cde 6 * You may obtain a copy of the License at
rob.meades@u-blox.com 1:566163f17cde 7 *
rob.meades@u-blox.com 1:566163f17cde 8 * http://www.apache.org/licenses/LICENSE-2.0
rob.meades@u-blox.com 1:566163f17cde 9 *
rob.meades@u-blox.com 1:566163f17cde 10 * Unless required by applicable law or agreed to in writing, software
rob.meades@u-blox.com 1:566163f17cde 11 * distributed under the License is distributed on an "AS IS" BASIS,
rob.meades@u-blox.com 1:566163f17cde 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rob.meades@u-blox.com 1:566163f17cde 13 * See the License for the specific language governing permissions and
rob.meades@u-blox.com 1:566163f17cde 14 * limitations under the License.
rob.meades@u-blox.com 1:566163f17cde 15 */
rob.meades@u-blox.com 1:566163f17cde 16
rob.meades@u-blox.com 1:566163f17cde 17 #ifndef BATTERY_GAUGE_BQ27441_H
rob.meades@u-blox.com 1:566163f17cde 18 #define BATTERY_GAUGE_BQ27441_H
rob.meades@u-blox.com 1:566163f17cde 19
rob.meades@u-blox.com 1:566163f17cde 20 /**
rob.meades@u-blox.com 1:566163f17cde 21 * @file battery_gauge_bq27441.h
rob.meades@u-blox.com 1:566163f17cde 22 * This file defines the API to the TI BQ27441 battery gauge chip.
rob.meades@u-blox.com 1:566163f17cde 23 */
rob.meades@u-blox.com 1:566163f17cde 24
RobMeades 2:93310a83401a 25 /* ----------------------------------------------------------------
RobMeades 2:93310a83401a 26 * COMPILE-TIME MACROS
RobMeades 2:93310a83401a 27 * -------------------------------------------------------------- */
rob.meades@u-blox.com 1:566163f17cde 28
RobMeades 2:93310a83401a 29 /** Device I2C address. */
rob.meades@u-blox.com 1:566163f17cde 30 #define BATTERY_GAUGE_BQ27441_ADDRESS 0x55
rob.meades@u-blox.com 1:566163f17cde 31
RobMeades 2:93310a83401a 32 /** The default seal code. */
rob.meades@u-blox.com 1:566163f17cde 33 #define SEAL_CODE_DEFAULT 0x8000
rob.meades@u-blox.com 1:566163f17cde 34
RobMeades 2:93310a83401a 35 /* ----------------------------------------------------------------
RobMeades 2:93310a83401a 36 * CLASSES
RobMeades 2:93310a83401a 37 * -------------------------------------------------------------- */
rob.meades@u-blox.com 1:566163f17cde 38
RobMeades 2:93310a83401a 39 /** BQ27441 battery gauge driver. */
rob.meades@u-blox.com 1:566163f17cde 40 class BatteryGaugeBq27441 {
rob.meades@u-blox.com 1:566163f17cde 41 public:
rob.meades@u-blox.com 1:566163f17cde 42
RobMeades 2:93310a83401a 43 /** Constructor. */
rob.meades@u-blox.com 1:566163f17cde 44 BatteryGaugeBq27441(void);
RobMeades 2:93310a83401a 45 /** Destructor. */
rob.meades@u-blox.com 1:566163f17cde 46 ~BatteryGaugeBq27441(void);
rob.meades@u-blox.com 1:566163f17cde 47
RobMeades 2:93310a83401a 48 /** Initialise the BQ27441 chip. Once initialised
RobMeades 2:93310a83401a 49 * the chip is put into its lowest power state. Any API call
RobMeades 2:93310a83401a 50 * will awaken the chip from this state and then return it once
RobMeades 2:93310a83401a 51 * more to the lowest possible power state.
RobMeades 2:93310a83401a 52 * @param pI2c a pointer to the I2C instance to use.
RobMeades 2:93310a83401a 53 * @param address 7-bit I2C address of the battery gauge chip.
RobMeades 2:93310a83401a 54 * @param sealCode the 16 bit seal code that will unseal the device if it is sealed.
RobMeades 2:93310a83401a 55 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 56 */
rob.meades@u-blox.com 1:566163f17cde 57 bool init (I2C * pI2c, uint8_t address = BATTERY_GAUGE_BQ27441_ADDRESS, uint16_t sealCode = SEAL_CODE_DEFAULT);
rob.meades@u-blox.com 1:566163f17cde 58
RobMeades 2:93310a83401a 59 /** Switch on the battery gauge. Battery gauging must be switched on
RobMeades 2:93310a83401a 60 * for the battery capacity and percentage readings to be valid. The
RobMeades 2:93310a83401a 61 * chip will consume more when battery gauging is switched on.
RobMeades 2:93310a83401a 62 * @param isSlow set this to true to save power if the battery current is not fluctuating very much.
RobMeades 2:93310a83401a 63 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 64 */
rob.meades@u-blox.com 1:566163f17cde 65 bool enableGauge (bool isSlow = false);
rob.meades@u-blox.com 1:566163f17cde 66
RobMeades 2:93310a83401a 67 /** Switch off the battery gauge.
RobMeades 2:93310a83401a 68 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 69 */
rob.meades@u-blox.com 1:566163f17cde 70 bool disableGauge (void);
rob.meades@u-blox.com 1:566163f17cde 71
rob.meades@u-blox.com 3:ebd56471d57c 72 /** Check whether battery gauging is enabled or not.
rob.meades@u-blox.com 3:ebd56471d57c 73 * @return true if battery gauging is enabled, otherwise false.
rob.meades@u-blox.com 3:ebd56471d57c 74 */
rob.meades@u-blox.com 3:ebd56471d57c 75 bool isGaugeEnabled(void);
rob.meades@u-blox.com 3:ebd56471d57c 76
RobMeades 2:93310a83401a 77 /** Determine whether a battery has been detected or not.
RobMeades 2:93310a83401a 78 * @return true if a battery has been detected, otherwise false.
RobMeades 2:93310a83401a 79 */
rob.meades@u-blox.com 1:566163f17cde 80 bool isBatteryDetected (void);
rob.meades@u-blox.com 1:566163f17cde 81
RobMeades 2:93310a83401a 82 /** Read the temperature of the BQ27441 chip.
RobMeades 2:93310a83401a 83 * If battery gauging is off this function will take ~1 second
RobMeades 2:93310a83401a 84 * to return while the ADCs are activated and the reading is taken.
RobMeades 2:93310a83401a 85 * If battery gauging is on, the last temperature reading taken
RobMeades 2:93310a83401a 86 * will be returned without delay.
RobMeades 2:93310a83401a 87 * @param pTemperatureC place to put the temperature reading.
RobMeades 2:93310a83401a 88 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 89 */
rob.meades@u-blox.com 1:566163f17cde 90 bool getTemperature (int32_t *pTemperatureC);
rob.meades@u-blox.com 1:566163f17cde 91
RobMeades 2:93310a83401a 92 /** Read the voltage of the battery.
RobMeades 2:93310a83401a 93 * If battery gauging is off this function will take ~1 second
RobMeades 2:93310a83401a 94 * to return while the ADCs are activated and the reading is taken.
RobMeades 2:93310a83401a 95 * If battery gauging is on, the last voltage reading taken
RobMeades 2:93310a83401a 96 * will be returned without delay.
RobMeades 2:93310a83401a 97 * @param pVoltageMV place to put the voltage reading.
RobMeades 2:93310a83401a 98 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 99 */
rob.meades@u-blox.com 1:566163f17cde 100 bool getVoltage (int32_t *pVoltageMV);
rob.meades@u-blox.com 1:566163f17cde 101
RobMeades 2:93310a83401a 102 /** Read the current flowing from the battery.
RobMeades 2:93310a83401a 103 * If battery gauging is off this function will take ~1 second
RobMeades 2:93310a83401a 104 * to return while the ADCs are activated and the reading is taken.
RobMeades 2:93310a83401a 105 * If battery gauging is on, the last current reading taken
RobMeades 2:93310a83401a 106 * will be returned without delay.
RobMeades 2:93310a83401a 107 * @param pCurrentMA place to put the current reading.
RobMeades 2:93310a83401a 108 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 109 */
rob.meades@u-blox.com 1:566163f17cde 110 bool getCurrent (int32_t *pCurrentMA);
rob.meades@u-blox.com 1:566163f17cde 111
RobMeades 2:93310a83401a 112 /** Read the remaining available battery energy.
RobMeades 2:93310a83401a 113 * The battery capacity reading will only be valid if
RobMeades 2:93310a83401a 114 * battery gauging is switched on.
RobMeades 2:93310a83401a 115 * @param pCapacityMAh place to put the capacity reading.
RobMeades 2:93310a83401a 116 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 117 */
rob.meades@u-blox.com 1:566163f17cde 118 bool getRemainingCapacity (int32_t *pCapacityMAh);
rob.meades@u-blox.com 1:566163f17cde 119
RobMeades 2:93310a83401a 120 /** Read the state of charge of the battery as a percentage.
RobMeades 2:93310a83401a 121 * The remaining percentage will only be valid if battery
RobMeades 2:93310a83401a 122 * gauging is switched on.
RobMeades 2:93310a83401a 123 * @param pBatteryPercent place to put the reading.
RobMeades 2:93310a83401a 124 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 125 */
rob.meades@u-blox.com 1:566163f17cde 126 bool getRemainingPercentage (int32_t *pBatteryPercent);
rob.meades@u-blox.com 1:566163f17cde 127
RobMeades 2:93310a83401a 128 /** An advanced function to read configuration data from the BQ27441 chip memory.
RobMeades 2:93310a83401a 129 * Please refer to the TI BQ27441 technical reference manual for details of classId,
RobMeades 2:93310a83401a 130 * offset, the meanings of the data structures and their lengths.
RobMeades 2:93310a83401a 131 * PLEASE READ THIS HEADER FILE DIRECTLY, DOXYGEN MANGLES THE NEXT BIT
RobMeades 2:93310a83401a 132 * Note: the chip handles the data for each sub-class in 32 byte blocks and the offset/
RobMeades 2:93310a83401a 133 * length combination used must respect this. For instance:
RobMeades 2:93310a83401a 134 *
RobMeades 2:93310a83401a 135 * Sub-class N (length 87 bytes)
RobMeades 2:93310a83401a 136 * bytes 0 to 31 bytes 32 to 63 bytes 64 to 86
RobMeades 2:93310a83401a 137 * -------------------------------- -------------------------------- -----------------------
RobMeades 2:93310a83401a 138 * | Data Block 0 || xx Data Block 1 yy ||zz Data Block 2 |
RobMeades 2:93310a83401a 139 * -------------------------------- -------------------------------- -----------------------
RobMeades 2:93310a83401a 140 *
RobMeades 2:93310a83401a 141 * To read item xx, 2 bytes long at offset 36, one would specify an offset of 36 and a length
RobMeades 2:93310a83401a 142 * of 2. To read both xx and yy at the same time (yy being 2 bytes long at offset 56),
RobMeades 2:93310a83401a 143 * one could specify an offset of 36 and a length of 21. However, one could not read xx, yy
RobMeades 2:93310a83401a 144 * and zz at the same time, or yy and zz at the same time, since they fall into different blocks;
RobMeades 2:93310a83401a 145 * two separate reads are required.
RobMeades 2:93310a83401a 146 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 147 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 148 * @param length the amount of data to read.
RobMeades 2:93310a83401a 149 * @param pData a place to put the read data.
RobMeades 2:93310a83401a 150 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 151 */
rob.meades@u-blox.com 1:566163f17cde 152 bool advancedGetConfig(uint8_t subClassId, int32_t offset, int32_t length, char * pData);
rob.meades@u-blox.com 1:566163f17cde 153
RobMeades 2:93310a83401a 154 /** An advanced function to write configuration data to the BQ27441 chip memory.
RobMeades 2:93310a83401a 155 * Please refer to the TI BQ27441 technical reference manual for details of classId,
RobMeades 2:93310a83401a 156 * offset, the meanings of the data structures and their lengths. See also the note above
RobMeades 2:93310a83401a 157 * advancedGetConfig() about how to use offset and length. If this function is used to
RobMeades 2:93310a83401a 158 * change the seal code for the chip then init() should be called once more to
RobMeades 2:93310a83401a 159 * update the seal code used by this driver.
RobMeades 2:93310a83401a 160 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 161 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 162 * @param length the length of the data to be written.
RobMeades 2:93310a83401a 163 * @param pData a pointer to the data to be written.
RobMeades 2:93310a83401a 164 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 165 */
rob.meades@u-blox.com 1:566163f17cde 166 bool advancedSetConfig(uint8_t subClassId, int32_t offset, int32_t length, const char * pData);
rob.meades@u-blox.com 1:566163f17cde 167
RobMeades 2:93310a83401a 168 /** Send a control word (see section 4.1 of the BQ27441 technical reference manual).
RobMeades 2:93310a83401a 169 * @param controlWord the control word to send.
RobMeades 2:93310a83401a 170 * @param pDataReturned a place to put the word of data that could be returned,
RobMeades 2:93310a83401a 171 * depending on which control word is used (may be NULL).
RobMeades 2:93310a83401a 172 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 173 */
rob.meades@u-blox.com 1:566163f17cde 174 bool advancedSendControlWord (uint16_t controlWord, uint16_t *pDataReturned);
rob.meades@u-blox.com 1:566163f17cde 175
RobMeades 2:93310a83401a 176 /** Read two bytes starting at a given address on the chip.
RobMeades 2:93310a83401a 177 * See sections 4.2 to 4.20 of the BQ27441 technical reference manual for the list
RobMeades 2:93310a83401a 178 * of addresses.
RobMeades 2:93310a83401a 179 * @param address the start address to read from. For instance, for temperature this is 0x02.
RobMeades 2:93310a83401a 180 * @param pDataReturned a place to put the word of data returned.
RobMeades 2:93310a83401a 181 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 182 */
rob.meades@u-blox.com 1:566163f17cde 183 bool advancedGet (uint8_t address, uint16_t *pDataReturned);
rob.meades@u-blox.com 1:566163f17cde 184
RobMeades 2:93310a83401a 185 /** Check if the chip is SEALED or UNSEALED.
RobMeades 2:93310a83401a 186 * @return true if it is SEALED, otherwise false.
RobMeades 2:93310a83401a 187 */
rob.meades@u-blox.com 1:566163f17cde 188 bool advancedIsSealed(void);
rob.meades@u-blox.com 1:566163f17cde 189
RobMeades 2:93310a83401a 190 /** Put the chip into SEALED mode. SEALED mode is
RobMeades 2:93310a83401a 191 * used to prevent accidental writes to the chip when it
RobMeades 2:93310a83401a 192 * is in a production device. All of the functions in this
RobMeades 2:93310a83401a 193 * class are able to work with a SEALED chip, provided the
RobMeades 2:93310a83401a 194 * correct seal code is provided to the init() function.
RobMeades 2:93310a83401a 195 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 196 */
rob.meades@u-blox.com 1:566163f17cde 197 bool advancedSeal(void);
rob.meades@u-blox.com 1:566163f17cde 198
RobMeades 2:93310a83401a 199 /** Send the seal code to the chip to unseal it.
RobMeades 2:93310a83401a 200 * @param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
RobMeades 2:93310a83401a 201 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 202 */
rob.meades@u-blox.com 1:566163f17cde 203 bool advancedUnseal(uint16_t sealCode = SEAL_CODE_DEFAULT);
rob.meades@u-blox.com 1:566163f17cde 204
RobMeades 2:93310a83401a 205 /** Do a hard reset of the chip, reinitialising RAM data to defaults from ROM.
RobMeades 2:93310a83401a 206 * Note: the SEALED/UNSEALED status of the chip is unaffected.
RobMeades 2:93310a83401a 207 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 208 */
rob.meades@u-blox.com 1:566163f17cde 209 bool advancedReset(void);
rob.meades@u-blox.com 1:566163f17cde 210
rob.meades@u-blox.com 1:566163f17cde 211 protected:
RobMeades 2:93310a83401a 212 /** Pointer to the I2C interface. */
rob.meades@u-blox.com 1:566163f17cde 213 I2C * gpI2c;
RobMeades 2:93310a83401a 214 /** The address of the device. */
rob.meades@u-blox.com 1:566163f17cde 215 uint8_t gAddress;
RobMeades 2:93310a83401a 216 /** The seal code for the device. */
rob.meades@u-blox.com 1:566163f17cde 217 uint16_t gSealCode;
RobMeades 2:93310a83401a 218 /** Flag to indicate device is ready. */
rob.meades@u-blox.com 1:566163f17cde 219 bool gReady;
RobMeades 2:93310a83401a 220 /** Flag to indicate that monitor mode is active. */
rob.meades@u-blox.com 1:566163f17cde 221 bool gGaugeOn;
rob.meades@u-blox.com 1:566163f17cde 222
RobMeades 2:93310a83401a 223 /** Read two bytes starting at a given address.
RobMeades 2:93310a83401a 224 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 225 * @param registerAddress the register address to start reading from.
RobMeades 2:93310a83401a 226 * @param pBytes place to put the two bytes.
RobMeades 2:93310a83401a 227 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 228 */
rob.meades@u-blox.com 1:566163f17cde 229 bool getTwoBytes (uint8_t registerAddress, uint16_t *pBytes);
rob.meades@u-blox.com 1:566163f17cde 230
RobMeades 2:93310a83401a 231 /** Compute the checksum of a block of memory in the chip.
RobMeades 2:93310a83401a 232 * @param pData a pointer to the 32 byte data block.
RobMeades 2:93310a83401a 233 * @return the checksum value.
RobMeades 2:93310a83401a 234 */
rob.meades@u-blox.com 1:566163f17cde 235 uint8_t computeChecksum(const char * pData);
rob.meades@u-blox.com 1:566163f17cde 236
RobMeades 2:93310a83401a 237 /** Read data of a given length and class ID.
RobMeades 2:93310a83401a 238 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 239 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 240 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 241 * @param pData a place to put the read data.
RobMeades 2:93310a83401a 242 * @param length the size of the place to put the data block.
RobMeades 2:93310a83401a 243 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 244 */
rob.meades@u-blox.com 1:566163f17cde 245 bool readExtendedData(uint8_t subClassId, int32_t offset, int32_t length, char * pData);
rob.meades@u-blox.com 1:566163f17cde 246
RobMeades 2:93310a83401a 247 /** Write an extended data block.
RobMeades 2:93310a83401a 248 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 249 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 250 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 251 * @param pData a pointer to the data to be written.
RobMeades 2:93310a83401a 252 * @param length the size of the data to be written.
RobMeades 2:93310a83401a 253 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 254 */
rob.meades@u-blox.com 1:566163f17cde 255 bool writeExtendedData(uint8_t subClassId, int32_t offset, int32_t length, const char * pData);
rob.meades@u-blox.com 1:566163f17cde 256
RobMeades 2:93310a83401a 257 /** Check if the chip is SEALED or UNSEALED.
RobMeades 2:93310a83401a 258 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 259 * @return true if it is SEALED, otherwise false.
RobMeades 2:93310a83401a 260 */
rob.meades@u-blox.com 1:566163f17cde 261 bool isSealed(void);
rob.meades@u-blox.com 1:566163f17cde 262
RobMeades 2:93310a83401a 263 /** Put the chip into SEALED mode.
RobMeades 2:93310a83401a 264 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 265 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 266 */
rob.meades@u-blox.com 1:566163f17cde 267 bool seal(void);
rob.meades@u-blox.com 1:566163f17cde 268
RobMeades 2:93310a83401a 269 /** Unseal the chip.
RobMeades 2:93310a83401a 270 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 271 * @param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
RobMeades 2:93310a83401a 272 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 273 */
rob.meades@u-blox.com 1:566163f17cde 274 bool unseal(uint16_t sealCode);
rob.meades@u-blox.com 1:566163f17cde 275
RobMeades 2:93310a83401a 276 /** Make sure that the chip is awake and has taken a reading.
RobMeades 2:93310a83401a 277 * Note: the function does its own locking of gpI2C so that it isn't
RobMeades 2:93310a83401a 278 * held for the entire time we wait for ADC readings to complete.
RobMeades 2:93310a83401a 279 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 280 */
rob.meades@u-blox.com 1:566163f17cde 281 bool makeAdcReading(void);
rob.meades@u-blox.com 1:566163f17cde 282
RobMeades 2:93310a83401a 283 /** Set Hibernate mode.
RobMeades 2:93310a83401a 284 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 285 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 286 */
rob.meades@u-blox.com 1:566163f17cde 287 bool setHibernate(void);
rob.meades@u-blox.com 1:566163f17cde 288 };
rob.meades@u-blox.com 1:566163f17cde 289
rob.meades@u-blox.com 1:566163f17cde 290 #endif
rob.meades@u-blox.com 1:566163f17cde 291
RobMeades 2:93310a83401a 292 /* End Of File */