Latest Version: 1.0.0
This library provides a driver for the Texas Instruments BQ24295 switch-mode battery charge and system power management device for single-cell Li-Ion and Li-polymer batteries. The BQ24295 supports high input voltage fast charging and communicates over an I²C interface.
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 "BQ24295.device.lib.nut:1.0.0" at the top of your device code.
The constructor does not configure the battery charger. It is therefore strongly recommended that the enable() method is called to configure the charger with settings for you battery immediately after calling the constructor and on cold boots.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| i2cBus | imp i2c bus object | Yes | The imp I²C bus that the BQ24295 is connected to. The I²C bus must be pre-configured — the library will not configure the bus |
| i2cAddress | Integer | No | The BQ24295’s I²C address. Default: 0xD6 |
#require "BQ24295.device.lib.nut:1.0.0"
// Alias and configure an impC001 I2C bus
local i2c = hardware.i2cKL;
i2c.configure(CLOCK_SPEED_400_KHZ);
// Instantiate a BQ24295 object
batteryCharger <- BQ24295(i2c);
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. See Setting Up The BQ24295 Library For Your Battery for guidance.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| settings | Table | No | A table of settings — see Settings Options, below |
| Key | Type | Description |
|---|---|---|
| voltage | Float | The desired charge termination voltage in Volts. Range: 3.504V - 4.400V. Default: 4.208V |
| current | Integer | The desired fast-charge current limit in mA. Range: 512mA - 3008mA. Default: 1024mA |
| chrgTermLimit | Integer | The current at which the charge cycle will be terminated when the battery voltage is above the recharge threshold. Range: 128mA - 2048mA. Default: 256mA |
Nothing.
// Configure battery charger 4.2V to a maximum of 2000mA
local settings = { "voltage" : 4.2,
"current" : 2000 };
batteryCharger.enable(settings);
This method disables the device's charging capabilities. The battery will not charge until enable() is called.
Nothing.
// Disable charging
batteryCharger.disable();
This method gets the charge termination voltage for the battery.
Float — The charge voltage limit in Volts.
local voltage = batteryCharger.getChrgTermV();
server.log("Charge Termination Voltage: " + voltage + "V");
This method reports the type of power source connected to the charger input as well as the resulting input current limit.
Table — An input status report with the following keys:
| Key | Type | Description |
|---|---|---|
| vbus | Integer | Possible input states — see VBUS Status, below, for details |
| currLimit | Integer | 100-3000mA |
| VBUS Status Constant | Value |
|---|---|
| BQ24295_VBUS_STATUS.UNKNOWN | 0x00 |
| BQ24295_VBUS_STATUS.USB_HOST | 0x40 |
| BQ24295_VBUS_STATUS.ADAPTER_PORT | 0x80 |
| BQ24295_VBUS_STATUS.OTG | 0xC0 |
local inputStatus = batteryCharger.getInputStatus();
local msg = "";
switch(inputStatus.vbus) {
case BQ24295_VBUS_STATUS.UNKNOWN:
msg = "No input or DPDM detection incomplete";
break;
case BQ24295_VBUS_STATUS.USB_HOST:
msg = "USB host";
break;
case BQ24295_VBUS_STATUS.ADAPTER_PORT:
msg = "Adapter port";
break;
case BQ24295_VBUS_STATUS.OTG:
msg = "OTG";
break;
}
server.log("Charging mode: " + msg);
server.log("Input current limit: " + inputStatus.currLimit);
This method reports the battery charging status.
Integer — A charging status constant:
| Charging Status Constant | Value |
|---|---|
| BQ24295_CHARGING_STATUS.NOT_CHARGING | 0x00 |
| BQ24295_CHARGING_STATUS.PRE_CHARGE | 0x10 |
| BQ24295_CHARGING_STATUS.FAST_CHARGE | 0x20 |
| BQ24295_CHARGING_STATUS.CHARGE_TERMINATION_DONE | 0x30 |
local status = batteryCharger.getChrgStatus();
switch(status) {
case BQ24295_CHARGING_STATUS.NOT_CHARGING:
server.log("Battery is not charging");
// Do something
break;
case BQ24295_CHARGING_STATUS.PRE_CHARGE:
server.log("Battery pre-charging");
// Do something
break;
case BQ24295_CHARGING_STATUS.FAST_CHARGING:
server.log("Battery is fast charging");
// Do something
break;
case BQ24295_CHARGING_STATUS.CHARGE_TERMINATION_DONE:
server.log("Battery charge termination done");
// Do something
break;
}
This method reports possible charger faults.
Table — A charger fault report with the following keys:
| Key/Fault | Type | Description |
|---|---|---|
| watchdog | Bool | true if watchdog timer has expired, otherwise false |
| boost | Bool | true if VBUS overloaded in OTG, VBUS is OVP, or the battery is in any state that prevents the boost function from being started; otherwise false |
| chrg | Integer | A charging fault. See Charging Faults, below, for possible values |
| batt | Bool | true if battery OVP, otherwise false |
| ntc | Integer | An NTC fault. See NTC Faults, below, for possible values |
| Charging Fault Constant | Value |
|---|---|
| BQ24295_CHARGING_FAULT.NORMAL | 0x00 |
| BQ24295_CHARGING_FAULT.INPUT_FAULT | 0x10 |
| BQ24295_CHARGING_FAULT.THERMAL_SHUTDOWN | 0x20 |
| BQ24295_CHARGING_FAULT.CHARGE_TIMER_EXPIRATION | 0x30 |
| NTC Fault Constant | Value |
|---|---|
| BQ24295_NTC_FAULT.NORMAL | 0x00 |
| BQ24295_NTC_FAULT.TS_HOT | 0x01 |
| BQ24295_NTC_FAULT.TS_COLD | 0x02 |
local faults = batteryCharger.getChrgFaults();
server.log("Fault Report:");
server.log("-----------------------------------");
if (faults.watchdog) server.log("Watchdog Timer Fault reported");
if (faults.boost) server.log("Boost Fault reported");
if (faults.batt) server.log("VBAT too high");
switch(faults.chrg) {
case BQ24295_CHARGING_FAULT.NORMAL:
server.log("Charging OK");
break;
case BQ24295_CHARGING_FAULT.INPUT_FAULT:
server.log("Charging NOT OK - Input Fault reported: OVP or bad source");
break;
case BQ24295_CHARGING_FAULT.THERMAL_SHUTDOWN:
server.log("Charging NOT OK - Thermal Shutdown reported");
break;
case BQ24295_CHARGING_FAULT.CHARGE_TIMER_EXPIRATION:
server.log("Charging NOT OK - Charge Timer expired");
break;
}
switch(faults.ntc) {
case BQ24295_NTC_FAULT.NORMAL:
server.log("NTC OK");
break;
case BQ24295_NTC_FAULT.TS_COLD:
server.log("NTC NOT OK - TS Cold");
break;
case BQ24295_NTC_FAULT.TS_HOT:
server.log("NTC NOT OK - TS Hot");
break;
}
server.log("-----------------------------------");
This method provides a software reset which clears all of the BQ24295’s register settings.
Note This will reset the charge voltage and current to the register defaults: 4.208V and 1024mA. Please ensure that you confirm these are suitable for your battery — see Setting Up The BQ24295 Library For Your Battery for guidance. If the defaults are not appropriate for your battery, make sure you call enable() with the correct settings immediately after calling reset().
Nothing.
// Reset the BQ24295
batteryCharger.reset();
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 |
This library is licensed under the MIT License.