MAX17055 Battery Fuel Gauge

Latest Version: 1.0.2

The MAX17055 is a low-power fuel-gauge IC that implements the Maxim ModelGauge m5 EZ algorithm. It measures battery voltage, current and temperature to produce fuel gauge results. Its typical power consumption is 7μA.

You can view the library’s source code on GitHub. Click here to see information on other versions of this library.

To include this library in your project, add #require "MAX17055.device.lib.nut:1.0.2" at the top of your device code.

Class Usage

Constructor: MAX17055(i2cBus[, i2cAddress])

Parameters

Parameter	Type	Required?	Description
i2cBus	Object	Yes	The imp I²C bus that the fuel gauge is connected to. The bus must be pre-configured; the library will not configure the bus
i2cAddress	Integer	No	The I²C address of the fuel gauge. Default: `0x6C`

Return Value

Nothing.

Example

#require "MAX17055.device.lib.nut:1.0.2"

local i2c = hardware.i2cKL;
i2c.configure(CLOCK_SPEED_400_KHZ);
fuelGauge <- MAX17055(i2c);

Class Methods

init(settings[, callback])

This method initializes the fuel gauge. If a power on reset alert is detected, the settings parameter will be used to re-configure the fuel gauge. Initialization is an asynchronous process; the optional callback function, if provided, will be triggered when initialization is complete.

Parameters

Parameter	Type	Required?	Description
settings	Table	Yes	A table of configuration settings — see Settings Table Options, below
callback	Function	No	A function that will be triggered when initialization is complete. It has one (required) parameter of its own which will receive an error message string if an error was encountered during initialization, otherwise `null`

Settings Table Options

Key	Type	Required?	Description
desCap	Integer	Yes	The designed capacity of the battery in mAh
senseRes	Float	Yes	The size of the sense resistor in Ω
chrgTerm	Integer	Yes	The battery’s termination charge in mA
emptyVTarget	Float	Yes	The empty target voltage in V. Resolution is 10mV
recoveryV	Float	Yes	A recovery voltage in V. Once the cell voltage rises above this point, empty voltage detection is re-enabled. Resolution is 40mV
chrgV	Integer	Yes	The charge voltage. Use the class constants MAX17055_V_CHRG_4_2 (4.2V) or MAX17055_V_CHRG_4_4_OR_4_35 (4.35V or 4.4V)
battType	Integer	Yes	Select the type of battery from the following class enum: MAX17055_BATT_TYPE.LiCoO2 (most common), MAX17055_BATT_TYPE.NCA_NCR or MAX17055_BATT_TYPE.LiFePO4

Return Value

Nothing.

Example

local settings = {
    "desCap"       : 2000, // mAh
    "senseRes"     : 0.01, // ohms
    "chrgTerm"     : 20,   // mA
    "emptyVTarget" : 3.3,  // V
    "recoveryV"    : 3.88, // V
    "chrgV"        : MAX17055_V_CHRG_4_2,
    "battType"     : MAX17055_BATT_TYPE.LiCoO2
}

fuelGauge.init(settings, function(err) {
    if (err != null) {
        server.error(err);
    } else {
        server.log("Fuel gauge initialized.");
        // Start using fuel gauge.
    }
});

getStateOfCharge()

This method returns the gauge’s reported remaining capacity in mAh and state-of-charge percentage output. The reported capacity is protected from making sudden jumps during load changes.

Return Value

Table — Contains the keys percent and capacity, each with values in mAh.

Example

local state = fuelGauge.getStateOfCharge();
server.log("Remaining cell capacity: " + state.capacity + "mAh");
server.log("Percent of battery remaining: " + state.percent + "%");

getTimeTilEmpty()

This method returns the estimated time to empty (TTE) for the battery under present temperature and load conditions. The TTE value is determined by relating the average capacity to the average current. The corresponding average current filtering gives a delay in TTE, but provides more stable results.

Note The battery may require a few charge cycles to pass before this call returns a non-default value.

Return Value

Float — The estimated time in hours until the battery is empty.

Example

local tte = fuelGauge.getTimeTilEmpty();
server.log("Time til empty: " + tte + " hours");

getTimeTilFull()

This method returns the estimated time to full (TTF) for the battery under present conditions. The TTF value is determined by determining the constant current and constant voltage portions of the charge cycle based on experience of prior charge cycles. Time to full is then estimated by comparing present charge current to the charge termination current. Operation of the TTF register assumes all charge profiles are consistent in the application.

