API Overview

The MAX17048 driver API is organized into functional groups based on the device’s capabilities.

Primary API

The Primary API provides access to general usage options and information.

Battery Monitoring

These properties provide real-time battery measurements (read-only):

`cell_voltage`	Battery cell voltage.
`cell_percent`	Battery state of charge (SOC).
`charge_rate`	Battery charge or discharge rate.

from max1704x_smbus import MAX17048

sensor = MAX17048()

# Battery measurements
print(f"Voltage: {sensor.cell_voltage} V")
print(f"Charge level: {sensor.cell_percent} %")
print(f"Charge rate: {sensor.charge_rate} %/hr")

Device Information

Read chip identification and version information (read-only):

`chip_id`	Unique identifier of the device.
`chip_version`	Production version of the device.

print(f"Chip: 0x{sensor.chip_id:02X} v{sensor.chip_version}")

Configuration & Control

Configure device behavior and perform control operations:

`rcomp`	Temperature compensation value.
`reset`()	Perform a soft reset of the MAX17048/MAX17049 device.
`quick_start`()	Trigger a quick-start estimation of OCV and SOC.

Sleep API

Control sleep status of the device. During sleep, measurements and alert monitoring are paused.

`sleep_enable`	Enable or disable sleep mode.
`sleep_switch`	Control whether the IC is forced into sleep mode.

from max1704x_smbus import MAX17048

sensor = MAX17048()
sensor.sleep_enable = True

# Check current voltage and voltage_high alert
print(sensor.cell_voltage)              # 4.07625
print(sensor.alert_voltage_high_flag)   # False

# Let's force an alert to be triggered
sensor.alert_voltage_high_threshold = 3.7
sensor.alert_voltage_high_threshold = 5.0
print(sensor.alert_voltage_high_flag)   # True

# Entering sleep mode
sensor.sleep_switch = True

# Clear and check the alert flag (still in sleep mode)
sensor.alert_voltage_high_flag_clear()
print(sensor.alert_voltage_high_flag)   # True

# Check the alert flag (after exiting sleep mode)
sensor.sleep_switch = False
print(sensor.alert_voltage_high_flag)   # False

Hibernate API

`hibernating`	Whether the device is currently in hibernation.
`activity_threshold`	Charge/Discharge rate threshold to exit hibernation.
`hibernation_threshold`	Charge/Discharge rate threshold to enter hibernation.
`hibernate`()	Enter hibernation mode immediately.
`wake`()	Exit hibernation mode immediately.

Hibernation can be controlled automatically via thresholds or manually via methods, or a combination of both approaches.

Automatic mode with thresholds:

from max1704x_smbus import MAX17048

sensor = MAX17048()

sensor.activity_threshold = 0.08    # Exits hibernation if |OCV - CELL| > 80 mV
sensor.hibernation_threshold = 20   # Enters hibernation if CRATE < 20 %/hr (for 6 min)

if sensor.hibernating:
    print("Device in hibernation")

Manual control:

from max1704x_smbus import MAX17048

sensor = MAX17048()

sensor.wake()

if some_condition:      # Force hibernation
    sensor.hibernate()

Alerts API

All items in the alerts API begin with alert_ and follow the naming format alert_<type>_<element>, except for alert_reason.

Global Alerts

`alert_global_flag`	Indicate whether an alert condition is currently active.
`alert_global_flag_clear`()	Clear the global alert flag and deassert the `ALRT` pin.
`alert_reason`	6-bit bitmask of currently active alert causes.

Constants are available to mask alert_reason:

ALERTFLAG_SOC_CHANGE

ALERTFLAG_SOC_LOW

ALERTFLAG_VOLTAGE_RESET

ALERTFLAG_VOLTAGE_LOW

ALERTFLAG_VOLTAGE_HIGH

ALERTFLAG_RESET_INDICATOR

from max1704x_smbus import MAX17048
from max1704x_smbus.core import ALERTFLAG_SOC_LOW, ALERTFLAG_VOLTAGE_LOW, ALERTFLAG_VOLTAGE_HIGH

sensor = MAX17048()

if sensor.alert_reason & (ALERTFLAG_SOC_LOW | ALERTFLAG_VOLTAGE_LOW):
    print("Warning: Battery Low")
    # Handle low battery condition
elif sensor.alert_reason & ALERTFLAG_VOLTAGE_HIGH:
    print("Critical: Overvoltage detected")
    # Handle overvoltage condition

SoC Change Alert

`alert_soc_change_enable`	Enable or disable the state-of-charge (SOC) change alert.
`alert_soc_change_flag`	SOC change flag.
`alert_soc_change_flag_clear`()	Clear the SOC change flag.

Triggers when State of Charge (SoC) changes at least 1%.

from max1704x_smbus import MAX17048

sensor = MAX17048()

sensor.alert_soc_change_enable = True

while True:
    if sensor.alert_soc_change_flag:
        print("SoC Changed!")
        sensor.alert_soc_change_flag_clear()

SoC Low Alert

`alert_soc_low_threshold`	Low-SOC alert threshold.
`alert_soc_low_flag`	SOC low flag.
`alert_soc_low_flag_clear`()	Clear the SOC low flag.

Triggers when battery percentage falls below the configured threshold.

Overvoltage Alert

`alert_voltage_high_threshold`	Maximum voltage threshold for triggering a voltage alert.
`alert_voltage_high_flag`	Voltage high flag.
`alert_voltage_high_flag_clear`()	Clear the voltage high flag.

Triggers when battery voltage rises above the configured threshold.

Undervoltage Alert

`alert_voltage_low_threshold`	Minimum voltage threshold for triggering a voltage alert.
`alert_voltage_low_flag`	Voltage low flag.
`alert_voltage_low_flag_clear`()	Clear the voltage low flag.

Triggers when battery voltage falls below the configured threshold.

Voltage Reset Alert (Battery Removal)

`alert_voltage_reset_enable`	Enable or disable voltage reset alert.
`alert_voltage_reset_threshold`	Reset threshold voltage.
`alert_voltage_reset_flag`	Voltage reset flag.
`alert_voltage_reset_flag_clear`()	Clear the voltage reset flag.

Triggers when battery voltage falls and rises again above the configured threshold, indicating a battery reconnection.

Reset Indicator (Power-On / Reset)

`alert_reset_indicator_flag`	Reset indicator flag.
`alert_reset_indicator_flag_clear`()	Clear the reset indicator flag.

Activated when powered up or reset, indicating the device still requires configuration.

Analog Comparator

The IC has a fast analog comparator and a slower digital ADC to detect battery removal and reinsertion (Voltage Reset Alert).

This fast analog comparator can be disabled when the device enters hibernation mode by setting the comparator_disabled bit. This saves approximately 0.5µA.

comparator_disabled

Control whether the analog comparator for VRESET is disabled.

If the comparator is enabled, the IC takes 1ms to reset after the cell voltage (VCELL) rises above the threshold.

Otherwise, the trigger relies on the digital ADC, taking 250ms to reset.