Http outlet for Homebridge
npm install homebridge-http-outlethomebridge-http-outlet is a Homebridge plugin with which you can configure
HomeKit outlets which forward any requests to a defined http server. This comes in handy when you already have home
automated equipment which can be controlled via http requests. Or you have built your own equipment, for example some sort
of outlet controlled with an wifi enabled Arduino board which than can be integrated via this plugin into Homebridge.
First of all you need to have Homebridge installed. Refer to the repo for
instructions.
Then run the following command to install homebridge-http-outlet
```
sudo npm install -g homebridge-http-outlet
All characteristic from the _'outlet'_ service have the permission to notify the HomeKit controller of state homebridge-http-outlet
changes. supports two concepts to send state changes to HomeKit.
The 'pull' way is probably the easiest to set up and supported in every scenario. homebridge-http-outlet requests the pullInterval
state of the outlet in an specified interval (pulling) and sends the value to HomeKit.
However the pull way is currently only supported for the _'On'_ characteristic!
Look for in the list of configuration options if you want to configure it.
When using the 'push' concept, the http device itself sends the updated value to homebridge-http-outlet whenever homebridge-http-outlet
values change. This is more efficient as the new value is updated instantly and does not homebridge-http-outlet
need to make needless requests when the value didn't actually change.
However because the http device needs to actively notify the there is more work needed
to implement this method into your http device.
#### Using MQTT:
MQTT (Message Queuing Telemetry Transport) is a protocol widely used by IoT devices. IoT devices can publish messages
on a certain topic to the MQTT broker which then sends this message to all clients subscribed to the specified topic.
In order to use MQTT you need to setup a broker server (mosquitto is a solid
open source MQTT broker running perfectly on a device like the Raspberry Pi) and then instruct all clients to
publish/subscribe to it.
#### Using 'homebridge-http-notification-server':
For those of you who are developing the http device by themselves I developed a pretty simple 'protocol' based on http
to send push-updates.
How to implement the protocol into your http device can be read in the chapter
Notification Server
The configuration can contain the following properties:
##### Basic configuration options:
- accessory \name
- \
* onUrl \offUrl
an urlObject) which is called when you turn on the outlet.
* \statusUrl
an urlObject) which is called when you turn off the outlet.
* \statusPattern
an urlObject) to query the current power state from the outlet. By default it expects the http server to
return '1' for ON and '0' for OFF leaving out any html markup.
You can change this using option (see below).statusPattern
* \statusUrl
body of the http response from the . When matching the status of the outlet is set to ON otherwise OFF.
More about regex pattern.
- outletInUse \statusUrl \statusPattern
and urlObject) to query if the outlet is currently in use. By default it expects the http server
to '1' for IN USE and '0' for NOT IN USE.
- \outletInUse.statusUrl
body of the http response from the .
When matching the status of the outlet is set to IN USE otherwise NOT IN USE.
##### Advanced configuration options:
* auth \username \password
* \sendImmediately
* \WWW-Authenticate
credentials immediately to the http server. This is best practice for basic authentication.
When set to false the plugin will send the proper authentication header after receiving an 401 error code
(unauthenticated). The response from the http server must include a proper header.
Digest authentication requires this property to be set to false!
- statusCache \outletInUseCache
of the _On_ characteristic is cached before a new request is made to the http device.
Default is 0 which indicates no caching. A value of -1 will indicate infinite caching.
- \
characteristic
* pullInterval \mqtt
pulls updates from your http device. For more information read pulling updates.
(This option is currently only supported for the _'On'_ characteristic!)
* \<mqttObject\> optional: Defines all properties used for mqtt connection (More on MQTT).
For configuration see mqttObject.
- debug \
In the Examples section are some example configurations to get you started.
#### UrlObject
A urlObject can have the following properties:
* url \method
* \body
* \strictSSL
converted to a JSON string automatically.
* \auth
the whole certificate chain must be trusted. The default is false because most people will work with self signed
certificates in their homes and their devices are already authorized since being in their networks.
* \username \password
* \sendImmediately
* \WWW-Authenticate
credentials immediately to the http server. This is best practice for basic authentication.
When set to false the plugin will send the proper authentication header after receiving an 401 error code
(unauthenticated). The response must include a proper header. headers
Digest authentication requires this property to be set to false!
* \`json`
{
"url": "http://example.com:8080",
"method": "GET",
"body": "exampleBody",
"strictSSL": false,
"auth": {
"username": "yourUsername",
"password": "yourPassword"
},
"headers": {
"Content-Type": "text/html"
}
}
#### MQTTObject
A mqttObject can have the following properties:
##### Basic configuration options:
* host \port
* \credentials
* \username \password
* \subscriptions
- \topic \characteristic
- \messagePattern
- \messagePattern is not specified the patternGroupToExtract
message received will be used as value. If the characteristic expects a boolean value it is tested if the
specified regex is contained in the received message. Otherwise the pattern is matched against the message
and the data from regex group can be extracted using the given .patternGroupToExtract
- \
extracted.
##### Advanced configuration options:
* protocol \qos
* \0
must also be configured accordingly).
In contrast to most implementations the default value is 1.
* : 'At most once' - the message is sent only once and the client and broker take no additional steps to 1
acknowledge delivery (fire and forget).
* : 'At least once' - the message is re-tried by the sender multiple times until acknowledgement is 2
received (acknowledged delivery).
* : 'Exactly once' - the sender and receiver engage in a two-level handshake to ensure only one copy of the clientId
message is received (assured delivery).
* \'mqttjs_' + Math.random().toString(16).substr(2, 8)\): Defines clientIdkeepalive
* \clean
* \reconnectPeriod
* \connectTimeout
* \
CONNECT needs to be acknowledged (CONNACK).
Below is an example of an mqttObject containing the basic properties for an outlet service:
`json`
{
"host": "127.0.0.1",
"port": "1883",
"credentials": {
"username": "yourUsername",
"password": "yourPassword"
},
"subscriptions": [
{
"topic": "your/topic/here",
"characteristic": "On",
"messagePattern": "on"
},
{
"topic": "your/other/topic/here",
"characteristic": "OutletInUse",
"messagePattern": "inuse"
}
]
}
#### Basic outlet with power
This is a basic outlet configuration supporting the required On and the optional OutletInUse characteristic.
Note that every url is simply a string and are only examples. You could also define every url using a urlObject.
``json``
{
"accessory": "HTTP-OUTLET",
"name": "Outlet",
"onUrl": "http://localhost/api/outletOn",
"offUrl": "http://localhost/api/outletOff",
"statusUrl": "http://localhost/api/outletStatus"
}
#### Outlet supporting outletInUse
``json``
{
"accessory": "HTTP-OUTLET",
"name": "Outlet",
"onUrl": "http://localhost/api/outletOn",
"offUrl": "http://localhost/api/outletOff",
"statusUrl": "http://localhost/api/outletStatus",
"outletInUse": {
"statusUrl": "http://localhost/api/isOutletInUse"
}
}
homebridge-http-outlet can be used together with homebridge-http-notification-server
homebridge-http-notification-server in order to receive
updates when the state changes at your external program. For details on how to implement those updates and how to
install and configure , please refer to the
README of the repository first.
Down here is an example on how to configure homebridge-http-outlet to work with your implementation of the homebridge-http-notification-server.
`json`
{
"accessories": [
{
"accessory": "HTTP-OUTLET",
"name": "Outlet",
"notificationID": "my-outlet",
"notificationPassword": "superSecretPassword",
"onUrl": "http://localhost/api/outletOn",
"offUrl": "http://localhost/api/outletOff",
"statusUrl": "http://localhost/api/outletStatus"
}
]
}
* notificationID is an per Homebridge instance unique id which must be included in any http request. notificationPassword
* is optional. It can be used to secure any incoming requests.
To get more details about the configuration have a look at the
README.
Available characteristics (for the POST body)
Down here are all characteristics listed which can be updated with an request to the homebridge-http-notification-server
* characteristic "On": expects a boolean valuecharacteristic
* "OutletInUse": expects a boolean value`