ESP32 Thing Hookup Guide

Pages
Contributors: jimblom
Favorited Favorite 23

Introduction

The SparkFun ESP32 Thing is a comprehensive development platform for Espressif's ESP32, their super-charged version of the popular ESP8266. Like the 8266, the ESP32 is a WiFi-compatible microcontroller but adds nearly 30 I/O pins. The ESP32’s power and versatility will make it the foundation of IoT and connected projects for many years to come.

SparkFun ESP32 Thing

SparkFun ESP32 Thing

DEV-13907
$23.50
69

The SparkFun ESP32 Thing equips the ESP32 with everything necessary to program, run, and develop on the wonderchip. In addition to the WiFi SoC, the Thing includes an FTDI FT231x, which converts USB to serial, and allows your computer to program and communicate with the microcontroller. It also features a lithium-polymer (LiPo) battery charger, so your ESP32 project can be truly wireless. Additionally, the board includes a handful of LEDs and buttons to aid in your development.

Covered In This Tutorial

This hookup guide serves as a primer on all things ESP32 Thing. It documents hardware features of the board, including a handful of assembly tips. Then it will delve into firmware development -- including demonstrating how to add ESP32 support to the popular Arduino IDE.

The tutorial is broken up into a handful of sections, which you can navigate through using the menu on the right. Those sections include:

Not Yet Implemented
The Arduino board definitions for the ESP32 are still a work in progress. There are a handful of peripherals and features that have yet to be implemented, including:

* Analog Input (analogRead([pin]))
* Analog Ouptut (analogWrite([pin], [value]))
* WiFi Server and WiFI UDP
* Real-Time Clock
* Touch-controller interface

These peripherals are available (if, also, still in their infancy) in the IoT Development Framework for the ESP32. If your application requires analog input, RTC, or any of the features above, consider giving the ESP-IDF a try!

Bill of Materials

The ESP32 Thing includes almost everything you'll need to begin using and programming the WiFi/BT SoC. In fact, the only required extra is a Micro-B USB Cable. The ESP32 Thing's USB interface can be used to both power and program the chip. Once you're done programming the chip, a 5V Micro-B USB Wall Adapter can be used to power the board.

USB Micro-B Cable - 6 Foot

USB Micro-B Cable - 6 Foot

CAB-10215
$5.50
15
USB Micro-B Cable - 6"

USB Micro-B Cable - 6"

CAB-13244
$2.10
3
Wall Adapter Power Supply - 5VDC, 2A (USB Micro-B)

Wall Adapter Power Supply - 5VDC, 2A (USB Micro-B)

TOL-15311
$6.50

SparkFun Cerberus USB Cable - 6ft

CAB-12016
16 Retired

As an alternative power source, the ESP32 Thing includes support for single-cell lithium-polymer (LiPo) batteries, which plug into the board's white 2-pin JST connector. LiPo's are perfect for projects on-the-go, or those that just need a little extra umph. The board includes a LiPo charger -- the rechargeable batteries can be juiced back up by plugging the Thing into a 5V USB source.

Lithium Ion Battery - 400mAh

Lithium Ion Battery - 400mAh

PRT-13851
$5.50
10
Lithium Ion Battery - 2Ah

Lithium Ion Battery - 2Ah

PRT-13855
$13.95
9
Lithium Ion Battery - 850mAh

Lithium Ion Battery - 850mAh

PRT-13854
$10.95
2

Lithium Ion Battery - 1Ah

PRT-13813
8 Retired

Finally, to connect the ESP32's 28 I/O pins to external components, you'll need to do some soldering. Soldering tools, including an iron and solder, are a must for any electronics workbench. And either headers or wire are our recommended mate for soldering into the Thing's pins.

Break Away Headers - Straight

Break Away Headers - Straight

PRT-00116
$1.75
20
Hook-Up Wire - Assortment (Stranded, 22 AWG)

Hook-Up Wire - Assortment (Stranded, 22 AWG)

