Skip to content

Quickstart

Run the driver on your PC first, with no hardware; then start the PMIC from your MCU: wire the chip, write a small port class, declare what your cell and supply tolerate, and call three driver functions.

Datasheet sections this page relies on

From NXP Semiconductors PF1550 7:

  • Pins and package: 4.2 Pin definitions, p. 8

All of them, with the driver API for each: Datasheet map.

Try it on your PC

examples/host/ runs the real driver against a simulated PF1550, through a host port. From the repository root, with CMake and a C++20 compiler:

cmake -S examples/host -B build-example
cmake --build build-example
./build-example/pf1550_host_example
PF1550 driver 0.1.0 on the host
pf1550: initialised
charger state 1, fault 0, VBUS valid 1
LDO1 1800000 uV, run 1
0 interrupt passes

The calls in main.cpp are the ones below; only the port differs on an MCU. CI builds and runs this example on every pull request.

1. Wire it

MCU PF1550 Notes
I2C SCL SCL Pull-up to VDDIO; up to 400 kHz
I2C SDA SDA Pull-up to VDDIO
GPIO output STANDBY Optional, for RequestStandby()
GPIO input INTB Optional, open drain, active low
1.7 V to 3.3 V VDDIO The I/O supply

The chip answers at 0x08 unless its OTP set another address (0x08 to 0x0F); pass the address as the third constructor argument. The Hardware page has the full pin list, and the datasheet's example schematic the power connections (battery, supply, regulator outputs and capacitors).

2. Add the driver

Add the repository as a submodule and link the pf1550::pf1550 CMake target. Installation covers CMake on any MCU, the installed package and ESP-IDF.

git submodule add https://github.com/kokeb-labs-drivers/driver-pf1550.git external/driver-pf1550

3. Write the port

The port is the only platform code: it brings the bus up and moves bytes. Replace the platform_* calls with your SDK's.

my_port.hpp
class MyPort : public pf1550::I2cInterface<MyPort> {
public:
  // Bring the bus up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_i2c_init();
    }
    return ready_;
  }

  // One write transaction: START, address + W, the bytes (register first), STOP.
  bool Write(uint8_t addr, const uint8_t* data, std::size_t len) noexcept {
    return platform_i2c_write(addr, data, len);
  }

  // Write then read with a repeated START in between.
  bool WriteRead(uint8_t addr, const uint8_t* tx, std::size_t tx_len, uint8_t* rx,
                 std::size_t rx_len) noexcept {
    return platform_i2c_write_read(addr, tx, tx_len, rx, rx_len);
  }

  // Wait at least `us` microseconds: the DVS-done wait depends on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Porting explains each method, the optional hooks and the transfer rules.

4. Declare your limits and start the chip

main.cpp
#include "pf1550.hpp"

int start_pmic(MyPort& port) {
  pf1550::Config config{};
  config.limits.cell_max_mv = 4200;          // from your cell's data sheet
  config.limits.cell_max_charge_ma = 500;    // from your cell's data sheet
  config.limits.input_max_ma = 1000;         // what your supply delivers
  pf1550::PF1550<MyPort> pmic(port, config); // no I/O yet

  if (auto r = pmic.EnsureInitialized(); !r) { // 1. bus up, DEVICE_ID, charger as found
    return static_cast<int>(r.error); //    NoDevice, DeviceIdMismatch, Unsafe, OutOfLimits ...
  }
  const auto status = pmic.ReadChargerStatus(); // 2. read only
  if (!status) {
    return static_cast<int>(status.error);
  }
  return static_cast<int>(status.value.fault); // 3. 0 is Fault::None
}

What each step does:

  1. The constructor stores the configuration and does no I/O. Limits has no defaults: your cell's highest charge voltage and current, and what your supply can deliver. EnsureInitialized() rejects a configuration without them (InvalidArgument) before it sends anything.
  2. EnsureInitialized() calls your port's EnsureInitialized(), checks that DEVICE_ID reads 0x7C, then reads the charger as found. Some pre-programmed options start with the charger on and the fast-charge timer off; if the charger is on and not covered by your limits the call returns Unsafe or OutOfLimits, or, with AsFoundPolicy::MakeSafe, switches charging off.
  3. ReadChargerStatus() reads VBUS, the charger state (twice, to catch a change between reads) and the battery state, and classifies the fault. It writes nothing.

Nothing was written to the chip in this example. Configure() writes what Config asks for; SetChargerMode() turns charging on. See the API guide.

This example is built by the host CI, so it compiles against the current headers.

If it does not work

Symptom First thing to check
EnsureInitialized() returns InvalidArgument Limits is unset or a value is off the datasheet grid (Configuration)
EnsureInitialized() returns NoDevice Power, SDA, SCL and the address: nothing acknowledged (Troubleshooting)
EnsureInitialized() returns Bus Your port's EnsureInitialized() or a bus fault
EnsureInitialized() returns DeviceIdMismatch Another chip answered (Troubleshooting)
EnsureInitialized() returns Unsafe or OutOfLimits The charger was found on outside your limits (Troubleshooting)

Next

  • API guide: configure, charge, rails, interrupts, power states, errors.
  • Configuration: limits, acknowledgements, every block, Kconfig.
  • Examples: the host example and the MCU examples.
  • Platforms: which MCUs have a port and an example.