Skip to content
Homebridge Plugin
Branch: master
Clone or download
Latest commit 7d4fe0f Dec 21, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE Add LICENSE Oct 12, 2016 Update Dec 11, 2018
index.js Set Accessory Information during Add Dec 10, 2018
package.json publish v0.2.2 Dec 20, 2018


NPM version

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


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

Install homebridge-websocket:

sudo npm install -g homebridge-websocket


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:


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

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": {
{"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",
    "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",
      "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://
option:   Send/Receice intery message


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

You can’t perform that action at this time.