Power mgt - AXP2101 Power management ESP32

Power management controller

Plugin details

Type: Power mgt

Name: AXP2101 Power management ESP32

Status: COLLECTION DISPLAY ENERGY NEOPIXEL

GitHub: P139_AXP2101.ino

Maintainer: tonhuisman

Used libraries: Own AXP2101 library, loosely based on M5Stack Core2 code

Description

I2C Power management controller. As found in some ESP32 models of M5Stack and TTGO.

Plugin is only available in ESP32 builds, as the library uses some software constructs that aren’t available for ESP8266, and this controller is currently only found to be used with ESP32 boards.

Configuration

Device configuration

  • Name A unique name should be entered here.

  • Enabled The device can be disabled or enabled. When not enabled the device should not use any resources.

Priority task

  • Priority task: The Priority task option is available in selected plugins only, where they can be configured to be initialized as part of the ESPEasy hardware initialization procedure.

For some ESP devices, the installed controllers need to be powered on via a Power management device before they can be initialized, but as the Power management controllers are implemented as plugins, to use the available Device configuration infrastructure, a mechanism to load and initialize these plugins before parts of the hardware, like the SPI interface, are initialized, the Priority task option is available.

Enable a Priority task

  • Configure the plugin as desired and required: All settings must be completed before assigning the Priority task setting, as once enabled, no settings can be changed, to avoid the unit getting into a hardware deadlock.

  • Check if the settings are as intended: Just a double-check option to validate the plugin settings. This includes enabling the plugin.

  • Enable the Priority task option: Once the plugin is enabled, the settings are saved in that state, and no other Power management plugin is enabled as Priority task, the checkbox will be enabled, and can be checked.

../_images/PriorityTask_Unchecked.png

  • Save the plugin with enabled Priority task: Enable the checkbox, and Submit the device page. After the usual page reload, the Enabled checkbox, while it still looks available, can no longer be unchecked, the Predefined device configuration won’t reload the page, and the Submit and Delete buttons are no longer available.

../_images/PriorityTask_Buttons.png

  • Reboot the ESP: To complete the Priority task configuration, the device needs to be restarted. This can be achieved by a reboot command, or using the Reboot button on the Tools page, a power cycle, or by pressing the reset button, if available.

When viewing the log during startup, these extra log messages are available at the Info level:

7982 : Info   : INIT : I2C
7985 : Info   : INIT : Check for Priority tasks
8035 : Info   : INIT : Started Priority task 1, [AXP192] Power mgt - AXP192 Power management
8036 : Info   : INIT : SPI not enabled

(The taskname and activated plugin can change, depending on the used Power mgt plugin.)

Note

An enabled Priority task can not be disabled, or re-enabled, using the TaskEnable,<task> and TaskDisable,<task> commands, to avoid hardware dead-lock situations.

Note

When a Priority task is enabled, on the Hardware tab the I2C GPIO configuration can not be changed anymore, as that could inhibit the correct working of the related plugin, and block the entire ESP unit from working as intended.

Now that the Power management controller is enabled and configured as a Priority task, the dependent hardware can be configured, in this case the SPI controller on the Hardware page.

After configuring the SPI settings, any Device that needs the SPI interface, like a TFT controller, can be configured as usual. Configuring the SPI settings may require to reset or power cycle the device.

Disable a Priority task

  • Prepare configuration to disable Priority task: If the Priority task needs to be disabled, it is required to execute a similar procedure as when enabling the Priority task, but in reverse order.

    • Disable Devices/Tasks that use the specific hardware: Any task that uses the hardware, controlled via the Priority task, like a TFT controller, must be disabled (and saved).

    • Disable the hardware interface: The same goes for the SPI interface, it must be disabled on the Hardware page, and the device should at least be rebooted, to activate that change.

  • Send the command to disable the priority task: To disable a priority task, a separate command is introduced: disableprioritytask,<task> that takes 1 required argument, the name or number of a task that is a Priority task. This will disable the Priority task state in memory, but not save that state!

  • Open the Device configuration: To complete disabling of the former Priority task, open the device confguration page for that task. You will notice that the Enabled checkbox is still disabled (can’t be clicked to change state). To complete this, the page should be saved using the Submit button. When the page is reloaded, also the task will be Disabled automatically! If so desired, instead of saving the page, the task can immediately be deleted by use of the Delete button.

  • Procedure completed: The Priority task is now disabled (or removed), and the settings are updated. After another reboot, the startup log will provide the matching information:

