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.
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:
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.
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:
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:
||UART1 TX Pin||Maps to
||UART1 RX Pin||Maps to
||UART2 TX Pin||Maps to
||UART2 RX Pin||Maps to
||UART3 TX Pin||Maps to
||UART3 RX Pin||Maps to
||I2C SDA||Maps to
||I2C SCL||Maps to
||SPI MOSI||Maps to
||SPI MISO||Maps to
||SPI CLK||Maps to
Internal ESP32 Pins
All internal pins can be accessed using the following nomenclature:
GPIO_NUM_[PIN]. For example, pin 12 can be accessed via
The default pin for any peripheral can be changed within an element's properties, from an element that references that particular peripheral.
Below is information regarding the ESP32’s exposed peripherals.
This I2C bus is exposed via pins
This SPI bus is exposed via pins
UART1 (USB Debug Console)
This UART is exposed via the micro-USB connector on the ESP32 or pins
This UART is exposed via pins
This UART is exposed via pins
ADC2 cannot be used, since it conflicts with the Wi-Fi. The following pins can be used for analog input:
Any GPIO pin can be used for PWM output.
Programming the ESP32 involves using the programmer interface in Atmosphere Studio to install embedded firmware.
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.
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:
|Getting Started with ESP32|
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.
|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.|
The following additional resources and downloadable files are available for the ESP32: