Homebridge-websocket

Homebridge-websocket is a Plugin for Homebridge. The Websocket-API supports the main homebridge functions. This allows you to add and control accessories from a “Bridge” or “Gateway” with a Websocket API. Node-RED is the perfect platform to use with homebridge-websocket.

Node-RED is a visual tool for wiring together hardware devices, APIs and online services.
I’ve been using this for some time now to “glue” all of my IoT devices together. Using web sockets makes this even more elegant. The combination of a MQTT broker, Node-RED and Homebridge connected trough web sockets enables me to make my iOS devices believe everything is designed for Homekit. So now Siri can control my lights, thermostat, TV or just tell me the air quality in the babyroom without having only Homekit capable devices.

Installation

If you are new to Homebridge, please first read the Homebridge documentation. If you are running on a Raspberry, you will find a tutorial in the homebridge-punt Wiki.

Install homebridge:

sudo npm install -g homebridge

Install homebridge-websocket:

sudo npm install -g homebridge-websocket

Configuration

Add the websocket-platform in config.json in your home directory inside .homebridge.

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

  "platforms": [
    {
      "platform" : "websocket",
      "name" : "websocket",
      "port": 4050
    }
  ],           

  "accessories": []
}

Websocket Uri

The homebridge-websocket is listen on:

ws://127.0.0.1:4050

Replace 127.0.0.1 with your ip-address. The port 4050 can be changed in config.json. The websocket-client (e.g. Node-RED) has to connect to homebridge-websocket.

Websocket API

The data is sent/received in a JSON format with this structure:

{topic: <function>, payload: {<data>}}
function input / output
add output
remove output
get output
setValue output
set input
get input
response input
callback output
input:  the websocket-client receives a message from the homebridge-websocket.
output: the websocket-client sends a message to the homebridge-websocket.

Howto examples:

add (output)

{topic: "add", payload: {"name": "flex_lamp", "service": "Switch"}}

After the new accessory is added homebridge-websocket sends an acknowledge message:

{"topic":"response", "payload": {"ack": true, "message": "accessory 'flex_lamp' is added."}}

remove (output)

{topic: "remove", payload: {"name": "flex_lamp"}}

After the accessory is removed homebridge sends an acknowledge message:

{"topic":"response", "payload": {"ack": true, "message": "accessory 'flex_lamp' is removed."}}

get (output)

{topic: "get", payload: {"name": "all"}}

homebridge sends an accessories list:

{"topic": "accessories", "payload": {
  "node_switch":{"service":"Switch","characteristics":{"On":true}},
  "office_lamp":{"service":"Lightbulb","characteristics":{"On":"blank","Brightness":65}},
  "at_home":{"service":"OccupancySensor","characteristics":{"OccupancyDetected":1}}
  }
}
{topic: "get", payload: {"name": "temp_outdoor"}}

homebridge sends the accessory JSON object:

{"topic": "accessories", payload: {
  "temp_outdoor": {"service": "TemperatureSensor", "characteristics": {"CurrentTemperature": "13.4"}}
  }
}

setValue (output)

{topic: "setValue", payload: {"name": "flex_lamp", "characteristic": "On", "value": true}}

set (input)

{topic: "set", payload: {"name": "flex_lamp", "characteristic": "On", "value": true}}

get (input)

{topic: "get", payload: {"name": "flex_lamp", "characteristic": "On"}}

When homebridge-websocket sends a get topic it expects a callback with the value within 1 second.

callback (output)

{topic: "callback", payload: {"name": "flex_lamp", "characteristic": "On", "value": true}}

The required characteristics are added with the default properties. If you need to change the default, define the characteristic-name with the properties. e.g.:

{topic: "add",
 payload:
  {
    "name": "temp_living",
    "service": "TemperatureSensor",
    "CurrentTemperature": {"minValue": -20, "maxValue": 60,"minStep": 1}
  }
}

To add an optional charachteristic define the characteristic-name with “default” or with the properties. e.g.:

{topic: "add", payload: {"name": "living_lamp", "service": "Lightbulb", "Brightness": "default"}}
{topic: "add",
  payload:
    {
      "name": "bathroom_blind",
      "service": "WindowCovering",
      "CurrentPosition": {"minStep": 5},
      "TargetPosition": {"minStep": 5},
      "CurrentHorizontalTiltAngle": {"minValue": 0, "minStep": 5},
      "TargetHorizontalTiltAngle": {"minValue": 0, "minStep": 5}
    }
}

HomeKitTypes.js describes all the predifined Services and Characteristcs.

node-RED

This article is mostly from: https://github.com/cflurin/homebridge-websocket

Please be aware the provided Node-Red example on github is actually not working. I found this after installing everything for the third time because it crashes Hombridge HARD.

Also make sure not to update too frequently to homekit as it blocks your devices, this is not visible in the standard apple app but is in the paid “Home” app. I yet have to find out what exactly makes the Homekit API block a device.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a website or blog at WordPress.com

Up ↑

%d bloggers like this: