Firebase IoT ESP32 Integration: Realtime DB vs Firestore Build Guide

Connecting an ESP32 to Google Firebase is the fastest path to a cloud-backed IoT dashboard, but the ecosystem is fractured between legacy libraries, differing database models, and silent authentication failures. If you are building a sensor node that pushes telemetry and listens for remote commands, you need a deterministic setup. This guide targets the ESP32-WROOM-32E (38-pin variant) pushing BME280 environmental data to Firebase, with a remote-controlled LED. We will cut through the abstraction, wire the hardware, flash production-ready C++ firmware, and debug the exact error strings the Firebase client throws when things break.

The Firebase IoT ESP32 Decision Matrix

Google offers two primary NoSQL databases for IoT: Realtime Database (RTDB) and Cloud Firestore. Choosing the wrong one will either bloat your ESP32's memory or bottleneck your write limits. Here is the decision path for embedded nodes.

Hardware Spec Sheet and Pin Mapping

This build assumes you are using the widely available 38-pin DevKit V1 form factor. Do not use 5V logic sensors without a level shifter; the ESP32-WROOM-32E GPIO pins are strictly 3.3V tolerant. Feeding 5V into GPIO21 will permanently brick the silicon.

Step-by-Step Wiring and Firmware Flash

1. Wire the I2C Bus: Connect BME280 VCC to ESP32 3V3. Connect GND to GND. Connect SDA to GPIO21 and SCL to GPIO22. The internal pull-ups on the ESP32 are typically sufficient for short breadboard runs (< 10cm).
2. Wire the Control LED: Connect the anode (long leg) of the LED to a 330Ω resistor, then to GPIO25. Connect the cathode (short leg) directly to ESP32 GND.
3. Provision Firebase: In the Google Firebase Console, create a project. Build a Realtime Database in 'Test Mode' (for development). Go to Project Settings > Service Accounts > Database Secrets to generate your API Key (or use the modern Web API Key from Project Settings > General).
4. Configure Authentication: In the Authentication tab, enable 'Email/Password' sign-in. Create a test user. You will hardcode these into the firmware for node-level auth.
5. Install Libraries: In the Arduino IDE Library Manager, install Firebase ESP32 Client by Mobizt (ensure it is v4.x or newer) and Adafruit BME280 Library (which will auto-install the Adafruit Unified Sensor dependency).
6. Flash and Verify: Upload the code below. Open the Serial Monitor at 115200 baud. You should see WiFi connection, followed by Firebase token generation, and finally 'Pushing temp' logs.

The Complete ESP32 Firebase C++ Firmware

This firmware uses the synchronous FirebaseESP32 library. It includes explicit error handling for HTTP codes and I2C initialization failures. Replace the placeholder strings with your actual credentials.

#include <WiFi.h>
#include <FirebaseESP32.h>
#include <Wire.h>
#include <Adafruit_BME280.h>

// --- PIN DEFINITIONS ---
#define LED_PIN 25
#define I2C_SDA 21
#define I2C_SCL 22

// --- CREDENTIALS ---
#define WIFI_SSID "YOUR_WIFI_SSID"
#define WIFI_PASSWORD "YOUR_WIFI_PASSWORD"
// CRITICAL: Do NOT include 'https://' or trailing '/' in the URL
#define DATABASE_URL "your-project-id-default-rtdb.firebaseio.com" 
#define API_KEY "YOUR_WEB_API_KEY"
#define USER_EMAIL "test@firebase-iot.com"
#define USER_PASSWORD "SecurePass123!"

// --- OBJECTS ---
FirebaseData fbdo;
FirebaseAuth auth;
FirebaseConfig config;
Adafruit_BME280 bme;

unsigned long lastPush = 0;
const unsigned long PUSH_INTERVAL = 5000; // 5 seconds

