|
| 1 | +# M5PM1 Function Overview (English) |
| 2 | + |
| 3 | +Feature overview of the PM1 power management driver library for Arduino/ESP-IDF. |
| 4 | + |
| 5 | +- **Version**: 1.0.1 |
| 6 | +- **Default I2C address**: `0x6E` |
| 7 | +- **I2C speed**: Default 100 kHz, can switch to 400 kHz (the library rebuilds I2C internally after switching) |
| 8 | + |
| 9 | +## Project Structure and Roles |
| 10 | + |
| 11 | +- `src/M5PM1.h`: Public APIs, registers/enums, cache structure definitions. |
| 12 | +- `src/M5PM1.cpp`: Driver implementation, conflict checks, snapshot and cache logic. |
| 13 | +- `src/M5PM1_i2c_compat.h`: Arduino/ESP-IDF I2C compatibility wrapper. |
| 14 | + |
| 15 | +## Examples |
| 16 | + |
| 17 | +- `examples/basic_power_adc/basic_power_adc.ino`: Initialization, device info, VBAT/VIN/5V readings, ADC/temperature sampling, power rail control. |
| 18 | +- `examples/gpio_pwm/gpio_pwm.ino`: GPIO output/input reads and PWM breathing LED demo. |
| 19 | +- `examples/interrupt_button_sleep/interrupt_button_sleep.ino`: GPIO interrupt, button APIs, timer/wake, and shutdown demo. |
| 20 | +- `examples/neopixel/neopixel.ino`: NeoPixel rainbow demo. |
| 21 | + |
| 22 | +## Feature Categories |
| 23 | + |
| 24 | +### 1) Initialization and Logging |
| 25 | + |
| 26 | +- **Initialization** |
| 27 | + - Arduino: `begin(TwoWire*, addr, sda, scl, speed)` |
| 28 | + - ESP-IDF: `begin(i2c_port_t, addr, sda, scl, speed)` |
| 29 | + - ESP-IDF: `begin(i2c_master_bus_handle_t, addr, speed)` |
| 30 | + - ESP-IDF: `begin(i2c_bus_handle_t, addr, speed)` |
| 31 | +- **Logging** |
| 32 | + - `setLogLevel`/`getLogLevel` |
| 33 | + |
| 34 | +### 2) Device Information |
| 35 | + |
| 36 | +- `getDeviceId`/`getDeviceModel`/`getHwVersion`/`getSwVersion` |
| 37 | + |
| 38 | +### 3) GPIO Basics and Advanced Control |
| 39 | + |
| 40 | +- **Arduino style** |
| 41 | + - `pinMode`/`digitalWrite`/`digitalRead` |
| 42 | +- **With return status** |
| 43 | + - `pinModeWithRes`/`digitalWriteWithRes`/`digitalReadWithRes` |
| 44 | +- **Advanced configuration** |
| 45 | + - `gpioSet`/`gpioSetFunc`/`gpioSetMode`/`gpioSetOutput`/`gpioGetInput` |
| 46 | + - `gpioSetPull`/`gpioSetDrive`/`ledEnSetDrive` |
| 47 | + - `gpioSetWakeEnable`/`gpioSetWakeEdge` |
| 48 | +- **Pin status and validation** |
| 49 | + - `dumpPinStatus`/`verifyPinConfig`/`getPinStatus`/`getPinStatusArray` |
| 50 | + |
| 51 | +### 4) Power Hold |
| 52 | + |
| 53 | +- `gpioSetPowerHold`/`gpioGetPowerHold` |
| 54 | +- `ldoSetPowerHold`/`ldoGetPowerHold` |
| 55 | +- `dcdcSetPowerHold`/`dcdcGetPowerHold` |
| 56 | + |
| 57 | +### 5) ADC and Temperature |
| 58 | + |
| 59 | +- `analogRead`/`isAdcBusy`/`disableAdc`/`readTemperature` |
| 60 | + |
| 61 | +### 6) PWM |
| 62 | + |
| 63 | +- `setPwmFrequency`/`getPwmFrequency` |
| 64 | +- `setPwmDuty`/`getPwmDuty` (0-100%) |
| 65 | +- `setPwmDuty12bit`/`getPwmDuty12bit` (0-4095) |
| 66 | +- `setPwmConfig` |
| 67 | +- `analogWrite` (0-255) |
| 68 | + |
| 69 | +### 7) Voltage Reading |
| 70 | + |
| 71 | +- `readVref`/`getRefVoltage`/`readVbat`/`readVin`/`read5VInOut` |
| 72 | + |
| 73 | +### 8) Power Management and Battery |
| 74 | + |
| 75 | +- `getPowerSource` |
| 76 | +- `getWakeSource`/`clearWakeSource` |
| 77 | +- `setPowerConfig`/`getPowerConfig`/`clearPowerConfig` |
| 78 | +- `setChargeEnable`/`setDcdcEnable`/`setLdoEnable`/`set5VInOutEnable`/`setLedEnLevel` |
| 79 | +- `setBatteryLvp` |
| 80 | + |
| 81 | +### 9) Watchdog and Timer |
| 82 | + |
| 83 | +- `wdtSet`/`wdtFeed`/`wdtGetCount` |
| 84 | +- `timerSet`/`timerClear` |
| 85 | + |
| 86 | +### 10) Button |
| 87 | + |
| 88 | +- `btnSetConfig`/`btnGetState`/`btnGetFlag` |
| 89 | +- `setSingleResetDisable` (High risk)/`getSingleResetDisable` |
| 90 | +- `setDoubleOffDisable` (High risk)/`getDoubleOffDisable` |
| 91 | + |
| 92 | +### 11) Interrupts |
| 93 | + |
| 94 | +- **Status read and clear** |
| 95 | + - `irqGetGpioStatus`/`irqClearGpio` |
| 96 | + - `irqGetSysStatus`/`irqClearSys` |
| 97 | + - `irqGetBtnStatus`/`irqClearBtn` |
| 98 | +- **Enum-style read** |
| 99 | + - `irqGetGpioStatusEnum`/`irqGetSysStatusEnum`/`irqGetBtnStatusEnum` |
| 100 | +- **Interrupt masks** |
| 101 | + - `irqSetGpioMask`/`irqGetGpioMask`/`irqSetGpioMaskAll`/`irqGetGpioMaskAll` |
| 102 | + - `irqSetSysMask`/`irqGetSysMask`/`irqSetSysMaskAll`/`irqGetSysMaskAll` |
| 103 | + - `irqSetBtnMask`/`irqGetBtnMask`/`irqSetBtnMaskAll`/`irqGetBtnMaskAll` |
| 104 | + |
| 105 | +### 12) System Commands |
| 106 | + |
| 107 | +- `sysCmd`/`shutdown`/`reboot`/`enterDownloadMode` |
| 108 | +- `setDownloadLock` (High risk)/`getDownloadLock` |
| 109 | + |
| 110 | +### 13) NeoPixel |
| 111 | + |
| 112 | +- `setLeds`/`setLedCount`/`setLedColor`/`refreshLeds`/`disableLeds` |
| 113 | + |
| 114 | +### 14) AW8737A Pulse Control |
| 115 | + |
| 116 | +- `setAw8737aPulse`/`refreshAw8737aPulse` |
| 117 | + |
| 118 | +### 15) RTC RAM |
| 119 | + |
| 120 | +- `writeRtcRAM`/`readRtcRAM` |
| 121 | + |
| 122 | +### 16) I2C Configuration and Auto Wake |
| 123 | + |
| 124 | +- `setI2cConfig`/`switchI2cSpeed`/`getI2cSpeed` |
| 125 | +- `setI2cSleepTime`/`getI2cSleepTime` |
| 126 | +- `setAutoWakeEnable`/`isAutoWakeEnabled`/`sendWakeSignal` |
| 127 | +- Compatibility layer: `M5PM1_i2c_compat.h` |
| 128 | + |
| 129 | +### 17) State Snapshot/Cache/Validation |
| 130 | + |
| 131 | +- `setAutoSnapshot`/`isAutoSnapshotEnabled`/`updateSnapshot`/`verifySnapshot` |
| 132 | +- `validateConfig` |
| 133 | +- `getCachedPwmFrequency`/`getCachedPwmState`/`getCachedAdcState` |
| 134 | +- `getCachedPowerConfig`/`getCachedButtonConfig` |
| 135 | +- `getCachedIrqMasks`/`getCachedIrqStatus` |
| 136 | + |
| 137 | +## Precautions |
| 138 | + |
| 139 | +If using high-risk functions `setDownloadLock`, `setSingleResetDisable`, or `setDoubleOffDisable` results in the inability to enable download mode, single-click reset, or double-click shutdown, please disconnect/reconnect the battery (devices with built-in batteries may risk damage to the casing and components) or quickly short BAT and GND (this operation may damage the battery). |
| 140 | + |
| 141 | +## Pin and Function Limits |
| 142 | + |
| 143 | +| Area | Description | Notes | |
| 144 | +| :--- | :--- | :--- | |
| 145 | +| **WAKE mutual exclusion** | GPIO0/2 are mutually exclusive; GPIO3/4 are mutually exclusive | Only for WAKE function | |
| 146 | +| **Wake (WAKE)** | GPIO0/2/3/4 support wake | GPIO1 does not support WAKE | |
| 147 | +| **ADC channels** | GPIO1=ADC1, GPIO2=ADC2 | Temperature is an internal channel | |
| 148 | +| **PWM channels** | GPIO3=PWM0, GPIO4=PWM1 | Frequency shared across channels | |
| 149 | +| **NeoPixel** | GPIO0 only; LED count 1-31; data area 0x60 - 0x9F | I2C briefly non-interruptible during refresh | |
| 150 | +| **I2C sleep** | Idle timeout can enter low power | Sleep is ineffective when PWM is enabled or in download mode | |
| 151 | +| **Register blocks** | 0x00 - 0x0C, 0x10 - 0x19, 0x20 - 0x2A, 0x30 - 0x35, 0x38 - 0x3D, 0x40 - 0x45, 0x48 - 0x4A, 0x50, 0x53, 0x60 - 0x9F, 0xA0 - 0xBF | Supports continuous read/write | |
| 152 | + |
| 153 | +## Version and Dependencies |
| 154 | + |
| 155 | +- **Version**: 1.0.1 |
| 156 | +- **Platforms**: Arduino / ESP-IDF (>=4.4) |
| 157 | +- **Dependency**: espressif/i2c_bus |
0 commit comments