diff --git a/docs/en/api.md b/docs/en/api.md index a82b0dbd..6ae59513 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)** |**[I/O](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..bac0a7ef --- /dev/null +++ b/docs/en/api/commutil.md @@ -0,0 +1,216 @@ +# I2C + +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 |function address | +| 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| + +**Example of use;** + +```arduino + bool result[0x80]; + M5.I2C.scanID(&result[0]); +``` diff --git a/docs/en/api/gpio.md b/docs/en/api/gpio.md index de868a6b..0b57d019 100644 --- a/docs/en/api/gpio.md +++ b/docs/en/api/gpio.md @@ -1,21 +1,309 @@ -# 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); -``` \ No newline at end of file +# I/O (GPIO/ADC/DAC/PWM) + +*Refer to Arduino API of [Arduino](http://www.arduino.cc)* + +*For the sake of convenience, I will focus on things that are closely related to M5Stack* + +*M5STACK PIN allocation:* + +| pin No | Name |allocation| +| --- | --- | --- | +| 0 | G0 |downloader | +| 1 | T1 |UART | +| 2 | G2 |Side terminal (except M5FIRE),M5-BUS| +| 3 | R1 |UART | +| 4 | G4 |TF| +| 5 | G5 |Side terminal (except M5FIRE),M5-BUS| +| 6 | G6 |SDIO | +| 7 | G7 |SDIO | +| 8 | G8 |SDIO | +| 9 | G9 |SDIO | +| 10 | G10 |SDIO | +| 11 | G11 |SDIO | +| 12 | G12 |LCD | +| 13 | G13 |LCD | +| 14 | G14 |LCD | +| 15 | G15 |LCD | +| 16 | R2 |UART | +| 17 | T2 |UART | +| 18 | G18 |TF,Top terminal(SCK),M5-BUS| +| 19 | G19 |TF,Top terminal(MISO),M5-BUS| +| 21 | G21 |GROVE-A(SDA)| +| 22 | G22 |GROVE-A(SCL)| +| 23 | G23 |TF,Top terminal(MOSI)| +| 25 | G25 |Speaker,Side terminal (except M5FIRE),M5-BUS| +| 26 | G26 |Side terminal (except M5FIRE),M5-BUS| +| 27 | G27 |LCD | +| 32 | G32 |LCD BackLight | +| 33 | G33 |LCD | +| 34 | G34 |None | +| 35 | G35 |Side terminal (except M5FIRE)| +| 36 | G36 |Side terminal (except M5FIRE)| +| 37 | G37 |Button C| +| 38 | G38 |Button B| +| 39 | G39 |Button A| + + +## digitalRead() + +**Syntax:** + +int digitalRead(uint8_t pin); + +**Description:** + +Reads the state of the terminal. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8 |Pin No | + +**Function return value:** + +Pin input state(0/1) + +**Note** + +1)If the pin mode is not set to INPUT, the correct result will not be returned. + +2)If there are other circuits in the control line, they will be affected. + +**Example of use;** + +```arduino +uint32_t pin21_data; +pin21_data = digitalRead(21); +``` + +## digitalWrite() + +**Syntax:** + +void digitalWrite(uint8_t pin, uint8_t val); + +**Description:** + +Writes the state of the terminal. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8 |pin No | +| val | uint8 |出力状態(0/1) | + +**Function return value:** + +None. + +**Note** + +1)If the pin mode is not set to OUTPUT, the correct result will not be returned. + +2)If there are other circuits in the control line, please note it as it may be physically damaged. + + +**Example of use;** + +```arduino +digitalWrite(2,1); +``` + +## pinMode() + +**Syntax:** + +void pinMode(uint8_t pin, uint8_t mode); + +**Description:** + +Set terminal input / output mode. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8 |pin No | +| mode | uint8 |INPUT,OUTPUT,INPUT_PULLUPのいずれか| + +**Function return value:** + +None. + +**Note** + +If there are other circuits on the bus, please note that there is a possibility of physical damage. + +For example, when the speaker (G25) terminal is set to INPUT mode, the current flowing to the speaker causes the main unit to generate heat. + +Make sure that the operations are correct as there is a risk of damage. + +**Example of use;** + +```arduino +pinMode(2,INPUT); +``` + +## analogRead() + +**Syntax:** +uint16_t analogRead(uint8_t pin); + +**Description:** + +Reads the value of the analog terminal. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8 |pin No | + +**Function return value:** + +Read result. The maximum value of the response is determined by analogSetWidth (). + +**Note** + +G35 and G36 can be used in M5Stack. + +**Example of use;** + +```arduino +uint16_t ret; +ret=analogRead(35); +``` + +## dacWrite() + +**Syntax:** + +void dacWrite(uint8_t pin, uint8_t value); + +**Description:** + +Output command to analog terminal. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8 |pin No | +| value | uint8 |set output voltage | + +**Function return value:** + +None.。 + +**Note** + +G25 and G26 can be used in M5Stack. + +**Example of use;** + +```arduino +dacWrite(25,0x40); +``` + +## ledcSetup() + +**Syntax:** + +double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits); + +**Description:** + +Set the duty output + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| channel | uint8 |channel (0～15) | +| freq | double |frequency (Hz) | +| resolution_bits | uint8_t |Number of full scale bits for duty indication | + +**Function return value:** + +Actual output frequency. + +**Note** + +Channel and GPIO port numbers are not identical. + +It is good to recognize that it is a number to memorize the setting. + + + +## ledcAttachPin() + +**Syntax:** + +void ledcAttachPin(uint8_t pin, uint8_t chan); + +**Description:** + +Specify the port to output. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8_t |pin No) | +| chan | uint8_t |Channel(0～15) | + +**Function return value:** + +None. + + +## ledcWrite() + +**Syntax:** + +void ledcWrite(uint8_t chan, uint32_t duty); + +**Description:** + +Output with the specified duty value. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| chan | uint8_t |Channel(0～15) | +| duty | uint32_t |Duty | + +**Function return value:** + +None. + +**Note** + +The unit of duty depends on the bit scale set at initialization. + +When specifying with 8 bits, specifying 0xFF results in 100% output. + + +## ledcDetachPin() + +**Syntax:** + +void ledcDetachPin(uint8_t pin); + +**Description:** + +Release the assigned port and stop the output. + +**Function argument** + +| Function argument |Type |Description | +| --- | --- | --- | +| pin | uint8_t |pin No) | + + +**Function return value:** + +None. diff --git a/docs/en/api/power.md b/docs/en/api/power.md index 77b20ba0..e61ac316 100644 --- a/docs/en/api/power.md +++ b/docs/en/api/power.md @@ -1,5 +1,196 @@ # 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 + 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** + +| Param | Description | +| --- | --- | +|true|Press and hold to turn on / off.| +|false|Turn on / off with two short presses.| + +**Function return value** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true| ON / OFF in one short press.| +|false| Follow the setPowerBoostOnOff () method.| + +**Function return value** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true|The power will be turned on again. | +|false|The power will not be turned on again. | + +**Function return value** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true| Turn on the LED with two short presses| +|false| Turn on the LED with Press and hold| + +**Function return value** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true| Accept power operation.| +|false| Does not accept power control.| + +**Function return value** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true|Control success.| +|false|Control failure. | + + ## setPowerBoostKeepOn() **Syntax:** @@ -12,37 +203,17 @@ This function sets/unsets always boost output mode. **Function argument** -true: Turn on always boost output mode, -false: Turn off always boost output mode. +| Param | Description | +| --- | --- | +|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; -} -``` +| Param | Description | +| --- | --- | +|true|Control success.| +|false|Control failure. | ## setKeepLightLoad() @@ -53,40 +224,73 @@ 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** -true: When the current is too small, IP5306 will *not* automatically shutdown, -false: When the current is too small, IP5306 will automatically shutdown. +| Param | Description | +| --- | --- | +|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. +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true|Enable energy saving shutdown function.| +|false|Disable energy saving shutdown function.| + +**Function return value** + +| Param | Description | +| --- | --- | +|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** + +| Param | Description | +| --- | --- | +|true|Enable the auto start function.| +|false|Disable auto start function.| + +**Function return value** + +| Param | Description | +| --- | --- | +|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() @@ -97,41 +301,22 @@ bool setKeepLightLoad(bool en) { **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. +| Param | Description | +| --- | --- | +|true|Start charging, | +|false| Stop charging. | **Function return value** -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; -} -``` +| Param | Description | +| --- | --- | +|true|Control success.| +|false|Control failure. | ## isChargeFull() @@ -149,26 +334,11 @@ No argument. **Function return value** -true: Full charged, -false: Not full charged. +| Param | Description | +| --- | --- | +|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 +348,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** @@ -186,19 +356,11 @@ No argument. **Function return value** -true: Battery controller is found, -false: Battery controller is not found. +| Param | Description | +| --- | --- | +|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() @@ -216,26 +378,11 @@ No argument. **Function return value** -true: In charging, -false: Not in charging. +| Param | Description | +| --- | --- | +|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() @@ -254,27 +401,9 @@ No argument. **Function return value** 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 +412,181 @@ 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** + +| Param | Description | +| --- | --- | +|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. -**Definition:** +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. +**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.md b/docs/ja/api.md index f54fcf27..d03e9d68 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)** |**[I/O](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..092c933d --- /dev/null +++ b/docs/ja/api/commutil.md @@ -0,0 +1,215 @@ +# I2C + +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|読込失敗。| + +**使用例;** + +```arduino + bool result[0x80]; + M5.I2C.scanID(&result[0]); +``` + diff --git a/docs/ja/api/gpio.md b/docs/ja/api/gpio.md index 938a1a70..42e19332 100644 --- a/docs/ja/api/gpio.md +++ b/docs/ja/api/gpio.md @@ -1,23 +1,311 @@ -# 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); -``` \ No newline at end of file +# I/O (GPIO/ADC/DAC/PWM) + +*詳しくは [Arduino](http://www.arduino.cc) の マニュアルを見てください* + +*便宜上、M5Stackに関連の深いものに絞って説明します* + +**M5STACK割り当て:** + +| pin番号 | 名称 |割り当て先| +| --- | --- | --- | +| 0 | G0 |ダウンローダ | +| 1 | T1 |UART | +| 2 | G2 |側面端子(M5FIREを除く),M5-BUS| +| 3 | R1 |UART | +| 4 | G4 |TF| +| 5 | G5 |側面端子(M5FIREを除く),M5-BUS| +| 6 | G6 |SDIO | +| 7 | G7 |SDIO | +| 8 | G8 |SDIO | +| 9 | G9 |SDIO | +| 10 | G10 |SDIO | +| 11 | G11 |SDIO | +| 12 | G12 |LCD | +| 13 | G13 |LCD | +| 14 | G14 |LCD | +| 15 | G15 |LCD | +| 16 | R2 |UART | +| 17 | T2 |UART | +| 18 | G18 |TF,上面端子(SCK),M5-BUS| +| 19 | G19 |TF,上面端子(MISO),M5-BUS| +| 21 | G21 |GROVE-A(SDA)| +| 22 | G22 |GROVE-A(SCL)| +| 23 | G23 |TF,上面端子(MOSI)| +| 25 | G25 |スピーカ,側面端子(M5FIREを除く),M5-BUS| +| 26 | G26 |側面端子(M5FIREを除く),M5-BUS| +| 27 | G27 |LCD | +| 32 | G32 |LCDバックライト | +| 33 | G33 |LCD | +| 34 | G34 |なし | +| 35 | G35 |側面端子(M5FIREを除く)| +| 36 | G36 |側面端子(M5FIREを除く)| +| 37 | G37 |Cボタン| +| 38 | G38 |Bボタン| +| 39 | G39 |Aボタン| + + +## digitalRead() + +**構文:** + +int digitalRead(uint8_t pin); + +**説明:** + +端子の状態を読み取ります。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8 |ピン番号 | + +**戻り値:** + +ピンの電圧入力状態(0/1) + +**注意** + +1)ピンモードがINPUTになっていない場合は正しい結果を返しません。 + +2)バスに他の回路がある場合、その影響を受けます。 + +**使用例;** +```arduino +uint32_t pin21_data; +pin21_data = digitalRead(21); +``` + +## digitalWrite() + +**構文:** + +void digitalWrite(uint8_t pin, uint8_t val); + +**説明:** + +端子の状態を書き込みます。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8 |ピン番号 | +| val | uint8 |出力状態(0/1) | + +**戻り値:** + +なし + +**注意** + +1)ピンモードがOUTPUTになっていない場合は正しい結果を返しません。 + +2)バスに他の回路がある場合、物理的に破損する可能性があるため、注意してください。 + + +**使用例;** + +```arduino +digitalWrite(2,1); +``` + +## pinMode() + +**構文:** + +void pinMode(uint8_t pin, uint8_t mode); + +**説明:** + +端子の入出力モードを設定します + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8 |ピン番号 | +| mode | uint8 |INPUT,OUTPUT,INPUT_PULLUPのいずれか| + +**戻り値:** + +なし + +**注意** + +バスに他の回路がある場合、物理的に破損する可能性があるため、注意してください。 + +例えば、スピーカ(G25)端子をINPUTモードにすると、スピーカへ流れる電流により本体が発熱します。 + +故障の恐れがあるため、指示内容が正しいことを確認してください。 + +**使用例;** + +```arduino +pinMode(2,INPUT); +``` + +## analogRead() + +**構文:** +uint16_t analogRead(uint8_t pin); + +**説明:** + +アナログ端子の値を読み取ります。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8 |ピン番号 | + +**戻り値:** + +読み取り結果。返答の最大値はanalogSetWidth()で決定します。 + +**注意** + +M5StackではG35,G36が使用できます。 + +**使用例;** + +```arduino +uint16_t ret; +ret=analogRead(35); +``` + +## dacWrite() + +**構文:** + +void dacWrite(uint8_t pin, uint8_t value); + +**説明:** + +アナログ端子に出力指示をします。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8 |ピン番号 | +| value | uint8 |出力指示電圧 | + +**戻り値:** + +なし。 + +**注意** + +M5StackではG25,G26が使用できます。 + +**使用例;** + +```arduino +dacWrite(25,0x40); +``` + +## ledcSetup() + +**構文:** + +double ledcSetup(uint8_t channel, double freq, uint8_t resolution_bits); + +**説明:** + +デューティ出力設定をします + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| channel | uint8 |チャネル(0～15) | +| freq | double |周波数(Hz) | +| resolution_bits | uint8_t |デューティ指示のフルスケールビット数 | + +**戻り値:** + +実際の出力周波数。 + +**注意** + +チャンネルとGPIOポート番号は同一ではありません。 + +設定を記憶するための番号だと認識するとよいでしょう。 + + + +## ledcAttachPin() + +**構文:** + +void ledcAttachPin(uint8_t pin, uint8_t chan); + +**説明:** + +出力するポートを指定します。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8_t |ピン番号) | +| chan | uint8_t |チャネル(0～15) | + +**戻り値:** + +なし + + + + +## ledcWrite() + +**構文:** + +void ledcWrite(uint8_t chan, uint32_t duty); + +**説明:** + +指定したデューティ値で出力します。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| chan | uint8_t |チャネル(0～15) | +| duty | uint32_t |デューティ | + +**戻り値:** + +なし + +**注意** + +デューティの単位は、初期化時に設定したビットスケールに依存します。 + +8ビットで指示していた場合は 0xFF を指定すると100%出力になります。 + + + +## ledcDetachPin() + +**構文:** + +void ledcDetachPin(uint8_t pin); + +**説明:** + +割り当てたポートを解放し、出力をやめます。 + +**引数** + +| 引数 |型 |説明 | +| --- | --- | --- | +| pin | uint8_t |ピン番号) | + + +**戻り値:** + +なし diff --git a/docs/ja/api/power.md b/docs/ja/api/power.md index 8f54dabc..387af76c 100644 --- a/docs/ja/api/power.md +++ b/docs/ja/api/power.md @@ -1,5 +1,191 @@ # Power +*電源関連の機能はIP5306チップに依存しています。必要に応じてデータシート[IP5306]（https://github.com/m5stack/M5-Schematic/blob/master/Core/IIC_IP5306_REG_V1.4.pdf）を参照してください* + +*古いM5STACKハードウェアの場合、IP5306チップが通信未対応です。機能を使う場合は制御できないケースも考慮してください。* + +下記の例のように、初期化、通信確認、制御の順で使用してください。 +```arduino + 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 +194,22 @@ **説明:** -電源供給状態を設定します。 +省エネを無効にし電源供給状態を維持します。 **引数** -true: 常時供給モードon。 -false: 常時供給モードoff。 +| 値 |説明 | +| --- |--- | +|true|電源供給を常に保ちます。 （IP5306スリープ無効）| +|false| 電源供給はIP5306が判断します。（IP5306スリープ有効）| **戻り値** -true: 制御成功。 -false: 制御失敗。 +| 値 |説明 | +| --- |--- | +|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,40 +220,71 @@ bool setPowerBoostKeepOn(bool en){ **説明:** 自動シャットダウン無効化機能を設定します。 +(非推奨：この関数は無効化され、今後なくなります) **引数** -true: 軽負荷時に自動シャットダウンしません。 -false: 軽負荷時に自動シャットダウンします。 +| 値 |説明 | +| --- |--- | +|true| 軽負荷時に自動シャットダウンしません。 | +|false| 軽負荷時に自動シャットダウンします。 | **戻り値** -true: 制御成功。 -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(); +**構文:** - 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; -} -``` +bool setLowPowerShutdown(bool en) + +**説明:** + +省電力時の自動シャットダウン機能を設定します。 +(非推奨：この関数は無効化され、今後なくなります。setPowerBoostKeepOnを使ってください) + +**引数** + +| 値 |説明 | +| --- |--- | +|true|省エネシャットダウン機能を有効にします。| +|false|省エネシャットダウン機能を無効にします。| + +**戻り値** + +| 値 |説明 | +| --- |--- | +|true|制御成功| +|false|制御失敗| + +## setAutoBootOnLoad() + +**構文:** + +bool setAutoBootOnLoad(bool en) + +**説明:** + +IP5306の2次側に電力消費が発生した場合に自動起動するかを設定します。 + +**引数** + +| 値 |説明 | +| --- |--- | +|true|自動起動機能を有効にします。| +|false|自動起動機能を無効にします。| + +**戻り値** + +| 値 |説明 | +| --- |--- | +|true|制御成功| +|false|制御失敗| ## setCharge() @@ -101,37 +299,18 @@ bool setKeepLightLoad(bool en) { **引数** -true: 充電開始指示。 -false: 充電中止指示。 +| 値 |説明 | +| --- |--- | +|true|充電開始指示。| +|false|充電中止指示。| **戻り値** -true: 制御成功。 -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,26 +328,11 @@ bool POWER::setCharge(bool en){ **戻り値** -true: 満充電。 -false: 満充電ではない。 +| 値 |説明 | +| --- |--- | +|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 +343,8 @@ bool isChargeFull(){ **説明:** 電源コントローラが制御可能かどうかを判断します。 +古いM5Stackなど、IP5306を認識できない場合はfalseとなります。 +その場合は、Powerクラスのほとんどが機能しません。 **引数** @@ -186,19 +352,11 @@ bool isChargeFull(){ **戻り値** -true: 電源コントローラーを制御可能。 -false: 電源コントローラーを制御不可能。 +| 値 |説明 | +| --- |--- | +|true|電源コントローラーを制御可能。| +|false|電源コントローラーを制御不可能。| -**定義:** - -```arduino -bool canControl(){ - uint8_t data; - Wire.beginTransmission(IP5306_ADDR); - Wire.write(IP5306_REG_READ0); - return(Wire.endTransmission()==0); -} -``` ## isCharging() @@ -216,32 +374,17 @@ bool canControl(){ **戻り値** -true: 充電中。 -false: 充電中ではない。 +| 値 |説明 | +| --- |--- | +|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 +399,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 +408,22 @@ int8_t getBatteryLevel() { **説明:** -スリープ復帰信号ポートを設定します。 +スリープから復帰するときに監視する信号ポートを設定します。 -**定義:** +**引数** + +| 値 |説明 | +| --- |--- | +|button| ポート番号 | + +**戻り値** + +なし + +**使用例:** ```arduino -void setWakeupButton(uint8_t button) { - _wakeupPin = button; -} +setWakeupButton(BUTTON_A_PIN); ``` ## reset() @@ -301,83 +434,150 @@ 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.md b/docs/zh_CN/api.md index 904696a0..0c5f1a93 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)** |**[I/O](zh_CN/api/gpio)** | +|**[I2C 沟通](zh_CN/api/commutil)** | | ## deepSleep() @@ -343,28 +528,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无法确定电源关闭。 +