Firebase: Control ESP32 GPIOs from Anywhere

In this section, we’ll configure the ESP32 board to do the following tasks:

For this task, you require the following parts:

You can use the preceding links or go straight to locate all the parts for your projects at the ideal price!

You require to insert the following in the code prior to publishing it to your board:

Project Overview

Continue reviewing to discover just how the code functions or miss to the.

1. The ESP32 authenticates as a user with email and password to be able to access the database (that user must be added on the Firebase authentication methods);
2. The database is protected using database rules. We’ll add the following rule: only authenticated users can access the database;
3. The database has several nodes that save the ESP32 GPIO states. As an example, we’ll control three GPIOs (12, 13, and 14). You can add or remove nodes to control more or less GPIOs.
4. The ESP32 will listen for changes on the GPIOs database nodes. Whenever there’s a change, it will update the GPIO states accordingly.
5. You can change the GPIO states manually on the database using the Firebase console, or you can create a web page (accessible from anywhere) with buttons to control the GPIOs and show the current GPIO states ().

You can download the adhering to JSON file and import it to your database, and also it will produce nodes for 2 boards:

Preparing Arduino IDE

After submitting the JSON data, the database will certainly look as complies with:

Now, you can publish the same code to the brand-new board (it is suitable with the ESP32 and also ESP8266).

Make certain you have the ESP32 add-on installed in your Arduino IDE:

1) Create Firebase Project

If you want to set the ESP boards utilizing VS Code with the PlatformIO extension, comply with the next tutorial rather:

1) Go to and sign in utilizing a Google Account.

In this area, we’ll program the ESP32 board to do the adhering to tasks:

For this job, you need the adhering to parts:

You can make use of the preceding links or go directly to discover all the components for your tasks at the best price!

Also, alter the display rate to 115200 by adding the following line to the platformio.ini file of your task:

2) Set Authentication Methods

Copy the following code to your Arduino IDE or to the main.cpp data if you’re making use of VS Code.

You require to put the complying with in the code before posting it to your board:

Continue reading to discover exactly how the code functions or miss to the.

You can download and install the following JSON data and also import it to your data source, and also it will produce nodes for two boards:

After posting the JSON file, the database will look as follows:

Now, you can publish the same code to the brand-new board (it is suitable with the ESP32 and also ESP8266).

6) Add an email address for the authorized user. It can be your google account email or any other email. You can also create an email for this specific project. Add a password that will allow you to sign in to your app and access the database. Don’t forget to save the password in a safe place because you’ll need it later. When you’re done, click Add user.

7) A new user was successfully created and added to the Users table.

Notice that Firebase creates a unique UID for each registered user. The user UID allows us to identify the user and keep track of the user to provide or deny access to the project or the database. There’s also a column that registers the date of the last sign-in. At the moment, it is empty because we haven’t signed in with that user yet.

Copy the User UID because you’ll need it later.

3) Get Project API Key

To interface with your Firebase project using the ESP32 or ESP8266 boards, you need to get your project API key. Follow the next steps to get your project API key.

1) On the left sidebar, click on Project Settings.

2) Copy the Web API Key to a safe place because you’ll need it later.

4) Set up the Realtime Database

Now, let’s create a realtime database and set up database rules for our project.

1) On the left sidebar, click on Realtime Database and then click on Create Database.

2) Select your database location. It should be the closest to your location.

3) Set up security rules for your database. You can select Start in test mode. We’ll change the database rules in just a moment.

4) Your database is now created. You need to copy and save the database URL—highlighted in the following image—because you’ll need it later in your ESP32 code.

5) Set up Database Security Rules

Now, let’s set up the database rules. On the Realtime Database tab, select the Rules tab at the top. Then, click on Edit rules, and add the following rules.

{
  "rules": {
    ".read": "auth.uid === 'REPLACE_WITH_YOUR_USER_UID'",
    ".write": "auth.uid === 'REPLACE_WITH_YOUR_USER_UID'"
  }
}

Insert the UID of the user you created previously. Then, click Publish.

These database rules determine that:

• Only the user with that specific UID can read and write to the database (change the GPIO states).

Add More Users

