### ESP-IDF 4.x Setup Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Basic usage example for initializing an XPowers device on ESP-IDF 4.x.

```cpp
#include "driver/i2c.h"
#include "XPowersLib.h"

XPowersAXP2101 power;

void setup() {
    power.begin(I2C_NUM_0, 0x34, 21, 22);
}
```

--------------------------------

### Complete Minimal Setup Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/usage-examples.md

Initializes the AXP2101 PMU and configures a DCDC output. Ensure the correct chip definition is set before including the library.

```cpp
#define XPOWERS_CHIP_AXP2101
#include <Wire.h>
#include "XPowersLib.h"

XPowersPMU power;

void setup() {
    Serial.begin(115200);
    
    if (!power.begin(Wire, 0x34, 21, 22)) {
        Serial.println("Error!");
        return;
    }
    
    // Configure single 3.3V output
    power.enablePowerOutput(XPOWERS_DCDC1);
    power.setPowerChannelVoltage(XPOWERS_DCDC1, 3300);
    
    Serial.println("Ready");
}

void loop() {
    Serial.printf("Battery: %d%% | ", power.getBatteryPercent());
    Serial.printf("System: %umV\n", power.getSystemVoltage());
    delay(1000);
}
```

--------------------------------

### ESP-IDF 5.x Setup Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Example showing how to configure and initialize an I2C master bus for use with XPowersLib.

```cpp
#include "driver/i2c_master.h"
#include "XPowersLib.h"

i2c_master_bus_handle_t bus_handle;
XPowersAXP2101 power;

void setup() {
    i2c_master_bus_config_t bus_cfg = {
        .clk_source = I2C_CLK_SRC_DEFAULT,
        .i2c_port = I2C_NUM_0,
        .scl_io_num = 22,
        .sda_io_num = 21,
        .glitch_ignore_cnt = 7,
    };
    i2c_new_master_bus(&bus_cfg, &bus_handle);
    
    power.begin(bus_handle, 0x34);
}
```

--------------------------------

### Arduino I2C Setup Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Basic usage example for initializing an XPowers device on an Arduino platform.

```cpp
#include <Wire.h>
#include "XPowersLib.h"

XPowersAXP2101 power;

void setup() {
    power.begin(Wire, 0x34, 21, 22);  // SDA=21, SCL=22
}
```

--------------------------------

### Initialize ESP-IDF Application

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Main entry point setup for ESP-IDF projects.

```cpp
#define XPOWERS_CHIP_AXP2101
#define CONFIG_XPOWERS_ESP_IDF_NEW_API

#include "driver/i2c_master.h"
#include "XPowersLib.h"

extern "C" void app_main() {
    // ... initialization
}
```

--------------------------------

### PMU Output Log Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/examples/ESP_IDF_Example/README.md

Example output showing the initialization status and voltage configuration of the PMU.

```text
I (345) mian: I2C initialized successfully
I (355) AXP2101: Init PMU SUCCESS!
I (385) AXP2101: DCDC=======================================================================
I (385) AXP2101: DC1  :ENABLE    Voltage:3300 mV
I (385) AXP2101: DC2  :DISABLE   Voltage:900 mV
I (395) AXP2101: DC3  :ENABLE    Voltage:3300 mV
I (395) AXP2101: DC4  :DISABLE   Voltage:1100 mV
I (405) AXP2101: DC5  :DISABLE   Voltage:1200 mV
I (405) AXP2101: ALDO=======================================================================
I (415) AXP2101: ALDO1:ENABLE    Voltage:1800 mV
I (425) AXP2101: ALDO2:ENABLE    Voltage:2800 mV
I (425) AXP2101: ALDO3:ENABLE    Voltage:3300 mV
I (435) AXP2101: ALDO4:ENABLE    Voltage:3000 mV
I (435) AXP2101: BLDO=======================================================================
I (445) AXP2101: BLDO1:ENABLE    Voltage:3300 mV
```

--------------------------------

### Enable Power Output Usage Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Demonstrates enabling specific DCDC and LDO power channels.

```cpp
power.enablePowerOutput(XPOWERS_DCDC1);    // Enable DCDC1
power.enablePowerOutput(XPOWERS_LDO2);     // Enable LDO2
```

--------------------------------

### Custom Callback Bit-bang Example

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Example implementation of custom I2C read/write functions for bit-banging.

```cpp
int myI2CRead(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len) {
    // Custom I2C read implementation
    if (!bitbang_start(devAddr, I2C_READ)) return -1;
    if (!bitbang_write(regAddr)) return -1;
    if (!bitbang_read(data, len)) return -1;
    bitbang_stop();
    return 0;
}

int myI2CWrite(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len) {
    // Custom I2C write implementation
    if (!bitbang_start(devAddr, I2C_WRITE)) return -1;
    if (!bitbang_write(regAddr)) return -1;
    if (!bitbang_write(data, len)) return -1;
    bitbang_stop();
    return 0;
}

XPowersAXP2101 power;

void setup() {
    power.begin(0x34, myI2CRead, myI2CWrite);
}
```

--------------------------------

### Configure GPIO

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Set and get the operating mode for GPIO pins.

```cpp
bool setGpioMode(uint8_t gpio, uint8_t mode)
uint8_t getGpioMode(uint8_t gpio)
```

