ESP32

The ESP32 is a hybrid Bluetooth Low Energy (BLE) and Wi-Fi chip from Espressif Systems that is used in several products and IoT solutions.

Project Specifics

The ESP32 project type is not specific to any one ESP32 device and is applicable for any ESP32-based development board. Any ESP32 device should work without issue with this project type, however there are some nuances with ESP32 variants regarding pin mappings and peripherals. If you have an ESP32 variant that has an individual project type (such as the Sparkfun ESP32 Thing) it’s recommended you work with the corresponding project type.

Having both BLE and Wi-Fi connectivity options, ESP32 projects include the following protocol elements:

BLE Characteristic

BLE Connection

Wi-Fi Connection

As is standard with any project type that uses Wi-Fi, cloud elements are accessible from both the Embedded and Application tabs in Atmosphere Studio.

Hardware Specifics

Some devices may have limitations or design restrictions that cause unexpected behavior when used with Atmosphere. Specific information and details pertaining to the ESP32 and its performance on Atmosphere is noted below.

Wi-Fi/BLE Co-existence Limitations

The ESP32 can operate both Wi-Fi and BLE at the same time, however it greatly disrupts the stability of the BLE connection to the device. As a result, Atmosphere’s embedded framework automatically disconnects from a Wi-Fi connection whenever a BLE connection is established.

This prevents any cloud events directly sent from the embedded device from getting to the cloud on the primary embedded cloud interface. Once the device’s BLE connection is disconnected, it automatically reconnects over Wi-Fi.

Unavailable ADC2 During Wi-Fi Connection

The ESP-IDF SDK (and possibly the ESP32 hardware) has a limitation where a Wi-Fi connection interferes with the device’s ability to read data from an ADC pin reading from ADC channel 2.

The I/O pins affected by this include the following:

IO27
IO26
IO25
IO15
IO14
IO13
IO12
IO4
IO2
IO0

If you wish to use any of these pins for ADC, you must not have Wi-Fi enabled at the time you attempt to make a reading from them. These pins do continue to work as expected while BLE is running.

For more information on this issue, view the forum post on Espressif’s website at Espressif ESP32 Forum: “When will support for ADC2 (with Wi-Fi) be added?”

There is currently a conversation on the Arduino-ESP32 GitHub tracker that addresses this as well: GitHub: Arduino-ESP32 Issues 102.

Default Pin Mapping

Atmosphere configures each peripheral to a default pin for every supported device, based on ideal pairing of pins and their usage. The default pin configuration is set for convenience and enables each peripheral to work naturally without needing to be modified.

If you're not using an Espressif ESP32 development kit, refer to the appropriate page for the variant of a supported ESP32 type for more detailed information, as its pin mapping may be different.

All pins can be used as general purpose input/output (GPIO) unless otherwise specified.

ESP32 projects start with the following pin configuration:

Pin Table

Pin	Description	Notes
`ESP32_UART1_TX`	UART1 TX Pin	Maps to `IO4`
`ESP32_UART1_RX`	UART1 RX Pin	Maps to `IO5`
`ESP32_UART2_TX`	UART2 TX Pin	Maps to `IO12`
`ESP32_UART2_RX`	UART2 RX Pin	Maps to `IO13`
`ESP32_UART3_TX`	UART3 TX Pin	Maps to `IO1`
`ESP32_UART3_RX`	UART3 RX Pin	Maps to `IO3`
`ESP32_I2C_SDA`	I2C SDA	Maps to `IO21`
`ESP32_I2C_SCL`	I2C SCL	Maps to `IO22`
`ESP32_SPI_MOSI`	SPI MOSI	Maps to `IO23`
`ESP32_SPI_MISO`	SPI MISO	Maps to `IO25`
`ESP32_SPI_CLK`	SPI CLK	Maps to `IO19`

Internal ESP32 Pins

