Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit c4607cd

Browse files
Tinyu-ZhaoTinyu-Zhao
authoredJun 20, 2024
Significant changes to README.md and M5Stack.h to benefit new users
Significant changes to README.md and M5Stack.h to benefit new users
2 parents 2feddca + 7a52ed1 commit c4607cd

File tree

3 files changed

+100
-50
lines changed

3 files changed

+100
-50
lines changed
 

‎README.md

+33-23
Original file line numberDiff line numberDiff line change
@@ -5,46 +5,58 @@
55

66
English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_started_ja.md)
77

8-
<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">
8+
The M5Stack library provides access to the built-in hardware of the M5Stack Core (including Basic and Gray) controllers.
99

10-
<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">
10+
## Recommendation
11+
**<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>**
1112

12-
* **For the Detailed documentation of Gray, please [Click here](https://docs.m5stack.com/en/core/gray)**
13+
## Usage
14+
This library's functionality is available through the M5Stack class, referenced as `M5`, including:
15+
- 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.
16+
- Power control, including device shutoff and battery level detection via `M5.Power` and the IP5306 power management chip
17+
- Hardware buttons via `M5.BtnA`, `M5.BtnB`, `M5.BtnC`
18+
- Speaker, via `M5.Speaker`, supporting tones, volume control, and basic wave audio playback using ESP32's DAC function
19+
- Accelerometer, via `M5.Imu`, `M5.Mpu6886`, or `M5.Sh200Q` (accelerometer type depends on version of Basic/Gray)
1320

14-
* **For the Detailed documentation of Basic, please [Click here](https://docs.m5stack.com/en/core/basic_v2.6)**
21+
To use the M5Stack library, `#include "M5Stack.h"` must appear at the top of your sketch.
1522

16-
* **In order to buy Gray, please [Click here](https://shop.m5stack.com/products/grey-development-core)**
23+
The most productive way to become acquainted with the class is through the numerous included examples. Additional documentation within this library:
24+
- [docs/Power_capabilities.md](docs/Power_capabilities.md)
1725

18-
* **In order to buy Basic, please [Click here](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-6)**
26+
Additional optional include files:
27+
- `M5Faces.h` for access to M5Stack Faces accessories (EOL)
28+
- `LoRaWan.h`
1929

20-
*We have several master M5Cores with different configurations, this is the difference between them [Compared](https://docs.m5stack.com/en/products_selector).*
30+
<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">
2131

22-
### M-BUS
23-
![image](docs/M-BUS.jpg)
32+
* **Hardware documentation for [Gray v1.0 (EOL)](https://docs.m5stack.com/en/core/gray)**
2433

25-
## More Information
34+
* **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.
35+
36+
* **[Buy Basic](https://shop.m5stack.com/products/esp32-basic-core-iot-development-kit-v2-7)**
2637

27-
**UIFlow Quick Start**: [Click Here](https://docs.m5stack.com/zh_CN/quick_start/m5core/uiflow)
38+
*[Comparison of M5Stack controllers](https://docs.m5stack.com/en/products_selector)*
39+
40+
### M-BUS
41+
<img src="docs/M-BUS.jpg" width="300" />
2842

29-
**MicroPython API**: [Click Here](https://docs.m5stack.com/zh_CN/mpy/display/m5stack_lvgl)
43+
## More Information
3044

31-
**Arduino IDE Development**: [Click Here](https://docs.m5stack.com/zh_CN/quick_start/m5core/arduino)
45+
**UIFlow Quick Start**: [Click Here](https://docs.m5stack.com/en/quick_start/m5core/uiflow)
3246

33-
**M5StickC Arduino API**: [Click Here](https://docs.m5stack.com/zh_CN/api/system)
47+
**MicroPython API**: [Click Here](https://docs.m5stack.com/en/mpy/display/m5stack_lvgl)
3448

35-
**Gray PinMap**: [Click Here](https://docs.m5stack.com/zh_CN/core/gray)
49+
**Arduino IDE Development**: [Click Here](https://docs.m5stack.com/en/quick_start/m5core/arduino)
3650

37-
**Basic PinMap**: [Click Here](https://docs.m5stack.com/zh_CN/core/basic)
51+
**Gray PinMap**: [Click Here](https://docs.m5stack.com/en/core/gray)
3852

53+
**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)**
3954

4055
## USER CASES
4156

4257
* [M5Stack-SD-Updater](https://github.com/tobozo/M5Stack-SD-Updater) - Customizable menu system for M5Stack - loads apps from the Micro SD
4358
card
4459

45-
* [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) - TFT library for the ESP8266 and ESP32 that supports different driver chips
46-
47-
4860
* [M5StackSAM](https://github.com/tomsuch/M5StackSAM) - Simple Applications Menu Arduino Library for M5Stack
4961

5062
* [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
5365

5466
* [M5ez](https://github.com/M5ez/M5ez) - The easy way to program on the M5Stack
5567

56-
5768
* [M5Stack MultiApp Advanced](https://github.com/botofancalin/M5Stack-MultiApp-Advanced) - A M5Stack firmware made on PlatformIO
5869

59-
6070
* [M5Stack ESP32 Oscilloscope](https://github.com/botofancalin/M5Stack-ESP32-Oscilloscope) - A fully functional oscilloscope based on ESP32 M5Stack
6171

6272
* [M5Stack-Avatar](https://github.com/meganetaaan/m5stack-avatar) - An M5Stack library for rendering avatar faces
6373

64-
* [M5Stack_CrackScreen](https://github.com/nomolk/M5Stack_CrackScreen) - Crack your M5Stack!!
74+
* [M5Stack_CrackScreen](https://github.com/nomolk/M5Stack_CrackScreen) - Crack your M5Stack
6575

6676
* [M5_Shuttle_Run](https://github.com/n0bisuke/M5_Shuttle_Run) - M5_Shuttle_Run
6777

@@ -81,7 +91,7 @@ English | [中文](docs/getting_started_cn.md) | [日本語](docs/getting_starte
8191

8292
* [ArduinoWiFiPhotoBackup](https://github.com/moononournation/ArduinoWiFiPhotoBackup) - M5STACK Arduino WiFi Photo Backup device
8393

84-
* [M5StackHIDCtrlAltDel](https://github.com/mhama/M5StackHIDCtrlAltDel) - You can send ctrl+alt+del to your PC from M5Stack
94+
* [M5StackHIDCtrlAltDel](https://github.com/mhama/M5StackHIDCtrlAltDel) - You can send ctrl+alt+del to your PC via Bluetooth from M5Stack
8595

8696
* [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
8797

‎docs/Power_capabilities.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
## Power management capabilities of M5Stack Core / Basic / Gray
2+
3+
Document v0.1
4+
5+
The power management capabilities are provided by the IP5306 power controller, specifically the IP5306_I2C version of the controller,
6+
that can be accessed on the I2C bus at address 0x75. Access is possible via M5.Power, which is implemented in
7+
`src/utility/Power.h` and `src/utility/Power.cpp`, and becomes available with `#include "M5Stack.h"`.
8+
9+
### Capabilities
10+
11+
- **Can the M5Stack Core turn itself off?** Yes, using `powerOFF()`, which shuts off the LED backlight, the WiFi radio, the
12+
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,
13+
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.
14+
- **Can it wake itself back up after a pre-determined delay or at a specific time?**
15+
No, since it doesn't have a real-time clock chip (RTC), but ESP32 sleep modes may provide a suitable alternative.
16+
- **Can it tell if it is running on external versus battery power?** If `isCharging()` or `isChargeFull()` true, probably on external power.
17+
- **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*
18+
- **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"*
19+
- **Can it tell the state of charge of the battery?** Yes, using `getBatteryLevel()`, which returns one of:
20+
0, 25, 50, 75, 100 (representing a percentage), or -1 (if unable to read)
21+
- **Can it read its battery voltage?** Not possible to read the voltage level directly, only the approximate percentage of 0/25/50/75/100.
22+
- **Can communication with the IP5306 power controller be tested and confirmed?** Yes, with `canControl()`
23+
- **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
24+
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
25+
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,
26+
and will not charge the battery. The IP5306 will shut down under this condition to minimize battery drain, unless configured not to.
27+
When the chip is shut down, it will not respond to I2C communication
28+
(for example, `getBatteryLevel()` will return -1)
29+
- **What other capabilities?** *(to be answered -- translation of Chinese-language datasheet is difficult to understand)*
30+
- *auto shutoff settings - voltage low for how long causes a shutoff*
31+
- *inhibit the power button, report it as an event?*
32+
- *setting the charging voltage and current*
33+
- *distinguish between a software/hardware/watchdog/sleep/poweron reset*
34+
- *maintain any of the settings across power cycles and/or complete loss of all power*
35+
- *how does setAutoBootOnLoad() work? when enabled, it seems the device can be powered back on simply by connecting a load -- such as
36+
connecting another M5Stack controller to be powered from PORT_A -- if done before the shutdown_8s time expires*

‎src/M5Stack.h

+31-27
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
* @brief Header for M5Stack.cpp module
1414
*
1515
* \par Description
16-
* This file is a drive for M5Stack core.
16+
* This file is a driver for M5Stack Core/Basic/Gray.
1717
*
1818
* \par Method List:
1919
*
@@ -37,24 +37,20 @@
3737
LCD:
3838
M5.lcd.setBrightness(uint8_t brightness);
3939
M5.Lcd.drawPixel(int16_t x, int16_t y, uint16_t color);
40-
M5.Lcd.drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t
41-
color); M5.Lcd.fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t
42-
color); M5.Lcd.fillScreen(uint16_t color); M5.Lcd.drawCircle(int16_t x0,
43-
int16_t y0, int16_t r, uint16_t color); M5.Lcd.drawCircleHelper(int16_t x0,
44-
int16_t y0, int16_t r, uint8_t cornername,uint16_t color);
40+
M5.Lcd.drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t color);
41+
M5.Lcd.fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);
42+
M5.Lcd.fillScreen(uint16_t color); M5.Lcd.drawCircle(int16_t x0, int16_t y0, int16_t r, uint16_t color);
43+
M5.Lcd.drawCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t cornername,uint16_t color);
4544
M5.Lcd.fillCircle(int16_t x0, int16_t y0, int16_t r, uint16_t color);
46-
M5.Lcd.fillCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t
47-
cornername,int16_t delta, uint16_t color); M5.Lcd.drawTriangle(int16_t x0,
48-
int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color);
49-
M5.Lcd.fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1,
50-
int16_t x2, int16_t y2, uint16_t color); M5.Lcd.drawRoundRect(int16_t x0,
51-
int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color);
52-
M5.Lcd.fillRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h,
53-
int16_t radius, uint16_t color); M5.Lcd.drawBitmap(int16_t x, int16_t y, const
54-
uint8_t bitmap[], int16_t w, int16_t h, uint16_t color);
55-
M5.Lcd.drawRGBBitmap(int16_t x, int16_t y, const uint16_t bitmap[],
56-
int16_t w, int16_t h), M5.Lcd.drawChar(uint16_t x, uint16_t y, char c, uint16_t
57-
color, uint16_t bg, uint8_t size); M5.Lcd.setCursor(uint16_t x0, uint16_t y0);
45+
M5.Lcd.fillCircleHelper(int16_t x0, int16_t y0, int16_t r, uint8_t cornername,int16_t delta, uint16_t color);
46+
M5.Lcd.drawTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color);
47+
M5.Lcd.fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint16_t color);
48+
M5.Lcd.drawRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color);
49+
M5.Lcd.fillRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint16_t color);
50+
M5.Lcd.drawBitmap(int16_t x, int16_t y, const uint8_t bitmap[], int16_t w, int16_t h, uint16_t color);
51+
M5.Lcd.drawRGBBitmap(int16_t x, int16_t y, const uint16_t bitmap[], int16_t w, int16_t h),
52+
M5.Lcd.drawChar(uint16_t x, uint16_t y, char c, uint16_t color, uint16_t bg, uint8_t size);
53+
M5.Lcd.setCursor(uint16_t x0, uint16_t y0);
5854
M5.Lcd.setTextColor(uint16_t color);
5955
M5.Lcd.setTextColor(uint16_t color, uint16_t backgroundcolor);
6056
M5.Lcd.setTextSize(uint8_t size);
@@ -64,13 +60,12 @@
6460
M5.Lcd.println();
6561
M5.Lcd.drawCentreString(const char *string, int dX, int poY, int font);
6662
M5.Lcd.drawRightString(const char *string, int dX, int poY, int font);
67-
M5.Lcd.drawJpg(const uint8_t *jpg_data, size_t jpg_len, uint16_t x,
68-
uint16_t y); M5.Lcd.drawJpgFile(fs::FS &fs, const char *path, uint16_t x,
69-
uint16_t y); M5.Lcd.drawBmpFile(fs::FS &fs, const char *path, uint16_t x,
70-
uint16_t y);
63+
M5.Lcd.drawJpg(const uint8_t *jpg_data, size_t jpg_len, uint16_t x, uint16_t y);
64+
M5.Lcd.drawJpgFile(fs::FS &fs, const char *path, uint16_t x, uint16_t y);
65+
M5.Lcd.drawBmpFile(fs::FS &fs, const char *path, uint16_t x, uint16_t y);
7166
7267
Button:
73-
M5.BtnA/B/C.read();
68+
M5.BtnA/B/C.read(); // Must be called in loop(), or via update()
7469
M5.BtnA/B/C.isPressed();
7570
M5.BtnA/B/C.isReleased();
7671
M5.BtnA/B/C.wasPressed();
@@ -125,21 +120,30 @@ class M5Stack {
125120
M5Stack();
126121
void begin(bool LCDEnable = true, bool SDEnable = true,
127122
bool SerialEnable = true, bool I2CEnable = false);
123+
124+
// Updates the status of hardware buttons, and ends any completed tone on the speaker.
125+
// Recommended to be placed in loop()
128126
void update();
129127

130-
// LCD
128+
// LCD display, derived from TFT_eSPI. See examples
131129
M5Display Lcd = M5Display();
132130

133-
// Power
131+
// Power and battery charge control. Call Power.begin() in setup().
134132
POWER Power;
135133

136134
// Button API
137135
#define DEBOUNCE_MS 10
136+
137+
// Hardware button A. Call read() before checking if isPressed()
138138
Button BtnA = Button(BUTTON_A_PIN, true, DEBOUNCE_MS);
139+
140+
// Hardware button B. Call read() before checking if isPressed()
139141
Button BtnB = Button(BUTTON_B_PIN, true, DEBOUNCE_MS);
142+
143+
// Hardware button C. Call read() before checking if isPressed()
140144
Button BtnC = Button(BUTTON_C_PIN, true, DEBOUNCE_MS);
141145

142-
// SPEAKER
146+
// SPEAKER on DAC pin 25
143147
SPEAKER Speaker;
144148

145149
// UART
@@ -154,7 +158,7 @@ class M5Stack {
154158
SH200Q Sh200Q;
155159

156160
/**
157-
* Function has been move to Power class.(for compatibility)
161+
* Function has been moved to Power class (for compatibility)
158162
* This name will be removed in a future release.
159163
*/
160164
void setPowerBoostKeepOn(bool en) __attribute__((deprecated));

0 commit comments

Comments
 (0)
Failed to load comments.