SDK

CW2217 fuel gauge

The chip that measures a Kode Dot's battery voltage and current, how it is woken and read, and every register and driver call over it.

What it is

The CW2217 from CellWise measures the battery cell. It has a voltmeter for the cell, an ammeter that reads the voltage across a 10 mΩ resistor in series with the cell, and a thermistor input. On top of those sits an algorithm that turns the measurements into a charge percentage, a health figure and a count of charge cycles. Datasheet: CW2217EAAD-DS V1.0.

The algorithm needs an 80-byte description of the exact cell, the battery profile, which the chip maker supplies per cell model. No profile for the Kode Dot's cell exists, so none is loaded. The chip works as a voltmeter and an ammeter, and both are exact. The percentage, health, cycle count and average current registers carry no meaning. AO_Power computes the percentage itself from the cell's voltage curve.

How it is connected

flowchart LR
cell["1000 mAh cell"] -- "VBAT" --> cw["CW2217"]
cell -- "R75, 10 mOhm shunt" --> cw
p4["ESP32-P4<br/>AO_Power"] -- "I2C, 0x64" --> cw
cw -. "FG_GPOUT<br/>not routed" .-> p4
class cell chip
class cw chip
class p4 ao

The CW2217 answers at 0x64 on the shared I2C bus (KBSP_I2C_ADDR_GAUGE). AO_Power owns it and claims it as KBSP_RES_GAUGE; nothing else writes to it. The charger, the BQ25896 (sdk/kdrv/bq25896), shares the same owner, because the two chips answer one question between them: the charger knows what the power path is doing, the gauge knows the cell.

The wiring

The wiring decides what the gauge can do:

• The chip runs from the cell. Its I2C side wakes above 2.4 V and stops below 2.2 V. With no battery fitted it does not answer at all, and AO_Power treats it as an optional part that is absent.
• The shunt is R75, 10 mΩ, in series with the cell on the VBAT_SHUNT net, read through a 100 Ω filter on each sense pin. The sense pins are wired so that charging reads positive, as the datasheet defines it. The current agrees with the charger's within one of its 50 mA steps and has the same sign: the gauge read +511 mA while the charger reported 500 mA of charge, measured on a Kode Dot.
• The thermistor pin is not connected. The temperature register reads 0x00, which is −40 °C. The cell's temperature comes from the charger.
• The alarm pin FG_GPOUT reaches neither the P4 nor the expander. The expander's P5 is the IMU's INT1 line. Nothing in the firmware reads a gauge interrupt, and none of the three alarm sources would give a useful signal without a profile.

Bring-up

kdrv_cw2217_init() probes 0x64 for 100 ms, attaches the device and checks that VERSION reads 0xA0. It writes nothing. The chip starts asleep, with CONFIG at 0xF0. AO_Power then calls kdrv_cw2217_wake(), which writes 0x30, waits 20 ms and writes 0x00, and returns at once.

The algorithm needs 900 to 1100 ms to come up, and until it does the chip answers FW_VERSION 0 and a cell voltage of 0 mV. Both look like readings. The driver does not wait, because an Active Object never waits. AO_Power polls the readiness byte on its own timer.

The poll and the percentage

AO_Power reads at 1.5 s after boot and then every 2 s (KODE_POWER_FIRST_MS, KODE_POWER_POLL_MS). Until ready reads 1 it uses the charger's voltage alone. After that the cell voltage is the gauge's, unless it reads 2000 mV or less, and the current comes from the gauge. Every poll publishes one POWER_EVT_SIG with the voltage, the current (into the cell positive, out negative) and the percentage.

The percentage is AO_Power's. It works in three steps:

1. It takes the gauge's voltage and subtracts the current times 180 mΩ (KBSP_CELL_R_INT_MOHM) to estimate the open-circuit voltage.
2. It smooths that with a moving average of weight 1/5.
3. It reads the percentage off a 13-point curve in kbsp_cell.h.

The displayed value moves at most 2 points per reading. When the charger reports the charge as done, the value is 100.

The driver is one table

kdrv_cw2217.c describes every field as a row: register, kind, shift and width. kdrv_cw2217_get() and kdrv_cw2217_set() take a field and a value in its unit. A set refuses read-only rows and values out of range, does a masked read-modify-write so neighbouring bits keep their values, and reads the row back.

Four sequences are typed calls: wake, sleep, restart and loading a profile. The driver logs when the chip stops answering and when it returns, once each.

Specifications

The board

The measurement and control registers

The registers 0x00 to 0x0F: the readings, the configuration and the alarms. [7:6] is bits 7 and 6. A range such as 0x02-0x03 is two registers holding one number, high byte first.

The profile and extended registers

The registers 0x10 to 0xAB: the battery profile, the host temperature and the figures that need a profile to mean anything.

The fields

The driver's table. The first column is the name the console's gauge command takes. RO is read-only.

The driver computes the current in 64-bit microamps as code × 52.4 mV / (32768 × KBSP_CELL_RSENSE_MOHM) and rounds to the milliamp, away from zero. The table's range comes from the same constant. A write to t_host_c2 sets the high byte, then a low byte that alternates between 0 and 1, and reads nothing back.

The driver

The owner

Gotchas

Example code

Ask AO_Power to dump the gauge. Open the serial log and look for the kdrv.cw2217 lines: ready=1, the cell voltage in vcell_mv, and a profile of 80 zero bytes.

/*
 * gauge_dump.c - 2026-10-28 - from Kode with love
 *
 * Waits for the CW2217 fuel gauge on the Kode Dot to come up, then asks
 * AO_Power, the chip's owner, to log every field. With a battery fitted, the
 * serial log shows one line of fields (vcell_mv, current_ma, ready and the
 * rest) and the five lines of the 80-byte battery profile.
 */
#include "kode_ao.h"
 
/* Bring the system up, give the gauge time to start, then ask for the dump. */
void app_main(void)
{
    kode_init();
 
    /* The gauge needs about a second after its wake before it means anything. */
    kode_delay_ms(3000);
    power_field_request(POWER_CHIP_GAUGE, POWER_OP_DUMP, 0U, 0);
 
    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_cw2217.c, beside the charger's.
• kdrv_cw2217.h: the fields, the sequences and the profile calls.
• components/kaos/power: AO_Power, the owner, with the poll and the percentage.