Tyler Sisk
Library to interface to the TI BQ27441, a fuel gauge monitor
Fork of
battery-gauge-bq27441
by 
u-blox
Diff: battery_gauge_bq27441.h
- Revision:
- 2:93310a83401a
- Parent:
- 1:566163f17cde
- Child:
- 3:ebd56471d57c
--- a/battery_gauge_bq27441.h Mon Apr 10 11:18:51 2017 +0100
+++ b/battery_gauge_bq27441.h Tue Apr 11 09:57:10 2017 +0000
@@ -22,239 +22,266 @@
* This file defines the API to the TI BQ27441 battery gauge chip.
*/
-// ----------------------------------------------------------------
-// COMPILE-TIME MACROS
-// ----------------------------------------------------------------
+/* ----------------------------------------------------------------
+ * COMPILE-TIME MACROS
+ * -------------------------------------------------------------- */
-/// Device I2C address.
+/** Device I2C address. */
#define BATTERY_GAUGE_BQ27441_ADDRESS 0x55
-/// The default seal code.
+/** The default seal code. */
#define SEAL_CODE_DEFAULT 0x8000
-// ----------------------------------------------------------------
-// CLASSES
-// ----------------------------------------------------------------
+/* ----------------------------------------------------------------
+ * CLASSES
+ * -------------------------------------------------------------- */
-/// BQ27441 battery gauge driver.
+/** BQ27441 battery gauge driver. */
class BatteryGaugeBq27441 {
public:
- /// Constructor.
+ /** Constructor. */
BatteryGaugeBq27441(void);
- /// Destructor.
+ /** Destructor. */
~BatteryGaugeBq27441(void);
- /// Initialise the BQ27441 chip. Once initialised
- // the chip is put into its lowest power state. Any API call
- // will awaken the chip from this state and then return it once
- // more to the lowest possible power state.
- // \param pI2c a pointer to the I2C instance to use.
- //\ param address 7-bit I2C address of the battery gauge chip.
- // \param sealCode the 16 bit seal code that will unseal the device if it is sealed.
- // \return true if successful, otherwise false.
+ /** Initialise the BQ27441 chip. Once initialised
+ * the chip is put into its lowest power state. Any API call
+ * will awaken the chip from this state and then return it once
+ * more to the lowest possible power state.
+ * @param pI2c a pointer to the I2C instance to use.
+ * @param address 7-bit I2C address of the battery gauge chip.
+ * @param sealCode the 16 bit seal code that will unseal the device if it is sealed.
+ * @return true if successful, otherwise false.
+ */
bool init (I2C * pI2c, uint8_t address = BATTERY_GAUGE_BQ27441_ADDRESS, uint16_t sealCode = SEAL_CODE_DEFAULT);
- /// Switch on the battery gauge. Battery gauging must be switched on
- // for the battery capacity and percentage readings to be valid. The
- // chip will consume more when battery gauging is switched on.
- // \param isSlow set this to true to save power if the battery current is not fluctuating very much.
- // \return true if successful, otherwise false.
+ /** Switch on the battery gauge. Battery gauging must be switched on
+ * for the battery capacity and percentage readings to be valid. The
+ * chip will consume more when battery gauging is switched on.
+ * @param isSlow set this to true to save power if the battery current is not fluctuating very much.
+ * @return true if successful, otherwise false.
+ */
bool enableGauge (bool isSlow = false);
- /// Switch off the battery gauge.
- // \return true if successful, otherwise false.
+ /** Switch off the battery gauge.
+ * @return true if successful, otherwise false.
+ */
bool disableGauge (void);
- /// Determine whether a battery has been detected or not.
- // \return true if a battery has been detected, otherwise false.
+ /** Determine whether a battery has been detected or not.
+ * @return true if a battery has been detected, otherwise false.
+ */
bool isBatteryDetected (void);
- /// Read the temperature of the BQ27441 chip.
- // If battery gauging is off this function will take ~1 second
- // to return while the ADCs are activated and the reading is taken.
- // If battery gauging is on, the last temperature reading taken
- // will be returned without delay.
- // \param pTemperatureC place to put the temperature reading.
- // \return true if successful, otherwise false.
+ /** Read the temperature of the BQ27441 chip.
+ * If battery gauging is off this function will take ~1 second
+ * to return while the ADCs are activated and the reading is taken.
+ * If battery gauging is on, the last temperature reading taken
+ * will be returned without delay.
+ * @param pTemperatureC place to put the temperature reading.
+ * @return true if successful, otherwise false.
+ */
bool getTemperature (int32_t *pTemperatureC);
- /// Read the voltage of the battery.
- // If battery gauging is off this function will take ~1 second
- // to return while the ADCs are activated and the reading is taken.
- // If battery gauging is on, the last voltage reading taken
- // will be returned without delay.
- // \param pVoltageMV place to put the voltage reading.
- // \return true if successful, otherwise false.
+ /** Read the voltage of the battery.
+ * If battery gauging is off this function will take ~1 second
+ * to return while the ADCs are activated and the reading is taken.
+ * If battery gauging is on, the last voltage reading taken
+ * will be returned without delay.
+ * @param pVoltageMV place to put the voltage reading.
+ * @return true if successful, otherwise false.
+ */
bool getVoltage (int32_t *pVoltageMV);
- /// Read the current flowing from the battery.
- // If battery gauging is off this function will take ~1 second
- // to return while the ADCs are activated and the reading is taken.
- // If battery gauging is on, the last current reading taken
- // will be returned without delay.
- // \param pCurrentMA place to put the current reading.
- // \return true if successful, otherwise false.
+ /** Read the current flowing from the battery.
+ * If battery gauging is off this function will take ~1 second
+ * to return while the ADCs are activated and the reading is taken.
+ * If battery gauging is on, the last current reading taken
+ * will be returned without delay.
+ * @param pCurrentMA place to put the current reading.
+ * @return true if successful, otherwise false.
+ */
bool getCurrent (int32_t *pCurrentMA);
- /// Read the remaining available battery energy.
- // The battery capacity reading will only be valid if
- // battery gauging is switched on.
- // \param pCapacityMAh place to put the capacity reading.
- // \return true if successful, otherwise false.
+ /** Read the remaining available battery energy.
+ * The battery capacity reading will only be valid if
+ * battery gauging is switched on.
+ * @param pCapacityMAh place to put the capacity reading.
+ * @return true if successful, otherwise false.
+ */
bool getRemainingCapacity (int32_t *pCapacityMAh);
- /// Read the state of charge of the battery as a percentage.
- // The remaining percentage will only be valid if battery
- // gauging is switched on.
- // \param pBatteryPercent place to put the reading.
- // \return true if successful, otherwise false.
+ /** Read the state of charge of the battery as a percentage.
+ * The remaining percentage will only be valid if battery
+ * gauging is switched on.
+ * @param pBatteryPercent place to put the reading.
+ * @return true if successful, otherwise false.
+ */
bool getRemainingPercentage (int32_t *pBatteryPercent);
- /// An advanced function to read configuration data from the BQ27441 chip memory.
- // Please refer to the TI BQ27441 technical reference manual for details of classId,
- // offset, the meanings of the data structures and their lengths.
- // Note: the chip handles the data for each sub-class in 32 byte blocks and the offset/
- // length combination used must respect this. For instance:
- //
- // Sub-class N (length 87 bytes)
- // bytes 0 to 31 bytes 32 to 63 bytes 64 to 86
- // -------------------------------- -------------------------------- -----------------------
- // | Data Block 0 || xx Data Block 1 yy ||zz Data Block 2 |
- // -------------------------------- -------------------------------- -----------------------
- //
- // To read item xx, 2 bytes long at offset 36, one would specify an offset of 36 and a length
- // of 2. To read both xx and yy at the same time (yy being 2 bytes long at offset 56),
- // one could specify an offset of 36 and a length of 21. However, one could not read xx, yy
- // and zz at the same time, or yy and zz at the same time, since they fall into different blocks;
- // two separate reads are required.
- // \param subClassId the sub-class ID of the block.
- // \param offset the offset of the data within the class.
- // \param length the amount of data to read.
- // \param pData a place to put the read data.
- // \return true if successful, otherwise false.
+ /** An advanced function to read configuration data from the BQ27441 chip memory.
+ * Please refer to the TI BQ27441 technical reference manual for details of classId,
+ * offset, the meanings of the data structures and their lengths.
+ * PLEASE READ THIS HEADER FILE DIRECTLY, DOXYGEN MANGLES THE NEXT BIT
+ * Note: the chip handles the data for each sub-class in 32 byte blocks and the offset/
+ * length combination used must respect this. For instance:
+ *
+ * Sub-class N (length 87 bytes)
+ * bytes 0 to 31 bytes 32 to 63 bytes 64 to 86
+ * -------------------------------- -------------------------------- -----------------------
+ * | Data Block 0 || xx Data Block 1 yy ||zz Data Block 2 |
+ * -------------------------------- -------------------------------- -----------------------
+ *
+ * To read item xx, 2 bytes long at offset 36, one would specify an offset of 36 and a length
+ * of 2. To read both xx and yy at the same time (yy being 2 bytes long at offset 56),
+ * one could specify an offset of 36 and a length of 21. However, one could not read xx, yy
+ * and zz at the same time, or yy and zz at the same time, since they fall into different blocks;
+ * two separate reads are required.
+ * @param subClassId the sub-class ID of the block.
+ * @param offset the offset of the data within the class.
+ * @param length the amount of data to read.
+ * @param pData a place to put the read data.
+ * @return true if successful, otherwise false.
+ */
bool advancedGetConfig(uint8_t subClassId, int32_t offset, int32_t length, char * pData);
- /// An advanced function to write configuration data to the BQ27441 chip memory.
- // Please refer to the TI BQ27441 technical reference manual for details of classId,
- // offset, the meanings of the data structures and their lengths. See also the note above
- // advancedGetConfig() about how to use offset and length. If this function is used to
- // change the seal code for the chip then init() should be called once more to
- // update the seal code used by this driver.
- // \param subClassId the sub-class ID of the block.
- // \param offset the offset of the data within the class.
- // \param length the length of the data to be written.
- // \param pData a pointer to the data to be written.
- // \return true if successful, otherwise false.
+ /** An advanced function to write configuration data to the BQ27441 chip memory.
+ * Please refer to the TI BQ27441 technical reference manual for details of classId,
+ * offset, the meanings of the data structures and their lengths. See also the note above
+ * advancedGetConfig() about how to use offset and length. If this function is used to
+ * change the seal code for the chip then init() should be called once more to
+ * update the seal code used by this driver.
+ * @param subClassId the sub-class ID of the block.
+ * @param offset the offset of the data within the class.
+ * @param length the length of the data to be written.
+ * @param pData a pointer to the data to be written.
+ * @return true if successful, otherwise false.
+ */
bool advancedSetConfig(uint8_t subClassId, int32_t offset, int32_t length, const char * pData);
- /// Send a control word (see section 4.1 of the BQ27441 technical reference manual).
- // \param controlWord the control word to send.
- // \param pDataReturned a place to put the word of data that could be returned,
- // depending on which control word is used (may be NULL).
- // \return true if successful, otherwise false.
+ /** Send a control word (see section 4.1 of the BQ27441 technical reference manual).
+ * @param controlWord the control word to send.
+ * @param pDataReturned a place to put the word of data that could be returned,
+ * depending on which control word is used (may be NULL).
+ * @return true if successful, otherwise false.
+ */
bool advancedSendControlWord (uint16_t controlWord, uint16_t *pDataReturned);
- /// Read two bytes starting at a given address on the chip.
- // See sections 4.2 to 4.20 of the BQ27441 technical reference manual for the list
- // of addresses.
- // \param address the start address to read from. For instance, for temperature this is 0x02.
- // \param pDataReturned a place to put the word of data returned.
- // \return true if successful, otherwise false.
+ /** Read two bytes starting at a given address on the chip.
+ * See sections 4.2 to 4.20 of the BQ27441 technical reference manual for the list
+ * of addresses.
+ * @param address the start address to read from. For instance, for temperature this is 0x02.
+ * @param pDataReturned a place to put the word of data returned.
+ * @return true if successful, otherwise false.
+ */
bool advancedGet (uint8_t address, uint16_t *pDataReturned);
- /// Check if the chip is SEALED or UNSEALED.
- // \return true if it is SEALED, otherwise false.
+ /** Check if the chip is SEALED or UNSEALED.
+ * @return true if it is SEALED, otherwise false.
+ */
bool advancedIsSealed(void);
- /// Put the chip into SEALED mode. SEALED mode is
- // used to prevent accidental writes to the chip when it
- // is in a production device. All of the functions in this
- // class are able to work with a SEALED chip, provided the
- // correct seal code is provided to the init() function.
- // \return true if successful, otherwise false.
+ /** Put the chip into SEALED mode. SEALED mode is
+ * used to prevent accidental writes to the chip when it
+ * is in a production device. All of the functions in this
+ * class are able to work with a SEALED chip, provided the
+ * correct seal code is provided to the init() function.
+ * @return true if successful, otherwise false.
+ */
bool advancedSeal(void);
- /// Send the seal code to the chip to unseal it.
- // \param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
- // \return true if successful, otherwise false.
+ /** Send the seal code to the chip to unseal it.
+ * @param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
+ * @return true if successful, otherwise false.
+ */
bool advancedUnseal(uint16_t sealCode = SEAL_CODE_DEFAULT);
- /// Do a hard reset of the chip, reinitialising RAM data to defaults from ROM.
- // Note: the SEALED/UNSEALED status of the chip is unaffected.
- // \return true if successful, otherwise false.
+ /** Do a hard reset of the chip, reinitialising RAM data to defaults from ROM.
+ * Note: the SEALED/UNSEALED status of the chip is unaffected.
+ * @return true if successful, otherwise false.
+ */
bool advancedReset(void);
protected:
- /// Pointer to the I2C interface.
+ /** Pointer to the I2C interface. */
I2C * gpI2c;
- /// The address of the device.
+ /** The address of the device. */
uint8_t gAddress;
- /// The seal code for the device.
+ /** The seal code for the device. */
uint16_t gSealCode;
- /// Flag to indicate device is ready.
+ /** Flag to indicate device is ready. */
bool gReady;
- /// Flag to indicate that monitor mode is active.
+ /** Flag to indicate that monitor mode is active. */
bool gGaugeOn;
- /// Read two bytes starting at a given address.
- // Note: gpI2c should be locked before this is called.
- // \param registerAddress the register address to start reading from.
- // \param pBytes place to put the two bytes.
- // \return true if successful, otherwise false.
+ /** Read two bytes starting at a given address.
+ * Note: gpI2c should be locked before this is called.
+ * @param registerAddress the register address to start reading from.
+ * @param pBytes place to put the two bytes.
+ * @return true if successful, otherwise false.
+ */
bool getTwoBytes (uint8_t registerAddress, uint16_t *pBytes);
- /// Compute the checksum of a block of memory in the chip.
- // \param pData a pointer to the 32 byte data block.
- // \return the checksum value.
+ /** Compute the checksum of a block of memory in the chip.
+ * @param pData a pointer to the 32 byte data block.
+ * @return the checksum value.
+ */
uint8_t computeChecksum(const char * pData);
- /// Read data of a given length and class ID.
- // Note: gpI2c should be locked before this is called.
- // \param subClassId the sub-class ID of the block.
- // \param offset the offset of the data within the class.
- // \param pData a place to put the read data.
- // \param length the size of the place to put the data block.
- // \return true if successful, otherwise false.
+ /** Read data of a given length and class ID.
+ * Note: gpI2c should be locked before this is called.
+ * @param subClassId the sub-class ID of the block.
+ * @param offset the offset of the data within the class.
+ * @param pData a place to put the read data.
+ * @param length the size of the place to put the data block.
+ * @return true if successful, otherwise false.
+ */
bool readExtendedData(uint8_t subClassId, int32_t offset, int32_t length, char * pData);
- /// Write an extended data block.
- // Note: gpI2c should be locked before this is called.
- // \param subClassId the sub-class ID of the block.
- // \param offset the offset of the data within the class.
- // \param pData a pointer to the data to be written.
- // \param length the size of the data to be written.
- // \return true if successful, otherwise false.
+ /** Write an extended data block.
+ * Note: gpI2c should be locked before this is called.
+ * @param subClassId the sub-class ID of the block.
+ * @param offset the offset of the data within the class.
+ * @param pData a pointer to the data to be written.
+ * @param length the size of the data to be written.
+ * @return true if successful, otherwise false.
+ */
bool writeExtendedData(uint8_t subClassId, int32_t offset, int32_t length, const char * pData);
- /// Check if the chip is SEALED or UNSEALED.
- // Note: gpI2c should be locked before this is called.
- // \return true if it is SEALED, otherwise false.
+ /** Check if the chip is SEALED or UNSEALED.
+ * Note: gpI2c should be locked before this is called.
+ * @return true if it is SEALED, otherwise false.
+ */
bool isSealed(void);
- /// Put the chip into SEALED mode.
- // Note: gpI2c should be locked before this is called.
- // \return true if successful, otherwise false.
+ /** Put the chip into SEALED mode.
+ * Note: gpI2c should be locked before this is called.
+ * @return true if successful, otherwise false.
+ */
bool seal(void);
- /// Unseal the chip.
- // Note: gpI2c should be locked before this is called.
- // \param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
- // \return true if successful, otherwise false.
+ /** Unseal the chip.
+ * Note: gpI2c should be locked before this is called.
+ * @param sealCode the 16 bit seal code that will unseal the chip if it is sealed.
+ * @return true if successful, otherwise false.
+ */
bool unseal(uint16_t sealCode);
- /// Make sure that the chip is awake and has taken a reading.
- // Note: the function does its own locking of gpI2C so that it isn't
- // held for the entire time we wait for ADC readings to complete.
- // \return true if successful, otherwise false.
+ /** Make sure that the chip is awake and has taken a reading.
+ * Note: the function does its own locking of gpI2C so that it isn't
+ * held for the entire time we wait for ADC readings to complete.
+ * @return true if successful, otherwise false.
+ */
bool makeAdcReading(void);
- /// Set Hibernate mode.
- // Note: gpI2c should be locked before this is called.
- // \return true if successful, otherwise false.
+ /** Set Hibernate mode.
+ * Note: gpI2c should be locked before this is called.
+ * @return true if successful, otherwise false.
+ */
bool setHibernate(void);
};
#endif
-// End Of File
+/* End Of File */