PRT-11375
$22.50
19
Solder Lead Free - 100-gram Spool

Solder Lead Free - 100-gram Spool

TOL-09325
$9.95
8
Soldering Iron - 30W (US, 110V)

Soldering Iron - 30W (US, 110V)

TOL-09507
$10.95
7

Suggested Reading

It may look intimidating, but the ESP32 Thing -- especially when you take advantage of its Arduino compatibility -- is a perfect IoT foundation for electronics users of all experience levels. There are, however, a few concepts you should be familiar with before venturing further into this tutorial. If any of the concepts below sound foreign to you, consider reading through that tutorial first:

How to Solder: Through-Hole Soldering

This tutorial covers everything you need to know about through-hole soldering.

Serial Communication

Asynchronous serial communication concepts: packets, signal levels, baud rates, UARTs and more!

How to Power a Project

A tutorial to help figure out the power requirements of your project.

What is an Arduino?

What is this 'Arduino' thing anyway? This tutorials dives into what an Arduino is and along with Arduino projects and widgets.

Looking to get hands-on with ESP32?

We've got you covered!

SparkFun ESP32 Thing

SparkFun ESP32 Thing

DEV-13907
$23.50
69
ESP32 Thing Stackable Header Set

ESP32 Thing Stackable Header Set

PRT-14311
$1.75

SparkFun ESP32 Thing Power Control Shield

DEV-14155
Retired

SparkFun ESP32 Thing Motion Shield

DEV-14430
1 Retired

Hardware Overview

Espressif's ESP32 is one of the most unique microcontrollers on the market. Its laundry list of features include:

  • Dual-core Tensilica LX6 microprocessor
  • Up to 240MHz clock frequency
  • 520kB internal SRAM
  • Integrated 802.11 BGN WiFi transceiver
  • 2.2 to 3.6V operating range
  • 2.5 µA sleep current under hibernation
  • 32 GPIO
  • 10-electrode capacitive touch support
  • Hardware accelerated encryption (AES, SHA2, ECC, RSA-4096)

The ESP32 Thing is designed to surround the ESP32 with everything necessary to run and program the microcontroller, plus a few extra goodies to take advantage of the chip's unique features.

Annotated top diagram

Peripherals and I/O

The ESP32 features your standard fare of hardware peripherals, including:

And, thanks to the chip's pin multiplexing feature, those peripherals can be connected to just about any of the 28 broken out I/O pins. That means you decide which pins are RX, TX, MISO, MOSI, SCLK, SDA, SCL, etc.

There are, however, a few hardware features -- namely the ADC and DAC -- which are assigned static pins. The graphical reference below helps demonstrate where you can find those peripherals (click to embiggen!).

Graphical Datasheet

Click the image for a closer look.

One I2C, two of the UART interfaces, and one of the SPI interfaces can be assigned to any pin your project requires.

Input Only Pins: 34-39

Pins 34, 35, 36, 37, 38 and 39 cannot be configured as outputs, but they can be used as either digital inputs, analog inputs, or for other unique purposes. Also note that they do not have internal pull-up or pull-down resistors, like the other I/O pins.

GPIO pins 36-39 are an integral part of the ultra low noise pre-amplifier for the ADC – they are wired up to 270pF capacitors, which help to configure the sampling time and noise of the pre-amp.

Schematic close up of pins 34-39

From the ESP32 Thing Schematic: GPIO 36-39 are tied together with caps. Those and pins 34 and 35 are input only!

Powering the ESP32 Thing

The two main power inputs to the ESP32 Thing are USB and a single-cell lithium-polymer (LiPo) battery. If both USB and the LiPo are plugged into the board, the onboard charge controller will charge the LiPo battery at a rate of up to 500mA.

The ESP32's operating voltage range is 2.2 to 3.6V. Under normal operation the ESP32 Thing will power the chip at 3.3V. The I/O pins are not 5V-tolerant! If you interface the board with 5V (or higher) components, you'll need to do some level shifting.

