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 "mbed.h"
00038 
00039 #define MAX17055_I2C_ADDRESS   0x6C
00040 
00041 #define MAX17055_NO_ERROR 0
00042 #define MAX17055_ERROR    -1
00043 
00044 #define MAX17055_V_LSB_MV         7.8125E-5f
00045 #define MAX17055_V_MAX_MIN_LSB_MV 2.0E-2f
00046 #define MAX17055_I_LSB_UV         1.5625E-3f
00047 #define MAX17055_I_MAX_MIN_LSB_MV 0.0004f
00048 
00049 /**
00050  * @brief MAX17055 7µA 1-Cell Fuel Gauge with ModelGauge m5 EZ
00051  *
00052  * @details The MAX17055 is a low 7μA operating current fuel gauge which
00053  * implements Maxim ModelGauge™ m5 EZ algorithm.  ModelGauge m5 EZ makes
00054  * fuel gauge implementation easy by eliminating battery characterization
00055  * requirements and simplifying host software interaction.
00056  * The ModelGauge m5 EZ robust algorithm provides tolerance against battery
00057  * diversity for most lithium batteries and applications.
00058  * <br>https://www.maximintegrated.com/en/products/power/battery-management/MAX17055.html
00059  *
00060  * @code
00061  * #include "mbed.h"
00062  * #include "MAX17055.h"
00063  *
00064  * // I2C Master 2
00065  * I2C i2c(I2C2_SDA, I2C2_SCL);
00066  *
00067  * MAX17055 max17055(i2c);
00068  *
00069  * int main()
00070  * {
00071  *     int status;
00072  *     float f_value;
00073  *
00074  *     // Set sense resistor value
00075  *     max17055.init(0.05f);
00076  *
00077  *     // Print status
00078  *     max17055.status(&status);
00079  *     printf("MAX17055 status: %04X\r\n", (uint16_t)status);
00080  *
00081  *     for (;;) {
00082  *         // Print formatted voltage, current and temperature values
00083  *         max17055.v_cell(&f_value);
00084  *         printf("%6.3fV ", f_value);
00085  *         max17055.current(&f_value);
00086  *         printf("%6.3fI ", f_value);
00087  *         max17055.temp(&f_value);
00088  *         printf("%6.3fC ", f_value);
00089  *         printf("\r\n");
00090  *
00091  *         Thread::wait(3000);
00092  *     }
00093  * }
00094  * @endcode
00095  */
00096 
00097 class MAX17055
00098 {
00099 public:
00100 
00101     /**
00102      * @brief   Register Address
00103      * @details MAX17055 register addresses
00104      */
00105     typedef enum {
00106         STATUS = 0x00,
00107         V_ALRT_TH,
00108         T_ALRT_TH,
00109         S_ALRT_TH,
00110         AT_RATE,
00111         REP_CAP,
00112         REP_SOC,
00113         AGE,
00114         TEMP,
00115         V_CELL,
00116         CURRENT,
00117         AVG_CURRENT,
00118         Q_RESIDUAL,
00119         MIX_SOC,
00120         AV_SOC,
00121         MIX_CAP,
00122         FULL_CAP_REP,
00123         TTE,
00124         QR_TABLE_00,
00125         FULL_SOC_THR,
00126         R_CELL,
00127         AVG_TA = 0x16,
00128         CYCLES,
00129         DESIGN_CAP,
00130         AVG_V_CELL,
00131         MAX_MIN_TEMP,
00132         MAX_MIN_VOLT,
00133         MAX_MIN_CURR,
00134         CONFIG,
00135         I_CHG_TERM,
00136         AV_CAP,
00137         TTF,
00138         DEV_NAME,
00139         QR_TABLE_10,
00140         FULL_CAP_NOM,
00141         AIN = 0x27,
00142         LEARN_CFG,
00143         FILTER_CFG,
00144         RELAX_CFG,
00145         MISC_CFG,
00146         T_GAIN,
00147         T_OFF,
00148         C_GAIN,
00149         C_OFF,
00150         QR_TABLE_20 = 0x32,
00151         DIE_TEMP = 0x34,
00152         FULL_CAP,
00153         R_COMP0 = 0x38,
00154         TEMP_CO,
00155         V_EMPTY,
00156         F_STAT = 0x3D,
00157         TIMER,
00158         SHDN_TIMER,
00159         USER_MEM1,
00160         QR_TABLE_30 = 0x42,
00161         R_GAIN,
00162         DQ_ACC = 0x45,
00163         DP_ACC,
00164         CONVG_CFG = 0x49,
00165         VF_REM_CAP,
00166         QH = 0x4D,
00167         STATUS_2 = 0xB0,
00168         POWER,
00169         ID_USER_MEM2,
00170         AVG_POWER,
00171         I_ALRT_TH,
00172         TTF_CFG,
00173         CV_MIX_CAP,
00174         CV_HALF_TIME,
00175         CG_TEMP_CO,
00176         CURVE,
00177         HIB_CFG,
00178         CONFIG2,
00179         V_RIPPLE,
00180         RIPPLE_CFG,
00181         TIMER_H,
00182         R_SENSE_USER_MEM3 = 0xD0,
00183         SC_OCV_LIM,
00184         SOC_HOLD,
00185         MAX_PEAK_POWER,
00186         SUS_PEAK_POWER,
00187         PACK_RESISTANCE,
00188         SYS_RESISTANCE,
00189         MIN_SYS_VOLTAGE,
00190         MPP_CURRENT,
00191         SPP_CURRENT,
00192         MODEL_CFG,
00193         AT_Q_RESIDUAL,
00194         AT_TTE,
00195         AT_AV_SOC,
00196         AT_AV_CA
00197     } reg_t;
00198 
00199     /**
00200      * MAX17055 constructor
00201      *
00202      * @param i2c I2C object to use.
00203      * @param address Slave Address of the device.
00204      */
00205     MAX17055(I2C &i2c, int address = MAX17055_I2C_ADDRESS);
00206 
00207     /**
00208      * MAX17055 destructor
00209      */
00210     ~MAX17055();
00211 
00212     /**
00213      * @brief   Initialize driver state
00214      * @details Initialize driver with supplied sense resistor value.
00215      * @param   value The sense resistor value in ohms
00216      * @returns 0 if no errors, -1 if error
00217      */
00218     void init(float r_sense);
00219 
00220     /**
00221      * @brief   Read status register
00222      * @details Read status register.
00223      * @param   value The location to store value read
00224      * @returns 0 if no errors, -1 if error
00225      */
00226     int status(int *value);
00227 
00228     /**
00229      * @brief   Read VCell register
00230      * @details Read VCell register reports the voltage measured between
00231      * BATT and CSP.
00232      * @param   value The location to store value read
00233      * @returns 0 if no errors, -1 if error
00234      */
00235     int v_cell(int *value);
00236 
00237     /**
00238      * @brief   Read VCell register
00239      * @details The VCell register reports the voltage measured between
00240      * BATT and CSP.
00241      * @param   value The location to store value read
00242      * @returns 0 if no errors, -1 if error
00243      */
00244     int v_cell(float *value);
00245 
00246     /**
00247      * @brief   Read AvgVCell register
00248      * @details The AvgVCell register reports an average of the VCell
00249      * register readings.
00250      * @param   value The location to store value read
00251      * @returns 0 if no errors, -1 if error
00252      */
00253     int avg_v_cell(int *value);
00254 
00255     /**
00256      * @brief   Read AvgVCell register
00257      * @details The AvgVCell register reports an average of the VCell
00258      * register readings.
00259      * @param   value The location to store value read
00260      * @returns 0 if no errors, -1 if error
00261      */
00262     int avg_v_cell(float *value);
00263 
00264     /**
00265      * @brief   Read MaxMinVolt register
00266      * @details The MaxMinVolt register maintains the maximum and minimum
00267      * of VCell register values since device reset.
00268      * @param   value The location to store value read
00269      * @returns 0 if no errors, -1 if error
00270      */
00271     int max_min_volt(int *max, int *min);
00272 
00273     /**
00274      * @brief   Read MaxMinVolt register
00275      * @details The MaxMinVolt register maintains the maximum and minimum
00276      * of VCell register values since device reset.
00277      * @param   value The location to store value read
00278      * @returns 0 if no errors, -1 if error
00279      */
00280     int max_min_volt(float *max, float *min);
00281 
00282     /**
00283      * @brief   Read Current register
00284      * @details The Current register reports the voltage between the
00285      * CSP and CSN pins.
00286      * @param   value The location to store value read
00287      * @returns 0 if no errors, -1 if error
00288      */
00289     int current(int *value);
00290 
00291     /**
00292      * @brief   Read Current register
00293      * @details The Current register reports the voltage between the
00294      * CSP and CSN pins.
00295      * @param   value The location to store value read
00296      * @returns 0 if no errors, -1 if error
00297      */
00298     int current(float *value);
00299 
00300     /**
00301      * @brief   Read AvgCurrent register
00302      * @details The AvgCurrent register reports an average of Current
00303      * register readings.
00304      * @param   value The location to store value read
00305      * @returns 0 if no errors, -1 if error
00306      */
00307     int avg_current(int *value);
00308 
00309     /**
00310      * @brief   Read AvgCurrent register
00311      * @details The AvgCurrent register reports an average of Current
00312      * register readings.
00313      * @param   value The location to store value read
00314      * @returns 0 if no errors, -1 if error
00315      */
00316     int avg_current(float *value);
00317 
00318     /**
00319      * @brief   Read MinMaxCurr register
00320      * @details The MaxMinCurr register maintains the maximum and
00321      * minimum Current register values since the last IC reset
00322      * or until cleared by host software.
00323      * @param   value The location to store value read
00324      * @returns 0 if no errors, -1 if error
00325      */
00326     int max_min_curr(int *max, int *min);
00327 
00328     /**
00329      * @brief   Read MinMaxCurrent register
00330      * @details The MaxMinCurr register maintains the maximum and
00331      * minimum Current register values since the last IC reset
00332      * or until cleared by host software.
00333      * @param   value The location to store value read
00334      * @returns 0 if no errors, -1 if error
00335      */
00336     int max_min_curr(float *max, float *min);
00337 
00338     /**
00339      * @brief   Read Temp register
00340      * @details The Temp register provides the temperature measured
00341      * by the thermistor or die temperature.
00342      * @param   value The location to store value read
00343      * @returns 0 if no errors, -1 if error
00344      */
00345     int temp(int *value);
00346 
00347     /**
00348      * @brief   Read Temp register
00349      * @details The Temp register provides the temperature measured
00350      * by the thermistor or die temperature.
00351      * @param   value The location to store value read
00352      * @returns 0 if no errors, -1 if error
00353      */
00354     int temp(float *value);
00355 
00356     /**
00357      * @brief   Read AvgTA register
00358      * @details The AvgTA register reports an average of the readings
00359      * from the Temp register.
00360      * @param   value The location to store value read
00361      * @returns 0 if no errors, -1 if error
00362      */
00363     int avg_ta(int *value);
00364 
00365     /**
00366      * @brief   Read AvgTA register
00367      * @details The AvgTA register reports an average of the readings
00368      * from the Temp register.
00369      * @param   value The location to store value read
00370      * @returns 0 if no errors, -1 if error
00371      */
00372     int avg_ta(float *value);
00373 
00374     /**
00375      * @brief   Read MaxMinTemp register
00376      * @details The MaxMinTemp register maintains the maximum and
00377      * minimum Temp register values since the last fuel-gauge reset
00378      * or until cleared by host software.
00379      * @param   value The location to store value read
00380      * @returns 0 if no errors, -1 if error
00381      */
00382     int max_min_temp(int *max, int *min);
00383 
00384     /**
00385      * @brief   Read MaxMinTemp register
00386      * @details The MaxMinTemp register maintains the maximum and
00387      * minimum Temp register values since the last fuel-gauge reset
00388      * or until cleared by host software.
00389      * @param   value The location to store value read
00390      * @returns 0 if no errors, -1 if error
00391      */
00392     int max_min_temp(float *max, float *min);
00393 
00394     /**
00395      * @brief   Write 8-Bit Register
00396      * @details Writes the given value to the specified register.
00397      * @param   reg The register to be written
00398      * @param   value The data to be written
00399      * @param   verify Verify data after write
00400      * @returns 0 if no errors, -1 if error.
00401      */
00402     int writeReg(reg_t reg, char value, bool verify = false);
00403 
00404     /**
00405      * @brief   Write 16-Bit Register
00406      * @details Writes the given value to the specified register.
00407      * @param   reg The register to be written
00408      * @param   value The data to be written
00409      * @param   verify Verify data after write
00410      * @returns 0 if no errors, -1 if error.
00411      */
00412     int writeReg(reg_t reg, uint16_t value, bool verify = false);
00413 
00414     /**
00415      * @brief   Read 8-Bit Register
00416      * @details Reads from the specified register
00417      * @param   reg The register to be read
00418      * @param   value Pointer for where to store the data
00419      * @returns 0 if no errors, -1 if error.
00420      */
00421     int readReg(reg_t reg, char *value);
00422 
00423     /**
00424      * @brief   Read 8-Bit Register(s)
00425      * @details Reads len bytes starting from the specified register
00426      * @param   reg The register to be read
00427      * @param   value Pointer for where to store the data
00428      * @param   len Number of bytes to read
00429      * @returns 0 if no errors, -1 if error.
00430      */
00431     int readReg(reg_t reg, char *buf, int len);
00432 
00433     /**
00434      * @brief   Read 16-Bit Register
00435      * @details Reads from the specified register
00436      * @param   reg The register to be read
00437      * @param   value Pointer for where to store the data
00438      * @returns 0 if no errors, -1 if error.
00439      */
00440     int readReg16(reg_t reg, int *value);
00441 
00442 private:
00443     I2C &i2c;
00444     int addr;
00445 
00446     float r_sense;
00447     float i_lsb;
00448     float i_min_max_lsb;
00449 };
00450 
00451 #endif