u-blox / battery-gauge-bq35100

This class provides APIs to all of the registers of the TI BQ35100 battery gauge, as used on the u-blox C030 primary battery shield.

Dependents:   example-battery-gauge-bq35100

battery_gauge_bq35100.h@1:ee7cc8d75283, 2017-11-09 (annotated)

Committer:
RobMeades
Date:
Thu Nov 09 22:55:13 2017 +0000
Revision:
1:ee7cc8d75283
Parent:
0:cec745c014b7
Child:
2:4c699a813451
Lots of functionality, having figured out that a reduced I2C clock rate seems to be required and how the seal/unseal functionality and data flash checksumming works.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
RobMeades 0:cec745c014b7 1 /* mbed Microcontroller Library
RobMeades 0:cec745c014b7 2 * Copyright (c) 2017 u-blox
RobMeades 0:cec745c014b7 3 *
RobMeades 0:cec745c014b7 4 * Licensed under the Apache License, Version 2.0 (the "License");
RobMeades 0:cec745c014b7 5 * you may not use this file except in compliance with the License.
RobMeades 0:cec745c014b7 6 * You may obtain a copy of the License at
RobMeades 0:cec745c014b7 7 *
RobMeades 0:cec745c014b7 8 * http://www.apache.org/licenses/LICENSE-2.0
RobMeades 0:cec745c014b7 9 *
RobMeades 0:cec745c014b7 10 * Unless required by applicable law or agreed to in writing, software
RobMeades 0:cec745c014b7 11 * distributed under the License is distributed on an "AS IS" BASIS,
RobMeades 0:cec745c014b7 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
RobMeades 0:cec745c014b7 13 * See the License for the specific language governing permissions and
RobMeades 0:cec745c014b7 14 * limitations under the License.
RobMeades 0:cec745c014b7 15 */
RobMeades 0:cec745c014b7 16
RobMeades 0:cec745c014b7 17 #ifndef BATTERY_GAUGE_BQ35100_H
RobMeades 0:cec745c014b7 18 #define BATTERY_GAUGE_BQ35100_H
RobMeades 0:cec745c014b7 19
RobMeades 0:cec745c014b7 20 /**
RobMeades 0:cec745c014b7 21 * @file battery_gauge_bq35100.h
RobMeades 0:cec745c014b7 22 * This file defines the API to the TI BQ35100 battery gauge chip.
RobMeades 0:cec745c014b7 23 */
RobMeades 0:cec745c014b7 24
RobMeades 0:cec745c014b7 25 /* ----------------------------------------------------------------
RobMeades 0:cec745c014b7 26 * COMPILE-TIME MACROS
RobMeades 0:cec745c014b7 27 * -------------------------------------------------------------- */
RobMeades 0:cec745c014b7 28
RobMeades 0:cec745c014b7 29 /** Device I2C address. */
RobMeades 0:cec745c014b7 30 #define BATTERY_GAUGE_BQ35100_ADDRESS 0x55
RobMeades 0:cec745c014b7 31
RobMeades 1:ee7cc8d75283 32 /** I2C clock frequency.
RobMeades 1:ee7cc8d75283 33 * NOTE: the battery shield board on the C030 platform will not work
RobMeades 1:ee7cc8d75283 34 * at the default I2C clock frequency.
RobMeades 1:ee7cc8d75283 35 */
RobMeades 1:ee7cc8d75283 36 #define I2C_CLOCK_FREQUENCY 250
RobMeades 1:ee7cc8d75283 37
RobMeades 1:ee7cc8d75283 38 /** Settling time after gaugeEnable is set high */
RobMeades 1:ee7cc8d75283 39 #define GAUGE_ENABLE_SETTLING_TIME_MS 10
RobMeades 1:ee7cc8d75283 40
RobMeades 1:ee7cc8d75283 41 /** The default seal codes (step 1 in the higher word, step 2 the lower word), NOT byte reversed. */
RobMeades 1:ee7cc8d75283 42 #define SEAL_CODES_DEFAULT 0x04143672
RobMeades 1:ee7cc8d75283 43
RobMeades 1:ee7cc8d75283 44 /** The default full access codes (step 1 in the higher word, step 2 the lower word). */
RobMeades 1:ee7cc8d75283 45 #define FULL_ACCESS_CODES_DEFAULT 0xFFFFFFFF
RobMeades 0:cec745c014b7 46
RobMeades 0:cec745c014b7 47 /* ----------------------------------------------------------------
RobMeades 0:cec745c014b7 48 * CLASSES
RobMeades 0:cec745c014b7 49 * -------------------------------------------------------------- */
RobMeades 0:cec745c014b7 50
RobMeades 0:cec745c014b7 51 /** BQ35100 battery gauge driver. */
RobMeades 0:cec745c014b7 52 class BatteryGaugeBq35100 {
RobMeades 0:cec745c014b7 53 public:
RobMeades 0:cec745c014b7 54
RobMeades 1:ee7cc8d75283 55 /** The security mode of the BQ35100 chip. */
RobMeades 1:ee7cc8d75283 56 typedef enum {
RobMeades 1:ee7cc8d75283 57 SECURITY_MODE_UNKNOWN = 0x00,
RobMeades 1:ee7cc8d75283 58 SECURITY_MODE_FULL_ACCESS = 0x01, //!< Allows writes to all of memory.
RobMeades 1:ee7cc8d75283 59 SECURITY_MODE_UNSEALED = 0x02, //!< Allows writes to all of memory apart from the security codes area.
RobMeades 1:ee7cc8d75283 60 SECURITY_MODE_SEALED = 0x03 //!< Normal operating mode, prevents accidental writes.
RobMeades 1:ee7cc8d75283 61 } SecurityMode;
RobMeades 1:ee7cc8d75283 62
RobMeades 0:cec745c014b7 63 /** Constructor. */
RobMeades 0:cec745c014b7 64 BatteryGaugeBq35100(void);
RobMeades 0:cec745c014b7 65 /** Destructor. */
RobMeades 0:cec745c014b7 66 ~BatteryGaugeBq35100(void);
RobMeades 0:cec745c014b7 67
RobMeades 0:cec745c014b7 68 /** Initialise the BQ35100 chip. Once initialised
RobMeades 0:cec745c014b7 69 * the chip is put into its lowest power state. Any API call
RobMeades 0:cec745c014b7 70 * will awaken the chip from this state and then return it once
RobMeades 0:cec745c014b7 71 * more to the lowest possible power state.
RobMeades 0:cec745c014b7 72 * @param pI2c a pointer to the I2C instance to use.
RobMeades 1:ee7cc8d75283 73 * @param gaugeEnable the gauge enable pin (will be set high to enable the chip).
RobMeades 0:cec745c014b7 74 * @param address 7-bit I2C address of the battery gauge chip.
RobMeades 1:ee7cc8d75283 75 * @param sealCodes the two 16 bit seal codes (step 1 in the higher word, step 2 in the
RobMeades 1:ee7cc8d75283 76 * lower word, NOT byte reversed) that will unseal the device if it is sealed.
RobMeades 1:ee7cc8d75283 77 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 78 */
RobMeades 1:ee7cc8d75283 79 bool init(I2C * pI2c, PinName gaugeEnable, uint8_t address = BATTERY_GAUGE_BQ35100_ADDRESS,
RobMeades 1:ee7cc8d75283 80 uint32_t sealCodes = SEAL_CODES_DEFAULT);
RobMeades 1:ee7cc8d75283 81
RobMeades 1:ee7cc8d75283 82 /** Switch on the battery gauge. Battery gauging must be switched on
RobMeades 1:ee7cc8d75283 83 * for the battery capacity and percentage readings to be valid. The
RobMeades 1:ee7cc8d75283 84 * chip will consume more when battery gauging is switched on.
RobMeades 1:ee7cc8d75283 85 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 86 */
RobMeades 1:ee7cc8d75283 87 bool enableGauge(void);
RobMeades 1:ee7cc8d75283 88
RobMeades 1:ee7cc8d75283 89 /** Switch off the battery gauge.
RobMeades 1:ee7cc8d75283 90 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 91 */
RobMeades 1:ee7cc8d75283 92 bool disableGauge(void);
RobMeades 1:ee7cc8d75283 93
RobMeades 1:ee7cc8d75283 94 /** Check whether battery gauging is enabled or not.
RobMeades 1:ee7cc8d75283 95 * @return true if battery gauging is enabled, otherwise false.
RobMeades 1:ee7cc8d75283 96 */
RobMeades 1:ee7cc8d75283 97 bool isGaugeEnabled(void);
RobMeades 1:ee7cc8d75283 98
RobMeades 1:ee7cc8d75283 99 /** Set the designed capacity of the cell.
RobMeades 1:ee7cc8d75283 100 * @param capacityMAh the capacity.
RobMeades 1:ee7cc8d75283 101 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 102 */
RobMeades 1:ee7cc8d75283 103 bool setDesignCapacity(uint32_t capacityMAh);
RobMeades 1:ee7cc8d75283 104
RobMeades 1:ee7cc8d75283 105 /** Get the designed capacity of the cell.
RobMeades 1:ee7cc8d75283 106 * @param pCapacityMAh a palce to put the capacity.
RobMeades 1:ee7cc8d75283 107 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 108 */
RobMeades 1:ee7cc8d75283 109 bool getDesignCapacity(uint32_t *pCapacityMAh);
RobMeades 1:ee7cc8d75283 110
RobMeades 1:ee7cc8d75283 111 /** Read the temperature of the BQ35100 chip.
RobMeades 1:ee7cc8d75283 112 * @param pTemperatureC place to put the temperature reading.
RobMeades 1:ee7cc8d75283 113 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 114 */
RobMeades 1:ee7cc8d75283 115 bool getTemperature(int32_t *pTemperatureC);
RobMeades 1:ee7cc8d75283 116
RobMeades 1:ee7cc8d75283 117 /** Read the voltage of the battery.
RobMeades 1:ee7cc8d75283 118 * @param pVoltageMV place to put the voltage reading.
RobMeades 0:cec745c014b7 119 * @return true if successful, otherwise false.
RobMeades 0:cec745c014b7 120 */
RobMeades 1:ee7cc8d75283 121 bool getVoltage(int32_t *pVoltageMV);
RobMeades 1:ee7cc8d75283 122
RobMeades 1:ee7cc8d75283 123 /** Read the current flowing from the battery.
RobMeades 1:ee7cc8d75283 124 * @param pCurrentMA place to put the current reading.
RobMeades 1:ee7cc8d75283 125 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 126 */
RobMeades 1:ee7cc8d75283 127 bool getCurrent(int32_t *pCurrentMA);
RobMeades 1:ee7cc8d75283 128
RobMeades 1:ee7cc8d75283 129 /** Read the battery capacity used in uAh (NOT mAh).
RobMeades 1:ee7cc8d75283 130 * @param pCapacityUAh place to put the capacity reading.
RobMeades 1:ee7cc8d75283 131 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 132 */
RobMeades 1:ee7cc8d75283 133 bool getUsedCapacity(uint32_t *pCapacityUAh);
RobMeades 1:ee7cc8d75283 134
RobMeades 1:ee7cc8d75283 135 /** Get the remaining battery capacity in uAh (NOT mAh).
RobMeades 1:ee7cc8d75283 136 * NOTE: this relies on the Design Capacity of the battery
RobMeades 1:ee7cc8d75283 137 * having been set correctly.
RobMeades 1:ee7cc8d75283 138 * @param pCapacityUAh place to put the capacity reading.
RobMeades 1:ee7cc8d75283 139 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 140 */
RobMeades 1:ee7cc8d75283 141 bool getRemainingCapacity(uint32_t *pCapacityUAh);
RobMeades 1:ee7cc8d75283 142
RobMeades 1:ee7cc8d75283 143 /** Get the remaining battery capacity in percent.
RobMeades 1:ee7cc8d75283 144 * NOTE: this relies on the Design Capacity of the battery
RobMeades 1:ee7cc8d75283 145 * having been set correctly.
RobMeades 1:ee7cc8d75283 146 * @param pBatteryPercentage place to put the reading.
RobMeades 1:ee7cc8d75283 147 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 148 */
RobMeades 1:ee7cc8d75283 149 bool getRemainingPercentage(int32_t *pBatteryPercentage);
RobMeades 1:ee7cc8d75283 150
RobMeades 1:ee7cc8d75283 151 /** Advanced function to get the security mode of the chip.
RobMeades 1:ee7cc8d75283 152 * @return the security mode.
RobMeades 1:ee7cc8d75283 153 */
RobMeades 1:ee7cc8d75283 154 SecurityMode advancedGetSecurityMode(void);
RobMeades 1:ee7cc8d75283 155
RobMeades 1:ee7cc8d75283 156 /** Set the security mode of the chip. SECURITY_MODE_UNSEALED mode allows
RobMeades 1:ee7cc8d75283 157 * writes to the chip and read access to certain proteced areas while
RobMeades 1:ee7cc8d75283 158 * SECURITY_MODE_FULL_ACCESS, in addition, allows the security codes
RobMeades 1:ee7cc8d75283 159 * to be updated. All of the functions in this class are able to work with a
RobMeades 1:ee7cc8d75283 160 * SEALED chip, provided the correct codes are provided to the init() function.
RobMeades 1:ee7cc8d75283 161 * NOTE: it is only possible to move to SECURITY_MODE_FULL_ACCESS from
RobMeades 1:ee7cc8d75283 162 * SECURITY_MODE_UNSEALED.
RobMeades 1:ee7cc8d75283 163 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 164 */
RobMeades 1:ee7cc8d75283 165 bool advancedSetSecurityMode(SecurityMode securityMode);
RobMeades 1:ee7cc8d75283 166
RobMeades 1:ee7cc8d75283 167 /** Do a hard reset of the chip, reinitialising RAM data to defaults from ROM.
RobMeades 1:ee7cc8d75283 168 * Note: the security mode of the chip is unaffected.
RobMeades 1:ee7cc8d75283 169 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 170 */
RobMeades 1:ee7cc8d75283 171 bool advancedReset(void);
RobMeades 0:cec745c014b7 172
RobMeades 0:cec745c014b7 173 protected:
RobMeades 0:cec745c014b7 174 /** Pointer to the I2C interface. */
RobMeades 0:cec745c014b7 175 I2C * gpI2c;
RobMeades 0:cec745c014b7 176 /** The address of the device. */
RobMeades 0:cec745c014b7 177 uint8_t gAddress;
RobMeades 1:ee7cc8d75283 178 /** The gauge enable pin. */
RobMeades 1:ee7cc8d75283 179 DigitalOut *pGaugeEnable;
RobMeades 1:ee7cc8d75283 180 /** The seal codes for the device (step 1 in the higher word, step 2 the lower word), NOT byte reversed. . */
RobMeades 1:ee7cc8d75283 181 uint32_t gSealCodes;
RobMeades 1:ee7cc8d75283 182 /** The full access codes for the device (step 1 in the higher word, step 2 the lower word), NOT byte reversed. . */
RobMeades 1:ee7cc8d75283 183 uint32_t gFullAccessCodes;
RobMeades 0:cec745c014b7 184 /** Flag to indicate device is ready. */
RobMeades 0:cec745c014b7 185 bool gReady;
RobMeades 1:ee7cc8d75283 186 /** Flag to indicate that monitor mode is active. */
RobMeades 1:ee7cc8d75283 187 bool gGaugeOn;
RobMeades 0:cec745c014b7 188
RobMeades 0:cec745c014b7 189 /** Read two bytes starting at a given address.
RobMeades 1:ee7cc8d75283 190 * Note: gpI2c should be locked before this is called.
RobMeades 1:ee7cc8d75283 191 * @param registerAddress the register address to start reading from.
RobMeades 1:ee7cc8d75283 192 * @param pBytes place to put the two bytes.
RobMeades 1:ee7cc8d75283 193 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 194 */
RobMeades 1:ee7cc8d75283 195 bool getTwoBytes(uint8_t registerAddress, uint16_t *pBytes);
RobMeades 1:ee7cc8d75283 196
RobMeades 1:ee7cc8d75283 197 /** Compute the checksum of a block of memory in the chip.
RobMeades 1:ee7cc8d75283 198 * @param pData a pointer to the data block.
RobMeades 1:ee7cc8d75283 199 * @parm length the length over which to compute the checksum.
RobMeades 1:ee7cc8d75283 200 * @return the checksum value.
RobMeades 1:ee7cc8d75283 201 */
RobMeades 1:ee7cc8d75283 202 uint8_t computeChecksum(const char * pData, int32_t length);
RobMeades 1:ee7cc8d75283 203
RobMeades 1:ee7cc8d75283 204 /** Read data of a given length and class ID.
RobMeades 1:ee7cc8d75283 205 * Note: gpI2c should be locked before this is called.
RobMeades 1:ee7cc8d75283 206 * @param address the address of the data within the class.
RobMeades 1:ee7cc8d75283 207 * @param pData a place to put the read data.
RobMeades 1:ee7cc8d75283 208 * @param length the size of the place to put the data block.
RobMeades 1:ee7cc8d75283 209 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 210 */
RobMeades 1:ee7cc8d75283 211 bool readExtendedData(int32_t address, int32_t length, char * pData);
RobMeades 1:ee7cc8d75283 212
RobMeades 1:ee7cc8d75283 213 /** Write an extended data block.
RobMeades 1:ee7cc8d75283 214 * Note: gpI2c should be locked before this is called.
RobMeades 1:ee7cc8d75283 215 * @param address the address to write to.
RobMeades 1:ee7cc8d75283 216 * @param pData a pointer to the data to be written.
RobMeades 1:ee7cc8d75283 217 * @param length the size of the data to be written.
RobMeades 1:ee7cc8d75283 218 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 219 */
RobMeades 1:ee7cc8d75283 220 bool writeExtendedData(int32_t address, int32_t length, const char * pData);
RobMeades 1:ee7cc8d75283 221
RobMeades 1:ee7cc8d75283 222 /** Get the security mode of the chip.
RobMeades 1:ee7cc8d75283 223 * Note: gpI2c should be locked before this is called.
RobMeades 1:ee7cc8d75283 224 * @return the security mode.
RobMeades 1:ee7cc8d75283 225 */
RobMeades 1:ee7cc8d75283 226 SecurityMode getSecurityMode(void);
RobMeades 1:ee7cc8d75283 227
RobMeades 1:ee7cc8d75283 228 /** Set the security mode of the chip.
RobMeades 1:ee7cc8d75283 229 * Note: gpI2c should be locked before this is called.
RobMeades 1:ee7cc8d75283 230 * @param securityMode the security mode to set.
RobMeades 1:ee7cc8d75283 231 * @return true if successful, otherwise false.
RobMeades 1:ee7cc8d75283 232 */
RobMeades 1:ee7cc8d75283 233 bool setSecurityMode(SecurityMode securityMode);
RobMeades 1:ee7cc8d75283 234
RobMeades 1:ee7cc8d75283 235 /** Make sure that the chip is awake and has taken a reading.
RobMeades 1:ee7cc8d75283 236 * Note: the function does its own locking of gpI2C so that it isn't
RobMeades 1:ee7cc8d75283 237 * held for the entire time we wait for ADC readings to complete.
RobMeades 0:cec745c014b7 238 * @return true if successful, otherwise false.
RobMeades 0:cec745c014b7 239 */
RobMeades 1:ee7cc8d75283 240 bool makeAdcReading(void);
RobMeades 0:cec745c014b7 241 };
RobMeades 0:cec745c014b7 242
RobMeades 0:cec745c014b7 243 #endif
RobMeades 0:cec745c014b7 244
RobMeades 0:cec745c014b7 245 /* End Of File */