We consider that the Espressif IoT Development Framework (ESP-IDF), version 4.4.1, and Visual Studio Code environment is installed on the computer. For more details, see:
- https://docs.espressif.com/projects/esp-idf/en/v4.4.1/esp32/get-started/index.html#installation-step-by-step
- https://code.visualstudio.com/
As of VS-code v1.56.1 integrated terminals require additional configuration to work correctly. see https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations to edit the setting.json
file and add the following entry:
"terminal.integrated.allowWorkspaceConfiguration":true
In Linux (from Ubuntu 20.x), on connecting an ESP32 board with a CP210x USB to serial converter, there is a problem of connection. Add the following entries below that disable both parts of the brltty service and allowed the ESP32 development boards to properly connect.
sudo systemctl stop brltty-udev.service
sudo systemctl mask brltty-udev.service
sudo systemctl stop brltty.service
sudo systemctl disable brltty.service
Another solution is to uninstall brltty as below:
sudo apt remove brltty
Firstly, you have to clone the esp32-vscode-project-template
project and follow the next steps.
git clone https://github.com/fmuller-pns/esp32-vscode-project-template.git
mv esp32-vscode-project-template <my_project_name>
cd <my_project_name>
rm -fR .git
code .
"IDF_TOOLS": "~/.espressif/tools",
"IDF_PATH": "~/esp/esp-idf"
This step renames the executable file. By default, the executable file is main.elf
.
- Open
CMakeLists.txt
and replacemain
by <my_project_name> - Open
Makefile
and replacemain
by <my_project_name> - Open
.vscode/launch.json
and replacemain
by <my_project_name> (lines 11 and 19)
Choose an external or internal terminal.
- using keyboard shortcut:
Ctrl+Shift+
2 - or pressing
F1
key and typingintegrated
- using keyboard shortcut:
Ctrl+Shift+C
- or pressing
F1
key and typingexternal
ls /dev/ttyUSB*
/dev/ttyUSB0
The serial port is /dev/ttyUSB0
identified above.
idf.py -p /dev/ttyUSB0 flash monitor
Serial port /dev/ttyUSB0
Connecting........_____....._
Detecting chip type... ESP32
Chip is ESP32-PICO-D4 (revision 1)
The message "Hello ESP32 !
" appears.
...
W (290) spi_flash: Detected size(4096k) larger than the size in the binary image header(2048k). Using the size in the binary image header.
I (300) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
Hello ESP32 !
To exit monitoring, typing Ctrl+AltGr+]
- using keyboard shortcut:
Ctrl+Shift+C
- or pressing
F1
key and typingexternal
- using keyboard shortcut:
Ctrl+Shift+
2 - or pressing
F1
key and typingintegrated
idf.py fullclean
idf.py menuconfig
idf.py build
ls /dev/ttyUSB*
idf.py -p /dev/ttyUSB0 flash
idf.py -p /dev/ttyUSB0 flash monitor
To exit monitoring, typing Ctrl+AltGr+]
- In the menu, select
Run Task...
- Select the task you want to launch:
ESP32 - Build only
: just build the projectESP32 - Flash and Monitor
: build (when modifications of code), flash and monitorESP32 - Clean Project
: Clean project (Full clean)ESP32 - OpenOCD with FT2232
: Run in dedicated terminal the openOCD command to debug the projectESP32 - Doxygen - HTML doc.
: Generate HTML documentation with Doxygen
cd <project_name>
git config --global user.name "your name"
git config --global user.email "your email address"
This is useful when connecting your GIT to GitHub.
git config credential.helper store
We consider you have followed the sections above:
- Getting Started
- Configure GIT for your new project
Now, how to communicate with GitHub ?
- Open visual studio code.
- Click on the
Source Control
icon on your left side or useCtrl+Shift+G
shortcut. - For the first time, click on
Initialize Repository
button - Enter a message for your first commit (ex: first commit) and click on Commit icon
- Press
F1
and typinggit add remote
and entering :- remote name : your github repository previously created
- remote url : https://github.com/xxx/your_project.git
- username and password
- Push to the GitHub server (master branch)
See https://code.visualstudio.com/docs/editor/versioncontrol for more details.
You must install FTDI FT2232 driver.
- Install USB Driver
sudo apt-get install libusb-1.0
lsusb
Result:
Bus 001 Device 002: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC
- Install OpenOCD rules. The path for rule copy can be different and depend on your ESP-IDF installation.
sudo usermod -a -G dialout $USER
sudo usermod -a -G plugdev $USER
sudo cp ~/.espressif/tools/openocd-esp32/v0.10.0-esp32-20210401/openocd-esp32/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/
sudo reboot
- Connect the ESP32 board (USB)
- Open an external terminal for building, flashing and running project
The serial port is
/dev/ttyUSB0
identified above.
idf.py -p /dev/ttyUSB0 flash monitor
- Connect the JTAG FT2232 (USB)
- Open another external terminal for running
openocd
with configuration file (ftdi_ft2232.cfg
) located in the project root.
openocd -f ftdi_ft2232.cfg
- Result on openocd terminal
Open On-Chip Debugger v0.10.0-esp32-20190313 (2019-03-13-09:52)
Licensed under GNU GPL v2
adapter speed: 20000 kHz
Info : Configured 2 cores
esp32 interrupt mask on
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Debug controller 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : Detected debug stubs @ 3ffb2950 on core0 of target 'esp32'
Info : Listening on port 3333 for gdb connections
-
Click on the left on the line you want to set a breakpoint. A red bullet appears.
-
Click on debug Icon
-
Click on RUN
ESP32 OpenOCD
. If an error arises, click again. -
The program stops at the breakpoint and you can see variables and more
Do not touch the terminal with openocd
command.
- Stop the program into the terminal, typing
Ctrl+AltGr+]
- Build, flash and run program
The serial port is
/dev/ttyUSB0
identified above.
idf.py -p /dev/ttyUSB0 flash monitor
- Click on RUN
ESP32 OpenOCD
. If an error arises, click again. - The program stops at the breakpoint and you can see variables and more
You can use Using Tasks for ESP32 or follow the steps below.
- Open external terminal from vscode, using keyboard shortcut:
Ctrl+Shift+C
, or pressingF1
key and typingexternal
- Generate HTML documentation in
html_doc
folder
- From the User interface (allow you updating the
Doxyfile
configuration file)
doxywizard
- Directly from
Doxyfile
configuration file
doxygen
- A new
html
folder is created, the entry file isindex.html