max1704x_smbus.core

This module provides the main public interface for interacting with the MAX17048/MAX17049 fuel gauge devices. It contains the primary class MAX17048 and several useful constants.

class max1704x_smbus.core.MAX17048(i2c_bus=1, address=54)

Interface for the MAX17048 fuel gauge.

High-level interface to the Maxim MAX17048/MAX17049 battery fuel gauge IC. The class exposes commonly used readings (voltage, SOC, charge rate), alert configuration and handling, and hibernation controls via an attribute-like API.

__init__(i2c_bus=1, address=54)

Initialize a MAX17048/MAX17049 fuel gauge instance.

Establishes communication with the device over the specified I²C bus and verifies that a supported chip is present at the given address.

Parameters:

i2c_bus (int, optional) – I²C bus number where the device is connected. Default is 1.
address (int, optional) – I²C address of the device. Default is MAX1704X_I2CADDR_DEFAULT.

Raises:

RuntimeError – If the device does not respond with a valid chip version, indicating either incorrect wiring or absence of a MAX17048/MAX17049.

reset()

Perform a soft reset of the MAX17048/MAX17049 device.

Sends the reset command and clears the reset alert flag. This operation performs a soft reset of the device, restarting its internal fuel gauge logic without physically disconnecting the power supply.

Raises:: RuntimeError – If the reset command does not succeed or if clearing the reset alert fails.
Return type:: None

quick_start()

Trigger a quick-start estimation of OCV and SOC.

Initiates a recalculation of open-circuit voltage (OCV) and state-of-charge (SOC) based on the instantaneous cell voltage.

Notes

This method sets the Quick-Start bit in the MODE register to trigger a recalculation. Use with caution; see the Quick-Start section of the datasheet for details.

Return type:: None

property cell_voltage: float

Battery cell voltage.

Returns:: Cell voltage in volts.
Return type:: float

property cell_percent: float

Battery state of charge (SOC).

Returns:: State of charge as a percentage of full capacity (0-100).
Return type:: float

property charge_rate: float

Battery charge or discharge rate.

Returns:: Rate of change in percent per hour. Positive values indicate charging, negative values indicate discharging.
Return type:: float

property chip_version: int

Production version of the device.

Returns:: Chip version value.
Return type:: int

property chip_id: int

Unique identifier of the device.

Returns:: Chip ID value.
Return type:: int

property rcomp: int

Temperature compensation value.

Used to optimize accuracy for different lithium chemistries or operating temperature ranges.

Returns:: Chip ID value.
Return type:: int

property comparator_disabled: bool

Control whether the analog comparator for VRESET is disabled.

When set to True, the analog comparator (used to detect battery removal and reinsertion) is disabled during hibernate mode, reducing supply current by about 0.5 µA. When False, the comparator remains enabled.

Returns:: True if the comparator is disabled in hibernate mode, False if enabled.
Return type:: bool

Notes

Corresponds to the Dis bit in the VRESET/ID register. See the VRESET section of the datasheet for details on threshold adjustment and reset timing behavior.

property hibernating: bool

Whether the device is currently in hibernation.

Read the device hibernation status. Returns True when the hardware reports it is in hibernation mode.

Returns:: True if the device is in hibernation, False otherwise.
Return type:: bool

Notes

Corresponds to the HibStat bit in the MODE register. This property is read-only. Use hibernate() or wake() to change the device state.

property activity_threshold: float

Charge/Discharge rate threshold to exit hibernation.

When the rate of change of the cell voltage exceeds this threshold, the device leaves hibernation.

Returns:: Threshold in volts, between 0 and 0.31875 V.
Return type:: float
Raises:: ValueError – If a value outside the valid range is assigned.

property hibernation_threshold: float

Charge/Discharge rate threshold to enter hibernation.

When the rate of change of the cell falls below this threshold, the device enters hibernation. This condition must be maintained for 6 minutes.

Returns:: Threshold in percent per hour, between 0 and 53%/h.
Return type:: float
Raises:: ValueError – If a value outside the valid range is assigned.

hibernate()

