max17055.h

00001 /*******************************************************************************
00002 * Copyright (C) 2018 Maxim Integrated Products, Inc., All Rights Reserved.
00003 *
00004 * Permission is hereby granted, free of charge, to any person obtaining a
00005 * copy of this software and associated documentation files (the "Software"),
00006 * to deal in the Software without restriction, including without limitation
00007 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008 * and/or sell copies of the Software, and to permit persons to whom the
00009 * Software is furnished to do so, subject to the following conditions:
00010 *
00011 * The above copyright notice and this permission notice shall be included
00012 * in all copies or substantial portions of the Software.
00013 *
00014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020 * OTHER DEALINGS IN THE SOFTWARE.
00021 *
00022 * Except as contained in this notice, the name of Maxim Integrated
00023 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00024 * Products, Inc. Branding Policy.
00025 *
00026 * The mere transfer of this software does not imply any licenses
00027 * of trade secrets, proprietary technology, copyrights, patents,
00028 * trademarks, maskwork rights, or any other form of intellectual
00029 * property whatsoever. Maxim Integrated Products, Inc. retains all
00030 * ownership rights.
00031 *******************************************************************************
00032 */
00033 
00034 #ifndef __MAX17055_H_
00035 #define __MAX17055_H_
00036 
00037 // Include
00038 #include "mbed.h"
00039 
00040 /* STATUS register bits */
00041 #define MAX17055_STATUS_BST             (1 << 3)
00042 #define MAX17055_STATUS_POR             (1 << 1)
00043 
00044 /// Model loading options
00045 #define MODEL_LOADING_OPTION1           1 //EZ Config
00046 
00047 //Remove this and leave it
00048 
00049 /**
00050  * @brief MBED Library for the MAX17055\n
00051  * The MAX17055 is a low 7μA operating current fuel gauge which  \n
00052  * implements Maxim ModelGauge™ m5 EZ algorithm.                 \n
00053  * <a href="https://www.maximintegrated.com/en/design/partners-and-technology/design-technology/modelgauge-battery-fuel-gauge-technology.html">ModelGauge</a>
00054  * m5 EZ makes fuel gauge implementation easy by eliminating     \n
00055  * battery characterization requirements and simplifying host    \n
00056  * software interaction. The ModelGauge m5 EZ robust algorithm   \n
00057  * provides tolerance against battery diversity for most lithium \n
00058  * batteries and applications. Communication is through a       \n
00059  * I2C interface. The MAX17055 comes as part of the   \n
00060  * MAX32620FTHR MBED enable development board.\n
00061  * \n
00062  * Visit the product page for more information:
00063  * <a href="https://www.maximintegrated.com/MAX17055.html">MAX17055 Product Page</a>\n
00064  * <a href="https://www.maximintegrated.com/MAX17055.pdf">MAX17055 Data Sheet</a>\n
00065  * <a href="https://www.maximintegrated.com/MAX32620FTHR.html">MAX32620FTHR Product Page</a>\n
00066  * <a href="https://www.maximintegrated.com/MAX32620FTHR.pdf">MAX32620FTHR Data Sheet</a>\n
00067  *
00068  *  Battery Recommendations based on sense Resistor Values (MAX32620FTHR comes with a 5 mOhm rsense resistor)\n
00069  *
00070  * | BATTERY FULL CAPACITY(mAh) | Sense Resistor | Current Register Resolution(uA) | Current Register Range(A) | Capacity Resolution(mAh) |\n
00071  * |----------------------------|----------------|---------------------------------|---------------------------|--------------------------|\n
00072  * | 1600 - 24576               | 5              | 312.5                           | +/- 10.24                 | 1                        |\n
00073  * | 8000 - 12288               | 10             | 156.25                          | +/- 5.12                  | 0.5                      |\n
00074  * | 400-6144                   | 20             | 78.125                          | +/- 2.56                  | 0.25                     |\n
00075  * | 160-2458                   | 50             | 31.25                           | +/- 1.024                 | 0.1                      |\n
00076  * | 40-614                     | 200            | 7.8125                          | +/- 0.256                 | 0.025                    |\n
00077  *
00078  *
00079  * @code
00080  * #include "mbed.h"
00081  * #include "max17055.h"
00082  *
00083  *
00084  *    //LED indication
00085  *    DigitalOut rled(LED1);
00086  *    
00087  *    //I2C communications
00088  *    I2C i2cBus(P5_7, P6_0);
00089  *    
00090  *    //Fuel Gauge
00091  *    MAX17055 fuelGauge(i2cBus);
00092  *    MAX17055::platform_data design_param;
00093  *    MAX17055::saved_FG_params_t saved_param;
00094  *    
00095  *    //MAX77650 PMIC
00096  *    #define POWER_HOLD_ON 1
00097  *    #define POWER_HOLD_OFF 0
00098  *    
00099  *    DigitalOut pw_Hold(P2_2, POWER_HOLD_ON); //To enable battery operation from the PMIC
00100  *    
00101  *    //Battery Parameters Storage from the Fuel Gauge MAX17055
00102  *    union max17055_u {
00103  *        struct battery {
00104  *            uint8_t avg_soc_FG;     // in Battery Percent
00105  *           float tte_FG;            // in seconds
00106  *            float ttf_FG;           // in seconds
00107  *            int avg_vcell_FG;       // in 78.125uV per bit
00108  *            float avg_curr_FG;      // in uAmps
00109  *            float curr_FG;          // in uAmps
00110  *            int rep_cap;            // in mAh
00111  *            int rep_SOC;            // in %
00112  *        } battery;
00113  *    } max17055_u;
00114  *    
00115  *    
00116  *    int main(void)
00117  *    {
00118  *        rled = true;
00119  *        //These are the calculated parameters for rsense 5mOhm found in the MAX32620FTHR and a 350mAh Li+ Cell.
00120  *        design_param.designcap  = 0x015E;  //Design Battery Capacity mAh this can change depending on the batteries implemented see battery data sheet for details.
00121  *        design_param.ichgterm  = 0x0070;  // Charge Termination Current for the Battery This is specified by the manufacturer.
00122  *        design_param.vempty  = 0x9600;  // Battery Empty Voltage This is specified by design, but manufacturer has a min Empty voltage specification.
00123  *        design_param.vcharge  = 4200;  // Battery Charge Voltage can be obtained from MAX77650 configuration
00124  *        design_param.rsense = 5; //5mOhms for MAX32620, keep in mind the MAX17055EVKIT has a 10mOhm resistor. This is a design specific value. Used for calculation results.
00125  *
00126  *    //Saved Parameters
00127  *    //saved_param.cycles = 0; //This value is used for the save parameters function
00128  *    
00129  *    status = fuelGauge.init(design_param);
00130  * //    printf("Init FuelGauge Function Status= %X \r\n",status);
00131  *
00132  *    if (status == 0)
00133  *        fuelGauge.save_Params(saved_param);
00134  *
00135  *    while (1) {
00136  *        //This code is an example to illustrate the performance or the Fuel Gauge. This can change with the design requirements. Use this as a way to troubleshoot the FuelGauge.
00137  *        rled = !rled;
00138  *
00139  *       max17055_u.battery.avg_vcell_FG = fuelGauge.get_avgVcell();
00140  *       max17055_u.battery.avg_curr_FG  = fuelGauge.get_AvgCurrent(design_param);
00141  *       max17055_u.battery.curr_FG      = fuelGauge.get_Current(design_param); 
00142  *       max17055_u.battery.rep_cap      = fuelGauge.get_battCAP(design_param);
00143  *       max17055_u.battery.rep_SOC      = fuelGauge.get_SOC();
00144  *        
00145  *        //This code works with Arduino Serial Plotter to visualize data
00146  *        printf("%f " ,(max17055_u.battery.avg_vcell_FG/1000000.0)); //V
00147  *        printf("%f " ,max17055_u.battery.avg_curr_FG);              //uA
00148  *        printf("%f " ,max17055_u.battery.curr_FG);                  //uA
00149  *        printf("%d " ,max17055_u.battery.rep_cap);                  //mAh
00150  *        printf("%d " ,max17055_u.battery.rep_SOC);                  //%
00151  *        printf("\n");
00152  *        wait(1);
00153  *     }
00154  * }
00155  * @endcode
00156  */
00157 
00158 
00159 
00160 /*-------------------------------------------------------------------------*//**
00161  * MAX17055 Class
00162  * @brief      Class for MAX17055 Battery Fuel Gauge
00163  *          - Generic API for Implementing the Battery Fuel Gauge
00164  */
00165 class MAX17055
00166 {
00167 
00168 public:
00169 
00170     ///8-bit write address
00171     static const uint8_t I2C_W_ADRS = 0x6C;
00172     ///8-bit read address
00173     static const uint8_t I2C_R_ADRS = 0x6D;
00174 
00175     /**
00176      * @brief      Register Addresses for the MAX17055
00177      * @details    Enumerated register addresses
00178      */
00179     enum Registers_e {
00180         STATUS_REG                  = 0x00, /*!< 0x00 default value = 0x0002 */
00181         VALRTTH_REG                 = 0x01, /*!< 0x01 */
00182         TALRTTH_REG                 = 0x02, /*!< 0x02 */
00183         SALRTTH_REG                 = 0x03, /*!< 0x03 */
00184         ATRATE_REG                  = 0x04, /*!< 0x04 write negative 2s comp of a 16-bit theoretical load */
00185         REPCAP_REG                  = 0x05, /*!< 0x05 */
00186         REPSOC_REG                  = 0x06, /*!< 0x06 */
00187         TEMP_REG                    = 0x08, /*!< 0x08 */
00188         VCELL_REG                   = 0x09, /*!< 0x09 */
00189         CURRENT_REG                 = 0x0A, /*!< 0x0A */
00190         AVGCURRENT_REG              = 0x0B, /*!< 0x0B */
00191         MIXSOC_REG                  = 0x0D, /*!< 0x0D */
00192         AVSOC_REG                   = 0x0E, /*!< 0x0E */
00193         MIXCAP_REG                  = 0x0F, /*!< 0x0F */
00194 
00195         FULLCAPREP_REG              = 0x10, /*!< 0x10 */
00196         TTE_REG                     = 0X11, /*!< 0x11 */
00197         QRTABLE00_REG               = 0x12, /*!< 0x12 */
00198         FULLSOCTHR_REG              = 0x13, /*!< 0x13 */
00199         CYCLES_REG                  = 0x17, /*!< 0x17 */
00200         DESIGNCAP_REG               = 0x18, /*!< 0x18 */
00201         AVGVCELL_REG                = 0x19, /*!< 0x19 */
00202         MAXMINVOLT_REG              = 0x1B, /*!< 0x1B */
00203         CONFIG_REG                  = 0x1D, /*!< 0x1D default = 0x2210 */
00204         ICHGTERM_REG                = 0x1E, /*!< 0x1E */
00205 
00206         TTF_REG                     = 0x20, /*!< 0x20 */
00207         VERSION_REG                 = 0x21, /*!< 0x21 */
00208         QRTABLE10_REG               = 0x22, /*!< 0x22 */
00209         FULLCAPNOM_REG              = 0x23, /*!< 0x23 */
00210         LEARNCFG_REG                = 0x28, /*!< 0x28 */
00211         RELAXCFG_REG                = 0x2A, /*!< 0x2A */
00212         TGAIN_REG                   = 0x2C, /*!< 0x2C */
00213         TOFF_REG                    = 0x2D, /*!< 0x2D */
00214 
00215         QRTABLE20_REG               = 0x32, /*!< 0x32 */
00216         RCOMP0_REG                  = 0x38, /*!< 0x38 */
00217         TEMPCO_REG                  = 0x39, /*!< 0x39 */
00218         VEMPTY_REG                  = 0x3A, /*!< 0x39 */
00219         FSTAT_REG                   = 0x3D, /*!< 0x39 */
00220 
00221         QRTABLE30_REG               = 0x42, /*!< 0x39 */
00222         DQACC_REG                   = 0x45, /*!< 0x39 */
00223         DPACC_REG                   = 0x46, /*!< 0x39 */
00224         VFSOC0_REG                  = 0x48, /*!< 0x39 */
00225         QH0_REG                     = 0x4C, /*!< 0x39 */
00226         QH_REG                      = 0x4D, /*!< 0x39 */
00227 
00228         VFSOC0_QH0_LOCK_REG         = 0x60, /*!< 0x39 */
00229         LOCK1_REG                   = 0x62, /*!< 0x39 */
00230         LOCK2_REG                   = 0x63, /*!< 0x39 */
00231 
00232         MODELDATA_START_REG         = 0x80, /*!< 0x39 */
00233 
00234         IALRTTH_REG                 = 0xB4, /*!< 0x39 */
00235         CURVE_REG                   = 0xB9, /*!< 0x39 */
00236         HIBCFG_REG                  = 0xBA, /*!< 0x39 default = 0x870C (0x890C)*/
00237         CONFIG2_REG                 = 0xBB, /*!< 0xBB default = 0x3658 */
00238 
00239         MODELCFG_REG                = 0xDB, /*!< 0xDB */
00240         ATTTE_REG                   = 0xDD, /*!< 0xDD */
00241         ATAVSOC_REG                 = 0xDE, /*!< 0xDE */
00242         ATAVCAP_REG                 = 0xDF, /*!< 0xDF */
00243 
00244         OCV_REG                     = 0xFB, /*!< 0x39 */
00245         VFSOC_REG                   = 0xFF  /*!< 0x39 */
00246     };
00247 
00248     /**
00249      * @brief      Saved Platform Data for Fuel Gauge Model
00250      * @details    Struct with fuel Gauge Platform Data for Fuel Gauge Model based on the final design.
00251      */
00252     struct platform_data { //to clarify if Part of the class
00253         uint16_t designcap ;/*!< struct value 1 */
00254         uint16_t ichgterm ; /*!< struct value 2 */
00255         uint16_t vempty ;   /*!< struct value 3 */
00256         int vcharge ;       /*!< struct value 1 */
00257 
00258         /**
00259          * rsense in miliOhms.
00260          * default 10 (if rsense = 0) as it is the recommended value by
00261          * the datasheet although it can be changed by board designers.
00262          * MAX32620FTHR has a 5mOhm sense resitor installed.
00263          */
00264         unsigned int rsense;
00265     } ;
00266 
00267     /**
00268      * @brief      Saved Fuel Gauge Parameters
00269      * @details    It is recommended to save the learned capacity parameters
00270      *             every time bit 2 of the Cycles register toggles (so that it
00271      *             is saved every 64% change in the battery) so that if power is
00272      *             lost the values can easily be restored.
00273      */
00274     struct saved_FG_params_t {
00275         int rcomp0;              /**< The RComp0 is the characterization information critical to computing the open-circuit voltage of a cell under loaded conditions. */
00276         int temp_co;             /**< The TempCo value is the temperature compensation information based on the RComp0 value*/
00277         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. */
00278         int cycles;              /**< The Cycles value maintains a total count of the number of charge/discharge cycles of the cell that have occurred */
00279         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
00280                                     is calculated each time a cell relaxation event is detected. This values is used to generate other outputs of the ModelGauge m5 algorithm. */
00281     } ;
00282 
00283     /**
00284      * @brief       max17055 Constructor
00285      */
00286     MAX17055(I2C &i2c);
00287 
00288     /**
00289      * @brief       Fuel Gauge Destructor
00290      */
00291     ~MAX17055();
00292 
00293     /**
00294      * @brief      Poll Flag clear Function.
00295      */
00296     int poll_flag_clear(Registers_e reg_addr, int mask, int timeout);
00297 
00298     /**
00299      * @brief      Check POR function
00300      */
00301     int check_POR_func();
00302 
00303     /**
00304      * @brief        clear POR bit function
00305      */
00306     int clear_POR_bit();
00307 
00308     /**
00309      * @brief       Write and Verify a MAX17055 register
00310      */
00311     int write_and_verify_reg(Registers_e reg_addr, uint16_t reg_data);
00312 
00313     /**
00314      * @brief       Initialization Function for MAX17055.
00315      */
00316     int init(platform_data des_data);
00317 
00318     /**
00319      * @brief       Get Temperature Function from the MAX17055 TEMP register.
00320      */
00321     int get_temperature();
00322 
00323     /**
00324      * @brief       Forced Exit Hibernate Mode Function for MAX17055
00325      */
00326     uint16_t forcedExitHiberMode();// Hibernate spelling
00327 
00328     /**
00329      * @brief       EZ Config function
00330      */
00331     uint16_t EZconfig(platform_data des_data);
00332 
00333     /**
00334      * @brief       Get reported Battery Capacity Function from MAX17055 Fuel Gauge
00335      */
00336     int get_battCAP(platform_data des_data);
00337 
00338     /**
00339      * @brief       Get reported State Of Charge(SOC) Function from MAX17055 Fuel Gauge
00340      */
00341     int get_SOC();
00342 
00343     /**
00344      * @brief       Get at rate Average State Of Charge(SOC) Function from MAX17055 Fuel Gauge.
00345      */
00346     int get_atAvSOC();
00347 
00348     /**
00349      * @brief       Get the Time to Empty(TTE) Function form MAX17055 Fuel Gauge.
00350      */
00351     float get_TTE();
00352 
00353     /**
00354      * @brief       Get the at Time to Empty(atTTE) value Function for MAX17055 Fuel Gauge.
00355      */
00356     float get_atTTE();
00357 
00358     /**
00359      * @brief        Get mix State Of Charge(SOC) Function for MAX17055 Fuel Gauge.
00360      */
00361     int get_mixSOC();
00362 
00363     /**
00364      * @brief      Get the Time to Full(TTE) values Function for MAX17055 Fuel Gauge.
00365      */
00366     float get_TTF();
00367 
00368     /**
00369      * @brief       Get voltage of the cell Function for MAX17055 Fuel Gauge.
00370      */
00371     int get_Vcell();
00372 
00373     /**
00374      * @brief       Get average voltage of the cell Function for MAX17055 Fuel Gauge.
00375      */
00376     int get_avgVcell();
00377 
00378     /**
00379      * @brief       Get current Function for MAX17055 Fuel Gauge.
00380      */
00381     float get_Current(platform_data des_data);
00382 
00383     /**
00384      * @brief       Get average current Function for MAX17055 Fuel Gauge.
00385      */
00386     float get_AvgCurrent(platform_data des_data);
00387 
00388     /**
00389      * @brief        lsb_to_uvolts Conversion Function
00390      */
00391     int lsb_to_uvolts(uint16_t lsb);
00392 
00393     /**
00394      * @brief        raw_current_to_uamp Conversion Function
00395      */
00396     float raw_current_to_uamps(uint32_t curr, int rsense_value);
00397 
00398     /**
00399      * @brief        raw_cap_to_uAh Conversion Function
00400      */
00401     int raw_cap_to_uAh(uint32_t raw_cap, int rsense_value);
00402 
00403     /**
00404      * @brief        Save Learned Parameters Function for battery Fuel Gauge model.
00405      */
00406     int save_Params(saved_FG_params_t FG_params);
00407 
00408     /**
00409      * @brief        Restore Parameters Function for battery Fuel Gauge model.
00410      */
00411     int restore_Params(saved_FG_params_t FG_params);
00412 
00413     /**
00414      * @brief        Function to Save Average Current to At Rate register.
00415      */
00416     int avCurr_2_atRate();
00417 
00418     /**
00419      * @brief       Get specified register info Function for MAX17055 Fuel Gauge.
00420      */
00421     int16_t get_regInfo(Registers_e reg_addr);
00422 
00423 protected:
00424 
00425     /**
00426      * @brief      Writes to MAX17055 register.
00427      */
00428     int writeReg(const Registers_e reg_addr, uint16_t reg_data);
00429 
00430 
00431     /**
00432      * @brief      Reads from MAX17055 register.
00433      */
00434     int32_t readReg(Registers_e reg_addr, uint16_t &value);
00435 
00436 
00437 
00438 
00439 private:
00440 
00441     I2C &m_i2cBus;        // I2C object
00442 
00443 };
00444 
00445 #endif /* _MAX17055_H_ */