To add more users, you can simply go to the Authentication tab and click Add user. Add an email and password for the new user, and finally click on Add user to create the user.

Copy the user UID of that new user and add it to the database rules, as follows:

{
  "rules": {
    ".read": "auth.uid === 'REPLACE_WITH_YOUR_USER_UID' || auth.uid === 'REPLACE_WITH_USER_UID2'",
    ".write": "auth.uid === 'REPLACE_WITH_YOUR_USER_UID' || auth.uid === 'REPLACE_WITH_USER_UID2'"
  }
}

For example. In my case, the UIDs of the users are: RjO3taAzMMXB82Xmir2LQ7XXXXXX and 9QdDc9as5mRXGAjEsQiUJkXXXXXX. So, the database rules will look as follows:

{
  "rules": {
    ".read": "auth.uid === 'RjO3taAzMMXB82Xmir2LQ7XXXXXX' || auth.uid === '9QdDc9as5mRXGAjEsQiUJkXXXXXX'",
    ".write": "auth.uid === 'RjO3taAzMMXB82Xmir2LQ7XXXXXX' || auth.uid === '9QdDc9as5mRXGAjEsQiUJkXXXXXX'"
  }
}

Finally, Publish your database rules.

To learn more about database rules, you can check the .

6) Organizing Your Database Nodes

All the data stored in the Firebase Realtime Database is stored as JSON objects. So, you can think of the database as a cloud-based JSON tree. When you add data to the JSON tree, it becomes a node with an associated key in the existing JSON structure.

Not familiar with JSON? .

The best way to organize your data will depend on your project features and how users access the data.

We want to control the ESP32 GPIOs. We can organize the data in a way that makes it easy to add more GPIOs and boards later on. So, we can structure the database as follows:

• board1:
  • outputs:
    • digital:
      • 12: 0
      • 13: 0
      • 14: 0

In JSON format, here’s what it would look like:

{
  "board1": {
    "outputs": {
      "digital": {
        "12": 0,
        "13": 0,
        "14": 0
      }
    }
  }
}

Creating Database Nodes

Now let’s create the database nodes in our database. You can create the nodes manually by writing the nodes on the Firebase console, on the web app, or via the ESP32. We’ll create them manually, so it is easier to follow the tutorial.

1) Click on the Realtime Database so that we start creating the nodes.

2) You can create the database nodes manually by using the (+) icons on the database. However, to prevent typos, we provide a JSON file that you can upload to create the same nodes as ours. Click the link below to download the JSON file.

After downloading, unzip the folder to access the .json file.

3) Now, go back to your database on the Firebase console. Click on the three-dot icon and select Import JSON.

4) Select the JSON file that you’ve just downloaded.

5) Your database should look as shown below.

All the database nodes required for this project are created. You can proceed to the next section.

7) ESP32: Listening for Database Changes (control GPIOs)

In this section, we’ll program the ESP32 board to do the following tasks:

1. Authenticate as a user with email and password ();
2. Listening for database changes on the GPIO nodes and changing their states accordingly.

Parts Required

For this project, you need the following parts:

• (read );
• ;
• ;
• ;
• .

You can use the preceding links or go directly to to find all the parts for your projects at the best price!

Schematic Diagram

In this example, we’ll control three LEDs connected to GPIOs 12, 13, and 14. So, wire three LEDs to the ESP32. You can follow the next schematic diagram.

You can use any , but you also need to change the database nodes.

Installing the Firebase ESP Client Library

The provides many examples on how to interface the ESP32 with Firebase services. and consider supporting the author if the library is useful for your projects.

Install the Firebase-ESP-Client Library (Arduino IDE)

Follow this section if you’re using Arduino IDE.

Go to Sketch > Include Library > Manage Libraries, search for “Firebase ESP Client”. Select the Firebase Arduino Client Library for ESP8266 and ESP32.

Now, you’re all set to start programming the ESP32 boards to interact with the database.

Install the Firebase-ESP-Client Library (VS Code)

Follow the next instructions if you’re using VS Code + PlatformIO.

Click on the PIO Home icon and select the Libraries tab. Search for “Firebase ESP Client“. Select the Firebase Arduino Client Library for ESP8266 and ESP32.