The 3.3V regulator on the ESP32 Thing can reliably supply up to 600mA, which should be more than enough overhead for most projects. The ESP32 can pull as much as 250mA during RF transmissions, but we've generally measured it to consume around 150mA -- even while actively transmitting over WiFi. The output of the regulator is also broken out to the sides of the board -- the pins labeled "3V3." These pins can be used to supply external components.

ESP32 power inputs/outputs

In addition to USB and battery connectors, the VBAT, and VUSB pins are all broken out to both sides of the board. These pins can be used as an alternative supply input to the Thing. The maximum, allowable voltage input to VUSB is 6V, and VBAT should not be connected to anything other than a LiPo battery. Alternatively, if you have a regulated voltage source between 2.2V and 3.6V, the "3V3" lines can be used to directly supply the ESP32 and its peripherals.

Board Dimensions

The board is 2.32"x1.00".

Board Dimensions

Assembly Tips

The ESP32 Thing ships without anything soldered into the header pins -- ensuring that you can mold the board to best fit your project. To use the chip's pins you'll need to solder something to the I/O and power rail vias broken out to either side of the board.

New to soldering? Check out our Through-Hole Soldering Tutorial for a quick introduction!

What you solder to the ESP32 Thing's I/O pins is completely up to you. The header rows are breadboard-compatible, so you may want to solder male headers in. (Mildly satisfying: the ESP32 Thing's pair of 20-pin headers means you can get the most out of our 40-pin header strips.)

ESP32 Thing with male headers soldered

Then plug it into the breadboard, hanging the USB and LiPo connectors off the end, and start wiring!

ESP32 Thing breadboard action shot

All those wires and components, and there are still plenty of GPIO left to use!

Alternatively, female headers (you may need two separate strips to solder all 40 pins), right-angle headers, or stranded wire are all good options, depending on your project's needs.

Installing via Arduino IDE Boards Manager

Good news! Espressif has added support for the Arduino Boards Manager and by installing this way, you get the benefit of a slew of great built-in examples. Instructions for installing via the board manager can be found at espressif's Arduino-ESP32 Read the Docs.

For more information on installing boards via the Arduino Board Manager, check out the Installing Board Definitions in the Arduino IDE tutorial.

Installing Board Definitions in the Arduino IDE

September 9, 2020

How do I install a custom Arduino board/core? It's easy! This tutorial will go over how to install an Arduino board definition using the Arduino Board Manager. We will also go over manually installing third-party cores, such as the board definitions required for many of the SparkFun development boards.

If you are familiar with installing boards via the Arduino IDE Boards Manager, the url to add is:

language:bash
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
Warning: If you have previously installed the ESP32 Arduino Core via the instructions in Install Option 2, we strongly recommend removing the associated folders before installing via the boards manager.

To remove previous arduino core installs for the esp32, start by finding your .../Arduino/hardware folder. This can be located by looking at your Sketchbook location under File > Preferences.



Go to this location in your finder and delete the esp32 folder.


Once you have deleted the esp32 folder, you can then install using the Arduino Boards Manager.

If you have successfully installed the ESP32 core to your Arduino IDE, you should see the following under Tools with the ESP32 Dev Module selected:

Tools menu with Board: ESP32 Dev Module option selected

Installing the ESP32 Arduino Core

For the more advanced or adventurous route, you can skip the Arduino IDE Boards Manager and install the ESP32 Arduino Core. The pair of Tensilica cores in the ESP32 are Xtensa-based – not your standard ARM or AVR. Fortunately, there is still a GNU compiler available for the ESP32, which opens up a world of possible development environment (IDE) set ups! The rest of this section covers setting up the Arduino IDE with ESP32 support.

In abstracting away a lot of the complicated overhead, the Arduino IDE for the ESP32 also eliminates access to some of the SoC's more advanced features. If you'd like to try your hand at setting up a more advanced toolchain for the ESP32, we recommend checking out Espressif's esp-idf GitHub repository. The esp-idf – short for IoT Development Framework – is Espressif's software development kit (SDK) for the ESP32.

