From 628404c203e1c2da94e294a582c56ff633d6c66d Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Wed, 24 Jan 2024 19:43:30 -0700 Subject: [PATCH 01/13] Update README.md Edits to bring this up to date --- README.md | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ee1b06c..3f97886 100644 --- a/README.md +++ b/README.md @@ -5,37 +5,30 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md) -gray +graybasic -basic +* **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)** -* **For the Detailed documentation of Gray, please [Click here](https://docs.m5stack.com/en/core/gray)** +* **Hardware documentation for [Basic v1.0 (EOL)](https://docs.m5stack.com/en/core/basic) [Basic v2.6 (EOL)](https://docs.m5stack.com/en/core/basic_v2.6) [Basic v2.7](https://docs.m5stack.com/en/core/basic_v2.7)** -* **For the Detailed documentation of Basic, please [Click here](https://docs.m5stack.com/en/core/basic_v2.6)** +* **[Buy Basic](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-7)** -* **In order to buy Gray, please [Click here](https://shop.m5stack.com/products/grey-development-core)** - -* **In order to buy Basic, please [Click here](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-6)** - -*We have several master M5Cores with different configurations, this is the difference between them [Compared](https://docs.m5stack.com/en/products_selector).* +*[Comparison of M5Stack controllers](https://docs.m5stack.com/en/products_selector).* ### M-BUS ![image](docs/M-BUS.jpg) ## More Information -**UIFlow Quick Start**: [Click Here](https://docs.m5stack.com/zh_CN/quick_start/m5core/uiflow) +**UIFlow Quick Start**: [Click Here](https://docs.m5stack.com/en/quick_start/m5core/uiflow) -**MicroPython API**: [Click Here](https://docs.m5stack.com/zh_CN/mpy/display/m5stack_lvgl) +**MicroPython API**: [Click Here](https://docs.m5stack.com/en/mpy/display/m5stack_lvgl) -**Arduino IDE Development**: [Click Here](https://docs.m5stack.com/zh_CN/quick_start/m5core/arduino) +**Arduino IDE Development**: [Click Here](https://docs.m5stack.com/en/quick_start/m5core/arduino) -**M5StickC Arduino API**: [Click Here](https://docs.m5stack.com/zh_CN/api/system) - -**Gray PinMap**: [Click Here](https://docs.m5stack.com/zh_CN/core/gray) - -**Basic PinMap**: [Click Here](https://docs.m5stack.com/zh_CN/core/basic) +**Gray PinMap**: [Click Here](https://docs.m5stack.com/en/core/gray) +**Basic PinMap**: [v1.0 (EOL)](https://docs.m5stack.com/en/core/basic) [v2.6 (EOL)](https://docs.m5stack.com/en/core/basic_v2.6) [v2.7](https://docs.m5stack.com/en/core/basic_v2.7)** ## USER CASES @@ -44,7 +37,6 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_starte * [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) - TFT library for the ESP8266 and ESP32 that supports different driver chips - * [M5StackSAM](https://github.com/tomsuch/M5StackSAM) - Simple Applications Menu Arduino Library for M5Stack * [cfGUI](https://github.com/JF002/cfGUI) - A simple GUI library for M5Stack (ESP32) From 58c49a22fc43fe054f1ae879fb5c8dee7a784a79 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Wed, 24 Jan 2024 20:03:46 -0700 Subject: [PATCH 02/13] Update README.md Describe the class members --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3f97886..a5d1162 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,13 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md) +The M5Stack library provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, including: +- LCD display via `M5.Lcd`, a customized version of the [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) LCD library, adapted for Basic and Gray. The display resolution is 320x240 supporting 262K colors. Several fonts, graphics primitives, and JPEG support are included. +- Power management via `M5.Power` +- Hardware buttons via `M5.BtnA`, `M5.BtnB`, `M5.BtnC` +- Speaker, via `M5.Speaker`, supporting tones, volume control, and basic wave audio playback +- Accelerometer, via `M5.Imu`, `M5.Mpu6886`, or `M5.Sh200Q` (accelerometer type depends on version of Basic/Gray) + graybasic * **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)** @@ -13,7 +20,7 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_starte * **[Buy Basic](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-7)** -*[Comparison of M5Stack controllers](https://docs.m5stack.com/en/products_selector).* +*[Comparison of M5Stack controllers](https://docs.m5stack.com/en/products_selector)* ### M-BUS ![image](docs/M-BUS.jpg) From c0ceb3151034ca1fe82088c00f7dfb935cd6fbfa Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Wed, 24 Jan 2024 20:15:36 -0700 Subject: [PATCH 03/13] Update README.md continued edits --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a5d1162..6632169 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,17 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md) -The M5Stack library provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, including: -- LCD display via `M5.Lcd`, a customized version of the [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) LCD library, adapted for Basic and Gray. The display resolution is 320x240 supporting 262K colors. Several fonts, graphics primitives, and JPEG support are included. -- Power management via `M5.Power` +The M5Stack library is included with `#include `, and provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, referenced as `M5`, including: +- LCD display via `M5.Lcd`, a customized version of the [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) LCD library, adapted for Basic and Gray. The display resolution is 320x240 supporting 262K colors. Several fonts, graphics primitives, QR code rendering, and PNG/BMP/JPEG support are included. +- Power control via `M5.Power` and the IP5306 power management chip - Hardware buttons via `M5.BtnA`, `M5.BtnB`, `M5.BtnC` - Speaker, via `M5.Speaker`, supporting tones, volume control, and basic wave audio playback - Accelerometer, via `M5.Imu`, `M5.Mpu6886`, or `M5.Sh200Q` (accelerometer type depends on version of Basic/Gray) +Additional include files: +- `M5Faces.h` for access to M5Stack Faces products (EOL) +- `LoRaWan.h` + graybasic * **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)** From b08e0380df76ba2193dd42af78a542fa96bdf00f Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Wed, 24 Jan 2024 20:17:12 -0700 Subject: [PATCH 04/13] Update README.md continued edits --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6632169..3347b3b 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,17 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md) -The M5Stack library is included with `#include `, and provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, referenced as `M5`, including: +The M5Stack library provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, referenced as `M5`, including: - LCD display via `M5.Lcd`, a customized version of the [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) LCD library, adapted for Basic and Gray. The display resolution is 320x240 supporting 262K colors. Several fonts, graphics primitives, QR code rendering, and PNG/BMP/JPEG support are included. - Power control via `M5.Power` and the IP5306 power management chip - Hardware buttons via `M5.BtnA`, `M5.BtnB`, `M5.BtnC` - Speaker, via `M5.Speaker`, supporting tones, volume control, and basic wave audio playback - Accelerometer, via `M5.Imu`, `M5.Mpu6886`, or `M5.Sh200Q` (accelerometer type depends on version of Basic/Gray) -Additional include files: -- `M5Faces.h` for access to M5Stack Faces products (EOL) +To use the M5Stack library, `#include "M5Stack.h"` must appear at the top of your sketch. + +Additional optional include files: +- `M5Faces.h` for access to M5Stack Faces accessories (EOL) - `LoRaWan.h` graybasic @@ -46,8 +48,6 @@ Additional include files: * [M5Stack-SD-Updater](https://github.com/tobozo/M5Stack-SD-Updater) - Customizable menu system for M5Stack - loads apps from the Micro SD card -* [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) - TFT library for the ESP8266 and ESP32 that supports different driver chips - * [M5StackSAM](https://github.com/tomsuch/M5StackSAM) - Simple Applications Menu Arduino Library for M5Stack * [cfGUI](https://github.com/JF002/cfGUI) - A simple GUI library for M5Stack (ESP32) From 2d561191f9824bc3a7386f44f7f44b032cd300a9 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Wed, 24 Jan 2024 23:54:06 -0700 Subject: [PATCH 05/13] Update README.md mention power and dac features --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3347b3b..d499ffe 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,15 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_starte The M5Stack library provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, referenced as `M5`, including: - LCD display via `M5.Lcd`, a customized version of the [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) LCD library, adapted for Basic and Gray. The display resolution is 320x240 supporting 262K colors. Several fonts, graphics primitives, QR code rendering, and PNG/BMP/JPEG support are included. -- Power control via `M5.Power` and the IP5306 power management chip +- Power control, including device shutoff and battery level detection via `M5.Power` and the IP5306 power management chip - Hardware buttons via `M5.BtnA`, `M5.BtnB`, `M5.BtnC` -- Speaker, via `M5.Speaker`, supporting tones, volume control, and basic wave audio playback +- Speaker, via `M5.Speaker`, supporting tones, volume control, and basic wave audio playback using ESP32's DAC function - Accelerometer, via `M5.Imu`, `M5.Mpu6886`, or `M5.Sh200Q` (accelerometer type depends on version of Basic/Gray) To use the M5Stack library, `#include "M5Stack.h"` must appear at the top of your sketch. +The most productive way to become acquainted with the class is through the numerous included examples. + Additional optional include files: - `M5Faces.h` for access to M5Stack Faces accessories (EOL) - `LoRaWan.h` From 6aa8c09ff00f073712863eea117d17423c374435 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 00:06:01 -0700 Subject: [PATCH 06/13] Update M5Stack.h Add/changed comments only --- src/M5Stack.h | 58 +++++++++++++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/src/M5Stack.h b/src/M5Stack.h index 8a538e3..647de13 100644 --- a/src/M5Stack.h +++ b/src/M5Stack.h @@ -13,7 +13,7 @@ * @brief Header for M5Stack.cpp module * * \par Description - * This file is a drive for M5Stack core. + * This file is a driver for M5Stack Core/Basic/Gray. * * \par Method List: * @@ -37,24 +37,20 @@ LCD: M5.lcd.setBrightness(uint8_t brightness); M5.Lcd.drawPixel(int16_t x, int16_t y, uint16_t color); - M5.Lcd.drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t - color); M5.Lcd.fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t - color); M5.Lcd.fillScreen(uint16_t color); M5.Lcd.drawCircle(int16_t x0, - int16_t y0, int16_t r, uint16_t color); M5.Lcd.drawCircleHelper(int16_t x0, - int16_t y0, int16_t r, uint8_t cornername,uint16_t color); + M5.Lcd.drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t color); + M5.Lcd.fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color); + M5.Lcd.fillScreen(uint16_t color); M5.Lcd.drawCircle(int16_t x0, int16_t y0, int16_t r, uint16_t color); + M5.Lcd.drawCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t cornername,uint16_t color); M5.Lcd.fillCircle(int16_t x0, int16_t y0, int16_t r, uint16_t color); - M5.Lcd.fillCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t - cornername,int16_t delta, uint16_t color); M5.Lcd.drawTriangle(int16_t x0, - int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color); - M5.Lcd.fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, - int16_t x2, int16_t y2, uint16_t color); M5.Lcd.drawRoundRect(int16_t x0, - int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color); - M5.Lcd.fillRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, - int16_t radius, uint16_t color); M5.Lcd.drawBitmap(int16_t x, int16_t y, const - uint8_t bitmap[], int16_t w, int16_t h, uint16_t color); - M5.Lcd.drawRGBBitmap(int16_t x, int16_t y, const uint16_t bitmap[], - int16_t w, int16_t h), M5.Lcd.drawChar(uint16_t x, uint16_t y, char c, uint16_t - color, uint16_t bg, uint8_t size); M5.Lcd.setCursor(uint16_t x0, uint16_t y0); + M5.Lcd.fillCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t cornername,int16_t delta, uint16_t color); + M5.Lcd.drawTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color); + M5.Lcd.fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color); + M5.Lcd.drawRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color); + M5.Lcd.fillRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color); + M5.Lcd.drawBitmap(int16_t x, int16_t y, const uint8_t bitmap[], int16_t w, int16_t h, uint16_t color); + M5.Lcd.drawRGBBitmap(int16_t x, int16_t y, const uint16_t bitmap[], int16_t w, int16_t h), + M5.Lcd.drawChar(uint16_t x, uint16_t y, char c, uint16_t color, uint16_t bg, uint8_t size); + M5.Lcd.setCursor(uint16_t x0, uint16_t y0); M5.Lcd.setTextColor(uint16_t color); M5.Lcd.setTextColor(uint16_t color, uint16_t backgroundcolor); M5.Lcd.setTextSize(uint8_t size); @@ -64,13 +60,12 @@ M5.Lcd.println(); M5.Lcd.drawCentreString(const char *string, int dX, int poY, int font); M5.Lcd.drawRightString(const char *string, int dX, int poY, int font); - M5.Lcd.drawJpg(const uint8_t *jpg_data, size_t jpg_len, uint16_t x, - uint16_t y); M5.Lcd.drawJpgFile(fs::FS &fs, const char *path, uint16_t x, - uint16_t y); M5.Lcd.drawBmpFile(fs::FS &fs, const char *path, uint16_t x, - uint16_t y); + M5.Lcd.drawJpg(const uint8_t *jpg_data, size_t jpg_len, uint16_t x, uint16_t y); + M5.Lcd.drawJpgFile(fs::FS &fs, const char *path, uint16_t x, uint16_t y); + M5.Lcd.drawBmpFile(fs::FS &fs, const char *path, uint16_t x, uint16_t y); Button: - M5.BtnA/B/C.read(); + M5.BtnA/B/C.read(); // Must be called in loop(), or via update() M5.BtnA/B/C.isPressed(); M5.BtnA/B/C.isReleased(); M5.BtnA/B/C.wasPressed(); @@ -125,21 +120,30 @@ class M5Stack { M5Stack(); void begin(bool LCDEnable = true, bool SDEnable = true, bool SerialEnable = true, bool I2CEnable = false); + + // Updates the status of hardware buttons, and ends any completed tone on the speaker. + // Recommended to be placed in loop() void update(); - // LCD + // LCD display, derived from TFT_eSPI. See examples M5Display Lcd = M5Display(); - // Power + // Power and battery charge control. Call Power.begin() in setup(). POWER Power; // Button API #define DEBOUNCE_MS 10 + + // Hardware button A. Call read() before checking if isPressed() Button BtnA = Button(BUTTON_A_PIN, true, DEBOUNCE_MS); + + // Hardware button B. Call read() before checking if isPressed() Button BtnB = Button(BUTTON_B_PIN, true, DEBOUNCE_MS); + + // Hardware button C. Call read() before checking if isPressed() Button BtnC = Button(BUTTON_C_PIN, true, DEBOUNCE_MS); - // SPEAKER + // SPEAKER on DAC pin 25 SPEAKER Speaker; // UART @@ -154,7 +158,7 @@ class M5Stack { SH200Q Sh200Q; /** - * Function has been move to Power class.(for compatibility) + * Function has been moved to Power class (for compatibility) * This name will be removed in a future release. */ void setPowerBoostKeepOn(bool en) __attribute__((deprecated)); From 602f5f6f7b319b538314125b9a9bcdc4fae97622 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 12:41:57 -0700 Subject: [PATCH 07/13] Create Power_capabilities.md to describe POWER class --- docs/Power_capabilities.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/Power_capabilities.md diff --git a/docs/Power_capabilities.md b/docs/Power_capabilities.md new file mode 100644 index 0000000..aaf5602 --- /dev/null +++ b/docs/Power_capabilities.md @@ -0,0 +1,27 @@ +## Power management capabilities of M5Stack Core / Basic / Gray + +Document v0.1 + +The power management capabilities are provided by the IP5306 power controller, specifically the IP5306_I2C version of the controller, +that can be accessed on the I2C bus at address 0x75. Access is possible using the `POWER` class, +located in `Power.h` and `Power.cpp`, automatically included with `#include "M5Stack.h"`. + +### Capabilities + +- **Can the M5Stack Core turn itself off?** Yes, using `powerOFF()`, which shuts off the LED backlight, the WiFi radio, the + Bluetooth stack, and then asks the chip to remove the power before putting the ESP into deep sleep mode. If called when the device is externally powered, + these actions (including the deep sleep mode) will give the appearance and effect of being powered off. Pressing the power/reset button turns it back on. +- **Can it wake itself back up after a pre-determined delay or at a specific time?** + No, since it doesn't have a real-time clock chip (RTC), but ESP32 sleep modes may provide a suitable alternative. +- **Can it tell if it is running on external versus battery power?** +- **Can it tell if the battery is being charged or discharged?** +- **Can it tell if a battery is present or absent?** *possibly, but not formally* +- **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of: 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read) +- **Can it read its battery voltage?** Not possible to read the voltage level directly, only the approximate percentage of 25/50/75/100. +- **Can communication with the IP5306 power controller be tested and confirmed?** Yes, with `canControl()` +- **What other capabilities?** *(to be answered -- translation of Chinese-language datasheet is difficult to understand)* + - *auto shutoff settings - voltage low for how long causes a shutoff* + - *inhibit the power button, report it as an event?* + - *setting the charging voltage and current* + - *distinguish between a software/hardware/watchdog/poweron reset* + - *maintain any of the settings across power cycles and/or complete loss of all power* From 766187c9d73b6cc63a5524654521568351ef0d56 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 13:26:16 -0700 Subject: [PATCH 08/13] Update Power_capabilities.md --- docs/Power_capabilities.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/Power_capabilities.md b/docs/Power_capabilities.md index aaf5602..4c7531b 100644 --- a/docs/Power_capabilities.md +++ b/docs/Power_capabilities.md @@ -13,15 +13,17 @@ located in `Power.h` and `Power.cpp`, automatically included with `#include "M5S these actions (including the deep sleep mode) will give the appearance and effect of being powered off. Pressing the power/reset button turns it back on. - **Can it wake itself back up after a pre-determined delay or at a specific time?** No, since it doesn't have a real-time clock chip (RTC), but ESP32 sleep modes may provide a suitable alternative. -- **Can it tell if it is running on external versus battery power?** -- **Can it tell if the battery is being charged or discharged?** +- **Can it tell if it is running on external versus battery power?** If `isCharging()` or `isChargeFull()` true, probably on external power. +- **Can it detect the rate of charge or discharge?** *probably not, but inference can probably be made by comparing `isChargeFull()` to the charge full current cutoff* - **Can it tell if a battery is present or absent?** *possibly, but not formally* -- **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of: 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read) -- **Can it read its battery voltage?** Not possible to read the voltage level directly, only the approximate percentage of 25/50/75/100. +- **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of: 0, 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read) +- **Can it read its battery voltage?** Not possible to read the voltage level directly, only the approximate percentage of 0/25/50/75/100. - **Can communication with the IP5306 power controller be tested and confirmed?** Yes, with `canControl()` - **What other capabilities?** *(to be answered -- translation of Chinese-language datasheet is difficult to understand)* - *auto shutoff settings - voltage low for how long causes a shutoff* - *inhibit the power button, report it as an event?* - *setting the charging voltage and current* - - *distinguish between a software/hardware/watchdog/poweron reset* + - *distinguish between a software/hardware/watchdog/sleep/poweron reset* - *maintain any of the settings across power cycles and/or complete loss of all power* + - *how does setAutoBootOnLoad() work? when enabled, it seems the device can be powered back on simply by connecting a load -- such as + connecting another M5Stack controller to be powered from PORTA -- if done before the shutdown_8s time expires* From fec0a3e390d52390aa0a05ac217f646c71a832c6 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 13:51:13 -0700 Subject: [PATCH 09/13] Update Power_capabilities.md --- docs/Power_capabilities.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Power_capabilities.md b/docs/Power_capabilities.md index 4c7531b..40f59ef 100644 --- a/docs/Power_capabilities.md +++ b/docs/Power_capabilities.md @@ -3,8 +3,8 @@ Document v0.1 The power management capabilities are provided by the IP5306 power controller, specifically the IP5306_I2C version of the controller, -that can be accessed on the I2C bus at address 0x75. Access is possible using the `POWER` class, -located in `Power.h` and `Power.cpp`, automatically included with `#include "M5Stack.h"`. +that can be accessed on the I2C bus at address 0x75. Access is possible via M5.Power, which is implemented in +`src/utility/Power.h` and `src/utility/Power.cpp`, and becomes available with `#include "M5Stack.h"`. ### Capabilities @@ -15,7 +15,7 @@ located in `Power.h` and `Power.cpp`, automatically included with `#include "M5S No, since it doesn't have a real-time clock chip (RTC), but ESP32 sleep modes may provide a suitable alternative. - **Can it tell if it is running on external versus battery power?** If `isCharging()` or `isChargeFull()` true, probably on external power. - **Can it detect the rate of charge or discharge?** *probably not, but inference can probably be made by comparing `isChargeFull()` to the charge full current cutoff* -- **Can it tell if a battery is present or absent?** *possibly, but not formally* +- **Can it tell if a battery is present or absent?** *possibly, but not formally... an absent battery seems to always be reported as "charging", having a level of "100%", and never becomes "charge full"* - **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of: 0, 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read) - **Can it read its battery voltage?** Not possible to read the voltage level directly, only the approximate percentage of 0/25/50/75/100. - **Can communication with the IP5306 power controller be tested and confirmed?** Yes, with `canControl()` From 0531f383c7dc6c90bcf665d95b50c1f1fc36a75a Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 14:11:54 -0700 Subject: [PATCH 10/13] Update README.md --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d499ffe..5aa1ab9 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ The M5Stack library provides access to the built-in hardware of the M5Stack Bas To use the M5Stack library, `#include "M5Stack.h"` must appear at the top of your sketch. -The most productive way to become acquainted with the class is through the numerous included examples. +The most productive way to become acquainted with the class is through the numerous included examples. Additional documentation within this library: +- [docs/Power_capabilities.md](docs/Power_capabilities.md) Additional optional include files: - `M5Faces.h` for access to M5Stack Faces accessories (EOL) @@ -24,7 +25,7 @@ Additional optional include files: * **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)** -* **Hardware documentation for [Basic v1.0 (EOL)](https://docs.m5stack.com/en/core/basic) [Basic v2.6 (EOL)](https://docs.m5stack.com/en/core/basic_v2.6) [Basic v2.7](https://docs.m5stack.com/en/core/basic_v2.7)** +* **Hardware documentation for [Basic v1.0 (EOL)](https://docs.m5stack.com/en/core/basic) [Basic v2.6 (EOL)](https://docs.m5stack.com/en/core/basic_v2.6) [Basic v2.7](https://docs.m5stack.com/en/core/basic_v2.7)**. The version number may be printed on the main circuit board next to the SD card slot. * **[Buy Basic](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-7)** @@ -58,15 +59,13 @@ Additional optional include files: * [M5ez](https://github.com/M5ez/M5ez) - The easy way to program on the M5Stack - * [M5Stack MultiApp Advanced](https://github.com/botofancalin/M5Stack-MultiApp-Advanced) - A M5Stack firmware made on PlatformIO - * [M5Stack ESP32 Oscilloscope](https://github.com/botofancalin/M5Stack-ESP32-Oscilloscope) - A fully functional oscilloscope based on ESP32 M5Stack * [M5Stack-Avatar](https://github.com/meganetaaan/m5stack-avatar) - An M5Stack library for rendering avatar faces -* [M5Stack_CrackScreen](https://github.com/nomolk/M5Stack_CrackScreen) - Crack your M5Stack!! +* [M5Stack_CrackScreen](https://github.com/nomolk/M5Stack_CrackScreen) - Crack your M5Stack * [M5_Shuttle_Run](https://github.com/n0bisuke/M5_Shuttle_Run) - M5_Shuttle_Run @@ -86,7 +85,7 @@ Additional optional include files: * [ArduinoWiFiPhotoBackup](https://github.com/moononournation/ArduinoWiFiPhotoBackup) - M5STACK Arduino WiFi Photo Backup device -* [M5StackHIDCtrlAltDel](https://github.com/mhama/M5StackHIDCtrlAltDel) - You can send ctrl+alt+del to your PC from M5Stack +* [M5StackHIDCtrlAltDel](https://github.com/mhama/M5StackHIDCtrlAltDel) - You can send ctrl+alt+del to your PC via Bluetooth from M5Stack * [M5Stack Markdown Web Server](https://github.com/PartsandCircuits/M5Stack-MarkdownWebServer) - Markdown & icons loaded from an Micro SD card/TF card to run a web page From ffa25647dcc78beaa5cb1b0bb531bb8f528de1bb Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 22:45:16 -0700 Subject: [PATCH 11/13] Update Power_capabilities.md --- docs/Power_capabilities.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/Power_capabilities.md b/docs/Power_capabilities.md index 40f59ef..3208e4c 100644 --- a/docs/Power_capabilities.md +++ b/docs/Power_capabilities.md @@ -16,9 +16,16 @@ that can be accessed on the I2C bus at address 0x75. Access is possible via M5. - **Can it tell if it is running on external versus battery power?** If `isCharging()` or `isChargeFull()` true, probably on external power. - **Can it detect the rate of charge or discharge?** *probably not, but inference can probably be made by comparing `isChargeFull()` to the charge full current cutoff* - **Can it tell if a battery is present or absent?** *possibly, but not formally... an absent battery seems to always be reported as "charging", having a level of "100%", and never becomes "charge full"* -- **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of: 0, 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read) +- **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of: + 0, 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read) - **Can it read its battery voltage?** Not possible to read the voltage level directly, only the approximate percentage of 0/25/50/75/100. - **Can communication with the IP5306 power controller be tested and confirmed?** Yes, with `canControl()` +- **Where does the IP5306 power controller get its own power?** Only from either the battery or the USB port. The 5V connection on the M5Stack + Core/Basic/Gray controller is not a power *source* for the IP5306 chip and is considered downstream from the chip (i.e. the *output*). If the M5Stack controller + is being powered through the 5V pin (for example, through a base or some other accessory), this power is not an *input* to the IP5306 chip, + and will not charge the battery. The IP5306 will shut down under this condition to minimize battery drain, unless configured not to. + When the chip is shut down, it will not respond to I2C communication + (for example, `getBatteryLevel()` will return -1) - **What other capabilities?** *(to be answered -- translation of Chinese-language datasheet is difficult to understand)* - *auto shutoff settings - voltage low for how long causes a shutoff* - *inhibit the power button, report it as an event?* @@ -26,4 +33,4 @@ that can be accessed on the I2C bus at address 0x75. Access is possible via M5. - *distinguish between a software/hardware/watchdog/sleep/poweron reset* - *maintain any of the settings across power cycles and/or complete loss of all power* - *how does setAutoBootOnLoad() work? when enabled, it seems the device can be powered back on simply by connecting a load -- such as - connecting another M5Stack controller to be powered from PORTA -- if done before the shutdown_8s time expires* + connecting another M5Stack controller to be powered from PORT_A -- if done before the shutdown_8s time expires* From 5a9f50408e017f5665e41ad3c9555cbb36d5d536 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Thu, 25 Jan 2024 22:46:16 -0700 Subject: [PATCH 12/13] Update Power_capabilities.md --- docs/Power_capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Power_capabilities.md b/docs/Power_capabilities.md index 3208e4c..a513606 100644 --- a/docs/Power_capabilities.md +++ b/docs/Power_capabilities.md @@ -22,7 +22,7 @@ that can be accessed on the I2C bus at address 0x75. Access is possible via M5. - **Can communication with the IP5306 power controller be tested and confirmed?** Yes, with `canControl()` - **Where does the IP5306 power controller get its own power?** Only from either the battery or the USB port. The 5V connection on the M5Stack Core/Basic/Gray controller is not a power *source* for the IP5306 chip and is considered downstream from the chip (i.e. the *output*). If the M5Stack controller - is being powered through the 5V pin (for example, through a base or some other accessory), this power is not an *input* to the IP5306 chip, + is being powered through the 5V connection other than the USB port (for example, through a base or some other accessory), this power is not an *input* to the IP5306 chip, and will not charge the battery. The IP5306 will shut down under this condition to minimize battery drain, unless configured not to. When the chip is shut down, it will not respond to I2C communication (for example, `getBatteryLevel()` will return -1) From 7a52ed12616615d2357e91e55c2a1f43458cd5e5 Mon Sep 17 00:00:00 2001 From: "@chipguyhere" <73178777+chipguyhere@users.noreply.github.com> Date: Fri, 26 Jan 2024 07:36:47 -0700 Subject: [PATCH 13/13] Suggest using M5Unified instead --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5aa1ab9..36c89e6 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,13 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md) -The M5Stack library provides access to the built-in hardware of the M5Stack Basic and Gray controllers through the M5Stack class, referenced as `M5`, including: +The M5Stack library provides access to the built-in hardware of the M5Stack Core (including Basic and Gray) controllers. + +## Recommendation +**This library is not recommended for new projects, nor for projects using M5Stack products other than _Basic_ and _Gray_. See [M5Unified](https://github.com/M5Stack/M5Unified) and [M5GFX](https://github.com/M5Stack/M5GFX) for libraries that are more up-to-date and with support for many newer M5Stack products.** + +## Usage +This library's functionality is available through the M5Stack class, referenced as `M5`, including: - LCD display via `M5.Lcd`, a customized version of the [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) LCD library, adapted for Basic and Gray. The display resolution is 320x240 supporting 262K colors. Several fonts, graphics primitives, QR code rendering, and PNG/BMP/JPEG support are included. - Power control, including device shutoff and battery level detection via `M5.Power` and the IP5306 power management chip - Hardware buttons via `M5.BtnA`, `M5.BtnB`, `M5.BtnC` @@ -21,7 +27,7 @@ Additional optional include files: - `M5Faces.h` for access to M5Stack Faces accessories (EOL) - `LoRaWan.h` -graybasic +basicgray * **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)** @@ -32,7 +38,7 @@ Additional optional include files: *[Comparison of M5Stack controllers](https://docs.m5stack.com/en/products_selector)* ### M-BUS -![image](docs/M-BUS.jpg) + ## More Information