gauge/xpowers/GaugeAXP2602.hpp

Go to the documentation of this file.

 
#pragma once
 
#include <math.h>
 
#include "../../SensorBuildOpt.h"
#if !SENSORLIB_EXCLUDE_GAUGE_AXP2602
 
#include "platform/comm/I2CDeviceWithHal.hpp"
#include "../GaugeBase.hpp"
 
// AXP2602 Unique device address
static constexpr uint8_t AXP2602_SLAVE_ADDRESS  = (0x62);
 
class GaugeAXP2602 : public GaugeBase, public I2CDeviceWithHal
{
public:
    enum CurrentSenseResistor {
        SENSE_RESISTOR_10_MOHM = 0x00,
        SENSE_RESISTOR_5_MOHM = 0x01,
        SENSE_RESISTOR_20_MOHM = 0x02,
        SENSE_RESISTOR_40_MOHM = 0x03
    };
 
    enum  IRQStatus {
        IRQ_STATUS_NONE                = 0x00,
        IRQ_STATUS_LOW_BATTERY         = 0x01,
        IRQ_STATUS_SOC_UPDATE          = 0x02,
        IRQ_STATUS_OVER_TEMPERATURE    = 0x03,
        IRQ_STATUS_WDT_TIMEOUT         = 0x04
    };
 
    enum IRQEnable {
        IRQ_ENABLE_WDT_TIMEOUT   = 0x08,
        IRQ_ENABLE_OVER_TEMPERATURE = 0x04,
        IRQ_ENABLE_SOC_UPDATE    = 0x02,
        IRQ_ENABLE_LOW_BATTERY   = 0x01
    };
    enum OperatingMode {
        // It has relatively high power consumption, but can be used for both charging and discharging.
        OPERATING_MODE_HIGH_PRECISION = 0x00,
        // In default mode, it can be used for both charging and discharging.
        OPERATING_MODE_NORMAL = 0x02,
        // With relatively low power consumption, it can only be used in low-power scenarios during discharge.
        // In other scenarios, software switching to normal mode or high-precision mode is required.
        OPERATING_MODE_LOW_POWER = 0x06,
    };
 
    struct GaugeData {
 
        uint8_t chipID;              // Chip ID
        // Voltage, current, and temperature measurements
        uint16_t voltage;           // mV
        int16_t currentRaw;         // mA (Signed, two's complement representation)
        int8_t temperature;         // °C
        uint16_t tdieTemperatureRaw;   // Thermosensitive Temperature ADC Raw Value
 
        // Battery status information
        uint8_t soc;                // Battery percentage (0-100)
        uint8_t soh;                // Battery health status (0-100)
        uint16_t timeToEmpty;       // Time remaining (minutes)
        uint16_t timeToFull;        // Full time (minutes)
 
        // IRQ status
        IRQStatus irqStatus;
 
        // Operating mode
        OperatingMode operatingMode;
 
        // Configuration status
        bool thermalDieEnabled;
        bool currentMeasurementEnabled;
        bool batteryDetectionEnabled;
        bool sleepModeEnabled;
        CurrentSenseResistor senseResistor;
 
        float current;              // Actual current calculated from the sampling resistor（mA）
        float actualDieTemperature; // die temperature calculated according to the formula（℃）
        float power;                // Instantaneous power (W), positive indicates discharging, negative indicates charging.
 
        GaugeData() :
            chipID(0),
            voltage(0),
            currentRaw(0),
            temperature(0),
            tdieTemperatureRaw(0),
            soc(0),
            soh(0),
            timeToEmpty(0),
            timeToFull(0),
            irqStatus(IRQ_STATUS_NONE),
            operatingMode(OPERATING_MODE_NORMAL),
            thermalDieEnabled(true),
            currentMeasurementEnabled(true),
            batteryDetectionEnabled(true),
            sleepModeEnabled(false),
            senseResistor(SENSE_RESISTOR_10_MOHM),
            current(0.0f),
            actualDieTemperature(0.0f),
            power(0.0f)
        {}
    };
 
    GaugeAXP2602() = default;
 