7882 : Info   : INIT : I2C
7886 : Info   : INIT : Check for Priority tasks
7896 : Info   : INIT : SPI not enabled

(No mention of a Priority task being started.)

[End of Priority task paragraph]

I2C Options

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the Hardware page

Device Settings

  • Charge LED: Select the working of the Charge LED (if that’s available on your device). Available options:

../_images/P139_ChargeLEDOptions.png

  • Off: Do not turn the LED on during charging.

  • Flash 1Hz: The LED will flash in a slow 1Hz tempo during charging.

  • Flash 4Hz: The LED will flash in a somewhat faster 4Hz rate during charging.

  • Steady On: The LED will be on during charging.

  • Generate events: Generate events when the charging state changes. There are 2 event values for this event: <taskname>#ChargingState=<NewState>,<OldState>.

Hardware ports AXP2101

  • Predefined device configuration The plugin provides presets for some specific devices:

../_images/P139_PredefinedDeviceOptions.png

  • Select an option to set default values: This option will always be selected when opening the page.

  • M5Stack Core2 v1.1: Settings for the M5Stack Core2 v1.1, and some derived special models, hardware (not for v1.0 hardware).

  • M5Stack Core S3: Settings for the M5Stack S3 hardware.

  • LilyGO T-Beam v1.2: Settings for the LilyGO T-Beam v1.2 series of GPS/LoRa devices with optional OLed display (not for v1.0 or v1.1 models).

  • LilyGO T-Beam S3 v3: Settings for the LilyGO T-Beam S3 v3 series hardware.

  • LilyGO T-Pcie v1.2: Settings for the LilyGO T-Pcie v1.2 series hardware.

  • User defined: To be able to configure all available ports the User defined option is added, f.e. when using a custom designed, or not yet supported, hardware setup.

When available, new predefined devices will be added. The User defined option will stay the last option.

Depending on the selected configuration, the ports of the AXP2101 can be set at a predefined value. When setting a value below the minimum value (shown next to the voltage selector), the port will be turned off. Above the maximum voltage is not supported/allowed. Stepsize/resolution depends on the port, and can be found in the technical documentation of the AXP2101.

Warning

Check board documentation for what each port is actually connected to, and the allowed voltage range for that port.

For the available ports, the initial state can be selected. The available options are:

../_images/P139_InitialStateOptions.png

  • Off: Sets the state to off level (0 V).

  • On: Sets the state to on (high) level.

  • Default: Doesn’t set the state of the port.

If the column shows [Protected] or [Disabled], that port is not available for use in the current configuration or in the commands (see below).

Output Configuration

  • Number Output Values: Select the number of values that have to be available. The default is set to Quad, as there are far more than 4 values available for display.

Available options: Single (1), Dual (2), Triple (3) and Quad (4).

  • Value 1..4: Select the desired value to be available in the Values fields. The name of the Values will be set to a matching default automatically, but can be changed afterward.

../_images/P139_ValueOptions.png ../_images/P139_ValueOptionsB.png

Available options:

  • None: To leave the value empty/0.00

  • DCDC1 .. CPULDOS: The voltage of the port.

  • ChargeLed: The state of the Charge LED, 0 = Off, 1 = Flash 1Hz, 2 = Flash 4Hz, 3 = Steady On.

  • BatCharge: The charge state percentage of the battery.

  • ChargingState: The state of charging, -1 = discharging, 0 = standby, 1 = charging.

  • BatPresent: Is a battery present (1) or disconnected (0).

  • ChipID: The ID set in the chip, 0 = not found, 71 = AXP2101.

  • ChargingDetail: The detailed state of charging.

    • 0: tri-charge

    • 1: pre-charge

    • 2: constant charge (CC)

    • 3: constant voltage (CV)

    • 4: charge done

    • 5: not charging

  • BatVoltage: The battery voltage.

  • BatTemp: The temperature of the battery, (if a battery-temperature sensor is installed).

  • BusVoltage: The bus-voltage.

  • SysVoltage: The system-voltage.

  • ChipTemp: The internal temperature of the chip.

Note

Not all options hold usable values for all boards, some may even be not connected. Check the board documentation for available values.

Data Acquisition

This group of settings, Single event with all values, Send to Controller and Interval settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.

  • Interval By default, Interval will be set to 0 sec. as it is optional. When set > 0 it is the frequency used to read sensor values and send these to any Controllers configured for this device.

