[P139] Add documentation

docs/source/Plugin/P139.rst

@@ -0,0 +1,185 @@
+.. include:: ../Plugin/_plugin_substitutions_p13x.repl
+.. _P139_page:
+
+|P139_typename|
+==================================================
+
+|P139_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P139_type|
+
+Name: |P139_name|
+
+Status: |P139_status|
+
+GitHub: |P139_github|_
+
+Maintainer: |P139_maintainer|
+
+Used libraries: |P139_usedlibraries|
+
+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
+--------------
+
+.. image:: P139_DeviceConfiguration.png
+  :alt: 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.
+
+.. include:: PriorityTask.rst
+
+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 :ref:`Hardware_page`
+
+Device Settings
+^^^^^^^^^^^^^^^^
+
+* **Charge LED**: Select the working of the Charge LED (if that's available on your device). Available options:
+
+.. image:: 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:
+
+.. image:: 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:
+
+.. image:: 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.
+
+.. image:: P139_ValueOptions.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 current that the battery is being charged or discharged with.
+
+* *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``
+
+.. 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: :ref:`Task Value Statistics:  <Task Value Statistics>`
+
+Commands
+~~~~~~~~
+
+.. include:: P139_commands.repl
+
+
+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.
+
+.. include:: P139_values.repl
+
+
+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:
+
+.. include:: P139_events.repl
+
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+
+  |added| 2025-01-19 Initially added.

docs/source/Plugin/P139_commands.repl

@@ -0,0 +1,53 @@
+.. csv-table::
+    :header: "Command Syntax", "Extra information"
+    :widths: 20, 30
+
+    "
+    | 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.
+    "

docs/source/Plugin/P139_events.repl

@@ -0,0 +1,12 @@
+.. csv-table::
+    :header: "Event", "Extra information"
+    :widths: 20, 30
+
+    "
+    | ``<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.
+    "

docs/source/Plugin/P139_values.repl

@@ -0,0 +1,54 @@
+.. csv-table::
+    :escape: ^
+    :widths: 20, 30
+
+    "
+    Every value option can be appended with ``.status`` (or ``.state`` for ``BatCharge`` and any of the ports)
+    ","
+    | ``.status``: A text representation of the value will be returned.
+    | ``.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 current that the battery is being charged or discharged with.
+    "
+    "
+    ``[<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``
+    "

docs/source/Plugin/_Plugin.rst

@@ -374,6 +374,7 @@ There are different released versions of ESP Easy:
    ":ref:`P135_page`","|P135_status|","P135"
    ":ref:`P137_page`","|P137_status|","P137"
    ":ref:`P138_page`","|P138_status|","P138"
+   ":ref:`P139_page`","|P139_status|","P139"
    ":ref:`P141_page`","|P141_status|","P141"
    ":ref:`P142_page`","|P142_status|","P142"
    ":ref:`P143_page`","|P143_status|","P143"

docs/source/Plugin/_plugin_categories.repl

@@ -24,7 +24,7 @@
 .. |Plugin_Notify| replace:: :ref:`P055_page`, :ref:`P065_page`
 .. |Plugin_Output| replace:: :ref:`P029_page`, :ref:`P038_page`, :ref:`P041_page`, :ref:`P042_page`, :ref:`P043_page`, :ref:`P070_page`, :ref:`P124_page`, :ref:`P126_page`, :ref:`P128_page`, :ref:`P152_page`, :ref:`P162_page`, :ref:`P166_page`
 .. |Plugin_Position| replace:: :ref:`P082_page`, :ref:`P121_page`, :ref:`P142_page`
-.. |Plugin_PowerMgt| replace:: :ref:`P137_page`, :ref:`P138_page`
+.. |Plugin_PowerMgt| replace:: :ref:`P137_page`, :ref:`P138_page`, :ref:`P139_page`
 .. |Plugin_Presence| replace:: :ref:`P159_page`
 .. |Plugin_Regulator| replace:: :ref:`P021_page`
 .. |Plugin_RFID| replace:: :ref:`P008_page`, :ref:`P017_page`, :ref:`P040_page`, :ref:`P111_page`

docs/source/Plugin/_plugin_substitutions_p13x.repl

@@ -88,3 +88,16 @@
 .. |P138_maintainer| replace:: `tonhuisman`
 .. |P138_compileinfo| replace:: `.`
 .. |P138_usedlibraries| replace:: `https://github.com/codewitch-honey-crisis/htcw_ip5306`
+
+.. |P139_name| replace:: :cyan:`AXP2101 Power management ESP32`
+.. |P139_type| replace:: :cyan:`Power mgt`
+.. |P139_typename| replace:: :cyan:`Power mgt - AXP2101 Power management ESP32`
+.. |P139_porttype| replace:: `.`
+.. |P139_status| replace:: :yellow:`COLLECTION` :yellow:`DISPLAY` :yellow:`ENERGY` :yellow:`NEOPIXEL`
+.. |P139_github| replace:: P139_AXP2101.ino
+.. _P139_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P139_AXP2101.ino
+.. |P139_usedby| replace:: `.`
+.. |P139_shortinfo| replace:: `Power management controller`
+.. |P139_maintainer| replace:: `tonhuisman`
+.. |P139_compileinfo| replace:: `.`
+.. |P139_usedlibraries| replace:: `Own AXP2101 library, loosely based on M5Stack Core2 code`

docs/source/Reference/Command.rst

@@ -763,6 +763,11 @@ P137 :ref:`P137_page`
 
 .. include:: ../Plugin/P137_commands.repl
 
+P139 :ref:`P139_page`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: ../Plugin/P139_commands.repl
+
 P141 :ref:`P141_page`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/Reference/Events.rst

@@ -550,6 +550,11 @@ P138 :ref:`P138_page`
 
 .. include:: ../Plugin/P138_events.repl
 
+P139 :ref:`P139_page`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: ../Plugin/P139_events.repl
+
 P143 :ref:`P143_page`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^