Merge pull request #6 from m5stack/dev-readthedocs

Dev readthedocs
2026-05-20 10:23:01 -07:00 · 2018-09-19 11:50:36 +08:00
parent 0a1c8285a3 5ccfd37a08
commit e71b6a3818
10 changed files with 587 additions and 5 deletions
@@ -0,0 +1,17 @@
+# M5GO Thermal Unit User Guide
+
+## 1. Burn Demo Firmware
+
+Burn the Demo Firmware via M5Burner for verifying this unit.
+(This firmware is just a verification firmware)
+
+1. Connect your board with PC.Choice your serial port, baudrate and the firwmare named `M5GO-Unit-ThermalCam` and then click `Erase` as shown below. 
+
+![image](../../_static/screenshots/download_m5go_thermal_firmware_01.png)
+
+
+2. Then click `Burn` to burn the firmware.
+
+![image](../../_static/screenshots/download_m5go_thermal_firmware_02.png)
+
+Onece it shows `Staying in bootloader`, reset your M5GO Core.
@@ -0,0 +1,102 @@
+# M5Stack-Core Get Started(macOS, Arudino)
+
+### CONTENT
+
+1. [Setting Environment](#setting-environment)
+
+    - [1. Install Arduino IDE](#1-install-arduino-ide)
+
+    - [2. ESP32 Board Support](#2-esp32-board-support)
+
+    - [3. Install M5Stack Lib](#3-install-m5stack-lib)
+
+2. [Example](#example)
+
+### Setting Environment
+
+*Before setting the development environment, we suggest you confirm whether the USB driver has installed. If not, please visit this link `establish serial connection`.* TODO: add a link
+
+#### 1. Install `Arduino IDE`
+
+First, if Arudino IDE is not installed, install it. It's *download address* is 
+https://www.arduino.cc/en/Main/Software 
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_download_arduino_ide.png)
+
+
+#### 2. ESP32 Board Support
+
+Open Terminal and execute the following command (copy->paste and hit enter):
+
+```
+
+mkdir -p ~/Documents/Arduino/hardware/espressif && \
+cd ~/Documents/Arduino/hardware/espressif && \
+git clone https://github.com/espressif/arduino-esp32.git esp32 && \
+cd esp32 && \
+git submodule update --init --recursive && \
+cd tools && \
+python get.py
+
+```
+
+Where ~/Documents/Arduino represents your sketch book location as per "Arduino" > "Preferences" > "Sketchbook location" (in the IDE once started). Adjust the command above accordingly if necessary!
+
+**Note:**
+If you get the error below: `xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun`, install the command line dev tools with `xcode-select --install` and try the command above again and restart Arduino IDE.
+
+If you get the error: `IOError: [Errno socket error] [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590) when running python get.py`, try `python3` instead of `python` and restart Arduino IDE.
+
+
+
+#### 3. Install M5Stack Lib
+
+Start up Arduino IDE, then Select `Sketch`->`Include Library`->`Manage Libraries...`
+Type `M5Stack` into the search box, search it and install.
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_install_m5stack_lib.png)
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_search_m5stack.png)
+
+
+### Example
+
+The USB cable connects to M5Stack Core, then select your serial port which is connected M5Stack Core.
+Select a demo example, compile and upload
+
+#### 1. Select your board and the serial port
+
+Start up Arduino IDE, and click `Tools -> Boards -> M5Stack-Core-ESP32` to select your board
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_select_board.png)
+
+Click `Tools -> Ports ->` to select the serial port which is connected with M5Stack Core
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_select_serial_port.png)
+
+### 2. Select an example
+
+Click `File-> Examples`. Here are some test programs in `M5Stack->`
+
+Try to open a sketch called `HelloWorld` inside Basics.
+
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_select_example.png)
+
+
+Compile it and upload, the M5Stack screen will show "Hello World!"
+
+![image](../../_static/getting_started_pics/m5stack_core/display_hello_world.png)
+
+
+### Note
+
+Although there was no problem in my environment, sometimes Slab_USBtoUART does not appear in some cases.
+In this case, open `security and privacy` in the system preferences and set it to `permit`.
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_security_and_privacy.png)
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_security_and_privacy_01.png)
+
+![image](../../_static/getting_started_pics/m5stack_core/macOS_security_and_privacy_02.png)
+
@@ -0,0 +1,132 @@
+# M5Stack-Core-Arduino —— Getting Started
+
+
+## 一、安装 USB 驱动
+
+点击以下链接，下载 M5Stack-Core 的 USB 转串口驱动
+
+https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers
+
+下载完之后，解压，根据系统位数，双击对应可执行文件
+
+(Windows 32位，执行 CP210xVCPInstaller_x68.exe；Windows 64位，执行 CP210xVCPInstaller_x64.exe；)
+
+*判断驱动安装是否成功：*
+如果安装成功，在插入 M5Stack 主控之后，设备管理器如下图所示出现，Silicon Labs 的 CP21x 系列串口端口号
+(我的电脑当前串口号是 COM3)
+
+![image](screenshots/my_com.png)
+
+
+## 二、开发环境
+## **Windows**
+### 1、安装 Arduino IDE
+
+*下载地址*
+https://www.arduino.cc/en/Main/Software 
+
+![image](screenshots/arduino_cc_package.png)
+
+
+如下图所示修改 Arduino 路径为 D:\Program Files
+
+![image](screenshots/select_arduino_install_path.png)
+
+
+此时，Arduino 的安装路径为 D:\Program Files\Arduino
+
+![image](screenshots/arduino_path.png)
+
+
+### 2、下载 ESP32 相关支持包
+
+（我的 Arduino 当前路径是 D:\Program Files\arduino）
+
+进入 Arduino 安装路径的 hareware 文件夹，按住 Shift 键的同时，右键选择“在此处打开命令窗口”
+
+
+在打开的 Windows 终端 CMD 中输入如下命令
+
+> * 创建 espressif 目录，并切换到此目录下
+
+mkdir espressif && cd espressif
+
+![image](screenshots/mkdir_espressif.png)
+
+
+> * 将 esp32 idf clone 在文件夹 esp32 下
+
+git clone --recursive https://github.com/espressif/arduino-esp32.git esp32
+
+![image](screenshots/download_idf.png)
+
+
+
+### 3、下载 ESP32 编译链 tools
+
+进入此路径 D:\Program Files\arduino\hardware\espressif\esp32\tools
+选中并双击执行 get.exe 文件
+
+![image](screenshots/select_get_exe_file.png)
+
+![image](screenshots/download_xtensa_tools.png)
+
+
+### 4、Arduino IDE 中下载 M5Stack 的库
+
+打开 Arduino IDE 之后，选择“项目”->“加载库”->“管理库...”，搜索“M5Stack”并点击“安装”
+
+![image](screenshots/select_arduino_lib.png)
+
+![image](screenshots/download_m5stack_lib.png)
+
+
+## 三、示例
+
+USB 线连接 M5Stack 主控，选择串口和一个示例程序，compile and upload
+
+### 1、打开一个示例程序，如打开 FactoryTest.ino
+
+![image](screenshots/select_demo.png)
+
+
+
+确认连接板子名称、串口波特率和当前串口号分别：M5Stack-Core-ESP32、921600、COM3(当前电脑串口号)
+
+![image](screenshots/select_board_and_com.png)
+
+
+编译运行成功之后，串口监视窗口显示如下
+
+
+![image](screenshots/FactoryTest_result.png)
+
+### 2、新建一个 M5Stack 程序
+
+打开 Arduino IDE 之后，新建 .ino 文件，并保存为 my_test.ino
+
+将如下代码拷贝进文件中。
+
+```cpp
+#include <M5Stack.h>
+
+// the setup routine runs once when M5Stack starts up
+void setup(){tack
+
+  // Initialize the M5Stack object
+  M5.begin();
+
+  // LCD display
+  M5.Lcd.print("Hello World!");
+  M5.Lcd.print("M5Stack is running successfully!");    
+}
+
+// the loop routine runs over and over again forever
+void loop() {
+
+}
+```
+
+点击编译运行，此时 M5Stack 显示器显示 "Hello World!" "M5Stack is running successfully!"
+
+
@@ -0,0 +1,128 @@
+# M5Stack-Core Get Started(Windows, Arudino)
+
+### CONTENT
+
+1. [Setting Environment](#setting-environment)
+
+    - [1. Install Arduino IDE](#1-install-arduino-ide)
+
+    - [2. Download Toolchain](#2-download-toolchain)
+
+    - [3. ESP32 Toolchain](#3-esp32-toolchain)
+
+    - [4. Download M5Stack Lib](#4-download-m5stack-lib)
+
+4. [Example](#example)
+
+### Setting Environment
+
+*Before setting the development environment, we suggest you confirm whether the USB driver has installed. If not, please visit this link `establish serial connection`.*
+
+#### 1. Install `Arduino IDE`
+
+*download address*
+https://www.arduino.cc/en/Main/Software
+
+![image](../../_static/screenshots/arduino_cc_package.png)
+
+
+modified the path of Arduino as `D:\Program Files` as shown below
+
+![image](../../_static/screenshots/select_arduino_install_path.png)
+
+
+Now my path of Arduino is `D:\Program Files\Arduino`
+
+![image](../../_static/screenshots/arduino_path.png)
+
+
+#### 2. Download Toolchain
+
+（Now my path of Arduino is `D:\Program Files\Arduino`）
+
+Enter the path `D:\Program Files\Arduino\hareware` via the terminal of Windows 
+
+Execute the following commands on the terminal of Windows
+> * new a directory named `espressif`, then enter this directory
+
+mkdir espressif && cd espressif
+
+![image](../../_static/screenshots/mkdir_espressif.png)
+
+
+> * clone `esp32 idf` at the directory named `esp32`
+
+git clone --recursive https://github.com/espressif/arduino-esp32.git esp32
+
+![image](../../_static/screenshots/download_idf.png)
+
+
+
+#### 3. ESP32 Toolchain
+
+Enter the path `D:\Program Files\arduino\hardware\espressif\esp32\tools`
+double click on `get.exe`
+
+![image](../../_static/screenshots/select_get_exe_file.png)
+
+![image](../../_static/screenshots/download_xtensa_tools.png)
+
+
+#### 4. Download the M5Stack Lib via Arduino IDE 
+
+Open Arduino IDE, then Select `Sketch`->`Include Library`->`Manage Libraries...`
+Search `M5Stack` and install it
+
+![image](../../_static/screenshots/select_arduino_lib.png)
+
+![image](../../_static/screenshots/download_m5stack_lib.png)
+
+
+### Example
+
+The USB cable connects to M5Stack Core, then select your serial port which is connected M5Stack Core.
+Select a demo example, compile and upload
+
+#### 1. Open a example likes `FactoryTest.ino`
+
+![image](../../_static/screenshots/select_demo.png)
+
+
+
+Comfire your board name, baudrate, the specified serial port: M5Stack-Core-ESP32、921600、COM3
+
+![image](../../_static/screenshots/select_board_and_com.png)
+
+After upload seccessfully, open the Serial Monitor
+
+![image](../../_static/screenshots/FactoryTest_result.png)
+
+#### 2. New a M5Stack program
+
+Open Arduino IDE, then new a `.ino` file, rename it as `my_test.ino`
+
+Copy the below code to my_test.ino
+
+```cpp
+#include <M5Stack.h>
+
+// the setup routine runs once when M5Stack starts up
+void setup(){tack
+
+  // Initialize the M5Stack object
+  M5.begin();
+
+  // LCD display
+  M5.Lcd.print("Hello World!");
+  M5.Lcd.print("M5Stack is running successfully!");    
+}
+
+// the loop routine runs over and over again forever
+void loop() {
+
+}
+```
+
+compile it and upload, the M5Stack screen will show "Hello World!" "M5Stack is running successfully!"
+
+
@@ -0,0 +1,119 @@
+# M5Stack-Core Get Started(Windows, MicroPython)
+
+### CONTENT
+
+1. [Burn Firmware](#Burn-Firmwared)
+
+    - [1. Download Firmware](#1-download-firmware)
+
+    - [2. Burn to M5Stack](#2-Burn-to-M5Stack)
+
+1. [Connect Wi-Fi](#connect-wi-fi)
+
+3. [Binding device](#binding-device)
+
+4. [Coding MicroPython](#coding-micropython)
+
+
+### Burn Firmware
+#### 1. Download Firmware
+https://github.com/m5stack/M5Cloud/tree/master/firmwares
+
+Now, the M5Cloud firmware I downloaded named `m5cloud-20180516-v0.4.0.bin`
+and it saved at `~/smbshare`
+
+#### 2. Burn to M5Stack
+![image](../../_static/windows-logo.png) | ![image](../../_static/linux-logo.png) | ![image](../../_static/macos-logo.png) 
+---|---|---
+Windows | Linux | MacOS
+
+***Windows***
+
+open Flash Download Tools([点击下载](https://www.espressif.com/sites/default/files/tools/flash_download_tools_v3.6.4.rar)) apply by Espressif, choose `ESP32 DownloadTool` option and execute three steps ( *choose firmware file, your serial port, erase and program flash* ) as shown below
+
+![image](../../_static/M5Stack_MicroPython_UserGuidePictures/windows_download_firmware.png)
+
+
+
+***MacOS/Linux***
+
+*1. Check port on Linux and MacOS*
+
+  To check the device name for the serial port of your M5Stack board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
+
+  Linux
+
+  ```
+  ls /dev/tty*
+  ```
+  
+  MacOS
+
+  ```
+  ls /dev/cu.*
+  ```
+
+
+*2. Adding user to `dialout` on Linux*
+
+The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to `dialout` group with the following command:
+
+  ```
+  sudo usermod -a -G dialout $USER
+  ```
+Now, my serial port named `ttyUSB0`
+
+*3. Download M5Cloud firmware to M5Stack board*
+  - Installing esptool：
+    ```
+    pip install esptool
+    ```
+  - Erase flash on M5Stack:
+    ```
+    esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
+    ```
+  - Download firmware to M5Stack: 
+    ```
+    esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash --flash_mode dio -z 0x1000 m5cloud-20180516-v0.4.0.bin
+    ```
+    
+### Connect Wi-Fi
+
+
+Mobile Phone or PC connect to M5Stack AP(like `M5Stack-a67c`), and then open brower to login 192.168.4.1 setting your LAN SSID and Password
+
+![image](../../_static/M5Stack_MicroPython_UserGuidePictures/m5stack_connet_wifi.png)
+
+### Binding device
+
+*1.login http://io.m5stack.com and register your own account(or login your account)*
+
+*2. press `Device->Add` buttom on M5Cloud IDE for binding M5Stack board to your account*
+
+*3. Input the Check Code for the M5Stack screen display，Check Code is random, after 60s will refresh*
+
+![image](../../_static/M5Stack_MicroPython_UserGuidePictures/WebIDE_check_code.png)
+
+### Coding MicroPython
+
+*1. create a new python project*
+
+![image](../../_static/M5Stack_MicroPython_UserGuidePictures/create_a_new_project.png)
+
+*2. write your own code and press `Upload & Run` buttom on the M5Cloud IDE*
+
+copy below code to `main.py` file and press `Upload & Run` 
+
+``` python
+from m5stack import lcd
+
+lcd.clear()
+lcd.setCursor(0, 0)
+lcd.setColor(lcd.WHITE)
+
+lcd.print("Hello World!")
+
+```
+
+![image](../../_static/M5Stack_MicroPython_UserGuidePictures/display_hello_world.png)
+
@@ -0,0 +1,74 @@
+# Establish Serial Connection
+
+This section provides guidance how to establish serial connection between your board and PC.
+
+### For MacOS
+
+#### 1. Install the USB driver
+
+[Download the SiLabs CP2104 Driver](https://www.silabs.com/documents/public/software/Mac_OSX_VCP_Driver.zip)
+
+As the disk image SiLabsUSBDriverDisk.dmg is downloaded, mount it.
+Proceed according to the instructions OK.
+
+![image](../../_static/getting_started_pics/establish_serial_connection/macOS_CP2104_dmg.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/macOS_CP2104_pkg.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/2.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/3.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/4.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/5.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/6.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/7.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/8.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/9.png)
+
+#### 2. Check port on MacOS
+
+To check the device name for the serial port of your your board board (or external converter dongle), open terminal and run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
+
+**MacOS**
+
+    ls /dev/cu.*
+
+
+
+### For Windows
+
+#### 1.Install the USB driver
+
+Download the [SiLabs CP2104 Driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
+
+Choice the version of USB driver according to your windows version(Windows7/8/10).
+
+![image](../../_static/getting_started_pics/establish_serial_connection/windows_download_CP2104_USB_driver.png)
+
+Choice the right version installer(x64/x86), and install it.
+
+![image](../../_static/getting_started_pics/establish_serial_connection/windows_install_usb_driver01.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/windows_install_usb_driver02.png)
+
+![image](../../_static/getting_started_pics/establish_serial_connection/windows_install_usb_driver03.png)
+
+
+#### 2. Check port on Windows
+
+Check the list of identified COM ports in the Windows Device Manager. Disconnect your board and connect it back, to verify which port disappears from the list and then shows back again.
+
+Figures below show serial port for M5Stack Core board
+
+![image](../../_static/getting_started_pics/establish_serial_connection/windows_m5stack_in_device_manager.png)
+
+
+
+
+
@@ -0,0 +1,9 @@
+# How to Burn Firmware
+
+This article will guide you how to burn a right firmware to your board.
+
+### For MacOS
+
+
+
+### For Windows
@@ -21,6 +21,10 @@ To develop applications for M5Stack Core you need:
 Your boards
 ============

+At the first time, you need to burn the specific firmware file(.bin) to your board following this article `How to burn firmware`_ befor developing it.
+
+.. _how to burn firmware: how_to_burn_firmware_en.html
+
 If you have one of ESP32 development boards listed below, click the corresponding one to start your development.

 ============================  ============================  ============================
@@ -31,9 +31,9 @@ If you want to get our products, access our `store`_ please.
 ----------------------  ----------------------  ----------------------
 `Product Documents`_     `Get Started`_           `API Reference`_
 ----------------------  ----------------------  ----------------------
-|M5Stack Cases|_           |M5Stack Awesome|_           |FAQ|_    
+|M5Stack Cases|_           |M5Stack Awesome|_           |FAQ|_
 ----------------------  ----------------------  ----------------------
-`M5Stack Cases`_           `M5Stack Awesome`_           `FAQ`_  
+`M5Stack Cases`_           `M5Stack Awesome`_           `FAQ`_
 ======================  ======================  ======================


@@ -67,6 +67,3 @@ If you want to get our products, access our `store`_ please.
   M5Stack Cases <basic-cases/index>
   M5Stack Awesome <m5stack-awesome/index>
   FAQ <m5stack-faq/index>
-
-
-