Then, click Add to Project and select the project you’re working on.

Also, change the monitor speed to 115200 by adding the following line to the platformio.ini file of your project:

monitor_speed = 115200

Listening for Database Changes (GPIO states) — Code

Copy the following code to your Arduino IDE or to the main.cpp file if you’re using VS Code.

You need to insert the following in the code before uploading it to your board:

• your network credentials
• project API key
• database URL
• authorized user email and password

/*
  Rui Santos
  Complete project details at our blog.
    - ESP32: https://RandomNerdTutorials.com/firebase-control-esp32-gpios/
    - ESP8266: https://RandomNerdTutorials.com/firebase-control-esp8266-nodemcu-gpios/
  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.
  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  Based in the RTDB Basic Example by Firebase-ESP-Client library by mobizt
  https://github.com/mobizt/Firebase-ESP-Client/blob/main/examples/RTDB/Basic/Basic.ino
*/

#include <Arduino.h>
#if defined(ESP32)
  #include <WiFi.h>
#elif defined(ESP8266)
  #include <ESP8266WiFi.h>
#endif
#include <Firebase_ESP_Client.h>

// Provide the token generation process info.
#include "addons/TokenHelper.h"
// Provide the RTDB payload printing info and other helper functions.
#include "addons/RTDBHelper.h"

// Insert your network credentials
#define WIFI_SSID "REPLACE_WITH_YOUR_SSID"
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD"

// Insert Firebase project API Key
#define API_KEY "REPLACE_WITH_YOUR_PROJECT_API_KEY"

// Insert Authorized Username and Corresponding Password
#define USER_EMAIL "REPLACE_WITH_THE_USER_EMAIL"
#define USER_PASSWORD "REPLACE_WITH_THE_USER_PASSWORD"

// Insert RTDB URLefine the RTDB URL
#define DATABASE_URL "REPLACE_WITH_YOUR_DATABASE_URL"

// Define Firebase objects
FirebaseData stream;
FirebaseAuth auth;
FirebaseConfig config;

// Variables to save database paths
String listenerPath = "board1/outputs/digital/";

// Declare outputs
const int output1 = 12;
const int output2 = 13;
const int output3 = 14;

// Initialize WiFi
void initWiFi() {
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  Serial.print("Connecting to WiFi ..");
  while (WiFi.status() != WL_CONNECTED) {
    Serial.print('.');
    delay(1000);
  }
  Serial.println(WiFi.localIP());
  Serial.println();
}

// Callback function that runs on database changes
void streamCallback(FirebaseStream data){
  Serial.printf("stream path, %s/nevent path, %s/ndata type, %s/nevent type, %s/n/n",
                data.streamPath().c_str(),
                data.dataPath().c_str(),
                data.dataType().c_str(),
                data.eventType().c_str());
  printResult(data); //see addons/RTDBHelper.h
  Serial.println();

  // Get the path that triggered the function
  String streamPath = String(data.dataPath());

  // if the data returned is an integer, there was a change on the GPIO state on the following path /{gpio_number}
  if (data.dataTypeEnum() == fb_esp_rtdb_data_type_integer){
    String gpio = streamPath.substring(1);
    int state = data.intData();
    Serial.print("GPIO: ");
    Serial.println(gpio);
    Serial.print("STATE: ");
    Serial.println(state);
    digitalWrite(gpio.toInt(), state);
  }

  /* When it first runs, it is triggered on the root (/) path and returns a JSON with all keys
  and values of that path. So, we can get all values from the database and updated the GPIO states*/
  if (data.dataTypeEnum() == fb_esp_rtdb_data_type_json){
    FirebaseJson json = data.to<FirebaseJson>();

    // To iterate all values in Json object
    size_t count = json.iteratorBegin();
    Serial.println("/n---------");
    for (size_t i = 0; i < count; i++){
        FirebaseJson::IteratorValue value = json.valueAt(i);
        int gpio = value.key.toInt();
        int state = value.value.toInt();
        Serial.print("STATE: ");
        Serial.println(state);
        Serial.print("GPIO:");
        Serial.println(gpio);
        digitalWrite(gpio, state);
        Serial.printf("Name: %s, Value: %s, Type: %s/n", value.key.c_str(), value.value.c_str(), value.type == FirebaseJson::JSON_OBJECT ? "object" : "array");
    }
    Serial.println();
    json.iteratorEnd(); // required for free the used memory in iteration (node data collection)
  }
  
  //This is the size of stream payload received (current and max value)
  //Max payload size is the payload size under the stream path since the stream connected
  //and read once and will not update until stream reconnection takes place.
  //This max value will be zero as no payload received in case of ESP8266 which
  //BearSSL reserved Rx buffer size is less than the actual stream payload.
  Serial.printf("Received stream payload size: %d (Max. %d)/n/n", data.payloadLength(), data.maxPayloadLength());
}

