Getting started

This tutorial will show you how to install the tools necessary to program the ESP32 and write your first program.

Warning

The ESP32 board used for this tutorial is the uPesy ESP32 WROOM DevKit

Overview

For beginners, the simplest and most common way to program the ESP32 is using the Arduino IDE software, used to program Arduino boards.It can also be used to program other boards by adding them via its board manager.

For beginners, there is also an alternative called MicroPython. It is possible to program the ESP32 in Python, with less good performance but which allows to benefit from all the advantages of Python. For example, code execution is immediate : you don’t have to wait 20s for the compilation and uploading of the program to be finished. There are however fewer tutorials on the Internet.

For the more advanced, the use of VS Code with PlateformIO is recommended to be able to use all the functions of the board and modify the default parameters. You can also program the board with the ESP-IDF espressif framework directly from PlatformIO.

See also

A tutorial is also available to use the ESP32 with Micro Python or PlatformIO


Arduino IDE

../_images/arduino_ide_pres.png

Arduino IDE software is an IDE specially designed to easily program Arduino boards. It has a simple interface that allows beginners to navigate easily. Many examples and libraries are included to make programming simple and intuitive. Even if the software was originally designed for Arduino boards, you can add extensions to program other types of boards such as ESP32. Many example codes for the ESP32 are available for common sensors but also for WiFi and Bluetooth. It is also very easy to install and use built-in libraries for the ESP32.

This is the software that is recommended for beginners, especially for those who learn programming through Arduino boards and ESP32.

Framework

What made the ESP32 boards so successful is that we can program them with the same language and the same libraries as the Arduino boards. We combine the power of the ESP32 with the simplicity of the Arduino code.

We use the Arduino framework in this tutorial

Important

You must therefore first install the Arduino IDE software, then install specific tools from this software to be able to program the ESP32 with the Arduino framework.

Installation

Here is the steps to install Arduino IDE.

Note

If you already have Arduino IDE installed, check that it is up to date (> 1.8) because some bugs with the ESP32 are due to an older version an can be easily fix by an update

Arduino IDE installation

To install Arduino IDE on Windows :

  • Download the latest version of the software on the Arduino website, by clicking on the first link “Windows Installer, for Windows XP and up”

  • Launch the .exe installation file, then fill in the following boxes:

../_images/arduinoIDE0.PNG
  • In the next window, leave the default installation location

../_images/arduinoIDE1.PNG
  • Then authorize the installation of the drivers:

../_images/arduinoIDE2.PNG ../_images/arduinoIDE3.PNG ../_images/arduinoIDE4.PNG
  • The installation is now complete. A window of this type should appear:

../_images/arduinoIDE5.PNG

Warning

A Windows Firewall window may ask you to allow the application to access the Internet. Accept the authorization to be able to download libraries, updates, maps and tools for the ESP32.

You can currently program only Arduino boards. You need to download other tools to be able to program ESP32 boards

Installation of the esp32 extension to use the Arduino framework

To install the necessary tools, you should:

  • Go to File> Preferences

../_images/arduinoIDE6.PNG
  • Click on Additional Boards Manager URL and add the URL:

https://dl.espressif.com/dl/package_esp32_index.json
../_images/arduinoIDE7.PNG
  • Then go to the Boards manager: Tools > Board > Boards Manager

../_images/arduinoIDE8.PNG
  • Scroll down until you find esp32, and click on install. Once the download and installation are complete, the tools are ready to use.

../_images/arduinoIDE9.PNG
  • ESP32 boards have been added with the other boards:

../_images/arduinoIDE10.PNG
  • If you have an uPesy ESP32 Wroom DevKit board or other ESP32 board, you can choose “ESP32 Dev Module” or ” DOIT ESP32 DEVKIT V1” board. Moreover, to be able to use the additional RAM of the uPesy ESP32 Wrover Devkit board, you must choose a compatible board, such as the “ESP32 Wrover Module” board.

../_images/arduinoIDE11.jpg
  • Installation is now complete, you can program your ESP32 board like a classic Arduino board.

First sketch

Now that all the tools are installed, we will be able to create our first program and send it to the ESP32 board. But before making the first program, you must make sure that you can communicate with the ESP32 board.

Board Detection

Note

ESP32 boards should be automatically detected: there is no need to install additional drivers.

Connect your ESP32 board to your computer via USB (with a USB Micro-B cable). On Windows, when you plug in the board, you should hear the same noise as a USB key but it’s normal to not see the ESP32 board in the file explorer.

