This is a library for the MAX17055 Li+ Battery Fuel Gauge.
Dependents: Low_Power_Long_Distance_IR_Vision_Robot MAX17055_EZconfig MAX17055_EZconfig_Sample Low_Power_Long_Distance_IR_Vision_Robot
Fork of max17055 by
Diff: max17055.h
- Revision:
- 11:bdbd3104995b
- Parent:
- 10:f145eb7522ff
- Child:
- 12:519a18fc3b28
--- a/max17055.h Tue Feb 06 21:14:08 2018 +0000 +++ b/max17055.h Tue Feb 27 15:53:04 2018 +0000 @@ -3,13 +3,13 @@ * * @author Felipe Neira - Maxim Integrated - TTS * -* @version 1.2 +* @version 1.4 * -* Started: 9JAN18 +* Started: 6FEB18 * * Updated: -* New functions improved for continious display. Change copyright notice for 2018. -* +* Removed BATTERY CLASS. +* Add Doxygen documentations. * * /******************************************************************************* @@ -62,17 +62,27 @@ /** - * @brief Library for the MAX17055\n - * The MAX17055 is a low 7μA operating current fuel gauge - * which implements Maxim ModelGauge™ m5 EZ algorithm. - * ModelGauge m5 EZ makes fuel gauge implementation easy - * by eliminating battery characterization requirements - * and simplifying host software interaction. - * The ModelGauge m5 EZ robust algorithm provides tolerance against - * battery diversity for most lithium batteries and applications. - * Communication is through an SPI-compatible interface. - * + * @brief MBED Library for the MAX17055\n + * The MAX17055 is a low 7μA operating current fuel gauge which \n + * implements Maxim ModelGauge™ m5 EZ algorithm. \n + * <a href="https://www.maximintegrated.com/en/design/partners-and-technology/design-technology/modelgauge-battery-fuel-gauge-technology.html">ModelGauge</a> + * m5 EZ makes fuel gauge implementation easy by eliminating \n + * battery characterization requirements and simplifying host \n + * software interaction. The ModelGauge m5 EZ robust algorithm \n + * provides tolerance against battery diversity for most lithium \n + * batteries and applications. Communication is through an \n + * SPI-compatible interface. The MAX17055 comes as part of the \n + * MAX32620FTHR MBED enable development board.\n + * \n + * Visit the product page for more information: + * <a href="https://www.maximintegrated.com/MAX17055.html">MAX17055 Product Page</a>\n + * <a href="https://www.maximintegrated.com/MAX17055.pdf">MAX17055 Data Sheet</a>\n + * <a href="https://www.maximintegrated.com/MAX32620FTHR.html">MAX32620FTHR Product Page</a>\n + * <a href="https://www.maximintegrated.com/MAX32620FTHR.pdf">MAX32620FTHR Data Sheet</a>\n + * * @code + * + * ///This is not the final test code. Just sample place holder. * #include "mbed.h" * #include "MAX17055.h" * @@ -98,11 +108,11 @@ * @endcode */ -/******************************************************************//** -* MAX17055 Class -**********************************************************************/ -/// MAX17055 Battery Fuel Gauge Class -/** Generic API for a battery fuel gauge + +/*-------------------------------------------------------------------------*//** + * MAX17055 Class + * @brief Class for MAX17055 Battery Fuel Gauge + * - Generic API for Implementing the Battery Fuel Gauge */ class MAX17055 { @@ -116,113 +126,98 @@ ///8-bit read address static const uint8_t I2C_R_ADRS = 0x6D; - - /////Max # Bytes in FIFO -// static const uint16_t MAX_FIFO_BYTES = 288; -// ///# of bytes per LED channel -// static const uint8_t BYTES_PER_CH = 3; - - - //Defined instance for external structs - struct BATTERY::battery_cfg_t batt_con; - - - - - /** - * @brief Register Addresses for the MAX17055 - * @details Enumerated register addresses + * @brief Register Addresses for the MAX17055 + * @details Enumerated register addresses */ - enum Registers_e { - STATUS_REG = 0x00, /**< 0x00 default = 0x0002 */ - VALRTTH_REG = 0x01, /**< 0x01 */ - TALRTTH_REG = 0x02, /**< 0x02 */ - SALRTTH_REG = 0x03, /**< 0x03 */ - REPCAP_REG = 0x05, /**< 0x05 */ - REPSOC_REG = 0x06, /**< 0x06 */ - TEMP_REG = 0x08, /**< 0x08 */ - VCELL_REG = 0x09, /**< 0x09 */ - CURRENT_REG = 0x0A, /**< 0x0A */ - AVGCURRENT_REG = 0x0B, /**< 0x0B */ - MIXSOC_REG = 0x0D, /**< 0x0D */ - AVSOC_REG = 0x0E, /**< 0x0E */ - MIXCAP_REG = 0x0F, /**< 0x0F */ + enum Registers_e { + STATUS_REG = 0x00, /*!< 0x00 default value = 0x0002 */ + VALRTTH_REG = 0x01, /*!< 0x01 */ + TALRTTH_REG = 0x02, /*!< 0x02 */ + SALRTTH_REG = 0x03, /*!< 0x03 */ + ATRATE_REG = 0x04, /*!< 0x04 write negative 2s comp of a 16-bit theorithical load */ + REPCAP_REG = 0x05, /*!< 0x05 */ + REPSOC_REG = 0x06, /*!< 0x06 */ + TEMP_REG = 0x08, /*!< 0x08 */ + VCELL_REG = 0x09, /*!< 0x09 */ + CURRENT_REG = 0x0A, /*!< 0x0A */ + AVGCURRENT_REG = 0x0B, /*!< 0x0B */ + MIXSOC_REG = 0x0D, /*!< 0x0D */ + AVSOC_REG = 0x0E, /*!< 0x0E */ + MIXCAP_REG = 0x0F, /*!< 0x0F */ - FULLCAPREP_REG = 0x10, /**< 0x10 */ - TTE_REG = 0X11, /**< 0x11 */ - QRTABLE00_REG = 0x12, /**< 0x12 */ - FULLSOCTHR_REG = 0x13, /**< 0x13 */ - CYCLES_REG = 0x17, /**< 0x17 */ - DESIGNCAP_REG = 0x18, /**< 0x18 */ - AVGVCELL_REG = 0x19, /**< 0x19 */ - MAXMINVOLT_REG = 0x1B, /**< 0x1B */ - CONFIG_REG = 0x1D, /**< 0x1D default = 0x2210 */ - ICHGTERM_REG = 0x1E, /**< 0x1E */ + FULLCAPREP_REG = 0x10, /*!< 0x10 */ + TTE_REG = 0X11, /*!< 0x11 */ + QRTABLE00_REG = 0x12, /*!< 0x12 */ + FULLSOCTHR_REG = 0x13, /*!< 0x13 */ + CYCLES_REG = 0x17, /*!< 0x17 */ + DESIGNCAP_REG = 0x18, /*!< 0x18 */ + AVGVCELL_REG = 0x19, /*!< 0x19 */ + MAXMINVOLT_REG = 0x1B, /*!< 0x1B */ + CONFIG_REG = 0x1D, /*!< 0x1D default = 0x2210 */ + ICHGTERM_REG = 0x1E, /*!< 0x1E */ - TTF_REG = 0x20, /**< 0x20 */ - VERSION_REG = 0x21, /**< 0x21 */ - QRTABLE10_REG = 0x22, /**< 0x22 */ - FULLCAPNOM_REG = 0x23, /**< 0x23 */ - LEARNCFG_REG = 0x28, /**< 0x28 */ - RELAXCFG_REG = 0x2A, /**< 0x2A */ - TGAIN_REG = 0x2C, /**< 0x2C */ - TOFF_REG = 0x2D, /**< 0x2D */ + TTF_REG = 0x20, /*!< 0x20 */ + VERSION_REG = 0x21, /*!< 0x21 */ + QRTABLE10_REG = 0x22, /*!< 0x22 */ + FULLCAPNOM_REG = 0x23, /*!< 0x23 */ + LEARNCFG_REG = 0x28, /*!< 0x28 */ + RELAXCFG_REG = 0x2A, /*!< 0x2A */ + TGAIN_REG = 0x2C, /*!< 0x2C */ + TOFF_REG = 0x2D, /*!< 0x2D */ + + QRTABLE20_REG = 0x32, /*!< 0x32 */ + RCOMP0_REG = 0x38, /*!< 0x38 */ + TEMPCO_REG = 0x39, /*!< 0x39 */ + VEMPTY_REG = 0x3A, /*!< 0x39 */ + FSTAT_REG = 0x3D, /*!< 0x39 */ - QRTABLE20_REG = 0x32, /**< 0x32 */ - RCOMP0_REG = 0x38, /**< 0x38 */ - TEMPCO_REG = 0x39, /**< 0x39 */ - VEMPTY_REG = 0x3A, - FSTAT_REG = 0x3D, - - QRTABLE30_REG = 0x42, - DQACC_REG = 0x45, - DPACC_REG = 0x46, - VFSOC0_REG = 0x48, - QH0_REG = 0x4C, - QH_REG = 0x4D, + QRTABLE30_REG = 0x42, /*!< 0x39 */ + DQACC_REG = 0x45, /*!< 0x39 */ + DPACC_REG = 0x46, /*!< 0x39 */ + VFSOC0_REG = 0x48, /*!< 0x39 */ + QH0_REG = 0x4C, /*!< 0x39 */ + QH_REG = 0x4D, /*!< 0x39 */ - VFSOC0_QH0_LOCK_REG = 0x60, - LOCK1_REG = 0x62, - LOCK2_REG = 0x63, + VFSOC0_QH0_LOCK_REG = 0x60, /*!< 0x39 */ + LOCK1_REG = 0x62, /*!< 0x39 */ + LOCK2_REG = 0x63, /*!< 0x39 */ - MODELDATA_START_REG = 0x80, + MODELDATA_START_REG = 0x80, /*!< 0x39 */ - IALRTTH_REG = 0xB4, - CURVE_REG = 0xB9, - HIBCFG_REG = 0xBA, - CONFIG2_REG = 0xBB, /**< 0xBB default = 0x3658 */ + IALRTTH_REG = 0xB4, /*!< 0x39 */ + CURVE_REG = 0xB9, /*!< 0x39 */ + HIBCFG_REG = 0xBA, /*!< 0x39 */ + CONFIG2_REG = 0xBB, /*!< 0xBB default = 0x3658 */ - MODELCFG_REG = 0xDB, - ATTTE_REG = 0xDD, + MODELCFG_REG = 0xDB, /*!< 0x39 */ + ATTTE_REG = 0xDD, /*!< 0x39 */ - OCV_REG = 0xFB, - VFSOC_REG = 0xFF, - } ; - - + OCV_REG = 0xFB, /*!< 0x39 */ + VFSOC_REG = 0xFF /*!< 0x39 */ + }; + /** - * @brief Saved Fuel Gauge Parameters - * @details Struct with saved fuel Gauge Parametrs - */ + * @brief Saved Plataform Data for Fuel Gauge Model + * @details Struct with fuel Gauge Plataform Data for Fuel Gauge Model based on the final design. + */ + struct platform_data{ //to clarify if Part of the class + uint16_t designcap;/*!< struct value 1 */ + uint16_t ichgterm; /*!< struct value 2 */ + uint16_t vempty; /*!< struct value 3 */ + int vcharge; /*!< struct value 1 */ - struct platform_data{ //to clarify if Part of the class - uint16_t designcap;/**< struct value 1 */ - uint16_t ichgterm; /**< struct value 2 */ - uint16_t vempty; /**< struct value 3 */ - int vcharge; /**< struct value 1 */ - - uint16_t learncfg; /**< struct value 1 */ - uint16_t relaxcfg; /**< struct value 1 */ - uint16_t config; /**< struct value 1 */ - uint16_t config2; /**< struct value 1 */ - uint16_t fullsocthr;/**< struct value 1 */ - uint16_t tgain; /**< struct value 1 */ - uint16_t toff; /**< struct value 1 */ - uint16_t curve; /**< struct value 1 */ - uint16_t rcomp0; /**< struct value 1 */ - uint16_t tempco; /**< struct value 1 */ - uint16_t qrtable00; + uint16_t learncfg; /*!< struct value 1 */ + uint16_t relaxcfg; /*!< struct value 1 */ + uint16_t config; /*!< struct value 1 */ + uint16_t config2; /*!< struct value 1 */ + uint16_t fullsocthr;/*!< struct value 1 */ + uint16_t tgain; /*!< struct value 1 */ + uint16_t toff; /*!< struct value 1 */ + uint16_t curve; /*!< struct value 1 */ + uint16_t rcomp0; /*!< struct value 1 */ + uint16_t tempco; /*!< struct value 1 */ + uint16_t qrtable00; uint16_t qrtable10; uint16_t qrtable20; uint16_t qrtable30; @@ -249,59 +244,24 @@ int curr_min; /**< in mA */ } ; - /** - * @brief Saved Fuel Gauge Parameters - * @details It is recommended to save the learned capacity parameters - * every time bit 2 of the Cycles register toggles - * (so that it is saved every 64% change in the battery) - * so that if power is lost the values can easily be restored. - */ - + * @brief Saved Fuel Gauge Parameters + * @details It is recommended to save the learned capacity parameters + * every time bit 2 of the Cycles register toggles (so that it + * is saved every 64% change in the battery) so that if power is + * lost the values can easily be restored. + */ struct saved_FG_params_t{ - int rcomp0; /**< Explain */ - int temp_co; /**< Explain */ - int full_cap_rep; /**< Explain */ - int cycles; /**< Explain */ - int full_cap_nom; /**< Explain */ + int rcomp0; /**< The RComp0 is the characterization information critical to computing the open-circuit voltage of a cell under loaded conditions. */ + int temp_co; /**< The TempCo value is the temperature compensation information based on the RComp0 value*/ + int full_cap_rep; /**< The full capacity in relation with RepCap for reporting to the GUI. A new full-capacity value is calculated at the end of every charge cycle in the application. */ + int cycles; /**< The Cycles value maintains a total count of the number of charge/discharge cycles of the cell that have occurred */ + int full_cap_nom; /**< This is the calculated full capacity of the cell, not including temperature and empty compensation. A new full-capacity nominal value + is calculated each time a cell relaxation event is detected. This values is used to generate other outputs of the ModelGauge m5 algorithm. */ } ; - -/******************************************************************//** -* BATTERY Class -**********************************************************************/ -/// Battery Class -/** Generic API for a battery fuel gauge - -class BATTERY -{ - -public: - - - struct battery_cfg_t{ - int capacity; //!< The rated capacity in mAh of the battery - int voltageMax; //!< The maximum voltage in mV that should be used for charging - int voltageNom; //!< The normal voltage in mV of the battery near mid charge - int voltageMin; //!< The minimum voltage in mV that the battery should be discharged - int temperatureMax; //!< The maximum temperature in degrees C where charging is allowed - int temperatureMin; //!< The minimum temperature in degrees C where charging is allowed - int currentCharge; //!< The current as a percentage of capicity used for charging - int currentTerm; //!< The current as a percentage of capacity to stop charging - int currentPre; //!< The current as a percentage of capacity for pre-charging - } ; - - - - -}; - - - - /** * @brief max17055 Constructor - * @details max17055 Constructor with battery and i2c as parameters */ MAX17055(I2C &i2c); @@ -309,351 +269,136 @@ * @brief Fuel Gauge Destructor */ ~MAX17055(); - - //////////////////////////////////////////////////////////////////////////// /** - * \brief Poll Flag clear - * \par Details - * This function clears status flags for the MAX17055 - * - * \param[in] reg_addr - register address - * \param[in] mask - register address - * \param[in] timeout - register data - * - * \retval 1 on success - * -1 on Failure - */ - - - + * @brief Poll Flag clear Function. + */ int poll_flag_clear(Registers_e reg_addr, int mask, int timeout); - //////////////////////////////////////////////////////////////////////////////// + /** + * @brief Check POR function + */ + int check_POR_func(); /** - * \brief Check POR function - * \par Details - * This function check is there was a power on reset event for the MAX17055 - * - * \retval 1 for no POR detected - * -1 for POR detected - */ - int check_POR_func(); - - //////////////////////////////////////////////////////////////////////////////// - - /** - * \brief clear POR bit function - * \par Details - * This function clear the idicating bit for POR - MAX17055 - * - * \retval 1 for Success - * -1 for errors - */ + * @brief clear POR bit function + */ int clear_POR_bit(); /** - * \brief Write and Verify a MAX17055 register - * \par Details - * This function wites and verifies if the writing process was successful - * - * \param[in] reg_addr - register address - * \param[out] reg_data - the variable that contains the data to write - * to the register address - * - * \retval 1 on success - * -1 if write errors - * -2 if read errors - * -3 if data curruption - * - */ - - + * @brief Write and Verify a MAX17055 register + */ int write_and_verify_reg(Registers_e reg_addr, uint16_t reg_data); - - /////////////////////////////////////////////////////////////////////////// - /** - * \brief Initialise Function for MAX17055 - * \par Details - * This function intitializes the MAX17055 - * - * \retval 1 on success - * -1 if errors exist - */ - - + * @brief Initialization Function for MAX17055. + */ int init(platform_data des_data); - - //////////////////////////////////////////////////////////////////////////// - /** - * \brief Get Internal Temperature Function for MAX17055 - * \par Details - * This function sends a request to access the internal - * of the MAX17055 - * - * - * \retval temperature value - * -1 if errors exist - */ - - + * @brief Get Temperature Function from the MAX17055 TEMP register. + */ int get_temperature(); - - //////////////////////////////////////////////////////////////////////////// - /** - * \brief Forced Exit Hibernate Mode Function for MAX17055 - * \par Details - * This function executes a force exit from hibernate mode. - * - * \retval returns HibCFG original value before forced Exit Hybernate mode - * - */ - - + * @brief Forced Exit Hibernate Mode Function for MAX17055 + */ uint16_t forcedExitHyberMode(); /** - * \brief EZ COnfing Init function - * \par Details - * This function implements the steps for the EZ confing m5 FuelGauge - * - * \retval returns TBD - * - */ - - + * @brief EZ Confing Initialization function + */ uint16_t EZconfig_init(platform_data des_data); - - /////////////////////////////////////////////////////////////////////////// - + /** - * \brief Get State Of Charge(SOC) Function for MAX17055 - * \par Details - * This function sends a request to access the internal - * of the MAX17055 - * - * \param[in] reg_addr - register address - * \param[out] reg_data - SOC data from the REPSOC_REG register - * \retval 1 on success - * - * -1 if errors exist - */ - - + * @brief Get reported State Of Charge(SOC) Function from MAX17055 Fuel Gauge + */ int get_SOC(); - /////////////////////////////////////////////////////////////////////////// + /** + * @brief Get Average State Of Charge(SOC) Function from MAX17055 Fuel Gauge. + */ + int get_avSOC(); /** - * \brief Get Average State Of Charge(SOC) Function for MAX17055 - * \par Details - * This function sends a request to access the internal - * of the MAX17055 - * - * \param[in] reg_addr - register address - * \param[out] reg_data - SOC data from the REPSOC_REG register - * \retval 1 on success - * - * -1 if errors exist - */ - - - int get_avSOC(); - - //////////////////////////////////////////////////////////////////////////// + * @brief Get the Time to Empty(TTE) Function form MAX17055 Fuel Gauge. + */ + int get_TTE(); /** - * \brief Get the remaining Time to Empty(TTE) Function for MAX17055 - * \par Details - * This function sends a request to access the internal register - * of the MAX17055 - * - * \retval tte_data - Time to Empty data from the TTE_REG register - * - * -1 if errors exist - */ - + * @brief Get the at Time to Empty(atTTE) value Function for MAX17055 Fuel Gauge. + */ int get_atTTE(); /** - * \brief Get State Of Charge(SOC) Function for MAX17055 - * \par Details - * This function sends a request to access the internal - * of the MAX17055 - * - * \param[in] reg_addr - register address - * \param[out] reg_data - SOC data from the REPSOC_REG register - * \retval 1 on success - * - * -1 if errors exist - */ - - + * @brief Get mix State Of Charge(SOC) Function for MAX17055 Fuel Gauge. + */ int get_mixSOC(); - //////////////////////////////////////////////////////////////////////////// - /** - * \brief Get the remaining Time to Full(TTE) Function for MAX17055 - * \par Details - * This function sends a request to access the internal register - * of the MAX17055 - * - * \retval ttf_data - Time to Empty data from the TTF_REG register - * - * -1 if errors exist - */ - - + * @brief Get the Time to Full(TTE) values Function for MAX17055 Fuel Gauge. + */ int get_TTF(); - - //////////////////////////////////////////////////////////////////////////// + /** + * @brief Get voltage of the cell Function for MAX17055 Fuel Gauge. + */ + int get_Vcell(); /** - * \brief Get voltage of the cell Function for MAX17055 - * \par Details - * This function sends a request to access the internal register - * of the MAX17055 to read the voltage of the cell - * - * \retval vcell_data - vcell data from the VCELL_REG register - * - * -1 if errors exist - */ - - - int get_Vcell(); - - //////////////////////////////////////////////////////////////////////////// + * @brief Get current Function for MAX17055 Fuel Gauge. + */ + int get_Current(platform_data des_data); /** - * \brief Get current Function for MAX17055 - * \par Details - * This function sends a request to access the internal register - * of the MAX17055 to read the current register. - * - * \retval curr_data - vcell data from the VCELL_REG register - * - * -1 if errors exist - */ - - - int get_Current(platform_data des_data); - - //////////////////////////////////////////////////////////////////////////// + * @brief Get average current Function for MAX17055 Fuel Gauge. + */ + int get_AvgCurrent(platform_data des_data); /** - * \brief Get Average Current Function for MAX17055 - * \par Details - * This function sends a request to access the internal register - * of the MAX17055 to read the average current register. - * - * \retval curr_data - vcell data from the AVGCURRENT_REG register - * - * -1 if errors exist - */ - - - int get_AvgCurrent(platform_data des_data); - - //////////////////////////////////////////////////////////////////////////// - - /** - * \brief lsb_to_uvolts Converssion Function - * \par Details - * This function takes the lsb value of the register and convert it - * to uvolts - * - * \param[in] lsb - value of register lsb - * \retval lsb - converted lsb to uvolts - * - */ - + * @brief lsb_to_uvolts Converssion Function + */ int lsb_to_uvolts(uint16_t lsb); - - /////////////////////////////////////////////////////////////////////////////// - /** - * \brief raw_current_to_uamp Converssion Function - * \par Details - * This function takes the raw current value of the register and - * converts it to uamps - * - * \param[in] curr - raw current value of register - * \retval res - converted raw current to uamps - Signed 2's complement - * - */ - + * @brief raw_current_to_uamp Converssion Function + */ int raw_current_to_uamps(uint32_t curr, int rsense_value); - /////////////////////////////////////////////////////////////////////////////// + /** + * @brief Save Learned Parameters Function for battery Fuel Gauge model. + */ + int save_Params(saved_FG_params_t FG_params); /** - * \brief Save Learned Parameters Function - * \par Details - * It is recommended to save the learned capacity parameters every - * time bit 2 of the Cycles register toggles - * (so that it is saved every 64% change in the battery) - * so that if power is lost the values can easily be restored. - * - * \param[in] struct saved_FG_params_t - * \retval void - * - */ - - int save_Params(saved_FG_params_t FG_params); - - /////////////////////////////////////////////////////////////////////////////// + * @brief Resotore Parameters Function for battery Fuel Gauge model. + */ + int restore_Params(saved_FG_params_t FG_params); /** - * \brief Resotore Parameters Function - * \par Details - * If power is lost, then the capacity information - * can be easily restored with this function - * - * \param[in] struct saved_FG_params_t - * \retval void - * - */ - - int restore_Params(saved_FG_params_t FG_params); + * @brief Function to Save Average Current to At Rate register. + */ + int avCurr_2_atRate(); protected: + /** - * @brief Write Register - * @details Writes data to max17055 Register - * - * @parameters reg_addr Registers to write - * reg_data Data to write + * @brief Writes to MAX17055 register. */ int writeReg(const Registers_e reg_addr, uint16_t reg_data); + /** - * @brief Read Register - * @details Reads data from max17055 register - * - * @parameters reg_addr Register to read + * @brief Reads from MAX17055 register. */ int32_t readReg(Registers_e reg_addr, uint16_t &value); - - - - private: - I2C &m_i2cBus; // I2C object + I2C &m_i2cBus; // I2C object };