Installing the ESP32 Core

Espressif's official ESP32 Arduino core is hosted here on GitHub. They have a fairly simple set of installation directions to help.

Clone or Download the Core

To install the ESP32 board definitions, you'll need download the contents of the esp32-arduino repository, and place them in a "hardware/espressif/esp32" directory in your Arduino sketchbook directory. You can either download those files using the git command line tool, or by downloading them from GitHub.

Alternatively, these files can be installed in your Arduino’s base directory. On Windows, that may be C:/Program Files (x86)/Arduino/hardware and on Mac that may be /Applications/Arduino.app/Contents/Java/hardware.

If you have git, open a terminal, navigate to your Arduino sketchbook, and type:

mkdir hardware
cd hardware
mkdir espressif
cd espressif
git clone https://github.com/espressif/arduino-esp32.git esp32

Those commands will make a "hardware" and "espressif" directories, then download the arduino-esp32 GitHub repository into an "esp32" folder.

Example terminal commands

If you don't have git, click here to download the core (or click "Download" > "Download ZIP" on the GitHub page), and unzip it to an espressif/esp32 directory in your Arduino sketchbook.

Windows folder installation

"boards.txt", "platform.txt", and the cores, doc, tools, etc. folders should all live in the esp32 directory.

Install the Xtensa and ESP32 Tools

To compile code for the ESP32, you need the Xtensa GNU compiler collection (GCC) installed on your machine. Windows users can run get.exe, found in the "esp32/tools" folder.

Location of get.exe

Windows users can run "get.exe" to download the ESP32 software tools.

Mac and Linux users should run the tools/get.py python script to download the tools. Using a terminal, navigate to the esp32/tools folder. Then type:

python get.py

The "get.py" python script will download the Xtensa GNU tools and the ESP32 software development kit (SDK), and unzip them to the proper location. You should see a few new folders in the "tools" directory, including "sdk" and "xtensa-esp32-elf" once it's done.

With the ESP32 Arduino core installed, you're ready to begin programming. If you haven't already, plug the ESP32 Thing into your computer using a micro-B USB cable.

ESP32 Thing plugged into breadboard

FTDI Drivers

If you've never connected an FTDI device to your computer before, you may need to install drivers for the USB-to-serial converter. Check out our How to Install FTDI Drivers tutorial for help with the installation.

Once the board is plugged in (and drivers installed), it should be assigned a unique port identifier. On Windows machines, this will be something like "COM#", and on Macs or Linux computers it will come in the form of "/dev/tty.usbserial-XXXXXX."

Select the Board and Port

Once the ESP32 Arduino core is installed, you should see an "ESP32 Dev Module" option under your "Tools" > "Board" menu. Select that.

Arduino board select

Then select your ESP32 Thing's serial port under the "Tools" > "Port" menu.

Arduino port select

