mirror of
https://github.com/m5stack/M5Stack.git
synced 2026-05-20 10:06:46 -07:00
Significant changes to README.md and M5Stack.h to benefit new users
Significant changes to README.md and M5Stack.h to benefit new users
This commit is contained in:
Tinyu
@@ -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">
|
||||
|
||||
* **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
|
||||
|
||||
<img src="docs/M-BUS.jpg" width="300" />
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@@ -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*
|
||||
+31
-27
@@ -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));
|
||||
|
||||
Reference in New Issue
Block a user