diff --git a/docs/en/api/power.md b/docs/en/api/power.md index 77b20ba0..28887f7a 100644 --- a/docs/en/api/power.md +++ b/docs/en/api/power.md @@ -1,5 +1,170 @@ # Power +* Power related functions depend on the IP5306 chip. Please refer to the data sheet [IP5306] (https://github.com/m5stack/M5-Schematic/blob/master/Core/IIC_IP5306_REG_V1.4.pdf) as required. +* The older M5STACK hardware does not support communication with IP5306 chip. When using functions, also consider supporting out of control cases. * + +Use initialization, communication check, and control in this order, as shown in the example below. + +```arduino +deepSleep(SLEEP_SEC(5)); + M5.Power.begin(); + if(!M5.Power.canControl()) { + //can't control. + return; + } + M5.Power.lightSleep(SLEEP_SEC(5)); +``` +## begin() + +**Syntax:** + +void begin() + +**Description:** + +Performs initialization of Power class. + + +**Function argument** + +No argument. + +**Function return value** + +No return value. + +## setPowerBoostOnOff() + +**Syntax:** + +bool setPowerBoostOnOff(bool en) + +**Description:** + +Change the power on / off method. +The power does not turn off when connected via USB. + +**Function argument** + +true: Press and hold to turn on / off. +false: Turn on / off with two short presses. + +**Function return value** + +true: Control success, +false: Control failure. + +## setPowerBoostSet() + +**Syntax:** + +bool setPowerBoostSet(bool en) + +**Description:** + +Change the power on / off method. +The power does not turn off when connected via USB. + +**Function argument** + +true: ON / OFF in one short press. +false: Follow the setPowerBoostOnOff () method. + +**Function return value** + +true: Control success, +false: Control failure. + +## setPowerVin() + +**Syntax:** + +bool setPowerVin(bool en) + +**Description:** + +When the power supply from USB etc. is cut off, +Decide whether to turn on the power again. + +**Function argument** + +true: The power will be turned on again. +false: The power will not be turned on again. + +**Function return value** + +true: Control success, +false: Control failure. + +## setPowerWLEDSet() + +**Syntax:** + +bool setPowerWLEDSet(bool en) + +**Description:** + +Set the mode to turn on the power LED. +In addition, IP5306 of M5GO is not wired and can not be controlled by this function. + +**Function argument** + +true: Turn on the LED with two short presses +false: Turn on the LED with Press and hold + +**Function return value** + +true: Control success, +false: Control failure. + +## setPowerBtnEn() + +**Syntax:** + +bool setPowerBtnEn(bool en) + +**Description:** + +Set whether to accept the power button. + +About the behavior when not accepting the button: +If the power is on, the power button only accepts CPU reset. +If the power is not supplied, the power can not be turned on. + +**Function argument** + +true: Accept power operation. +false: Does not accept power control. + +**Function return value** + +true: Control success, +false: Control failure. + + +## setLowPowerShutdownTime() + +**Syntax:** + +bool setLowPowerShutdownTime(ShutdownTime time) + +**Description:** + +Set the waiting time until IP5306 makes the energy saving judgment and the power is turned off. + +**Function argument** + +ShutdownTime::SHUTDOWN_8S : wait at 8sec. +ShutdownTime::SHUTDOWN_16S : wait at 16sec. +ShutdownTime::SHUTDOWN_32S : wait at 32sec. +ShutdownTime::SHUTDOWN_64S : wait at 64sec. + +**Function return value** + +true: Control success, +false: Control failure. + + ## setPowerBoostKeepOn() **Syntax:** @@ -12,38 +177,14 @@ This function sets/unsets always boost output mode. **Function argument** -true: Turn on always boost output mode, -false: Turn off always boost output mode. +true: Always output power. +false: not Always output power. **Function return value** true: Control success, false: Control failure. -**Definition:** - -```arduino -bool setPowerBoostKeepOn(bool en){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); - - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (en) Wire.write(data | BOOST_OUT_BIT); - else Wire.write(data &(~BOOST_OUT_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` - ## setKeepLightLoad() **Syntax:** @@ -53,6 +194,7 @@ bool setPowerBoostKeepOn(bool en){ **Description:** This function sets/unsets to disable the automatic shutdown. +(Deprecated: This function will be disabled and will be removed in the near future) **Function argument** @@ -64,29 +206,49 @@ false: When the current is too small, IP5306 will automatically shutdown. true: Control success, false: Control failure. -**Definition:** -```arduino -bool setKeepLightLoad(bool en) { - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); +## setLowPowerShutdown() - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); +**Syntax:** + +bool setLowPowerShutdown(bool en) + +**Description:** + +Set the power saving automatic shutdown function. +(Deprecated: this function is disabled and will eventually disappear. Use setPowerBoostKeepOn()) + +**Function argument** + +true: Enable energy saving shutdown function. +false: Disable energy saving shutdown function. + +**Function return value** + +true: Control success, +false: Control failure. + + +## setAutoBootOnLoad() + +**Syntax:** + +bool setAutoBootOnLoad(bool en) + +**Description:** + +Set whether to automatically start when power consumption occurs on the secondary side of IP5306. + +**Function argument** + +true: Enable the auto start function. +false: Disable auto start function. + +**Function return value** + +true: Control success, +false: Control failure. - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (!en) Wire.write(data | LIGHT_LOAD_BIT); - else Wire.write(data &(~LIGHT_LOAD_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` ## setCharge() @@ -109,29 +271,6 @@ false: Stop charging. true: Control success, false: Control failure. -**Definition:** - -```arduino -bool setCharge(bool en){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); - - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (en) Wire.write(data | CHARGE_OUT_BIT); - else Wire.write(data &(~CHARGE_OUT_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` ## isChargeFull() @@ -152,23 +291,6 @@ No argument. true: Full charged, false: Not full charged. -**Definition:** - -```arduino -bool isChargeFull(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ1); - Wire.endTransmission(false); - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - if (data & (1 << CHARGE_FULL_BIT)) return true; - else return false; - } - return false; -} -``` ## canControl() @@ -178,7 +300,7 @@ bool isChargeFull(){ **Description:** -This function checks the existence of the battery controller on I2C. +This function checks the existence of the battery controller over I2C communication. **Function argument** @@ -189,16 +311,6 @@ No argument. true: Battery controller is found, false: Battery controller is not found. -**Definition:** - -```arduino -bool canControl(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - return(Wire.endTransmission()==0); -} -``` ## isCharging() @@ -219,23 +331,6 @@ No argument. true: In charging, false: Not in charging. -**Definition:** - -```arduino -bool isCharging(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - Wire.endTransmission(false); - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - if (data & (1 << CHARGE_FULL_BIT)) return true; - else return false; - } - return false; -} -``` ## getBatteryLevel() @@ -256,25 +351,6 @@ No argument. Battery remaining percentage. (0-100 %) Returns -1 if it can not communicate with the controller. -**Definition:** - -```arduino -int8_t getBatteryLevel() { - Wire.beginTransmission(0x75); - Wire.write(0x78); - if (Wire.endTransmission(false) == 0 && Wire.requestFrom(0x75, 1)) { - switch (Wire.read() & 0xF0) { - case 0xE0: return 25; - case 0xC0: return 50; - case 0x80: return 75; - case 0x00: return 100; - default: return 0; - } - } - return -1; -} -``` - ## setWakeupButton() **Syntax:** @@ -283,101 +359,167 @@ int8_t getBatteryLevel() { **Description:** -This function sets the port to exit sleep mode. +Sets the signal port to monitor when waking from sleep. -**Definition:** +**Function argument** + +button: number of port. + +**Function return value** + +No return value. + +**Example of use:** ```arduino -void setWakeupButton(uint8_t button) { - _wakeupPin = button; -} +setWakeupButton(BUTTON_A_PIN); ``` ## reset() **Syntax:** -void reset() +void reset(); **Description:** -This function resets the CPU. +Reset CPU and reboot. -**Definition:** +**Function argument** -```arduino -void reset() { - esp_restart(); -} -``` +No argument. - ## deepSleep() **Syntax:** -void deepSleep() +void deepSleep(uint64_t time_in_us) **Description:** This function shifts to deep sleep mode. +It starts when the specified time or port status changes. +After waking up, the CPU will be restarted instead of running from the next line. -**Definition:** - +**Example of use:** +Save energy for 5 seconds and then restart. ```arduino -void deepSleep(){ - - #ifdef M5STACK_FIRE - // Keep power keep boost on - setPowerBoostKeepOn(true); - #endif - - // power off the Lcd - M5.Lcd.setBrightness(0); - M5.Lcd.sleep(); - - // ESP32 into deep sleep - esp_sleep_enable_ext0_wakeup((gpio_num_t)_wakeupPin , LOW); - - while(digitalRead(_wakeupPin) == LOW) { - delay(10); - } - esp_deep_sleep_start(); -} +deepSleep(SLEEP_SEC(5)); ``` + +## lightSleep() + +**Syntax:** + +void lightSleep(uint64_t time_in_us) + +**Description:** +This function shifts to deep sleep mode. +It starts when the specified time or port changes. +After returning, it will be executed from the next line. +Power saving capability is lacking compared to deepSleep(). + +**Example of use:** +Save energy for 5 seconds and then restart. +```arduino +lightSleep(SLEEP_SEC(5)); +``` + +## powerOFF() + +**Syntax:** + +void powerOFF() + +**Description:** +Turn off the power. +By turning off the IP5306 after 8 seconds using the power saving function +Turn off the power supplied to the circuit side. + +**Usage notes:** +M5Stack does not have a means to forcibly turn off the power. +So,this function is realized by using the power saving function of IP5306. +If the user is consuming current in the circuit IP5306 fails to determine the power off. + diff --git a/docs/ja/api/power.md b/docs/ja/api/power.md index 8f54dabc..7af5b4ff 100644 --- a/docs/ja/api/power.md +++ b/docs/ja/api/power.md @@ -1,5 +1,167 @@ # Power +*電源関連の機能はIP5306チップに依存しています。必要に応じてデータシート[IP5306](https://github.com/m5stack/M5-Schematic/blob/master/Core/IIC_IP5306_REG_V1.4.pdf)を参照してください * +*古いM5STACKハードウェアの場合、IP5306チップが通信未対応です。機能を使う場合は制御できないケースも考慮してください。* + +下記の例のように、初期化、通信確認、制御の順で使用してください。 +```arduino +deepSleep(SLEEP_SEC(5)); + M5.Power.begin(); + if(!M5.Power.canControl()) { + //can't control. + return; + } + M5.Power.lightSleep(SLEEP_SEC(5)); +``` +## begin() + +**構文:** + +void begin() + +**説明:** + +Powerクラスの初期化を行います。 + + +**引数** +なし。 + +**戻り値** +なし。 + +## setPowerBoostOnOff() + +**構文:** + +bool setPowerBoostOnOff(bool en) + +**説明:** + +電源をON/OFFの方法を変更します。 +USB接続時は電源をOFFにできません。 + +**引数** + +true: 長押しでON/OFFします。 +false: 短押し2回でON/OFFします。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + +## setPowerBoostSet() + +**構文:** + +bool setPowerBoostSet(bool en) + +**説明:** + +電源をON/OFFの方法を変更します。 +USB接続時は電源をOFFにできません。 + +**引数** + +true: 短押し1回でON/OFFします。 +false: setPowerBoostOnOff()の方法に従います。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + +## setPowerVin() + +**構文:** + +bool setPowerVin(bool en) + +**説明:** + +USBなどからの電源供給が途切たとき、 +電源を再投入するかを決定します。 + +**引数** + +true: 電源を再投入します。 +false: 電源を再投入しません。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + + +## setPowerWLEDSet() + +**構文:** + +bool setPowerWLEDSet(bool en) + +**説明:** + +電源LEDを付けるためのモードを設定します。 +なお、M5GOのIP5306は結線されておらず、この関数では制御できません。 + +**引数** + +true: 短押し2回でLEDをつけます +false: 長押しでLEDをつけます + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + +## setPowerBtnEn() + +**構文:** + +bool setPowerBtnEn(bool en) + +**説明:** + +電源ボタンを受け付けるか設定します。 +ボタンを受け付けない場合は、 +通電状態ならば電源ボタンはCPUリセットのみを受け付けます。 +非通電状態ならば、電源は投入できなくなります。 + +**引数** + +true: 電源操作を受け付けます。 +false: 電源操作を受け付けません。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + + +## setLowPowerShutdownTime() + +**構文:** + +bool setLowPowerShutdownTime(ShutdownTime time) + +**説明:** + +IP5306が省エネ判断をして電源OFFするまでの待ち時間を設定します。 + +**引数** + +ShutdownTime::SHUTDOWN_8S 8秒待ちます。 +ShutdownTime::SHUTDOWN_16S 16秒待ちます。 +ShutdownTime::SHUTDOWN_32S 32秒待ちます。 +ShutdownTime::SHUTDOWN_64S 64秒待ちます。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + + ## setPowerBoostKeepOn() **構文:** @@ -8,41 +170,18 @@ **説明:** -電源供給状態を設定します。 +省エネを無効にし電源供給状態を維持します。 **引数** -true: 常時供給モードon。 -false: 常時供給モードoff。 +true: 電源供給を常に保ちます。 (IP5306スリープ無効) +false: 電源供給はIP5306が判断します。(IP5306スリープ有効) **戻り値** true: 制御成功。 false: 制御失敗。 -**定義** - -```arduino -bool setPowerBoostKeepOn(bool en){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); - - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (en) Wire.write(data | BOOST_OUT_BIT); - else Wire.write(data &(~BOOST_OUT_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` ## setKeepLightLoad() @@ -53,6 +192,7 @@ bool setPowerBoostKeepOn(bool en){ **説明:** 自動シャットダウン無効化機能を設定します。 +(非推奨:この関数は無効化され、今後なくなります) **引数** @@ -64,29 +204,48 @@ false: 軽負荷時に自動シャットダウンします。 true: 制御成功。 false: 制御失敗。 -**定義:** -```arduino -bool setKeepLightLoad(bool en) { - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); +## setLowPowerShutdown() - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); +**構文:** + +bool setLowPowerShutdown(bool en) + +**説明:** + +省電力時の自動シャットダウン機能を設定します。 +(非推奨:この関数は無効化され、今後なくなります。setPowerBoostKeepOnを使ってください) + +**引数** + +true: 省エネシャットダウン機能を有効にします。 +false: 省エネシャットダウン機能を無効にします。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 + +## setAutoBootOnLoad() + +**構文:** + +bool setAutoBootOnLoad(bool en) + +**説明:** + +IP5306の2次側に電力消費が発生した場合に自動起動するかを設定します。 + +**引数** + +true: 自動起動機能を有効にします。 +false: 自動起動機能を無効にします。 + +**戻り値** + +true: 制御成功。 +false: 制御失敗。 - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (!en) Wire.write(data | LIGHT_LOAD_BIT); - else Wire.write(data &(~LIGHT_LOAD_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` ## setCharge() @@ -109,29 +268,6 @@ false: 充電中止指示。 true: 制御成功。 false: 制御失敗。 -**定義:** - -```arduino -bool POWER::setCharge(bool en){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); - - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (en) Wire.write(data | CHARGE_OUT_BIT); - else Wire.write(data &(~CHARGE_OUT_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` ## isChargeFull() @@ -152,23 +288,6 @@ bool POWER::setCharge(bool en){ true: 満充電。 false: 満充電ではない。 -**定義:** - -```arduino -bool isChargeFull(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ1); - Wire.endTransmission(false); - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - if (data & (1 << CHARGE_FULL_BIT)) return true; - else return false; - } - return false; -} -``` ## canControl() @@ -179,6 +298,8 @@ bool isChargeFull(){ **説明:** 電源コントローラが制御可能かどうかを判断します。 +古いM5Stackなど、IP5306を認識できない場合はfalseとなります。 +その場合は、Powerクラスのほとんどが機能しません。 **引数** @@ -189,16 +310,6 @@ bool isChargeFull(){ true: 電源コントローラーを制御可能。 false: 電源コントローラーを制御不可能。 -**定義:** - -```arduino -bool canControl(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - return(Wire.endTransmission()==0); -} -``` ## isCharging() @@ -219,29 +330,12 @@ bool canControl(){ true: 充電中。 false: 充電中ではない。 -**定義:** - -```arduino -bool isCharging(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - Wire.endTransmission(false); - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - if (data & (1 << CHARGE_FULL_BIT)) return true; - else return false; - } - return false; -} -``` ## getBatteryLevel() **構文:** -bool getBatteryLevel() +int8_t getBatteryLevel() **説明:** @@ -256,24 +350,6 @@ bool isCharging(){ バッテリーレベルを(0-100)の範囲で返します。(単位:%) もし残量が確認できる状態になければ-1を返します。 -**定義:** - -```arduino -int8_t getBatteryLevel() { - Wire.beginTransmission(0x75); - Wire.write(0x78); - if (Wire.endTransmission(false) == 0 && Wire.requestFrom(0x75, 1)) { - switch (Wire.read() & 0xF0) { - case 0xE0: return 25; - case 0xC0: return 50; - case 0x80: return 75; - case 0x00: return 100; - default: return 0; - } - } - return -1; -} -``` ## setWakeupButton() @@ -283,14 +359,20 @@ int8_t getBatteryLevel() { **説明:** -スリープ復帰信号ポートを設定します。 +スリープから復帰するときに監視する信号ポートを設定します。 -**定義:** +**引数** + +button: ポート番号 + +**戻り値** + +なし + +**使用例:** ```arduino -void setWakeupButton(uint8_t button) { - _wakeupPin = button; -} +setWakeupButton(BUTTON_A_PIN); ``` ## reset() @@ -301,83 +383,142 @@ void setWakeupButton(uint8_t button) { **説明:** -CPUをリセットします。 +CPUをリセットし、再起動します。 -**定義:** +**引数** -```arduino -void reset() { - esp_restart(); -} -``` +なし - +## isResetbyWatchdog() + +**構文:** + +bool isResetbyWatchdog() + +**説明:** + +現在の起動状態がウォッチドッグ後であるか判定します。 + +**引数** + +なし + +**戻り値** + +true : ウォッチドッグによるもの +false: それ以外によるもの + +## isResetbyDeepsleep() + +**構文:** + +bool isResetbyDeepsleep() + +**説明:** + +現在の起動状態がdeepSleep()後であるか判定します。 + +**引数** + +なし + +**戻り値** + +true : deepSleep()後の起動 +false: それ以外によるもの + +## isResetbyPowerSW() + +**構文:** + +bool isResetbyPowerSW() + +**説明:** + +現在の起動状態がパワーSWからの電源投入後であるか判定します。 + +**引数** + +なし + +**戻り値** + +true : パワーSWからの電源投入後の起動 +false: それ以外によるもの ## deepSleep() **構文:** -void deepSleep() +void deepSleep(uint64_t time_in_us) **説明:** +省電力モードに移行します。 +指定した時間、もしくはポートに変化があった場合に起動します。 +復帰した後は、次の行からの実行ではなく、CPUは再起動されます。 -deep sleepモードに移行します。 - -**定義:** - +**使用例:** +5秒省エネを行い、その後に再起動します。 ```arduino -void deepSleep(){ - - #ifdef M5STACK_FIRE - // Keep power keep boost on - setPowerBoostKeepOn(true); - #endif - - // power off the Lcd - M5.Lcd.setBrightness(0); - M5.Lcd.sleep(); - - // ESP32 into deep sleep - esp_sleep_enable_ext0_wakeup((gpio_num_t)_wakeupPin , LOW); - - while(digitalRead(_wakeupPin) == LOW) { - delay(10); - } - esp_deep_sleep_start(); -} +deepSleep(SLEEP_SEC(5)); ``` + +## lightSleep() + +**構文:** + +void lightSleep(uint64_t time_in_us) + +**説明:** +省電力モードに移行します。 +指定した時間、もしくはポートに変化があった場合に起動します。 +復帰した後は、次の行から実行されます。 +deepSleepに比べ、省電力能力に欠けます。 + +**使用例:** +5秒省エネを行い、その後に再起動します。 +```arduino +lightSleep(SLEEP_SEC(5)); +``` + +## powerOFF() + +**構文:** + +void powerOFF() + +**説明:** +電源を切ります。 +省電力機能を用いて、IP5306を8秒後にOFFさせることで +回路側に供給される電源をOFFとします。 + +**使用上の注意** +強制的に電源をOFFにする手段が用意されていないため +IP5306の省電力機能をつかってこの機能を実現しています。 +そのためユーザが回路で電流を消費している場合には +IP5306は電源OFFへの移行判断に失敗します。 + diff --git a/docs/zh_CN/api/power.md b/docs/zh_CN/api/power.md index 0b69df00..6f05e5e0 100644 --- a/docs/zh_CN/api/power.md +++ b/docs/zh_CN/api/power.md @@ -1,6 +1,55 @@ # Power *电源相关的函数可能涉及 IP5306 芯片的寄存器,如果有不明白的地方,可以查看 [IP5306](https://github.com/m5stack/M5-Schematic/blob/master/Core/IIC_IP5306_REG_V1.4.pdf) 的寄存器手册。* +* IP5306芯片不支持与旧M5STACK硬件通信。使用功能时,还要考虑支持失控情况。 *按顺序使用:初始化,通信检查和控制,如以下示例所示。 + +```arduino +deepSleep(SLEEP_SEC(5)); + M5.Power.begin(); + if(!M5.Power.canControl()) { + //can't control. + return; + } + M5.Power.lightSleep(SLEEP_SEC(5)); +``` +## begin() + +**函数原型:** + +void begin() + +**功能:** + +Performs initialization of Power class. + +**参数** + +无。 + +**返回值** + +无。 + +## setPowerBoostOnOff() + +**函数原型:** + +bool setPowerBoostOnOff(bool en) + +**功能:** + +更改电源开/关方法。 +通过USB连接时,电源不会关闭。 + +**参数** + +true:按住可打开/关闭。 +false:两次短按打开/关闭。 + +**返回值** + +true: 控制成功 +false: 控制失败 ## setPowerBoostKeepOn() @@ -8,42 +57,128 @@ bool setPowerBoostKeepOn(bool en) -**功能: BOOST 输出常开功能** +**功能:** +更改电源开/关方法。 +通过USB连接时,电源不会关闭。 **参数** - -true: BOOST 常开 -false: BOOST 常闭 +true: 短按一下开/关。 +false: 遵循setPowerBoostOnOff()方法。 **返回值** true: 控制成功 false: 控制失败 -**函数实现** +## setPowerVin() -```arduino -bool setPowerBoostKeepOn(bool en){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); +**函数原型:** - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); +bool setPowerVin(bool en) - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (en) Wire.write(data | BOOST_OUT_BIT); - else Wire.write(data &(~BOOST_OUT_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -#endif -``` +**功能:** + +当USB等电源切断时, +决定是否再次打开电源。 + +**参数** + +true: 电源将再次打开。 +false: 电源不会再次打开。 + +**返回值** + +true: 控制成功 +false: 控制失败 + +## setPowerWLEDSet() + +**函数原型:** + +bool setPowerWLEDSet(bool en) + +**功能:** + +设置模式以打开电源LED。 +M5GO的IP5306没有接线,无法通过此功能进行控制。 + +**参数** + +true: 两次短按即可打开LED +false: 按住可打开LED + +**返回值** + +true: 控制成功 +false: 控制失败 + +## setPowerBtnEn() + +**函数原型:** + +bool setPowerBtnEn(bool en) + +**功能:** + +设置是否接受电源按钮。 + +关于不接受按钮时的行为: +如果电源打开,电源按钮仅接受CPU复位。 +如果未提供电源,则无法打开电源。 + +**参数** + +true: 接受电源操作。 +false: 不接受电源控制。 + +**返回值** + +true: 控制成功 +false: 控制失败 + + +## setLowPowerShutdownTime() + +**函数原型:** + +bool setLowPowerShutdownTime(ShutdownTime time) + +**功能:** + +设置等待时间,直到IP5306进行节能判断并关闭电源。 + +**参数** + +ShutdownTime::SHUTDOWN_8S : 等待8秒。 +ShutdownTime::SHUTDOWN_16S : 等待16秒。 +ShutdownTime::SHUTDOWN_32S : 等待32秒。 +ShutdownTime::SHUTDOWN_64S : 等待64秒。 + +**返回值** + +true: 控制成功 +false: 控制失败 + + +## setPowerBoostKeepOn() + +**函数原型:** + +bool setPowerBoostKeepOn(bool en) + +**功能:** + +此功能设置/取消设置始终提升输出模式。 + +**参数** + +true: 总是输出功率。 +false: 不总是输出功率。 + +**返回值** + +true: 控制成功 +false: 控制失败 ## setKeepLightLoad() @@ -53,7 +188,9 @@ bool setPowerBoostKeepOn(bool en){ **功能:** -设置自动关机功能。 +此功能设置/取消设置以禁用自动关闭。 +(已弃用:此功能将被禁用,并将在不久的将来删除) + **参数** @@ -65,29 +202,47 @@ false:电流消耗低时自动关闭 true: 控制成功 false: 控制失败 -**函数实现** +## setLowPowerShutdown() -```arduino -bool setKeepLightLoad(bool en) { - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); +**函数原型:** - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); +bool setLowPowerShutdown(bool en) - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (!en) Wire.write(data | LIGHT_LOAD_BIT); - else Wire.write(data &(~LIGHT_LOAD_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` +**功能:** + +此功能设置/取消设置以禁用自动关闭。 +(已弃用:此功能将被禁用,并将在不久的将来删除) + + +**参数** + +true:启用节能关机功能。 +false:禁用节能关机功能。 + +**返回值** + +true: 控制成功 +false: 控制失败 + +## setAutoBootOnLoad() + +**函数原型:** + +bool setAutoBootOnLoad(bool en) + +**功能:** + +设置是否在IP5306的次级侧发生功耗时自动启动. + +**参数** + +true:启用自动启动功能。 +false:禁用自动启动功能。 + +**返回值** + +true: 控制成功 +false: 控制失败 ## setCharge() @@ -96,8 +251,11 @@ bool setKeepLightLoad(bool en) { bool setCharge(bool en) -**功能:设置充电状态** +**功能:** +此功能设置/取消设置充电模式。电池充满电后, +尝试设置充电启用 - >禁用 - >启用,它可以充电。 +**参数** true:充电开始指令 false:充电停止指令 @@ -106,30 +264,6 @@ false:充电停止指令 true: 控制成功 false: 控制失败 -**定義:** - -```arduino -bool POWER::setCharge(bool en){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - Wire.endTransmission(); - - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_SYS_CTL0); - if (en) Wire.write(data | CHARGE_OUT_BIT); - else Wire.write(data &(~CHARGE_OUT_BIT)); - Wire.endTransmission(); - return true; - } - return false; -} -``` - ## isChargeFull() **函数原型:** @@ -149,23 +283,6 @@ bool POWER::setCharge(bool en){ true:完全充电 false:没有完全充电 -**函数实现:** - -```arduino -bool isChargeFull(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ1); - Wire.endTransmission(false); - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - if (data & (1 << CHARGE_FULL_BIT)) return true; - else return false; - } - return false; -} -``` ## canControl() @@ -175,7 +292,7 @@ bool isChargeFull(){ **功能:** -确认完全充电 +此功能通过I2C通信检查电池控制器是否存在。 **参数** @@ -186,16 +303,6 @@ bool isChargeFull(){ true: 电源控制器发现 false:找不到电源控制器 -**函数实现:** - -```arduino -bool canControl(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - return(Wire.endTransmission()==0); -} -``` ## isCharging() @@ -214,23 +321,6 @@ bool canControl(){ true: 在充电过程中 false: 不充电 -**函数实现:** - -```arduino -bool isCharging(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - Wire.endTransmission(false); - if(Wire.requestFrom(IP5306_ADDR, 1)) - { - data = Wire.read(); - if (data & (1 << CHARGE_FULL_BIT)) return true; - else return false; - } - return false; -} -``` ## getBatteryLevel() @@ -251,24 +341,6 @@ bool isCharging(){ 返回0到100范围内的电池电量.(单位:%) 如果无法检查剩余金额,则返回-1 -**函数实现:** - -```arduino -int8_t getBatteryLevel() { - Wire.beginTransmission(0x75); - Wire.write(0x78); - if (Wire.endTransmission(false) == 0 && Wire.requestFrom(0x75, 1)) { - switch (Wire.read() & 0xF0) { - case 0xE0: return 25; - case 0xC0: return 50; - case 0x80: return 75; - case 0x00: return 100; - default: return 0; - } - } - return -1; -} -``` ## setWakeupButton() @@ -278,12 +350,18 @@ int8_t getBatteryLevel() { **功能:设置睡眠返回端口** -**函数实现:** +**参数** + +button: 端口号 + +**返回值** + +无。 + +**使用示例** ```arduino -void setWakeupButton(uint8_t button) { - _wakeupPin = button; -} +setWakeupButton(BUTTON_A_PIN); ``` ## reset() @@ -294,48 +372,91 @@ void setWakeupButton(uint8_t button) { **功能:执行CPU重置** -**函数实现:** +**参数** -```arduino -void reset() { - esp_restart(); -} -``` +无。 - ## deepSleep() @@ -343,28 +464,47 @@ bool batteryMode(bool en){ void deepSleep() -**功能:进入 deep sleep 状态** - -**函数实现:** +**功能:** +此功能转换为深度睡眠模式。 +它在指定的时间或端口状态更改时启动。 +唤醒后,CPU将重新启动,而不是从下一行运行。 +**使用示例** +节能5秒钟然后重新启动。 ```arduino -void deepSleep(){ - - #ifdef M5STACK_FIRE - // Keep power keep boost on - setPowerBoostKeepOn(true); - #endif - - // power off the Lcd - M5.Lcd.setBrightness(0); - M5.Lcd.sleep(); - - // ESP32 into deep sleep - esp_sleep_enable_ext0_wakeup((gpio_num_t)_wakeupPin , LOW); - - while(digitalRead(_wakeupPin) == LOW) { - delay(10); - } - esp_deep_sleep_start(); -} +deepSleep(SLEEP_SEC(5)); ``` +## lightSleep() + +**函数原型:** + +void lightSleep(uint64_t time_in_us) + +**功能:** +此功能转换为深度睡眠模式。 +它在指定的时间或端口更改时启动。 +返回后,它将从下一行执行。 +与deepSleep()相比,缺少省电功能。 + +**使用示例** +节能5秒钟然后重新启动。 +```arduino +lightSleep(SLEEP_SEC(5)); +``` + +## powerOFF() + +**函数原型:** + +void powerOFF() + +**功能:** +关掉电源。 +使用省电功能在8秒后关闭IP5306 +关闭提供给电路侧的电源。 + +**使用注意事项** +M5Stack无法强行关闭电源。 +因此,该功能通过使用IP5306的省电功能实现。 +如果用户在电路中消耗电流,IP5306无法确定电源关闭。 +