max17055.h

00001 /******************************************************************//**
00002 * @file max17055.h
00003 *
00004 * @author Felipe Neira - Maxim Integrated - TTS
00005 *
00006 * @version 1.5
00007 *
00008 * Started: 13DEC17
00009 *
00010 * Updated: 16APR18.
00011 * Remove unnecessary code.  
00012 * Check spelling
00013 * Error check
00014 * 
00015 *
00016 /*******************************************************************************
00017 * Copyright (C) 2018 Maxim Integrated Products, Inc., All Rights Reserved.
00018 *
00019 * Permission is hereby granted, free of charge, to any person obtaining a
00020 * copy of this software and associated documentation files (the "Software"),
00021 * to deal in the Software without restriction, including without limitation
00022 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00023 * and/or sell copies of the Software, and to permit persons to whom the
00024 * Software is furnished to do so, subject to the following conditions:
00025 *
00026 * The above copyright notice and this permission notice shall be included
00027 * in all copies or substantial portions of the Software.
00028 *
00029 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00030 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00031 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00032 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00033 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00034 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00035 * OTHER DEALINGS IN THE SOFTWARE.
00036 *
00037 * Except as contained in this notice, the name of Maxim Integrated
00038 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00039 * Products, Inc. Branding Policy.
00040 *
00041 * The mere transfer of this software does not imply any licenses
00042 * of trade secrets, proprietary technology, copyrights, patents,
00043 * trademarks, maskwork rights, or any other form of intellectual
00044 * property whatsoever. Maxim Integrated Products, Inc. retains all
00045 * ownership rights.
00046 *******************************************************************************
00047 */
00048 
00049 #ifndef __MAX17055_H_
00050 #define __MAX17055_H_
00051 
00052 // Include
00053 #include "mbed.h"
00054 
00055 /* STATUS register bits */
00056 #define MAX17055_STATUS_BST             (1 << 3)
00057 #define MAX17055_STATUS_POR             (1 << 1)
00058 
00059 /// Model loading options
00060 #define MODEL_LOADING_OPTION1           1 //EZ Config
00061 // #define MODEL_LOADING_OPTION2           2 //Not implemented in this version of the library
00062 // #define MODEL_LOADING_OPTION3           3 //Not implemented in this version of the library
00063 //Remove this and leave it 
00064 
00065 /**
00066  * @brief MBED Library for the MAX17055\n
00067  * The MAX17055 is a low 7μA operating current fuel gauge which  \n
00068  * implements Maxim ModelGauge™ m5 EZ algorithm.                 \n   
00069  * <a href="https://www.maximintegrated.com/en/design/partners-and-technology/design-technology/modelgauge-battery-fuel-gauge-technology.html">ModelGauge</a>
00070  * m5 EZ makes fuel gauge implementation easy by eliminating     \n
00071  * battery characterization requirements and simplifying host    \n
00072  * software interaction. The ModelGauge m5 EZ robust algorithm   \n
00073  * provides tolerance against battery diversity for most lithium \n
00074  * batteries and applications. Communication is through an       \n
00075  * SPI-compatible interface. The MAX17055 comes as part of the   \n 
00076  * MAX32620FTHR MBED enable development board.\n 
00077  * \n
00078  * Visit the product page for more information:
00079  * <a href="https://www.maximintegrated.com/MAX17055.html">MAX17055 Product Page</a>\n
00080  * <a href="https://www.maximintegrated.com/MAX17055.pdf">MAX17055 Data Sheet</a>\n
00081  * <a href="https://www.maximintegrated.com/MAX32620FTHR.html">MAX32620FTHR Product Page</a>\n
00082  * <a href="https://www.maximintegrated.com/MAX32620FTHR.pdf">MAX32620FTHR Data Sheet</a>\n
00083  * 
00084  * @code
00085  * 
00086  * ///This is not the final test code. Just sample place holder. 
00087  * #include "mbed.h"
00088  * #include "MAX17055.h"
00089  *
00090  *
00091  * // Hardware serial port
00092  * Serial serial(USBTX, USBRX);
00093  *
00094  * //SPI communications
00095  * I2C i2c(SCL, SDA);
00096  *
00097  * //Fuel Gauge
00098  * MAX17055 max17055(i2C, Sutff );//To be completed
00099  *
00100  *
00101  * int main(void)
00102  * {
00103  *     CODE CODE TBD
00104  *      while(true)
00105  *      {
00106  *          CODE CODE TBD
00107  *      }
00108  * }
00109  * @endcode
00110  */
00111 
00112 
00113 /*-------------------------------------------------------------------------*//**
00114  * MAX17055 Class
00115  * @brief      Class for MAX17055 Battery Fuel Gauge
00116  *          - Generic API for Implementing the Battery Fuel Gauge
00117  */
00118 class MAX17055
00119 {
00120 
00121 public:
00122 
00123     ///8-bit write address
00124     static const uint8_t I2C_W_ADRS = 0x6C;
00125     ///8-bit read address
00126     static const uint8_t I2C_R_ADRS = 0x6D;
00127 
00128     /**
00129      * @brief      Register Addresses for the MAX17055
00130      * @details    Enumerated register addresses
00131      */
00132     enum Registers_e {   
00133         STATUS_REG                  = 0x00, /*!< 0x00 default value = 0x0002 */
00134         VALRTTH_REG                 = 0x01, /*!< 0x01 */
00135         TALRTTH_REG                 = 0x02, /*!< 0x02 */ 
00136         SALRTTH_REG                 = 0x03, /*!< 0x03 */ 
00137         ATRATE_REG                  = 0x04, /*!< 0x04 write negative 2s comp of a 16-bit theoretical load */
00138         REPCAP_REG                  = 0x05, /*!< 0x05 */ 
00139         REPSOC_REG                  = 0x06, /*!< 0x06 */
00140         TEMP_REG                    = 0x08, /*!< 0x08 */
00141         VCELL_REG                   = 0x09, /*!< 0x09 */
00142         CURRENT_REG                 = 0x0A, /*!< 0x0A */ 
00143         AVGCURRENT_REG              = 0x0B, /*!< 0x0B */
00144         MIXSOC_REG                  = 0x0D, /*!< 0x0D */
00145         AVSOC_REG                   = 0x0E, /*!< 0x0E */
00146         MIXCAP_REG                  = 0x0F, /*!< 0x0F */
00147 
00148         FULLCAPREP_REG              = 0x10, /*!< 0x10 */
00149         TTE_REG                     = 0X11, /*!< 0x11 */
00150         QRTABLE00_REG               = 0x12, /*!< 0x12 */
00151         FULLSOCTHR_REG              = 0x13, /*!< 0x13 */
00152         CYCLES_REG                  = 0x17, /*!< 0x17 */
00153         DESIGNCAP_REG               = 0x18, /*!< 0x18 */
00154         AVGVCELL_REG                = 0x19, /*!< 0x19 */
00155         MAXMINVOLT_REG              = 0x1B, /*!< 0x1B */
00156         CONFIG_REG                  = 0x1D, /*!< 0x1D default = 0x2210 */
00157         ICHGTERM_REG                = 0x1E, /*!< 0x1E */
00158 
00159         TTF_REG                     = 0x20, /*!< 0x20 */
00160         VERSION_REG                 = 0x21, /*!< 0x21 */
00161         QRTABLE10_REG               = 0x22, /*!< 0x22 */
00162         FULLCAPNOM_REG              = 0x23, /*!< 0x23 */
00163         LEARNCFG_REG                = 0x28, /*!< 0x28 */
00164         RELAXCFG_REG                = 0x2A, /*!< 0x2A */
00165         TGAIN_REG                   = 0x2C, /*!< 0x2C */
00166         TOFF_REG                    = 0x2D, /*!< 0x2D */
00167 
00168         QRTABLE20_REG               = 0x32, /*!< 0x32 */
00169         RCOMP0_REG                  = 0x38, /*!< 0x38 */
00170         TEMPCO_REG                  = 0x39, /*!< 0x39 */
00171         VEMPTY_REG                  = 0x3A, /*!< 0x39 */
00172         FSTAT_REG                   = 0x3D, /*!< 0x39 */
00173 
00174         QRTABLE30_REG               = 0x42, /*!< 0x39 */
00175         DQACC_REG                   = 0x45, /*!< 0x39 */
00176         DPACC_REG                   = 0x46, /*!< 0x39 */
00177         VFSOC0_REG                  = 0x48, /*!< 0x39 */
00178         QH0_REG                     = 0x4C, /*!< 0x39 */
00179         QH_REG                      = 0x4D, /*!< 0x39 */
00180 
00181         VFSOC0_QH0_LOCK_REG         = 0x60, /*!< 0x39 */
00182         LOCK1_REG                   = 0x62, /*!< 0x39 */
00183         LOCK2_REG                   = 0x63, /*!< 0x39 */
00184 
00185         MODELDATA_START_REG         = 0x80, /*!< 0x39 */
00186 
00187         IALRTTH_REG                 = 0xB4, /*!< 0x39 */
00188         CURVE_REG                   = 0xB9, /*!< 0x39 */
00189         HIBCFG_REG                  = 0xBA, /*!< 0x39 default = 0x870C (0x890C)*/
00190         CONFIG2_REG                 = 0xBB, /*!< 0xBB default = 0x3658 */
00191 
00192         MODELCFG_REG                = 0xDB, /*!< 0xDB */
00193         ATTTE_REG                   = 0xDD, /*!< 0xDD */
00194         ATAVSOC_REG                 = 0xDE, /*!< 0xDE */
00195         ATAVCAP_REG                 = 0xDF, /*!< 0xDF */
00196 
00197         OCV_REG                     = 0xFB, /*!< 0x39 */
00198         VFSOC_REG                   = 0xFF  /*!< 0x39 */
00199     };
00200       
00201     /**
00202      * @brief      Saved Platform Data for Fuel Gauge Model
00203      * @details    Struct with fuel Gauge Platform Data for Fuel Gauge Model based on the final design.
00204      */
00205     struct platform_data{  //to clarify if Part of the class
00206         uint16_t designcap ;/*!< struct value 1 */
00207         uint16_t ichgterm ; /*!< struct value 2 */
00208         uint16_t vempty ;   /*!< struct value 3 */
00209         int vcharge ;       /*!< struct value 1 */
00210 
00211         uint16_t learncfg ;  /*!< struct value 1 */
00212         uint16_t relaxcfg ;  /*!< struct value 1 */
00213         uint16_t config ;    /*!< struct value 1 */
00214         uint16_t config2 ;   /*!< struct value 1 */
00215         uint16_t fullsocthr ;/*!< struct value 1 */
00216         uint16_t tgain ;     /*!< struct value 1 */
00217         uint16_t toff ;      /*!< struct value 1 */
00218         uint16_t curve ;     /*!< struct value 1 */
00219         uint16_t rcomp0 ;    /*!< struct value 1 */
00220         uint16_t tempco ;    /*!< struct value 1 */ 
00221         uint16_t qrtable00; 
00222         uint16_t qrtable10;
00223         uint16_t qrtable20;
00224         uint16_t qrtable30;
00225 
00226         uint16_t dpacc;
00227         uint16_t modelcfg;
00228 
00229         //uint16_t model_data[MAX17055_TABLE_SIZE];
00230         int (*get_charging_status)(void);
00231         int model_option;
00232         /**
00233          * rsense in miliOhms.
00234          * default 10 (if rsense = 0) as it is the recommended value by
00235          * the datasheet although it can be changed by board designers.
00236          */
00237         unsigned int rsense; 
00238         int volt_min;   /**< in mV */
00239         int volt_max;   /**< in mV */
00240         int temp_min;   /**< in DegreC */
00241         int temp_max;   /**< in DegreeC */
00242         int soc_max;    /**< in percent */
00243         int soc_min;    /**< in percent */
00244         int curr_max;   /**< in mA */
00245         int curr_min;   /**< in mA */
00246      } ;
00247     
00248     /**
00249      * @brief      Saved Fuel Gauge Parameters
00250      * @details    It is recommended to save the learned capacity parameters
00251      *             every time bit 2 of the Cycles register toggles (so that it
00252      *             is saved every 64% change in the battery) so that if power is
00253      *             lost the values can easily be restored.
00254      */
00255     struct saved_FG_params_t{
00256         int rcomp0;              /**< The RComp0 is the characterization information critical to computing the open-circuit voltage of a cell under loaded conditions. */
00257         int temp_co;             /**< The TempCo value is the temperature compensation information based on the RComp0 value*/
00258         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. */
00259         int cycles;              /**< The Cycles value maintains a total count of the number of charge/discharge cycles of the cell that have occurred */
00260         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
00261                                     is calculated each time a cell relaxation event is detected. This values is used to generate other outputs of the ModelGauge m5 algorithm. */
00262      } ;
00263 
00264     /**
00265      * @brief       max17055 Constructor
00266      */
00267     MAX17055(I2C &i2c);
00268 
00269     /**
00270      * @brief       Fuel Gauge Destructor
00271      */
00272     ~MAX17055();
00273     
00274     /**
00275      * @brief      Poll Flag clear Function.
00276      */
00277     int poll_flag_clear(Registers_e reg_addr, int mask, int timeout);
00278 
00279     /**
00280      * @brief      Check POR function
00281      */
00282     int check_POR_func();
00283 
00284     /**
00285      * @brief        clear POR bit function
00286      */
00287     int clear_POR_bit();
00288 
00289     /**
00290      * @brief       Write and Verify a MAX17055 register
00291      */
00292     int write_and_verify_reg(Registers_e reg_addr, uint16_t reg_data);
00293 
00294     /**
00295      * @brief       Initialization Function for MAX17055.
00296      */
00297     int init(platform_data des_data);
00298 
00299     /**
00300      * @brief       Get Temperature Function from the MAX17055 TEMP register.
00301      */
00302     int get_temperature();
00303 
00304     /**
00305      * @brief       Forced Exit Hibernate Mode Function for MAX17055
00306      */
00307     uint16_t forcedExitHiberMode();// Hibernate spelling 
00308     
00309     /**
00310      * @brief       EZ Config Initialization function
00311      */
00312     uint16_t EZconfig_init(platform_data des_data);
00313       
00314     /**
00315      * @brief       Get reported State Of Charge(SOC) Function from MAX17055 Fuel Gauge
00316      */
00317     int get_SOC();
00318 
00319     /**
00320      * @brief       Get at rate Average State Of Charge(SOC) Function from MAX17055 Fuel Gauge.
00321      */
00322     int get_atAvSOC();
00323 
00324     /**
00325      * @brief       Get the Time to Empty(TTE) Function form MAX17055 Fuel Gauge.
00326      */   
00327     float get_TTE();
00328 
00329     /**
00330      * @brief       Get the at Time to Empty(atTTE) value Function for MAX17055 Fuel Gauge.
00331      */   
00332     float get_atTTE();
00333 
00334     /**
00335      * @brief        Get mix State Of Charge(SOC) Function for MAX17055 Fuel Gauge.
00336      */
00337     int get_mixSOC();
00338 
00339     /**
00340      * @brief      Get the Time to Full(TTE) values Function for MAX17055 Fuel Gauge.
00341      */
00342     float get_TTF();
00343     
00344     /**
00345      * @brief       Get voltage of the cell Function for MAX17055 Fuel Gauge.
00346      */
00347     int get_Vcell();
00348 
00349     /**
00350      * @brief       Get current Function for MAX17055 Fuel Gauge.
00351      */
00352     int get_Current(platform_data des_data);
00353     
00354     /**
00355      * @brief       Get average current Function for MAX17055 Fuel Gauge.
00356      */  
00357     int get_AvgCurrent(platform_data des_data);
00358     
00359     /**
00360      * @brief        lsb_to_uvolts Conversion Function         
00361      */
00362     int lsb_to_uvolts(uint16_t lsb);
00363     
00364     /**
00365      * @brief        raw_current_to_uamp Conversion Function         
00366      */
00367     int raw_current_to_uamps(uint32_t curr, int rsense_value);
00368 
00369     /**
00370      * @brief        Save Learned Parameters Function for battery Fuel Gauge model.
00371      */
00372     int save_Params(saved_FG_params_t FG_params);
00373 
00374     /**
00375      * @brief        Restore Parameters Function for battery Fuel Gauge model.
00376      */
00377     int restore_Params(saved_FG_params_t FG_params);
00378 
00379     /**
00380      * @brief        Function to Save Average Current to At Rate register.
00381      */
00382     int avCurr_2_atRate();
00383 
00384 protected:
00385 
00386     /**
00387      * @brief      Writes to MAX17055 register.
00388      */
00389     int writeReg(const Registers_e reg_addr, uint16_t reg_data);
00390 
00391 
00392     /**
00393      * @brief      Reads from MAX17055 register.
00394      */
00395     int32_t readReg(Registers_e reg_addr, uint16_t &value);
00396 
00397 
00398 
00399 
00400 private:
00401 
00402     I2C &m_i2cBus;        // I2C object
00403 
00404 };
00405 
00406 #endif /* _MAX17055_H_ */