homebridge-pubnub

Let's say you built a Pyton program running on Raspberry-Pi managing a thermostat. If you wanted to connect it with Siri (HomeKit), homebridge-pubnub would be perfect for that.

You have to make your Pyton program listen to PubNub for any HomeKit commands coming from iOS/Siri, and then control the thermostat accordingly. Also, when the user physically turns off the thermostat, your Pyton program has to report this change to HomeKit.

PubNub and RabbitMQ are both supported on a variety of platforms/programming languages and are easy to implement. The difference is that RabbitMQ works only locally, while PubNub sends messages over the internet. You may use both or just one in this plugin.

Installation

1. Install homebridge using: npm install -g homebridge
2. Install homebridge-rabbitmq using: npm install -g homebridge-pubnub
3. Update your configuration file (/home/username/.homebridge/config.json)

Configuration

In the config.json, PubNub accessories will look something like this:

"accessories": [ 
    {
        "accessory":          "PubNub",
        "name":               "Basement Pump",
        "service":            "Switch",      
        "pubnub_publishKey":  "pub-c-e3ea66a0-138a-xxxx-xxxx-76bc98ded9de",
        "pubnub_subscribeKey":"sub-c-7fe92286-de40-xxxx-xxxx-0619f8945a4f"
    },
    {
        "accessory":          "PubNub",
        "name":               "Bed Lamp",
        "service":            "Light",
        "pubnub_publishKey":  "pub-c-e3ea66a0-138a-xxxx-xxxx-76bc98ded9de",
        "pubnub_subscribeKey":"sub-c-7fe92286-de40-xxxx-xxxx-0619f8945a4f"
    },
    {
        "accessory":          "PubNub",
        "name":               "My LEDs",
        "service":            "Light",
        "pubnub_publishKey":  "pub-c-e3ea66a0-138a-xxxx-xxxx-76bc98ded9de",
        "pubnub_subscribeKey":"sub-c-7fe92286-de40-xxxx-xxxx-0619f8945a4f"
    }
]

Legend:

• accessory = always "PubNub"
• name - something like "Cloe's Lamp"
• service - Switch, Light or Thermostat (just these 3 for now...)
• pubnub_publishKey (optional) - specify in every PubNub accessory
• pubnub_subscribeKey (optional) - get these two on www.pubnub.com

Receiving messages inside your app

When user uses iOS/Siri to change a homebridge accessory, homebridge will send a message to PubNub channel named "homebridge". Optionaly, if RabbitMQ server is running on localhost, message will be sent there too, on queue "homebridge"!

Example: Received Message from PubNub:

eyANCiAgInNlcnZpY2UiOiAiTGlnaHQiLA0KICAibmFtZSI6ICJDbG9lJ3MgTGFtcCIsDQogICJtZXRob2QiOiAiYnJpZ2h0bmVzcyIsDQogICJ2YWx1ZSI6IDgwLjANCn0g

After decoding from base64 string to normal string:

{ 
  "hbtype": "homekitCommand",
  "hbUID": "lm2ukj"
  "service": "Light",
  "name": "Cloe's Lamp",
  "method": "brightness",
  "value": 80.0
} 

TIP: hbUID is a unique identifier (randomly generated string). If you use both RabbitMQ and PubNub in your application, use this identifier to avoid processing same json twice.

Sending messages from your app

When you (or another app of yours) changes the powerstate, brightness, temperature, etc. of the real-life device, you need to report this change back to homebridge. To do that, have your app send a JSON like this:

{ 
  "hbtype: "externalUpdate",   <- must be included
  "service": "Light",
  "name": "Cloe's Lamp",
  "method": "hue",
  "value": 360
} 

NOTE: Just like in receiving, messages sent to PubNub must be in base64 format. Otherwise, PubNub service may refuse to deliver them.

Getting a list of all available PubNub accessories

Send this JSON to receive a list of all PubNub accessories currently loaded in Homebridge:

{
    hbtype:requestAccessories
}

Getting a dictionary of all current values

Send this JSON to receive dictionary containing all the names and values for each PubNub accessory loaded in Homebridge.

{
    hbtype:requestInfo
}

List of methods/values

List of all possible Methods:

• Switch - powerState
• Light - powerState, brightness, hue, saturation
• Thermostat - targetHeatingCoolingState, targetTemperature, temperatureDisplayUnits

List of all possible Values

• PowerState: 0 = off, 1 = on
• Hue: 0 - 360
• Saturation: 0 - 100
• Brightness: 0 - 100
• TargetTemperature: any number
• HeatingCoolingStates: 0 = off, 1 = heat, 2 = cool, 3 = auto
• TemperatureDisplayUnits: 0 = Celsius, 1 = Fahrenheit

Bonus: Testing Homebridge

Aside from sending PubNub/RabbitMQ messages, homebridge-pubnub can also execute terminal commands. You can use variables inside those commands: #NAME# and #VALUE#. In config.json, in PubNub accessory simply add a new key/value:

"[method]_command":"[terminal command here]"

Example:

{
        "accessory":          "PubNub",
        "name":               "Cloe's Lamp",
        "service":            "Light", 
        "brightness_command": "sudo gpio pin 3 pwm #VALUE# -g"
}