IP5108

📦 Latest release: v1.2.0 — INT-pin wake detection, register bug fixes, I2C batching, and a non-linear battery-percentage curve. See the release notes for details.

A high‑level Arduino library for the IP5108 Power Management IC — the all‑in‑one Li‑ion charge/boost controller found in many power banks and portable devices.
This library lets you control charging, boost output, flashlight mode, and battery monitoring over I²C, with clean APIs designe.

---

✨ Features

• Enable/disable:
  • Charger
  • Boost output
  • Flashlight / LED light
  • Auto‑power functions
• Configure:
  • Shutdown time
  • Light shutdown current
  • Battery type & charge voltage
  • Boost current limit
• Read:
  • Battery voltage, open‑circuit voltage, current
  • Charging state & status flags
  • Button press events (short, long, double)
  • Battery percentage (non‑linear OCV curve, not a straight voltage map)
• Optional datasheet‑correct wake detection via the IC's INT/L3 pin
• Minimal dependencies, Arduino‑IDE & PlatformIO ready

---

📦 Installation

Arduino IDE

1. Download this repository as a ZIP.
2. In Arduino IDE: Sketch → Include Library → Add .ZIP Library…
3. Select the downloaded ZIP file.

PlatformIO

Add to your platformio.ini:

lib_deps =
    https://github.com/milad-nikpendar/IP5108

---

🔌 Wiring

IP5108 Pin	ESP32 Pin	Notes
SDA (L2)	GPIO21 (example)	Any I²C‑capable pin. Needs an external pull‑up to VREG (datasheet §2)
SCL (L1)	GPIO22 (example)	Any I²C‑capable pin. Needs an external pull‑up to VREG (datasheet §2)
INT (L3)	Any free GPIO (optional, but recommended)	See "Wake detection & INT" below
VCC	3.3 V / 5 V	Per datasheet
GND	GND	Common ground

Default I²C address: 0x75
I²C speed: up to 400 kHz

⚠️ Wake detection & INT (read this if begin() connects unreliably)

The IP5108 only re-checks whether SDA/SCL are pulled up to VREG at the instant it wakes from sleep (button press, load insertion, or 5V charger insertion). If that check passes it enters I²C mode and drives L3/INT high; if it doesn't, the IC falls back to LED‑indicator mode instead (the same three pins double as a 4‑LED battery‑level driver on this chip family) until the next wake — retrying I²C afterwards cannot recover it for the rest of that power session, and even "just" a normal I²C transaction touching SDA/SCL before the IC has finished this check can itself disturb the result.

If your board wires L3/INT to a spare GPIO, pass it to begin() (see Quick Start below): the library will then wait for INT to read HIGH before touching SDA/SCL at all, which is what the datasheet specifies and is the only fully reliable way to avoid this race. Without INT wired, begin() falls back to a best‑effort I²C probe with no such guarantee — on some boards/power paths (e.g. a battery‑only cold boot vs. a charger‑fed boot, which don't share the same rail‑settling timing) this can intermittently fail to connect even with correct pull‑ups.

---

🚀 Quick Start

#include <Wire.h>
#include <IP5108.h>

IP5108 pmic;

// GPIO wired to the IC's L3/INT pin, or -1 if it isn't wired on your board
// (see "Wake detection & INT" above).
const int8_t INT_PIN = -1;

void setup() {
  Serial.begin(115200);
  Wire.begin(21, 22, 400000); // SDA, SCL, freq

  if (!pmic.begin(0x75, &Wire, INT_PIN)) {
    Serial.println("IP5108 not found!");
    while (1) delay(1000);
  }

  pmic.Charger(true);       // Enable charging
  pmic.Boost(true);         // Enable boost output
  pmic.FlashLight(true);    // Turn on flashlight
}

void loop() {
  Serial.printf("Battery: %.3f V, %.3f A, %d%%\n",
                pmic.BatteryVoltage(),
                pmic.BatteryCurrent(),
                pmic.battery_percentage());
  delay(1000);
}

---

📖 API Overview

Method	Description
begin(addr, wire, intPin = -1, intTimeoutMs = 2000)	Initialize with I²C address and Wire instance. If intPin is given, waits for it to read HIGH before touching the bus at all (see "Wake detection & INT")
waitForI2CReady(timeoutMs = 2000)	Blocks until the configured INT pin reads HIGH; returns true immediately if no INT pin was configured
Charger(bool)	Enable/disable battery charging
Boost(bool)	Enable/disable boost output
FlashLight(bool)	Enable/disable flashlight
BatteryVoltage()	Get battery (charger-side) voltage, in Volts
BatteryOCVoltage()	Get battery open-circuit (IR-compensated) voltage, in Volts
BatteryCurrent()	Get battery current, in Amps
battery_percentage()	Estimate battery percentage: 0-100, or -1 if unknown
ChargingStatus()	Get charging status flags
setDoublePressAction(actionType_t)	Configure the double‑press button action
setLongPressAction(actionType_t, LongPressTime_t)	Configure the long‑press button action and its hold duration

(See IP5108.h for full API list.)

---

🛠 Examples

• Basic_Init – Initialize and enable charger
• Battery_Monitor – Print battery voltage, current, and percentage

---

🧰 Development Notes

• Designed for ESP32 under Arduino framework.
• Uses TwoWire for I²C — pass custom SDA/SCL pins if needed.
• All register definitions are based on the IP5108 datasheet.
• Includes helper functions for safe updates and bit‑mask writes.

---

🧾 License

This project is licensed under the MIT License – see LICENSE for details.

✍️ Author

Milad Nikpendar
GitHub: milad-nikpendar/IP5108
Email: milad82nikpendar@gmail.com