Tutorial

Widget Tutorial

This tutorial demonstrates how to create a simple widget that runs in NodeJS and listens for changes to a Firebase value. Then the tutorial demonstrates how to connect that widget to a Homebridge server in order to control the widget through Homekit on iOS.

Step 0: Create a Firebase Database

1. Create an account with Firebase
2. Create a new project in Firebase.
3. Create a new user in Firebase/Auth

Step 1: Create a Widget

This widget will be written in NodeJS. It will sit listening for changes to a given database reference and act on those changes.

Create a directory for the project and initialize the project using:

npm init.

Install the Firebase dependency. For now use version 2.4.1 because of this issue.

npm install --save firebase@2.4.1

Create the javascript code file (probably index.js)

const Firebase = require("firebase");
const FirebaseServer = "https://myfirebaseurl.firebaseio.com";
const FirebaseCredentials = {
    "email": "myemail@example.com",
    "password": "my_secret_password"
};
var db;

function PerformOnAction() {
    // this is where the code to manipulate your hardware goes
}

function PerformOffAction() {
    // this is where the code to manipulate your hardware goes
}

function db_onValue(snapshot) {
    if (snapshot.val() == "ON") {
        PerformOnAction();
    } else {
        PerformOffAction();
    }
}

function db_onError(err) {
    console.log(err);
}

function db_onAuth(authData) {
    if (authData) {
        console.log("Authenticated, create/change the value at " + 
            FirebaseServer + "/" + db.getAuth().uid + "/command");
        db.child(db.getAuth().uid).child('command')
            .on('value').then(db_onValue).catch(db_onError);
    } else {
        db.authWithPassword(FirebaseCredentials);
    }
}

db = new Firebase(FirebaseServer);
db.onAuth(db_onAuth);

Step 2: Verify Widget Operation

Verify that the widget is operating by running node index.js, and then manipulating the Firebase database manually.

Step 3: Install and Configure the Plugin on the Homebridge Server

On your homebridge server install the homebridge-fireswitch plugin: sudo npm install -g homebridge-fireswitch

Modify ~/.homebridge/config.json

{
    "bridge": {
        "name": "Homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "031-45-154"
    },

    "description": "My Homebridge Server",

    "accessories": [
        {
            "accessory": "FireSwitch",
            "name": "Firebase Switch",
            "description": "Testing the FireSwitch",
            "server": "https://myfirebaseurl.firebaseio.com/",
            "path": "{$uid}/command",
            "on_value": "ON",
            "off_value": "OFF",
            "auth_method": "password",
            "auth_credentials": {
                "email": "myemail@example.com",
                "password": "my_secret_password"
            }
        }
    ]
}

Step 4: Run Homebridge

homebridge

If you have not already connected your phone with your Homebridge server do so now. The new "Home" App in iOS 10 (beta) should work great, otherwise visit the Adding Homebridge to iOS page for more information.

Once your phone is connected to your Homebridge server the new accessory should show up. As you tell Siri to operate the switch you should see the corresponding values change in your Firebase instance and the PerformOnAction() and PerformOffAction() functions should be called.