diff --git a/docs/en/case.md b/docs/en/case.md index 43eea0cd..fee23e96 100644 --- a/docs/en/case.md +++ b/docs/en/case.md @@ -71,3 +71,5 @@ * [m5stack-onscreen-keyboard](https://github.com/yellowelise/m5stack-onscreen-keyboard) - Full size qwerty keyboard for M5Stack * [gui for m5stack by micropython](https://github.com/lifedebug/m5stack) - gui for m5stack by micropython + +* [M5Stack-Tetris-using-RCWController](https://github.com/PartsandCircuits/M5Stack-Tetris-using-RCWController) - Play Tetris on an M5Stack using the RCWController iPhone app to control the action. \ No newline at end of file diff --git a/docs/sidebar.md b/docs/sidebar.md index 7bd8d33f..4c8729dc 100644 --- a/docs/sidebar.md +++ b/docs/sidebar.md @@ -1,5 +1,5 @@ - [Product Documents](en/) -- [API Reference](en/api) +- [API For Arduino](en/api) - [M5Stack Cases](en/case) - [Related Documents](en/related_documents) - [FAQ](en/faq) diff --git a/docs/zh_CN/api.md b/docs/zh_CN/api.md index 4ba69a53..4ca78384 100644 --- a/docs/zh_CN/api.md +++ b/docs/zh_CN/api.md @@ -1,8 +1,20 @@ -# API参考 {docsify-ignore-all} +# Arduino API {docsify-ignore-all} + +## M5Core ||| |:---:|:---:| -|**[LCD](zh_CN/api/lcd)** | **[Speaker](zh_CN/api/speaker)** | +|**[System](zh_CN/api/system)** | **[喇叭](zh_CN/api/speaker)** | +|**[LCD 屏幕](zh_CN/api/lcd)** | **[按键](zh_CN/api/button)** | +|**[姿态传感器 (MPU9250)](zh_CN/api/mpu9250)** | **[TF 卡](zh_CN/api/tf)** | + + diff --git a/docs/zh_CN/api/button.md b/docs/zh_CN/api/button.md index ea94577e..4a80a940 100644 --- a/docs/zh_CN/api/button.md +++ b/docs/zh_CN/api/button.md @@ -1,6 +1,31 @@ # 按键 -### isPressed() +## read() + +**函数原型：** + +read(); // for arduino + + + +**功能：返回按键状态。1：按下；0：松开。** + +**例程** +```arduino +#include + +void setup(){ + M5.begin(); +} + +void loop(){ + Serial.print("Button A Status: "); + Serial.println(M5.BtnA.read()); + delay(200); +} +``` + +## isPressed() **函数原型：** @@ -26,7 +51,7 @@ void loop(){ } ``` -### wasPressed() +## wasPressed() **函数原型：** @@ -62,7 +87,7 @@ lcd.fillScreen(lcd.RED) * * * -### pressedFor() +## pressedFor() **函数原型：** diff --git a/docs/zh_CN/api/lcd.md b/docs/zh_CN/api/lcd.md index 0e7b5916..e6b0f39c 100644 --- a/docs/zh_CN/api/lcd.md +++ b/docs/zh_CN/api/lcd.md @@ -2,7 +2,7 @@ *屏幕像素为 320x240，以屏幕左上角为原点 (0,0)* -### fillScreen() +## fillScreen() **函数原型：** @@ -34,7 +34,7 @@ lcd.fillScreen(lcd.RED) * * * - - -### setTextColor() + +## setTextColor() **函数原型：** @@ -91,7 +91,7 @@ lcd.setTextColor(lcd.ORANGE, lcd.DARKCYAN) * * * -### setCursor() +## setCursor() **函数原型：** @@ -120,7 +120,7 @@ lcd.drawPixel(22,22,lcd.RED) * * * -### drawPixel() +## drawPixel() **函数原型：** @@ -152,7 +152,7 @@ lcd.drawPixel(22,22,lcd.RED) * * * -### drawLine() +## drawLine() **函数原型：** @@ -184,7 +184,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * -### drawTriangle() +## drawTriangle() **函数原型：** @@ -216,7 +216,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * -### fillTriangle() +## fillTriangle() **函数原型：** @@ -248,7 +248,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * -### drawRect() +## drawRect() **函数原型：** @@ -282,7 +282,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * -### fillRect() +## fillRect() **函数原型：** @@ -317,7 +317,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * -### drawRoundRect() +## drawRoundRect() **函数原型：** @@ -352,7 +352,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * -### print() +## print() **函数原型：** @@ -380,7 +380,7 @@ lcd.drawLine(0,0,12,12,lcd.WHITE) * * * - -### Usage {docsify-ignore} +## Usage {docsify-ignore} ```arduino #include diff --git a/docs/zh_CN/api/mpu9250.md b/docs/zh_CN/api/mpu9250.md new file mode 100644 index 00000000..73caf021 --- /dev/null +++ b/docs/zh_CN/api/mpu9250.md @@ -0,0 +1,253 @@ +# 姿态传感器 MPU9250 + +*姿态传感器 MPU9250 是一款多芯片模块，集成两个芯片，一个芯片是 MPU6500，由 3 轴陀螺仪和 3 轴加速度计组成，另外一个是 AK8963 是 3 轴磁力计。* + +## initMPU9250() + +**函数原型：** + +void initMPU9250(); + + + +**功能：初始化 MPU6500 芯片。** + +**例程：** +```arduino +#include +#include "utility/MPU9250.h" + +MPU9250 IMU; // new a MPU9250 object + +void setup(){ + M5.begin(); + + IMU.initMPU9250(); + byte c = IMU.readByte(MPU9250_ADDRESS, WHO_AM_I_MPU9250); + Serial.print("MPU9250 "); Serial.print("I AM "); Serial.print(c, HEX); +} +``` + +## initAK8963() + +**函数原型：** + +void initAK8963(float * destination); + + + +**功能：初始化 AK8963 芯片。** + +| 参数 | 描述 | +| --- | --- | +| destination | 出厂预设于 AK8963 芯片内缺省值的数组指针 | + +**例程：** +```arduino +#include +#include "utility/MPU9250.h" + +MPU9250 IMU; // new a MPU9250 object + +void setup(){ + M5.begin(); + + // "magCalibration[3] = {0};" was defined at file "MPU9250.h" + IMU.initAK8963(IMU.magCalibration); + Serial.println("AK8963 initialized for active data mode...."); + if (Serial) + { + // Serial.println("Calibration values: "); + Serial.print("X-Axis sensitivity adjustment value "); + Serial.println(IMU.magCalibration[0], 2); + Serial.print("Y-Axis sensitivity adjustment value "); + Serial.println(IMU.magCalibration[1], 2); + Serial.print("Z-Axis sensitivity adjustment value "); + Serial.println(IMU.magCalibration[2], 2); + } +} +``` + +## calibrateMPU9250() + +**函数原型：** + +void calibrateMPU9250(float * gyroBias, float * accelBias); + + + +**功能：初始化芯片后，执行该函数以读取静止状态下的陀螺仪和加速度值偏移，并保存到各自的偏移寄存器。** + +| 参数 | 描述 | +| --- | --- | +| gyroBias | 保存静止下陀螺仪值的数组的地址 | +| accelBias | 保存静止下加速度值的数组的地址 | + +**例程：** +```arduino +#include +#include "utility/MPU9250.h" + +MPU9250 IMU; // new a MPU9250 object + +void setup(){ + M5.begin(); + + IMU.initMPU9250(); + byte c = IMU.readByte(MPU9250_ADDRESS, WHO_AM_I_MPU9250); + Serial.print("MPU9250 "); Serial.print("I AM "); Serial.print(c, HEX); + // "gyroBias[3] = {0};" was defined at file "MPU9250.h" + // "accelBias[3] = {0};" was defined at file "MPU9250.h" + IMU.calibrateMPU9250(IMU.gyroBias, IMU.accelBias); + M5.Lcd.fillScreen(BLACK); + M5.Lcd.setTextSize(1); + M5.Lcd.setCursor(0, 0); M5.Lcd.print("MPU9250 bias"); + M5.Lcd.setCursor(0, 16); M5.Lcd.print(" x y z "); + + M5.Lcd.setCursor(0, 32); M5.Lcd.print((int)(1000*IMU.accelBias[0])); + M5.Lcd.setCursor(32, 32); M5.Lcd.print((int)(1000*IMU.accelBias[1])); + M5.Lcd.setCursor(64, 32); M5.Lcd.print((int)(1000*IMU.accelBias[2])); + M5.Lcd.setCursor(96, 32); M5.Lcd.print("mg"); + + M5.Lcd.setCursor(0, 48); M5.Lcd.print(IMU.gyroBias[0], 1); + M5.Lcd.setCursor(32, 48); M5.Lcd.print(IMU.gyroBias[1], 1); + M5.Lcd.setCursor(64, 48); M5.Lcd.print(IMU.gyroBias[2], 1); + M5.Lcd.setCursor(96, 48); M5.Lcd.print("o/s"); +} + +void loop(){ + +} +``` + +## readByte() + +**函数原型：** + +uint8_t readByte(uint8_t address, uint8_t subAddress); + + + +**功能：读取指定寄存器内数据。返回值：寄存器值，长度为8 位。** + +| 参数 | 描述 | +| --- | --- | +| address | 芯片 (MPU9250/AK8963)地址 | +| subAddress | 芯片内寄存器地址 | + +**例程：** +```arduino +#include +#include "utility/MPU9250.h" + +MPU9250 IMU; // new a MPU9250 object + +void setup(){ + M5.begin(); + + byte c = IMU.readByte(MPU9250_ADDRESS, WHO_AM_I_MPU9250); + Serial.print("MPU9250 "); Serial.print("I AM "); Serial.print(c, HEX); +} +``` + +## readGyroData() + +**函数原型：** + +void readGyroData(int16_t * destination); + + + +**功能：读取三个方向的陀螺仪值。** + +| 参数 | 描述 | +| --- | --- | +| destination | 保存陀螺仪值的数组的地址 | + +**例程：** +```arduino +#include +#include "utility/MPU9250.h" + +MPU9250 IMU; // new a MPU9250 object + +void setup(){ + M5.begin(); + + IMU.initMPU9250(); + byte c = IMU.readByte(MPU9250_ADDRESS, WHO_AM_I_MPU9250); + Serial.print("MPU9250 "); Serial.print("I AM "); Serial.print(c, HEX); + IMU.calibrateMPU9250(IMU.gyroBias, IMU.accelBias); +} + +void loop(){ + // If intPin goes high, all data registers have new data + // On interrupt, check if data ready interrupt + if (IMU.readByte(MPU9250_ADDRESS, INT_STATUS) & 0x01) + { + // "gyroCount[3] = {0};" was defined at file "MPU9250.h" + IMU.readGyroData(IMU.gyroCount); // Read the x/y/z adc values + IMU.getGres(); // get Gyro scales saved to "gRes" + IMU.gx = (float)IMU.gyroCount[0]*IMU.gRes; + IMU.gy = (float)IMU.gyroCount[1]*IMU.gRes; + IMU.gz = (float)IMU.gyroCount[2]*IMU.gRes; + Serial.print("X-gyro rate: "); Serial.print(IMU.gx, 3); + Serial.print(" degrees/sec "); + Serial.print("Y-gyro rate: "); Serial.print(IMU.gy, 3); + Serial.print(" degrees/sec "); + Serial.print("Z-gyro rate: "); Serial.print(IMU.gz, 3); + Serial.println(" degrees/sec"); + } +} +``` + +## readAccelData() + +**函数原型：** + +void readAccelData(int16_t * destination); + + + +**功能：读取三个方向的加速度值。** + +| 参数 | 描述 | +| --- | --- | +| destination | 保存加速度值的数组的地址 | + +**例程：** +```arduino +#include +#include "utility/MPU9250.h" + +MPU9250 IMU; // new a MPU9250 object + +void setup(){ + M5.begin(); + + IMU.initMPU9250(); + byte c = IMU.readByte(MPU9250_ADDRESS, WHO_AM_I_MPU9250); + Serial.print("MPU9250 "); Serial.print("I AM "); Serial.print(c, HEX); + IMU.calibrateMPU9250(IMU.gyroBias, IMU.accelBias); +} + +void loop(){ + // If intPin goes high, all data registers have new data + // On interrupt, check if data ready interrupt + if (IMU.readByte(MPU9250_ADDRESS, INT_STATUS) & 0x01) + { + // "accelCount[3] = {0};" was defined at file "MPU9250.h" + IMU.readAccelData(IMU.accelCount); + IMU.getAres(); // get accelerometer scales saved to "aRes" + IMU.ax = (float)IMU.accelCount[0]*IMU.aRes; // - accelBias[0]; + IMU.ay = (float)IMU.accelCount[1]*IMU.aRes; // - accelBias[1]; + IMU.az = (float)IMU.accelCount[2]*IMU.aRes; // - accelBias[2]; + Serial.print("X-acceleration: "); Serial.print(1000*IMU.ax); + Serial.print(" mg "); + Serial.print("Y-acceleration: "); Serial.print(1000*IMU.ay); + Serial.print(" mg "); + Serial.print("Z-acceleration: "); Serial.print(1000*IMU.az); + Serial.println(" mg "); + } +} +``` \ No newline at end of file diff --git a/docs/zh_CN/api/speaker.md b/docs/zh_CN/api/speaker.md index e825fc9e..2fc85909 100644 --- a/docs/zh_CN/api/speaker.md +++ b/docs/zh_CN/api/speaker.md @@ -14,7 +14,7 @@ M5.Speaker.tone(100); ``` --> -### tone() +## tone() **函数原型：** @@ -40,10 +40,3 @@ M5.begin(); M5.Speaker.tone(900, 1000); ``` - \ No newline at end of file diff --git a/docs/zh_CN/api/system.md b/docs/zh_CN/api/system.md new file mode 100644 index 00000000..487c7967 --- /dev/null +++ b/docs/zh_CN/api/system.md @@ -0,0 +1,130 @@ +# 系统函数 + +## begin() + +**函数原型：** + +void begin(bool LCDEnable=true, bool SDEnable=true, bool SerialEnable=true); + + + +**功能：清串口缓冲区，设置串口波特率为 115200；初始化 LCD；初始化 SD 卡；设置按键 A 是睡眠唤醒按键。** + +**函数实现** +```arduino +void M5Stack::begin(bool LCDEnable, bool SDEnable, bool SerialEnable) { + if (isInited) return; + else isInited = true; + if (SerialEnable) { + Serial.begin(115200); + Serial.flush(); + delay(50); + Serial.print("M5Stack initializing..."); + } + if (LCDEnable) { + Lcd.begin(); + } + if (SDEnable) { + SD.begin(TFCARD_CS_PIN, SPI, 40000000); + } + setWakeupButton(BUTTON_A_PIN); +} +``` + +**例程** +```arduino +#include + +void setup(){ + M5.begin(); +} +``` + +## update() + +**函数原型：** + +void update(); + + + +**功能：读取按键 A, B, C 的状态。** + +**函数实现** +```arduino +void M5Stack::update() { + + //Button update + BtnA.read(); + BtnB.read(); + BtnC.read(); + + //Speaker update + Speaker.update(); +} +``` + +**例程** +```arduino +#include + +void setup(){ + M5.begin(); +} + +void loop(){ + M5.update(); +} +``` + +## powerOFF() + +**函数原型：** + +void powerOFF(); + + + +**功能：系统进入深度睡眠状态。** + +**函数实现** +```arduino +void M5Stack::powerOFF() { + + #ifdef M5STACK_FIRE + // Keep power keep boost on + setPowerBoostKeepOn(true); + #endif + + // power off the Lcd + Lcd.setBrightness(0); + Lcd.sleep(); + + // ESP32 into deep sleep + esp_sleep_enable_ext0_wakeup((gpio_num_t)_wakeupPin , LOW); + + while(digitalRead(_wakeupPin) == LOW) { + delay(10); + } + esp_deep_sleep_start(); +} +``` + +**例程** +```arduino +#include + +void setup(){ + M5.begin(); + M5.Lcd.println("This is software power off demo"); + M5.Lcd.println("Press the button A to power off."); + M5.setWakeupButton(BUTTON_A_PIN); +} + +void loop() { + if(M5.BtnA.wasPressed()) { + M5.powerOFF(); + } + M5.update(); +} +``` \ No newline at end of file diff --git a/docs/zh_CN/api/tf.md b/docs/zh_CN/api/tf.md new file mode 100644 index 00000000..7ae72903 --- /dev/null +++ b/docs/zh_CN/api/tf.md @@ -0,0 +1,25 @@ +# TF 卡 + +## begin() + +**函数原型：** + +begin(); + +**功能：喇叭响指定频率的声音持续指定时间。** + +| 参数 | 描述 | +| --- | --- | +| freq | 声音频率 | +| duration | 持续时间 (单位：毫秒) | + + + +**例程** +```arduino +#include + +M5.begin(); + +M5.Speaker.tone(900, 1000); +``` diff --git a/docs/zh_CN/case.md b/docs/zh_CN/case.md index f5caa3c7..9e052eb8 100644 --- a/docs/zh_CN/case.md +++ b/docs/zh_CN/case.md @@ -68,4 +68,6 @@ * [m5stack-onscreen-keyboard](https://github.com/yellowelise/m5stack-onscreen-keyboard) - Full size qwerty keyboard for M5Stack -* [gui for m5stack by micropython](https://github.com/lifedebug/m5stack) - gui for m5stack by micropython \ No newline at end of file +* [gui for m5stack by micropython](https://github.com/lifedebug/m5stack) - gui for m5stack by micropython + +* [M5Stack-Tetris-using-RCWController](https://github.com/PartsandCircuits/M5Stack-Tetris-using-RCWController) - Play Tetris on an M5Stack using the RCWController iPhone app to control the action. \ No newline at end of file diff --git a/docs/zh_CN/sidebar.md b/docs/zh_CN/sidebar.md index f6b18899..1845d45e 100644 --- a/docs/zh_CN/sidebar.md +++ b/docs/zh_CN/sidebar.md @@ -1,5 +1,5 @@ - [产品介绍](zh_CN/) -- [API 参考](zh_CN/api) +- [Arduino API](zh_CN/api) - [M5Stack 案例](zh_CN/case) - [相关文档](zh_CN/related_documents) - [常见问题解答](zh_CN/faq)