void streamTimeoutCallback(bool timeout){
  if (timeout)
    Serial.println("stream timeout, resuming.../n");
  if (!stream.httpConnected())
    Serial.printf("error code: %d, reason: %s/n/n", stream.httpCode(), stream.errorReason().c_str());
}

void setup(){
  Serial.begin(115200);
  initWiFi();

  // Initialize Outputs
  pinMode(output1, OUTPUT);
  pinMode(output2, OUTPUT);
  pinMode(output3, OUTPUT);
  
  // Assign the api key (required)
  config.api_key = API_KEY;

  // Assign the user sign in credentials
  auth.user.email = USER_EMAIL;
  auth.user.password = USER_PASSWORD;

  // Assign the RTDB URL (required)
  config.database_url = DATABASE_URL;

  Firebase.reconnectWiFi(true);

  // Assign the callback function for the long running token generation task */
  config.token_status_callback = tokenStatusCallback; //see addons/TokenHelper.h

  // Assign the maximum retry of token generation
  config.max_token_generation_retry = 5;

  // Initialize the library with the Firebase authen and config
  Firebase.begin(&config, &auth);

  // Streaming (whenever data changes on a path)
  // Begin stream on a database path --> board1/outputs/digital
  if (!Firebase.RTDB.beginStream(&stream, listenerPath.c_str()))
    Serial.printf("stream begin error, %s/n/n", stream.errorReason().c_str());

  // Assign a calback function to run when it detects changes on the database
  Firebase.RTDB.setStreamCallback(&stream, streamCallback, streamTimeoutCallback);

  delay(2000);
}

void loop(){
  if (Firebase.isTokenExpired()){
    Firebase.refreshToken(&config);
    Serial.println("Refresh token");
  }
}

How the Code Works

Continue reading to learn how the code works or skip to the .

Include Libraries

First, include the required libraries. This code is also compatible with the ESP8266.

#include <Arduino.h>
#if defined(ESP32)
  #include <WiFi.h>
#elif defined(ESP8266)
  #include <ESP8266WiFi.h>
#endif
#include <Firebase_ESP_Client.h>

// Provide the token generation process info.
#include "addons/TokenHelper.h"
// Provide the RTDB payload printing info and other helper functions.
#include "addons/RTDBHelper.h"

Network Credentials

Include your network credentials in the following lines so that your boards can connect to the internet using your local network.

// Insert your network credentials
#define WIFI_SSID "REPLACE_WITH_YOUR_SSID"
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD"

Firebase Project API Key, Firebase User, and Database URL

Insert your —the one you’ve gotten .

#define API_KEY "REPLACE_WITH_YOUR_PROJECT_API_KEY"

Insert the —these are the details of the user you’ve added .

// Insert Authorized Email and Corresponding Password
#define USER_EMAIL "REPLACE_WITH_THE_USER_EMAIL"
#define USER_PASSWORD "REPLACE_WITH_THE_USER_PASSWORD"

Insert your in the following line:

// Insert RTDB URLefine the RTDB URL
#define DATABASE_URL "REPLACE_WITH_YOUR_DATABASE_URL"

Firebase Objects and Other Variables

First, you need to create a FirebaseData object (we called it stream) to handle the data when there’s a change on a specific database path.

FirebaseData stream;

The next line defines a FirebaseAuth object needed for authentication.

