Firebase Connector

Introduction

Firebase is a platform developed by Google for creating mobile and web applications. It provides various services like Realtime Database, Authentication, Cloud Messaging, and many more.

The Firebase Connector is a connector provided by Coreflux that enables seamless communication between Firebase Realtime Database and your MQTT broker. This guide will provide a comprehensive overview of the Firebase Connector, including its features, benefits, installation, configuration, and usage.

Features and Benefits

• Seamless Communication: Enables seamless communication between Firebase Realtime Database and your MQTT broker.
• Data Synchronization: Synchronizes data between Firebase and MQTT topics.
• Real-time Monitoring: Allows real-time monitoring of Firebase databases.
• Secure Connection: Supports secure connections using Transport Layer Security (TLS).

Prerequisites

Before you install and configure the Firebase Asset, make sure you have the following prerequisites:

• Basic understanding of the MQTT protocol.
• Coreflux account.
• Coreflux MQTT Broker.
• MQTT Client (such as MQTT Explorer).
• Access to a firebase realtime database

Connector Instalation

Using Coreflux HUB

Please refer to the general docs for connector installation through the Coreflux HUB.

Using Coreflux HUBLESS

Connector management and control are conducted using the MQTT protocol. Commands (payload) are sent to the $/Coreflux/Command topic. The results of these commands are published to $/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

1. Connect to the Coreflux MQTT Broker using your preferred client;

2. Login using your Coreflux Account:

   -L myname@mydomain.com password
   

3. Check for available connectors:

   -l
   

4. Install the connector:

   -I coreflux_firebasemqtt
   

5. If there were no issues during the installation, you should receive a message on the $/Coreflux/Command/Output:

Your coreflux_firebasemqtt was installed with the version <version> with the <asset_guid>. Let the magic begin!  

Connector Configuration

Before using the connector, it must be properly configured.
This configuration process entails adjusting various parameters that affect its functionality, the setup of the device, and how they interact with each other.
This involves specifying the device's IP address, selecting which symbols to read from the device, among other settings.

The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, Firebase Parameters and Tags.
The instructions bellow serve as a configuration guide, for each section. By the end, you should have a comprehensive example configuration that can be tailored to your specific needs.

⚠ : If a parameter is not included in the connector's configuration and it is not required, a default value will be applied. Incorrect configuration may cause the connector to not work as intended.

ℹ : This configuration is presented using a hubless setup as an example. The key takeaway is the understanding of the parameters and their significance. If you are configuring the connector via Coreflux Hub, the same parameters and configurations apply.

Parameters

MQTT Parameters

The MQTTParameters in the JSON configuration define how to connect to a MQTT Broker, specifying the communications details.

The Address and Port indicate the broker's network location (in this case, 127.0.0.1 on port 1883), which is where the data will be sent to or received from.
The parameters also detail authentication methods and use of TLS for secure communication.

This setup determines the pathway for the data exchange between the device and the MQTT broker, facilitating the monitoring or control of device operations.

Parameter	Description	Required	Example	Default Value
Port	Port number on which the MQTT broker is running.	Yes	1883	1883
Address	IP address or hostname of the MQTT broker.	Yes	"iot.coreflux.cloud"	"127.0.0.1"
IsAnonymous	Indicates if the connection is anonymous (no username/password required).	No	true	true
Username	Username for authentication, if not anonymous.	No	""	""
Password	Password for authentication, if not anonymous.	No	""	""
WithTLS	Specifies whether TLS encryption is enabled for secure communication.	No	true	false
ClientId	Used to uniquely to identify the client to the MQTT broker.	Yes	Client1	Random.Name.Generator

Example:

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    }
}

Firebase Parameters

Firebase Parameters in the JSON configuration outlines the setup for the connection between the asset and the Firebase Realtime Database.
These parameters require the user's email as User, the user's password, the database URL and the API Key from the database.

Parameter	Description	Required	Example	Default Value
User	Email of the user with access to the database. Found in the Authentication section.	Yes	"test@testmail.com"	""
Password	Password of the user with access to the database.	Yes	"securepassword123!"	""
DatabaseURL	Found in the Realtime Database section of the Firebase console.	Yes	"https://example-app.firebaseio.com/"	""
APIKey	An API key is a unique string that's used to route requests to your Firebase project.	Yes	"AIzaSyEXAMPLE12345FAKEKEY67890FAKEKEY"	""

