SDK

BQ25896 charger

The chip that charges a Kode Dot, picks its power source, boosts 5 V for the header and switches it off: every register, and the driver over them.

What it is

The BQ25896 from Texas Instruments decides where a Kode Dot's power comes from and what happens to the battery. It does four jobs:

1. It charges the cell from USB-C.
2. It feeds the board from the cable, the battery, or both, and keeps that supply, SYS, at a usable voltage.
3. It runs backwards: from the cell it makes 5 V on its input line, VBUS, which reaches the expansion header. This is the boost, also called OTG.
4. It holds the switch between the battery and the board, the BATFET. Opening it is the deepest off the hardware has, ship mode: the chip then draws 12 µA from the cell and nothing else runs.

It accepts 3.9 to 14 V in and charges at up to 3 A. Datasheet: TI SLUSC76C.

How it is connected

flowchart LR
subgraph dot["On the Kode Dot"]
  ao["AO_Power<br/>on the ESP32-P4"] -- "I2C, 0x6B" --> bq["BQ25896"]
  bot["bottom button"] -- "QON" --> bq
  bq -- "SYS" --> board["the board"]
  bq -- "BAT, through the BATFET" --> cell["1000 mAh cell"]
  bq -- "VBUS, boost" --> hdr["expansion header"]
end
usb["USB-C cable"] -- "VBUS" --> bq
class usb ext
class ao ao
class bq chip
class cell chip

The chip answers at 0x6B on the shared I2C bus (KBSP_I2C_ADDR_CHARGER). AO_Power owns it: nothing else in the system writes to it. Software reaches it through AO_Power's requests, kode_power_charge(), kode_power_charge_limit() and kode_power_boost(), and AO_Power publishes a reading every 2 s. Ship mode has one door, the console verb ship_mode; the facade has no call for it. The calls kode_power_sleep() and kode_power_off() rest the Kode Dot through AO_LowPower and never reach the charger (sdk/kaos/lowpower).

The wiring

The wiring decides more than the firmware does:

• The cable decides charging and boosting. A circuit that senses USB power drives the charge-enable pin CE and, through transistor Q5, the boost pin OTG. With a cable in, charging is allowed and the boost is physically impossible. On battery alone, the reverse. The P4 drives neither pin.
• The input limit is a resistor. R58, 470 Ω on the ILIM pin, sets the input current ceiling. A USB chip on the board drives PSEL, which tells the BQ25896 whether a computer or a wall adapter is plugged in.
• The temperature comes from the pack. R65 (5.23 kΩ) and R74 (30.1 kΩ) form the divider on the TS pin, with the pack's 10 kΩ thermistor on pin 2 of J7, the battery connector. This is the only temperature the charger sees.
• The bottom button is QON. Pressing it wakes a Kode Dot in ship mode; holding it 16 to 23 s with no cable power-cycles the whole board.
• PG, STAT and INT go nowhere the firmware reads. AO_Power polls the status over I2C instead.

The boot policy

At every boot AO_Power writes one policy, each line read back, from the cell's numbers in kbsp_cell.h. The chip keeps its registers when the P4 is reflashed, so the policy is written every time, never assumed:

When the Kode Dot rests, AO_Power writes conv_rate back to 0 on every round, in case a bench tool left the ADC continuous. While it sleeps, the minute's reading needs no conversion: the status registers and the gauge are read as they are, so a cable that appeared is seen fresh (sdk/kaos/power).

The pack takes charge between 10 and 45 °C, a narrower window than the chip's. AO_Power reads the temperature fault at every poll and holds charging off while it reads anything but normal. A boost request is refused below 3600 mV (KBSP_CELL_BOOST_MIN_MV), and a running boost is stopped below 3300 mV (KBSP_CELL_BOOST_STOP_MV) or on a boost fault.

The driver is one table

kdrv_bq25896.c describes every field of REG00 to REG14 as a row: register, shift, width, offset, step, the codes it accepts, and whether it is read-write, read-only or self-clearing. kdrv_bq25896_get() and kdrv_bq25896_set() take a field and a value in its unit (mV, mA, °C, a code).

A set does three things:

1. It rounds to the field's step and refuses a value out of range.
2. It does a masked read-modify-write, so the other fields of the register keep their bits.
3. It reads the register back.

A self-clearing bit is written and not checked, since it returns to 0 by itself. The driver holds no policy at all: what to write is AO_Power's decision. Three things are typed calls because a table cannot express them: the ADC block, the fault register and ship mode.

Specifications

The board

The settings registers

The registers 0x00 to 0x0A: settings. [7] is bit 7, [5:0] bits 5 to 0. Reset values are the datasheet's, after a real power-on; a reflash of the P4 does not reset them.

The status and reading registers

The registers 0x0B to 0x14: status, faults, thresholds, the ADC results and the part number.

The codes

What the code of each coded field means.

The driver

Gotchas

Example code

Ask AO_Power to charge the cell at 256 mA instead of the 512 mA it writes at boot. With the app running, type pmic field="ichg_ma" on the console: the answer reads 256.

/*
 * charge_limit.c - 2026-10-28 - from Kode with love
 *
 * Asks AO_Power, the owner of the Kode Dot's BQ25896, to charge the cell at
 * 256 mA, then keeps the app alive so the console stays up. Type
 * pmic field="ichg_ma" on the console and the value reads 256.
 */
#include "kode.h"
 
/* Bring the system up, ask for the new current, then idle. */
void app_main(void)
{
    kode_init();
    kode_power_charge_limit(256);
 
    while (1) {
        kode_delay_ms(1000);
    }
}

Compiled against the SDK with ESP-IDF v6.1 on 2026-10-28. TBD: a run on a Kode Dot.

In the SDK

• components/kdrv/power: the driver, kdrv_bq25896.c, beside the gauge's.
• kdrv_bq25896.h: every field, the ADC and fault structures, the calls.
• components/kaos/power: AO_Power, the owner, with the boot policy.