Link Search Menu Expand Document (external link)

Lesson 1: Intro to the ESP32

Table of Contents

  1. Programming environment
  2. The Adafruit ESP32 Huzzah32 Feather
    1. The Huzzah32 Specs
    2. ESP32 pin list
    3. Huzzah32 pin diagram
    4. Important notes
    5. ADC2 is only usable when WiFi not activated
    6. Huzzah32 installation instructions for the Arduino IDE
      1. Step 1: Add ESP32 to Arduino Board Manager
      2. Step 2: Install USB to UART Bridge Virtual COM Port Driver
      3. Step 3: Select “Adafruit ESP32 Feather” in board menu
      4. Step 4: Select the appropriate port
  3. Resources
    1. Official ESP32 Documentation
    2. Other
  4. Next Lesson

Image of a variety of ESP32 boards Image from makeradvisor.com. There are literally dozens of ESP32 boards. Search online for comparisons (e.g., link).

The ESP32 is a low-cost, “system-on-a-chip” board with integrated WiFi, Bluetooth, and a Tensilica Xtensa LX6 microprocessor running at 160 or 240 MHz. It is a successor to the massively successful ESP8266. The ESP32 is far more powerful than introductory Arduino boards like the Uno or Leonardo but also more complex.

There are literally dozens of ESP32 boards on the market, including Adafruit’s Huzzah32 and Sparkfun’s ESP32 Thing. Search online for comparisons (e.g., link). We will be using the Huzzah32.

Programming environment

You can program the ESP32 in variety of languages and programming environments, including C/C++, Micropython, Lua, and more. For programming environments, you can use Espressif’s IoT Development Framework (IDF) or VSCode with PlatformIO. Many ESP32 boards have Arduino libraries so you can also use the Arduino IDE, which is what we will do. This greatly simplifies programming the ESP32 (but at a cost of flexibility and efficiency).

The Adafruit ESP32 Huzzah32 Feather

For our course, we will be using Adafruit’s Huzzah32 ESP32 Feather Board, which came out in May 2017. This board is built on Espressif’s ESP32 WROOM module. While a bit more expensive than other ESP32 boards, Adafruit produces reliable, high-quality products and has good customer support (check out the Adafruit forums). In addition, because the Huzzah32 is a “Feather” board, it’s compatible with Adafruit’s expansion board series called Wings (link1, link2).

The Huzzah32 Specs

Name Arduino Uno Huzzah32
Image Arduino Uno ESP32 Huzzah32
Microcontroller 8-bit, 16 MHz ATmega328P 32-bit, 240 MHz dual core Tensilica LX6
Microcontroller Manufacturer Microchip (Atmel) Espressif
System-on-a-chip N/A ESP32
Input voltage (limit) 6-20V Use either USB (5V) or LiPoly (3.7/4.2V)
Operating voltage 5V 3.3V
Flash memory 32KB (0.5KB used by bootloader) 4MB
SRAM 2KB 520KB
GPIO pins 14 21
PWM pins 6 All
Analog inputs 6 14
Wi-Fi N/A 802.11b/g/n HT40 Wi-Fi transceiver
Bluetooth N/A Dual mode (classic and BLE)

Recall that flash memory is where your compiled program is stored and SRAM is where your microcontroller creates and manipulates variables when it runs.

The ESP32 also has 2xI2S Audio, 2xDAC, 2xI2C (only one configured by default in the Feather Arduino IDE support), 3xSPI (only one configured by default in Feather IDE support). See Adafruit overview.

There is a hardware floating point unit (FPU) on ESP32; however, there have been some criticisms about its performance (link1, link2).

The Huzzah32 is not designed for external power supplies, so either use the USB port with a 5V 1A USB wall adapter or by plugging into your computer or a LiPoly battery (3.7/4.2V). Unlike with the Arduino Uno and Leonardo, do not use a 9V battery or you could damage your board!

ESP32 pin list

The official ESP32 pin list is here:

Official ESP32 pin list Screenshot of the ESP32 pin list PDF.

In our code, we will reference the pins based on their GPIO number, their analog input number (prefixed by ‘A’) for analog input, or their touch number (prefixed by ‘T’) for using capacitive touch sensing. We can always use the GPIO number, however (which is just an integer). The ESP32 datasheet often uses the pin name (far left column of the above pin list) to refer to pins.

Huzzah32 pin diagram

So, what do all of these pins do? Oh, so many things!

The pin diagram for the Huzzah32 in the official Adafruit docs is pretty confusing. So, we created our own:

Huzzah32 pin diagram See the Adafruit Huzzah32 docs for details. Right-click and open image in a new tab to zoom in.