    ~GaugeAXP2602() = default;
 
#if defined(ARDUINO)
    bool begin(TwoWire &wire, int sda = -1, int scl = -1)
    {
        return I2CDeviceWithHal::begin(wire, AXP2602_SLAVE_ADDRESS, sda, scl);
    }
 
#elif defined(ESP_PLATFORM)
 
#if defined(SENSORLIB_USE_I2C_LEGACY)
    bool begin(i2c_port_t port_num, int sda = -1, int scl = -1)
    {
        return I2CDeviceWithHal::begin(port_num, AXP2602_SLAVE_ADDRESS, sda, scl);
    }
#else
    bool begin(i2c_master_bus_handle_t handle)
    {
        return I2CDeviceWithHal::begin(handle, AXP2602_SLAVE_ADDRESS);
    }
#endif  //ESP_PLATFORM
#endif  //ARDUINO
 
    bool begin(SensorCommCustom::CustomCallback callback,
               SensorCommCustomHal::CustomHalCallback hal_callback)
    {
        return I2CDeviceWithHal::begin(callback, hal_callback, AXP2602_SLAVE_ADDRESS);
    }
 
    bool refresh() override
    {
        if (!comm) return false;
 
        if (data.chipID != AXP2602_CHIP_ID) {
            SENSORLIB_LOG_E("Chip id not match : %" PRIu32, data.chipID);
            return false;
        }
 
        if (data.sleepModeEnabled) {
            // Chip is in sleep mode, no need to read other registers
            return true;
        }
 
        // Read voltage (14-bit ADC, 0-4500mV)
        int vbatHigh = readReg(REG_VBAT_ADC_HIGH);
        int vbatLow = readReg(REG_VBAT_ADC_LOW);
        if (vbatHigh >= 0 && vbatLow >= 0) {
            data.voltage = ((vbatHigh & 0x3F) << 8) | vbatLow;  // High 6 bits + Low 8 bits
        }
 
        // Read current (16-bit ADC, two's complement)
        int ibatHigh = readReg(REG_IBAT_ADC_HIGH);
        int ibatLow = readReg(REG_IBAT_ADC_LOW);
        if (ibatHigh >= 0 && ibatLow >= 0) {
            uint16_t raw = (ibatHigh << 8) | ibatLow;
            data.currentRaw = static_cast<int16_t>(raw);  // Convert to signed 16-bit
 
            // Calculate actual current value (mA) based on sense resistor
            float resolution = getCurrentResolution(data.senseResistor);
            data.current = data.currentRaw * resolution;
        }
 
        // Read temperature
        int temp = readReg(REG_TEMP_RESULT);
        if (temp >= 0) {
            // 1 LSB = 1°C, range -128°C to +127°C
            data.temperature = static_cast<int8_t>(temp);
        }
 
        // Read die temperature (13-bit ADC)
        int tdieHigh = readReg(REG_TDIE_ADC_HIGH);
        int tdieLow = readReg(REG_TDIE_ADC_LOW);
        if (tdieHigh >= 0 && tdieLow >= 0) {
            data.tdieTemperatureRaw = ((tdieHigh & 0x1F) << 8) | tdieLow;  // High 5 bits + Low 8 bits
            // Formula on page 10 of the manual: Temperature (°C) = (3415 - xDie) * 10 / 95 + 26
            data.actualDieTemperature = (3415.0 - data.tdieTemperatureRaw) * 10.0 / 95.0 + 26.0;
            if (data.actualDieTemperature < -40 || data.actualDieTemperature > 85) {
                SENSORLIB_LOG_E("Die temperature out of range: %d", data.actualDieTemperature);
                data.actualDieTemperature = 0; // Reset to 0 if out of range
            }
        }
 
        // Read battery status
        data.soc = readReg(REG_SOC);
        data.soh = readReg(REG_SOH);
 
        // Read time to empty estimation
        int timeEmptyHigh = readReg(REG_TIME_TO_EMPTY_HIGH);
        int timeEmptyLow = readReg(REG_TIME_TO_EMPTY_LOW);
        if (timeEmptyHigh >= 0 && timeEmptyLow >= 0) {
            data.timeToEmpty = (timeEmptyHigh << 8) | timeEmptyLow;
        }
 
        int timeFullHigh = readReg(REG_TIME_TO_FULL_HIGH);
        int timeFullLow = readReg(REG_TIME_TO_FULL_LOW);
        if (timeFullHigh >= 0 && timeFullLow >= 0) {
            data.timeToFull = (timeFullHigh << 8) | timeFullLow;
        }
 
        // Read IRQ status
        int irqStatus = readReg(REG_IRQ_STATUS);
        if (irqStatus >= 0) {
            data.irqStatus = static_cast<IRQStatus>(irqStatus & 0x0F);
        }
 
        // Read configuration
        int config = readReg(REG_COMM_CONFIG);
        if (config >= 0) {
            data.thermalDieEnabled = (config & sensorlib::_bv(6)) != 0;
            data.currentMeasurementEnabled = (config & sensorlib::_bv(5)) != 0;
            data.batteryDetectionEnabled = (config & sensorlib::_bv(4)) != 0;
            data.senseResistor = static_cast<CurrentSenseResistor>(config & 0x03);
        }
 
        // Calculate instantaneous power (W): P = V * I
        data.power = (data.voltage * data.current) / 1000000.0f;
 
        return true;
    }
 