Values

The measured values are available in variables, where the initial names are determined by the selected Value 1..4 settings. A formula can be set to recalculate. The number of decimals can be set as desired, and defaults to 2.

In selected builds, per Value Stats options are available, that when enabled, will gather the measured data and present most recent data in a graph, as described here: Task Value Statistics:

Commands

Command Syntax

Extra information
Commands to control the AXP2101 port voltages & states.
Attention: Commands will fail if the selected port is ‘Protected’ or ‘Disabled’ according to the selected Predefined device configuration.
axp,readchip
List the current values as configured in the chip. The logging level must be set to INFO. This data can be used to configure additional predefined devices.
axp,voltage,<port>,<voltage>
port one of the available ports.
voltage range: 0..<max_port_voltage> mV.
Set selected port to the specified voltage. When set to 0 mV the port will be turned off.
Ports of the AXP2101: DCDC1 .. DCDC4, ALDO1 .. ALDO4, BLDO1, BLDO2, DLDO1, DLDO2 or CPULDOS.
The max port voltage depends on the selected port, and is available in the technical documentation of the AXP2101.
axp,on,<port>
port one of the available ports.
Set the selected AXP2101 port ON.
Ports of the AXP2101: DCDC1 .. DCDC4, ALDO1 .. ALDO4, BLDO1, BLDO2, DLDO1, DLDO2 or CPULDOS.
axp,off,<port>
port one of the available ports.
Set the selected AXP2101 port OFF.
Ports of the AXP2101: DCDC1 .. DCDC4, ALDO1 .. ALDO4, BLDO1, BLDO2, DLDO1, DLDO2 or CPULDOS.
axp,percentage,<port>,<percentage>
port one of the available Ports.
percentage: 0 (off/low) or 1..100%
Set the selected port to Off for 0%, or On in range <min_range>..<max_range> for 1..100%.
Ports of the AXP2101: DCDC1 .. DCDC4, ALDO1 .. ALDO4, BLDO1, BLDO2, DLDO1, DLDO2 or CPULDOS.
The min and max port voltages depend on the selected port, and are available in the technical documentation of the AXP2101.

Extra values

As this plugin has more values available than can be set in the regular Values fields, all values are also available from the Get Config feature.

Most value options can be appended with .status (or .state for BatCharge and any of the ports)
.status: A text representation of the value will be returned, where applicable.
.state: A numeric representation of the value will be returned (usually the same as if the plain value name was used.)
Example: [<taskname>#ChargingDetail.status] will return constant charge (CC) for ChargingDetail = 2.

[<taskname>#<port>]
Ports of the AXP2101: DCDC1 .. DCDC4, ALDO1 .. ALDO4, BLDO1, BLDO2, DLDO1, DLDO2 or CPULDOS.

[<taskname>#ChargeLed]
The state of the Charge LED, 0 = Off, 1 = Flash 1Hz, 2 = Flash 4Hz, 3 = Steady On.

[<taskname>#BatCharge]
The charge state percentage of the battery.

[<taskname>#ChargingState]
The state of charging, -1 = Discharging, 0 = Standby, 1 = Charging.

[<taskname>#BatPresent]
Is a battery present (1) or disconnected (0). (no .status value available)

[<taskname>#ChipID]
The ID set in the chip, 71 = AXP2101 or any numeric value found, returning an empty value for the .status command-suffix.

[<taskname>#ChargingDet]
The detailed state of charging.

  • 0: tri-charge

  • 1: pre-charge

  • 2: constant charge (CC)

  • 3: constant voltage (CV)

  • 4: charge done

  • 5: not charging

[<taskname>#BatVoltage]
The current voltage of the battery.

[<taskname>#BatTemp]
The temperature of the battery, (if a battery-temperature sensor is installed).

[<taskname>#VBus]
The bus-voltage.

[<taskname>#VSys]
The charge state percentage of the battery.

[<taskname>#ChipTemp]
The internal temperature of the chip.

Extra events

Besides the regular events, of <taskname>#<valuename>=<value> or <taskname>#All=<value1>,..<valueN> when the Interval is set, there can be an extra event generated:

Event

Extra information
<taskname>#ChargingState=<old_state>,<new_state>
new_state / old_state: -1 (Discharging), 0 (Standby) or 1 (Charging).
Event generated when the Generate events checkbox is enabled.

Change log

Changed in version 2.0: added 2025-01-19 Initially added.