- ESP-WROOM-32 board
- FTDI232 USB to Serial adapter
- Olimex ARM-USB-OCD-H JTAG adapter
In theory it’s possible to program the flash memory also over JTAG but currently that’s not supported by the ESP32 OpenOCD driver. See also So we need an extra USB to Serial adapter. The Olimex ARM-USB-OCD-H JTAG adapter has also an extra RS232 port, but this port doesn’t provide 3.3 volt signals.
- Virtual Box 5.1.14 on Windows 10
- VirtualBox 5.1.14 Oracle VM VirtualBox Extension Pack
- Linux OS: Ubuntu 16.10 Desktop 64-bit running as guest on Virtual Box
- Virtual Box Guest Additions
- xtensa-esp32-elf toolchain
- ESP32 IDF
- OpenOCD; special version for ESP32
- Eclipse IDE for C++ Developers
- GNU ARM Eclipse Plug-ins
I’ve prepare a ready to use Virtual Box appliance for download. If you wouldn’t install all the software by yourself you can download the appliance. But be warned that’s a 3.23 GB download.
- https://matthias-jentsch.de/ESP32.ova (3.23 GB)
You can easily import this appliance into Virtual Box. The user account is esp32 with password esp32.
Installing the software:
If you like installing all software by yourself you can follow these steps
- Linux OS: Ubuntu 16.10 Desktop 64-bit running as guest on Oracle Virtual Box 5.1.14 on Windows 10
- I’ve also installed the VirtualBox 5.1.14 Oracle VM VirtualBox Extension Pack.
- After installing Ubuntu with the default settings I’ve installed the Virtual Box Guest Additions and activated the bidirectional clipboard.
- I also activated the USB-2.0-Controller in the settings for the Linux guest OS.
- for getting access to the serial port and to the JTAG adapter I put my user account into the dialout and plugdev groups and did a reboot
sudo usermod -a -G dialout $USER sudo usermod -a -G plugdev $USER sudo reboot
Displaying the output from the ESP32 UART is easy with the Putty tool. So I’ve installed it via
sudo apt-get install putty
- For getting the ESP32 toolchain ready I followed the documentation at https://esp-idf.readthedocs.io/en/latest/linux-setup.html
- I downloaded the 64-bit binary toolchain and extracted it to ~/esp/xtensa-esp32-elf/
- Anomalous to the documentation I’ve added the path to the xtensa tools to ~/.profile. Not to ~/.bash_profile
- The IDF_PATH variable I’d also set in the ~/.profile
- I added the following lines at the end of the ~./profile and did a source ~/.profile
- # exports for ESP32
- After that I could do the make menuconfig from step 4.
- I left all settings untouched, saved the configuration, exited menuconfig and executed the make command.
- That brought me to the point where the ESP32 toolchain was ready for compiling
OpenOCD with libftdi
- For debugging with OpenOCD and the Olimex ARM-USB-OCD-H JTAG adapter I did the following steps:
cd ~ sudo apt-get install build-essential git-core cmake doxygen libusb-1.0 make libtool pkg-config autoconf automake texinfo
git clone –recursive https://github.com/espressif/openocd-esp32.git
- Download the sources for libftdi from https://www.intra2net.com/en/developer/libftdi/download/libftdi1-1.3.tar.bz2 and extracted it into the openocd-esp32 directory
- Then I’ve build the libftdi with the following commands
cmake -DCMAKE_INSTALL_PREFIX=“/usr“ ../
sudo make install
- Now I was ready to build OpenOCD for EPS32 with the following commands
sudo make install
- After that I created a new text file and copied the content of the default configuration from here: https://raw.githubusercontent.com/espressif/esp-idf/master/docs/esp32.cfg into the text file
- In this file I changed the following settings:
source [find interface/ftdi/olimex-arm-usb-ocd-h.cfg] adapter_khz 2000 esp108 flashbootstrap 3.3
- The I saved this file to ~/openocd-esp32/esp32.cfg
- I also copied the file ~/openocd-esp32/contrib/99-openocd.rules into the /etc/udev/rules.d directory.
For running Eclipse I’ve installed the OpenJDK 8 via
sudo apt-get install openjdk-8-jre
- Then I’ve downloaded Eclipse Neon installer from https://www.eclipse.org/downloads/
- After unpacking the Eclipse installer package into ~/eclipse-installer I’ve started the eclipse-inst and installed the Eclipse IDE for C++ Developers into the default directory.
- Then start Eclipse
- Open a browser goto http://gnuarmeclipse.github.io/plugins/install/ and drag and drop the Install button to the running Eclipse
- Check the following features of the GNU ARM Eclipse Plug-ins
- GNU ARM C/C++ Cross Compiler
- GNU ARM C/C++ OpenOCD Debugging
- Click Confirm, accept the license agreement and click finish
Building the template app with Eclipse
For getting the template app (an blinky example) compiling in Eclipse I followed the documentation at: https://esp-idf.readthedocs.io/en/latest/eclipse-setup.html Additionally to the steps described I did the following:
- Added the targets „all“ and „flash“ via right click at the project => Build Targets => Create…
- After building the target „all“ I rebuild the index via right click at the project => Index => Rebuild
Creating the debugger configuration
For configuring the debugger in Eclipse I followed in general this documentation: http://gnuarmeclipse.github.io/debug/openocd/#create-the-debugger-configuration but with the following changes:
- Debugger tab:
- Options: -s /home/esp32/openocd-esp32/tcl -f /home/esp32/openocd-esp32/esp32.cfg
- Executable: xtensa-esp32-elf-gdb
- Startup tab:
- Uncheck „Enable ARM semihosting“
- Uncheck „Load executable“
- Set breakpoint at: „app_main“; not „main“
With this configuration you will always break at the first available instruction.
Connecting the hardware
Connecting the FTDI232 USB to Serial adapter to the ESP-WROOM-32
For flashing via this adapter I’ve connected the adapter to the ESP-WROOM-32 board. I found the ESP-WROOM-32 pinout here: https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf
- GND => GND
- 3.3V => 3.3V
- ChipPU via 1.5kΩ resistor to 3.3V and via button to GND; that’s the reset button
- GPIO0 via button to GND; holding this button down during reset will the the UART download mode
- GPIO4 via 330Ω resistor to the anode of a LED; cathode of the LED to GND
- U0RXD => TX of the FTDI232 adapter
- U0TXD => RX of the FTDI232 adapter
Connecting the Olimex ARM-USB-OCD-H to the ESP-WROOM-32
I’ve connected the following 7 pins of the 20 pin JTAG adapter to the ESP-WROOM-32 board:
- ESP32 3.3V => JTAG Pin 1 – VREF
- ESP32 ChipPU => JTAG Pin 3 – TTRST_N
- ESP32 GND => JTAG Pin 4 – GND
- ESP32 MTDI => JTAG Pin 5 – TTDI
- ESP32 MTMS => JTAG Pin 7 – TTMS
- ESP32 MTCK => JTAG Pin 9 – TTCK
- ESP32 MTDO => JTAG Pin 13 – TTDO
Connect the adapters to the Linux guest and establish a serial connection with putty
Connect both adapters (serial and JTAG) to the USB interfaces of the host computer and then connect both adapters to the Linux guest via Virtual Box menu Devices => USB => FTDI FT232R USB UART and Devices => USB => Olimex OpenOCD JTAG ARM-USB-OCD-H
Then I did a serial connection with putty and the following settings:
- Connection type: Serial
- Serial line: /dev/ttyUSB0
- Speed: 115200
During power on of the ESP-WROOM-32 module I hold down the button on GPIO0 pin. In putty I found the following message:
rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)) waiting for download
After that test I disconnected putty.
Flashing the template app with Eclipse
If the ESP-WROOM-32 is in download mode you simply build the „flash“ target in Eclipse and wait until the download of the template app into the ESP32 flash is done. After that you can reset the ESP32 and see that you LED is blinking.
In Eclipse you can choose now Run => Debug Configurations…, select under GDB OpenOCD Debugging the app-template configuration and click Debug. If all is working fine you LED stops blinking and you will break in ipc.c:ipc_task. That’s the fist code that’s executed after booting. Now you can press F8 and stop in app_main.
Now you can debug the template app step-by-step, inspect variables, set breakpoints and so on…