From c0f9f7cecd128932d232860ef23eb2a8aaa8adcc Mon Sep 17 00:00:00 2001 From: Mori Naoyuki Date: Thu, 2 May 2019 03:52:49 +0900 Subject: [PATCH 1/8] modify : Document follows current M5.Power class Delete definition: Changes occur every software change, making maintenance difficult. If you look at the source, it solves. So I deleted it. --- docs/en/api/power.md | 528 +++++++++++++++++++++++++--------------- docs/ja/api/power.md | 527 ++++++++++++++++++++++++--------------- docs/zh_CN/api/power.md | 522 ++++++++++++++++++++++++--------------- 3 files changed, 1000 insertions(+), 577 deletions(-) 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无法确定电源关闭。 + From c7344f36f14c7b7abbb4445d1e26bcca1880accf Mon Sep 17 00:00:00 2001 From: Mori Naoyuki Date: Thu, 2 May 2019 04:00:51 +0900 Subject: [PATCH 2/8] modify: Wrong return type *getBatteryLevel() bool -> int8_t --- docs/zh_CN/api/power.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh_CN/api/power.md b/docs/zh_CN/api/power.md index 6f05e5e0..15d8c100 100644 --- a/docs/zh_CN/api/power.md +++ b/docs/zh_CN/api/power.md @@ -326,7 +326,7 @@ false: 不充电 **函数原型:** -bool getBatteryLevel() +int8_t getBatteryLevel() **功能:** From 01ed338681eb8f6f51444cc7d1b060a8bc0bc149 Mon Sep 17 00:00:00 2001 From: Mori Naoyuki Date: Thu, 2 May 2019 04:07:29 +0900 Subject: [PATCH 3/8] fix: worng sample code and tag --- docs/en/api/power.md | 2 +- docs/ja/api/power.md | 2 +- docs/zh_CN/api/power.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/api/power.md b/docs/en/api/power.md index 28887f7a..d0a276fb 100644 --- a/docs/en/api/power.md +++ b/docs/en/api/power.md @@ -1,12 +1,12 @@ # 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. diff --git a/docs/ja/api/power.md b/docs/ja/api/power.md index 7af5b4ff..e413a256 100644 --- a/docs/ja/api/power.md +++ b/docs/ja/api/power.md @@ -1,11 +1,11 @@ # 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. diff --git a/docs/zh_CN/api/power.md b/docs/zh_CN/api/power.md index 15d8c100..ba67689f 100644 --- a/docs/zh_CN/api/power.md +++ b/docs/zh_CN/api/power.md @@ -1,10 +1,10 @@ # 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. From e0a0d5a5ec7c15e516d039832ac6f060a0e6a608 Mon Sep 17 00:00:00 2001 From: Mori Naoyuki Date: Thu, 2 May 2019 14:04:24 +0900 Subject: [PATCH 4/8] modify : Correction of unlinked articles (api.md) add : Communication Library (commutil.md) fix : aligned format (power.md) --- docs/en/api.md | 4 +- docs/en/api/commutil.md | 194 +++++++++++++++++++++++++++++++++++++ docs/en/api/power.md | 133 +++++++++++++------------ docs/ja/api.md | 3 +- docs/ja/api/commutil.md | 192 ++++++++++++++++++++++++++++++++++++ docs/ja/api/gpio.md | 48 ++++----- docs/ja/api/power.md | 119 +++++++++++------------ docs/zh_CN/api.md | 3 +- docs/zh_CN/api/commutil.md | 193 ++++++++++++++++++++++++++++++++++++ docs/zh_CN/api/gpio.md | 21 ++++ docs/zh_CN/api/power.md | 126 ++++++++++++------------ 11 files changed, 826 insertions(+), 210 deletions(-) create mode 100644 docs/en/api/commutil.md create mode 100644 docs/ja/api/commutil.md create mode 100644 docs/zh_CN/api/commutil.md create mode 100644 docs/zh_CN/api/gpio.md diff --git a/docs/en/api.md b/docs/en/api.md index a82b0dbd..fced5af3 100644 --- a/docs/en/api.md +++ b/docs/en/api.md @@ -7,7 +7,9 @@ |**[System](en/api/system)** | **[Speaker](en/api/speaker)** | |**[LCD](en/api/lcd)** | **[Button](en/api/button)** | |**[IMU Sensor(MPU9250)](en/api/mpu9250)** | **[TF Card](en/api/tf)** | -|**[Power](en/api/power)** | +|**[Power](en/api/power)** |[GPIO](en/api/gpio)** | +|**[I2C Communication](en/api/commutil)** | | + ## M5StickC diff --git a/docs/en/api/commutil.md b/docs/en/api/commutil.md new file mode 100644 index 00000000..f8d13998 --- /dev/null +++ b/docs/en/api/commutil.md @@ -0,0 +1,194 @@ +# I2C {docsify-ignore-all} + +This is a class to control M5Stack's Grove-A port (I2C). +I2C communication needs to be initialized in advance by M5.Begin(). + +## writeCommand() + +**Syntax:** +bool writeCommand(uint8_t address, uint8_t subAddress); + +**Description:** + +Write to the specified address. +Used when there are no parameters. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| subAddress | uint8_t |function address | + +**Function return value** +| Value |Description | +| --- | --- | +|true|Write success| +|false|Write failure| + + +## writeByte() + +**Syntax:** +bool writeByte(uint8_t address, uint8_t subAddress, uint8_t data); + +**Description:** + +Write to the specified address. +Used when there is one parameter. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| subAddress | uint8_t |function address | +| data | uint8_t |parameter | + +**Function return value** +| Value |Description | +| --- | --- | +|true|Write success| +|false|Write failure| + + + +## writeBytes() + +**Syntax:** + bool writeBytes(uint8_t address, uint8_t subAddress, uint8_t *data,uint8_t length); + +**Description:** + +Write to the specified address. +Use when there are multiple parameters. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| subAddress | uint8_t |function address | +| data | uint8_t * | top of data memory | +| length | uint8_t | length of data | + +**Function return value** +| Value |Description | +| --- | --- | +|true|Write success| +|false|Write failure| + + +## readByte() + +**Syntax:** + bool readByte(uint8_t address, uint8_t *result); + +**Description:** + +Read from the specified address. +It is used when there is no data to send before reading and the response is 1 byte. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| result | uint8_t * | stored memory | + +**Function return value** +| Value |Description | +| --- | --- | +|true|Read success| +|false|Read failure| + + +## readByte() + +**Syntax:** +bool readByte(uint8_t address, uint8_t subAddress,uint8_t *result); + +**Description:** + +Read from the specified address. +It is used when the data to be sent before reading is only the functional address and the response is 1 byte. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| subAddress | uint8_t |機能アドレス | +| result | uint8_t * |stored memory| + +**Function return value** +| Value |Description | +| --- | --- | +|true|Read success| +|false|Read failure| + + +## readBytes() + +**Syntax:** +bool readBytes(uint8_t address, uint8_t count,uint8_t * dest); + +**Description:** + +Read from the specified address. +Use when there is no data to send before reading and there are multiple responses. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| count | uint8_t | Length of request bytes | +| result | uint8_t * |stored memory| + +**Function return value** +| Value |Description | +|true|Read success| +|false|Read failure| + +## readBytes() + +**Syntax:** +bool readBytes(uint8_t address, uint8_t subAddress, uint8_t count, uint8_t * dest); + +**Description:** + +Read from the specified address. +It is used when the data to be sent before reading is only the functional address and there are multiple responses. + +**Function argument** +| argument |Typer |Description | +| --- | --- | --- | +| address | uint8_t |Slave Address | +| subAddress | uint8_t |Addresress | +| count | uint8_t | Length of request bytes | +| result | uint8_t * |stored memory| + + +**Function return value** +| Value |Description | +| --- | --- | +|true|Read success| +|false|Read failure| + + +## scanID() + +**Syntax:** +bool readBytes(bool *result); + +**Description:** + +Perform device presence check on I2C bus. + +**Function argument** +| Function argument |Type |Description | +| --- | --- | --- | +| result | bool * |stored memory(128bytes) | + +**Function return value** +| Value |Description | +| --- | --- | +|true|Read success| +|false|Read failure| + + diff --git a/docs/en/api/power.md b/docs/en/api/power.md index d0a276fb..5ce11653 100644 --- a/docs/en/api/power.md +++ b/docs/en/api/power.md @@ -46,13 +46,13 @@ 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. +|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. +|true|Control success.| +|false|Control failure. | ## setPowerBoostSet() @@ -67,13 +67,13 @@ The power does not turn off when connected via USB. **Function argument** -true: ON / OFF in one short press. -false: Follow the setPowerBoostOnOff () method. +|true| ON / OFF in one short press.| +|false| Follow the setPowerBoostOnOff () method.| **Function return value** -true: Control success, -false: Control failure. +|true|Control success.| +|false|Control failure. | ## setPowerVin() @@ -88,13 +88,13 @@ 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. +|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. +|true|Control success.| +|false|Control failure. | ## setPowerWLEDSet() @@ -109,13 +109,13 @@ In addition, IP5306 of M5GO is not wired and can not be controlled by this funct **Function argument** -true: Turn on the LED with two short presses -false: Turn on the LED with Press and hold +|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. +|true|Control success.| +|false|Control failure. | ## setPowerBtnEn() @@ -128,18 +128,20 @@ false: Control failure. 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. +|true| Accept power operation.| +|false| Does not accept power control.| **Function return value** -true: Control success, -false: Control failure. +|true|Control success.| +|false|Control failure. | ## setLowPowerShutdownTime() @@ -154,15 +156,15 @@ Set the waiting time until IP5306 makes the energy saving judgment and the power **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. +|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. +|true|Control success.| +|false|Control failure. | ## setPowerBoostKeepOn() @@ -177,13 +179,13 @@ This function sets/unsets always boost output mode. **Function argument** -true: Always output power. -false: not Always output power. +|true| Always output power.| +|false| not Always output power.| **Function return value** -true: Control success, -false: Control failure. +|true|Control success.| +|false|Control failure. | ## setKeepLightLoad() @@ -198,13 +200,13 @@ This function sets/unsets to disable the automatic shutdown. **Function argument** -true: When the current is too small, IP5306 will *not* automatically shutdown, -false: When the current is too small, IP5306 will automatically shutdown. +|true| When the current is too small, IP5306 will *not* automatically shutdown, | +|false| When the current is too small, IP5306 will automatically shutdown. | **Function return value** -true: Control success, -false: Control failure. +|true|Control success.| +|false|Control failure. | ## setLowPowerShutdown() @@ -220,13 +222,13 @@ Set the power saving automatic shutdown function. **Function argument** -true: Enable energy saving shutdown function. -false: Disable energy saving shutdown function. +|true|Enable energy saving shutdown function.| +|false|Disable energy saving shutdown function.| **Function return value** -true: Control success, -false: Control failure. +|true|Control success.| +|false|Control failure. | ## setAutoBootOnLoad() @@ -241,13 +243,13 @@ Set whether to automatically start when power consumption occurs on the secondar **Function argument** -true: Enable the auto start function. -false: Disable auto start function. +|true|Enable the auto start function.| +|false|Disable auto start function.| **Function return value** -true: Control success, -false: Control failure. +|true|Control success.| +|false|Control failure. | ## setCharge() @@ -259,18 +261,18 @@ false: Control failure. **Description:** This function sets/unsets charge mode. When the battery is fully charged, + try set charge enable->disable->enable, It can be recharged. **Function argument** -true: Start charging, -false: Stop charging. +|true|Start charging, | +|false| Stop charging. | **Function return value** -true: Control success, -false: Control failure. - +|true|Control success.| +|false|Control failure. | ## isChargeFull() @@ -288,8 +290,8 @@ No argument. **Function return value** -true: Full charged, -false: Not full charged. +|true|Full charged, | +|false|Not full charged. | ## canControl() @@ -308,8 +310,8 @@ No argument. **Function return value** -true: Battery controller is found, -false: Battery controller is not found. +|true|Battery controller is found, | +|false|Battery controller is not found. | ## isCharging() @@ -328,8 +330,8 @@ No argument. **Function return value** -true: In charging, -false: Not in charging. +|true|In charging, | +|false| Not in charging.| ## getBatteryLevel() @@ -349,6 +351,7 @@ No argument. **Function return value** Battery remaining percentage. (0-100 %) + Returns -1 if it can not communicate with the controller. ## setWakeupButton() @@ -363,7 +366,7 @@ Sets the signal port to monitor when waking from sleep. **Function argument** -button: number of port. +|button| number of port. | **Function return value** @@ -410,8 +413,8 @@ No argument, **Function return value** -true : By software reset -false: For other reasons +|true| By software reset| +|false| For other reasons| ## isResetbyWatchdog() @@ -429,8 +432,8 @@ No argument, **Function return value** -true : By watchdog -false: For other reasons +|true | By watchdog| +|false| For other reasons| ## isResetbyDeepsleep() @@ -448,8 +451,8 @@ No argument, **Function return value** -true : after deepSleep() -false: For other reasons +|true | after deepSleep()| +|false| For other reasons| ## isResetbyPowerSW() @@ -467,8 +470,8 @@ No argument, **Function return value** -true : By PowerSwitch -false: For other reasons +|true | By PowerSwitch| +|false| For other reasons| ## deepSleep() @@ -480,6 +483,7 @@ false: For other reasons **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. @@ -497,8 +501,10 @@ deepSleep(SLEEP_SEC(5)); **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:** @@ -515,11 +521,12 @@ lightSleep(SLEEP_SEC(5)); **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.md b/docs/ja/api.md index f54fcf27..04789ebb 100644 --- a/docs/ja/api.md +++ b/docs/ja/api.md @@ -7,7 +7,8 @@ |**[システム](ja/api/system)** | **[スピーカー](ja/api/speaker)** | |**[LCD 画面表示](ja/api/lcd)** | **[ボタン](ja/api/button)** | |**[IMUセンサー(MPU9250)](ja/api/mpu9250)** | **[TFカード(SDカード)](ja/api/tf)** | -|**[電源](ja/api/power)** | | +|**[電源](ja/api/power)** |[GPIO](ja/api/gpio)** | +|**[I2C通信](ja/api/commutil)** | | ## M5StickC diff --git a/docs/ja/api/commutil.md b/docs/ja/api/commutil.md new file mode 100644 index 00000000..d0ade5ba --- /dev/null +++ b/docs/ja/api/commutil.md @@ -0,0 +1,192 @@ +# I2C {docsify-ignore-all} + +M5StackのGrove-Aポート(I2C)を制御するクラスです。 +あらかじめ M5.Begin()でI2C通信が初期化されている必要があります。 + +## writeCommand() + +**構文:** +bool writeCommand(uint8_t address, uint8_t subAddress); + +**説明:** + +指定のアドレスに書きこみます。 +パラメータがない場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| subAddress | uint8_t |機能アドレス | + +**戻り値:** +| 値 |説明 | +|true|送信成功。| +|false|送信失敗。| + + +## writeByte() + +**構文:** +bool writeByte(uint8_t address, uint8_t subAddress, uint8_t data); + +**説明:** + +指定のアドレスに書きこみます。 +パラメータ１つある場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| subAddress | uint8_t |機能アドレス | +| data | uint8_t |パラメータ | + +**戻り値:** +| 値 |説明 | +| --- | --- | +|true|送信成功。| +|false|送信失敗。| + + + +## writeBytes() + +**構文:** + bool writeBytes(uint8_t address, uint8_t subAddress, uint8_t *data,uint8_t length); + +**説明:** + +指定のアドレスに書きこみます。 +パラメータが複数ある場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| subAddress | uint8_t |機能アドレス | +| data | uint8_t * |パラメータ配列の先頭 | +| length | uint8_t |パラメータ長 | + +**戻り値:** +| 値 |説明 | +| --- | --- | +|true|送信成功。| +|false|送信失敗。| + + +## readByte() + +**構文:** + bool readByte(uint8_t address, uint8_t *result); + +**説明:** + +指定のアドレスから読み込みます。 +読み込み前に送信するデータがなく、返答が1バイトの場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| result | uint8_t * |結果格納先 | + +**戻り値: +**| 値 |説明 | +| --- | --- | +|true|読込成功。| +|false|読込失敗。| + +## readByte() + +**構文:** +bool readByte(uint8_t address, uint8_t subAddress,uint8_t *result); + +**説明:** + +指定のアドレスから読み込みます。 +読み込み前に送信するデータが機能アドレスのみで、返答が1バイトの場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| subAddress | uint8_t |機能アドレス | +| result | uint8_t * |結果格納先 | + +**戻り値:** +| 値 |説明 | +| --- | --- | +|true|読込成功。| +|false|読込失敗。| + + +## readBytes() + +**構文:** +bool readBytes(uint8_t address, uint8_t count,uint8_t * dest); + +**説明:** + +指定のアドレスから読み込みます。 +読み込み前に送信するデータがなく、返答が複数ある場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| count | uint8_t |要求バイト数 | +| result | uint8_t * |結果格納先 | + +**戻り値:** +| 値 |説明 | +| --- | --- | +|true|読込成功。| +|false|読込失敗。| + +## readBytes() + +**構文:** +bool readBytes(uint8_t address, uint8_t subAddress, uint8_t count, uint8_t * dest); + +**説明:** + +指定のアドレスから読み込みます。 +読み込み前に送信するデータが機能アドレスのみで、返答が複数ある場合に使います。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| address | uint8_t |スレーブアドレス | +| subAddress | uint8_t |機能アドレス | +| count | uint8_t |要求バイト数 | +| result | uint8_t * |結果格納先 | + +**戻り値:** +| 値 |説明 | +| --- | --- | +|true|読込成功。| +|false|読込失敗。| + + +## scanID() + +**構文:** +bool readBytes(bool *result); + +**説明:** + +I2Cバス上のデバイス存在確認をおこないます。 + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| result | bool * |結果格納先 (128バイト) | + +**戻り値:** +| 値 |説明 | +| --- | --- | +|true|読込成功。| +|false|読込失敗。| + + diff --git a/docs/ja/api/gpio.md b/docs/ja/api/gpio.md index 938a1a70..473b1319 100644 --- a/docs/ja/api/gpio.md +++ b/docs/ja/api/gpio.md @@ -1,23 +1,27 @@ -# GPIO {docsify-ignore-all} - - - -*Refer to GPIO API of [Arduino](http://www.arduino.cc)* - -### digitalRead -> uint32 digitalRead(uint8 pin); - -Read the value of `pin` - -| Param | Type | Description | -| --- | --- | --- | -| pin | uint8 | the number of pin | - -Return: - digital level(0/1) - -**Example** -```arduino -uint32_t pin21_data; -pin21_data = digitalRead(21); +# GPIO {docsify-ignore-all} + + + +*詳しくは [Arduino](http://www.arduino.cc) の GPIOマニュアルを見てください* +## digitalRead() + +**構文:** + uint32 digitalRead(uint8 pin); + +**説明:** + +端子の状態を読み取ります。` + +**引数** +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8 |ピン番号 | + +戻り値: + ピンの電圧入力状態(0/1) + +**使用例;** +```arduino +uint32_t pin21_data; +pin21_data = digitalRead(21); ``` \ No newline at end of file diff --git a/docs/ja/api/power.md b/docs/ja/api/power.md index e413a256..2e1474f8 100644 --- a/docs/ja/api/power.md +++ b/docs/ja/api/power.md @@ -1,6 +1,6 @@ # Power -*電源関連の機能はIP5306チップに依存しています。必要に応じてデータシート[IP5306]（https://github.com/m5stack/M5-Schematic/blob/master/Core/IIC_IP5306_REG_V1.4.pdf）を参照してください * +*電源関連の機能はIP5306チップに依存しています。必要に応じてデータシート[IP5306]（https://github.com/m5stack/M5-Schematic/blob/master/Core/IIC_IP5306_REG_V1.4.pdf）を参照してください* *古いM5STACKハードウェアの場合、IP5306チップが通信未対応です。機能を使う場合は制御できないケースも考慮してください。* @@ -43,13 +43,13 @@ USB接続時は電源をOFFにできません。 **引数** -true: 長押しでON/OFFします。 -false: 短押し2回でON/OFFします。 +|true|長押しでON/OFFします。| +|false|短押し2回でON/OFFします。 | **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功。| +|false|制御失敗。| ## setPowerBoostSet() @@ -64,13 +64,13 @@ USB接続時は電源をOFFにできません。 **引数** -true: 短押し1回でON/OFFします。 -false: setPowerBoostOnOff()の方法に従います。 +|true|短押し1回でON/OFFします。| +|false|setPowerBoostOnOff()の方法に従います。 | **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setPowerVin() @@ -85,13 +85,13 @@ USBなどからの電源供給が途切たとき、 **引数** -true: 電源を再投入します。 -false: 電源を再投入しません。 +|true|電源を再投入します。| +|false|電源を再投入しません。 | **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setPowerWLEDSet() @@ -107,13 +107,13 @@ false: 制御失敗。 **引数** -true: 短押し2回でLEDをつけます -false: 長押しでLEDをつけます +|true|短押し2回でLEDをつけます| +|false|長押しでLEDをつけます| **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setPowerBtnEn() @@ -130,13 +130,13 @@ false: 制御失敗。 **引数** -true: 電源操作を受け付けます。 -false: 電源操作を受け付けません。 +|true|電源操作を受け付けます。| +|false|電源操作を受け付けません。| **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setLowPowerShutdownTime() @@ -151,15 +151,15 @@ IP5306が省エネ判断をして電源OFFするまでの待ち時間を設定 **引数** -ShutdownTime::SHUTDOWN_8S 8秒待ちます。 -ShutdownTime::SHUTDOWN_16S 16秒待ちます。 -ShutdownTime::SHUTDOWN_32S 32秒待ちます。 -ShutdownTime::SHUTDOWN_64S 64秒待ちます。 +|ShutdownTime::SHUTDOWN_8S |8秒待ちます。| +|ShutdownTime::SHUTDOWN_16S|16秒待ちます。| +|ShutdownTime::SHUTDOWN_32S|32秒待ちます。| +|ShutdownTime::SHUTDOWN_64S|64秒待ちます。| **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setPowerBoostKeepOn() @@ -174,13 +174,13 @@ false: 制御失敗。 **引数** -true: 電源供給を常に保ちます。 （IP5306スリープ無効） -false: 電源供給はIP5306が判断します。（IP5306スリープ有効） +|true|電源供給を常に保ちます。 （IP5306スリープ無効）| +|false| 電源供給はIP5306が判断します。（IP5306スリープ有効）| **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setKeepLightLoad() @@ -196,13 +196,13 @@ false: 制御失敗。 **引数** -true: 軽負荷時に自動シャットダウンしません。 -false: 軽負荷時に自動シャットダウンします。 +|true| 軽負荷時に自動シャットダウンしません。 | +|false| 軽負荷時に自動シャットダウンします。 | **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setLowPowerShutdown() @@ -218,13 +218,13 @@ false: 制御失敗。 **引数** -true: 省エネシャットダウン機能を有効にします。 -false: 省エネシャットダウン機能を無効にします。 +|true|省エネシャットダウン機能を有効にします。| +|false|省エネシャットダウン機能を無効にします。| **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## setAutoBootOnLoad() @@ -238,14 +238,13 @@ IP5306の2次側に電力消費が発生した場合に自動起動するかを **引数** -true: 自動起動機能を有効にします。 -false: 自動起動機能を無効にします。 +|true|自動起動機能を有効にします。| +|false|自動起動機能を無効にします。| **戻り値** -true: 制御成功。 -false: 制御失敗。 - +|true|制御成功| +|false|制御失敗| ## setCharge() @@ -260,13 +259,13 @@ false: 制御失敗。 **引数** -true: 充電開始指示。 -false: 充電中止指示。 +|true|充電開始指示。| +|false|充電中止指示。| **戻り値** -true: 制御成功。 -false: 制御失敗。 +|true|制御成功| +|false|制御失敗| ## isChargeFull() @@ -285,8 +284,8 @@ false: 制御失敗。 **戻り値** -true: 満充電。 -false: 満充電ではない。 +|true|満充電。 | +|false|満充電ではない。 | ## canControl() @@ -307,8 +306,8 @@ false: 満充電ではない。 **戻り値** -true: 電源コントローラーを制御可能。 -false: 電源コントローラーを制御不可能。 +|true|電源コントローラーを制御可能。| +|false|電源コントローラーを制御不可能。| ## isCharging() @@ -327,8 +326,8 @@ false: 電源コントローラーを制御不可能。 **戻り値** -true: 充電中。 -false: 充電中ではない。 +|true|充電中。| +|false|充電中ではない。| ## getBatteryLevel() @@ -429,8 +428,8 @@ false: それ以外によるもの **戻り値** -true : ウォッチドッグによるもの -false: それ以外によるもの +|true|ウォッチドッグによるもの| +|false|それ以外によるもの| ## isResetbyDeepsleep() @@ -448,8 +447,8 @@ false: それ以外によるもの **戻り値** -true : deepSleep()後の起動 -false: それ以外によるもの +|true|deepSleep()後の起動| +|false|それ以外によるもの| ## isResetbyPowerSW() @@ -467,8 +466,8 @@ false: それ以外によるもの **戻り値** -true : パワーSWからの電源投入後の起動 -false: それ以外によるもの +|true|パワーSWからの電源投入後の起動| +|false|それ以外によるもの| ## deepSleep() diff --git a/docs/zh_CN/api.md b/docs/zh_CN/api.md index 904696a0..46829f1f 100644 --- a/docs/zh_CN/api.md +++ b/docs/zh_CN/api.md @@ -7,7 +7,8 @@ |**[System](zh_CN/api/system)** | **[喇叭](zh_CN/api/speaker)** | |**[LCD 屏](zh_CN/api/lcd)** | **[按键](zh_CN/api/button)** | |**[MPU9250](zh_CN/api/mpu9250)** | **[TF 卡](zh_CN/api/tf)** | -|**[Power](zh_CN/api/power)** | +|**[电源管理](zh_CN/api/power)** |[GPIO](zh_CN/api/gpio)** | +|**[I2C 沟通](zh_CN/api/commutil)** | |