You can also select the "Upload Speed". 921600 baud -- the fastest selectable rate -- will get the code loaded onto your ESP32 the fastest, but may fail to upload once-in-a-while. (It's still way worth it for the speed increase!)

Loading Blink

To make sure your toolchain and board are properly set up, we'll upload the simplest of sketches -- Blink! The LED attached to GPIO 5 is perfect for this test. Plus, with the ESP32 attached to your computer, it's a good time to test out serial. Copy and paste the example sketch below, into a fresh Arduino sketch:

language:c
int ledPin = 5;

void setup()
{
    pinMode(ledPin, OUTPUT);
    Serial.begin(115200);
}

void loop()
{
    Serial.println("Hello, world!");
    digitalWrite(ledPin, HIGH);
    delay(500);
    digitalWrite(ledPin, LOW);
    delay(500);
}

With everything setup correctly, upload the code! Once the code finishes transferring, open the serial monitor and set the baud rate to 115200. You should see "Hello, world"'s begin to fly by.

If the blue LED remains dimly lit, it's probably still sitting in the bootloader. After uploading a sketch, you may need to tap the RST button to get your ESP32 Thing to begin running the sketch.

Example serial port output

You may also notice that when the ESP32 boots up it prints out a long sequence of debug messages. These are emitted every time the chip resets -- always at 115200 baud.

Arduino Example: WiFi

The ESP32 Arduino core includes a handful of WiFi examples, which demonstrate everything from scanning for nearby networks to sending data to a client server. You can find the examples under the File > Examples > WiFi menu.

Here's another example using the WiFi library, which demonstrates how to connect to a nearby WiFi network and poll a remote domain (http://example.com/) as a client:

language:c
#include <WiFi.h>

// WiFi network name and password:
const char * networkName = "YOUR_NETWORK_HERE";
const char * networkPswd = "YOUR_PASSWORD_HERE";

// Internet domain to request from:
const char * hostDomain = "example.com";
const int hostPort = 80;

const int BUTTON_PIN = 0;
const int LED_PIN = 5;

void setup()
{
  // Initilize hardware:
  Serial.begin(115200);
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  pinMode(LED_PIN, OUTPUT);

  // Connect to the WiFi network (see function below loop)
  connectToWiFi(networkName, networkPswd);

  digitalWrite(LED_PIN, LOW); // LED off
  Serial.print("Press button 0 to connect to ");
  Serial.println(hostDomain);
}

void loop()
{
  if (digitalRead(BUTTON_PIN) == LOW)
  { // Check if button has been pressed
    while (digitalRead(BUTTON_PIN) == LOW)
      ; // Wait for button to be released

    digitalWrite(LED_PIN, HIGH); // Turn on LED
    requestURL(hostDomain, hostPort); // Connect to server
    digitalWrite(LED_PIN, LOW); // Turn off LED
  }
}

void connectToWiFi(const char * ssid, const char * pwd)
{
  int ledState = 0;

  printLine();
  Serial.println("Connecting to WiFi network: " + String(ssid));

  WiFi.begin(ssid, pwd);

  while (WiFi.status() != WL_CONNECTED) 
  {
    // Blink LED while we're connecting:
    digitalWrite(LED_PIN, ledState);
    ledState = (ledState + 1) % 2; // Flip ledState
    delay(500);
    Serial.print(".");
  }

  Serial.println();
  Serial.println("WiFi connected!");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());
}

void requestURL(const char * host, uint8_t port)
{
  printLine();
  Serial.println("Connecting to domain: " + String(host));

  // Use WiFiClient class to create TCP connections
  WiFiClient client;
  if (!client.connect(host, port))
  {
    Serial.println("connection failed");
    return;
  }
  Serial.println("Connected!");
  printLine();

  // This will send the request to the server
  client.print((String)"GET / HTTP/1.1\r\n" +
               "Host: " + String(host) + "\r\n" +
               "Connection: close\r\n\r\n");
  unsigned long timeout = millis();
  while (client.available() == 0) 
  {
    if (millis() - timeout > 5000) 
    {
      Serial.println(">>> Client Timeout !");
      client.stop();
      return;
    }
  }

  // Read all the lines of the reply from server and print them to Serial
  while (client.available()) 
  {
    String line = client.readStringUntil('\r');
    Serial.print(line);
  }

  Serial.println();
  Serial.println("closing connection");
  client.stop();
}

void printLine()
{
  Serial.println();
  for (int i=0; i<30; i++)
    Serial.print("-");
  Serial.println();
}

Make sure you fill in the networkName and networkPswd variables with the name (SSID) and password of your WiFi network! Once you've done that and uploaded the code, open your serial monitor.

WiFi example serial terminal output

After your ESP32 connects to the WiFi network, it will wait for you to press the "0" button. Tapping that will cause the ESP32 to make an HTTP request to example.com. You should see a string of HTTP headers and HTML similar to the screenshot above.

Using the Arduino Addon

Before we leave you, here are a few tips, tricks, and gotcha's to look out for while you're using the ESP32 Arduino core.