--------------------------------

### Initialize AXP2101 on Arduino

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Basic setup for AXP2101 using the Wire library in an Arduino sketch.

```cpp
#define XPOWERS_CHIP_AXP2101

#include <Wire.h>
#include <XPowersLib.h>

XPowersPMU power;

void setup() {
    Serial.begin(115200);
    power.begin(Wire, 0x34, 21, 22);
}
```

--------------------------------

### Standard Library Usage Pattern

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Example of defining the chip and initializing the power management object in an Arduino sketch.

```cpp
// In sketch or header before #include "XPowersLib.h"
#define XPOWERS_CHIP_AXP2101

#include "XPowersLib.h"

XPowersPMU power;  // Resolves to XPowersAXP2101 due to define above
```

--------------------------------

### Initialize and Configure PMU

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Standard setup routine for initializing the PMU, enabling channels, setting voltages, and configuring battery charging parameters.

```cpp
#include "XPowersLib.h"

XPowersPMU power;  // Resolves to XPowersAXP2101 or other based on defines

void setup() {
    // Initialize with Arduino Wire library
    if (!power.init(Wire, AXP2101_SLAVE_ADDRESS, 21, 22)) {
        Serial.println("PMU init failed");
        return;
    }
    
    // Enable power channels
    power.enablePowerOutput(XPOWERS_DCDC1);
    power.enablePowerOutput(XPOWERS_LDO2);
    
    // Set voltages
    power.setPowerChannelVoltage(XPOWERS_DCDC1, 3300);  // 3.3V
    power.setPowerChannelVoltage(XPOWERS_LDO2, 3300);
    
    // Check battery
    Serial.printf("Battery: %d%%, %umV\n", 
        power.getBatteryPercent(), 
        power.getBattVoltage());
    
    // Enable charging
    power.setChargeTargetVoltage(XPOWERS_AXP2101_CHG_VOL_4V35);
    power.setChargerConstantCurr(XPOWERS_AXP2101_CHG_CUR_500MA);
}
```

--------------------------------

### Basic PMU Setup for Arduino/ESP32

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/README.md

Initializes the PMU over I2C and configures a DCDC output channel. Requires the Wire library and XPowersLib header.

```cpp
#define XPOWERS_CHIP_AXP2101
#include <Wire.h>
#include "XPowersLib.h"

XPowersPMU power;

void setup() {
    Serial.begin(115200);
    
    // Initialize PMU on I2C with SDA=21, SCL=22
    if (!power.begin(Wire, 0x34, 21, 22)) {
        Serial.println("PMU init failed!");
        return;
    }
    
    // Enable 3.3V output
    power.enablePowerOutput(XPOWERS_DCDC1);
    power.setPowerChannelVoltage(XPOWERS_DCDC1, 3300);
}

void loop() {
    Serial.printf("Battery: %d%% at %umV\n", 
        power.getBatteryPercent(), 
        power.getBattVoltage());
    delay(1000);
}
```

--------------------------------

### Linux Custom I2C Implementation

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Example of implementing custom I2C read/write functions for Linux environments.

```cpp
#include "XPowersLib.h"
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
#include <linux/i2c-dev.h>

int i2c_file = -1;

int linuxI2CRead(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len) {
    ioctl(i2c_file, I2C_SLAVE, devAddr);
    if (write(i2c_file, &regAddr, 1) != 1) return -1;
    if (read(i2c_file, data, len) != len) return -1;
    return 0;
}

int linuxI2CWrite(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len) {
    ioctl(i2c_file, I2C_SLAVE, devAddr);
    uint8_t buf[len + 1];
    buf[0] = regAddr;
    memcpy(buf + 1, data, len);
    if (write(i2c_file, buf, len + 1) != len + 1) return -1;
    return 0;
}

int main() {
    i2c_file = open("/dev/i2c-1", O_RDWR);
    if (i2c_file < 0) {
        perror("i2c open failed");
        return 1;
    }
    
    XPowersAXP2101 power;
    if (!power.begin(0x34, linuxI2CRead, linuxI2CWrite)) {
        fprintf(stderr, "PMU init failed\n");
        return 1;
    }
    
    // Use library...
    
    close(i2c_file);
    return 0;
}
```

--------------------------------

### Power Sequencing

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/api-summary.md

Methods for managing power channel start sequences and fast power-on options.

```APIDOC
## Power Sequencing

- `setPowerChannelStartSequence(channel, xpower_start_sequence_t opt)`: Set start sequence for a channel.
- `getPowerChannelStartSequence(channel)`: Get start sequence for a channel.
- `setFastPowerOnDvs(xpowers_fast_on_opt_t opt)`: Configure fast power-on DVS.
```

--------------------------------

### Enable Multiple Interrupts

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/api-summary.md

Example of combining multiple interrupt flags using the bitwise OR operator for unified interrupt configuration.

```cpp
power.enableInterrupt(XPOWERS_USB_INSERT_INT | XPOWERS_CHARGE_DONE_INT);
```

--------------------------------

### begin (ESP-IDF 5.x)

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C communication using the ESP-IDF 5.x master bus handle.

