battmon3.h

Go to the documentation of this file.

/****************************************************************************
** Copyright (C) 2020 MikroElektronika d.o.o.
** Contact: https://www.mikroe.com/contact
**
** 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 THE AUTHORS OR COPYRIGHT HOLDERS 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.
****************************************************************************/
 
#ifndef BATTMON3_H
#define BATTMON3_H
 
#ifdef __cplusplus
extern "C"{
#endif
 
#ifdef PREINIT_SUPPORTED
#include "preinit.h"
#endif
 
#ifdef MikroCCoreVersion
    #if MikroCCoreVersion >= 1
        #include "delays.h"
    #endif
#endif
 
#include "drv_digital_out.h"
#include "drv_digital_in.h"
#include "drv_i2c_master.h"
 
#define BATTMON3_REG_CONTROL                    0x00
#define BATTMON3_REG_ACCUMULATED_CAPACITY       0x02
#define BATTMON3_REG_TEMPERATURE                0x06
#define BATTMON3_REG_VOLTAGE                    0x08
#define BATTMON3_REG_BATTERY_STATUS             0x0A
#define BATTMON3_REG_BATTERY_ALERT              0x0B
#define BATTMON3_REG_CURRENT                    0x0C
#define BATTMON3_REG_SCALED_R                   0x16
#define BATTMON3_REG_MEASURED_Z                 0x22
#define BATTMON3_REG_INTERNAL_TEMPERATURE       0x28
#define BATTMON3_REG_STATE_OF_HEALTH            0x2E
#define BATTMON3_REG_DESIGN_CAPACITY            0x3C
#define BATTMON3_REG_MAC                        0x3E
#define BATTMON3_REG_MAC_DATA                   0x40
#define BATTMON3_REG_MAC_DATA_SUM               0x60
#define BATTMON3_REG_MAC_DATA_LEN               0x61
#define BATTMON3_REG_MAC_DATA_CONTROL           0x62
#define BATTMON3_REG_CAL_COUNT                  0x79
#define BATTMON3_REG_CAL_CURRENT                0x7A
#define BATTMON3_REG_CAL_VOLTAGE                0x7C
#define BATTMON3_REG_CAL_TEMPERATURE            0x7E
 
#define BATTMON3_CONTROL_STATUS                 0x0000
#define BATTMON3_CONTROL_DEVICE_TYPE            0x0001
#define BATTMON3_CONTROL_FW_VERSION             0x0002
#define BATTMON3_CONTROL_HW_VERSION             0x0003
#define BATTMON3_CONTROL_STATIC_CHEM_CHKSUM     0x0005
#define BATTMON3_CONTROL_CHEM_ID                0x0006
#define BATTMON3_CONTROL_PREV_MACWRITE          0x0007
#define BATTMON3_CONTROL_BOARD_OFFSET           0x0009
#define BATTMON3_CONTROL_CC_OFFSET              0x000A
#define BATTMON3_CONTROL_CC_OFFSET_SAVE         0x000B
#define BATTMON3_CONTROL_DF_VERSION             0x000C
#define BATTMON3_CONTROL_GAUGE_START            0x0011
#define BATTMON3_CONTROL_GAUGE_STOP             0x0012
#define BATTMON3_CONTROL_SEALED                 0x0020
#define BATTMON3_CONTROL_CAL_ENABLE             0x002D
#define BATTMON3_CONTROL_LT_ENABLE              0x002E
#define BATTMON3_CONTROL_RESET                  0x0041
#define BATTMON3_CONTROL_EXIT_CAL               0x0080
#define BATTMON3_CONTROL_ENTER_CAL              0x0081
#define BATTMON3_CONTROL_NEW_BATTERY            0xA613
 
#define BATTMON3_DF_CC_GAIN                     0x4000
#define BATTMON3_DF_CC_DELTA                    0x4004
#define BATTMON3_DF_CC_OFFSET                   0x4008
#define BATTMON3_DF_BOARD_OFFSET                0x400C
#define BATTMON3_DF_INT_TEMP_OFFSET             0x400D
#define BATTMON3_DF_EXT_TEMP_OFFSET             0x400E
#define BATTMON3_DF_PACK_V_OFFSET               0x400F
#define BATTMON3_DF_OPERATION_CONFIG_A          0x41B1
#define BATTMON3_DF_FULL_UNSEAL_STEP_1          0x41D0
#define BATTMON3_DF_CELL_DESIGN_CAPACITY        0x41FE
 
 // battmon3_reg
 
#define BATTMON3_CHEM_ID                        0x0606
 
#define BATTMON3_SEAL_CODES_DEFAULT             0x04143672ul
 
#define BATTMON3_STATUS_GA_BIT_MASK             0x0001
#define BATTMON3_STATUS_G_DONE_BIT_MASK         0x0040
#define BATTMON3_STATUS_INIT_COMP_BIT_MASK      0x0080
#define BATTMON3_STATUS_CCA_BIT_MASK            0x0400
#define BATTMON3_STATUS_BCA_BIT_MASK            0x0800
#define BATTMON3_STATUS_CAL_MODE_BIT_MASK       0x1000
#define BATTMON3_STATUS_FLASHF_BIT_MASK         0x8000
 
#define BATTMON3_OP_CONFIG_A_TEMPS_BIT_MASK     0x80
#define BATTMON3_OP_CONFIG_A_EXTVCELL_BIT_MASK  0x40
#define BATTMON3_OP_CONFIG_A_WRTEMP_BIT_MASK    0x20
#define BATTMON3_OP_CONFIG_A_LF_EN_BIT_MASK     0x10
#define BATTMON3_OP_CONFIG_A_GNDSEL_BIT_MASK    0x04
#define BATTMON3_OP_CONFIG_A_GMSEL_BIT_MASK     0x03
 
#define BATTMON3_DEVICE_ADDRESS                 0x55
 
 // battmon3_set
 
#define BATTMON3_MAP_MIKROBUS( cfg, mikrobus ) \
    cfg.scl = MIKROBUS( mikrobus, MIKROBUS_SCL ); \
    cfg.sda = MIKROBUS( mikrobus, MIKROBUS_SDA ); \
    cfg.en = MIKROBUS( mikrobus, MIKROBUS_PWM ); \
    cfg.alr = MIKROBUS( mikrobus, MIKROBUS_INT )
 
 // battmon3_map
 // battmon3
 
typedef struct
{
    // Output pins
    digital_out_t en;               
    // Input pins
    digital_in_t  alr;              
    // Modules
    i2c_master_t  i2c;              
    // I2C slave address
    uint8_t slave_address;          
    uint8_t security_mode;          
    bool    enabled;                
} battmon3_t;
 
typedef struct
{
    pin_name_t  scl;                
    pin_name_t  sda;                
    pin_name_t  en;                 
    pin_name_t  alr;                
    uint32_t  i2c_speed;            
    uint8_t   i2c_address;          
} battmon3_cfg_t;
 
typedef enum
{
    BATTMON3_OK = 0,
    BATTMON3_ERROR = -1
 
} battmon3_return_value_t;
 
typedef enum 
{
    BATTMON3_SECURITY_MODE_UNKNOWN = 0x00,
    BATTMON3_SECURITY_MODE_FULL_ACCESS = 0x01, 
    BATTMON3_SECURITY_MODE_UNSEALED = 0x02, 
    BATTMON3_SECURITY_MODE_SEALED = 0x03 
    
} battmon3_security_mode_t;
 
typedef enum 
{
    BATTMON3_GAUGE_MODE_ACCUMULATOR = 0x00,
    BATTMON3_GAUGE_MODE_SOH = 0x01, // for LiMnO2
    BATTMON3_GAUGE_MODE_EOS = 0x02, // for LiSOCl2
    BATTMON3_GAUGE_MODE_UNKNOWN = 0x03
    
} battmon3_gauge_mode_t;
 
void battmon3_cfg_setup ( battmon3_cfg_t *cfg );
 
err_t battmon3_init ( battmon3_t *ctx, battmon3_cfg_t *cfg );
 
err_t battmon3_default_cfg ( battmon3_t *ctx );
 
err_t battmon3_generic_write ( battmon3_t *ctx, uint8_t reg, uint8_t *tx_buf, uint8_t tx_len );
 
err_t battmon3_generic_read ( battmon3_t *ctx, uint8_t reg, uint8_t *rx_buf, uint8_t rx_len );
 
err_t battmon3_write_two_bytes ( battmon3_t *ctx, uint8_t reg, uint16_t data_in );
 
err_t battmon3_read_two_bytes ( battmon3_t *ctx, uint8_t reg, uint16_t *data_out );
 
err_t battmon3_write_control ( battmon3_t *ctx, uint16_t control );
 
err_t battmon3_read_control ( battmon3_t *ctx, uint16_t control, uint16_t *data_out );
 
err_t battmon3_write_data_flash ( battmon3_t *ctx, uint16_t address, uint8_t *tx_buf, uint8_t tx_len );
 
err_t battmon3_read_data_flash ( battmon3_t *ctx, uint16_t address, uint8_t *rx_buf, uint8_t rx_len );
 
err_t battmon3_check_communication ( battmon3_t *ctx );
 
err_t battmon3_read_status ( battmon3_t *ctx, uint16_t *status );
 
err_t battmon3_wait_for_status ( battmon3_t *ctx, uint16_t mask, uint16_t status );
 
void battmon3_set_en_pin_high ( battmon3_t *ctx );
 
void battmon3_set_en_pin_low ( battmon3_t *ctx );
 
uint8_t battmon3_get_alert_pin ( battmon3_t *ctx );
 
err_t battmon3_start_gauge ( battmon3_t *ctx );
 
err_t battmon3_stop_gauge ( battmon3_t *ctx );
 
err_t battmon3_disable_gauge ( battmon3_t *ctx );
 
err_t battmon3_set_gauge_mode ( battmon3_t *ctx, uint8_t gauge_mode );
 
err_t battmon3_reset ( battmon3_t *ctx );
 
err_t battmon3_read_security_mode ( battmon3_t *ctx );
 
err_t battmon3_set_security_mode ( battmon3_t *ctx, uint8_t security_mode );
 
err_t battmon3_new_battery ( battmon3_t *ctx, uint16_t des_capacity );
 
err_t battmon3_set_design_capacity ( battmon3_t *ctx, uint16_t des_capacity );
 
err_t battmon3_read_design_capacity ( battmon3_t *ctx, uint16_t *des_capacity );
 
err_t battmon3_read_used_capacity ( battmon3_t *ctx, float *used_capacity );
 
err_t battmon3_read_remaining_capacity ( battmon3_t *ctx, float *rem_capacity );
 
err_t battmon3_read_remaining_percentage ( battmon3_t *ctx, float *rem_percentage );
 
err_t battmon3_use_internal_temperature ( battmon3_t *ctx );
 
err_t battmon3_use_external_temperature ( battmon3_t *ctx );
 
err_t battmon3_read_temperature ( battmon3_t *ctx, float *temperature );
 
err_t battmon3_read_internal_temperature ( battmon3_t *ctx, float *temperature );
 
err_t battmon3_read_voltage ( battmon3_t *ctx, uint16_t *voltage );
 
err_t battmon3_read_current ( battmon3_t *ctx, int16_t *current );
 
err_t battmon3_read_scaled_r ( battmon3_t *ctx, uint16_t *scaled_r );
 
err_t battmon3_read_measured_z ( battmon3_t *ctx, uint16_t *measured_z );
 
err_t battmon3_read_state_of_health ( battmon3_t *ctx, uint8_t *state_of_health );
 
err_t battmon3_read_battery_status ( battmon3_t *ctx, uint8_t *batt_status );
 
err_t battmon3_read_battery_alert ( battmon3_t *ctx, uint8_t *batt_alert );
 
err_t battmon3_enter_calibration_mode ( battmon3_t *ctx );
 
err_t battmon3_exit_calibration_mode ( battmon3_t *ctx );
 
err_t battmon3_read_raw_calibration_data ( battmon3_t *ctx, uint8_t reg, uint16_t *cal_data );
 
err_t battmon3_perform_cc_offset ( battmon3_t *ctx );
 
err_t battmon3_perform_board_offset ( battmon3_t *ctx );
 
err_t battmon3_calibrate_voltage ( battmon3_t *ctx, uint16_t voltage );
 
err_t battmon3_calibrate_current ( battmon3_t *ctx, int16_t current );
 
err_t battmon3_calibrate_temperature ( battmon3_t *ctx, float temperature );
 
#ifdef __cplusplus
}
#endif
#endif // BATTMON3_H
 
 // battmon3
 
// ------------------------------------------------------------------------ END