Important notes

  • The ESP32 runs on 3.3V power and logic, and unless otherwise specified, GPIO pins are not 5V safe! The BAT pin should generally not be used directly as the Huzzah32 has a JST connection for the LiPoly battery. You should most definitely not hook up a 9V connection here.
  • There are 21 GPIO pins; however, on the Huzzah32, pins 34 (A2), 39 (A3), 36 (A4) are not output-capable and thus should only be used for input. So, 18 GPIO pins in total. Be forewarned: the pins are in a strange order, so read the diagram carefully.
  • PWM is possible on all 18 GPIO pins
  • 14 of the 21 GPIO pins can be used analog input pins; however, A13 is not exposed. It’s used for measuring the voltage on the LiPoly battery via a voltage divider. When reading in the battery level using analogRead(A13), make sure to multiply by 2 to get correct reading. Here’s an initial program to read and print out the battery level to Serial (link)
  • The ADC resolution is 12 bits (0-4095). This is in contrast to the Arduino Uno and Leonardo, which uses ATmega chips with 10 bit ADCs (so, 0-1023). Make sure you use the proper max value in your conversions (e.g., using map())
  • GPIO 13 is the LED_BUILTIN (the red LED next to micro USB)
  • The charging circuit light will flash quickly when there is no LiPoly battery plugged in. It’s harmless and doesn’t mean anything. This LED will also flash (more slowly) when the battery is plugged in and charging. The battery charges automatically when plugged in and the Huzzah32 is externally powered.
  • Only power your Huzzah32 either using the USB plug (max 5V, 1A) or a LiPoly battery (3.7/4.2V)

Animation of all 18 GPIO output pins fading in and out

The Huzzah32 has 21 GPIO pins; however pins 34 (A2), 39 (A3), 36 (A4) are not output-capable. In this animation, we are attempting to fade in/out all 21 GPIO pins and demonstrating that only 18 work for output.

ADC2 is only usable when WiFi not activated

The Adafruit docs state (somewhat confusingly) that ADC#1 only works when WiFi has started. We empirically tested this (see video below) and found this not to be true. On the other hand, the Espressif docs state that ADC#2 only works when WiFi has not started. We did find this to be true. So, we believe the Espressif docs are right and the Adafruit docs are wrong. Update: it turns out that the Adafruit docs are accurate but just poorly phrased. Indeed, ADC#1 is the only ADC that works when using WiFi (see Reddit post).

Indeed, we empirically tested this. Check out our two programs:

  • AnalogInputTest.ino reads from all analog input pins and prints the values to Serial (so you can view them in Serial Console or Serial Plotter)
  • WiFiAnalogInputTest.ino extends AnalogInputTest but turns on WiFi.

In the following video, I’m using AnalogInputTest.ino to test all 13 analog input pins (A0 - A12) using a trim potentiometer for input and the Serial Plotter for output.

Huzzah32 installation instructions for the Arduino IDE

You can follow the official Adafruit Huzzah32 Arduino IDE installation instructions, which we’ve expanded a bit below.

Step 1: Add ESP32 to Arduino Board Manager

  1. Open the Arduino IDE

  2. Go to Preferences Screenshot of opening preferences

  3. In preferences, find the Additional Board Manager URLs: field Screenshot of additional board manager url in preferences

  4. Add the ESP32 JSON url https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json Screenshot of entering in ESP32 JSON string

  5. Open the Arduino IDE Board Manager Screenshot of the Arduino IDE opening the board manager

  6. Search for ESP32 and click Install Screenshot showing ESP32 added to board manager

Step 2: Install USB to UART Bridge Virtual COM Port Driver

As noted in the official Adafruit Huzzah32 Arduino IDE installation instructions, the second step is to install the USB to UART Bridge Virtual COM Port (VCP) driver to interface with the ESP32 board. You can download the driver from Windows, Mac, and Linux here.

Step 3: Select “Adafruit ESP32 Feather” in board menu

Once installed, select the Adafruit ESP32 Feather in the Board menu.

Screenshot showing how to select the Adafruit ESP32 in the Board Manager menu

Step 4: Select the appropriate port

Finally, select the appropriate port

Screenshot showing how to select correct ESP32 port

Resources

Official ESP32 Documentation

Other

Next Lesson

In the next lesson, you will write your first ESP32 program using the ESP32 Arduino library.

Next: Blink an LED with ESP32


This website was developed by Professor Jon E. Froehlich and the Makeability Lab using Just the Docs. If you found the website useful or use it in your teaching, we'd love to hear from you: jonf@cs.uw.edu. This website and all code is open source (website GitHub, Arduino GitHub, p5js GitHub). You can find the MakeabilityLab_Arduino_Library here. Found an error? File a GitHub Issue.