Once the board is plugged in, you should see a COM number on Arduino IDE (here COM8).

../_images/arduinoIDE11.png

To receive messages from the board, you must open the serial monitor.

The value that must be changed in the serial monitor is the transmission speed. In general, the serial port common speed with an Arduino board is 9600 bauds (bytes/s). But with the ESP32, the commonly used speed is 115200 bauds. The reason is that the ESP32 sends messages at boot or for low level errors at this speed.

Hint

The serial port speed can be different from 115200 bauds but in this case the low level messages of the ESP32 will not be visible and will appear with incomprehensible characters.

Once the speed is changed, you can communicate with the ESP32.

All uPesy boards come already flashed with a program that blinks the blue LED present on the board and scan nearby Wi-Fi Access Point. With the ESP32 WROOM DevKit board, we then obtain in the serial monitor :

../_images/arduinoIDE12.jpg

The program present by default on ESP32 uPesy boards is available on Github

Your first sketch

Here is a very simple example which blinks the blue led located on the GPIO2 pin of the ESP32 Wroom DevKit board.

void setup () {
  Serial.begin (115200);
  Serial.println ("My first program");

  pinMode (2, OUTPUT);

}

void loop () {
  digitalWrite (2, HIGH); // We turn on the blue led
  delay (500); // We wait for 500 ms
  digitalWrite (2, LOW); // We turn off the blue led
  delay (500); // We wait for 500 ms
}

Tip

The code can be directly copied to the clipboard by clicking on the icon at the top right of the code block

Once you have typed or copied the example code and saved the code, you will have to compile the program.

The first compilation is quite long because all the source files for the ESP32, even those which are not directly used by the program are compiled. Fortunately, only the modified files will be compiled for next compilations.

To do this, simply press the “Verify” button. Then click on the arrow next to upload the program to the ESP32.

Tip

To compile and send immediately after the sketch, click directly on the arrow.

Here are the lines in the console that correspond to the program upload to an ESP32:

esptool.py v2.6
Serial port COM8
Connecting .....
Chip is ESP32D0WDQ5 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 4c: 11: ae: 68: 09: 44
Uploading stub ...
Running stub ...
Stub running ...
Changing baud rate to 921600
Changed.
Configuring flash size ...
Auto-detected Flash size: 8MB
Compressed 8192 bytes to 47 ...

Writing at 0x0000e000 ... (100%)
Wrote 8192 bytes (47 compressed) at 0x0000e000 in 0.0 seconds (effective 4096.0 kbit / s) ...
Hash of data verified.
Flash params set to 0x023f
Compressed 17392 bytes to 11185 ...

Writing at 0x00001000 ... (100%)
Wrote 17392 bytes (11185 compressed) at 0x00001000 in 0.2 seconds (effective 804.3 kbit / s) ...
Hash of data verified.
Compressed 261024 bytes to 123037 ...

Writing at 0x00010000 ... (12%)
Writing at 0x00014000 ... (25%)
Writing at 0x00018000 ... (37%)
Writing at 0x0001c000 ... (50%)
Writing at 0x00020000 ... (62%)
Writing at 0x00024000 ... (75%)
Writing at 0x00028000 ... (87%)
Writing at 0x0002c000 ... (100%)
Wrote 261024 bytes (123037 compressed) at 0x00010000 in 2.4 seconds (effective 866.8 kbit / s) ...
Hash of data verified.
Compressed 3072 bytes to 128 ...

Writing at 0x00008000 ... (100%)
Wrote 3072 bytes (128 compressed) at 0x00008000 in 0.0 seconds (effective 4096.0 kbit / s) ...
Hash of data verified.

Leaving ...
Hard resetting via RTS pin ...

Once the upload is finished, you should see the blue LED blinking faster than before (on uPesy boards).

Note

Once the upload is complete, the ESP32 directly executes the program. It is therefore normal to not see the message “My first program” when you go to the serial monitor. Unlike the Arduino, the ESP32 does not restart when you click on serial monitor button. (In Arduino IDE but not on PlatformIO)

So to see the message, you must either :
  • Add a delay of a few seconds with delay() before the execution of the code

  • Have the serial monitor open before the upload is complete

  • Press the “EN” button on the ESP32 board to do a manual restart.

Congratulations, you have completed your first program on the ESP32 and completed the quick start guide.

In the next section you will find more information about the pinout and functionalities of ESP32 boards from uPesy Electronics.