Configure VS Code for ESP-IDF ( OS X / Linux )


Menuconfig
Menuconfig
Build Output
Build Output
Serial Monitor
Serial Monitor
Debug Panes
Debug Panes
Debug with Serial Monitor
Debug with Serial Monitor
OpenOCD Server
OpenOCD Server


Setup

cmake
esp tools path

New Project

  • Copy an ESP-IDF project
  • Add the vscode.esp folder to the root of the project
  • Rename vscode.esp to .vscode
  • To rename the project:
  • Any folder with sources to build must contain a CMakeLists.txt file
  • Update c_cpp_properties.json to include your header locations (please see file notes below)

Debug

  • Install OpenOCD to ~/esp/ (elsewhere is ok just mind the .json paths)
    • OS X Specific:
      • Do not install FTDI VCP driver or hack kexts
      • Install libusb: brew install libusb
      • Unload Apple FTDI Driver: sudo kextunload -verbose -bundle-id com.apple.driver.AppleUSBFTDI -personalities-only
      • More Info about low-level usb port access for jtag
  • Edit launch.json and verify paths and serial port
  • Edit tasks.json and make sure paths of the “OpenOCD” task are correct
    • (i.e. ~/esp/openocd-esp32/bin/openocd and ~/esp/openocd-esp32/share/openocd/scripts)
  • Start OpenOCD server before debugging (F12 - Tasks: Run Task: OpenOCD)

sdkconfig.h

  • Include this file in your main file for ESP-IDF menuconfig definitons
// esp-idf definitions
#include "sdkconfig.h"


Hotkeys and Tasks


  • Press a key and run a task, or use the command menu to run a task by name.
F4 Config
F5 Debug
F6 Clean
F7 Build
F8 Flash
F9 Flash Monitor
F10 Monitor
F12 OpenOCD


