battmon3  2.0.0.0
battmon3.h
Go to the documentation of this file.
1 /****************************************************************************
2 ** Copyright (C) 2020 MikroElektronika d.o.o.
3 ** Contact: https://www.mikroe.com/contact
4 **
5 ** Permission is hereby granted, free of charge, to any person obtaining a copy
6 ** of this software and associated documentation files (the "Software"), to deal
7 ** in the Software without restriction, including without limitation the rights
8 ** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 ** copies of the Software, and to permit persons to whom the Software is
10 ** furnished to do so, subject to the following conditions:
11 ** The above copyright notice and this permission notice shall be
12 ** included in all copies or substantial portions of the Software.
13 **
14 ** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15 ** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
16 ** OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17 ** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
18 ** DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
19 ** OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
20 ** USE OR OTHER DEALINGS IN THE SOFTWARE.
21 ****************************************************************************/
22 
28 #ifndef BATTMON3_H
29 #define BATTMON3_H
30 
31 #ifdef __cplusplus
32 extern "C"{
33 #endif
34 
35 #include "mikrosdk_version.h"
36 
37 #ifdef __GNUC__
38 #if mikroSDK_GET_VERSION < 20800ul
39 #include "rcu_delays.h"
40 #else
41 #include "delays.h"
42 #endif
43 #endif
44 
45 #include "drv_digital_out.h"
46 #include "drv_digital_in.h"
47 #include "drv_i2c_master.h"
48 
69 #define BATTMON3_REG_CONTROL 0x00
70 #define BATTMON3_REG_ACCUMULATED_CAPACITY 0x02
71 #define BATTMON3_REG_TEMPERATURE 0x06
72 #define BATTMON3_REG_VOLTAGE 0x08
73 #define BATTMON3_REG_BATTERY_STATUS 0x0A
74 #define BATTMON3_REG_BATTERY_ALERT 0x0B
75 #define BATTMON3_REG_CURRENT 0x0C
76 #define BATTMON3_REG_SCALED_R 0x16
77 #define BATTMON3_REG_MEASURED_Z 0x22
78 #define BATTMON3_REG_INTERNAL_TEMPERATURE 0x28
79 #define BATTMON3_REG_STATE_OF_HEALTH 0x2E
80 #define BATTMON3_REG_DESIGN_CAPACITY 0x3C
81 #define BATTMON3_REG_MAC 0x3E
82 #define BATTMON3_REG_MAC_DATA 0x40
83 #define BATTMON3_REG_MAC_DATA_SUM 0x60
84 #define BATTMON3_REG_MAC_DATA_LEN 0x61
85 #define BATTMON3_REG_MAC_DATA_CONTROL 0x62
86 #define BATTMON3_REG_CAL_COUNT 0x79
87 #define BATTMON3_REG_CAL_CURRENT 0x7A
88 #define BATTMON3_REG_CAL_VOLTAGE 0x7C
89 #define BATTMON3_REG_CAL_TEMPERATURE 0x7E
90 
95 #define BATTMON3_CONTROL_STATUS 0x0000
96 #define BATTMON3_CONTROL_DEVICE_TYPE 0x0001
97 #define BATTMON3_CONTROL_FW_VERSION 0x0002
98 #define BATTMON3_CONTROL_HW_VERSION 0x0003
99 #define BATTMON3_CONTROL_STATIC_CHEM_CHKSUM 0x0005
100 #define BATTMON3_CONTROL_CHEM_ID 0x0006
101 #define BATTMON3_CONTROL_PREV_MACWRITE 0x0007
102 #define BATTMON3_CONTROL_BOARD_OFFSET 0x0009
103 #define BATTMON3_CONTROL_CC_OFFSET 0x000A
104 #define BATTMON3_CONTROL_CC_OFFSET_SAVE 0x000B
105 #define BATTMON3_CONTROL_DF_VERSION 0x000C
106 #define BATTMON3_CONTROL_GAUGE_START 0x0011
107 #define BATTMON3_CONTROL_GAUGE_STOP 0x0012
108 #define BATTMON3_CONTROL_SEALED 0x0020
109 #define BATTMON3_CONTROL_CAL_ENABLE 0x002D
110 #define BATTMON3_CONTROL_LT_ENABLE 0x002E
111 #define BATTMON3_CONTROL_RESET 0x0041
112 #define BATTMON3_CONTROL_EXIT_CAL 0x0080
113 #define BATTMON3_CONTROL_ENTER_CAL 0x0081
114 #define BATTMON3_CONTROL_NEW_BATTERY 0xA613
115 
121 #define BATTMON3_DF_CC_GAIN 0x4000
122 #define BATTMON3_DF_CC_DELTA 0x4004
123 #define BATTMON3_DF_CC_OFFSET 0x4008
124 #define BATTMON3_DF_BOARD_OFFSET 0x400C
125 #define BATTMON3_DF_INT_TEMP_OFFSET 0x400D
126 #define BATTMON3_DF_EXT_TEMP_OFFSET 0x400E
127 #define BATTMON3_DF_PACK_V_OFFSET 0x400F
128 #define BATTMON3_DF_OPERATION_CONFIG_A 0x41B1
129 #define BATTMON3_DF_FULL_UNSEAL_STEP_1 0x41D0
130 #define BATTMON3_DF_CELL_DESIGN_CAPACITY 0x41FE
131  // battmon3_reg
133 
148 #define BATTMON3_CHEM_ID 0x0606
149 
154 #define BATTMON3_SEAL_CODES_DEFAULT 0x04143672ul
155 
160 #define BATTMON3_STATUS_GA_BIT_MASK 0x0001
161 #define BATTMON3_STATUS_G_DONE_BIT_MASK 0x0040
162 #define BATTMON3_STATUS_INIT_COMP_BIT_MASK 0x0080
163 #define BATTMON3_STATUS_CCA_BIT_MASK 0x0400
164 #define BATTMON3_STATUS_BCA_BIT_MASK 0x0800
165 #define BATTMON3_STATUS_CAL_MODE_BIT_MASK 0x1000
166 #define BATTMON3_STATUS_FLASHF_BIT_MASK 0x8000
167 
172 #define BATTMON3_OP_CONFIG_A_TEMPS_BIT_MASK 0x80
173 #define BATTMON3_OP_CONFIG_A_EXTVCELL_BIT_MASK 0x40
174 #define BATTMON3_OP_CONFIG_A_WRTEMP_BIT_MASK 0x20
175 #define BATTMON3_OP_CONFIG_A_LF_EN_BIT_MASK 0x10
176 #define BATTMON3_OP_CONFIG_A_GNDSEL_BIT_MASK 0x04
177 #define BATTMON3_OP_CONFIG_A_GMSEL_BIT_MASK 0x03
178 
184 #define BATTMON3_DEVICE_ADDRESS 0x55
185  // battmon3_set
187 
202 #define BATTMON3_MAP_MIKROBUS( cfg, mikrobus ) \
203  cfg.scl = MIKROBUS( mikrobus, MIKROBUS_SCL ); \
204  cfg.sda = MIKROBUS( mikrobus, MIKROBUS_SDA ); \
205  cfg.en = MIKROBUS( mikrobus, MIKROBUS_PWM ); \
206  cfg.alr = MIKROBUS( mikrobus, MIKROBUS_INT )
207  // battmon3_map // battmon3
210 
215 typedef struct
216 {
217  // Output pins
218  digital_out_t en;
220  // Input pins
221  digital_in_t alr;
223  // Modules
224  i2c_master_t i2c;
226  // I2C slave address
227  uint8_t slave_address;
229  uint8_t security_mode;
231  bool enabled;
233 } battmon3_t;
234 
239 typedef struct
240 {
241  pin_name_t scl;
242  pin_name_t sda;
244  pin_name_t en;
245  pin_name_t alr;
247  uint32_t i2c_speed;
248  uint8_t i2c_address;
251 
256 typedef enum
257 {
259  BATTMON3_ERROR = -1
260 
262 
267 typedef enum
268 {
273 
275 
280 typedef enum
281 {
283  BATTMON3_GAUGE_MODE_SOH = 0x01, // for LiMnO2
284  BATTMON3_GAUGE_MODE_EOS = 0x02, // for LiSOCl2
286 
288 
305 
320 
334 
349 err_t battmon3_generic_write ( battmon3_t *ctx, uint8_t reg, uint8_t *tx_buf, uint8_t tx_len );
350 
365 err_t battmon3_generic_read ( battmon3_t *ctx, uint8_t reg, uint8_t *rx_buf, uint8_t rx_len );
366 
380 err_t battmon3_write_two_bytes ( battmon3_t *ctx, uint8_t reg, uint16_t data_in );
381 
395 err_t battmon3_read_two_bytes ( battmon3_t *ctx, uint8_t reg, uint16_t *data_out );
396 
408 err_t battmon3_write_control ( battmon3_t *ctx, uint16_t control );
409 
422 err_t battmon3_read_control ( battmon3_t *ctx, uint16_t control, uint16_t *data_out );
423 
438 err_t battmon3_write_data_flash ( battmon3_t *ctx, uint16_t address, uint8_t *tx_buf, uint8_t tx_len );
439 
454 err_t battmon3_read_data_flash ( battmon3_t *ctx, uint16_t address, uint8_t *rx_buf, uint8_t rx_len );
455 
467 
479 err_t battmon3_read_status ( battmon3_t *ctx, uint16_t *status );
480 
493 err_t battmon3_wait_for_status ( battmon3_t *ctx, uint16_t mask, uint16_t status );
494 
504 
514 
524 
538 
553 
566 
580 err_t battmon3_set_gauge_mode ( battmon3_t *ctx, uint8_t gauge_mode );
581 
592 err_t battmon3_reset ( battmon3_t *ctx );
593 
605 
619 err_t battmon3_set_security_mode ( battmon3_t *ctx, uint8_t security_mode );
620 
632 err_t battmon3_new_battery ( battmon3_t *ctx, uint16_t des_capacity );
633 
645 err_t battmon3_set_design_capacity ( battmon3_t *ctx, uint16_t des_capacity );
646 
658 err_t battmon3_read_design_capacity ( battmon3_t *ctx, uint16_t *des_capacity );
659 
671 err_t battmon3_read_used_capacity ( battmon3_t *ctx, float *used_capacity );
672 
685 err_t battmon3_read_remaining_capacity ( battmon3_t *ctx, float *rem_capacity );
686 
699 err_t battmon3_read_remaining_percentage ( battmon3_t *ctx, float *rem_percentage );
700 
712 
724 
736 err_t battmon3_read_temperature ( battmon3_t *ctx, float *temperature );
737 
749 err_t battmon3_read_internal_temperature ( battmon3_t *ctx, float *temperature );
750 
762 err_t battmon3_read_voltage ( battmon3_t *ctx, uint16_t *voltage );
763 
775 err_t battmon3_read_current ( battmon3_t *ctx, int16_t *current );
776 
789 err_t battmon3_read_scaled_r ( battmon3_t *ctx, uint16_t *scaled_r );
790 
803 err_t battmon3_read_measured_z ( battmon3_t *ctx, uint16_t *measured_z );
804 
816 err_t battmon3_read_state_of_health ( battmon3_t *ctx, uint8_t *state_of_health );
817 
829 err_t battmon3_read_battery_status ( battmon3_t *ctx, uint8_t *batt_status );
830 
842 err_t battmon3_read_battery_alert ( battmon3_t *ctx, uint8_t *batt_alert );
843 
855 
867 
880 err_t battmon3_read_raw_calibration_data ( battmon3_t *ctx, uint8_t reg, uint16_t *cal_data );
881 
893 
905 
917 err_t battmon3_calibrate_voltage ( battmon3_t *ctx, uint16_t voltage );
918 
930 err_t battmon3_calibrate_current ( battmon3_t *ctx, int16_t current );
931 
945 err_t battmon3_calibrate_temperature ( battmon3_t *ctx, float temperature );
946 
947 #ifdef __cplusplus
948 }
949 #endif
950 #endif // BATTMON3_H
951  // battmon3
953 
954 // ------------------------------------------------------------------------ END
BATTMON3_GAUGE_MODE_EOS
@ BATTMON3_GAUGE_MODE_EOS
Definition: battmon3.h:284
battmon3_set_en_pin_low
void battmon3_set_en_pin_low(battmon3_t *ctx)
BATT-MON 3 set en pin low function.
battmon3_read_internal_temperature
err_t battmon3_read_internal_temperature(battmon3_t *ctx, float *temperature)
BATT-MON 3 read internal temperature function.
battmon3_t::enabled
bool enabled
Definition: battmon3.h:231
battmon3_read_control
err_t battmon3_read_control(battmon3_t *ctx, uint16_t control, uint16_t *data_out)
BATT-MON 3 read control function.
battmon3_check_communication
err_t battmon3_check_communication(battmon3_t *ctx)
BATT-MON 3 check communication function.
battmon3_cfg_t
BATT-MON 3 Click configuration object.
Definition: battmon3.h:240
battmon3_read_raw_calibration_data
err_t battmon3_read_raw_calibration_data(battmon3_t *ctx, uint8_t reg, uint16_t *cal_data)
BATT-MON 3 read raw calibration data function.
battmon3_calibrate_temperature
err_t battmon3_calibrate_temperature(battmon3_t *ctx, float temperature)
BATT-MON 3 calibrate temperature function.
battmon3_start_gauge
err_t battmon3_start_gauge(battmon3_t *ctx)
BATT-MON 3 start gauge function.
battmon3_t::en
digital_out_t en
Definition: battmon3.h:218
battmon3_set_en_pin_high
void battmon3_set_en_pin_high(battmon3_t *ctx)
BATT-MON 3 set en pin high function.
battmon3_read_battery_alert
err_t battmon3_read_battery_alert(battmon3_t *ctx, uint8_t *batt_alert)
BATT-MON 3 read battery alert function.
BATTMON3_SECURITY_MODE_UNKNOWN
@ BATTMON3_SECURITY_MODE_UNKNOWN
Definition: battmon3.h:269
battmon3_disable_gauge
err_t battmon3_disable_gauge(battmon3_t *ctx)
BATT-MON 3 disable gauge function.
battmon3_cfg_t::i2c_address
uint8_t i2c_address
Definition: battmon3.h:248
battmon3_read_measured_z
err_t battmon3_read_measured_z(battmon3_t *ctx, uint16_t *measured_z)
BATT-MON 3 read measured Z function.
battmon3_return_value_t
battmon3_return_value_t
BATT-MON 3 Click return value data.
Definition: battmon3.h:257
battmon3_get_alert_pin
uint8_t battmon3_get_alert_pin(battmon3_t *ctx)
BATT-MON 3 get alert pin function.
battmon3_security_mode_t
battmon3_security_mode_t
BATT-MON 3 the security mode of the BQ35100 chip.
Definition: battmon3.h:268
battmon3_read_two_bytes
err_t battmon3_read_two_bytes(battmon3_t *ctx, uint8_t reg, uint16_t *data_out)
BATT-MON 3 read two bytes function.
battmon3_read_data_flash
err_t battmon3_read_data_flash(battmon3_t *ctx, uint16_t address, uint8_t *rx_buf, uint8_t rx_len)
BATT-MON 3 read data flash function.
battmon3_write_two_bytes
err_t battmon3_write_two_bytes(battmon3_t *ctx, uint8_t reg, uint16_t data_in)
BATT-MON 3 write two bytes function.
battmon3_exit_calibration_mode
err_t battmon3_exit_calibration_mode(battmon3_t *ctx)
BATT-MON 3 exit calibration mode function.
battmon3_cfg_t::scl
pin_name_t scl
Definition: battmon3.h:241
battmon3_write_data_flash
err_t battmon3_write_data_flash(battmon3_t *ctx, uint16_t address, uint8_t *tx_buf, uint8_t tx_len)
BATT-MON 3 write data flash function.
battmon3_t::alr
digital_in_t alr
Definition: battmon3.h:221
battmon3_perform_board_offset
err_t battmon3_perform_board_offset(battmon3_t *ctx)
BATT-MON 3 perform board offset function.
battmon3_calibrate_voltage
err_t battmon3_calibrate_voltage(battmon3_t *ctx, uint16_t voltage)
BATT-MON 3 calibrate voltage function.
battmon3_read_state_of_health
err_t battmon3_read_state_of_health(battmon3_t *ctx, uint8_t *state_of_health)
BATT-MON 3 read state of health function.
battmon3_cfg_t::sda
pin_name_t sda
Definition: battmon3.h:242
BATTMON3_OK
@ BATTMON3_OK
Definition: battmon3.h:258
battmon3_read_security_mode
err_t battmon3_read_security_mode(battmon3_t *ctx)
BATT-MON 3 read security mode function.
battmon3_cfg_setup
void battmon3_cfg_setup(battmon3_cfg_t *cfg)
BATT-MON 3 configuration object setup function.
BATTMON3_SECURITY_MODE_FULL_ACCESS
@ BATTMON3_SECURITY_MODE_FULL_ACCESS
Allows writes to all of memory.
Definition: battmon3.h:270
battmon3_cfg_t::i2c_speed
uint32_t i2c_speed
Definition: battmon3.h:247
battmon3_enter_calibration_mode
err_t battmon3_enter_calibration_mode(battmon3_t *ctx)
BATT-MON 3 enter calibration mode function.
battmon3_read_remaining_percentage
err_t battmon3_read_remaining_percentage(battmon3_t *ctx, float *rem_percentage)
BATT-MON 3 read remaining percentage function.
battmon3_t::slave_address
uint8_t slave_address
Definition: battmon3.h:227
battmon3_new_battery
err_t battmon3_new_battery(battmon3_t *ctx, uint16_t des_capacity)
BATT-MON 3 new battery function.
BATTMON3_SECURITY_MODE_SEALED
@ BATTMON3_SECURITY_MODE_SEALED
Normal operating mode, prevents accidental writes.
Definition: battmon3.h:272
battmon3_default_cfg
err_t battmon3_default_cfg(battmon3_t *ctx)
BATT-MON 3 default configuration function.
battmon3_read_current
err_t battmon3_read_current(battmon3_t *ctx, int16_t *current)
BATT-MON 3 read current function.
battmon3_read_temperature
err_t battmon3_read_temperature(battmon3_t *ctx, float *temperature)
BATT-MON 3 read temperature function.
battmon3_wait_for_status
err_t battmon3_wait_for_status(battmon3_t *ctx, uint16_t mask, uint16_t status)
BATT-MON 3 wait for status function.
battmon3_read_scaled_r
err_t battmon3_read_scaled_r(battmon3_t *ctx, uint16_t *scaled_r)
BATT-MON 3 read scaled R function.
battmon3_calibrate_current
err_t battmon3_calibrate_current(battmon3_t *ctx, int16_t current)
BATT-MON 3 calibrate current function.
battmon3_read_used_capacity
err_t battmon3_read_used_capacity(battmon3_t *ctx, float *used_capacity)
BATT-MON 3 read used capacity function.
BATTMON3_SECURITY_MODE_UNSEALED
@ BATTMON3_SECURITY_MODE_UNSEALED
Allows writes to all of memory apart from the security codes area.
Definition: battmon3.h:271
battmon3_t::security_mode
uint8_t security_mode
Definition: battmon3.h:229
battmon3_generic_write
err_t battmon3_generic_write(battmon3_t *ctx, uint8_t reg, uint8_t *tx_buf, uint8_t tx_len)
BATT-MON 3 I2C writing function.
battmon3_init
err_t battmon3_init(battmon3_t *ctx, battmon3_cfg_t *cfg)
BATT-MON 3 initialization function.
BATTMON3_ERROR
@ BATTMON3_ERROR
Definition: battmon3.h:259
battmon3_reset
err_t battmon3_reset(battmon3_t *ctx)
BATT-MON 3 reset function.
battmon3_generic_read
err_t battmon3_generic_read(battmon3_t *ctx, uint8_t reg, uint8_t *rx_buf, uint8_t rx_len)
BATT-MON 3 I2C reading function.
battmon3_read_design_capacity
err_t battmon3_read_design_capacity(battmon3_t *ctx, uint16_t *des_capacity)
BATT-MON 3 read design capacity function.
BATTMON3_GAUGE_MODE_ACCUMULATOR
@ BATTMON3_GAUGE_MODE_ACCUMULATOR
Definition: battmon3.h:282
battmon3_read_remaining_capacity
err_t battmon3_read_remaining_capacity(battmon3_t *ctx, float *rem_capacity)
BATT-MON 3 read remaining capacity function.
battmon3_set_gauge_mode
err_t battmon3_set_gauge_mode(battmon3_t *ctx, uint8_t gauge_mode)
BATT-MON 3 set gauge mode function.
battmon3_cfg_t::alr
pin_name_t alr
Definition: battmon3.h:245
battmon3_t
BATT-MON 3 Click context object.
Definition: battmon3.h:216
battmon3_use_external_temperature
err_t battmon3_use_external_temperature(battmon3_t *ctx)
BATT-MON 3 use external temperature function.
battmon3_t::i2c
i2c_master_t i2c
Definition: battmon3.h:224
battmon3_read_voltage
err_t battmon3_read_voltage(battmon3_t *ctx, uint16_t *voltage)
BATT-MON 3 read voltage function.
BATTMON3_GAUGE_MODE_SOH
@ BATTMON3_GAUGE_MODE_SOH
Definition: battmon3.h:283
battmon3_set_design_capacity
err_t battmon3_set_design_capacity(battmon3_t *ctx, uint16_t des_capacity)
BATT-MON 3 set design capacity function.
BATTMON3_GAUGE_MODE_UNKNOWN
@ BATTMON3_GAUGE_MODE_UNKNOWN
Definition: battmon3.h:285
battmon3_use_internal_temperature
err_t battmon3_use_internal_temperature(battmon3_t *ctx)
BATT-MON 3 use internal temperature function.
battmon3_perform_cc_offset
err_t battmon3_perform_cc_offset(battmon3_t *ctx)
BATT-MON 3 perform CC offset function.
battmon3_cfg_t::en
pin_name_t en
Definition: battmon3.h:244
battmon3_set_security_mode
err_t battmon3_set_security_mode(battmon3_t *ctx, uint8_t security_mode)
BATT-MON 3 set security mode function.
battmon3_gauge_mode_t
battmon3_gauge_mode_t
BATT-MON 3 the gauge mode of the BQ35100 chip.
Definition: battmon3.h:281
battmon3_write_control
err_t battmon3_write_control(battmon3_t *ctx, uint16_t control)
BATT-MON 3 write control function.
battmon3_read_status
err_t battmon3_read_status(battmon3_t *ctx, uint16_t *status)
BATT-MON 3 read status function.
battmon3_stop_gauge
err_t battmon3_stop_gauge(battmon3_t *ctx)
BATT-MON 3 stop gauge function.
battmon3_read_battery_status
err_t battmon3_read_battery_status(battmon3_t *ctx, uint8_t *batt_status)
BATT-MON 3 read battery status function.