FirebaseAuth auth;

Finally, the following line defines a FirebaseConfig object required for configuration data.

FirebaseConfig config;

Database Path

Then, create a variable that saves the database path where we’ll be listening for changes. Taking into account the database structure we created previously, the listener database path should be as follows:

String listenerPath = "board1/outputs/digital/";

If you want to add more boards, then you just need to change the listener path accordingly.

Create variables for the outputs you’ll control. In our case, we’re controlling GPIOs 12, 13, and 14. You can control any other ESP32 GPIOs (you’ll also need to change the database nodes):

const int output1 = 12;
const int output2 = 13;
const int output3 = 14;

initWifi()

The iniWifi() function connects the ESP32 to your local network. We’ll call it later in the setup() to initialize Wi-Fi.

// Initialize WiFi
void initWiFi() {
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  Serial.print("Connecting to WiFi ..");
  while (WiFi.status() != WL_CONNECTED) {
    Serial.print('.');
    delay(1000);
  }
  Serial.println(WiFi.localIP());
  Serial.println();
}

setup()

Let’s now jump to the setup(). We’ll take a look at the streamCallback() function later.

Initialize the Serial Monitor:

Serial.begin(115200);

Call the initiWiFi() function we created previously, to connect your board to your local network.

initWiFi();

Initialize the GPIOs as outputs.

// Initialize Outputs
pinMode(output1, OUTPUT);
pinMode(output2, OUTPUT);
pinMode(output3, OUTPUT);

Assign the API key to the Firebase configuration.

config.api_key = API_KEY;

The following lines assign the email and password to the Firebase authentication object.

auth.user.email = USER_EMAIL;
auth.user.password = USER_PASSWORD;

Assign the database URL to the Firebase configuration object.

config.database_url = DATABASE_URL;

Add the following to the configuration object.

// Assign the callback function for the long running token generation task
config.token_status_callback = tokenStatusCallback; //see addons/TokenHelper.h

// Assign the maximum retry of token generation
config.max_token_generation_retry = 5;

Initialize the Firebase library (authenticate) with the configuration and authentication settings we defined earlier.

// Initialize the library with the Firebase authen and config
Firebase.begin(&config, &auth);

Stream Database – Listening for Changes

Listening for changes on the database works with callback functions. This means, that when a change is detected on the database, a callback function will run.

The following line of code starts a stream to listen for changes on the listenerPath.

if (!Firebase.RTDB.beginStream(&stream, listenerPath.c_str()))

Then, set a callback function to be triggered whenever there’s a change on the listenerPath—the streamCallback function.

Firebase.RTDB.setStreamCallback(&stream, streamCallback, streamTimeoutCallback);

streamCallback() function

Let’s now take a look at the streamCallback function created previously.

When the streamCallback() function is triggered, an object called data of type FirebaseStream is passed automatically as an argument to that function. From that object, we can get the stream path, the data path (the full database path where the change occurred, including the value of the lowest child), the data type of that value, and the event type that triggered the stream.