c_cpp_properties.json


  • This file tells VS Code's IntelliSense engine where to find headers.
  • Paths must be specified non-recursively like ${env:IDF_PATH}/components/freertos/include
  • In order to make this easier, VS Code has a contextual menu that appears as a lightbulb above missing files. The cursor must be within the squiggle for the lightbulb to appear.
  • Click the lightbulb, select the appropriate header path, and it will be appended to the includePath variable automatically.
    • Note: Although recursive paths may be specified like ${env:IDF_PATH}/components/**, the ESP-IDF contains redundant headers in various locations. Unfortunately this confuses IntelliSense, and it falls out of sync with the ESP-IDF toolchain. However, this recursion may work for other folder structures with unique filenames.

  1. {
  2. "configurations": [
  3. {
  4. "name": "ESP-IDF",
  5. "cStandard": "c11",
  6. "cppStandard": "c++17",
  7. "intelliSenseMode": "clang-x64",
  8. "compilerPath": "~/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc",
  9. "includePath": [
  10. "${workspaceFolder}",
  11. "${workspaceFolder}/build/config",
  12. "",
  13. "~/esp/xtensa-esp32-elf/include/gdb",
  14. "~/esp/xtensa-esp32-elf/lib/gcc/xtensa-esp32-elf/5.2.0/include",
  15. "~/esp/xtensa-esp32-elf/lib/gcc/xtensa-esp32-elf/5.2.0/include-fixed",
  16. "~/esp/xtensa-esp32-elf/xtensa-esp32-elf/include",
  17. "~/esp/xtensa-esp32-elf/xtensa-esp32-elf/include/c++/5.2.0",
  18. "",
  19. "${env:IDF_PATH}/components",
  20. "${env:IDF_PATH}/components/freertos/include",
  21. "${env:IDF_PATH}/components/xtensa/include",
  22. "${env:IDF_PATH}/components/xtensa/esp32/include",
  23. "${env:IDF_PATH}/components/esp_rom/include",
  24. "${env:IDF_PATH}/components/esp_common/include",
  25. "${env:IDF_PATH}/components/heap/include",
  26. "${env:IDF_PATH}/components/esp32/include",
  27. "${env:IDF_PATH}/components/driver/include",
  28. "${env:IDF_PATH}/components/soc/include",
  29. "${env:IDF_PATH}/components/soc/esp32/include",
  30. "${env:IDF_PATH}/components/spi_flash/include",
  31. ""
  32. ]
  33. }
  34. ],
  35. "version": 4
  36. }

genflash.sh


  • Shell script to generate flash folder containing .bin files and flash.sh script
  • Make sure serial port is correct

  1. # esp32 flash script generator
  2. port="/dev/tty.SLAB_USBtoUART"
  3. echo
  4. echo Creating flash folder
  5. echo $(rm -Rf flash)
  6. mkdir flash
  7. cd flash
  8. cp ../build/bootloader/bootloader.bin ./
  9. cp ../build/partition_table/partition-table.bin ./
  10. cp ../build/*.bin ./
  11. fio=$(sed -n 's/^#define CONFIG_ESPTOOLPY_FLASHMODE //p' ../build/config/sdkconfig.h | sed 's/"//g')
  12. mhz=$(sed -n 's/^#define CONFIG_ESPTOOLPY_FLASHFREQ //p' ../build/config/sdkconfig.h | sed 's/"//g')
  13. app=$(find *.bin ! -name "bootloader.bin" ! -name "partition-table.bin")
  14. echo "\$IDF_PATH/components/esptool_py/esptool/esptool.py -p $port -b 1500000 --after hard_reset write_flash --flash_mode $fio --flash_size detect --flash_freq $mhz 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 $app" > flash.sh
  15. chmod 755 flash.sh

keybindings.json


  • These custom keybindings should be added to the local keybindings.json file of your VS Code installation.
  • Preferences → Keyboard Shortcuts → { } file tab bar button

  1. // vscode keybindings for esp-idf
  2. // place these in your local vscode keybindings.json file
  3. [
  4. {
  5. "key": "f2",
  6. "command": "workbench.action.tasks.runTask",
  7. "args": "Monitor Exit"
  8. },
  9. {
  10. "key": "f4",
  11. "command": "workbench.action.tasks.runTask",
  12. "args": "Config"
  13. },
  14. {
  15. "key": "f6",
  16. "command": "workbench.action.tasks.runTask",
  17. "args": "Clean"
  18. },
  19. {
  20. "key": "f7",
  21. "command": "workbench.action.tasks.runTask",
  22. "args": "Build"
  23. },
  24. {
  25. "key": "f8",
  26. "command": "workbench.action.tasks.runTask",
  27. "args": "Flash"
  28. },
  29. {
  30. "key": "f9",
  31. "command": "workbench.action.tasks.runTask",
  32. "args": "Flash Monitor"
  33. },
  34. {
  35. "key": "f10",
  36. "command": "workbench.action.tasks.runTask",
  37. "args": "Monitor"
  38. },
  39. {
  40. "key": "f12",
  41. "command": "workbench.action.tasks.runTask",
  42. "args": "OpenOCD"
  43. }
  44. ]

launch.json


  • Debugger setup script

  1. {
  2. "version": "0.2.0",
  3. "configurations": [
  4. {
  5. "name": "Debug",
  6. // "preLaunchTask": "Flash",
  7. "type": "cppdbg",
  8. "request": "launch",
  9. "MIMode": "gdb",
  10. "miDebuggerPath": "/Users/cooper/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb",
  11. "program": "${workspaceFolder}/build/${workspaceFolderBasename}.elf",
  12. "args": [],
  13. "environment": [],
  14. "stopAtEntry": true,
  15. "externalConsole": false,
  16. "cwd": "${workspaceRoot}",
  17. "setupCommands": [
  18. {
  19. "description": "Enable pretty-printing for gdb",
  20. "text": "-enable-pretty-printing",
  21. "ignoreFailures": true
  22. },
  23. {
  24. "text": "target remote localhost:3333"
  25. },
  26. {
  27. "text": "mon reset halt"
  28. },
  29. {
  30. "text": "flushregs"
  31. },
  32. {
  33. "text": "thb app_main"
  34. },
  35. ],
  36. }
  37. ]
  38. }

screenrc.monitor


  • Configuration file for the Monitor screen session

  1. # screen config file for
  2. # 'serial monitor' in vscode terminal
  3.  
  4. # clear the screen
  5. clear
  6.  
  7. # current directory backtick command
  8. backtick 1 0 0 basename $PWD
  9.  
  10. # enable scrolling for mouse and bar
  11. termcapinfo xterm* ti@:te@
  12.  
  13. # put status at bottom of window
  14. hardstatus alwayslastline
  15.  
  16. # status string
  17. hardstatus string ' %1` : %t : 115200 %= %c:%s %= [ctrl-a k y] to exit '
  18.  
  19. # clear the screen again
  20. clear

screenrc.openocd


  • Configuration file for the OpenOCD server screen session

  1. # screen config file for
  2. # OpenOCD in vscode terminal
  3.  
  4. # clear the screen
  5. clear
  6.  
  7. # enable scrolling for mouse and bar
  8. termcapinfo xterm* ti@:te@
  9.  
  10. # put status at bottom of window
  11. hardstatus alwayslastline
  12.  
  13. # status string
  14. hardstatus string ' OpenOCD %= %c:%s %= [ctrl-c] to exit '
  15.  
  16. # clear the screen again
  17. clear

tasks.json


  • These tasks configure VS Code to work like an IDE for the ESP-IDF
  • Make sure paths and serial port in “OpenOCD” task are correct
    • i.e. ~/esp/openocd-esp32/bin/openocd and ~/esp/openocd-esp32/share/openocd/scripts

  1. // VS Code Tasks For ESP-IDF Toolchain - Cooper Baker 05/03/19
  2. {
  3. "version": "2.0.0",
  4. "tasks": [
  5. {
  6. "label": "Config",
  7. "dependsOn": ["Clean"],
  8. "type": "shell",
  9. "command": "idf.py menuconfig",
  10. "options": {
  11. "cwd": "${workspaceFolder}",
  12. },
  13. "presentation": {
  14. "focus": true,
  15. }
  16. },
  17. {
  18. "label": "Clean",
  19. "type": "shell",
  20. "command": "clear && idf.py fullclean && echo $(rm -Rf flash)",
  21. "options": {
  22. "cwd": "${workspaceFolder}"
  23. }
  24. },
  25. {
  26. "label": "Build",
  27. "type": "shell",
  28. "command": "cd .. && clear && idf.py all && .vscode/genflash.sh",
  29. "options": {
  30. "cwd": "${workspaceFolder}/build"
  31. },
  32. "problemMatcher": {
  33. "base":"$gcc",
  34. "fileLocation": ["relative", "${workspaceFolder}/build"]
  35. }
  36. },
  37. {
  38. "label": "Flash",
  39. "dependsOn": ["Monitor Exit"],
  40. "type":"shell",
  41. "command": "cd .. && echo $( screen -S monitor -X quit ) && clear && idf.py -p /dev/tty.SLAB_USBtoUART -b 1500000 flash size && .vscode/genflash.sh",
  42. "options": {
  43. "cwd": "${workspaceFolder}/build"
  44. },
  45. "problemMatcher": {
  46. "base":"$gcc",
  47. "fileLocation": ["relative", "${workspaceFolder}/build"]
  48. }
  49. },
  50. {
  51. "label": "Flash Monitor",
  52. "dependsOn": ["Monitor Exit"],
  53. "type": "shell",
  54. "command": "cd .. && echo $( screen -S monitor -X quit ) && clear && idf.py -p /dev/tty.SLAB_USBtoUART -b 1500000 flash && .vscode/genflash.sh && screen -S monitor -c .vscode/screenrc.monitor /dev/tty.SLAB_USBtoUART 115200",
  55. "options": {
  56. "cwd": "${workspaceFolder}/build"
  57. },
  58. "problemMatcher": {
  59. "base":"$gcc",
  60. "fileLocation": ["relative", "${workspaceFolder}/build"]
  61. }
  62. },
  63. {
  64. "label": "Monitor",
  65. "dependsOn":["Monitor Exit"],
  66. "type": "shell",
  67. "command": "echo $( screen -S monitor -X quit ) && clear && screen -S monitor -c .vscode/screenrc.monitor /dev/tty.SLAB_USBtoUART 115200",
  68. "options": {
  69. "cwd": "${workspaceFolder}"
  70. }
  71. },
  72. {
  73. "label": "OpenOCD",
  74. "dependsOn":["OpenOCD Exit"],
  75. "type": "shell",
  76. "command": "echo $( screen -S monitor -X quit ) && screen -S openocd -c .vscode/screenrc.openocd ~/esp/openocd-esp32/bin/openocd -s ~/esp/openocd-esp32/share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/${input:Chip}.cfg -c init -c \"reset init\"",
  77. "options": {
  78. "cwd": "${workspaceFolder}"
  79. }
  80. },
  81. {
  82. "label": "Monitor Exit",
  83. "type":"shell",
  84. "command": "echo $( screen -S monitor -X quit )",
  85. "options": {
  86. "cwd": "${workspaceFolder}"
  87. },
  88. "presentation": {
  89. "echo": false,
  90. "reveal": "never",
  91. "focus": false,
  92. "panel": "shared",
  93. "showReuseMessage": false,
  94. "clear": true
  95. }
  96. },
  97. {
  98. "label": "OpenOCD Exit",
  99. "type":"shell",
  100. "command": "echo $( screen -S openocd -X quit )",
  101. "options": {
  102. "cwd": "${workspaceFolder}"
  103. },
  104. "presentation": {
  105. "echo": false,
  106. "reveal": "never",
  107. "focus": false,
  108. "panel": "shared",
  109. "showReuseMessage": false,
  110. "clear": false
  111. }
  112. }
  113. ],
  114. "inputs": [
  115. {
  116. "id": "Chip",
  117. "type": "pickString",
  118. "description": "Chip To Debug",
  119. "options": ["esp-wroom-32", "esp32-wrover"],
  120. "default": "esp32-wrover"
  121. }
  122. ]
  123. }

  • code/vscode.txt
  • Last modified: 08/05/2019
  • by cooper