ESP32 Arduino Setup: Difference between revisions

Latest revision as of 15:53, 8 March 2023

[work in progress]

Arduino IDE setup for ESP32

This guide walks you through setting up the legacy Arduino IDE for use with ESP32 devkit v1 module as well as installation of the libraries we most use during H&D workshops. The instructions are for Arduino IDE version 1.x, but should mostly make sense for version 2.x as well. The reason we're using the older version of the IDE is because there isn't any way in the new version to upload files to the ESP32 board.

This page only documents the installation of the ESP32 support for the Arduino IDE. Next steps may involve:

Installation

Download IDE

First, download the Legacy Arduino IDE.

Download the Arduino software here: Arduino Download.

Pick the installer appropriate for your system.

If necessary you can follow one of these guides:

Installing Arduino
- Windows
- Mac OSX
- Linux

Install ESP32 Boards

Next we need to install an extension that makes it possible to program the ESP32 modules from the Arduino IDE.

Arduino IDE settings Open the Arduino Setting by going to: - Windows/Linux: Menu > File > Preferences... - MacOS: Menu > Arduino > Preferences...

Copy and paste the following into ‘Additional Boards Manager URLs’ and click ‘Ok’.

https://dl.espressif.com/dl/package_esp32_index.json

Screenshot of the popup window for adding board urls

Optional:

Change the compilation and upload process display mode to ‘verbose mode’
Check ‘compile’ and ‘upload’ in ‘Show verbose output during:’

Launch the Board Manager Go to the menu Tools > Boards > Board manager...

Screenshot showing where to find the board manager panel: Menu > Tools > Board > Boards Manager

Arduino board manager popup window

Type ‘esp32’ in the search box and click ‘Install’

Board manager pop-up with esp32 typed into search box

Install drivers

For your computer to be able to communicate with the ESP32 board you need device drivers. If you have already installed the SiLabs driver you can skip this step. If you're unsure, check the step Check if the USB driver are working below.

Installing a USB device driver to communicate with the ESP32 module (chip name: SiliconLabs CP2012)

Linux 3.x.x & 4.x.x

Driver installation not required (included in kernel)
- udev rules update required
- 99-platformio-udev.rules

Linux 2.6.x

Linux 2.6.x - No information

Windows

Mac OS

