Skip to main content

BQ25895

Latest Version: 2.0.0

The library provides a driver for the BQ25895 and the BQ25895M switch-mode battery charge and system power path management devices for single-cell Li-Ion and Li-polymer batteries. Theses ICs support high input voltage fast charging and communicates over an I²C interface. The BQ25895 and the BQ25895M have different default settings — please see the enable() method for details of the default charge settings.

Note 1 When using an impC001 breakout board without a battery connected it is recommended that you always enable the battery charger with BQ25895 default settings. If a battery is connected, please follow the instructions in the library repo’s Examples directory to determine the correct settings for your battery.

Note 2 This library supersedes the BQ25895M library, which is now deprecated and will not be maintained. We strongly recommend that you update to the the new library, but please be aware that this incorporates a breaking change which you will need to accommodate. Please see the enable() method description for details.

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 "BQ25895.device.lib.nut:2.0.0" at the top of your device code.

Class Usage

Constructor: BQ25895(i2cBus [,i2cAddress])

The constructor does not configure the battery charger. It is recommended that either the enable() method is called and passed settings for your battery, or the disable() method is called immediately after the constructor and on cold boots.

Parameters

Parameter Type Required? Description
i2cBus imp i2c bus object Yes The imp I²C bus that the BQ25895/BQ25895M is connected to. The I²C bus must be pre-configured — the library will not configure the bus
i2cAddress Integer No The BQ25895's I²C address. Default: 0xD4

Example

#require "BQ25895.device.lib.nut:2.0.0"

// Alias and configure an impC001 I2C bus
local i2c = hardware.i2cKL;
i2c.configure(CLOCK_SPEED_400_KHZ);

// Instantiate a BQ25895 object
batteryCharger <- BQ25895(i2c);

Class Methods

enable([settings])

This method configures and enables the battery charger with settings to perform a charging cycle when a battery is connected and an input source is available. It is recommended that this method is called immediately after the constructor and on cold boots with the settings for your battery.

For the BQ25895, the defaults are 4.208V and 2048mA. For the BQ25895M, the defaults are 4.352V and 2048mA, which you apply by adding the key BQ25895MDefaults and the value true in a table of settings passed into the method. Please ensure you confirm that these defaults are suitable for your battery — see the document Setting Up The BQ25895 Library For Your Battery in the library repo for guidance.

IMPORTANT The default settings applied by the library have been changed from those set by this library’s predecessor, the BQ25895M library. You must consider this a breaking change when upgrading to the new library, and ensure your code calls enable() with the correct settings — see the examples below.

Parameters

Parameter Type Required? Description
settings Table No A table of additional settings — see Settings Options, below

Settings Options

Key Type Description
BQ25895MDefaults Boolean Whether to enable the charger with defaults for the BQ25895M part. If true the chargeVoltage is set to 4.352V and currentLimit to 2048mA. Default: false
voltage Float The desired charge voltage in Volts. Range: 3.84-4.608V. Default: 4.208V.
Note If BQ25895MDefaults flag is set to true, this value will be ignored
current Integer The desired fast charge current limit in mA. Range: 0-5056mA. Default: 2048mA.
Note If BQ25895MDefaults flag is set to true, this value will be ignored
setChargeCurrentOptimizer Boolean Identify maximum power point without overload the input source. Default: true
setChargeTerminationCurrentLimit Integer Charge cycle is terminated when battery voltage is above recharge threshold and the current is below termination current. Range: 64-1024mA. Default: 256mA

Return Value

Nothing.

Example 1: Using the BQ25895 with Defaults

// Configure battery charger with default setting for BQ25895,
// ie. a charge voltage of 4.208V and current limit of 2048mA.
batteryCharger.enable();

Example 2: Using the BQ25895 with Other Settings

// Configure battery charger for BQ25895 to charge at 4.0V
// to a maximum of 2000mA
local settings = { "voltage" : 4.0,
                   "current" : 2000 };
batteryCharger.enable(settings);

Example 3: Using the BQ25895M with Defaults