Example:

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "FirebaseParameters":{
      "User" : "test@testmail.com",
      "Password" : "securepassword123!",
      "DatabaseURL" : "https://example-app.firebaseio.com/",
      "APIKey" : "AIzaSyEXAMPLE12345ABCD67890FAKEKEY"
    }
}

Tags

Tags are crucial components that simplify the set of actions the asset will perform in the workspace. Each Tag establishes a direct link to the nodes in the firebase realtime database and the payload from MQTT, including the Firebase Child Node to indicate the targeted node, the Firebase Action Type, to post json, value and update each, and Add Key To MQTT Topic, to personalize the MQTT topic for Firebase to MQTT communications based on the Key of the object.

Parameter	Description	Required	Example	Default Value
Name	Unique Tag Identifier	Yes	"RoomTemperature"	"TagName"
Route	Specifies the direction of data flow within the system. Acceptable values are: 'ToSubscribers' (0), 'ToOther' (1).	Yes	0	1
Publish	Choose how data is sent. Acceptable values are: 'Update' (0), 'Cyclic' (1), 'Once' (2)	Yes	0	2
PublishCycle	Specifies the interval for publishing messages when 'publish' is set to 'Cyclic'. Must be a value between 1 and 86,400 seconds (24 hours).	No	500	1
MqttTopic	Unique Topic connecting with the specified Register	Yes	"room/temp"	"mqtt/topic"
MqttRetain	Defines if the message should be retained. Options are: true or false.	Yes	true	false
QualityOfService	Defines the level of delivery assurance for MQTT messages. The options are: AtMostOnce (0), AtLeastOnce(1), ExactlyOnce(1).	Yes	2	2
FirebaseChildNode	Child node where the mqtt payload will be written/read. If not specified for MQTT to Firebase communications, it will post the data on the same path as the MQTT topic	No	true	false
FirebaseActionType	Sets the action option for the tag. Options are: 'PostJson' (0), , 'PostValue' (1),'UpdateJson' (2), 'UpdateValue' (3).	No	2	0
KeyType	For post, defines the type of key to be generated for the payload. Options are: 'AutoKey' (0), 'Time' (1) and 'Unix' (2)	No	2	0
AddKeyToMqttTopic	If the key of the object should be included to the publishing MQTT Topic	No	true	false

About Key Type

- `AutoKey`: Key automatically generated by firebase;
- `Time`: Uses a date formatted as dd-MM-yyyy_hh:mm:ss.fff_tt as the key;
- `Unix`: Uses a unix time by the milliseconds as the key.

About Firebase Action Types

- `PostJson`: This option will generate a new child node in the Firebase Realtime Database (RTDB) with a new key, and the content will be in JSON format. This is useful when you want to add a new record without overwriting the existing data.

- `PostValue`: This option is similar to `PostJSON`, but instead of posting JSON data, it posts a direct value.

- `UpdateJson`: This option will overwrite the specified child node in the RTDB with new JSON data. For example, if you specify a child node `users/user1` and the new JSON data is `{ "name": "John", "age": 30 }`, Firebase will overwrite the `users/user1` child node with the new JSON data.

- `UpdateValue`: This option is similar to `UpdateJSON`, but instead of posting JSON data, it posts a direct value. For example, if you specify a child node `users/user1` and the new value is `30`, Firebase will overwrite the `users/user1` child node with the new value `30`.

Example Configuration

Example:

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "FirebaseParameters":{
      "User" : "test@testmail.com",
      "Password" : "securepassword123!",
      "DatabaseURL" : "https://example-app.firebaseio.com/",
      "APIKey" : "AIzaSyEXAMPLE12345ABCD67890FAKEKEY"
    },
    "Tags":[
        {
            "Name" : "FromMqttToFirebase",
            "Route" : 1,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "FirebaseActionType" : 0,           
            "DataType" : 0,
            "KeyType" : 3,
            "FirebaseChildNode": "RTDB/Child/node"         
        },
        {
            "Name" : "FromFirebaseToMqtt",
            "Route" : 0,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "AddKeyToMqttTopic": true,
            "FirebaseChildNode": "RTDB/Anotherchild/node"           
        }
    ]
}

⚠ : Tags for payloads from MQTT to Firebase should use Route: ToOthers. From Firebase to MQTT, use Route: ToSubscribers