    float getCurrentResolution(CurrentSenseResistor resistor)
    {
        switch (resistor) {
        case SENSE_RESISTOR_5_MOHM:
            return 0.5f;    // 500uA/LSB = 0.5mA/LSB
        case SENSE_RESISTOR_10_MOHM:
            return 0.25f;   // 250uA/LSB = 0.25mA/LSB
        case SENSE_RESISTOR_20_MOHM:
            return 0.125f;  // 125uA/LSB = 0.125mA/LSB
        case SENSE_RESISTOR_40_MOHM:
            return 0.0625f; // 62.5uA/LSB = 0.0625mA/LSB
        default:
            return 0.25f;   // Default 10mΩ
        }
    }
 
    uint16_t getChipID() override
    {
        return readReg(REG_AXP2602_ID);
    }
 
    float getTemperature() override
    {
        return data.temperature;
    }
 
    uint8_t getBatteryStatus()
    {
        return data.soh;
    }
 
    uint16_t getStateOfCharge() override
    {
        return data.soc;
    }
 
    uint16_t getTimeToEmpty() override
    {
        return data.timeToEmpty;
    }
 
    uint16_t getTimeToFull() override
    {
        return data.timeToFull;
    }
 
    uint8_t getLowBatterySOCThreshold()
    {
        int lowSoc = readReg(REG_LOW_SOC_THLD);
        if (lowSoc >= 0) {
            return lowSoc & 0x3F;  // Low 6 bits valid
        }
        return 0;
    }
 
    uint8_t getOverTemperatureThreshold()
    {
        int otThld = readReg(REG_OT_THLD);
        if (otThld >= 0) {
            return otThld & 0x7F;  // Low 7 bits valid
        }
        return 0;
    }
 
    float getThermalDieTemperature()
    {
        return data.actualDieTemperature;
    }
 
    uint16_t getThermalDieTemperatureRaw()
    {
        return data.tdieTemperatureRaw;
    }
 
    uint16_t getVoltage() override
    {
        return data.voltage;
    }
 
 
    bool isCharging() override
    {
        return data.current > 0;
    }
 
    bool isDischarging() override
    {
        return data.current < 0;
    }
 
    float getChargingPower()
    {
        return (data.current > 0) ? data.power : 0.0f;
    }
 
    float getDischargingPower()
    {
        return (data.current < 0) ? -data.power : 0.0f;
    }
 
    float getAbsolutePower()
    {
        return fabsf(data.power);
    }
 
    float getCurrent() override
    {
        return data.current;
    }
 
    int16_t  getCurrentRaw()
    {
        return data.currentRaw;
    }
 
    void reset() override
    {
        setRegBit(REG_MODE, 5);
        hal->delay(50);
        clrRegBit(REG_MODE, 5);
        hal->delay(100);
    }
 
    void sleep()
    {
        if (setRegBit(REG_MODE, 0)) {
            data.sleepModeEnabled = true;
        }
    }
 
    bool isSleepModeEnabled()
    {
        return getRegBit(REG_MODE, 0);
    }
 
    void wakeup()
    {
        if (clrRegBit(REG_MODE, 0)) {
            data.sleepModeEnabled = false;
        }
    }
 
    void setLowBatterySOCThreshold(uint8_t threshold)
    {
        if (threshold > 63) {
            threshold = 63;
        }
        // Read low SOC threshold
        int lowSoc = readReg(REG_LOW_SOC_THLD);
        if (lowSoc >= 0) {
            lowSoc &= 0xC0;
            lowSoc |= (threshold & 0x3F); // Low 6 bits valid
            writeReg(REG_LOW_SOC_THLD, lowSoc);
        }
    }
 
