Skip to content

Manage the Espressif ESP32 boards

Install

To install the ESP32 boards,

  • Ensure the Arduino tools, CLI or IDE, are installed.

  • Ensure the arduino-cli.yaml configuration file for Arduino-CLI or the Additional boards manager URLs for Arduino IDE includes

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

  • Open a Terminal window.

  • Run

$
arduino-cli core install esp32:esp32

For more information on the installation process,

Additionally, the ESP32 boards supports JTAG debugging with the ESP-Prog programmer-debugger and a specific version of OpenOCD.

Develop

Upload with the ESP-Prog programmer-debugger

The ESP-Prog programmer-debugger provides JTAG debugging and re-routes the serial console.

Proceed as follow:

  • Ensure OpenOCD for ESP32 has been installed. Otherwise, follow the procedure Install the OpenOCD driver for ESP32.

  • Follow the table at Configure Other JTAG Interface and connect power +3.3V and Ground, JTAG TMS, TDI, TCK, TDO and RESET, serial TXD and RXD pins of the board to the corresponding pins of the ESP-Prog programmer-debugger.

  • Connect the external programmer to the USB port.

In case the following message is displayed on the serial console,

Brownout detector was triggered
  • Power the ESP32 board through the +5V pin instead of the +3.3V pin.

The ESP32 board requires up to 400 mA and may exceed what a standard USB port can deliver.

  • Power the ESP32 board with an external power supply.

For more information on the ESP-Prog,

For more information on debugging the ESP32,

Upload with WiFi

Although the ESP32 boards require no specific procedure for an over-the-air upload, the WiFi network needs to be installed and configured successfully before any upload.

Over-the-air upload requires that a sketch based on the ArduinoOTA library has been installed previously and is currently running. Otherwise,

  • Build and upload the BasicOTA example using the Arduino tools, either Arduino-CLI or Arduino IDE.

Before uploading, please

  • Check that the router has discovered the ESP32 board and note the IP address.

  • It is recommended to proceed with a test of the WiFi connection. Either try pinging the board on the Terminal, or uploading a sketch from the Arduino IDE.

  • Ensure the firewall allows port 3232.

Check the running sketch

The over-the-air process is managed by the sketch itself, based on the ArduinoOTA library.

If the ArduinoOTA object isn’t running,

  • Build and upload the BasicOTA example using the Arduino tools, either Arduino-CLI or Arduino IDE.

  • Upload using an USB connection.

Note

The sketch requires twice its size.

Check the WiFi connection

To identify the IP addresses of the ESP32 board,

  • Open a Terminal window.

  • Run the following command.

$

arp -a
esp_a1b2c3 (192.168.240.1) at 12:ef:34:a1:b2:c3 on en0 ifscope [ethernet]

The address 192.168.240.1 gives access to the board.

  • Test the board is connected with ping.
$
ping 192.168.240.1
  • Ensure the firewall allows port 3232.

Enter IP address

During the first compilation, emCode looks for the ESP32 board.

If the ESP32 board isn’t found on the network, a window asks for the IP address.

  • Enter the IP address of the ESP32 board.

  • Click on OK to validate or Cancel to cancel.

When validated, the IP address is saved on the main Makefile of the project.

SSH_ADDRESS = 192.168.240.1

The IP address is only asked once.

  • To erase the IP address, just delete the whole line.

  • To edit the IP address, just change the value of the macro SSH_ADDRESS.

Password isn’t implemented.

Upload Wiring / Arduino sketch

Once the checks have been performed successfully, proceed as follow:

Connect the ESP32 board to the network through WiFi.

  • Launch any of the targets All, Upload or Fast.

A window may ask for allowing incoming network connections.

  • Click on Allow to proceed.

Note

The sketch requires twice its size.

For more information about the installation and use of the over-the-air upload,

Please refer to Arduino library to upload sketch over network to supported Arduino board at the ArduinoOTA repository.

Another procedure turns the ESP32 board into a web server.

Debug

Connect the ESP-Prog to the ESP32 board

The ESP-Prog provides a PROG 2x3 2.54 mm 0.1” connector and a JTAG 2x5 2.54 mm 0.1” connector.

  • Ensure OpenOCD for ESP32 has been installed. Otherwise, follow the procedure Install the OpenOCD driver for ESP32.

  • Follow the table at Configure Other JTAG Interface and connect power +3.3V and Ground, JTAG TMS, TDI, TCK, TDO and RESET, serial TXD and RXD pins of the board to the corresponding pins of the ESP-Prog programmer-debugger.

  • Open a Terminal and launch the command

$
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

This command prevents macOS from enumerating all the ports of the ESP-Prog programmer-debugger as serial ports.

  • Connect the external programmer to the USB port.

In case the following message is displayed on the serial console,

Brownout detector was triggered
  • Power the ESP32 board through the +5V pin instead of the +3.3V pin.

The ESP32 board requires up to 400 mA and may exceed what a standard USB port can deliver.

  • Power the ESP32 board with an external power supply.

At the end of the session,

  • Open a Terminal and launch the command
$
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver

This command allows macOS to automatically enumerate all the ports as serial ports again.

To check whether the FTDI driver is loaded,

  • Open a Terminal and launch the command
$
kextstat | grep FTDI

For more information on the ESP-Prog,

For more information on debugging the ESP32,