homebridge-websocket
Version:
Websocket Plugin for Homebridge
210 lines (151 loc) • 5.72 kB
Markdown
# homebridge-websocket
[![NPM version][npm-image]][npm-url]
[npm-image]: http://img.shields.io/npm/v/homebridge-websocket.svg
[npm-url]: https://npmjs.org/package/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](http://nodered.org/) 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](https://github.com/cflurin/homebridge-mqtt/issues/8)
### Installation
If you are new to Homebridge, please first read the [documentation](https://github.com/nfarina/homebridge) to install Homebridge.
Install homebridge-websocket:
```sh
sudo npm install -g homebridge-websocket
```
### Configuration
Add the websocket-platform in config.json in your home directory inside `.homebridge`.
```sh
{
"platform" : "websocket",
"name" : "websocket",
"port": 4050
}
```
### Websocket Uri
The homebridge-websocket is listen on:
```sh
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:
```sh
{"topic": <function>, "payload": {<data>}}
```
function | input / output
-------- | ---------
add | output
remove | output
get | output
setValue | output
set | input
get | input
response | input
callback | output
```sh
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)**
```sh
{"topic": "add", "payload": {"name": "flex_lamp", "service": "Switch"}}
```
or with the additional accessory informations
```sh
{"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:
```sh
{"topic":"response", "payload": {"ack": true, "message": "accessory 'flex_lamp' is added."}}
```
**remove (output)**
```sh
{"topic": "remove", "payload": {"name": "flex_lamp"}}
```
After the accessory is removed homebridge sends an acknowledge message:
```sh
{"topic":"response", "payload": {"ack": true, "message": "accessory 'flex_lamp' is removed."}}
```
**get (output)**
```sh
{"topic": "get", "payload": {"name": "all"}}
```
homebridge sends an accessories list:
```sh
{"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}}
}
}
```
```sh
{"topic": "get", "payload": {"name": "temp_outdoor"}}
```
homebridge sends the accessory JSON object:
```sh
{"topic": "accessories", "payload": {
"temp_outdoor": {"service": "TemperatureSensor", "characteristics": {"CurrentTemperature": "13.4"}}
}
}
```
**setValue (output)**
```sh
{"topic": "setValue", "payload": {"name": "flex_lamp", "characteristic": "On", "value": true}}
```
**set (input)**
```sh
{"topic": "set", "payload": {"name": "flex_lamp", "characteristic": "On", "value": true}}
```
**get (input)**
```sh
{"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)**
```sh
{"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.:
```sh
{"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.:
```sh
{"topic": "add", "payload": {"name": "living_lamp", "service": "Lightbulb", "Brightness": "default"}}
```
```sh
{"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](https://github.com/KhaosT/HAP-NodeJS/blob/master/lib/gen/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:
```sh
Type: Connect to
URL: ws://127.0.0.1:4050
option: Send/Receice intery message
```
Take a look at [collection/homebridge-websocket](https://github.com/cflurin/collection/tree/master/homebridge-websocket)
for the `example-flow.json` which you can import into node-RED.