Note The battery may require a few charge cycles to pass before this call returns a non-default value.

Return Value

Float — The estimated time in hours until the battery is fully charged.

Example

local ttf = fuelGauge.getTimeTilFull();
server.log("Time til full: " + ttf + " hours");

getVoltage()

This method returns the voltage measured between BATT and CSP pins.

Return Value

Float — A voltage in V.

Example

local voltage = fuelGauge.getVoltage();
server.log("BATT-to-CASP voltage: " + voltage + "V");

getCurrent()

This method measures the voltage between the CSP and CSN pins. Voltages outside the minimum and maximum register values are reported as the minimum or maximum value. The measured voltage value is then divided by the sense resistance and converted to mA. The value of the sense resistor determines the resolution and the full scale range of the current readings.

Return Value

Float — A current in mA.

Example

local current = fuelGauge.getCurrent();
server.log("Current: " + current + "mA");

getAvgCurrent()

This method returns an average of current readings in mA.

Return Value

Float — A current in mA.

Example

local current = fuelGauge.getAvgCurrent();
server.log("Average current: " + current + "mA");

getAvgCapacity()

This method returns the calculated available capacity of the battery based on all inputs from the ModelGauge m5 algorithm, including empty compensation. This provides unfiltered results. Jumps in the reported values can be caused by abrupt changes in load current or temperature.

Return Value

Float — A capacity result in mAh.

Example

local capacity = fuelGauge.getAvgCapacity();
server.log("Cell capacity: " + capacity + "mAh");

getTemperature()

Returns the internal die temperature in degrees Celsius.

Return Value

Float — A temperature in °C.

Example

local temp = fuelGauge.getTemperature();
server.log("Temp: " + temp + "°C");

enableAlerts(alerts)

Use this method to enable or disable the alert pin, battery or percentage change alerts.

Parameters

Parameter	Type	Required?	Description
alerts	Table	Yes	A table with the alerts to be enabled/disabled (see below)

Enable Alerts

Key	Type	Required?	Description
enChargeStatePercentChange	Boolean	No	Enable or disable an alert when the charge percentage crosses an integer percentage boundary, such as 50.0%, 51.0%, etc
enAlertPin	Boolean	No	Enable or disable the alert interrupt pin. Note This pin is not connected on the impC001 breakout board, but can be connected via Test Point 4 (TP4)

Return Value

Nothing.

Example

// Enable alert when battery is inserted, disable percent change alert
local enAlerts = {
    "enChargeStatePercentChange" : false,
    "enBattInsert" : true
};

fuelGauge.enableAlerts(enAlerts);

getAlertStatus()

This method returns a table containing the current status of flags related to alerts. Alerts need to be reset by calling clearStatusAlerts().

Return Value

Table — Contains the following keys:

Key	Type	Description
powerOnReset	Boolean	`true` when the system detects that a software or hardware power on reset event has occurred
chargeStatePercentChange	Boolean	When detection is enabled, this is `true` whenever the charge percentage crosses an integer percentage boundary, such as 50.0%, 51.0%, etc. This flag must be cleared to detect next event
raw	Integer	Raw status register value for debugging purposes

Example

local status = fuelGauge.getAlertStatus();
foreach (alert, state in status) {
    if (state && alert != "raw") server.log("Alert detected: " + alert);
}

clearStatusAlerts()

This method clears all of the status alerts flags, so that the next event can be detected.

Return Value

Nothing.

Example

local status = fuelGauge.getAlertStatus();
local alertDetected = false;
foreach (alert, state in status) {
    if (state) {
        alertDetected = true;
        server.log("Alert detected: " + alert);
    }
}

if (alertDetected) fuelGauge.clearStatusAlerts();

getDeviceRev()

This method returns the device revision information. The initial silicon revision is 0x4010.

Return Value

Integer — A revision number.

Example

local rev = fuelGauge.getDeviceRev();
server.log(format("Fuel gauge revision: 0x%04X", rev));

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release
1.0.1	GitHub	Bug fixes: capacity calculation, refresh bit mask, scope issue in _verify() method; typo in register name variable; updated example to use 4.2V charge (more common battery); simplified twos-complement calculation; updated state of charge percentage to float
1.0.2	GitHub	Fixed bug in enableAlerts(); removed alerts not supported by current hardware (breakout boards); improved init error messaging

License

This library is licensed under the MIT License.