```APIDOC
## bool begin(i2c_master_bus_handle_t bus_handle, uint8_t addr)

### Description
Initializes the device using an existing ESP-IDF 5.x I2C master bus handle.

### Parameters
- **bus_handle** (i2c_master_bus_handle_t) - Required - Handle to an initialized I2C master bus.
- **addr** (uint8_t) - Required - The I2C slave address of the device.

### Returns
- **bool** - Returns true if initialization is successful, false otherwise.
```

--------------------------------

### begin (ESP-IDF 4.x)

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C communication using the legacy ESP-IDF 4.x port configuration.

```APIDOC
## bool begin(i2c_port_t port_num, uint8_t addr, int sda, int scl)

### Description
Initializes the device using a specific ESP-IDF 4.x I2C port number and pin configuration.

### Parameters
- **port_num** (i2c_port_t) - Required - The I2C port identifier (e.g., I2C_NUM_0).
- **addr** (uint8_t) - Required - The I2C slave address of the device.
- **sda** (int) - Required - The SDA GPIO pin number.
- **scl** (int) - Required - The SCL GPIO pin number.

### Returns
- **bool** - Returns true if initialization is successful, false otherwise.
```

--------------------------------

### Get Chip ID

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Returns the hardware-specific chip identifier.

```cpp
virtual uint8_t getChipID() = 0;
```

--------------------------------

### begin (Custom Callback)

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C communication using custom read and write callback functions.

```APIDOC
## bool begin(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)

### Description
Initializes the device using custom user-provided I2C read and write functions, useful for bit-banging or custom protocols.

### Parameters
- **addr** (uint8_t) - Required - The I2C slave address.
- **readRegCallback** (iic_fptr_t) - Required - Function pointer for reading registers.
- **writeRegCallback** (iic_fptr_t) - Required - Function pointer for writing registers.

### Returns
- **bool** - Returns true if initialization is successful, false otherwise.
```

--------------------------------

### Get Chip Model

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Returns the XPowersChipModel_t enum representing the detected chip model.

```cpp
uint8_t getChipModel()
```

--------------------------------

### Initialization Sequence

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Standard steps to instantiate, configure, and verify the power management unit.

```cpp
XPowersAXP2101 power;
```

```cpp
// Arduino/ESP32
power.begin(Wire, 0x34, 21, 22);
   
// ESP-IDF 4.x
power.begin(I2C_NUM_0, 0x34, 21, 22);
   
// ESP-IDF 5.x
power.begin(bus_handle, 0x34);
   
// Custom callbacks
power.begin(0x34, myReadFunc, myWriteFunc);
```

```cpp
if (!power.init()) {
    Serial.println("I2C communication failed");
    return;
}
```

```cpp
power.setDC1Voltage(3300);
```

```cpp
power.deinit();  // Release I2C resources
```

--------------------------------

### Control DCDC Voltages

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Set and get voltage levels for the three DCDC outputs.

```cpp
bool setDC1Voltage(uint16_t millivolt)    // 700-3500 mV
uint16_t getDC1Voltage()

bool setDC2Voltage(uint16_t millivolt)    // 700-2275 mV
uint16_t getDC2Voltage()

bool setDC3Voltage(uint16_t millivolt)    // 700-3500 mV
uint16_t getDC3Voltage()
```

--------------------------------

### begin (Arduino TwoWire)

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C communication using the standard Arduino Wire library.

```APIDOC
## bool begin(TwoWire &w, uint8_t addr, int sda, int scl)

### Description
Initializes the power management device using an Arduino TwoWire bus instance.

### Parameters
- **w** (TwoWire&) - Required - The I2C bus object (e.g., Wire, Wire1).
- **addr** (uint8_t) - Required - The I2C slave address of the device.
- **sda** (int) - Required - The GPIO pin number for the SDA line.
- **scl** (int) - Required - The GPIO pin number for the SCL line.

### Returns
- **bool** - Returns true if initialization is successful, false otherwise.
```

--------------------------------

### Get Output Voltage Interface

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Defines the interface to retrieve the currently configured voltage for a channel.

```cpp
virtual uint16_t getPowerChannelVoltage(uint8_t channel) = 0;
```

--------------------------------

### System Configuration and Watchdog

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Advanced configuration for boot timing, GPIO, backup battery, charging, and watchdog timer.

```APIDOC
## Boot Time
- bool setBootTime(xpowers_axp192_boot_time_t opt)
- xpowers_axp192_boot_time_t getBootTime()

## GPIO
- bool setGpioMode(uint8_t gpio, uint8_t mode)
- uint8_t getGpioMode(uint8_t gpio)

## Backup Battery
- bool setBackupBatteryVoltage(xpowers_axp192_backup_batt_vol_t opt)
- bool setBackupBatteryCurrent(xpowers_axp192_backup_batt_curr_t opt)

## Charger
- bool setChargerTerminationCurr(xpowers_axp192_chg_iterm_t opt)
- bool setChargerPreCurr(uint8_t opt)

## Watchdog
- bool setWatchdogTimeout(uint8_t timeout)
- bool disableWatchdog()
- bool feedWatchdog()
```

--------------------------------

### Initialization and Constructors

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Methods for instantiating the AXP192 driver and initializing communication with the hardware.