Pin Mapping

The pin number you use for digitalWrite([pin], [value]) or digitalRead([pin]) should match those printed onto the board. You can also reference the graphical datasheet, if the tiny numbers are a strain on the eyes.

Both I2C interfaces are supported by the Wire library. The SDA and SCL pins are assigned, by default, to pins 21 and 22.

I2C SignalESP32 Pin
SDA21
SCL22

And the SPI library should support all three possible SPI interfaces. By default, here are the pin mappings for those interfaces:

SPI SignalESP32 Pin
MOSI23
MISO19
SCLK18
SS5

In addition to SPI and I2C, the Arduino core also supports interrupts on any pin with the attachInterrupt() function.

Not Yet Implemented

The Arduino board definitions for the ESP32 are still a work in progress. There are a handful of peripherals and features that have yet to be implemented, including:

  • Analog Input (analogRead([pin]))
  • Analog Ouptut (analogWrite([pin], [value]))
  • WiFi Server and WiFI UDP
  • Real-Time Clock
  • Touch-controller interface

These peripherals are available (if, also, still in their infancy) in the IoT Development Framework for the ESP32. If your application requires analog input, RTC, or any of the features above, consider giving the ESP-IDF a try!

Resources and Going Further

The ESP32 Thing's design is open-source! You can download, view, and modify the Eagle files (PCB design), checkout the schematic, or suggest revisions on the ESP32 Thing GitHub repository.

The ESP32 is still in its infancy, but resources are popping up all over the place for the chip. Check out some of these links for more information, documentation, and examples.

You can also check out these links to go further.

  • ESP-IDF -- IoT Development Framework -- If you want to take your development environment up a step from Arduino, this should be your first step into ESP32 software development. Some notes on the IDF:
    • The IDF is well-documented. Check out the set up guides (for Windows, Mac or Linux) for help getting your environment set up. For help with the API's and data structures, check out esp32.info.
    • There are a handful of example applications.
    • Use the ESP-IDF project template, once you're ready to start creating applications of your own.
  • Blynk -- Blynk allows you to control IoT development boards with an easily configurable iOS/Android app. And it already supports the ESP32!

Looking for additional functionality with the ESP32? Check out the ESP32 Thing Plus with the ESP32 WROOOM module.

ESP32 Thing Plus Hookup Guide

March 7, 2019

Hookup guide for the ESP32 Thing Plus (Micro-B) using the ESP32 WROOM's WiFi/Bluetooth system-on-chip in Arduino.

For more related tutorials, check out the following tutorials tagged with ESP32.

ESP32 Thing Plus Hookup Guide

Hookup guide for the ESP32 Thing Plus (Micro-B) using the ESP32 WROOM's WiFi/Bluetooth system-on-chip in Arduino.

Using Home Assistant to Expand Your Home Automations

An introduction to Home Assistant, an open source home automation hub.

MicroMod GNSS Function Board - ZED-F9P Hookup Guide

Add millimeter precision location data to your MicroMod project with this guide for the SparkFun MicroMod GNSS Function Board - ZED-F9P.

Measuring Height with Atmospheric Pressure

Measure height using atmospheric pressure with your Qwiic MicroPressure breakout board!

If you need some project inspiration, check out some of these IoT-focused projects and get making!

Getting Started with Load Cells

A tutorial defining what a load cell is and how to use one.

LED Cloud-Connected Cloud

Make an RGB colored cloud light! You can also control it from your phone, or hook up to the weather!

Photon Remote Temperature Sensor

Learn how to build your own Internet-connect, solar-powered temperature collection station using the Photon from Particle.

ESP8266 Powered Propane Poofer

Learn how Nick Poole built a WiFi controlled fire-cannon using the ESP8266 Thing Dev Board!

IoT Industrial Scale

What does a baby elephant weigh? How much impact force does a jump have? Answer these questions and more by building your very own IoT industrial scale using the SparkFun OpenScale.

Or check out these related blog posts.