Tyler Sisk / battery-gauge-bq27441

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

Dependents:   rcCar

Fork of battery-gauge-bq27441 by u-blox

battery_gauge_bq27441.h@2:93310a83401a, 2017-04-11 (annotated)

Committer:
RobMeades
Date:
Tue Apr 11 09:57:10 2017 +0000
Revision:
2:93310a83401a
Parent:
1:566163f17cde
Child:
3:ebd56471d57c
Change Doxygen comment format to match mbed on-line IDE's somewhat restrictive expectations.

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
RobMeades 2:93310a83401a 72 /** Determine whether a battery has been detected or not.
RobMeades 2:93310a83401a 73 * @return true if a battery has been detected, otherwise false.
RobMeades 2:93310a83401a 74 */
rob.meades@u-blox.com 1:566163f17cde 75 bool isBatteryDetected (void);
rob.meades@u-blox.com 1:566163f17cde 76
RobMeades 2:93310a83401a 77 /** Read the temperature of the BQ27441 chip.
RobMeades 2:93310a83401a 78 * If battery gauging is off this function will take ~1 second
RobMeades 2:93310a83401a 79 * to return while the ADCs are activated and the reading is taken.
RobMeades 2:93310a83401a 80 * If battery gauging is on, the last temperature reading taken
RobMeades 2:93310a83401a 81 * will be returned without delay.
RobMeades 2:93310a83401a 82 * @param pTemperatureC place to put the temperature reading.
RobMeades 2:93310a83401a 83 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 84 */
rob.meades@u-blox.com 1:566163f17cde 85 bool getTemperature (int32_t *pTemperatureC);
rob.meades@u-blox.com 1:566163f17cde 86
RobMeades 2:93310a83401a 87 /** Read the voltage of the battery.
RobMeades 2:93310a83401a 88 * If battery gauging is off this function will take ~1 second
RobMeades 2:93310a83401a 89 * to return while the ADCs are activated and the reading is taken.
RobMeades 2:93310a83401a 90 * If battery gauging is on, the last voltage reading taken
RobMeades 2:93310a83401a 91 * will be returned without delay.
RobMeades 2:93310a83401a 92 * @param pVoltageMV place to put the voltage reading.
RobMeades 2:93310a83401a 93 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 94 */
rob.meades@u-blox.com 1:566163f17cde 95 bool getVoltage (int32_t *pVoltageMV);
rob.meades@u-blox.com 1:566163f17cde 96
RobMeades 2:93310a83401a 97 /** Read the current flowing from the battery.
RobMeades 2:93310a83401a 98 * If battery gauging is off this function will take ~1 second
RobMeades 2:93310a83401a 99 * to return while the ADCs are activated and the reading is taken.
RobMeades 2:93310a83401a 100 * If battery gauging is on, the last current reading taken
RobMeades 2:93310a83401a 101 * will be returned without delay.
RobMeades 2:93310a83401a 102 * @param pCurrentMA place to put the current reading.
RobMeades 2:93310a83401a 103 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 104 */
rob.meades@u-blox.com 1:566163f17cde 105 bool getCurrent (int32_t *pCurrentMA);
rob.meades@u-blox.com 1:566163f17cde 106
RobMeades 2:93310a83401a 107 /** Read the remaining available battery energy.
RobMeades 2:93310a83401a 108 * The battery capacity reading will only be valid if
RobMeades 2:93310a83401a 109 * battery gauging is switched on.
RobMeades 2:93310a83401a 110 * @param pCapacityMAh place to put the capacity reading.
RobMeades 2:93310a83401a 111 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 112 */
rob.meades@u-blox.com 1:566163f17cde 113 bool getRemainingCapacity (int32_t *pCapacityMAh);
rob.meades@u-blox.com 1:566163f17cde 114
RobMeades 2:93310a83401a 115 /** Read the state of charge of the battery as a percentage.
RobMeades 2:93310a83401a 116 * The remaining percentage will only be valid if battery
RobMeades 2:93310a83401a 117 * gauging is switched on.
RobMeades 2:93310a83401a 118 * @param pBatteryPercent place to put the reading.
RobMeades 2:93310a83401a 119 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 120 */
rob.meades@u-blox.com 1:566163f17cde 121 bool getRemainingPercentage (int32_t *pBatteryPercent);
rob.meades@u-blox.com 1:566163f17cde 122
RobMeades 2:93310a83401a 123 /** An advanced function to read configuration data from the BQ27441 chip memory.
RobMeades 2:93310a83401a 124 * Please refer to the TI BQ27441 technical reference manual for details of classId,
RobMeades 2:93310a83401a 125 * offset, the meanings of the data structures and their lengths.
RobMeades 2:93310a83401a 126 * PLEASE READ THIS HEADER FILE DIRECTLY, DOXYGEN MANGLES THE NEXT BIT
RobMeades 2:93310a83401a 127 * Note: the chip handles the data for each sub-class in 32 byte blocks and the offset/
RobMeades 2:93310a83401a 128 * length combination used must respect this. For instance:
RobMeades 2:93310a83401a 129 *
RobMeades 2:93310a83401a 130 * Sub-class N (length 87 bytes)
RobMeades 2:93310a83401a 131 * bytes 0 to 31 bytes 32 to 63 bytes 64 to 86
RobMeades 2:93310a83401a 132 * -------------------------------- -------------------------------- -----------------------
RobMeades 2:93310a83401a 133 * | Data Block 0 || xx Data Block 1 yy ||zz Data Block 2 |
RobMeades 2:93310a83401a 134 * -------------------------------- -------------------------------- -----------------------
RobMeades 2:93310a83401a 135 *
RobMeades 2:93310a83401a 136 * To read item xx, 2 bytes long at offset 36, one would specify an offset of 36 and a length
RobMeades 2:93310a83401a 137 * of 2. To read both xx and yy at the same time (yy being 2 bytes long at offset 56),
RobMeades 2:93310a83401a 138 * one could specify an offset of 36 and a length of 21. However, one could not read xx, yy
RobMeades 2:93310a83401a 139 * and zz at the same time, or yy and zz at the same time, since they fall into different blocks;
RobMeades 2:93310a83401a 140 * two separate reads are required.
RobMeades 2:93310a83401a 141 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 142 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 143 * @param length the amount of data to read.
RobMeades 2:93310a83401a 144 * @param pData a place to put the read data.
RobMeades 2:93310a83401a 145 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 146 */
rob.meades@u-blox.com 1:566163f17cde 147 bool advancedGetConfig(uint8_t subClassId, int32_t offset, int32_t length, char * pData);
rob.meades@u-blox.com 1:566163f17cde 148
RobMeades 2:93310a83401a 149 /** An advanced function to write configuration data to the BQ27441 chip memory.
RobMeades 2:93310a83401a 150 * Please refer to the TI BQ27441 technical reference manual for details of classId,
RobMeades 2:93310a83401a 151 * offset, the meanings of the data structures and their lengths. See also the note above
RobMeades 2:93310a83401a 152 * advancedGetConfig() about how to use offset and length. If this function is used to
RobMeades 2:93310a83401a 153 * change the seal code for the chip then init() should be called once more to
RobMeades 2:93310a83401a 154 * update the seal code used by this driver.
RobMeades 2:93310a83401a 155 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 156 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 157 * @param length the length of the data to be written.
RobMeades 2:93310a83401a 158 * @param pData a pointer to the data to be written.
RobMeades 2:93310a83401a 159 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 160 */
rob.meades@u-blox.com 1:566163f17cde 161 bool advancedSetConfig(uint8_t subClassId, int32_t offset, int32_t length, const char * pData);
rob.meades@u-blox.com 1:566163f17cde 162
RobMeades 2:93310a83401a 163 /** Send a control word (see section 4.1 of the BQ27441 technical reference manual).
RobMeades 2:93310a83401a 164 * @param controlWord the control word to send.
RobMeades 2:93310a83401a 165 * @param pDataReturned a place to put the word of data that could be returned,
RobMeades 2:93310a83401a 166 * depending on which control word is used (may be NULL).
RobMeades 2:93310a83401a 167 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 168 */
rob.meades@u-blox.com 1:566163f17cde 169 bool advancedSendControlWord (uint16_t controlWord, uint16_t *pDataReturned);
rob.meades@u-blox.com 1:566163f17cde 170
RobMeades 2:93310a83401a 171 /** Read two bytes starting at a given address on the chip.
RobMeades 2:93310a83401a 172 * See sections 4.2 to 4.20 of the BQ27441 technical reference manual for the list
RobMeades 2:93310a83401a 173 * of addresses.
RobMeades 2:93310a83401a 174 * @param address the start address to read from. For instance, for temperature this is 0x02.
RobMeades 2:93310a83401a 175 * @param pDataReturned a place to put the word of data returned.
RobMeades 2:93310a83401a 176 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 177 */
rob.meades@u-blox.com 1:566163f17cde 178 bool advancedGet (uint8_t address, uint16_t *pDataReturned);
rob.meades@u-blox.com 1:566163f17cde 179
RobMeades 2:93310a83401a 180 /** Check if the chip is SEALED or UNSEALED.
RobMeades 2:93310a83401a 181 * @return true if it is SEALED, otherwise false.
RobMeades 2:93310a83401a 182 */
rob.meades@u-blox.com 1:566163f17cde 183 bool advancedIsSealed(void);
rob.meades@u-blox.com 1:566163f17cde 184
RobMeades 2:93310a83401a 185 /** Put the chip into SEALED mode. SEALED mode is
RobMeades 2:93310a83401a 186 * used to prevent accidental writes to the chip when it
RobMeades 2:93310a83401a 187 * is in a production device. All of the functions in this
RobMeades 2:93310a83401a 188 * class are able to work with a SEALED chip, provided the
RobMeades 2:93310a83401a 189 * correct seal code is provided to the init() function.
RobMeades 2:93310a83401a 190 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 191 */
rob.meades@u-blox.com 1:566163f17cde 192 bool advancedSeal(void);
rob.meades@u-blox.com 1:566163f17cde 193
RobMeades 2:93310a83401a 194 /** Send the seal code to the chip to unseal it.
RobMeades 2:93310a83401a 195 * @param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
RobMeades 2:93310a83401a 196 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 197 */
rob.meades@u-blox.com 1:566163f17cde 198 bool advancedUnseal(uint16_t sealCode = SEAL_CODE_DEFAULT);
rob.meades@u-blox.com 1:566163f17cde 199
RobMeades 2:93310a83401a 200 /** Do a hard reset of the chip, reinitialising RAM data to defaults from ROM.
RobMeades 2:93310a83401a 201 * Note: the SEALED/UNSEALED status of the chip is unaffected.
RobMeades 2:93310a83401a 202 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 203 */
rob.meades@u-blox.com 1:566163f17cde 204 bool advancedReset(void);
rob.meades@u-blox.com 1:566163f17cde 205
rob.meades@u-blox.com 1:566163f17cde 206 protected:
RobMeades 2:93310a83401a 207 /** Pointer to the I2C interface. */
rob.meades@u-blox.com 1:566163f17cde 208 I2C * gpI2c;
RobMeades 2:93310a83401a 209 /** The address of the device. */
rob.meades@u-blox.com 1:566163f17cde 210 uint8_t gAddress;
RobMeades 2:93310a83401a 211 /** The seal code for the device. */
rob.meades@u-blox.com 1:566163f17cde 212 uint16_t gSealCode;
RobMeades 2:93310a83401a 213 /** Flag to indicate device is ready. */
rob.meades@u-blox.com 1:566163f17cde 214 bool gReady;
RobMeades 2:93310a83401a 215 /** Flag to indicate that monitor mode is active. */
rob.meades@u-blox.com 1:566163f17cde 216 bool gGaugeOn;
rob.meades@u-blox.com 1:566163f17cde 217
RobMeades 2:93310a83401a 218 /** Read two bytes starting at a given address.
RobMeades 2:93310a83401a 219 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 220 * @param registerAddress the register address to start reading from.
RobMeades 2:93310a83401a 221 * @param pBytes place to put the two bytes.
RobMeades 2:93310a83401a 222 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 223 */
rob.meades@u-blox.com 1:566163f17cde 224 bool getTwoBytes (uint8_t registerAddress, uint16_t *pBytes);
rob.meades@u-blox.com 1:566163f17cde 225
RobMeades 2:93310a83401a 226 /** Compute the checksum of a block of memory in the chip.
RobMeades 2:93310a83401a 227 * @param pData a pointer to the 32 byte data block.
RobMeades 2:93310a83401a 228 * @return the checksum value.
RobMeades 2:93310a83401a 229 */
rob.meades@u-blox.com 1:566163f17cde 230 uint8_t computeChecksum(const char * pData);
rob.meades@u-blox.com 1:566163f17cde 231
RobMeades 2:93310a83401a 232 /** Read data of a given length and class ID.
RobMeades 2:93310a83401a 233 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 234 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 235 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 236 * @param pData a place to put the read data.
RobMeades 2:93310a83401a 237 * @param length the size of the place to put the data block.
RobMeades 2:93310a83401a 238 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 239 */
rob.meades@u-blox.com 1:566163f17cde 240 bool readExtendedData(uint8_t subClassId, int32_t offset, int32_t length, char * pData);
rob.meades@u-blox.com 1:566163f17cde 241
RobMeades 2:93310a83401a 242 /** Write an extended data block.
RobMeades 2:93310a83401a 243 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 244 * @param subClassId the sub-class ID of the block.
RobMeades 2:93310a83401a 245 * @param offset the offset of the data within the class.
RobMeades 2:93310a83401a 246 * @param pData a pointer to the data to be written.
RobMeades 2:93310a83401a 247 * @param length the size of the data to be written.
RobMeades 2:93310a83401a 248 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 249 */
rob.meades@u-blox.com 1:566163f17cde 250 bool writeExtendedData(uint8_t subClassId, int32_t offset, int32_t length, const char * pData);
rob.meades@u-blox.com 1:566163f17cde 251
RobMeades 2:93310a83401a 252 /** Check if the chip is SEALED or UNSEALED.
RobMeades 2:93310a83401a 253 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 254 * @return true if it is SEALED, otherwise false.
RobMeades 2:93310a83401a 255 */
rob.meades@u-blox.com 1:566163f17cde 256 bool isSealed(void);
rob.meades@u-blox.com 1:566163f17cde 257
RobMeades 2:93310a83401a 258 /** Put the chip into SEALED mode.
RobMeades 2:93310a83401a 259 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 260 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 261 */
rob.meades@u-blox.com 1:566163f17cde 262 bool seal(void);
rob.meades@u-blox.com 1:566163f17cde 263
RobMeades 2:93310a83401a 264 /** Unseal the chip.
RobMeades 2:93310a83401a 265 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 266 * @param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
RobMeades 2:93310a83401a 267 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 268 */
rob.meades@u-blox.com 1:566163f17cde 269 bool unseal(uint16_t sealCode);
rob.meades@u-blox.com 1:566163f17cde 270
RobMeades 2:93310a83401a 271 /** Make sure that the chip is awake and has taken a reading.
RobMeades 2:93310a83401a 272 * Note: the function does its own locking of gpI2C so that it isn't
RobMeades 2:93310a83401a 273 * held for the entire time we wait for ADC readings to complete.
RobMeades 2:93310a83401a 274 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 275 */
rob.meades@u-blox.com 1:566163f17cde 276 bool makeAdcReading(void);
rob.meades@u-blox.com 1:566163f17cde 277
RobMeades 2:93310a83401a 278 /** Set Hibernate mode.
RobMeades 2:93310a83401a 279 * Note: gpI2c should be locked before this is called.
RobMeades 2:93310a83401a 280 * @return true if successful, otherwise false.
RobMeades 2:93310a83401a 281 */
rob.meades@u-blox.com 1:566163f17cde 282 bool setHibernate(void);
rob.meades@u-blox.com 1:566163f17cde 283 };
rob.meades@u-blox.com 1:566163f17cde 284
rob.meades@u-blox.com 1:566163f17cde 285 #endif
rob.meades@u-blox.com 1:566163f17cde 286
RobMeades 2:93310a83401a 287 /* End Of File */