```APIDOC
## Constructors
- XPowersAXP192()
- XPowersAXP192(TwoWire &w, int sda, int scl, uint8_t addr)
- XPowersAXP192(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)

## Initialization
- bool init()
- bool init(TwoWire &w, int sda, int scl, uint8_t addr = AXP192_SLAVE_ADDRESS)
```

--------------------------------

### Initialization Flow

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Standard initialization sequence for XPowersLib devices.

```APIDOC
## Initialization Flow

### Description
Typical sequence to initialize a power management device, select the I2C backend, and verify communication.

### Methods
- `begin(...)`: Configures the I2C backend. Supports various signatures for Arduino, ESP-IDF 4.x/5.x, and custom callbacks.
- `init()`: Verifies communication with the PMU.
- `deinit()`: Releases I2C resources.
```

--------------------------------

### Initialize PMU on Arduino/ESP32

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/usage-examples.md

Sets up the PMU instance using the Wire library and verifies connection by reading the chip ID.

```cpp
#define XPOWERS_CHIP_AXP2101
#include <Wire.h>
#include "XPowersLib.h"

XPowersPMU power;
const uint8_t i2c_sda = 21;
const uint8_t i2c_scl = 22;

void setup() {
    Serial.begin(115200);
    
    // Initialize with Wire library
    if (!power.begin(Wire, AXP2101_SLAVE_ADDRESS, i2c_sda, i2c_scl)) {
        Serial.println("PMU initialization failed!");
        return;
    }
    
    Serial.printf("Chip ID: 0x%x\n", power.getChipID());
}

void loop() {
    delay(1000);
}
```

--------------------------------

### AXP192 Register Value Calculation

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/register-reference.md

Example calculation to determine the register value for a target voltage of 2000mV.

```text
RegValue = (2000 - 700) / 25 = 52 (0x34)
```

--------------------------------

### Configure Boot Time

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Set the startup delay for DCDC outputs.

```cpp
typedef enum {
    XPOWERS_AXP192_BOOT_TIME_128MS,
    XPOWERS_AXP192_BOOT_TIME_512MS,
    XPOWERS_AXP192_BOOT_TIME_1S,
    XPOWERS_AXP192_BOOT_TIME_2S,
} xpowers_axp192_boot_time_t;

bool setBootTime(xpowers_axp192_boot_time_t opt);
xpowers_axp192_boot_time_t getBootTime();
```

--------------------------------

### Get Status Register

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Retrieves the raw status register value, where bit definitions are specific to the individual chip.

```cpp
virtual uint16_t status() = 0;
```

--------------------------------

### Get VBUS Voltage

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Retrieves the current USB input voltage in millivolts. Returns 0 if no USB power is detected.

```cpp
virtual uint16_t getVbusVoltage()
```

--------------------------------

### Initialize Multiple Devices on ESP-IDF 5.x

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/usage-examples.md

Demonstrates sharing a single I2C master bus handle between multiple XPowersLib devices.

```cpp
#include "driver/i2c_master.h"
#include "XPowersLib.h"

i2c_master_bus_handle_t bus_handle;
XPowersAXP2101 pmu;
PowerDeliveryHUSB238 pd;

void initializeI2C() {
    i2c_master_bus_config_t bus_cfg = {
        .clk_source = I2C_CLK_SRC_DEFAULT,
        .i2c_port = I2C_NUM_0,
        .scl_io_num = 22,
        .sda_io_num = 21,
        .glitch_ignore_cnt = 7,
    };
    
    ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus_handle));
}

void app_main() {
    initializeI2C();
    
    // Two devices on same bus
    if (!pmu.begin(bus_handle, 0x34)) {
        ESP_LOGE("PMU", "Initialization failed");
        return;
    }
    
    if (!pd.init(bus_handle, 0x08)) {
        ESP_LOGE("PD", "Initialization failed");
        return;
    }
    
    // Both devices communicate on the same I2C bus
    
    pmu.deinit();
    pd.deinit();
}
```

--------------------------------

### Control LDO Voltages

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Set and get voltage levels for LDO outputs. Note that LDO1 is fixed at 3.3V for RTC.

```cpp
bool setLDO2Voltage(uint16_t millivolt)   // 1800-3300 mV
uint16_t getLDO2Voltage()

bool setLDO3Voltage(uint16_t millivolt)   // 1800-3300 mV
uint16_t getLDO3Voltage()

bool setLDO4Voltage(uint16_t millivolt)   // (not on AXP192)
bool setLDO5Voltage(uint16_t millivolt)   // 1800-3300 mV
uint16_t getLDO5Voltage()

// LDO1 is always 3.3V for RTC
```

--------------------------------

### ESP-IDF Build Process Commands

Source: https://github.com/lewisxhe/xpowerslib/blob/master/examples/ESP_IDF_Example/README.md

Sequence of shell commands to set up the ESP-IDF environment, clone the repository, and build the project.

```bash
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
git clone https://github.com/lewisxhe/XPowersLib.git
cd esp-idf
./install.sh
. ./export.sh
cd ..
cd XPowersLib/examples/ESP_IDF_Example
idf.py menuconfig
idf.py build
idf.py -b 921600 flash
idf.py monitor
```

--------------------------------