// Configure battery charger with default setting for BQ25895M,
// ie. charge voltage of 4.352V and current limit of 2048mA.
batteryCharger.enable({"BQ25895MDefaults": true});

disable()

This method disables the device's charging capabilities. The battery will not charge until enable() is called.

Return Value

Nothing.

Example

// Disable charging
batteryCharger.disable();

getChargeVoltage()

This method gets the connected battery's current charge voltage.

Return Value

Float — The charge voltage in V.

Example

local voltage = batteryCharger.getChargeVoltage();
server.log("Voltage (charge): " + voltage + "V");

getBatteryVoltage()

This method gets the current battery voltage based on internal ADC conversion.

Return Value

Float — The battery voltage in V.

Example

local voltage = batteryCharger.getBatteryVoltage();
server.log("Voltage (ADC): " + voltage + "V");

getVBUSVoltage()

This method gets the VBUS voltage based on ADC conversion. This is the input voltage.

Return Value

Float — The VBUS voltage in V.

Example

local voltage = batteryCharger.getVBUSVoltage();
server.log("Voltage (VBAT): " + voltage + "V");

getSystemVoltage()

This method gets the system voltage based on the ADC conversion. This the output voltage which can be used to drive other chips in your application. In most impC001-based applications, the system voltage is the impC001 VMOD supply.

Return Value

Float — The system voltage in V.

Example

local voltage = batteryCharger.getSystemVoltage();
server.log("Voltage (system): " + voltage + "V");

getChargingCurrent()

This method gets the measured current going to the battery.

Return Value

Integer — The charging current in mA.

Example

local current = batteryCharger.getChargingCurrent();
server.log("Current (charging): " + current + "mA");

getInputStatus()

This method reports the type of power source connected to the charger input as well as the resulting input current limit.

Return Value

Table — An input status report with the following keys:

Key Type Description
vbusStatus Integer Possible input states — see VBUS Status, below, for details
inputCurrentLimit Integer 100-3250mA

VBUS Status

VBUS Status Constant Value
BQ25895_VBUS_STATUS.NO_INPUT 0x00
BQ25895_VBUS_STATUS.USB_HOST_SDP 0x20
BQ25895_VBUS_STATUS.USB_CDP 0x40
BQ25895_VBUS_STATUS.USB_DCP 0x60
BQ25895_VBUS_STATUS.ADJUSTABLE_HV_DCP 0x80
BQ25895_VBUS_STATUS.UNKNOWN_ADAPTER 0xA0
BQ25895_VBUS_STATUS.NON_STANDARD_ADAPTER 0xC0
BQ25895_VBUS_STATUS.OTG 0xE0

Example

local inputStatus = batteryCharger.getInputStatus();
switch(inputStatus.vbusStatus) {
    case BQ25895_VBUS_STATUS.NO_INPUT:
        server.log("No Input");
        break;
    case BQ25895_VBUS_STATUS.USB_HOST_SDP:
        server.log("USB Host SDP");
        break;
    case BQ25895_VBUS_STATUS.USB_CDP:
        server.log("USB CDP");
        break;
    case BQ25895_VBUS_STATUS.USB_DCP:
        server.log("USB DCP");
        break;
    case BQ25895_VBUS_STATUS.ADJUSTABLE_HV_DCP:
        server.log("Adjustable High Voltage DCP");
        break;
    case BQ25895_VBUS_STATUS.UNKNOWN_ADAPTER:
        server.log("Unknown Adapter");
        break;
    case BQ25895_VBUS_STATUS.NON_STANDARD_ADAPTER:
        server.log("Non Standard Adapter");
        break;
    case BQ25895_VBUS_STATUS.OTG:
        server.log("OTG");
        break;
}

server.log("Input Current Limit = " + inputStatus.inputCurrentLimit);

getChargingStatus()

This method reports the battery charging status.

Return Value

Integer — A charging status constant:

Charging Status Constant Value
BQ25895_CHARGING_STATUS.NOT_CHARGING 0x00
BQ25895_CHARGING_STATUS.PRE_CHARGE 0x08
BQ25895_CHARGING_STATUS.FAST_CHARGE 0x10
BQ25895_CHARGING_STATUS.CHARGE_TERMINATION_DONE 0x18

Example

local status = charger.getChargingStatus();
switch(status) {
    case BQ25895_CHARGING_STATUS.NOT_CHARGING:
        server.log("Battery is not charging");
        // Do something
        break;
    case BQ25895_CHARGING_STATUS.PRE_CHARGE:
        server.log("Battery pre charging");
        // Do something
        break;
    case BQ25895_CHARGING_STATUS.FAST_CHARGING:
        server.log("Battery is fast charging");
        // Do something
        break;
    case BQ25895_CHARGING_STATUS.CHARGE_TERMINATION_DONE:
        server.log("Battery charge termination done");
        // Do something
        break;
}

getChargerFaults()

This method reports possible charger faults.

Return Value

Table — A charger fault report with the following keys:

Key/Fault Type Description
watchdogFault Bool true if watchdog timer has expired, otherwise false
boostFault Bool true if VMBUS overloaded in OTG, VBUS OVP, or battery is too low, otherwise false
chrgFault Integer A charging fault. See Charging Faults, below, for possible values
battFault Bool true if VBAT > VBATOVP, otherwise false
ntcFault Integer An NTC fault. See NTC Faults, below, for possible values

Charging Faults

Charging Fault Constant Value
BQ25895_CHARGING_FAULT.NORMAL 0x00
BQ25895_CHARGING_FAULT.INPUT_FAULT 0x10
BQ25895_CHARGING_FAULT.THERMAL_SHUTDOWN 0x20
BQ25895_CHARGING_FAULT.CHARGE_SAFETY_TIMER_EXPIRATION 0x30

NTC Faults

NTC Fault Constant Value
BQ25895_NTC_FAULT.NORMAL 0x00
BQ25895_NTC_FAULT.TS_COLD 0x01
BQ25895_NTC_FAULT.TS_HOT 0x02

Example

local faults = batteryCharger.getChargerFaults();
server.log("Fault Report");
if (faults.watchdogFault) server.log("Watchdog Timer Fault reported");
if (faults.boostFault) server.log("Boost Fault reported");

switch(faults.chrgFault) {
    case BQ25895_CHARGING_FAULT.NORMAL:
        server.log("Charging OK");
        break;
    case BQ25895_CHARGING_FAULT.INPUT_FAULT:
        server.log("Charging NOT OK - Input Fault reported");
        break;
    case BQ25895_CHARGING_FAULT.THERMAL_SHUTDOWN:
        server.log("Charging NOT OK - Thermal Shutdown reported");
        break;
    case BQ25895_CHARGING_FAULT.CHARGE_SAFETY_TIMER_EXPIRATION:
        server.log("Charging NOT OK - Safety Timer expired");
        break;
}

if (faults.battFault) server.log("VBAT too high");

switch(faults.ntcFault) {
    case BQ25895_NTC_FAULT.NORMAL:
        server.log("NTC OK");
        break;
    case BQ25895_NTC_FAULT.TS_COLD:
        server.log("NTC NOT OK - TS Cold");
        break;
    case BQ25895_NTC_FAULT.TS_HOT:
        server.log("NTC NOT OK - TS Hot");
        break;

reset()

This method provides a software reset which clears all of the BQ25895's register settings.

Note This will reset the charge voltage and current to the register defaults. For the BQ25895, the defaults are 4.208V and 2048mA. For the BQ25895M, the defaults are 4.352V and 2048mA. Please ensure that you confirm these are suitable for your battery — see Setting Up The BQ25895 Library For Your Battery in the library repo for guidance.

If the defaults are not appropriate for your battery, make sure you call enable() with the correct settings immediately after calling reset().

Return Value

Nothing.

Example

// Reset the BQ25895
batteryCharger.reset();

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
2.0.0 GitHub Initial release

License

This library is licensed under the MIT License.