Significant changes to README.md and M5Stack.h to benefit new users

m5stack · Jun 20, 2024 · c4607cd · c4607cd
2 parents 2feddca + 7a52ed1
commit c4607cd
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 50 deletions.
diff --git a/README.md b/README.md
@@ -5,46 +5,58 @@
 
 English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md)
 
-<img src="https://static-cdn.m5stack.com/resource/docs/static/assets/img/product_pics/core/gray/gray_01.webp" alt="gray" width="350" height="350">
+The M5Stack library provides access to the built-in hardware of the M5Stack Core (including Basic and Gray) controllers.
 
-<img src="https://static-cdn.m5stack.com/resource/docs/static/assets/img/product_pics/core/basic/basic_01.webp" alt="basic" width="350" height="350">
+## Recommendation
+**<span style="font-size: larger">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.</span>**
 
-* **For the Detailed documentation of Gray, please [Click here](https://docs.m5stack.com/en/core/gray)**
+## 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`
+- 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) 
 
-* **For the Detailed documentation of Basic, please [Click here](https://docs.m5stack.com/en/core/basic_v2.6)**
+To use the M5Stack library, `#include "M5Stack.h"` must appear at the top of your sketch.
 
-* **In order to buy Gray, please [Click here](https://shop.m5stack.com/products/grey-development-core)**
+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)
 
-* **In order to buy Basic, please [Click here](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-6)**
+Additional optional include files:
+- `M5Faces.h` for access to M5Stack Faces accessories (EOL)
+- `LoRaWan.h`
 
-*We have several master M5Cores with different configurations, this is the difference between them [Compared](https://docs.m5stack.com/en/products_selector).*
+<img src="https://static-cdn.m5stack.com/resource/docs/static/assets/img/product_pics/core/basic/basic_01.webp" alt="basic" width="350" height="350"><img src="https://static-cdn.m5stack.com/resource/docs/static/assets/img/product_pics/core/gray/gray_01.webp" alt="gray" width="350" height="350">
 
-### M-BUS
-![image](docs/M-BUS.jpg)
+* **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)**
 
-## More Information
+* **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)**
 
-**UIFlow Quick Start**: [Click Here](https://docs.m5stack.com/zh_CN/quick_start/m5core/uiflow)
+*[Comparison of M5Stack controllers](https://docs.m5stack.com/en/products_selector)*
+
+### M-BUS
+<img src="docs/M-BUS.jpg" width="300" />
 
-**MicroPython API**: [Click Here](https://docs.m5stack.com/zh_CN/mpy/display/m5stack_lvgl)
+## More Information
 
-**Arduino IDE Development**: [Click Here](https://docs.m5stack.com/zh_CN/quick_start/m5core/arduino)
+**UIFlow Quick Start**: [Click Here](https://docs.m5stack.com/en/quick_start/m5core/uiflow)
 
-**M5StickC Arduino API**: [Click Here](https://docs.m5stack.com/zh_CN/api/system)
+**MicroPython API**: [Click Here](https://docs.m5stack.com/en/mpy/display/m5stack_lvgl)
 
-**Gray PinMap**: [Click Here](https://docs.m5stack.com/zh_CN/core/gray)
+**Arduino IDE Development**: [Click Here](https://docs.m5stack.com/en/quick_start/m5core/arduino)
 
-**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
 
 * [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)
@@ -53,15 +65,13 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_starte
 
 * [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
 
@@ -81,7 +91,7 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_starte
 
 * [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
 

diff --git a/docs/Power_capabilities.md b/docs/Power_capabilities.md
@@ -0,0 +1,36 @@
+## 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 via M5.Power, which is implemented in
+`src/utility/Power.h` and `src/utility/Power.cpp`, and becomes available 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?** 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 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 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)
+- **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/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 PORT_A -- if done before the shutdown_8s time expires*
diff --git 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));