├── img ├── Flash_Cap0.PNG ├── Flash_Cap1.PNG ├── GDB_Cap0.PNG ├── GDB_Cap1.PNG ├── MSYS2_Cap0.PNG ├── OpenOCD_Cap0.PNG ├── Serial_Cap0.PNG ├── Serial_Cap1.PNG ├── VSCode_Cap0.PNG ├── VSCode_Cap1.PNG ├── VSCode_Cap2.PNG ├── VSCode_Cap3.PNG ├── VSCode_Cap4.PNG ├── VSCode_Cap5.PNG ├── Zadig_Cap0.PNG ├── Zadig_Cap1.PNG ├── Zadig_Cap2.PNG └── Zadig_Cap3.PNG └── tutorial.md /img/Flash_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Flash_Cap0.PNG -------------------------------------------------------------------------------- /img/Flash_Cap1.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Flash_Cap1.PNG -------------------------------------------------------------------------------- /img/GDB_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/GDB_Cap0.PNG -------------------------------------------------------------------------------- /img/GDB_Cap1.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/GDB_Cap1.PNG -------------------------------------------------------------------------------- /img/MSYS2_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/MSYS2_Cap0.PNG -------------------------------------------------------------------------------- /img/OpenOCD_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/OpenOCD_Cap0.PNG -------------------------------------------------------------------------------- /img/Serial_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Serial_Cap0.PNG -------------------------------------------------------------------------------- /img/Serial_Cap1.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Serial_Cap1.PNG -------------------------------------------------------------------------------- /img/VSCode_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/VSCode_Cap0.PNG -------------------------------------------------------------------------------- /img/VSCode_Cap1.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/VSCode_Cap1.PNG -------------------------------------------------------------------------------- /img/VSCode_Cap2.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/VSCode_Cap2.PNG -------------------------------------------------------------------------------- /img/VSCode_Cap3.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/VSCode_Cap3.PNG -------------------------------------------------------------------------------- /img/VSCode_Cap4.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/VSCode_Cap4.PNG -------------------------------------------------------------------------------- /img/VSCode_Cap5.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/VSCode_Cap5.PNG -------------------------------------------------------------------------------- /img/Zadig_Cap0.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Zadig_Cap0.PNG -------------------------------------------------------------------------------- /img/Zadig_Cap1.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Zadig_Cap1.PNG -------------------------------------------------------------------------------- /img/Zadig_Cap2.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Zadig_Cap2.PNG -------------------------------------------------------------------------------- /img/Zadig_Cap3.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haoyan-dev/esp32-devenv-vscode/db192bd6c13751283a18df2aea4752c43c52d5ad/img/Zadig_Cap3.PNG -------------------------------------------------------------------------------- /tutorial.md: -------------------------------------------------------------------------------- 1 | # Setting Development Environment for ESP32 (Windows) 2 | 3 | ## Introduction 4 | 5 | This is a tutorial that shows how to setup a development environment for ESP32 series. 6 | Following this tutorial, finally you can develop and debug your first project on ESP32 boards. 7 | 8 | Particially, for this case we choose: 9 | - OS: Windows 10 with MSYS2-32bit 10 | - Code Editor: VSCode 11 | - Development Board: ESP32-DevKitC(ESP32-WROOM-32) 12 | - JTAG Debugger: FT232HL 13 | 14 | ## Get Started 15 | 16 | To develop and debug our first project on ESP32 boards, we need to finish several configuration procedures, step by step. 17 | 1. Toolchain, that is used to compile applications for ESP32 18 | 2. ESP-IDF, that includes all of necessary APIs for ESP32 19 | 3. OpenOCD, that could provide on-chip debugging support via JTAG interface 20 | 4. VSCode, that is a code editor which could develop and debug your code. 21 | 22 | ## Toolchain 23 | 24 | To obtain the toolchain of ESP32 chips, we can directly download an pre-packaged MSYS2 environment from [here](https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.zip). 25 | If you are curious about setting up a toolchain manually, here is a [tutorial]() from the official site could be useful. 26 | 27 | Download the zip file and unzip it to `C:\` (or other directory which you prefer), then we will get an `msys32` directory under `C:\`. 28 | Click and run `C:\msys32\mingw32.exe` to check whether the environment has been configured. 29 | 30 | ![MSYS2 Environment](img/MSYS2_Cap0.PNG) 31 | 32 | > Note: Before you start `mingw32.exe`, it might need to run `autorebase.bat` first to make your `MSYS2` work normally. 33 | 34 | ## ESP-IDF 35 | 36 | ### Get ESP-IDF 37 | 38 | To get the ESP-IDF, we will use `git` command to clone it from ESP-IDF repository provided by Espressif. 39 | 40 | ```bash 41 | cd ~ 42 | mkdir esp 43 | cd ~/esp 44 | git clone --recursive https://github.com/espressif/esp-idf.git 45 | ``` 46 | 47 | ### Set IDF_PATH 48 | 49 | To make the API work well, we need to set the system variable of `IDF_PATH`. 50 | An official [tutorial](http://esp-idf.readthedocs.io/en/latest/get-started/windows-setup.html) is supplied. 51 | 52 | Here, we already prepared a `export_idf_path.sh`. 53 | However, you need to modify the directory based on your own case. 54 | Note that, you should use forward-slashes to replace back-slashes, e.g.: 55 | ``` 56 | export IDF_PATH="C:/msys32/home/yourusername/esp/esp-idf" 57 | ``` 58 | 59 | ### Test with Hello-World 60 | 61 | #### Copy Sample Project 62 | 63 | Copy `hello_world` example from ESP-IDF to `~/esp` directory: 64 | 65 | ```bash 66 | cd ~/esp 67 | cp -r $IDF_PATH/examples/get-started/hello_world . 68 | $ 69 | ``` 70 | 71 | #### Connect 72 | 73 | Connect your ESP board to PC, and check the port number of COM device in device manager. 74 | 75 | 76 | #### Configure 77 | 78 | Go to directory of `hello_world` project, then configure the project by `menuconfig`. 79 | 80 | ```bash 81 | cd ~/esp/hello_world 82 | make menuconfig 83 | ``` 84 | 85 | ![Serial Port Configuration - 1](img/Serial_Cap1.PNG) 86 | ![Serial Port Configuration - 2](img/Serial_Cap0.PNG) 87 | 88 | After finished the configuration of serial port, save and exit by selecting `< Save >` and `< Exit >`. 89 | 90 | #### Build, Flash, and Monitor 91 | 92 | Now, you can build `hello_world` project and flash it into the chip, then use `make monitor` command to read messages. 93 | 94 | ```bash 95 | make flash 96 | make monitor 97 | ``` 98 | 99 | ![Flash](img/Flash_Cap0.PNG) 100 | ![Monitor](img/Flash_Cap1.PNG) 101 | 102 | > Note: `Ctrl + ]` can exit the monitor. 103 | 104 | --- 105 | 106 | If you got correct ouput, the compling and flashing parts now are working well. 107 | 108 | ## OpenOCD 109 | 110 | Here, we supply a pre-compiled `OpenOCD-ESP32`, and you can directly download [openocd-0.10.0-dev-gcdaf22fd](https://github.com/espressif/openocd-esp32/releases) and use it. 111 | Copy `OpenOCD` to `C:\msys32\home\yourusername\`, and unzip it. 112 | 113 | ```bash 114 | cd ~ 115 | tar -xzvf openocd-0.10.0-dev-gcdaf22fd.tar.gz . 116 | ``` 117 | 118 | > Note: if your MSYS2 environment doesn't have `tar` tool, please use `pacman -S tar` to install it. 119 | 120 | After unzipped files, enter below commands to configure OpenOCD. 121 | 122 | ```bash 123 | cd ~/openocd-0.10.0-dev-gcdaf22fd 124 | cp -r ./share/ /mingw32/share/openocd 125 | cp ./bin/openocd.exe /mingw32/bin/ 126 | ``` 127 | 128 | Before we run `openocd`, a dependancy of `libusb` is needed. 129 | 130 | ```bash 131 | pacman -S mingw-w64-i686-libusb 132 | ``` 133 | 134 | ### Replace driver for FT232HL 135 | 136 | As a default, Windows does not have a libusb driver, hence `FT232HL` will be recognized as a virtual serial port. 137 | Here, we can use [Zadig](http://zadig.akeo.ie/) and easily change the default driver to `libusb` driver. 138 | 139 | Follow below precedures, finally `FT232HL` could work as a JTAG debugger. 140 | 141 | ![Zadig - Step.1](img/Zadig_Cap0.PNG) 142 | ![Zadig - Step.2](img/Zadig_Cap1.PNG) 143 | ![Zadig - Step.3](img/Zadig_Cap2.PNG) 144 | ![Zadig - Step.4](img/Zadig_Cap3.PNG) 145 | 146 | ### Connect to JTAG Debugger 147 | 148 | Enter below command to start `OpenOCD`. 149 | 150 | ![OpenOCD Output](img/OpenOCD_Cap0.PNG) 151 | 152 | If you get output as above, `OpenOCD` now is working well. 153 | 154 | ### Link with GDB 155 | 156 | Open a new `MSYS2` terminal window, and start `gdb`. 157 | 158 | ```bash 159 | cd ~/esp/hello_world/ 160 | xtensa-esp32-elf-gdb -ex 'target remote localhost:3333' ./build/hello-world.elf 161 | ``` 162 | 163 | ![GDB Output](img/GDB_Cap0.PNG) 164 | ![OpenOCD Output](img/GDB_Cap1.PNG) 165 | 166 | If you got output as above, `OpenOCD` and `GDB` now is connected. 167 | 168 | ## VS Code 169 | 170 | [VS Code](https://code.visualstudio.com/) is a light-weight, open source code editor published by Microsoft. 171 | Download it from official site, and install it. 172 | 173 | After installation, launch `VS Code` and install essential extensions. 174 | 1. C/C++ for Visual Studio Code 175 | 2. Native Debug 176 | 177 | ![VS Code Extension](img/VSCode_Cap0.PNG) 178 | 179 | ### Configure VS Code 180 | 181 | First, we create a new project in `VS Code`, using `esp-idf\examples\get-started\blink`. 182 | Put `blink` project into anywhere you want, and open this folder in `VS Code`. 183 | 184 | #### IntelliSense 185 | 186 | To enable code completion and navigation, we need to generate a `c_cpp_properties.json` file first. 187 | Enter `Ctrl+Shift+P` to open `Command Palette`, then choose `C/Cpp: Edit Configurations` to generate a new `c_cpp_properties.json` file. 188 | 189 | ![C/Cpp Configurations](img/VSCode_Cap1.PNG) 190 | 191 | The modified `c_cpp_properties.json` file has shown as below. 192 | Please change `includePath` to adapt your own case. 193 | 194 | ```json 195 | { 196 | "configurations": [ 197 | { 198 | "name": "ESP32-Win", 199 | "includePath": [ 200 | "${workspaceRoot}", 201 | "C:/msys32/opt/xtensa-esp32-elf/lib/gcc/xtensa-esp32-elf/5.2.0/include", 202 | "C:/msys32/opt/xtensa-esp32-elf/lib/gcc/xtensa-esp32-elf/5.2.0/include-fixed", 203 | "C:/msys32/opt/xtensa-esp32-elf/xtensa-esp32-elf/include", 204 | "C:/msys32/opt/xtensa-esp32-elf/xtensa-esp32-elf/sysroot/usr/include", 205 | "C:/msys32/home/Iris/esp/esp-idf/components" 206 | ], 207 | "intelliSenseMode": "clang-x64", 208 | "browse": { 209 | "path": [ 210 | "${workspaceRoot}", 211 | "C:/msys32/opt/xtensa-esp32-elf/lib/gcc/xtensa-esp32-elf/5.2.0/include", 212 | "C:/msys32/opt/xtensa-esp32-elf/lib/gcc/xtensa-esp32-elf/5.2.0/include-fixed", 213 | "C:/msys32/opt/xtensa-esp32-elf/xtensa-esp32-elf/include", 214 | "C:/msys32/opt/xtensa-esp32-elf/xtensa-esp32-elf/sysroot/usr/include", 215 | "C:/msys32/home/Iris/esp/esp-idf/components" 216 | ], 217 | "limitSymbolsToIncludedHeaders": true, 218 | "databaseFilename": "${workspaceRoot}/.vscode/browse.vc.db" 219 | } 220 | } 221 | ], 222 | "version": 3 223 | } 224 | ``` 225 | 226 | > Note: The IntelliSense of VS Code does not treat `includePath` recursively, which means you might need to fill all of subfolder's path manually. 227 | > Here is one convenient trick to help you. 228 | > Open any cpp file, and find any green squiggle. 229 | > Click the lightbulk, you will be able to add `includePath` setting automatically. 230 | 231 | #### Tasks 232 | 233 | To handle build, clean, and flash tasks in `VS Code`, we need to configure `tasks.json` file. 234 | Enter `Ctrl+Shift+P` to open `Command Palette`, then choose `Tasks: Configuration Task` to generate a new `tasks.json` file. 235 | 236 | ![Tasks Configuration](img/VSCode_Cap2.PNG) 237 | 238 | Modify the file as below, then you can use customized tasks in `VS Code` toolbar. 239 | 240 | ```json 241 | { 242 | // See https://go.microsoft.com/fwlink/?LinkId=733558 243 | // for the documentation about the tasks.json format 244 | "version": "2.0.0", 245 | "tasks": [ 246 | { 247 | "label": "build app", 248 | "group": "build", 249 | "command": "make", 250 | "type": "shell", 251 | "args": [ 252 | "app" 253 | ], 254 | "presentation": { 255 | "reveal": "always", 256 | }, 257 | "problemMatcher": { 258 | "owner": "cpp", 259 | "fileLocation": "absolute", 260 | "pattern": { 261 | "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", 262 | "file": 1, 263 | "line": 2, 264 | "column": 3, 265 | "severity": 4, 266 | "message": 5 267 | } 268 | } 269 | }, 270 | { 271 | "label": "clean app", 272 | "command": "make", 273 | "type": "shell", 274 | "args": [ 275 | "app-clean" 276 | ], 277 | "presentation": { 278 | "reveal": "always", 279 | }, 280 | }, 281 | { 282 | "label": "flash app", 283 | "command": "make", 284 | "type": "shell", 285 | "args": [ 286 | "app-flash" 287 | ], 288 | "presentation": { 289 | "reveal": "always", 290 | }, 291 | }, 292 | { 293 | "label": "monitor", 294 | "type":"process", 295 | "windows": { 296 | "command": "c:/msys32/mingw32.exe", 297 | "args": [ 298 | "make", 299 | "monitor" 300 | ], 301 | }, 302 | "presentation": { 303 | "reveal": "always", 304 | }, 305 | "problemMatcher": [] 306 | }, 307 | { 308 | "label": "menuconfig", 309 | "type":"process", 310 | "windows": { 311 | "command": "C:/msys32/mingw32.exe", 312 | "args": [ 313 | "make", 314 | "menuconfig" 315 | ] 316 | }, 317 | "presentation": { 318 | "reveal": "always", 319 | }, 320 | "problemMatcher": [] 321 | } 322 | ] 323 | } 324 | ``` 325 | 326 | > Note: Please modify `command` property to match with your own case. 327 | 328 | #### Integrated Terminal 329 | 330 | To set the default integrated terminal as MSYS2, we need to configure `User Settings`. 331 | Clike `File - Preferences - Settings` to open `Setting` window. 332 | In `User Settings` panel, write below lines to setup. 333 | 334 | ![User Settings](img/VSCode_Cap3.PNG) 335 | 336 | ```json 337 | { 338 | "terminal.integrated.shell.windows": "C:/msys32/usr/bin/bash.exe", 339 | "terminal.integrated.shellArgs.windows": [ 340 | "--login", 341 | ], 342 | "terminal.integrated.env.windows": { 343 | "CHERE_INVOKING": "1", 344 | "MSYSTEM": "MINGW32", 345 | }, 346 | } 347 | ``` 348 | 349 | 350 | 354 | --------------------------------------------------------------------------------