AXP192 Power Management IC Driver (axp192-dd)

This crate provides a no_std driver for the AXP192 power management IC, commonly used in M5Stack devices and other embedded systems. The project aims to support the full functionality of the AXP192 PMIC, leveraging the device-driver crate with a declarative YAML manifest (device.yaml) for a robust, type-safe register map definition. The low-level API covers 100% of the AXP192's registers, with device.yaml providing a comprehensive and accurate description of all registers and their fields. While the low-level API is complete, some high-level convenience methods for easier access may still be added in the future.

Attention: to use this crate make sure to enable either async or blocking feature flag.

Overview

The axp192-dd driver offers:

• Declarative Configuration: The AXP192 register map is defined in device.yaml, enabling device-driver to generate a type-safe, low-level register access API. This approach enhances maintainability and extensibility.
• Flexible Operation Modes: Supports both asynchronous (async/await) and blocking I2C communication via feature flags. The bisync crate provides a unified API, reducing code duplication.
• High-Level and Low-Level APIs:
  • High-level methods simplify tasks like setting DC-DC/LDO voltages, reading ADC voltages.
  • Low-level API (via the ll field of the Axp192 struct) offers direct, type-safe access to all registers defined in device.yaml via raw values or enums.
• Peripheral Control: Manages DC-DCs, LDOs, GPIOs, ADC conversions, interrupts, and power settings.
• no_std and no-alloc: Optimized for bare-metal and RTOS environments.
• Optional Logging: Supports defmt and the log facade for debugging.

⚠️ Warning! ⚠️

Caution! The AXP192 controls power to the microcontroller and critical components. Incorrect configuration may cause malfunctions, data loss, or hardware damage.

• Always consult the official AXP192 datasheet (see Datasheet) before modifying power settings.
• Verify voltage and current limits for your device and components.
• Exercise caution when adjusting output voltages or charging parameters.
• The authors are not liable for damage caused by misuse.

Features

• Declarative Register Map: Defined in device.yaml.
• Async/Await Support: Enabled by the async feature with embedded-hal-async.
• Blocking Support: Enabled by the blocking feature with embedded-hal.
• Unified API with bisync: Shared logic for async and blocking modes.
• Type-Safe Register Access: Generated by device-driver.
• Comprehensive Control: (See device.yaml for details)
  • DC-DC and LDO voltage/enable.
  • Battery charging and status.
  • ADC readings (voltages, currents, temperature).
  • GPIO configuration.
  • Interrupt management.
  • Power key (PEK) parameters.
• no_std and no-alloc.
• Optional Logging: Supports defmt and log facade.

Getting Started

1. Add axp192-dd to Cargo.toml:

   [dependencies]
   axp192-dd = { version = "0.1.0", features = ["async"] } # Or "blocking"
   embedded-hal-async = "1.0.0" # If using async feature
   # Or
   embedded-hal = "1.0.0" # If using blocking feature
   

   Note: Other dependencies required by axp192-dd are managed internally and do not need to be added manually.

2. Instantiate the driver with your I2C bus:

   use axp192_dd::{Axp192, LdoId};
   #[cfg(feature = "blocking")] {
   use embedded_hal::i2c::I2c;
   
   pub struct MyI2cBus;
   
   struct MyI2cError;
   
   impl I2c for MyI2cBus {
       type Error = MyI2cError;
   
       fn transaction(&mut self, _a: u8, _o: &mut [embedded_hal::i2c::Operation<'_>]) -> Result<(), Self::Error> {
         todo!() }
   }
   
   # initialize
   let i2c_bus_impl = MyI2cBus;
   let mut axp = Axp192::new(i2c_bus_impl);
   axp.set_ldo_voltage_mv(LdoId::Ldo2, 3300)?;
   # returns:  Ok::<(), axp192_dd::AxpError<MyI2cError>>(())
   

   Methods are async fn with the async feature, otherwise blocking.

Examples

Examples for ESP32-C3 using Rust on ESP and esp-hal are included. Setup is required (see esp-hal docs).

• Async Example: examples/test_pmic_async.rs

  cargo run --release --example test_pmic_async --features async,defmt
  

• Blocking Example: examples/test_pmic_blocking.rs

  cargo run --release --example test_pmic_blocking --features blocking,defmt
  

Register Map

The AXP192 register map is defined in device.yaml, which device-driver uses to generate Rust code. This file specifies:

• Register names, addresses, and sizes.
• Field names, bit positions, and access modes (Read-Only, Read-Write, Write-1-Clear).
• Enumerations for field values (e.g., charging currents, voltage settings).
• Reset values and descriptions based on the datasheet.

Access the low-level API via axp.ll (e.g., axp.ll.power_status().read()). High-level methods provide convenient access to common features.

Supported Devices

The AXP192 is used in devices including:

• M5Stack Core 2 (and Core 2 for AWS)
• M5Stack Tough
• M5StickC
• M5StickC PLUS

Datasheet

• AXP192 Datasheet v1.1 (English Draft)

Feature Flags

• default = []: No default features; explicitly select async or blocking.
• async: Enables async operation with embedded-hal-async.
• blocking: Enables blocking operation with embedded-hal.
  • Note: async and blocking are mutually exclusive.
• std: Enables std features for thiserror.
• log: Enables log facade logging. Requires log = { version = "0.4", optional = true }.
• defmt: Enables defmt logging. Requires defmt = { version = "1.0", optional = true }.

Contributions are welcome! While the register map in device.yaml is complete, you can contribute by:

• Adding high-level convenience methods to simplify common operations (e.g., battery management, interrupt handling).
• Enhancing documentation with additional examples or clarifications.
• Reporting issues or suggesting improvements.
• Suggest code refactoring.

Please submit issues, fork the repository, and create pull requests.

License

This project is dual-licensed under the MIT License or Apache License 2.0, at your option.