bq25887

Platform-agnostic Rust driver for the Texas Instruments BQ25887 synchronous battery charger. The crate targets no_std environments, provides an async-friendly I²C interface built on embedded-hal-async, and generates its register API at build time from a YAML manifest.

Features

• Asynchronous I²C driver (Bq25887Driver) built on embedded-hal-async::i2c::I2c.
• Complete register coverage through generated accessors (see src/bq25887.yaml).
• Convenience methods for common charger configuration flows.
• Optional logging integrations via the defmt-03 and log feature flags.
• no_std compatible (only depends on alloc-free crates by default).

Getting Started

Add the crate to your Cargo.toml:

[dependencies]
bq25887 = "0.1"
embedded-hal-async = "1.0"

# Optional feature flags:
# bq25887 = { version = "0.1", features = ["defmt-03"] }
# bq25887 = { version = "0.1", features = ["log"] }

Async usage

Use any I²C type that implements embedded_hal_async::i2c::I2c to talk to the charger:

use bq25887::Bq25887Driver;

pub async fn configure_charger<I2C>(i2c: I2C) -> Result<(), bq25887::BQ25887Error<I2C::Error>>
where
    I2C: embedded_hal_async::i2c::I2c,
{
    let mut driver = Bq25887Driver::new(i2c);

    // Refresh cached register view, including the cell voltage limit (register 0x00)
    driver.refresh_configuration_cache().await?;
    let limit = driver
        .configuration_cache()
        .cell_voltage_limit
        .expect("cache populated");

    // Raise the regulation voltage slightly (example value only!)
    let new_limit = limit.with_vcellreg(limit.vcellreg().saturating_add(1));
    driver.write_voltage_regulation_limit(new_limit).await?;

    // Check charger status after applying the new limit
    let status = driver.read_charger_status_1().await?;
    if status.chrg_stat() != 0 {
        // handle charger state change here (for example, log telemetry or notify a power-management state machine)
    }

    Ok(())
}

Charger configuration helpers

The driver exposes high-level methods for each register group, e.g. read_charge_current_limit, write_input_voltage_limit, and friends. These helpers wrap the generated register accessors and convert conversion errors into the crate’s custom error type.

Embassy integration

Enable the embassy feature to pull in the bq25887::embassy module. It provides thin wrappers around embassy_embedded_hal::shared_bus::asynch::i2c so you can build a driver from a shared Mutex-guarded bus via new_driver, or apply per-device bus settings with new_driver_with_config. These helpers make it straightforward to share one I²C peripheral across multiple Embassy tasks while keeping charger operations serialized.

use bq25887::embassy::{new_driver, SharedBus};
use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex;
use embassy_sync::mutex::Mutex;

// Replace `MyAsyncI2c` with your HAL's async I²C peripheral.
static BUS: SharedBus<ThreadModeRawMutex, MyAsyncI2c> = Mutex::new(MyAsyncI2c::new());

async fn poll_charger() -> Result<(), bq25887::BQ25887Error<MyAsyncI2c::Error>> {
    let mut driver = new_driver(&BUS);

    let status = driver.read_charger_status_1().await?;
    // Inspect `status` or update application state.
    Ok(())
}

Feature flags

Minimum Supported Rust Version

Rust 1.85 or newer is required. The MSRV will only increase in minor releases and will be documented in the changelog.

Build-time code generation

During cargo build, build.rs reads src/bq25887.yaml, generates the register accessor API, and writes it into $OUT_DIR. No manual steps are necessary for downstream users.

Development

cargo fmt --all
cargo clippy --all-targets --all-features
cargo test --all-features
cargo publish --dry-run

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the project by you shall be dual licensed as above, without any additional terms or conditions.

Links

• 📦 Crate: https://crates.io/crates/bq25887
• 📚 Docs: https://docs.rs/bq25887
• 🗺️ Repository: https://github.com/leftger/bq25887
• 📄 Datasheet: https://www.ti.com/lit/ug/slusd89b/slusd89b.pdf