homebridge-ws-beta v0.11.16

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.

Note-RED is a visual tool for wiring together hardware devices, APIs and online services.

Please note that you can only get the accessories which are added via this homebridge-websocket plugin. The same applies to the homebridge-mqtt plugin. See comments here

Installation

If you are new to Homebridge, please first read the documentation to install Homebridge.

Install homebridge-websocket:

sudo npm install -g homebridge-websocket

Configuration

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

{
  "platform" : "websocket",
  "name" : "websocket",
  "port": 4050
}

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>}}

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"}}

or with the additional accessory informations

{"topic": "add", "payload": {"name": "flex_lamp", "service": "Switch", "manufacturer": "lamp_manu", "model": "flex_007", "serialnumber": "4711", "firmwarerevision": "1.0.0"}}

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.

Websocket client (node-RED)

Here's an example flow. It shows how to add an accessory (office_lamp) and how to set the value on/off. The messages sent from the homebridge-websocket are displayed on the debug tap.

node-RED websocket settings:

Type:     Connect to
URL:      ws://127.0.0.1:4050
option:   Send/Receice intery message

Take a look at collection/homebridge-websocket for the example-flow.json which you can import into node-RED.