Getting Started with ESP32

This guide teaches you how to get started using ESP32 devices with Atmosphere. This includes creating your first project, programming the project’s firmware into your ESP32, registering the device to Atmosphere, and having its data displayed on a dashboard.

This guide demonstrates a simple project that blinks a development board’s LED and reads an ADC pin once a second.

Prerequisite: You should already have an Atmosphere account.

Hardware Requirements

  • Espressif ESP32-based device
  • Tablet or smartphone mobile device

For the purposes of this guide, we’re using the Adafruit HUZZAH32 ESP32 Feather Board, but any development board using an ESP32 module will work. This includes the following development boards with a unique project type in Atmosphere:

Software Requirements

  • Atmosphere IoT app. The mobile app allows you to view your registered devices and display and run the project’s interface. You can download the Atmosphere IoT app from its downloads page or through the Apple App Store or Google Play Store.
  • Atmosphere IoT Agent. 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, used to assist in programming your device. You can download the Atmosphere IoT Agent from its downloads page.
  • Ensure Bluetooth is enabled on the mobile device you’ll use to interact with the ESP32. This project only uses the ESP32 with Bluetooth Low Energy.

Step 1 of 9: Create a New Project

Navigate to Atmosphere IoT Studio from the side menu. When you visit IoT Studio for the first time in a session, you are brought to the IoT Studio Projects screen.

  1. Click the New Project button. This displays a New Project window.
    1. Select the ESP32 project type and give the project a name, then click Create. This opens a new project in IoT Studio. Alternatively if you’re using an ESP32 variant that has its own project type, you can create the project for that type and still use this guide.

This guide walks through the step-by-step process to perform actions in IoT Studio, but doesn't cover the in-depth aspects of IoT Studio itself. To learn more about using IoT Studio, its areas and features, and Studio elements, visit the Atmosphere Studio section.

Step 2 of 9: Create the Project’s Embedded Firmware

The first aspect of building this sample project is adding elements to the Embedded tab to create the project’s embedded firmware. This involves setting an interval to read embedded data, and to tell the interval to read the board’s GPIO and ADC pins.

  1. Add the following elements to the canvas by clicking them in the Element Toolbox:
    • Interval Element Interval element: The interval element sets the project to run at the time set in the element’s properties, which by default is set to once per second (1000 ms).
    • ADC Pin Element ADC pin element: The ADC pin element reads the board’s ADC pin. By default this is set to the corresponding ADC pin.
    • GPIO Element GPIO pin element: The GPIO pin element reads the board’s GPIO pin. By default this is set to the GPIO pin associated to the board’s LED.

      Each of the elements will work as intended by default, so none of their properties need to be changed.
  2. Connect the interval element to the GPIO element. This creates an event between them, which can be seen in either the interval element’s properties, or by clicking the connector’s Configuration Button button. The event added is within the Interval trigger, with the GPIO pin ability Toggle. This means that when the interval element is triggered (which is every second), it will toggle the GPIO pin.
  3. Connect the interval element to the ADC pin element, which also creates an event between them, Read Raw. This event will read the raw ADC value when the interval element triggers.
  4. Add a BLE Characteristic Element BLE characteristic element to the canvas, which creates a GATT characteristic to use in your project. This element is a coupled element that bridges the project between the Embedded tab and Application tab, meaning it’s included on both tabs. Select the BLE characteristic element, and change the Read Data Type field to Unsigned Integer. This reads an unsigned integer, which is the ADC value sent to it.
  5. Connect the ADC pin element to the BLE characteristic element, which ties the value of the ADC pin to the Application tab. This creates an event between the two elements of Set Value, which sets a value for the project’s interface after it reads the raw ADC pin value.

That’s all for work in the Embedded tab. To this point, an interval has been set that will run once per second after the project opens, and when run will both toggle a GPIO pin and read an ADC pin. The Embedded tab canvas should resemble the following image:

ESP32 Embedded Tab

Step 3 of 9: Create the Project’s Interface

The second aspect of building this sample project is adding elements to the Application tab to create the project’s visual component.

Click the Application tab to move to the application area of the project. Notice how the Element Toolbox has changed, and that the coupled BLE characteristic element is displayed on the canvas.

  1. Click the App Builder button in the Application tab’s toolbar to display the app builder. This area creates the visual interface for your project. By default this uses the smallest display size supported for an interface (320x560), but you can add an interface size by clicking the add display button. Use the display size that fits best with your mobile device.
  2. Add an Interval Element interval element to the canvas, and connect it to the existing BLE characteristic element. This creates the trigger event Read, which reads the value of the BLE characteristic element sent from the Embedded tab every time the interval triggers.
  3. Add a Label Element label element to the canvas. The label element displays text on a project’s interface. Notice when the label is added to the canvas, a corresponding interface component is added to the app builder. The label component can be moved around on the interface wherever you like.
  4. Connect the BLE characteristic element to the label element. This creates an event between the two elements of Set Text under the Read trigger, which sets the text to the value of the label when the BLE characteristic is read. This correlates the set value from the BLE characteristic element in the Embedded tab to the label on the interface.

This is all that needs to be done for the project’s interface, simply using a label to display a text value. To this point, an interval has been set that will read the BLE characteristic value once per second, which will display the read value on the interface label. The Application tab’s canvas should resemble the following image:

ESP32 Application Tab

Step 4 of 9: Enable the Project’s Cloud Connectivity

The third aspect of building this sample project is enabling it for cloud connectivity. This is done on both the Application and Cloud tabs.

  1. While still in the Application tab, add a Device Event Element Device Event element to the canvas. The Device Event element is a coupled element between the Application and Cloud tabs that enables a project’s data to be sent to Atmosphere.
  2. Connect the BLE characteristic element to the Device Event element. This adds the Send Event event to the Read trigger, which sends the set value data to Atmosphere when the BLE characteristic is read.
  3. Click the Cloud tab to move to the cloud area of the project. Notice how the Element Toolbox has changed, and that the coupled Device Event element is displayed on the canvas.
  4. Add a Cloud Storage Element cloud storage element to the canvas, and connect the cloud storage element to the Device Event element. This allows Atmosphere to store data sent to it from the connected Device Event element.

That’s all for creating the project! With the added cloud connectivity, the project will send the ADC pin value from the Embedded tab to the Application tab, which then uses a Device Event to send it to the Cloud tab, where it’s connected to a cloud storage element to store the data on Atmosphere.

The final canvas for each tab should resemble the following images:

Embedded Application Cloud
ESP32 Embedded Tab ESP32 Application Tab ESP32 Cloud Tab

Step 5 of 9: Compile the Project

Once the project is finished, it needs to be compiled. Compiling readies the entire project’s source code for deployment.

  1. From any tab, click the Compile button in the project options menu on the top-right of the screen. You’ll see a loading message on the screen, and will be notified when the project is compiled.

Step 6 of 9: Program Firmware into the Device

With the project compiled, your ESP32 can be programmed with the project’s embedded firmware.

Prior to programming a device, ensure you have the following configuration:

  • The device is connected to the computer via USB to an available communication port.
  • The Atmosphere IoT Agent is installed and running.
  • An Internet connection is maintained.

With setup complete, you can program your board:

  1. While the Embedded tab is active, click the Program Firmware button from the tab’s toolbar. This displays the Program Firmware window.
  2. Under Device Port, select the communication port the device is connected to.
  3. Click Program to start programming. When complete, you’ll be notified that the device is programmed with the project’s embedded firmware.

Once the device is programmed, the LED will begin toggling on and off!

Step 7 of 9: Register the Device

With firmware installed, the device can now be recognized and connected to Atmosphere. From here, open the Atmosphere IoT app on your mobile device. We’ll use the mobile app to both register the device, and eventually view the label data on the project’s interface.

To register a device:

  1. Navigate to the Devices area, and click the Register Device button in the top-right of the screen to display the Scan window. When the window opens it automatically starts scanning for available devices within range.
    • Ensure your ESP32 is within range from the device you are attempting to register from, otherwise it may not appear.
    • If you want to connect the ESP32 over Wi-Fi, you can configure Wi-Fi network settings at this point. If Wi-Fi settings are entered, the device will connect to Atmosphere over Wi-Fi and remain connected as long as the Wi-Fi connection is maintained.
  2. The list of available devices appears. Select your device you just programmed and click Register.

The device is registered to Atmosphere and displayed on the page.

Step 8 of 9: View the Project Interface

Each registered device has its own dedicated console page, which displays its information and is where you access the device’s interface to interact with it. Select your newly-registered device in the Devices area to access its console.

The interface created in Studio’s Application tab is available on a device’s console to interact with it. As long as the device is powered on and connected to Atmosphere, it can be interacted with.

To display the interface you created, click the Interface button at the top of the screen. This opens the project interface from within the Atmosphere IoT app.

The project’s interface displays the ADC pin value, which updates once per second.

If your ESP32 is connected over Wi-Fi and you open the project's interface, the device will temporarily disconnect from Wi-Fi and connect using BLE instead. This is because the ESP32 can't simultaneously maintain both connections, so BLE is used while interacting with the device and its interface. Once you leave the interface, the BLE connection is closed and the device reconnects over Wi-Fi.

Step 9 of 9: View Device Data

Now that the device’s data is sent to Atmosphere, let’s view it through one of the many dashboard widgets available. In this guide we’ll use a data graph to chart the ADC reading.

  1. To add a widget to the device’s dashboard, click the Configuration button on the right side of the screen. This displays the menu of available widgets. Select the Data Graph data graph widget to add a graph to the dashboard.
  2. Once on the dashboard, click the widget’s Menu menu icon to display its menu, then click Settings.
  3. In the data graph’s settings, give the widget a name, such as “ESP32 ADC Reading.”
  4. In the Data Source field, click Select, then choose the following configuration options for the widget:
    • Cloud Storage: Select the cloud storage that is storing the ADC data.
    • X-axis Value: Select the timestamp to go along the graph’s x-axis. The timestamp is the time the server receives the data.
    • Y-axis Value: Select the ADC dataset to go up the graph’s y-axis.
  5. When finished click Save. This populates the data graph plotting the value of the ADC as time progresses. If you have a means of manipulating the ADC on your development board, you can see the value change more drastically along the graph. If you’d like to adjust the graph’s timeline or its bounds, you can edit those properties from the data graph’s menu as well.

Congratulations, you just finished a complete ESP32 project with Atmosphere!