Enter hibernation mode immediately.

This method forces the device into hibernation by setting both thresholds to their maximum values, regardless of the current charge/discharge rate or voltage change.

Notes

This operation overwrites the hibernation thresholds. Calling hibernate() followed by wake() does not restore previous threshold values.

Return type:: None

wake()

Exit hibernation mode immediately.

This method forces the device out of hibernation by setting both thresholds to zero, regardless of the current charge/discharge rate or voltage change.

Notes

This operation overwrites the hibernation thresholds. Calling hibernate() followed by wake() does not restore previous threshold values.

Return type:: None

property sleep_enable: bool

Enable or disable sleep mode.

Returns:: True if sleep mode is enabled, False otherwise.
Return type:: bool

See also

sleep_switch

Notes

Corresponds to the EnSleep bit in the MODE register (read/write).

property sleep_switch: bool

Control whether the IC is forced into sleep mode.

Writing True forces the device into sleep mode, and False forces it to exit. This control is effective only if sleep_enable is enabled.

Returns:: True if forcing the device into sleep mode, False if forcing exit.
Return type:: bool

See also

sleep_enable

Notes

Corresponds to the SLEEP bit in the CONFIG register.

property alert_global_flag: bool

Indicate whether an alert condition is currently active.

Returns:: True if an alert is active, False otherwise.
Return type:: bool

Notes

This flag has automatic behavior:

Auto-set: Automatically becomes True when any individual alert is triggered
Auto-clear: Automatically becomes False when all individual alert flags are cleared

The alert_reset_indicator_flag does not affect this global flag status.

alert_global_flag_clear()

Clear the global alert flag and deassert the ALRT pin.

This operation resets the alert status in the configuration register and simultaneously releases the physical ALRT pin, until a new alert condition is triggered. As a side effect, all individual alert flags are also cleared simultaneously.

See also

alert_global_flag

Notes

The alert_reset_indicator_flag is NOT cleared by this method, as it is not a true alert but a device status indicator. To clear it, use alert_reset_indicator_flag_clear() instead.

Return type:: None

property alert_reason: int

6-bit bitmask of currently active alert causes.

Returns:: Mask of alert flags. Multiple causes may be set simultaneously. Individual causes can be checked against the module constants (e.g. ALERTFLAG_SOC_LOW).
Return type:: int

property alert_soc_change_enable: bool

Enable or disable the state-of-charge (SOC) change alert.

When enabled, the device asserts an alert whenever the SOC changes by at least 1%.

Returns:: True if the SOC change alert is enabled, False otherwise.
Return type:: bool

property alert_soc_change_flag: bool

SOC change flag.

Indicates whether SOC has changed at least 1% (if enabled).

Returns:: True if SOC changed at least 1%, False otherwise.
Return type:: bool

Notes

Corresponds to the SC bit in the STATUS register. This property is read-only. Use alert_soc_change_flag_clear() to clear the flag after handling the alert.

alert_soc_change_flag_clear()

Clear the SOC change flag.

Clear the SC (SOC change) flag in the STATUS register.

Return type:: None

property alert_soc_low_threshold: int

Low-SOC alert threshold.

Defines the state-of-charge (SOC) percentage below which the device asserts an alert condition.

Returns:: Threshold in percent, between 1 and 32%.
Return type:: int
Raises:: ValueError – If a value outside the valid range is assigned.

property alert_soc_low_flag: bool

SOC low flag.

Indicates whether SOC crosses the alert_soc_low_threshold.

Returns:: True if SOC crossed the configured threshold, False otherwise.
Return type:: bool

Notes

Corresponds to the HD bit in the STATUS register. This property is read-only. Use alert_soc_low_flag_clear() to clear the flag after handling the alert.

alert_soc_low_flag_clear()

Clear the SOC low flag.

Clear the HD (SOC low) flag in the STATUS register.

Return type:: None

property alert_voltage_high_threshold: float

Maximum voltage threshold for triggering a voltage alert.

Returns:: Upper-limit threshold in volts, between 0 and 5.1 V.
Return type:: float
Raises:: ValueError – If a value outside the valid range is assigned.