### Set and Get VBUS Voltage Limit

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Configures the VBUS overvoltage threshold. The valid range depends on the specific PMIC model.

```cpp
virtual void setVbusVoltageLimit(uint8_t opt) = 0;
virtual uint8_t getVbusVoltageLimit(void) = 0;
```

--------------------------------

### Configure PlatformIO for ESP-IDF

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Build configuration for ESP-IDF 5.x projects using XPowersLib.

```ini
[env:esp32-idf5]
platform = espressif32 @ ^6.0.0
board = esp32-devkitc
framework = espidf
build_flags = 
    -DXPOWERS_CHIP_AXP2101
    -DCONFIG_XPOWERS_ESP_IDF_NEW_API
lib_deps = XPowersLib
```

--------------------------------

### Set and Get VBUS Current Limit

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Manages the inrush current limit for VBUS. Supported limits vary by chip model.

```cpp
virtual bool setVbusCurrentLimit(uint8_t opt) = 0;
virtual uint8_t getVbusCurrentLimit(void) = 0;
```

--------------------------------

### init()

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Initializes the PMU via I2C. This method must be called before any other library methods are invoked.

```APIDOC
## init()

### Description
Initializes the PMU via I2C. Must be called before using any other methods.

### Signature
`virtual bool init() = 0;`

### Returns
- **bool**: Returns true on successful initialization, false if communication fails or chip is not detected.
```

--------------------------------

### Set and Get Charger Constant Current

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Controls the constant current phase of the charging process, with ranges typically between 100mA and 1320mA.

```cpp
virtual bool setChargerConstantCurr(uint8_t opt) = 0;
virtual uint8_t getChargerConstantCurr() = 0;
```

--------------------------------

### Set and Get Charge Target Voltage

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Configures the target charging voltage. Use chip-specific enums from XPowersParams.hpp based on the hardware model.

```cpp
virtual bool setChargeTargetVoltage(uint8_t opt) = 0;
virtual uint8_t getChargeTargetVoltage() = 0;
```

--------------------------------

### AXP202 Constructor and Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Initialization methods for the AXP202 PMU, supporting both direct I2C and callback-based communication.

```cpp
XPowersAXP202()
XPowersAXP202(TwoWire &w, int sda, int scl, uint8_t addr)
XPowersAXP202(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)

bool init()
bool init(TwoWire &w, int sda, int scl, uint8_t addr = AXP202_SLAVE_ADDRESS)
```

--------------------------------

### Linux Makefile Configuration

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Build instructions for compiling XPowersLib on Linux.

```makefile
CFLAGS = -std=c++11 -I./src
SOURCES = main.cpp XPowersLibInterface.cpp
OBJECTS = $(SOURCES:.cpp=.o)

main: $(OBJECTS)
	g++ -o $@ $^

%.o: %.cpp
	g++ $(CFLAGS) -c $< -o $@

clean:
	rm -f $(OBJECTS) main
```

--------------------------------

### Initialization and Lifecycle

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/api-summary.md

Functions for initializing the PMU and managing I2C resources.

```APIDOC
## Initialization Methods

### init()
- **Returns**: bool - Initialize PMU via I2C

### deinit()
- **Returns**: void - Release I2C resources

### begin(Wire, addr, sda, scl)
- **Returns**: bool - [Arduino] Initialize with TwoWire

### begin(i2c_bus_handle, addr)
- **Returns**: bool - [ESP-IDF 5.x] Initialize with bus handle

### begin(i2c_port, addr, sda, scl)
- **Returns**: bool - [ESP-IDF 4.x] Initialize with port

### begin(addr, readFunc, writeFunc)
- **Returns**: bool - [Generic] Initialize with callbacks
```

--------------------------------

### Constructor Variants

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Supported patterns for initializing the PMU object, including Arduino TwoWire, custom callbacks, and default configurations.

```cpp
XPowersAXP192(TwoWire &w, int sda = SDA, int scl = SCL, uint8_t addr = AXP192_SLAVE_ADDRESS)
```

```cpp
XPowersAXP192(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)
```

```cpp
XPowersAXP192()
```

--------------------------------

### XPowersAXP202 Initialization and Control

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Methods for initializing the AXP202 PMU and controlling its DCDC and LDO voltage outputs.

```APIDOC
## XPowersAXP202 Initialization

### Constructors
- XPowersAXP202()
- XPowersAXP202(TwoWire &w, int sda, int scl, uint8_t addr)
- XPowersAXP202(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)

### Initialization
- bool init()
- bool init(TwoWire &w, int sda, int scl, uint8_t addr = AXP202_SLAVE_ADDRESS)

### Output Control
- bool setDC2Voltage(uint16_t millivolt) // 700-2275 mV
- bool setDC3Voltage(uint16_t millivolt) // 700-3500 mV
- bool setLDO2Voltage(uint16_t millivolt) // 1800-3300 mV
- bool setLDO3Voltage(uint16_t millivolt) // 700-3500 mV
- bool setLDO4Voltage(uint16_t millivolt) // 1800-3300 mV
- bool enableDC2() / bool disableDC2()
- bool enableLDO2() / bool disableLDO2()
```

--------------------------------

### Initialize AXP192 Device

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Methods to initialize the device communication.