void setup() {
  Serial.begin(115200);
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);

  // Initialize I2C with explicit pins
  Wire.begin(I2C_SDA, I2C_SCL);
  
  if (!bme.begin(0x76)) {
    Serial.println("[FATAL] BME280 not found. Check I2C wiring and pull-ups.");
    while (1) { delay(1000); } // Halt execution
  }
  Serial.println("[OK] BME280 initialized.");

  // Connect to WiFi
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  Serial.print("Connecting to WiFi");
  while (WiFi.status() != WL_CONNECTED) {
    Serial.print(".");
    delay(500);
  }
  Serial.println("\n[OK] WiFi Connected. IP: " + WiFi.localIP().toString());

  // Configure Firebase
  config.database_url = DATABASE_URL;
  config.api_key = API_KEY;
  auth.user.email = USER_EMAIL;
  auth.user.password = USER_PASSWORD;

  Firebase.begin(&config, &auth);
  Firebase.reconnectWiFi(true);
  
  // Set write size limit to prevent heap fragmentation
  fbdo.setBSSLBufferSize(4096, 1024);
}

void loop() {
  if (Firebase.ready()) {
    // 1. Push Telemetry
    if (millis() - lastPush > PUSH_INTERVAL) {
      lastPush = millis();
      float tempC = bme.readTemperature();
      
      if (Firebase.RTDB.setFloat(&fbdo, "/sensors/node1/temp", tempC)) {
        Serial.println("[OK] Pushed Temp: " + String(tempC));
      } else {
        Serial.println("[ERR] Push Failed: " + fbdo.errorReason());
      }
    }

    // 2. Listen for Remote Command (LED)
    if (Firebase.RTDB.getBool(&fbdo, "/controls/node1/led")) {
      bool ledState = fbdo.boolData();
      digitalWrite(LED_PIN, ledState ? HIGH : LOW);
    } else {
      // Handle read errors silently unless debugging
      if (fbdo.httpCode() != 0) {
        Serial.println("[ERR] Read Failed: " + fbdo.errorReason());
      }
    }
  }
  
  delay(100); // Yield to WiFi stack
}

Debugging: Exact Error Strings and Ranked Fixes

When the ESP32 fails to talk to Firebase, the library returns specific error strings. Do not guess; read the serial output and follow this decision tree. Before diving deep, check the First Three Things:

1. Database URL Formatting: The DATABASE_URL must be exactly project-id.firebaseio.com. Including https:// or a trailing slash / will cause silent SSL handshake failures in v4.x of the Mobizt library.
2. API Key vs Service Account: Ensure you are using the Web API Key from Project Settings, not a Service Account JSON blob. The FirebaseESP32 library uses Web API keys for user-auth flows.
3. Heap Memory: Firebase SSL handshakes require ~30KB of free heap. If you have other heavy libraries loaded, check ESP.getFreeHeap() before calling Firebase.begin().

Extending and Simplifying the Build

Once the baseline telemetry loop is stable, you will inevitably need to scale. Here is how to adapt this architecture without rewriting the core firmware.

• Simplify for Battery Nodes: If you are running on a 18650 Li-ion cell, drop the polling getBool() read in the loop. Instead, use Firebase.RTDB.beginStream() to open a persistent WebSocket. This allows the ESP32 to sleep and only wake on server-sent events, cutting average current draw from 80mA to <15mA.
• Extend to Multiple Nodes: Never hardcode node IDs in the paths. Use the ESP32's MAC address to generate a unique node path dynamically: String nodePath = "/sensors/" + WiFi.macAddress() + "/temp";. This allows you to flash identical firmware to 50 different boards and have them self-organize in the Firebase JSON tree.
• Upgrade to Firestore (When Necessary): If your application requires complex querying (e.g., "get all nodes where temp > 30C AND battery > 20%"), RTDB will fail you. You will need to migrate to Firestore. When you do, switch to the FirebaseClient (v1.x) async library by Mobizt, as the legacy FirebaseESP32 library does not support Firestore's gRPC endpoints.

For deeper architectural references, consult the Espressif ESP32 Datasheet for power-state management, the Mobizt Firebase ESP32 Client GitHub repository for library-specific edge cases, and the official Google Firebase Realtime Database Documentation for structuring your JSON tree to minimize read costs.