    void setOverTemperatureThreshold(uint8_t threshold)
    {
        if (threshold > 127) {
            threshold = 127;
        }
        writeReg(REG_OT_THLD, threshold & 0x7F);
    }
 
    void setThermalDieMeasurement(bool enable)
    {
        if (enable) {
            setRegBit(REG_COMM_CONFIG, 6);
        } else {
            clrRegBit(REG_COMM_CONFIG, 6);
        }
        data.thermalDieEnabled = enable;
    }
 
    bool isThermalDieMeasurementEnabled()
    {
        return data.thermalDieEnabled;
    }
 
    void setCurrentMeasurement(bool enable)
    {
        if (enable) {
            setRegBit(REG_COMM_CONFIG, 5);
        } else {
            clrRegBit(REG_COMM_CONFIG, 5);
        }
        data.currentMeasurementEnabled = enable;
    }
 
    bool isCurrentMeasurementEnabled()
    {
        return data.currentMeasurementEnabled;
    }
 
    void setBatteryDetection(bool enable)
    {
        if (enable) {
            setRegBit(REG_COMM_CONFIG, 4);
        } else {
            clrRegBit(REG_COMM_CONFIG, 4);
        }
        data.batteryDetectionEnabled = enable;
    }
 
    bool isBatteryVoltageMeasurementEnabled()
    {
        return data.batteryDetectionEnabled;
    }
 
    void setCurrentSenseResistor(CurrentSenseResistor resistorValue)
    {
        int val = readReg(REG_COMM_CONFIG);
        if (val < 0) return;
 
        val = (val & ~0x03) | (resistorValue & 0x03);
        writeReg(REG_COMM_CONFIG, val);
        data.senseResistor = resistorValue;
    }
 
    CurrentSenseResistor getCurrentSenseResistor()
    {
        return data.senseResistor;
    }
 
 
    IRQStatus getIRQStatus()
    {
        return data.irqStatus;
    }
 
    void enableIRQ(IRQEnable irq)
    {
        enableIRQ(irq, true);
    }
 
    void disableIRQ(IRQEnable irq)
    {
        enableIRQ(irq, false);
    }
 
    void disableAllIRQ()
    {
        writeReg(REG_IRQ_ENABLE, 0x00);
    }
 
    void enableIRQ(IRQEnable irq, bool enable, bool low_level_trigger = true)
    {
        int val = readReg(REG_IRQ_ENABLE);
        if (val < 0) {
            return;
        }
        // Set trigger mode: bit7=0 for low level, bit7=1 for low pulse.
        if (low_level_trigger) {
            val &= ~0x80;  // Low level trigger
        } else {
            val |= 0x80;   // Low pulse trigger
        }
        // Set IRQ enable bit
        if (enable) {
            val |= irq;
        } else {
            val &= ~irq;
        }
        writeReg(REG_IRQ_ENABLE, val);
    }
 
    void clearIRQStatus()
    {
        writeReg(REG_IRQ_STATUS, 0x00);
        hal->delay(2);
        writeReg(REG_IRQ_STATUS, 0x0F);
        data.irqStatus = IRQ_STATUS_NONE;
    }
 
    void setOperatingMode(OperatingMode mode)
    {
        switch (mode) {
        case OPERATING_MODE_HIGH_PRECISION:
        case OPERATING_MODE_NORMAL:
        case OPERATING_MODE_LOW_POWER:
            break;
        default:
            return;
        }
        writeReg(REG_OPERATING_MODE, mode);
        data.operatingMode = mode;
    }
 
    OperatingMode getOperatingMode()
    {
        // Read operating mode
        int opMode = readReg(REG_OPERATING_MODE);
        if (opMode >= 0) {
            data.operatingMode = static_cast<OperatingMode>(opMode & 0x07);
        }
        return data.operatingMode;
    }
 
    bool writeGaugeData(uint8_t *data, uint8_t len)
    {
        if (len != 128 || data == NULL)return false;
        // Reset gauge first
        writeReg(REG_MODE, 0x01);
        hal->delay(50);
        writeReg(REG_MODE, 0x00);
        hal->delay(50);
 
        // Enabled BROM register
        clrRegBit(REG_PARA_CONFIG, 0);
        setRegBit(REG_PARA_CONFIG, 0);
        // Write data to buffer
        for (uint8_t i = 0; i < 128; i++) {
            writeReg(REG_BROM, data[i]);
        }
 
        // Reenable ROM register
        clrRegBit(REG_PARA_CONFIG, 0);
        setRegBit(REG_PARA_CONFIG, 0);
 
        return compareGaugeData(data, len);
    }
 
