1874

A tutorial explaining how to get started with the ESP32.

ESP32 and the Arduino IDE

The popular Arduino IDE can be used to develop applications for the ESP32. The Arduino IDE is available for Windows, Mac OS, and Linux (32 and 64 bit).
 


1. Download and install the Arduino IDE (1.8.0 or higher) following the recommended procedures for your operating system.
2. Start the Arduino IDE and open the Preferences window (menu 'Files' -> 'Preferences').
3. Enter 'https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json' into the 'Additional Board Manager URLs' field. (You can add multiple URLs by separating them with commas.) This link may change in the future, so if it doesn't work for you check the Espressif GitHub page. 

 
Arduino IDE Preferences
Add the link to the JSON file to the 'Additional Boards Manager URLs' box. Use comma's to separate multiple URLs.
4. Open the 'Boards Manager' (menu 'Tools' -> 'Board' -> 'Boards Manager...') and search the list for the entry 'esp32 by Espressif Systems'. Click it to make the 'Install' button appear. Click 'Install'. Depending on your internet connection this can take some time.

 
Arduino IDE Boards Manager
Scroll through the list of available Boards packages until you find 'esp32'. Click on the entry to make the Install button appear.

Select ESP32 Board & Port

5. After succesful installation of the esp32 package, select your ESP32 board (menu 'Tools' -> 'Board').

 
Arduino IDE Boards
Select your ESP32 board from the long list of candidates. Note that most are more or less the same.
6. Connect your ESP32 board and select its serial port (menu 'Tools' -> 'Port')

 
Arduino IDE Port
Select the serial port created by your ESP32 board.

Ready to go

7. From the menu 'File' -> 'Examples' -> '01.Basics' you can now load the 'Blink' example. Click the 'Upload' button (arrow to the right) or menu 'Sketch' -> 'Upload'. If all goes well, after some time you will see an LED blink on your ESP32 board.

Not all ESP32 boards have a user LED

Please note that not all ESP32 boards have a user-programmable LED and so the example may fail. When the compilation fails with the message  
'LED_BUILTIN' was not declared in this scope
then your board probably does not have the user LED. The ESP32 DevkitC for instance does not have a user-programmable LED.

The example 'AnalogReadSerial' should work in most cases. Refer to the documentation of your board to locate the analog input pin.

The official Espressif ESP32 Arduino information is found at https://github.com/espressif/arduino-esp32

SPIFFS - uploading sketch data

SPIFFS (SPI Flat File System, i.e. it does not know about directories or folders) is required when you want to store files on the ESP32 module. A typical usecase are webpages and illustrations, etc. that are served by a webserver running on the ESP32. A special tool is required to upload your files into the SPIFFS. Here is how you install it into the Arduino IDE:

1. Install the ESP32 Boards Package in the Arduino IDE as described above.
2. Download the SPIFFS tool from the 'Arduino ESP32 filesystem uploader' page.
3. Depending on your Arduino installation, there are two options:
  1. Arduino Standard Setup. Unpack the downloaded archive to [arduino]\tools. You should end up with  [arduino]\tools\ESP32FS\tool\esp32fs.jar (note the path!)
  2. Arduino Portable Setup. Unpack the downloaded archive to [arduino]\portable\sketchbook\tools. You should end up with  [arduino]\portable\sketchbook\tools\ESP32FS\tool\esp32fs.jar (note the path!)
4. Restart the Arduino IDE. Check the menu 'Tools'. If you see the entry 'ESP32 Sketch Data Upload' then all is well.

 
Arduino IDE SPIFFS
A successful installation of the SPIFFS uploader tool will create this menu entry.

Uploading the files to the SPIFFS

The files that must be copied to the SPIFFS must be placed in a folder named 'data' inside the sketch folder. Simply click 'ESP32 Sketch Data Upload' to start the upload.

For the official SPIFFS uploader documentation see https://github.com/me-no-dev/arduino-esp32fs-plugin

Access Point (AP) mode

The typical chicken-and-egg problem with Wi-Fi connected equipment is that before you can connect to it, you must somehow connect to it so you can connect it to the network. Get it? The ESP32 solves this paradox by providing an Access Point (AP) mode.

192.168.4.1

When the ESP32 is not connected to a network, you can often access it by connecting to the ESP32 network (or some other obvious network name or ID that shows up in the list of available networks) and then pointing a browser to the address 192.168.4.1. The computer, tablet or smartphone running the browser must not be connected to another Wi-Fi network. When doing this with a smartphone it is often preferable to switch off mobile data to prevent the phone from trying the mobile data network to find the address 192.168.4.1.

Once connected to the ESP32 in AP mode, you can configure the parameters for the Wi-Fi network that it should connect to. Make sure to store these parameters in the module's flash memory and restart it. In most (normal usecase) situations the ESP32 will then automatically connect to the chosen Wi-Fi network.