Source code for philander.stc311x_reg

# TODO: all the comments

"""Register definitions for the STC311x family battery gas gauges.
    
Definition of registers and default values for the
above-mentioned chips.
Externalized, just for clarity of the source code.
"""
__author__ = "Carl Bellgardt"
__version__ = "0.1"
__all__ = ["STC3115_Reg", "STC3117_Reg", "_STC311x_Reg", "ChipType"]

from enum import Enum, auto


[docs] class ChipType(Enum): STC3115 = auto() STC3117 = auto()
class _STC311x_Reg: def __init__(self, Param_dict): # apply config self.CONFIG_GASGAUGE_0_RSENSE = Param_dict["Gasgauge.senseResistor"] self.CONFIG_GASGAUGE_0_BATTERY_IDX = Param_dict["Gasgauge.battery_idx"] # TODO: what is this pin used for? self.CONFIG_GASGAUGE_0_GPIO_ALARM = Param_dict["Gasgauge.gpio_alarm_idx"] self.RELAX_MAX_DEFAULT = Param_dict["Gasgauge.cmonit_max"] self.SETUP_0_REG_CC_CNF = Param_dict["Gasgauge.cc_cnf"] self.SETUP_0_REG_VM_CNF = Param_dict["Gasgauge.vm_cnf"] self.SETUP_0_REG_ALARM_SOC = Param_dict["Gasgauge.alarm_soc"] self.SETUP_0_REG_ALARM_VOLTAGE = Param_dict["Gasgauge.alarm_voltage"] self.SETUP_0_REG_CURRENT_THRES = Param_dict["Gasgauge.current_thres"] self.SETUP_0_REG_CMONIT_MAX = Param_dict["Gasgauge.cmonit_max"] # Definition of registers and their content REG_MODE = 0 # Mode register # possible values of the mode register MODE_VMODE = 0x01 # 0: Mixed mode (Coulomb counter active); 1: Power saving voltage mode MODE_ALM_ENA = 0x08 # Alarm function enable MODE_GG_RUN = 0x10 # Standby / operating mode MODE_FORCE_CC = 0x20 # Forces the relaxation timer to switch to the Coulomb counter (CC) state. MODE_FORCE_VM = 0x40 # Forces the relaxation timer to switch to voltage mode (VM) state. REG_CTRL = 1 # Control and status register # possible values of the control register CTRL_IO0DATA = 0x01 # ALM pin status / ALM pin output drive CTRL_GG_RST = 0x02 # resets the conversion counter GG_RST is a self-clearing bit CTRL_GG_VM = 0x04 # Coulomb counter mode / Voltage mode active CTRL_BATFAIL = 0x08 # Battery removal (BATD high). CTRL_PORDET = 0x10 # Power on reset (POR) detection / Soft reset CTRL_ALM_SOC = 0x20 # Set with a low-SOC condition CTRL_ALM_VOLT = 0x40 # Set with a low-voltage condition CTRL_DEFAULT = CTRL_IO0DATA REG_SOC_L = 2 REG_SOC_H = 3 REG_SOC = REG_SOC_L # Battery state of charge (SOC) REG_COUNTER_L = 4 REG_COUNTER_H = 5 REG_COUNTER = REG_COUNTER_L # Number of conversions REG_CURRENT_L = 6 REG_CURRENT_H = 7 REG_CURRENT = REG_CURRENT_L # Battery current, voltage drop over sense resistor REG_VOLTAGE_L = 8 REG_VOLTAGE_H = 9 REG_VOLTAGE = REG_VOLTAGE_L # Battery voltage REG_TEMPERATURE = 10 # Temperature [C] # REG 11, 12 set in chip specific implementation REG_OCV_L = 13 REG_OCV_H = 14 REG_OCV = REG_OCV_L # OCV register REG_CC_CNF_L = 15 REG_CC_CNF_H = 16 REG_CC_CNF = REG_CC_CNF_L # Coulomb counter gas gauge configuration CC_CNF_DEFAULT = 395 # Coulomb-counter mode configuration default value REG_VM_CNF_L = 17 REG_VM_CNF_H = 18 REG_VM_CNF = REG_VM_CNF_L # Voltage gas gauge algorithm parameter VM_CNF_DEFAULT = 321 # Voltage mode configuration default value REG_ALARM_SOC = 19 # SOC alarm level [0.5%] REG_ALARM_VOLTAGE = 20 # Battery low voltage alarm level [17.6mV] REG_CURRENT_THRES = 21 # Current threshold for current monitoring REG_CMONIT_COUNT = 22 # Current monitoring counter REG_RELAX_COUNT = REG_CMONIT_COUNT REG_CMONIT_MAX = 23 # Maximum counter value for current monitoring REG_RELAX_MAX = REG_CMONIT_MAX RELAX_MAX_DEFAULT = None # set in __init__() REG_ID = 24 # Part type ID = 16 (hex) CHIP_ID = None # Expected chip ID, depends on specific chip # REG 25 - 30 set in chip specific implementation # RAM registers: Working registers for gas gauge REG_RAM0 = 32 REG_RAM1 = 33 REG_RAM2 = 34 REG_RAM3 = 35 REG_RAM4 = 36 REG_RAM5 = 37 REG_RAM6 = 38 REG_RAM7 = 39 REG_RAM8 = 40 REG_RAM9 = 41 REG_RAM10 = 42 REG_RAM11 = 43 REG_RAM12 = 44 REG_RAM13 = 45 REG_RAM14 = 46 REG_RAM15 = 47 REG_RAM_FIRST = REG_RAM0 REG_RAM_LAST = REG_RAM15 RAM_SIZE = (REG_RAM_LAST - REG_RAM_FIRST + 1) IDX_RAM_TEST = 0 RAM_TEST = 0xB2 # Arbitrary test pattern IDX_RAM_SOC_L = 1 IDX_RAM_SOC_H = 2 IDX_RAM_SOC = IDX_RAM_SOC_L IDX_RAM_CC_CNF_L = 3 IDX_RAM_CC_CNF_H = 4 IDX_RAM_CC_CNF = IDX_RAM_CC_CNF_L IDX_RAM_VM_CNF_L = 5 IDX_RAM_VM_CNF_H = 6 IDX_RAM_VM_CNF = IDX_RAM_VM_CNF_L IDX_RAM_UNUSED_BEGIN = 7 IDX_RAM_UNUSED_END = 14 IDX_RAM_CRC = 15 # Define configuration (defaults) CONFIG_GASGAUGE_0_RSENSE = None # Sense resistor in milli Ohm; set in __init__() CONFIG_RSENSE_DEFAULT = 10 # default value CONFIG_GASGAUGE_0_GPIO_ALARM = None # GPIO pin index for interrupts; set in __init__() # TODO: all these configs below should be set via the __init__ and calculated accordingly # if defined(Gasgauge.battery_idx): # TODO: -> make default in Param_dict None? # TODO: how does this function work: #SETUP_0_REG_CC_CNF = ((CONFIG_GASGAUGE_0_RSENSE) * ( CFG_SUBSECTATR(BATTERY, CONFIG_GASGAUGE_0_BATTERY_IDX, CAPACITY) ) * 250 + 6194) / 12389 # else: default case (if parameter is not given) SETUP_0_REG_CC_CNF = None # set in __init__() # TODO: same as above: # if defined(Gasgauge.battery_idx): # SETUP_0_REG_VM_CNF = ((_CFG_SUBSECTATR(BATTERY, CONFIG_GASGAUGE_0_BATTERY_IDX, IMPEDANCE)) # (CFG_SUBSECTATR(BATTERY, CONFIG_GASGAUGE_0_BATTERY_IDX, CAPACITY)) # 50L + 24444L ) / 48889L # else SETUP_0_REG_VM_CNF = None # set in __init__() # if defined(CONFIG_GASGAUGE_0_ALARM_SOC): # SETUP_0_REG_ALARM_SOC = (CONFIG_GASGAUGE_0_ALARM_SOC << 1) # else SETUP_0_REG_ALARM_SOC = None # SOC lower threshold; SOC alarm level [0.5%]; set in __init__ ALARM_SOC_DEFAULT = 2 # default value # if defined(CONFIG_GASGAUGE_0_ALARM_VOLTAGE): # SETUP_0_REG_ALARM_VOLTAGE = ((CONFIG_GASGAUGE_0_ALARM_VOLTAGE # 5 + 44) / 88) # else SETUP_0_REG_ALARM_VOLTAGE = None # Voltage lower threshold; 3.0 V; set in __init__() ALARM_VOLTAGE_DEFAULT = 170 # default value # if defined(CONFIG_GASGAUGE_0_RELAX_CURRENT): # SETUP_0_REG_CURRENT_THRES = ((CONFIG_GASGAUGE_0_RELAX_CURRENT # CFG_SUBSECTATR(BATTERY, CONFIG_GASGAUGE_0_BATTERY_IDX, IMPEDANCE) + 23520L) / 47040L) # else SETUP_0_REG_CURRENT_THRES = None # Current monitoring threshold; +/-470 V drop; set in __init__() CURRENT_THRES_DEFAULT = 10 # default value # if defined(CONFIG_GASGAUGE_0_RELAX_TIMER): # SETUP_0_REG_CMONIT_MAX = ((_CONFIG_GASGAUGE_0_RELAX_TIMER + 2) >> 2) # else SETUP_0_REG_CMONIT_MAX = None # Monitoring timing threshold; CC-VM: 4 minutes; VM->CC: 1 minute; set in __init__() CMONIT_MAX_DEFAULT = 120 # default value # Other defines DEVICE_ADDRESS_I2C = 0x70 # I2C device address is fix. POR_DELAY_LOOPS_MAX = 2000 # Delay while doing a soft-reset.
[docs] class STC3115_Reg(_STC311x_Reg): CHIP_TYPE = ChipType.STC3115 # STC3115 exclusive mode values (in addition to inherited values _STC311x_Reg._MODE_*) # possible values of the mode register REG_MODE MODE_CLR_VM_ADJ = 0x02 # Clear ACC_VM_ADJ and REG_VM_ADJ MODE_CLR_CC_ADJ = 0x04 # Clear ACC_CC_ADJ and REG_CC_ADJ MODE_DEFAULT = (_STC311x_Reg.MODE_VMODE | _STC311x_Reg.MODE_ALM_ENA) MODE_OFF = 0 # STC3115 exclusive control values (in addition to inherited values _STC311x_Reg._CTRL_*) # possible values of the control register REG_CTRL # there are None. # Definition of registers and their content CHIP_ID = 0x14 # Expected ID found in REG_ID REG_CC_ADJ_H = 11 # Coulomb counter adjustment factor REG_VM_ADJ_H = 12 # Voltage mode adjustment factor REG_CC_ADJ_L = 25 # Coulomb counter adjustment factor REG_VM_ADJ_L = 26 # Voltage mode adjustment factor REG_ACC_CC_ADJ_L = 27 REG_ACC_CC_ADJ_H = 28 REG_ACC_CC_ADJ = REG_ACC_CC_ADJ_L # Coulomb counter correction accumulator REG_ACC_VM_ADJ_L = 29 REG_ACC_VM_ADJ_H = 30 REG_ACC_VM_ADJ = REG_ACC_VM_ADJ_L # Voltage mode correction accumulator # OCV adjustment table [0.55mV] REG_OCVTAB0 = 48 REG_OCVTAB1 = 49 REG_OCVTAB2 = 50 REG_OCVTAB3 = 51 REG_OCVTAB4 = 52 REG_OCVTAB5 = 53 REG_OCVTAB6 = 54 REG_OCVTAB7 = 55 REG_OCVTAB8 = 56 REG_OCVTAB9 = 57 REG_OCVTAB10 = 58 REG_OCVTAB11 = 59 REG_OCVTAB12 = 60 REG_OCVTAB13 = 61 REG_OCVTAB14 = 62 REG_OCVTAB15 = 63 OCV_DEFAULT = 0
[docs] class STC3117_Reg(_STC311x_Reg): CHIP_TYPE = ChipType.STC3117 # STC3117 exclusive mode values (in addition to inherited values _STC311x_Reg._MODE_*) # possible values of the mode register REG_MODE MODE_BATD_PU = 0x02 # BATD internal pull-up enable MODE_FORCE_CD = 0x04 # CD driven by internal logic / forced high MODE_DEFAULT = (_STC311x_Reg.MODE_VMODE | MODE_BATD_PU | _STC311x_Reg.MODE_ALM_ENA) MODE_OFF = MODE_BATD_PU # STC3117 exclusive control values (in addition to inherited values _STC311x_Reg._CTRL_*) # possible values of the control register REG_CTRL CTRL_UVLOD = 0x80 # UVLO event detection # Definition of registers and their content CHIP_ID = 0x16 # Expected ID found in REG_ID REG_AVG_CURRENT_L = 11 REG_AVG_CURRENT_H = 12 REG_AVG_CURRENT = REG_AVG_CURRENT_L # Battery average current or SOC change rate REG_CC_ADJ_L = 27 REG_CC_ADJ_H = 28 REG_CC_ADJ = REG_CC_ADJ_L # Coulomb counter adjustment register REG_VM_ADJ_L = 29 REG_VM_ADJ_H = 30 REG_VM_ADJ = REG_VM_ADJ_L # Voltage mode adjustment register # Open Circuit Voltage (OCV) table registers # OCV points, 2 bytes per point [0.55mV] REG_OCVTAB0_L = 48 REG_OCVTAB0_H = 49 REG_OCVTAB0 = REG_OCVTAB0_L REG_OCVTAB1_L = 50 REG_OCVTAB1_H = 51 REG_OCVTAB1 = REG_OCVTAB1_L REG_OCVTAB2_L = 52 REG_OCVTAB2_H = 453 REG_OCVTAB2 = REG_OCVTAB2_L REG_OCVTAB3_L = 54 REG_OCVTAB3_H = 55 REG_OCVTAB3 = REG_OCVTAB3_L REG_OCVTAB4_L = 56 REG_OCVTAB4_H = 57 REG_OCVTAB4 = REG_OCVTAB4_L REG_OCVTAB5_L = 58 REG_OCVTAB5_H = 59 REG_OCVTAB5 = REG_OCVTAB5_L REG_OCVTAB6_L = 60 REG_OCVTAB6_H = 61 REG_OCVTAB6 = REG_OCVTAB6_L REG_OCVTAB7_L = 62 REG_OCVTAB7_H = 63 REG_OCVTAB7 = REG_OCVTAB7_L REG_OCVTAB8_L = 64 REG_OCVTAB8_H = 65 REG_OCVTAB8 = REG_OCVTAB8_L REG_OCVTAB9_L = 66 REG_OCVTAB9_H = 67 REG_OCVTAB9 = REG_OCVTAB9_L REG_OCVTAB10_L = 68 REG_OCVTAB10_H = 69 REG_OCVTAB10 = REG_OCVTAB10_L REG_OCVTAB11_L = 70 REG_OCVTAB11_H = 71 REG_OCVTAB11 = REG_OCVTAB11_L REG_OCVTAB12_L = 72 REG_OCVTAB12_H = 73 REG_OCVTAB12 = REG_OCVTAB12_L REG_OCVTAB13_L = 74 REG_OCVTAB13_H = 75 REG_OCVTAB13 = REG_OCVTAB13_L REG_OCVTAB14_L = 76 REG_OCVTAB14_H = 77 REG_OCVTAB14 = REG_OCVTAB14_L REG_OCVTAB15_L = 78 REG_OCVTAB15_H = 79 REG_OCVTAB15 = REG_OCVTAB15_L OCV0_DEFAULT = 0x1770 # 3300 mV OCV1_DEFAULT = 0x1926 # 3541 mV OCV2_DEFAULT = 0x19B2 # 3618 mV OCV3_DEFAULT = 0x19FB # 3658 mV OCV4_DEFAULT = 0x1A3E # 3695 mV OCV5_DEFAULT = 0x1A6D # 3721 mV OCV6_DEFAULT = 0x1A9D # 3747 mV OCV7_DEFAULT = 0x1AB6 # 3761 mV OCV8_DEFAULT = 0x1AD5 # 3778 mV OCV9_DEFAULT = 0x1B01 # 3802 mV OCV10_DEFAULT = 0x1B70 # 3863 mV OCV11_DEFAULT = 0x1BB1 # 3899 mV OCV12_DEFAULT = 0x1BE8 # 3929 mV OCV13_DEFAULT = 0x1C58 # 3991 mV OCV14_DEFAULT = 0x1CF3 # 4076 mV OCV15_DEFAULT = 0x1DA9 # 4176 mV # State Of Charge (SOC) SOC points [0.5%] REG_SOCTAB0 = 80 REG_SOCTAB1 = 81 REG_SOCTAB2 = 82 REG_SOCTAB3 = 83 REG_SOCTAB4 = 84 REG_SOCTAB5 = 85 REG_SOCTAB6 = 86 REG_SOCTAB7 = 87 REG_SOCTAB8 = 88 REG_SOCTAB9 = 89 REG_SOCTAB10 = 90 REG_SOCTAB11 = 91 REG_SOCTAB12 = 92 REG_SOCTAB13 = 93 REG_SOCTAB14 = 94 REG_SOCTAB15 = 95 SOC0_DEFAULT = 0x00 # 0 % SOC1_DEFAULT = 0x06 # 3 % SOC2_DEFAULT = 0x0C # 6 % SOC3_DEFAULT = 0x14 # 10 % SOC4_DEFAULT = 0x1E # 15 % SOC5_DEFAULT = 0x28 # 20 % SOC6_DEFAULT = 0x32 # 25 % SOC7_DEFAULT = 0x3C # 30 % SOC8_DEFAULT = 0x50 # 40 % SOC9_DEFAULT = 0x64 # 50 % SOC10_DEFAULT = 0x7B # 60 % SOC11_DEFAULT = 0x82 # 65 % SOC12_DEFAULT = 0x8C # 70 % SOC13_DEFAULT = 0xA0 # 80 % SOC14_DEFAULT = 0xB4 # 90 % SOC15_DEFAULT = 0xC8 # 100 %