property alert_voltage_high_flag: bool

Voltage high flag.

Indicates whether the high voltage alert is active. True means the cell voltage has exceeded the threshold set in alert_voltage_high_threshold.

Returns:: True if the cell voltage has exceeded the threshold, False otherwise.
Return type:: bool

Notes

Corresponds to the VH bit in the STATUS register. This property is read-only. Use alert_voltage_high_flag_clear() to clear the flag after handling the alert.

alert_voltage_high_flag_clear()

Clear the voltage high flag.

Clear the VH (voltage high) flag in the STATUS register.

Return type:: None

property alert_voltage_low_threshold: float

Minimum voltage threshold for triggering a voltage alert.

Returns:: Lower-limit threshold in volts, between 0 and 5.1 V.
Return type:: float
Raises:: ValueError – If a value outside the valid range is assigned.

property alert_voltage_low_flag: bool

Voltage low flag.

Indicates whether the low voltage alert is active. True means the cell voltage has fallen below the threshold set in alert_voltage_low_threshold.

Returns:: True if the cell voltage has fallen below the threshold, False otherwise.
Return type:: bool

Notes

Corresponds to the VL bit in the STATUS register. This property is read-only. Use alert_voltage_low_flag_clear() to clear the flag after handling the alert.

alert_voltage_low_flag_clear()

Clear the voltage low flag.

Clear the VL (voltage low) flag in the STATUS register.

Return type:: None

property alert_voltage_reset_enable: bool

Enable or disable voltage reset alert.

Returns:: True if voltage reset alert is enabled, False otherwise.
Return type:: bool

Notes

Corresponds to the EnVr bit in the STATUS register (read/write).

property alert_voltage_reset_threshold: float

Reset threshold voltage.

Cell voltage threshold at which the device considers a battery removal or reinsertion.

Returns:: Threshold voltage in volts, between 0 and 5.1 V.
Return type:: float
Raises:: ValueError – If a value outside the valid range is assigned.

property alert_voltage_reset_flag: bool

Voltage reset flag.

Indicates whether the cell voltage dropped below and subsequently risen above the alert_voltage_reset_threshold threshold.

Returns:: True if the cell voltage dropped below and then rose above the configured reset threshold, False otherwise.
Return type:: bool

Notes

Corresponds to the VR bit in the STATUS register. This property is read-only. Use alert_voltage_reset_flag_clear() to clear the flag after handling the alert.

alert_voltage_reset_flag_clear()

Clear the voltage reset flag.

Clear the VR (voltage reset) flag in the STATUS register.

Return type:: None

property alert_reset_indicator_flag: bool

Reset indicator flag.

Indicates whether the device has recently powered up or reset and still requires configuration. A value of True means the IC is signaling that initialization is pending. False means the device has already been configured and the flag has been cleared.

Returns:: True if the reset indicator (RI) flag is set, False otherwise.
Return type:: bool

Notes

Corresponds to the RI bit in the STATUS register. This property is read-only. Use alert_reset_indicator_flag_clear() to acknowledge and clear the flag.

This flag is independent of alert_global_flag and is not automatically cleared when clearing the global alert flag.

alert_reset_indicator_flag_clear()

Clear the reset indicator flag.

Acknowledges that the device has been configured after a reset or power-up event by clearing the RI bit in the STATUS register.

See also

alert_reset_indicator_flag

Notes

This method explicitly writes 0 to the RI flag. The bit is set automatically by the device after power-up or reset.

Return type:: None

Module constants

max1704x_smbus.core.ALERTFLAG_SOC_CHANGE =0x20

max1704x_smbus.core.ALERTFLAG_SOC_LOW =0x10

max1704x_smbus.core.ALERTFLAG_VOLTAGE_RESET =0x08

max1704x_smbus.core.ALERTFLAG_VOLTAGE_LOW =0x04

max1704x_smbus.core.ALERTFLAG_VOLTAGE_HIGH =0x02

max1704x_smbus.core.ALERTFLAG_RESET_INDICATOR =0x01