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.

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.
• Unified Async/Blocking API: Uses the bisync crate to provide both asynchronous (Axp192Async) and blocking (Axp192) drivers from the same codebase, with no feature flags required.
• 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/Axp192Async 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.
• Unified Async/Blocking API: Both async and blocking drivers are always available; no feature flags required.
• 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 = "0.1.0"
   # For blocking usage (Axp192):
   embedded-hal = "1.0.0"
   # For async usage (Axp192Async):
   embedded-hal-async = "1.0.0"
   

   Note: Add the relevant embedded-hal crate for your use case, no need for both

   • Use embedded-hal for blocking drivers (Axp192)
   • Use embedded-hal-async for async drivers (Axp192Async)

2. Instantiate the driver with your I2C bus:

   • Blocking:

     use axp192_dd::{Axp192, LdoId};
     use embedded_hal::i2c::I2c;
     
     let i2c_bus_impl = /* your I2C bus */;
     let mut axp = Axp192::new(i2c_bus_impl);
     axp.set_ldo_voltage_mv(LdoId::Ldo2, 3300)?;
     

   • Async:

     use axp192_dd::{Axp192Async, LdoId};
     use embedded_hal_async::i2c::I2c;
     
     let i2c_bus_impl = /* your I2C bus */;
     let mut axp = Axp192Async::new(i2c_bus_impl);
     axp.set_ldo_voltage_mv(LdoId::Ldo2, 3300).await?;
     

Examples

Examples for ESP32-C3 using 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 defmt
  

• Blocking Example: examples/test_pmic_blocking.rs

  cargo run --release --example test_pmic_blocking --features 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; async and blocking drivers are always available.
• 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.