    bool compareGaugeData(uint8_t *data, uint8_t len)
    {
        if (len != 128 || data == NULL)return false;
        // Reset gauge to load new data
        uint8_t buffer[128];
        memset(buffer, 0, sizeof(buffer));
        // Reenable BROM register
        clrRegBit(REG_PARA_CONFIG, 0);
        setRegBit(REG_PARA_CONFIG, 0);
        for (uint8_t i = 0; i < 128; i++) {
            buffer[i] = readReg(REG_BROM);
        }
        // Disable BROM register
        clrRegBit(REG_PARA_CONFIG, 0);
        // Set data interface
        setRegBit(REG_PARA_CONFIG, 4);
        // Reset gauge
        setRegBit(REG_MODE, 5);
        clrRegBit(REG_MODE, 5);
 
        return memcmp(data, buffer, 128) == 0;
    }
 
    void enableWDT()
    {
        setRegBit(REG_PARA_CONFIG, 5);
    }
 
    void disableWDT()
    {
        clrRegBit(REG_PARA_CONFIG, 5);
    }
 
private:
    bool initImpl(uint8_t param) override
    {
        data.chipID = getChipID();
        if (data.chipID != AXP2602_CHIP_ID) {
            SENSORLIB_LOG_E("Chip id not match : %02X\n", data.chipID);
            return false;
        }
        reset();    // Reset Configuration
        hal->delay(100);
        wakeup();   // Wake Up Chip
        setCurrentSenseResistor(SENSE_RESISTOR_10_MOHM);
        setOperatingMode(OPERATING_MODE_NORMAL);
        data.sleepModeEnabled = isSleepModeEnabled();
        return true;
    }
 
protected:
    GaugeData data;
 
    static constexpr uint8_t REG_AXP2602_ID = 0x00;
    static constexpr uint8_t REG_BROM = 0x01;
    static constexpr uint8_t REG_MODE = 0x02;
    static constexpr uint8_t REG_PARA_CONFIG = 0x03;
    static constexpr uint8_t REG_VBAT_ADC_HIGH = 0x04;
    static constexpr uint8_t REG_VBAT_ADC_LOW = 0x05;
    static constexpr uint8_t REG_TEMP_RESULT = 0x06;
    static constexpr uint8_t REG_SOH = 0x07;
    static constexpr uint8_t REG_SOC = 0x08;
 
    static constexpr uint8_t REG_TIME_TO_EMPTY_HIGH = 0x0A;
    static constexpr uint8_t REG_TIME_TO_EMPTY_LOW = 0x0B;
    static constexpr uint8_t REG_TIME_TO_FULL_HIGH = 0x0C;
    static constexpr uint8_t REG_TIME_TO_FULL_LOW = 0x0D;
    static constexpr uint8_t REG_LOW_SOC_THLD = 0x0E;
    static constexpr uint8_t REG_OT_THLD = 0x0F;
 
    static constexpr uint8_t REG_COMM_CONFIG = 0x11;
    static constexpr uint8_t REG_IBAT_ADC_HIGH = 0x14;
    static constexpr uint8_t REG_IBAT_ADC_LOW = 0x15;
    static constexpr uint8_t REG_RDC25_CONFIG_HIGH = 0x1A;
    static constexpr uint8_t REG_RDC25_CONFIG_LOW = 0x1B;
    static constexpr uint8_t REG_QMAX_CONFIG_HIGH = 0x1E;
    static constexpr uint8_t REG_QMAX_CONFIG_LOW = 0x1F;
 
    static constexpr uint8_t REG_IRQ_STATUS = 0x20;
    static constexpr uint8_t REG_IRQ_ENABLE = 0x21;
    static constexpr uint8_t REG_TDIE_ADC_HIGH = 0xC2;
    static constexpr uint8_t REG_TDIE_ADC_LOW = 0xC3;
    static constexpr uint8_t REG_RDC25_QMAX_SEL = 0xC5;
    static constexpr uint8_t REG_OPERATING_MODE = 0xC6;
 
    static constexpr uint8_t AXP2602_CHIP_ID = 0x1C;
};
 
#endif