Fix minor issue and update the Realtime database simple examples

FAQ.md

@@ -1,5 +1,5 @@
 
-Revision `2024-06-07T05:35:03Z`
+Revision `2024-06-09T07:13:35Z`
 
 # Async Firebase Client library for Arduino Frequently Asked Questions.
 
@@ -343,7 +343,7 @@ For running more tasks concurrency, see [Running Many Tasks Concurrency Using Di
 #### A29: Please see, [Possible GSM issues](#possible-gsm-issues).
 
 ### Q30: How to stop the authentication task?
-#### A30: Normally the authentication task was unable to stop after initialize unless it can deinitialize.
+#### A30: Normally the authentication task was unable to stop after initialized unless it can deinitialize.
 
 You can use `deinitializeApp(<FirebaseApp>)` to deinitalize the `FirebaseApp` that was initialized.
 

README.md

@@ -2,11 +2,11 @@
 
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/mobizt/FirebaseClient/.github%2Fworkflows%2Fcompile_library.yml?logo=github&label=compile) [![Github Stars](https://img.shields.io/github/stars/mobizt/FirebaseClient?logo=github)](https://github.com/mobizt/FirebaseClient/stargazers) ![Github Issues](https://img.shields.io/github/issues/mobizt/FirebaseClient?logo=github)
 
-![GitHub Release](https://img.shields.io/github/v/release/mobizt/FirebaseClient) ![Arduino](https://img.shields.io/badge/Arduino-v1.2.11-57C207?logo=arduino) ![PlatformIO](https://badges.registry.platformio.org/packages/mobizt/library/FirebaseClient.svg) ![GitHub Release Date](https://img.shields.io/github/release-date/mobizt/FirebaseClient)
+![GitHub Release](https://img.shields.io/github/v/release/mobizt/FirebaseClient) ![Arduino](https://img.shields.io/badge/Arduino-v1.2.12-57C207?logo=arduino) ![PlatformIO](https://badges.registry.platformio.org/packages/mobizt/library/FirebaseClient.svg) ![GitHub Release Date](https://img.shields.io/github/release-date/mobizt/FirebaseClient)
 
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/mobizt?logo=github)](https://github.com/sponsors/mobizt)
 
-Revision `2024-06-07T06:05:58Z`
+Revision `2024-06-09T07:13:35Z`
 
 ## Table of Contents
 

examples/RealtimeDatabase/Simple/SimpleDatabaseSecret/SimpleDatabaseSecret.ino

@@ -1,5 +1,23 @@
+/**
+ * This example is for new users which are familiar with other legacy Firebase libraries.
+ *
+ * The example shows how to set, push and get the values to/from Realtime database.
+ *
+ * This example will not use any authentication method included database secret.
+ *
+ * It needs to change the security rules to allow read and write.
+ *
+ * This example is for ESP32, ESP8266 and Raspberry Pi Pico W.
+ *
+ * You can adapt the WiFi and SSL client library that are available for your devices.
+ *
+ * For the ethernet and GSM network which are not covered by this example,
+ * you have to try another elaborate examples and read the library documentation thoroughly.
+ *
+ */
+
 #include <Arduino.h>
-#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W) || defined(ARDUINO_GIGA)
+#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W)
 #include <WiFi.h>
 #elif defined(ESP8266)
 #include <ESP8266WiFi.h>
@@ -52,16 +70,23 @@ void setup()
  ssl.setBufferSizes(1024, 1024);
 #endif
 
+ // Initialize the authentication handler.
  initializeApp(client, app, getAuth(dbSecret));
 
- // Binding the FirebaseApp for authentication handler.
- // To unbind, use Database.resetApp();
+ // Binding the authentication handler with your Database class object.
  app.getApp<RealtimeDatabase>(Database);
 
+ // Set your database URL
  Database.url(DATABASE_URL);
 
+ // Set the operating result for the the following blocking (sync) functions.
+ // The result will keep in the async result object we set to the client.
  client.setAsyncResult(result);
 
+ // The following are blocking operations which the result will store in the result object we set above.
+
+ // In the another Stream examples, we will use the non-blocking (async) functions to allow the realtime incoming data. 
+
  // Set, push and get integer value
 
  Serial.print("Set int... ");
@@ -217,4 +242,9 @@ void setup()
 
 void loop()
 {
+ // We don't need to poll the async task using Database.loop(); as in the Stream examples because 
+ // only blocking (sync) functions were used in this example.
+
+ // We don't have to poll authentication handler task using app.loop() as seen in other examples
+ // because the database secret is the priviledge access key that never expired.
 }

examples/RealtimeDatabase/Simple/SimpleNoAuth/SimpleNoAuth.ino

@@ -1,4 +1,21 @@
-/** This example requires the Realtime database security rules setup as following.
+/**
+ * This example is for new users which are familiar with other legacy Firebase libraries.
+ *
+ * The example shows how to set, push and get the values to/from Realtime database.
+ *
+ * This example will use the database secret for priviledge Realtime database access which does not need
+ * to change the security rules or it can access Realtime database no matter what the security rules are set.
+ *
+ * This example is for ESP32, ESP8266 and Raspberry Pi Pico W.
+ *
+ * You can adapt the WiFi and SSL client library that are available for your devices.
+ *
+ * For the ethernet and GSM network which are not covered by this example,
+ * you have to try another elaborate examples and read the library documentation thoroughly.
+ *
+ */
+
+/** Change your Realtime database security rules as the following.
  {
  "rules": {
  ".read": true,
@@ -8,7 +25,7 @@
 */
 
 #include <Arduino.h>
-#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W) || defined(ARDUINO_GIGA)
+#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W)
 #include <WiFi.h>
 #elif defined(ESP8266)
 #include <ESP8266WiFi.h>
@@ -60,16 +77,23 @@ void setup()
  ssl.setBufferSizes(1024, 1024);
 #endif
 
+ // Initialize the authentication handler.
  initializeApp(client, app, getAuth(noAuth));
 
- // Binding the FirebaseApp for authentication handler.
- // To unbind, use Database.resetApp();
+ // Binding the authentication handler with your Database class object.
  app.getApp<RealtimeDatabase>(Database);
 
+ // Set your database URL
  Database.url(DATABASE_URL);
 
+ // Set the operating result for the the following blocking (sync) functions.
+ // The result will keep in the async result object we set to the client.
  client.setAsyncResult(result);
 
+ // The following are blocking operations which the result will store in the result object we set above.
+
+ // In the another Stream examples, we will use the non-blocking (async) functions to allow the realtime incoming data.
+
  // Set, push and get integer value
 
  Serial.print("Set int... ");
@@ -225,4 +249,9 @@ void setup()
 
 void loop()
 {
+ // We don't need to poll the async task using Database.loop(); as in the Stream examples because 
+ // only blocking (sync) functions were used in this example.
+
+ // We don't have to poll authentication handler task using app.loop() as seen in other examples
+ // because the database secret is the priviledge access key that never expired.
 }

examples/RealtimeDatabase/Simple/StreamDatabaseSecret/StreamDatabaseSecret.ino

@@ -1,5 +1,23 @@
+/**
+ * This example is for new users which are familiar with other legacy Firebase libraries.
+ *
+ * The example shows how to listen the data changes in your Firebase Realtime database
+ * while the database was set periodically.
+ *
+ * This example will use the database secret for priviledge Realtime database access which does not need
+ * to change the security rules or it can access Realtime database no matter what the security rules are set.
+ *
+ * This example is for ESP32, ESP8266 and Raspberry Pi Pico W.
+ *
+ * You can adapt the WiFi and SSL client library that are available for your devices.
+ *
+ * For the ethernet and GSM network which are not covered by this example,
+ * you have to try another elaborate examples and read the library documentation thoroughly.
+ *
+ */
+
 #include <Arduino.h>
-#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W) || defined(ARDUINO_GIGA)
+#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W)
 #include <WiFi.h>
 #elif defined(ESP8266)
 #include <ESP8266WiFi.h>
@@ -14,13 +32,25 @@
 #define DATABASE_SECRET "DATABASE_SECRET"
 #define DATABASE_URL "URL"
 
+// The SSL client used for secure server connection.
 WiFiClientSecure ssl1, ssl2;
+
+// The default network config object that used in this library.
 DefaultNetwork network;
+
+// The client, aka async client, is the client that handles many tasks required for each operation.
 AsyncClientClass client1(ssl1, getNetwork(network)), client2(ssl2, getNetwork(network));
 
+// The authentication task handler, aka FirebaseApp.
 FirebaseApp app;
+
+// The Realtime database class object that provides the functions.
 RealtimeDatabase Database;
+
+// The class that stores the operating result, aka AsyncResult.
 AsyncResult result1, result2;
+
+// The legacy token provider class used for authentication initialization.
 LegacyToken dbSecret(DATABASE_SECRET);
 
 unsigned long ms = 0;
@@ -91,30 +121,40 @@ void setup()
  ssl2.setBufferSizes(1024, 1024);
 #endif
 
+ // Initialize the authentication handler.
  initializeApp(client1, app, getAuth(dbSecret));
 
- // Binding the FirebaseApp for authentication handler.
- // To unbind, use Database.resetApp();
+ // Binding the authentication handler with your Database class object.
  app.getApp<RealtimeDatabase>(Database);
 
+ // Set your database URL
  Database.url(DATABASE_URL);
 
- client1.setAsyncResult(result1);
- client2.setAsyncResult(result2);
-
- Database.get(client1, "/test/stream", result1, true);
+ // Initiate the Stream connection to listen the data changes.
+ // This function can be called once.
+ // The Stream was connected using async get function (non-blocking) which the result was assign to the function.
+ Database.get(client1, "/test/stream", result1, true /* this option is for Stream connection */);
 }
 
 void loop()
 {
+ // Polling for internal task operation
+ // This required for Stream in this case.
  Database.loop();
 
+ // We don't have to poll authentication handler task using app.loop() as seen in other examples
+ // because the database secret is the priviledge access key that never expired.
+
+ // Set the random int value to "/test/stream/int" every 20 seconds.
  if (millis() - ms > 20000 || ms == 0)
  {
  ms = millis();
- Database.set<object_t>(client2, "/test/stream/ts", random(100, 999), result2);
+
+ // We set the data with this non-blocking set function (async) which the result was assign to the function.
+ Database.set<int>(client2, "/test/stream/int", random(100, 999), result2);
  }
 
+ // Polling print the result if it is available.
  printResult(result1);
  printResult(result2);
 }

examples/RealtimeDatabase/Simple/StreamNoAuth/StreamNoAuth.ino

@@ -1,4 +1,23 @@
-/** This example requires the Realtime database security rules setup as following.
+/**
+ * This example is for new users which are familiar with other legacy Firebase libraries.
+ *
+ * The example shows how to listen the data changes in your Firebase Realtime database
+ * while the database was set periodically.
+ *
+ * This example will not use any authentication method included database secret.
+ *
+ * It needs to change the security rules to allow read and write.
+ *
+ * This example is for ESP32, ESP8266 and Raspberry Pi Pico W.
+ *
+ * You can adapt the WiFi and SSL client library that are available for your devices.
+ *
+ * For the ethernet and GSM network which are not covered by this example,
+ * you have to try another elaborate examples and read the library documentation thoroughly.
+ *
+ */
+
+/** Change your Realtime database security rules as the following.
  {
  "rules": {
  ".read": true,
@@ -8,7 +27,7 @@
 */
 
 #include <Arduino.h>
-#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W) || defined(ARDUINO_GIGA)
+#if defined(ESP32) || defined(ARDUINO_RASPBERRY_PI_PICO_W)
 #include <WiFi.h>
 #elif defined(ESP8266)
 #include <ESP8266WiFi.h>
@@ -23,13 +42,25 @@
 #define DATABASE_SECRET "DATABASE_SECRET"
 #define DATABASE_URL "URL"
 
+// The SSL client used for secure server connection.
 WiFiClientSecure ssl1, ssl2;
+
+// The default network config object that used in this library.
 DefaultNetwork network;
+
+// The client, aka async client, is the client that handles many tasks required for each operation.
 AsyncClientClass client1(ssl1, getNetwork(network)), client2(ssl2, getNetwork(network));
 
+// The authentication task handler, aka FirebaseApp.
 FirebaseApp app;
+
+// The Realtime database class object that provides the functions.
 RealtimeDatabase Database;
+
+// The class that stores the operating result, aka AsyncResult.
 AsyncResult result1, result2;
+
+// The no-authentication provider class used for authentication initialization.
 NoAuth noAuth;
 
 unsigned long ms = 0;
@@ -100,30 +131,39 @@ void setup()
  ssl2.setBufferSizes(1024, 1024);
 #endif
 
+ // Initialize the authentication handler.
  initializeApp(client1, app, getAuth(noAuth));
 
- // Binding the FirebaseApp for authentication handler.
- // To unbind, use Database.resetApp();
+ // Binding the authentication handler with your Database class object.
  app.getApp<RealtimeDatabase>(Database);
 
+ // Set your database URL
  Database.url(DATABASE_URL);
 
- client1.setAsyncResult(result1);
- client2.setAsyncResult(result2);
-
- Database.get(client1, "/test/stream", result1, true);
+ // Initiate the Stream connection to listen the data changes.
+ // This function can be called once.
+ // The Stream was connected using async get function (non-blocking) which the result was assign to the function.
+ Database.get(client1, "/test/stream", result1, true /* this option is for Stream connection */);
 }
 
 void loop()
 {
+ // Polling for internal task operation
+ // This required for Stream in this case.
  Database.loop();
 
+ // We don't have to poll authentication handler task using app.loop() as seen in other examples
+ // because the database secret is the priviledge access key that never expired.
+
+ // Set the random int value to "/test/stream/int" every 20 seconds.
  if (millis() - ms > 20000 || ms == 0)
  {
  ms = millis();
- Database.set<object_t>(client2, "/test/stream/ts", random(100, 999), result2);
+ // We set the data with this non-blocking set function (async) which the result was assign to the function.
+ Database.set<int>(client2, "/test/stream/int", random(100, 999), result2);
  }
 
+ // Polling print the result if it is available.
  printResult(result1);
  printResult(result2);
 }

library.json

@@ -1,6 +1,6 @@
 {
  "name": "FirebaseClient",
- "version": "1.2.11",
+ "version": "1.2.12",
  "keywords": "communication, REST, esp32, esp8266, arduino",
  "description": "Async Firebase Client library for Arduino.",
  "repository": {

library.properties

@@ -1,6 +1,6 @@
 name=FirebaseClient
 
-version=1.2.11
+version=1.2.12
 
 author=Mobizt
 

src/FirebaseClient.h

@@ -147,7 +147,6 @@ namespace firebase
 #if defined(ENABLE_ID_TOKEN)
 
  app.auth_data.app_token.expire = app.expire;
- app.auth_data.user_auth.user.val[user_ns::api_key] = app.auth_data.user_auth.user.val[user_ns::api_key];
  app.auth_data.app_token.val[app_tk_ns::token] = app.auth_data.user_auth.id_token.val[id_tk_ns::token];
  app.auth_data.app_token.val[app_tk_ns::refresh] = app.auth_data.user_auth.id_token.val[id_tk_ns::refresh];
  app.auth_data.app_token.authenticated = app.auth_data.user_auth.id_token.val[id_tk_ns::token].length() ? app.auth_data.user_auth.initialized : false;