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 "drv_digital_out.h"
36 #include "drv_digital_in.h"
37 #include "drv_i2c_master.h"
38 
59 #define BATTMON3_REG_CONTROL 0x00
60 #define BATTMON3_REG_ACCUMULATED_CAPACITY 0x02
61 #define BATTMON3_REG_TEMPERATURE 0x06
62 #define BATTMON3_REG_VOLTAGE 0x08
63 #define BATTMON3_REG_BATTERY_STATUS 0x0A
64 #define BATTMON3_REG_BATTERY_ALERT 0x0B
65 #define BATTMON3_REG_CURRENT 0x0C
66 #define BATTMON3_REG_SCALED_R 0x16
67 #define BATTMON3_REG_MEASURED_Z 0x22
68 #define BATTMON3_REG_INTERNAL_TEMPERATURE 0x28
69 #define BATTMON3_REG_STATE_OF_HEALTH 0x2E
70 #define BATTMON3_REG_DESIGN_CAPACITY 0x3C
71 #define BATTMON3_REG_MAC 0x3E
72 #define BATTMON3_REG_MAC_DATA 0x40
73 #define BATTMON3_REG_MAC_DATA_SUM 0x60
74 #define BATTMON3_REG_MAC_DATA_LEN 0x61
75 #define BATTMON3_REG_MAC_DATA_CONTROL 0x62
76 #define BATTMON3_REG_CAL_COUNT 0x79
77 #define BATTMON3_REG_CAL_CURRENT 0x7A
78 #define BATTMON3_REG_CAL_VOLTAGE 0x7C
79 #define BATTMON3_REG_CAL_TEMPERATURE 0x7E
80 
85 #define BATTMON3_CONTROL_STATUS 0x0000
86 #define BATTMON3_CONTROL_DEVICE_TYPE 0x0001
87 #define BATTMON3_CONTROL_FW_VERSION 0x0002
88 #define BATTMON3_CONTROL_HW_VERSION 0x0003
89 #define BATTMON3_CONTROL_STATIC_CHEM_CHKSUM 0x0005
90 #define BATTMON3_CONTROL_CHEM_ID 0x0006
91 #define BATTMON3_CONTROL_PREV_MACWRITE 0x0007
92 #define BATTMON3_CONTROL_BOARD_OFFSET 0x0009
93 #define BATTMON3_CONTROL_CC_OFFSET 0x000A
94 #define BATTMON3_CONTROL_CC_OFFSET_SAVE 0x000B
95 #define BATTMON3_CONTROL_DF_VERSION 0x000C
96 #define BATTMON3_CONTROL_GAUGE_START 0x0011
97 #define BATTMON3_CONTROL_GAUGE_STOP 0x0012
98 #define BATTMON3_CONTROL_SEALED 0x0020
99 #define BATTMON3_CONTROL_CAL_ENABLE 0x002D
100 #define BATTMON3_CONTROL_LT_ENABLE 0x002E
101 #define BATTMON3_CONTROL_RESET 0x0041
102 #define BATTMON3_CONTROL_EXIT_CAL 0x0080
103 #define BATTMON3_CONTROL_ENTER_CAL 0x0081
104 #define BATTMON3_CONTROL_NEW_BATTERY 0xA613
105 
111 #define BATTMON3_DF_CC_GAIN 0x4000
112 #define BATTMON3_DF_CC_DELTA 0x4004
113 #define BATTMON3_DF_CC_OFFSET 0x4008
114 #define BATTMON3_DF_BOARD_OFFSET 0x400C
115 #define BATTMON3_DF_INT_TEMP_OFFSET 0x400D
116 #define BATTMON3_DF_EXT_TEMP_OFFSET 0x400E
117 #define BATTMON3_DF_PACK_V_OFFSET 0x400F
118 #define BATTMON3_DF_OPERATION_CONFIG_A 0x41B1
119 #define BATTMON3_DF_FULL_UNSEAL_STEP_1 0x41D0
120 #define BATTMON3_DF_CELL_DESIGN_CAPACITY 0x41FE
121  // battmon3_reg
123 
138 #define BATTMON3_CHEM_ID 0x0606
139 
144 #define BATTMON3_SEAL_CODES_DEFAULT 0x04143672ul
145 
150 #define BATTMON3_STATUS_GA_BIT_MASK 0x0001
151 #define BATTMON3_STATUS_G_DONE_BIT_MASK 0x0040
152 #define BATTMON3_STATUS_INIT_COMP_BIT_MASK 0x0080
153 #define BATTMON3_STATUS_CCA_BIT_MASK 0x0400
154 #define BATTMON3_STATUS_BCA_BIT_MASK 0x0800
155 #define BATTMON3_STATUS_CAL_MODE_BIT_MASK 0x1000
156 #define BATTMON3_STATUS_FLASHF_BIT_MASK 0x8000
157 
162 #define BATTMON3_OP_CONFIG_A_TEMPS_BIT_MASK 0x80
163 #define BATTMON3_OP_CONFIG_A_EXTVCELL_BIT_MASK 0x40
164 #define BATTMON3_OP_CONFIG_A_WRTEMP_BIT_MASK 0x20
165 #define BATTMON3_OP_CONFIG_A_LF_EN_BIT_MASK 0x10
166 #define BATTMON3_OP_CONFIG_A_GNDSEL_BIT_MASK 0x04
167 #define BATTMON3_OP_CONFIG_A_GMSEL_BIT_MASK 0x03
168 
174 #define BATTMON3_DEVICE_ADDRESS 0x55
175  // battmon3_set
177 
192 #define BATTMON3_MAP_MIKROBUS( cfg, mikrobus ) \
193  cfg.scl = MIKROBUS( mikrobus, MIKROBUS_SCL ); \
194  cfg.sda = MIKROBUS( mikrobus, MIKROBUS_SDA ); \
195  cfg.en = MIKROBUS( mikrobus, MIKROBUS_PWM ); \
196  cfg.alr = MIKROBUS( mikrobus, MIKROBUS_INT )
197  // battmon3_map // battmon3
200 
205 typedef struct
206 {
207  // Output pins
208  digital_out_t en;
210  // Input pins
211  digital_in_t alr;
213  // Modules
214  i2c_master_t i2c;
216  // I2C slave address
217  uint8_t slave_address;
219  uint8_t security_mode;
221  bool enabled;
223 } battmon3_t;
224 
229 typedef struct
230 {
231  pin_name_t scl;
232  pin_name_t sda;
234  pin_name_t en;
235  pin_name_t alr;
237  uint32_t i2c_speed;
238  uint8_t i2c_address;
241 
246 typedef enum
247 {
249  BATTMON3_ERROR = -1
250 
252 
257 typedef enum
258 {
263 
265 
270 typedef enum
271 {
273  BATTMON3_GAUGE_MODE_SOH = 0x01, // for LiMnO2
274  BATTMON3_GAUGE_MODE_EOS = 0x02, // for LiSOCl2
276 
278 
295 
310 
324 
339 err_t battmon3_generic_write ( battmon3_t *ctx, uint8_t reg, uint8_t *tx_buf, uint8_t tx_len );
340 
355 err_t battmon3_generic_read ( battmon3_t *ctx, uint8_t reg, uint8_t *rx_buf, uint8_t rx_len );
356 
370 err_t battmon3_write_two_bytes ( battmon3_t *ctx, uint8_t reg, uint16_t data_in );
371 
385 err_t battmon3_read_two_bytes ( battmon3_t *ctx, uint8_t reg, uint16_t *data_out );
386 
398 err_t battmon3_write_control ( battmon3_t *ctx, uint16_t control );
399 
412 err_t battmon3_read_control ( battmon3_t *ctx, uint16_t control, uint16_t *data_out );
413 
428 err_t battmon3_write_data_flash ( battmon3_t *ctx, uint16_t address, uint8_t *tx_buf, uint8_t tx_len );
429 
444 err_t battmon3_read_data_flash ( battmon3_t *ctx, uint16_t address, uint8_t *rx_buf, uint8_t rx_len );
445 
457 
469 err_t battmon3_read_status ( battmon3_t *ctx, uint16_t *status );
470 
483 err_t battmon3_wait_for_status ( battmon3_t *ctx, uint16_t mask, uint16_t status );
484 
494 
504 
514 
528 
543 
556 
570 err_t battmon3_set_gauge_mode ( battmon3_t *ctx, uint8_t gauge_mode );
571 
582 err_t battmon3_reset ( battmon3_t *ctx );
583 
595 
609 err_t battmon3_set_security_mode ( battmon3_t *ctx, uint8_t security_mode );
610 
622 err_t battmon3_new_battery ( battmon3_t *ctx, uint16_t des_capacity );
623 
635 err_t battmon3_set_design_capacity ( battmon3_t *ctx, uint16_t des_capacity );
636 
648 err_t battmon3_read_design_capacity ( battmon3_t *ctx, uint16_t *des_capacity );
649 
661 err_t battmon3_read_used_capacity ( battmon3_t *ctx, float *used_capacity );
662 
675 err_t battmon3_read_remaining_capacity ( battmon3_t *ctx, float *rem_capacity );
676 
689 err_t battmon3_read_remaining_percentage ( battmon3_t *ctx, float *rem_percentage );
690 
702 
714 
726 err_t battmon3_read_temperature ( battmon3_t *ctx, float *temperature );
727 
739 err_t battmon3_read_internal_temperature ( battmon3_t *ctx, float *temperature );
740 
752 err_t battmon3_read_voltage ( battmon3_t *ctx, uint16_t *voltage );
753 
765 err_t battmon3_read_current ( battmon3_t *ctx, int16_t *current );
766 
779 err_t battmon3_read_scaled_r ( battmon3_t *ctx, uint16_t *scaled_r );
780 
793 err_t battmon3_read_measured_z ( battmon3_t *ctx, uint16_t *measured_z );
794 
806 err_t battmon3_read_state_of_health ( battmon3_t *ctx, uint8_t *state_of_health );
807 
819 err_t battmon3_read_battery_status ( battmon3_t *ctx, uint8_t *batt_status );
820 
832 err_t battmon3_read_battery_alert ( battmon3_t *ctx, uint8_t *batt_alert );
833 
845 
857 
870 err_t battmon3_read_raw_calibration_data ( battmon3_t *ctx, uint8_t reg, uint16_t *cal_data );
871 
883 
895 
907 err_t battmon3_calibrate_voltage ( battmon3_t *ctx, uint16_t voltage );
908 
920 err_t battmon3_calibrate_current ( battmon3_t *ctx, int16_t current );
921 
935 err_t battmon3_calibrate_temperature ( battmon3_t *ctx, float temperature );
936 
937 #ifdef __cplusplus
938 }
939 #endif
940 #endif // BATTMON3_H
941  // battmon3
943 
944 // ------------------------------------------------------------------------ END
BATTMON3_GAUGE_MODE_EOS
@ BATTMON3_GAUGE_MODE_EOS
Definition: battmon3.h:274
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:221
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:230
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:208
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:259
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:238
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:247
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:258
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:231
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:211
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:232
BATTMON3_OK
@ BATTMON3_OK
Definition: battmon3.h:248
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:260
battmon3_cfg_t::i2c_speed
uint32_t i2c_speed
Definition: battmon3.h:237
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:217
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:262
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:261
battmon3_t::security_mode
uint8_t security_mode
Definition: battmon3.h:219
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:249
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:272
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:235
battmon3_t
BATT-MON 3 Click context object.
Definition: battmon3.h:206
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:214
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:273
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:275
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:234
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:271
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.