All internal pins can be accessed using the following nomenclature: IO[PIN] OR GPIO_NUM_[PIN]. For example, pin 12 can be accessed via IO12 or GPIO_NUM_12.

The default pin for any peripheral can be changed within an element's properties, from an element that references that particular peripheral.

Peripherals

Below is information regarding the ESP32’s exposed peripherals.

I2C

I2C1

This I2C bus is exposed via pins IO21(SDA) and IO22(SCL).

SPI

SPI1

This SPI bus is exposed via pins IO23(MOSI), IO25(MISO), and IO19(CLK).

UART

UART1 (USB Debug Console)

This UART is exposed via the micro-USB connector on the ESP32 or pins IO4(TX) and IO5(RX).

UART2

This UART is exposed via pins IO12(TX) and IO13(RX).

UART3

This UART is exposed via pins IO1(TX) and IO3(RX).

ADC

ADC2 cannot be used, since it conflicts with the Wi-Fi. The following pins can be used for analog input:

IO36
IO37
IO38
IO39
IO32
IO33
IO34
IO35

PWM

Any GPIO pin can be used for PWM output.

Programming Method

Programming the ESP32 involves using the programmer interface in Atmosphere Studio to install embedded firmware.

Setup Configuration

Prior to programming an ESP32, ensure you have the following setup configuration:

The ESP32 is connected to the computer via USB to an available communication port.
The computer has the necessary connectivity protocols enabled (Bluetooth Low Energy, Wi-Fi, etc.).
The Atmosphere IoT Agent is installed on the computer and running. The Atmosphere IoT Agent is a local application that runs in the system tray and acts as an intermediary between the computer’s connectivity protocol drivers and the browser running Atmosphere.
An Internet connection is maintained.
The project to be programmed has been compiled.

Programming Instructions

With setup complete, you can program the ESP32:

From Atmosphere Studio’s Embedded tab, click the button from the tab’s toolbar. This displays the Program Firmware window.
Under Device Port, select the communication port the device is connected to.
Click Program to start programming. When complete, you’ll receive a notification stating the device is programmed with the project’s embedded firmware.

When complete, the ESP32 is programmed with the project’s embedded firmware.

Guides and Tutorials

Get started using the ESP32 with Atmosphere by walking through the following guides:

ESP32 Guides
Getting Started with ESP32

Demo Projects

Atmosphere includes a variety of ESP32 demo projects for users of all levels. Check them out by clicking the demo’s name to open the project in Atmosphere.

Demos created under the generic ESP32 project type will program and operate for most ESP32-based development boards (including the ESP32 Dev Kit C) however they may experience issues with some ESP32 variants. If you're using a variant that has its own project type, it's recommended you re-create these demos under that project type to ensure they properly run.

Name	Description
Embedded-to-Cloud Demo	Send embedded data to the cloud over Wi-Fi using embedded cloud elements. The demo sends an integer every five seconds to the cloud and increments it by 1. The cloud then multiplies the value and returns the result to the device as a cloud command, which gets printed to the device’s debug console.
UART Loopback Demo	Learn how to use the UART element with a simple demo that sends “Hello World” one byte at a time over UART while demonstrating the buffering and regex capabilities of the UART driver. This demo uses UART2. Note to connect IO14 and IO15 on your ESP32 to send the TX back to RX.
UART Slave Demo	Create a UART slave device with this demo that’s capable of responding to specific commands using the regular expression element. You can also see how this demo is configured by reading the detailed Creating a UART Slave Device in Atmosphere post in the Atmosphere blog.
Wi-Fi Connection Element Demo	Learn how to use the Wi-Fi connection element with a demo that includes writing two BLE characteristics for a Wi-Fi networks’ SSID and password, which are used to initiate a Wi-Fi connection in STA mode. The control characteristic can also be used to disconnect and attempt to reconnect to Wi-Fi via the app.

Resources

The following additional resources and downloadable files are available for the ESP32:

ESP32 Raw Pin Mapping (zip)