battery-charger-fuel-gauge-integration

Use when integrating or debugging Li-ion charger/fuel gauge ICs (BQ24295, BQ27441, MAX17048) over I2C, covering charge start, watchdog host mode, NTC/JEITA faults, and SOC jumps

SKILL.md

GitHub

Battery Charger and Fuel Gauge Integration

Overview

Use this skill to bring up a Li-ion/LiPo charger IC (TI BQ24xxx/BQ25xxx) and a fuel gauge (TI BQ27xxx Impedance Track, or Maxim/Analog MAX1704x ModelGauge, e.g. MAX17048) over I2C. The hard parts are keeping the charger in host mode past its watchdog, and getting an accurate SOC before the gauge has a matching battery profile.

When To Use

Use this skill when:

  • Charging never starts or restarts in a loop: check input current limit (IINLIM, REG00[2:0]), EN_HIZ, the CE pin, and the I2C watchdog resetting registers to default.
  • The charger reports faults: REG09 latched faults, NTC_FAULT (REG09[2:0], with a real thermistor such as 103AT on the TS pin), safety timer expiration, or JEITA temperature de-rating.
  • SOC from BQ27441/MAX17048 is wrong or jumps at power-up: profile not loaded, no learning cycle, or bad OCV calibration.
  • I2C reads to the charger/gauge fail or the wrong 7-bit address is used.

Do not use this skill when the I2C bus itself is dead (no ACK on any address) or the board rails are wrong; debug the bus and power tree first with hardware-interface-debug.

First Questions

Ask for:

  • Exact charger and gauge part numbers, cell count/chemistry, pack capacity (mAh), and charge voltage (4.2 V vs 4.35 V — picks BQ27441-G1A vs -G1B).
  • 7-bit I2C addresses, bus speed, and pull-up values; whether INT/GPOUT is wired.
  • NTC/thermistor part and TS resistor network (RT1/RT2), plus target charge/discharge temperature window.
  • Whether a battery profile (TI golden image .gm.fs/.df.fs, or a Maxim RCOMP/custom-model INI) exists, or a golden image must be created.
  • Current symptom: register dump, fault code, measured VBAT/ICHG, or reported SOC vs true SOC.

Integration Checklist

  1. Confirm the device on the bus. ACK the charger and gauge 7-bit addresses; read a known register (charger REG0A Vendor/Part/Revision, or gauge Control() DEVICE_TYPE subcommand) before writing anything.

  2. Take and hold host mode on the charger. Set IINLIM in REG00[2:0], clear EN_HIZ (REG00[7]), enable charging via CE/CHG_CONFIG (REG01[4]), then feed the I2C watchdog (write REG01[6]) on a timer, or disable it (WATCHDOG = REG05[5:4] = 00), so registers do not reset to default and drop charging.

  3. Configure charge parameters and protection. Program fast-charge current (ICHG, REG02), pre-charge/termination current (REG03), charge voltage (VREG, REG04), and enable NTC/JEITA limits; confirm the thermistor scaling (e.g. 103AT) on the TS pin.

  4. Load the fuel gauge battery profile. For BQ27441: UNSEAL via Control(), enter CFGUPDATE, poll Flags() until bit 4 is set, write Design Capacity/Design Energy/Terminate Voltage/Taper Rate in the data-memory block, fix BlockDataChecksum (255 - x, where x is the byte-wise sum of the block), then SOFT_RESET. For MAX17048: load a custom model / set RCOMP0 (CONFIG default 0x97) or accept EZ defaults.

  5. Calibrate SOC at first power-up. Let the pack rest for a valid OCV read, then issue MAX17048 QuickStart (MODE = 0x4000) or check BQ27441 Flags() ITPOR cleared; do not QuickStart under load.

  6. Run temperature compensation and status polling. Update MAX17048 RCOMP from measured temperature at least once/minute; on BQ27441 feed Temperature() if host-reported. Poll charger CHRG_STAT (REG08[5:4]) and read REG09 twice to get fresh faults (it latches, clears on read).

Common Failures

  • Charging restarts every ~40 s: I2C watchdog expired (default 40 s), resetting the writable control registers to defaults; feed it or disable WATCHDOG.
  • No current with valid adapter: IINLIM too low, EN_HIZ set, ILIM pin resistor, or CE held high disabling charge.
  • Charge stuck in pre-charge or never terminating: BATLOWV threshold (REG04[1]), wrong termination current, or safety timer expiring (REG09 charge safety timer fault).
  • NTC_FAULT / no charge in a comfortable room: TS resistor network wrong, floating TS pin, or JEITA cold/hot fold-back.
  • SOC reads 0/100 % or jumps tens of percent: profile (Design Capacity) not written, BlockDataChecksum wrong so writes silently rejected, or ITPOR still set.
  • Gauge writes ignored: device still SEALED, or not in CFGUPDATE mode before writing the data-memory block.
  • I2C NAK: wrong 7-bit vs 8-bit address, missing pull-ups, or gauge in hibernate/shutdown.

Verification

Before claiming charging and gauging work:

  • Dump charger REG00–REG0A; confirm IINLIM, VREG, ICHG, watchdog state, and CHRG_STAT transitions Not Charging → Fast Charging → Termination Done.
  • Force a fault (unplug NTC or overheat pack) and confirm REG09/INT reports it and clears on re-read.
  • Compare gauge SOC against a coulomb-counted or bench-measured charge/discharge; verify it tracks within a few percent and survives a reset (ITPOR clear, profile persists).
  • Confirm charging continues across a full watchdog interval without host register rewrites (or with the feeding task running).

Example

User:

BQ24295 一充电就每隔几十秒重启,SOC 还老是乱跳,怎么查?

Agent:

  1. Asks for I2C address, adapter/IINLIM setting, whether the watchdog is fed, NTC network, and whether a BQ27441 profile was loaded.
  2. Reads REG00/REG08/REG09; if registers reverted to defaults, enables watchdog feeding (write REG01[6]) or disables WATCHDOG to hold host mode.
  3. Checks the gauge: UNSEAL, verifies Design Capacity and BlockDataChecksum, clears ITPOR, then QuickStart/rest-OCV calibrates SOC and re-tests across a charge cycle.