void streamCallback(FirebaseStream data){
  Serial.printf("stream path, %s/nevent path, %s/ndata type, %s/nevent type, %s/n/n",
                data.streamPath().c_str(),
                data.dataPath().c_str(),
                data.dataType().c_str(),
                data.eventType().c_str());
  printResult(data); //see addons/RTDBHelper.h
  Serial.println();

  // Get the path that triggered the function
  String streamPath = String(data.dataPath());

Then, from the obtained information, the ESP can run certain tasks, like updating the GPIO states.

When you change the value of the GPIO states on the database, the data returned by that event is an integer (in this case, 0 or 1). So, first, we check if the response is an integer:

if (data.dataTypeEnum() == fb_esp_rtdb_data_type_integer){

If it is, the event path corresponds to the GPIO node path, for example /12. From that path, we can get the GPIO number we want to change, we just need to cut the “/” from the string.

String gpio = streamPath.substring(1);

To better understand this, you can take a look at the following screenshot. It shows what you get when there’s a change in the GPIOs states.

We can get the value of the returned data as follows (knowing beforehand that it is an integer):

int state = data.intData();

Then, we can simply call the digitalWrite() function and pass as arguments the GPIO number and the state to keep the ESP32 output states updated.

digitalWrite(gpio.toInt(), state);

When the ESP first connects to the database, it is triggered on the root(/) path and returns a JSON object with all child nodes. So, we can get all values from the database and update the ESP32 GPIOs when it first runs. This is also useful because if the ESP32 resets, it will always receive this JSON object first, and will be able to update all GPIOs.

As you can see from the previous screenshot, the JSON object it receives looks as follows (it might be different depending on the GPIO states):

{
  "12": 0,
  "13": 0,
  "14": 0
}

When this happens, the returned data is of type JSON. So, we can get it with the following if statement:

if (data.dataTypeEnum() == fb_esp_rtdb_data_type_json){

We can convert the returned data to a FirebaseJSON object:

FirebaseJson json = data.to<FirebaseJson>();

Then, we can iterate through the whole JSON object and get the keys (GPIOs) and corresponding values (GPIO states). In each iteration, we save the GPIO on the gpio variable and its corresponding state on the state variable. Then, we call the digitalWrite() function to update its state.

// To iterate all values in Json object
size_t count = json.iteratorBegin();
Serial.println("/n---------");
for (size_t i = 0; i < count; i++){
    FirebaseJson::IteratorValue value = json.valueAt(i);
    int gpio = value.key.toInt();
    int state = value.value.toInt();
    Serial.print("STATE: ");
    Serial.println(state);
    Serial.print("GPIO:");
    Serial.println(gpio);
    digitalWrite(gpio, state);
    Serial.printf("Name: %s, Value: %s, Type: %s/n", value.key.c_str(), value.value.c_str(), value.type == FirebaseJson::JSON_OBJECT ? "object" : "array");
}
Serial.println();
json.iteratorEnd(); // required for free the used memory in iteration (node data collection)

This runs through all keys and values allowing us to update all GPIOs.

Because all our code works with callback functions, we don’t need to place anything on the loop() besides the lines to refresh the Firebase token.

void loop(){
  if (Firebase.isTokenExpired()){
    Firebase.refreshToken(&config);
    Serial.println("Refresh token");
  }
}

If the ESP32 needs to perform other tasks, you can add them in the loop(). In our case, this example only listens for database changes.

Demonstration

After inserting all required credentials, upload the code to your board.

After uploading, open the Serial Monitor at a baud rate of 115200 and reset the board. You should get something as shown below.

As you can see, when the ESP first runs, it gets a JSON object with all GPIO states.

{
  "12": 0,
  "13": 0,
  "14": 0
}

Then, go to the Firebase Realtime Database on the Firebase console. Manually change the GPIO states (either 0 or 1). After inserting a new value, press Enter.

Right after, you’ll see on the Serial Monitor that the ESP32 detected the changes.

And it will update the GPIO states and light up the LEDs almost instantaneously.

Then, if you reset your board (press the RST button or remove and apply power again), when it restarts, it will get the latest GPIO states from the database and updates them right away.

Taking it Further – Add More Boards

You can take this project further and add more boards. To do that, create new database nodes for a second board. You can add ESP32 or ESP8266 boards.

You can download the following JSON file and import it to your database, and it will create nodes for two boards:

After uploading the JSON file, the database will look as follows:

Now, you can upload the same code to the new board (it is compatible with the ESP32 and ESP8266). But don’t forget to change the listening path. It should be:

String listenerPath = "board2/outputs/digital/";

Now, you can control both boards by changing the GPIO states on the database.

In Part 2, we’ll create a Firebase web app so that you have a nice interface to control your GPIOs from anywhere without having to use the Firebase console and change the database manually:

• PART 2:

Wrapping Up

In this tutorial, you learned how to use the Firebase Realtime Database to save the ESP GPIO states. You also learned how to program the ESP32 to listen for database changes. Whenever a change is detected, we updated the corresponding GPIO states. You can change the code so that the ESP listens for any other data saved on the database, not only GPIO states. Because you can access the Firebase Realtime Database from anywhere, you can control your boards from anywhere too. This is great for IoT projects.