```cpp
bool init()
bool init(TwoWire &w, int sda, int scl, uint8_t addr = AXP192_SLAVE_ADDRESS)
```

--------------------------------

### Initialize and Configure SY6970/BQ25896 Chargers

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Common API methods for managing charger ICs, including status checks and current regulation.

```cpp
bool init()
uint8_t getChipID()
bool isPowerGood()
bool isCharging()

bool setChargerConstantCurr(uint8_t opt)
uint8_t getChargerConstantCurr()

bool enableOTG() / bool disableOTG()
bool isOTGMode()
```

--------------------------------

### Arduino Platform I2C Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Standard initialization for Arduino environments using the Wire library.

```cpp
#include <Wire.h>
#include "XPowersLib.h"

XPowersPMU power;

void setup() {
    power.begin(Wire, 0x34, 21, 22);  // SDA=21, SCL=22
}
```

--------------------------------

### AXP2101 Constructor and Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Initialization and deinitialization methods for the AXP2101 PMU.

```cpp
XPowersAXP2101()
XPowersAXP2101(TwoWire &w, int sda, int scl, uint8_t addr)
XPowersAXP2101(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)

bool init()
bool init(TwoWire &w, int sda, int scl, uint8_t addr = AXP2101_SLAVE_ADDRESS)
void deinit()  // Clean up ESP-IDF resources
```

--------------------------------

### Binary Size Optimization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Configure build flags to balance binary size and execution speed for PlatformIO and Makefile environments.

```ini
build_flags = -Os   # Optimize for size
build_flags = -O2   # Optimize for speed
```

```makefile
CFLAGS = -Os -flto
```

--------------------------------

### Arduino TwoWire Backend Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C bus using the standard Arduino Wire library.

```cpp
bool begin(TwoWire &w, uint8_t addr, int sda, int scl)
```

--------------------------------

### Configure ESP-IDF CMakeLists.txt

Source: https://github.com/lewisxhe/xpowerslib/blob/master/examples/ESP_IDF_Example/CMakeLists.txt

Required boilerplate for ESP-IDF projects to correctly include the XPowersLib component.

```cmake
cmake_minimum_required(VERSION 3.5)

set(EXTRA_COMPONENT_DIRS ../../../XPowersLib)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(XPowersLib_Example)
```

--------------------------------

### Custom Callback Backend Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the library with custom read and write function pointers for non-standard I2C implementations.

```cpp
bool begin(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)
```

```cpp
typedef int (*iic_fptr_t)(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len);
```

--------------------------------

### Configure AXP2101 Advanced Power Features

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/usage-examples.md

Demonstrates setting watchdog timers, charging thresholds, monitoring charge status, and defining power-on sequences.

```cpp
void axp2101Advanced() {
    // Set watchdog timer (8 seconds with reset)
    power.setWatchdogTimeout(XPOWERS_AXP2101_WDT_TIMEOUT_8S);
    power.setWatchdogConfig(XPOWERS_AXP2101_WDT_IRQ_AND_RSET);
    
    // Feed watchdog periodically in main loop
    // power.feedWatchdog();
    
    // Set charge termination current (charge stops at 100mA)
    power.setChargerTerminationCurr(XPOWERS_AXP2101_CHG_ITERM_100MA);
    
    // Set precharge current
    power.setChargerPreCurr(XPOWERS_AXP2101_PRECHARGE_100MA);
    
    // Query charging state
    xpowers_chg_status_t chargeState = power.getChargerStatus();
    switch (chargeState) {
        case XPOWERS_AXP2101_CHG_TRI_STATE:
            Serial.println("Trickle charge");
            break;
        case XPOWERS_AXP2101_CHG_CC_STATE:
            Serial.println("Constant current charging");
            break;
        case XPOWERS_AXP2101_CHG_CV_STATE:
            Serial.println("Constant voltage charging");
            break;
        case XPOWERS_AXP2101_CHG_DONE_STATE:
            Serial.println("Charge complete");
            break;
        case XPOWERS_AXP2101_CHG_STOP_STATE:
            Serial.println("Not charging");
            break;
        default:
            break;
    }
    
    // Query power on/off sources
    xpower_power_on_source_t onSrc = power.getPowerOnSource();
    xpower_power_off_source_t offSrc = power.getPowerOffSource();
    
    // Set power sequencing for outputs
    power.setPowerChannelStartSequence(XPOWERS_DCDC1, XPOWERS_AXP2101_SEQUENCE_LEVEL_0);
    power.setPowerChannelStartSequence(XPOWERS_LDO2, XPOWERS_AXP2101_SEQUENCE_LEVEL_1);
}
```

--------------------------------

### ESP-IDF 5.x New API Configuration

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Enable the new I2C driver API and initialize the bus handle for ESP-IDF 5.x.

```cpp
#define CONFIG_XPOWERS_ESP_IDF_NEW_API

#include "driver/i2c_master.h"
#include "XPowersLib.h"
```

```cpp
i2c_master_bus_handle_t bus_handle;

i2c_master_bus_config_t bus_cfg = {
    .clk_source = I2C_CLK_SRC_DEFAULT,
    .i2c_port = I2C_NUM_0,
    .scl_io_num = 22,
    .sda_io_num = 21,
};
i2c_new_master_bus(&bus_cfg, &bus_handle);

XPowersPMU power;
power.begin(bus_handle, 0x34);
```