⚠ : Be carefull to not subscribe to nodes that you will be writing on. It will create unwanted echos.

Saving the Configuration

Connector management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : Configuration requires the user to be logged in and have a connector installed. If these requirements are not met, please refer to the installation section.

1. Save the configuration:

-assetConfigSave <asset_guid> <configuration>`

ℹ : The connector asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Example:

-assetConfigSave assetName{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "FirebaseParameters":{
      "User" : "test@testmail.com",
      "Password" : "securepassword123!",
      "DatabaseURL" : "https://example-app.firebaseio.com/",
      "APIKey" : "AIzaSyEXAMPLE12345ABCD67890FAKEKEY"
    },
    "Tags":[
        {
            "Name" : "FromMqttToFirebase",
            "Route" : 1,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "FirebaseActionType" : 0,           
            "DataType" : 0         
        },
        {
            "Name" : "FromFirebaseToMqtt",
            "Route" : 0,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "AddKeyToMqttTopic": true,
            "FirebaseChildNode": "RTBD/child/node"           
        }
    ]
}

2. Check if the configuration was saved (optional):

-assetConfigLoad <asset_guid>

Using the Asset

⚠ : It is important to understand that the flow of data between the broker and the device highly depends on the configuration of both the connector and the device. In case of unexpected results, please verify the configuration and/or check the logs for any possible errors.

With Coreflux HUB

Please refer the to general docs for connector installation through the Coreflux HUB.

With Coreflux HUBLESS

Connector management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $/Coreflux/Command topic. The results of these commands are published to $/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Run Connector

1. Run connector:

-R <asset_guid>

Stop Connector

1. Stop connector:

-S <asset_guid>

Logs

Logs are essential to monitor and debug your system. They provide insight into the operation of your connectors and can help identify and resolve issues promptly.

With Coreflux HUB

On Coreflux HUB, the logs are displayed in the "Log" section of the connector configuration.

With MQTT Explorer

To display logs in MQTT Explorer, follow these steps:

1. Publish the following command to the $/Coreflux/Command topic:

-addTraceLog topic=topic/to/show/log level=Error/Information/Warning messageContains=(assetID)

2. The logs will be shown on the $/Coreflux/Log/Traces/topic/to/show/log topic.

Example1:

To display informational logs, use:

-addTraceLog topic=log/inf level=Information

Note : This will display the Logs "Information" of all the connectors

Example2:

To display error logs, from a specific connector, use:

-addTraceLog topic=log/slack/err level=Error messageContains=assetID

Note : This will display the Logs "Error" of a specific connector

Note: To display all three types of logs (Error, Information, and Warning), you will need to repeat this process three times, one for each log level. three times, one for each log level.

FAQ

General Questions

"What is the Firebase Connector?"

The Firebase Connector is a flux connector provided by Coreflux that enables seamless communication between Firebase Realtime Database and your MQTT broker. It allows you to synchronize data between Firebase and MQTT topics, monitor them in real-time, and easily integrate them with your IoT projects.

"What are the prerequisites for using the Firebase Connector?"

Before you install and configure the Firebase Connector, make sure you have the following prerequisites: - Basic understanding of the MQTT protocol. - Coreflux account. - Coreflux MQTT Broker. - MQTT Client (such as MQTT Explorer). - Access to a firebase realtime database

"How do I install the Firebase Connector?"

The Firebase Connector can be installed via Coreflux HUB or Coreflux HUBLESS. Detailed installation instructions can be found in the Installation section of the Firebase Connector documentation.

Configuration Questions

"How do I configure the Firebase Connector?"

To configure the Firebase Connector, you need to run only one command:

-assetConfigSave <guid> <configuration>

The <guid> is a unique asset id that is generated during the installation. To get the asset guid, consult the $SYS/Coreflux/Assets topic. The <configuration> parameter is where you are able to set the connector settings. Detailed configuration instructions and an example configuration can be found in the Configuration section of the Firebase Connector documentation.

"What are the parameters in the configuration?"

The configuration consists of three main sections: MQTTParameters, FirebaseParameters, and Tags. - MQTTParameters are used to configure the connection between the client and the MQTT broker. - FirebaseParameters are used to configure the connection between the MQTT Broker and Firebase Realtime Database. - Tags is an array of "Tag", each containing parameters for a unique database node and MQTT topic connection.