Check if you already have this driver installed by searching your machine for a file named “SiLabsUSBDriver.kext” AND/OR “SiLabsUSBDriverYos.kext” AND/OR “SiLabsUSBDriver64.kext”. On a Mac, they can be in either of these folders listed below, depending on your system. If you find nothing, proceed to install. Otherwise, uninstall using the uninstaller provided, before re-installing (drag the uninstall.sh file into a terminal window and hit enter to uninstall.
- /Library/Extensions/SiLabsUSBDriver.kext
- /Library/Extensions/SiLabsUSBDriverYos.kext
- /System/Library/Extensions/SiLabsUSBDriver64.kext
- /System/Library/Extensions/SiLabsUSBDriver.kext

Download the driver: Silabs USB communication chip driver download
Doubleclick “Install CP210x VCP Driver.app” to install it.
When it gives a security message, follow the instructions to allow the install to continue

Check if the USB driver are working

If you just installed the driver, restart your computer.
For Mac OS users: after restarting, make sure GateKeeper does not interfere with driver loading.
If you have problems, please check out this MacOS troubleshooting page.

If communication is possible, you should be able to select the port under: Menu > Tools > Port > ...

The name of the port may vary depending on your operating system.

- On Windows it will probably called COM* where * is a number, ie. COM4.
- On linux it will be called /dev/ttyUSB* where * is a number, ie /dev/ttyUSB0
- On MacOS it will be called /dev/cu.SLAB_USBtoUART as shown in the picture below.
  
  screenshot of Arduino window with menu Tools-Port-SLAB_USBtoUART selected

Install libraries

At this point you probably continue installing necessary libraries and uploading to the ESP32

Optional additional steps

Adjust ESP32 Dev Module board settings

Changing the settings below will increase the speed with which your webpages will be uploaded to the board.

Look up the board settings under > Tools > Most of these settings are correct by default, you just have to change QIO to DIO

Board: ESP32 Dev module
Upload Speed : 921600
CPU Frequency : 240MHz (WiFi BT)
Flash Frequency : 80MHz
Flash Mode : **DIO** (is QIO by default)
Flash Size : 4MB (32Mb)
Partition Scheme : Default
Core Debug Level : None
PSRAM : Disabled

Screenshot of board settings under > Tools in Arduino window

Increasing the upload capacity of the board (at your own risk)

It is possible to increase the upload capacity of the board so you can make slightly bigger websites. This is documented by Doohoyi from Dianaband, but we haven’t tried it. Proceed at your own risk!

Dianaband’s workshop documentation

Troubleshooting

We have collected various troubleshooting tips on the ESP32 Mac troubleshooting page

Acknowledgments

Is document is heavily based on the wonderful documentation of Dianaband: https://github.com/applecargo/WifiZineThrowie/blob/master/docs/index.md

@@ Line 1: / Line 1: @@
+[[Category:Tools]]
 [work in progress]
 == Arduino IDE setup for ESP32 ==
-This guide walks you through setting up the Arduino IDE for use with ESP32 devkit v1 module as well as installation of the libraries we most use during H&D workshops.
+This guide walks you through setting up the legacy Arduino IDE for use with ESP32 devkit v1 module as well as installation of the libraries we most use during H&D workshops.
-The instructions are for Arduino IDE version 1.x, but should mostly make sense for version 2.x as well.
+The instructions are for Arduino IDE version 1.x, but should mostly make sense for version 2.x as well. The reason we're using the older version of the IDE is because there isn't any way in the new version to upload files to the ESP32 board.
+This page only documents the installation of the ESP32 support for the Arduino IDE. Next steps may involve:
+* [[Installing ESP32/Arduino libraries]]
+* [[Uploading a website to the ESP32 module]]
 == Installation ==
 === Download IDE ===
-First, download the Arduino IDE.
+First, download the Legacy Arduino IDE.
 * Download the Arduino software here: [https://www.arduino.cc/en/Main/Software '''Arduino Download'''].
@@ Line 90: / Line 96: @@
 == Install libraries ==
-These are all optional depending on the workshop your following.
+At this point you probably continue [[Installing ESP32/Arduino libraries|installing necessary libraries and uploading to the ESP32]]
-=== ESPAsyncWebServer ===
+== Optional additional steps ==
-# [https://github.com/me-no-dev/ESPAsyncWebServer/archive/refs/heads/master.zip Download the code]
+=== Adjust ESP32 Dev Module board settings ===
-# Unzip the downloaded file.
-# Remove the "-master" part from the unzipped directory name, so <code>ESPAsyncWebServer-master</code> should now be called <code>ESPAsyncWebServer</code>
-# Move the renamed directory to your library directory:
-* On Windows: <code>My Documents\Arduino\libraries</code>
-* On Linux: <code>{sketchbook folder}/libraries</code>. The sketchbook folder location can be found (or changed) at File > Preferences > Sketchbook location:. This is the location of libraries installed via Library Manager (Sketch > Include Library > Manage Libraries…) or Sketch > Include Library > Add .ZIP Library. You should also manually install libraries to that location.
-* On MacOS: <code>~/Documents/Arduino/libraries</code>
-=== AsyncTCP ===
-Much the same as above:
-# [https://github.com/me-no-dev/AsyncTCP/archive/refs/heads/master.zip Download the code]
-# Unzip the downloaded file.
-# Remove the "-master" part from the unzipped directory name, so <code>AsyncTCP-master</code> should now be called <code>AsyncTCP</code>
-# Move the renamed directory to your library directory (See above).
-''Restart the IDE after installation.''
-== Confirming code compilation ==
-* Restart the Arduino IDE (the Arduino software)
-* Create a new sketch.
-* Copy/paste the following code. This code does nothing, but if it compiles and upload without errors we know that everything is installed correctly.
-<syntaxhighlight lang="c">
-#include <WiFi.h>
-#include <AsyncTCP.h>
-#include <ESPAsyncWebServer.h>
-void setup() {
+Changing the settings below will increase the speed with which your webpages will be uploaded to the board.
-}
-void loop() {
-}
-</syntaxhighlight>
-* Select the ESP32 Dev Module board
-[[File:Arduino-wifizine-select-board.png|500px|frame|none|alt=Screenshot of Arduino menu open at > Tools > Board > ESP32 Dev Module|Screenshot of Arduino menu open at > Tools > Board > ESP32 Dev Module]]
-== Compile ==
-Click on the compile button in the top left of the editor (see red arrow in pic beneath)
-[[File:Arduino-wifizine-popup.png|500px|frame|none|alt=arduino window with red arrow pointing to the compile button on the top left|Arduino window with red arrow pointing to the compile button on the top left]]
-* '''If the compilation process is successful, it will say “DONE COMPILING” at the bottom'''
-* This means Arduino confirms it can find everything it needs to upload working code
-* Don’t upload the code to the board yet, first we need some more stuff
-[[File:Arduino-wifizine-compile-done.png|500px|frame|none|alt=Screenshot of Arduino window with “done compiling” message in the bottom bar of the window|Screenshot of Arduino window with “done compiling” message in the bottom bar of the window]]
-* '''If the compilation process ends abnormally, it will give an orange error'''
-* If necessary, troubleshoot using the error messages (if you don’t get any, check that “verbose” is checked in settings of Arduino.
-[[File:Arduino-wifizine-compile-failed.png|500px|frame|none|alt=Arduino window with an orange error message|Arduino window with an orange error message]]
-=== Upload to the Board ===
-* Click on the Upload button (arrow pointing right on top of the Arduino window), and then '''''while''''' the text ‘''Connecting …''’ displays in the control window at the bottom of the screen, [https://randomnerdtutorials.com/solved-failed-to-connect-to-esp32-timed-out-waiting-for-packet-header/ press and hold the’ BOOT ’button on the ESP board for one second].
-[[File:Arduino-connecting.jpg|500px|frame|none|alt=when the output window in Arduino says CONNECTING, push the boot button on the board|when the output window in Arduino says CONNECTING, push the boot button on the board]]
-*'''If the upload was successful, you will see this screen''':
-[[File:Arduino-wifizine-upload-done.png|500px|frame|none|alt=output window in Arduino stating Leaving...Hard resetting via RTS pin....|output window in Arduino stating Leaving...Hard resetting via RTS pin....]]
-*'''If the upload was unsuccessful, you will see this error'''
-[[File:Arduino-wifizine-upload-failed.png|500px|frame|none|alt=arduino window with an orange error message|arduino window with an orange error message]]
-[https://randomnerdtutorials.com/esp32-troubleshooting-guide/ Troubleshooting tips for various problem factors here]
-'''Mac OS Monterey issue during upload'''
-* If you’re using Mac OS Monterey, you might get an error like this in the Arduino output window:
-” ''exec: “python”: executable file not found in $PATH error on mac monterey'' ”
-If that happens, open a Terminal window, and paste the code below to install the right version of Python in the right place. Then hit enter.
-<code>sed -i -e 's/=python /=python3 /g' ~/Library/Arduino15/packages/esp32/hardware/esp32/*/platform.txt</code>
-* Now restart the Arduino application and try uploading the code to the board again.
-=== Adjust ESP32 Dev Module board settings ===
 Look up the board settings under &gt; Tools &gt; Most of these settings are correct by default, you just have to change QIO to DIO
@@ Line 178: / Line 114: @@
 * Core Debug Level : None
 * PSRAM : Disabled
-<img src="./images/arduino-wifizine-config-board.png" alt="Screenshot of board settings under > Tools in Arduino window” width=“350”/>
+[[File:Arduino-wifizine-config-board.png|500px|frame|none|alt=Screenshot of board settings under > Tools in Arduino window|Screenshot of board settings under > Tools in Arduino window]]
 === Increasing the upload capacity of the board (at your own risk) ===
@@ Line 186: / Line 122: @@
 [https://github.com/applecargo/WifiZineThrowie/blob/master/docs/index.md#increasing-the-upload-capacity-of-the-board-optional Dianaband’s workshop documentation]
+== Troubleshooting ==
+We have collected various troubleshooting tips on the [[ESP32 Mac troubleshooting]] page
 == Acknowledgments ==
 Is document is heavily based on the wonderful documentation of Dianaband: https://github.com/applecargo/WifiZineThrowie/blob/master/docs/index.md