--------------------------------

### PlatformIO Build Flag Configuration

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Set the chip definition globally in the PlatformIO project configuration file.

```ini
build_flags = -DXPOWERS_CHIP_AXP2101
```

--------------------------------

### Wake-Up and Power Tracking

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/api-summary.md

Methods for configuring wake-up sources and tracking power state changes.

```APIDOC
## Wake-Up and Power Tracking

- `setWakeupSource(xpowers_wakeup_t opt)`: Set system wake-up source.
- `getPowerOnSource()`: Returns the cause of the last power-on.
- `getPowerOffSource()`: Returns the cause of the last power-off.
```

--------------------------------

### Charging Configuration Methods

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/README.md

Configures target charging voltage and constant current limits.

```cpp
power.setChargeTargetVoltage(XPOWERS_AXP2101_CHG_VOL_4V2)
power.setChargerConstantCurr(XPOWERS_AXP2101_CHG_CUR_500MA)
```

--------------------------------

### Initialize HUSB238 USB PD Controller

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Constructor and initialization methods for the HUSB238 controller, supporting both I2C and custom callback interfaces.

```cpp
PowerDeliveryHUSB238()
PowerDeliveryHUSB238(TwoWire &w, int sda, int scl, uint8_t addr)
PowerDeliveryHUSB238(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)

bool init()
void deinit()
```

--------------------------------

### XPowersAXP2101 Initialization and Control

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Methods for initializing the AXP2101 PMU, managing its extensive DCDC/LDO outputs, and controlling battery charging parameters.

```APIDOC
## XPowersAXP2101 Initialization

### Initialization
- bool init()
- bool init(TwoWire &w, int sda, int scl, uint8_t addr = AXP2101_SLAVE_ADDRESS)
- void deinit()

### Voltage Control
- bool setDC1Voltage(uint16_t millivolt) // 1500-3400 mV
- bool setALDO1Voltage(uint16_t millivolt) // 500-3500 mV
- bool setBLDO1Voltage(uint16_t millivolt) // 500-3500 mV
- bool setCPUSLDOVoltage(uint16_t millivolt) // 500-1400 mV

### Battery Charging
- bool setChargerPreCurr(xpowers_prechg_t opt)
- bool setChargerTerminationCurr(xpowers_axp2101_chg_iterm_t opt)
- xpowers_chg_status_t getChargerStatus()
```

--------------------------------

### Initialize AXP192 Constructor

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Variants for initializing the AXP192 class, supporting default Wire, custom I2C pins, or custom callback functions.

```cpp
XPowersAXP192()                          // Default, use Wire/SDA/SCL on Arduino
XPowersAXP192(TwoWire &w, int sda, int scl, uint8_t addr)
XPowersAXP192(uint8_t addr, iic_fptr_t readRegCallback, iic_fptr_t writeRegCallback)
```

--------------------------------

### Initialize PMU

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Initializes the PMU via I2C. Must be called before using any other methods.

```cpp
virtual bool init() = 0;
```

--------------------------------

### Configure STM32 Arduino Build

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Build flags for STM32 projects using the Arduino core.

```ini
[env:stm32f4]
platform = ststm32
board = nucleo_f401re
framework = arduino
build_flags = -DXPOWERS_CHIP_AXP2101
lib_deps = XPowersLib
```

--------------------------------

### ESP-IDF 5.x I2C Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C bus using the ESP-IDF 5.x master bus handle API.

```cpp
bool begin(i2c_master_bus_handle_t bus_handle, uint8_t addr)
```

--------------------------------

### Define Chip Selection Macros

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Define exactly one of these macros before including the library header to select the specific PMU or charger chip.

```cpp
#define XPOWERS_CHIP_AXP192   // Select AXP192 PMU
#define XPOWERS_CHIP_AXP202   // Select AXP202 PMU
#define XPOWERS_CHIP_AXP2101  // Select AXP2101 PMU
#define XPOWERS_CHIP_SY6970   // Select SY6970 charger
#define XPOWERS_CHIP_BQ25896  // Select BQ25896 charger
```

--------------------------------

### Configure Charger Settings

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Set charger termination current and precharge timeout settings.

```cpp
typedef enum {
    XPOWERS_AXP192_CHG_ITERM_LESS_10_PERCENT,
    XPOWERS_AXP192_CHG_ITERM_LESS_15_PERCENT,
} xpowers_axp192_chg_iterm_t;

bool setChargerTerminationCurr(xpowers_axp192_chg_iterm_t opt);

// Precharge settings
typedef enum {
    XPOWERS_AXP192_PRECHG_TIMEOUT_30MIN,
    XPOWERS_AXP192_PRECHG_TIMEOUT_40MIN,
    XPOWERS_AXP192_PRECHG_TIMEOUT_50MIN,
    XPOWERS_AXP192_PRECHG_TIMEOUT_60MIN,
} xpoers_axp192_prechg_to_t;

bool setChargerPreCurr(uint8_t opt);
```

--------------------------------

### System Power Configuration

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Methods for managing system voltage and shutdown thresholds.

