File content as of revision 9:f29d5e49b190:

/******************************************************************//**
* @file max17055.h
*
* @author Felipe Neira - Maxim Integrated - TTS
*
* @version 1.2
*
* Started: 9JAN18
*
* Updated: 
* New functions improved for continious display. Change copyright notice for 2018. 
*
* 
*
/*******************************************************************************
* Copyright (C) 2018 Maxim Integrated Products, Inc., All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
* OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*
* Except as contained in this notice, the name of Maxim Integrated
* Products, Inc. shall not be used except as stated in the Maxim Integrated
* Products, Inc. Branding Policy.
*
* The mere transfer of this software does not imply any licenses
* of trade secrets, proprietary technology, copyrights, patents,
* trademarks, maskwork rights, or any other form of intellectual
* property whatsoever. Maxim Integrated Products, Inc. retains all
* ownership rights.
*******************************************************************************
*/

#ifndef __MAX17055_H_
#define __MAX17055_H_

// Include
#include "mbed.h"

/* STATUS register bits */
#define MAX17055_STATUS_BST             (1 << 3)
#define MAX17055_STATUS_POR             (1 << 1)

/// Model loading options
#define MODEL_LOADING_OPTION1           1 //EZ Config
#define MODEL_LOADING_OPTION2           2 //Not implemented in this version of the library
#define MODEL_LOADING_OPTION3           3 //Not implemented in this version of the library


/**
 * @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.
 *
 * @code
 * #include "mbed.h"
 * #include "MAX17055.h"
 *
 *
 * // Hardware serial port
 * Serial serial(USBTX, USBRX);
 *
 * //SPI communications
 * I2C i2c(SCL, SDA);
 *
 * //Fuel Gauge
 * MAX17055 max17055(i2C, Sutff );//To be completed
 *
 *
 * int main(void)
 * {
 *     CODE CODE TBD
 *      while(true)
 *      {
 *          CODE CODE TBD
 *      }
 * }
 * @endcode
 */



//! BATTERY Battery Parameters Class
/*!
 Generic API for battery parameters
 */
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
     } ;
    
        
   

};

/******************************************************************//**
* MAX17055 Class
**********************************************************************/
/// MAX17055 Battery Fuel Gauge Class 
/** Generic API for a battery fuel gauge
 */
class MAX17055
{

public:

    ///7-bit slave address
    static const uint8_t I2C_ADRS   = 0x36;  //Slave address 0x6C or 0x36 for 7 MSbit Addres
    ///8-bit write address
    static const uint8_t I2C_W_ADRS = 0x6C;
    ///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
     */
    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 */

        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 */

        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,

        VFSOC0_QH0_LOCK_REG        = 0x60,
        LOCK1_REG                  = 0x62,
        LOCK2_REG                  = 0x63,

        MODELDATA_START_REG        = 0x80,

        IALRTTH_REG                = 0xB4,
        CURVE_REG                  = 0xB9,
        HIBCFG_REG                 = 0xBA,
        CONFIG2_REG                = 0xBB, /**< 0xBB default = 0x3658 */

        MODELCFG_REG               = 0xDB,
        ATTTE_REG                  = 0xDD,

        OCV_REG                    = 0xFB,
        VFSOC_REG                  = 0xFF,
    } ;
    
    
    /**
    * @brief       Saved Fuel Gauge Parameters
    * @details     Struct with saved fuel Gauge Parametrs
    */

        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 qrtable10;
        uint16_t qrtable20;
        uint16_t qrtable30;

        uint16_t dpacc;
        uint16_t modelcfg;

        //uint16_t model_data[MAX17055_TABLE_SIZE];
        int (*get_charging_status)(void);
        int model_option;
        /**
         * rsense in miliOhms.
         * default 10 (if rsense = 0) as it is the recommended value by
         * the datasheet although it can be changed by board designers.
         */
        unsigned int rsense; 
        int volt_min;   /**< in mV */
        int volt_max;   /**< in mV */
        int temp_min;   /**< in DegreC */
        int temp_max;   /**< in DegreeC */
        int soc_max;    /**< in percent */
        int soc_min;    /**< in percent */
        int curr_max;   /**< in mA */
        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.
    */

    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 */
     } ;



   


    /**
     * @brief       max17055 Constructor
     * @details     max17055 Constructor with battery and i2c as parameters
     */
    MAX17055(I2C &i2c);

    /**
     * @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
    */


    
    int poll_flag_clear(Registers_e reg_addr, int mask, int timeout);

    ////////////////////////////////////////////////////////////////////////////////

    /**
    * \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
    */
    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
    *
    */


    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
    */


    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
    */


    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
    *
    */


    uint16_t forcedExitHyberMode();
    
    /**
    * \brief        EZ COnfing Init function
    * \par          Details
    *               This function implements the steps for the EZ confing m5 FuelGauge
    *
    * \retval       returns TBD
    *
    */


    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
    */
    
    
    int get_SOC();

        ///////////////////////////////////////////////////////////////////////////

    /**
    * \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 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
    */   
    
    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
    */


    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
    */
    
    
    int get_TTF();
    
    
  ////////////////////////////////////////////////////////////////////////////

    /**
    * \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
    * \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
    * \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
    *         
    */
    
    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
    *         
    */
    
    int raw_current_to_uamps(uint32_t curr, int rsense_value);

    ///////////////////////////////////////////////////////////////////////////////

    /**
    * \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
    * \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);

protected:
    /**
     * @brief       Write Register
     * @details     Writes data to max17055 Register
     *
     * @parameters  reg_addr Registers to write
     *              reg_data Data to write
     */
    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
     */
    int32_t readReg(Registers_e reg_addr, uint16_t &value);








private:

    I2C &m_i2cBus;                          // I2C object

};

#endif /* _MAX17055_H_ */