From 7edb91712a31bf1bfb3480df6e56dd78b8578269 Mon Sep 17 00:00:00 2001
From: 916BGAI <916772719@qq.com>
Date: Mon, 11 Nov 2024 15:05:35 +0800
Subject: [PATCH] add pmu docs and example

---
 docs/doc/en/modules/pmu.md                    | 79 +++++++++++++++++++
 docs/doc/en/sidebar.yaml                      |  2 +
 docs/doc/zh/modules/pmu.md                    | 79 +++++++++++++++++++
 docs/doc/zh/sidebar.yaml                      |  2 +
 .../others/pmu_axp2101/axp2101_example.py     | 55 +++++++++++++
 examples/ext_dev/pmu_example.py               | 38 +++++++++
 6 files changed, 255 insertions(+)
 create mode 100644 docs/doc/en/modules/pmu.md
 create mode 100644 docs/doc/zh/modules/pmu.md
 create mode 100644 examples/ext_dev/others/pmu_axp2101/axp2101_example.py
 create mode 100644 examples/ext_dev/pmu_example.py

diff --git a/docs/doc/en/modules/pmu.md b/docs/doc/en/modules/pmu.md
new file mode 100644
index 00000000..5becda3d
--- /dev/null
+++ b/docs/doc/en/modules/pmu.md
@@ -0,0 +1,79 @@
+---
+title: MaixCAM MaixPy Power Management Unit
+update:
+  - date: 2024-11-08
+    author: 916BGAI
+    version: 1.0.0
+    content: Initial document
+---
+
+<br/>
+
+>! Warning !!!
+>Setting incorrect voltages may damage the `MaixCAM-Pro`. Do not modify the voltages of `DCDC2~DCDC5`, `ALDO1~ALDO4`, and `BLDO1~BLDO2` unless you fully understand the purpose and consequences of the adjustment.
+
+## Introduction
+
+The `MaixCAM-Pro` is equipped with the `AXP2101` Power Management Unit (PMU), providing multi-channel power outputs, charging management, and system protection functions. The `AXP2101` supports linear charging and features `5` `DC-DC` channels and 11 `LDO` channels, meeting a variety of power requirements. It also comes with multiple-channel `ADCs` for real-time monitoring of voltage and temperature, and integrates protection features such as over-voltage, over-current, and over-temperature to ensure system stability and safety.
+
+> The MaixCAM does not have an onboard power management unit. If power management functionality is required, please connect an external power management unit.
+
+## Using Power Management Unit in MaixPy
+
+Operate the AXP2101 device using the PMU module.
+
+Example:
+
+```python
+from maix import time, app
+from maix.ext_dev import pmu
+
+p = pmu.PMU("axp2101")
+
+# Get battery percent
+print(f"Battery percent: {p.get_bat_percent()}%")
+
+# Set the max battery charging current
+p.set_bat_charging_cur(1000)
+print(f"Max charging current: {p.get_bat_charging_cur()}mA")
+
+# Set DCDC1 voltage (!!! Do not modify the voltage of other channels,
+# as it may damage the device.)
+old_dcdc1_voltage = p.get_vol(pmu.PowerChannel.DCDC1)
+print(f"Old DCDC1 voltage: {old_dcdc1_voltage}mV")
+p.set_vol(pmu.PowerChannel.DCDC1, 3000)
+new_dcdc1_voltage = p.get_vol(pmu.PowerChannel.DCDC1)
+print(f"New DCDC1 voltage: {new_dcdc1_voltage}mV")
+
+# Get all channel voltages
+channels = [
+    pmu.PowerChannel.DCDC1, pmu.PowerChannel.DCDC2, pmu.PowerChannel.DCDC3,
+    pmu.PowerChannel.DCDC4, pmu.PowerChannel.DCDC5, pmu.PowerChannel.ALDO1,
+    pmu.PowerChannel.ALDO2, pmu.PowerChannel.ALDO3, pmu.PowerChannel.ALDO4,
+    pmu.PowerChannel.BLDO1, pmu.PowerChannel.BLDO2
+]
+
+print("------ All channel voltages: ------")
+for channel in channels:
+    print(f"{channel.name}: {p.get_vol(channel)}")
+print("-----------------------------------")
+
+# Poweroff (Important! Power will be cut off immediately)
+# p.poweroff()
+
+while not app.need_exit():
+    time.sleep_ms(1000)
+```
+
+> You can also use the `AXP2101` module to configure the power management unit. The usage is similar to the `PMU` module, and you can refer to the example script [axp2101_example.py](https://github.com/sipeed/MaixPy/blob/main/examples/ext_dev/others/pmu_axp2101/axp2101_example.py) for guidance.
+
+Initialize the `PMU` object, and call `get_bat_percent()` to get the current battery level. Call `set_bat_charging_cur()` to set the maximum charging current.
+
+Calling `poweroff()` will immediately cut off power to the device. Please ensure that data in memory is synced to disk before using this function.
+
+You can use the `set_vol()` and `get_vol()` methods to set and read the voltage of the `DC-DC` and `LDO` channels, respectively. Currently, the following channels of the `AXP2101` are supported for voltage configuration: `DCDC1~DCDC5`, `ALDO1~ALDO4`, and `BLDO1~BLDO2`.
+
+>! Warning !!!
+>Setting incorrect voltages may damage the `MaixCAM-Pro`. Do not modify the voltages of `DCDC2~DCDC5`, `ALDO1~ALDO4`, and `BLDO1~BLDO2` unless you fully understand the purpose and consequences of the adjustment. If you need to test, please use the `DCDC1` channel.
+
+For detailed information on the PMU API, please refer to the [PMU API Documentation](../../../api/maix/ext_dev/pmu.md)
\ No newline at end of file
diff --git a/docs/doc/en/sidebar.yaml b/docs/doc/en/sidebar.yaml
index e43b8aa0..31e2f407 100644
--- a/docs/doc/en/sidebar.yaml
+++ b/docs/doc/en/sidebar.yaml
@@ -172,6 +172,8 @@ items:
         label: TOF
     -   file: modules/thermal_cam.md
         label: Thermal imaging
+        file: modules/pmu.md
+        label: Power Management Unit
 
 -   label: Projects
     items:
diff --git a/docs/doc/zh/modules/pmu.md b/docs/doc/zh/modules/pmu.md
new file mode 100644
index 00000000..bbc2b3d5
--- /dev/null
+++ b/docs/doc/zh/modules/pmu.md
@@ -0,0 +1,79 @@
+---
+title: MaixCAM MaixPy 电源管理单元
+update:
+  - date: 2024-11-08
+    author: 916BGAI
+    version: 1.0.0
+    content: 初版文档
+---
+
+<br/>
+
+>! 警告 ！！！
+>设置错误的电压可能会损坏 `MaixCAM-Pro`。除非明确了解调整目的和后果，否则请勿修改 `DCDC2~DCDC5`、`ALDO1~ALDO4` 和 `BLDO1~BLDO2` 的电压。
+
+## 简介
+
+`MaixCAM-Pro` 板载了 `AXP2101` 电源管理单元，提供多通道电源输出、充电管理以及系统保护功能。`AXP2101` 支持线性充电，拥有 `5` 个 `DC-DC` 通道和 `11` 个 `LDO` 通道，能够满足多种电源需求。它还配备了多通道 `ADC`，用于实时监控电压和温度，并集成了过压、过流和过温等保护功能，确保系统的稳定性和安全性。
+
+> MaixCAM 没有板载电源管理单元，如需使用电源管理功能请自行外接。
+
+## MaixPy 中使用电源管理单元
+
+使用 `PMU` 模块操作 `AXP2101` 设备。
+
+示例代码:
+
+```python
+from maix import time, app
+from maix.ext_dev import pmu
+
+p = pmu.PMU("axp2101")
+
+# Get battery percent
+print(f"Battery percent: {p.get_bat_percent()}%")
+
+# Set the max battery charging current
+p.set_bat_charging_cur(1000)
+print(f"Max charging current: {p.get_bat_charging_cur()}mA")
+
+# Set DCDC1 voltage (!!! Do not modify the voltage of other channels,
+# as it may damage the device.)
+old_dcdc1_voltage = p.get_vol(pmu.PowerChannel.DCDC1)
+print(f"Old DCDC1 voltage: {old_dcdc1_voltage}mV")
+p.set_vol(pmu.PowerChannel.DCDC1, 3000)
+new_dcdc1_voltage = p.get_vol(pmu.PowerChannel.DCDC1)
+print(f"New DCDC1 voltage: {new_dcdc1_voltage}mV")
+
+# Get all channel voltages
+channels = [
+    pmu.PowerChannel.DCDC1, pmu.PowerChannel.DCDC2, pmu.PowerChannel.DCDC3,
+    pmu.PowerChannel.DCDC4, pmu.PowerChannel.DCDC5, pmu.PowerChannel.ALDO1,
+    pmu.PowerChannel.ALDO2, pmu.PowerChannel.ALDO3, pmu.PowerChannel.ALDO4,
+    pmu.PowerChannel.BLDO1, pmu.PowerChannel.BLDO2
+]
+
+print("------ All channel voltages: ------")
+for channel in channels:
+    print(f"{channel.name}: {p.get_vol(channel)}")
+print("-----------------------------------")
+
+# Poweroff (Important! Power will be cut off immediately)
+# p.poweroff()
+
+while not app.need_exit():
+    time.sleep_ms(1000)
+```
+
+> 也可以使用 `AXP2101` 模块对电源管理单元进行设置。使用方法和 `PMU` 模块类似，可以参考例程 [axp2101_example.py](https://github.com/sipeed/MaixPy/blob/main/examples/ext_dev/others/pmu_axp2101/axp2101_example.py)
+
+初始化 `PMU` 对象，调用 `get_bat_percent()` 即可获取当前电池电量。调用 `set_bat_charging_cur()` 可以设置最大充电电流。
+
+调用 `poweroff()` 设备将立即断电。在使用前，请确保将内存中的数据同步到磁盘。
+
+调用 `set_vol()` 和 `get_vol()` 方法可以分别设置和读取 `DC-DC` 和 `LDO` 通道的电压。当前支持对 `AXP2101` 的以下通道进行电压设置：`DCDC1~DCDC5`、`ALDO1~ALDO4` 和 `BLDO1~BLDO2`。
+
+>! 警告 ！！！
+>设置错误的电压可能会损坏 `MaixCAM-Pro`。除非明确了解调整目的和后果，否则请勿修改 `DCDC2~DCDC5`、`ALDO1~ALDO4` 和 `BLDO1~BLDO2` 的电压。若需测试，请使用 `DCDC1` 通道。
+
+有关 PMU API 的详细说明请看 [PMU API 文档](../../../api/maix/ext_dev/pmu.md)
\ No newline at end of file
diff --git a/docs/doc/zh/sidebar.yaml b/docs/doc/zh/sidebar.yaml
index f24cbdbc..a99d5481 100644
--- a/docs/doc/zh/sidebar.yaml
+++ b/docs/doc/zh/sidebar.yaml
@@ -173,6 +173,8 @@ items:
         label: TOF 测距
     -   file: modules/thermal_cam.md
         label: 热成像摄像头
+        file: modules/pmu.md
+        label: 电源管理单元
 
 -   label: 项目实战
     items:
diff --git a/examples/ext_dev/others/pmu_axp2101/axp2101_example.py b/examples/ext_dev/others/pmu_axp2101/axp2101_example.py
new file mode 100644
index 00000000..3f5e8fcd
--- /dev/null
+++ b/examples/ext_dev/others/pmu_axp2101/axp2101_example.py
@@ -0,0 +1,55 @@
+from maix import time, app
+from maix.ext_dev import axp2101
+
+axp = axp2101.AXP2101()
+
+# Get battery percent
+print(f"Battery percent: {axp.get_bat_percent()}%")
+
+# Set the max battery charging current
+charging_current = axp2101.ChargerCurrent.CHG_CUR_1000MA
+axp.set_bat_charging_cur(charging_current)
+max_charging_current = (int(axp.get_bat_charging_cur()) - 8) * 100 + 200
+print(f"Max charging current: {max_charging_current}mA")
+
+# Set DCDC1 voltage (!!! Do not modify the voltage of other channels,
+# as it may damage the device.)
+old_dcdc1_voltage = axp.dcdc1()
+new_dcdc1_voltage = axp.dcdc1(3000)
+print(f"Old DCDC1 voltage: {old_dcdc1_voltage}mV")
+print(f"New DCDC1 voltage: {new_dcdc1_voltage}mV")
+
+# List all power channels for voltage reading
+channels = [
+    ('DCDC1', axp.dcdc1),
+    ('DCDC2', axp.dcdc2),
+    ('DCDC3', axp.dcdc3),
+    ('DCDC4', axp.dcdc4),
+    ('DCDC5', axp.dcdc5),
+    ('ALDO1', axp.aldo1),
+    ('ALDO2', axp.aldo2),
+    ('ALDO3', axp.aldo3),
+    ('ALDO4', axp.aldo4),
+    ('BLDO1', axp.bldo1),
+    ('BLDO2', axp.bldo2),
+]
+
+# Get all channel voltages
+print("------ All channel voltage: ------")
+for name, channel in channels:
+    print(f"{name}: {channel()}")
+print("----------------------------------")
+
+# Set power-off time, device will shut down if the 
+# power button is held down longer than this time.
+axp.set_poweroff_time(axp2101.PowerOffTime.POWEROFF_4S)
+
+# Set power-on time, device will power on if the 
+# power button is held down longer than this time.
+axp.set_poweron_time(axp2101.PowerOnTime.POWERON_128MS)
+
+# Poweroff (Important! Power will be cut off immediately)
+# axp.poweroff()
+
+while not app.need_exit():
+    time.sleep_ms(1000)
\ No newline at end of file
diff --git a/examples/ext_dev/pmu_example.py b/examples/ext_dev/pmu_example.py
new file mode 100644
index 00000000..3c9143d8
--- /dev/null
+++ b/examples/ext_dev/pmu_example.py
@@ -0,0 +1,38 @@
+from maix import time, app
+from maix.ext_dev import pmu
+
+p = pmu.PMU("axp2101")
+
+# Get battery percent
+print(f"Battery percent: {p.get_bat_percent()}%")
+
+# Set the max battery charging current
+p.set_bat_charging_cur(1000)
+print(f"Max charging current: {p.get_bat_charging_cur()}mA")
+
+# Set DCDC1 voltage (!!! Do not modify the voltage of other channels,
+# as it may damage the device.)
+old_dcdc1_voltage = p.get_vol(pmu.PowerChannel.DCDC1)
+print(f"Old DCDC1 voltage: {old_dcdc1_voltage}mV")
+p.set_vol(pmu.PowerChannel.DCDC1, 3000)
+new_dcdc1_voltage = p.get_vol(pmu.PowerChannel.DCDC1)
+print(f"New DCDC1 voltage: {new_dcdc1_voltage}mV")
+
+# Get all channel voltages
+channels = [
+    pmu.PowerChannel.DCDC1, pmu.PowerChannel.DCDC2, pmu.PowerChannel.DCDC3,
+    pmu.PowerChannel.DCDC4, pmu.PowerChannel.DCDC5, pmu.PowerChannel.ALDO1,
+    pmu.PowerChannel.ALDO2, pmu.PowerChannel.ALDO3, pmu.PowerChannel.ALDO4,
+    pmu.PowerChannel.BLDO1, pmu.PowerChannel.BLDO2
+]
+
+print("------ All channel voltages: ------")
+for channel in channels:
+    print(f"{channel.name}: {p.get_vol(channel)}")
+print("-----------------------------------")
+
+# Poweroff (Important! Power will be cut off immediately)
+# p.poweroff()
+
+while not app.need_exit():
+    time.sleep_ms(1000)
\ No newline at end of file