```APIDOC
## getSystemVoltage()
### Description
Returns the VSYS system supply voltage.
### Response
- **uint16_t** - Voltage in millivolts.

## setSysPowerDownVoltage(uint16_t millivolt)
### Description
Sets the threshold at which the PMU triggers a system shutdown.
### Parameters
- **millivolt** (uint16_t) - Shutdown threshold (2600-3300 mV).

## getSysPowerDownVoltage()
### Description
Retrieves the current system shutdown voltage threshold.
### Response
- **uint16_t** - Threshold in millivolts.

## isDischarge()
### Description
Checks if the device is currently discharging from the battery.
### Response
- **bool** - true if actively discharging.
```

--------------------------------

### ESP-IDF 4.x Legacy Initialization

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/i2c-interface.md

Initializes the I2C bus using the legacy ESP-IDF 4.x port-based API.

```cpp
bool begin(i2c_port_t port_num, uint8_t addr, int sda, int scl)
```

--------------------------------

### Power Key Configuration

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/api-summary.md

Methods to configure power-on and power-off button press durations.

```APIDOC
## bool setPowerKeyPressOnTime(opt)

### Description
Sets the minimum press duration to power-on (128ms-2s).

### Parameters
- **opt** (int) - Required - Duration setting.

## uint8_t getPowerKeyPressOnTime()

### Description
Retrieves the current power-on time setting.

## bool setPowerKeyPressOffTime(opt)

### Description
Sets the long-press duration to trigger shutdown (4s-10s).

### Parameters
- **opt** (int) - Required - Duration setting.

## uint8_t getPowerKeyPressOffTime()

### Description
Retrieves the current power-off time setting.
```

--------------------------------

### Configure charging parameters

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/README.md

Sets the target charging voltage and constant current limit for the PMU.

```cpp
power.setChargeTargetVoltage(XPOWERS_AXP2101_CHG_VOL_4V2);
power.setChargerConstantCurr(XPOWERS_AXP2101_CHG_CUR_500MA);
```

--------------------------------

### Configure Backup Battery

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/chip-implementations.md

Set voltage and current limits for the backup battery.

```cpp
typedef enum {
    XPOWERS_AXP192_BACKUP_BAT_VOL_3V1,
    XPOWERS_AXP192_BACKUP_BAT_VOL_3V,
    XPOWERS_AXP192_BACKUP_BAT_VOL_3V0,
    XPOWERS_AXP192_BACKUP_BAT_VOL_2V5,
} xpowers_axp192_backup_batt_vol_t;

typedef enum {
    XPOWERS_AXP192_BACKUP_BAT_CUR_50UA,
    XPOWERS_AXP192_BACKUP_BAT_CUR_100UA,
    XPOWERS_AXP192_BACKUP_BAT_CUR_200UA,
    XPOWERS_AXP192_BACKUP_BAT_CUR_400UA,
} xpowers_axp192_backup_batt_curr_t;

bool setBackupBatteryVoltage(xpowers_axp192_backup_batt_vol_t opt);
bool setBackupBatteryCurrent(xpowers_axp192_backup_batt_curr_t opt);
```

--------------------------------

### Battery Status Methods

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/core-interface.md

Methods for retrieving battery percentage, voltage, connection status, and charging state.

```cpp
virtual int getBatteryPercent()      // 0-100%, or -1 if no battery
virtual uint16_t getBattVoltage()    // Millivolts, 0 if disconnected
virtual bool isBatteryConnect()      // true if battery detected
virtual bool isVbusIn()              // true if USB powered
virtual bool isCharging()            // true during charge
```

--------------------------------

### Configuring GPIO Pins

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/usage-examples.md

Set GPIO modes and read current configurations for AXP192/AXP202 devices. Ensure the pin index matches the hardware specification.

```cpp
void configureGpio() {
    // Configure GPIO0 (AXP192 specific)
    power.setGpioMode(0, OUTPUT);
    
    // Read GPIO mode
    uint8_t mode = power.getGpioMode(0);
}
```

--------------------------------

### Configure ESP32 Logging

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Uses ESP_LOGI for logging with the XPowers tag on ESP-IDF platforms.

```cpp
log_i("PMU initialized");  // Uses ESP_LOGI("XPowers", ...)
```

--------------------------------

### Bare-Metal Environment Integration

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Define necessary I2C abstractions when using the library outside of the standard Arduino framework.

```cpp
// Minimal Arduino compatibility layer
#include <cstdint>
#include <cstring>

typedef struct {
    // Your I2C bus structure
} TwoWire;

#define SDA 21
#define SCL 22
#define Wire (*(TwoWire*)NULL)

// Then include library
#include "XPowersLib.h"
```

--------------------------------

### Custom I2C Backend Implementation

Source: https://github.com/lewisxhe/xpowerslib/blob/master/_autodocs/configuration.md

Implement custom read and write functions for non-standard platforms or Linux.

```cpp
#include "XPowersLib.h"

int myI2CRead(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len) {
    // Platform-specific I2C read
    return 0;  // success
}

int myI2CWrite(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint8_t len) {
    // Platform-specific I2C write
    return 0;  // success
}

XPowersPMU power;

void setup() {
    power.begin(0x34, myI2CRead, myI2CWrite);
}
```