In case you want to provide your own sdkconfig.default, you can set the CMake variable IDF_SDKCONFIG_DEFAULTS, from the command line:
cmake S . B builddirectory DIDF_SDKCONFIG_DEFAULTS=path_to_your_sdkconfig_defaults -DCMAKE_TOOLCHAIN_FILE=freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja
If you don't specify a location for your own sdkconfig.default file, FreeRTOS uses the default file located at freertos/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults.
Summary
If you have a project with a component called example_component, and you want to override some configurations, here's a complete example of the top level CMakeLists.txt file.
cmake_minimum_required(VERSION 3.13) project(freertos_examples)
set(IDF_PROJECT_EXECUTABLE my_app)
58
Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT set(IDF_EXECUTABLE_SRCS "src/main.c")
# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)
# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
EXTRA_COMPONENT_DIRS
"components/example_component" ABSOLUTE )
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})
# Override the configurations for FreeRTOS.
include_directories(BEFORE freertos-configs)
# Add FreeRTOS as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "") add_subdirectory(freertos)
# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::core_mqtt)
Troubleshooting
• If you're running macOS and the operating system doesn't recognize your ESP-WROVER-KIT, make sure you don't have the D2XX drivers installed. To uninstall them, follow the instructions in the FTDI Drivers Installation Guide for macOS X.
• The monitor utility provided by ESP-IDF (and invoked using make monitor) helps you decode
addresses. For this reason, it can help you get some meaningful backtraces in the event the application stops working. For more information, see Automatic Address Decoding on the Espressif website.
• It's also possible to enable GDBstub for communication with gdb without requiring any special JTAG hardware. For more information, see Launching GDB with GDBStub on the Espressif website.
• For information about setting up an OpenOCD-based environment if JTAG hardware-based debugging is required, see JTAG Debugging on the Espressif website.
• If pyserial can't be installed using pip on macOS, download it from the pyserial website.
• If the board resets continuously, try erasing the flash by entering the following command on the terminal.
make erase_flash
• If you see errors when you run idf_monitor.py, use Python 2.7.
• Required libraries from ESP-IDF are included in FreeRTOS, so there is no need to download them externally. If the IDF_PATH environment variable is set, we recommend that you clear it before you build FreeRTOS.
• On Windows, it can take 3-4 minutes for the project to build. To reduce the build time, you can use the -j4 switch on the make command.
make flash monitor -j4
• If your device has trouble connecting to AWS IoT, open the aws_clientcredential.h file, and verify that the configuration variables are properly defined in the file.
clientcredentialMQTT_BROKER_ENDPOINT[] should look like 1234567890123-ats.iot.us-east-1.amazonaws.com.
• If you're following the steps in Using FreeRTOS in your own CMake project for ESP32 (p. 55) and you see undefined reference errors from the linker, it's usually because of missing dependent
Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT
libraries or demos. To add them, update the CMakeLists.txt file (under the root directory) using the standard CMake function target_link_libraries.
• ESP-IDF v4.2 supports the use of the xtensa\-esp32\-elf\-gcc 8\.2\.0\. toolchain. If you're using an earlier version of the Xtensa toolchain, download the required version.
• If you see an error log like the following about python dependencies that are not being met for ESP-IDF v4.2:
The following Python requirements are not satisfied:
click>=5.0
Please follow the instructions found in the "Set up the tools" section of ESP-IDF Getting Started Guide
Install the python dependencies on your platform using the following Python command:
root/vendors/espressif/esp-idf/requirements.txt
For more troubleshooting information, see Troubleshooting getting started (p. 22).
Debugging
Debugging code on Espressif ESP32-DevKitC and ESP-WROVER-KIT (ESP-IDF v4.2)
This section shows you how to debug Espressif hardware using ESP-IDF v4.2. You need a JTAG to USB cable. We use a USB to MPSSE cable (for example, the FTDI C232HM-DDHSL-0).
ESP-DevKitC JTAG setup
For the FTDI C232HM-DDHSL-0 cable, these are the connections to the ESP32 DevkitC.
| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| --- | --- | --- |
For the FTDI C232HM-DDHSL-0 cable, these are the connections to the ESP32-WROVER-KIT.
| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| --- | --- | --- |
Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT
These tables were developed from the FTDI C232HM-DDHSL-0 datasheet. For more information, see the section "C232HM MPSSE Cable Connection and Mechanical Details in the data sheet.
To enable JTAG on the ESP-WROVER-KIT, place jumpers on the TMS, TDO, TDI, TCK, and S_TDI pins as shown here.
Debugging on Windows (ESP-IDF v4.2)
To set up for debugging on Windows
1. Connect the USB side of the FTDI C232HM-DDHSL-0 to your computer and the other side as described in Debugging code on Espressif ESP32-DevKitC and ESP-WROVER-KIT (ESP-IDF v4.2) (p. 60). The FTDI C232HM-DDHSL-0 device should appear in Device Manager under Universal Serial Bus Controllers.
2. Under the list of universal serial bus devices, right-click the C232HM-DDHSL-0 device, and then choose Properties.
Note
The device might be listed as USB Serial Port.To see the properties of the device, in the properties window, choose the Details tab. If the device isn't listed, install the Windows driver for FTDI C232HM-DDHSL-0.
3. On the Details tab, choose Property, and then choose Hardware IDs. You should see something like this in the Value field.
FTDIBUS\COMPORT&VID_0403&PID_6014
In this example, the vendor ID is 0403 and the product ID is 6014.
Verify these IDs match the IDs in projects/espressif/esp32/make/aws_demos/
esp32_devkitj_v1.cfg. The IDs are specified in a line that begins with ftdi_vid_pid followed by a vendor ID and a product ID.
ftdi_vid_pid 0x0403 0x6014 4. Download OpenOCD for Windows.
5. Unzip the file to C:\ and add C:\openocd-esp32\bin to your system path.
6. OpenOCD requires libusb, which is not installed by default on Windows. To install libusb:
Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT a. Download zadig.exe.
b. Run zadig.exe. From the Options menu, choose List All Devices.
c. From the dropdown menu, choose C232HM-DDHSL-0.
d. In the target driver field, to the right of the green arrow, choose WinUSB.
e. For the list under the target driver field, choose the arrow, and then choose Install Driver.
Choose Replace Driver.
7. Open a command prompt, navigate to the root of your FreeRTOS download directory, and run the following command.
idf.py openocd
Leave this command prompt open.
8. Open a new command prompt, navigate to the root of your FreeRTOS download directory, and run
idf.py flash monitor
9. Open another command prompt, navigate to the root of your FreeRTOS download directory, and wait until the demo starts running on your board. When it does, run
idf.py gdb
The program should stop in the main function.
Note
The ESP32 supports a maximum of two break points.Debugging on macOS (ESP-IDF v4.2) 1. Download the FTDI driver for macOS.
2. Download OpenOCD.
3. Extract the downloaded .tar file and set the path in .bash_profile to OCD_INSTALL_DIR/
openocd-esp32/bin.
4. Use the following command to install libusb on macOS.
brew install libusb
5. Use the following command to unload the serial port driver.
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver 6. Use the following command to unload the serial port driver.
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
7. If you're running a macOS version later than 10.9, use the following command to unload the Apple FTDI driver.
sudo kextunload -b com.apple.driver.AppleUSBFTDI
8. Use the following command to get the product ID and vendor ID of the FTDI cable. It lists the attached USB devices.
62
Getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT
system_profiler SPUSBDataType
The output from system_profiler should look like the following.
DEVICE:
Product ID: product-ID
Vendor ID: vendor-ID (Future Technology Devices International Limited) 9. Open the projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg
file. The vendor ID and product ID for your device are specified in a line that begins with ftdi_vid_pid. Change the IDs to match the IDs from the system_profiler output in the previous step.
10. Open a terminal window, navigate to the root of your FreeRTOS download directory, and use the following command to run OpenOCD.
idf.py openocd
Leave this terminal window open.
11. Open a new terminal, and use the following command to load the FTDI serial port driver.
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver 12. Navigate to the root of your FreeRTOS download directory, and run
idf.py flash monitor
13. Open another new terminal, navigate to the root of your FreeRTOS download directory, and run
idf.py gdb
The program should stop at main.
Debugging on Linux (ESP-IDF v4.2)
1. Download OpenOCD. Extract the tarball and follow the installation instructions in the readme file.
2. Use the following command to install libusb on Linux.
sudo apt-get install libusb-1.0
3. Open a terminal and enter ls -l /dev/ttyUSB* to list all USB devices connected to your
computer. This helps you check if the board's USB ports are recognized by the operating system.
You should see output like the following.
$ls -l /dev/ttyUSB*
crw-rw---- 1 root dialout 188, 0 Jul 10 19:04 /dev/
ttyUSB0
crw-rw---- 1 root dialout 188, 1 Jul 10 19:04 /dev/
ttyUSB1
4. Sign off and then sign in and cycle the power to the board to make the changes take effect. In a terminal prompt, list the USB devices. Make sure the group owner has changed from dialout to plugdev.
Getting started with the Espressif ESP32-WROOM-32SE
$ls -l /dev/ttyUSB*
crw-rw---- 1 root plugdev 188, 0 Jul 10 19:04 /dev/
ttyUSB0
crw-rw---- 1 root plugdev 188, 1 Jul 10 19:04 /dev/
ttyUSB1
The /dev/ttyUSBn interface with the lower number is used for JTAG communication. The other interface is routed to the ESP32's serial port (UART) and is used for uploading code to the ESP32's flash memory.
5. In a terminal window, navigate to the root of your FreeRTOS download directory, and use the following command to run OpenOCD.
idf.py openocd
6. Open another terminal, navigate to the root of your FreeRTOS download directory, and run the following command.
idf.py flash monitor
7. Open another terminal, navigate the root of your FreeRTOS download directory, and run the following command:
idf.py gdb
The program should stop in main().