diff --git a/README.md b/README.md index ee1b06c..36c89e6 100644 --- a/README.md +++ b/README.md @@ -5,46 +5,58 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md) -gray +The M5Stack library provides access to the built-in hardware of the M5Stack Core (including Basic and Gray) controllers. -basic +## 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.** -* **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).* +basicgray + +* **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)**. 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)** + +*[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 * [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 new file mode 100644 index 0000000..a513606 --- /dev/null +++ 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 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));