Powerful http switch for Homebridge: https://github.com/homebridge/homebridge
ISC License
homebridge-http-switch
is a Homebridge plugin with which you can configure
HomeKit switches 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 lightning controlled with an wifi enabled Arduino board which than can be integrated via this plugin into Homebridge.
homebridge-http-switch
supports three different type of switches. A normal stateful
switch and two variants of
stateless switches (stateless
and stateless-reverse
) which differ in their original position. For stateless switches
you can specify multiple urls to be targeted when the switch is turned On/Off.
More about on how to configure such switches can be read further down.
First of all you need to have Homebridge installed. Refer to the repo for
instructions.
Then run the following command to install homebridge-http-switch
sudo npm install -g homebridge-http-switch
The 'On' characteristic from the 'switch' service has the permission to notify
the HomeKit controller of state
changes. homebridge-http-switch
supports two ways to send state changes to HomeKit.
The 'pull' way is probably the easiest to set up and supported in every scenario. homebridge-http-switch
requests the
state of the switch in an specified interval (pulling) and sends the value to HomeKit.
Look for pullInterval
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-switch
whenever
the value changes. This is more efficient as the new value is updated instantly and homebridge-http-switch
does not
need to make needless requests when the value didn't actually change.
However because the http device needs to actively notify the homebridge-http-switch
there is more work needed
to implement this method into your http device.
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. For shelly.cloud devices mqtt is the best and only option to implement push-updates.
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:
name
<string> required: Defines the name which is later displayed in HomeKitswitchType
<string> optional (Default: "stateful"): Defines the type of the switch:
statusUrl
to determine the currentonUrl
<string | [string] | urlObject | [urlObject]> required: Defines the urloffUrl
<string | [string] | urlObject | [urlObject]> required: Defines the urlstatusUrl
<string | urlObject> required: Defines the urlstatusPattern
option.serialNumber
<string> optional (Default: "SW01"): Defines a custom serial number shown in the home app.statusPattern
<string> optional (Default: "1"): Defines a regex pattern which is compared to the body of the statusUrl
.statusCache
<number> optional (Default: 0): Defines the amount of time in milliseconds a queried stateauth
<object> optional: If your http server requires authentication you can specify your credential in thisonUrl
, offUrl
and statusUrl
.username
<string> required
password
<string> required
sendImmediately
<boolean> optional (Default: true): When set to true the plugin will send theWWW-Authenticate
header.httpMethod
deprecated <string> optional: If defined it sets the http method for onUrl
and offUrl
.timeout
<integer> optional (Default: 1000): When using a stateless switch this timeout inpullInterval
<integer> optional: The property expects an interval in milliseconds in which the pluginswitchType
is "stateful")mqtt
<mqttObject> optional: Defines all properties used for mqtt connection.multipleUrlExecutionStrategy
<string> optional (Default: "parallel"): Defines the strategy used whendebug
<boolean> optional: If set to true debug mode is enabled and the plugin prints more detailed information.Below are two example configurations. One is using simple string urls and the other is using simple urlObjects. Both configs can be used for a basic plugin configuration.
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"switchType": "stateful",
"onUrl": "http://localhost/api/switchOn",
"offUrl": "http://localhost/api/switchOff",
"statusUrl": "http://localhost/api/switchStatus"
}
]
}
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"switchType": "stateful",
"onUrl": {
"url": "http://localhost/api/switchOn",
"method": "GET"
},
"offUrl": {
"url": "http://localhost/api/switchOff",
"method": "GET"
},
"statusUrl": {
"url": "http://localhost/api/switchStatus",
"method": "GET"
}
}
]
}
A urlObject can have the following properties:
url
<string> required: Defines the url pointing to your http servermethod
<string> optional (Default: "GET"): Defines the http method used to make the http requestbody
<any> optional: Defines the body sent with the http request. If value is not a string it will bestrictSSL
<boolean> optional (Default: false): If enabled the SSL certificate used must be valid andauth
<object> optional: If your http server requires authentication you can specify your credential in thisusername
<string> required
password
<string> required
sendImmediately
<boolean> optional (Default: true): When set to true the plugin will send theWWW-Authenticate
header.headers
<object> optional: Using this object you can define any http headers which are sent with the httprequestTimeout
<number> optional (Default: 20000): Time in milliseconds specifying timeout (Time to waitrepeat
<number> optional (Default: 1): Defines how often the execution of this urlObject shouldonUrl
or offUrl
.multipleUrlExecutionStrategy
property. Using "parallel" execution could result indelayBeforeExecution
<number> optional (Default: 0): Defines the time in milliseconds to waitonUrl
or offUrl
.multipleUrlExecutionStrategy
property.Below is an example of an urlObject containing the basic properties:
{
"url": "http://example.com:8080",
"method": "GET",
"body": "exampleBody",
"strictSSL": false,
"auth": {
"username": "yourUsername",
"password": "yourPassword"
},
"headers": {
"Content-Type": "text/html"
}
}
A mqttObject can have the following properties:
host
<string> required: Defines the host of the mqtt broker.port
<number> optional (Default: 1883): Defines the port of the mqtt broker.credentials
<object> optional: Defines the credentials used to authenticate with the mqtt broker.
username
<string> required
password
<string> optional
subscriptions
<object | array> required: Defines an array (or one single object) of subscriptions.
topic
<string> required: Defines the topic to subscribe to.characteristic
<string> required: Defines the characteristic this subscription updates.messagePattern
<string> optional: Defines a regex pattern. If messagePattern
is not specified thepatternGroupToExtract
.patternGroupToExtract
<number> optional (Default: 1): Defines the regex group of which data isprotocol
<string> optional (Default: "mqtt"): Defines protocol used to connect to the mqtt brokerqos
<number> optional (Default: 1): Defines the Quality of Service (Notice, the QoS of the publisher0
: 'At most once' - the message is sent only once and the client and broker take no additional steps to1
: 'At least once' - the message is re-tried by the sender multiple times until acknowledgement is2
: 'Exactly once' - the sender and receiver engage in a two-level handshake to ensure only one copy of theclientId
<string> optional (Default: 'mqttjs_' + Math.random().toString(16).substr(2, 8)
): Defines clientIdkeepalive
<number> optional (Default: 60): Time in seconds to send a keepalive. Set to 0 to disable.clean
<boolean> optional (Default: true): Set to false to receive QoS 1 and 2 messages while offline.reconnectPeriod
<number> optional (Default: 1000): Time in milliseconds after which a reconnect is tried.connectTimeout
<number> optional (Default: 30000): Time in milliseconds the client waits until theBelow is an example of an mqttObject containing the basic properties for a switch service:
{
"host": "127.0.0.1",
"port": 1883,
"credentials": {
"username": "yourUsername",
"password": "yourPassword"
},
"subscriptions": [
{
"topic": "your/topic/here",
"characteristic": "On",
"messagePattern": "on"
}
]
}
Since OFF is the only possible state you do not need to declare offUrl
and statusUrl
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"switchType": "stateless",
"timeout": 1000,
"onUrl": "http://localhost/api/switchOn"
}
]
}
Since ON is the only possible state you do not need to declare onUrl
and statusUrl
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"switchType": "stateless-reverse",
"timeout": 1000,
"offUrl": "http://localhost/api/switchOff"
}
]
}
If you wish to do so you can specify an array of urls or urlObjects (onUrl
or offUrl
) when your switch is a
stateless switch or a reverse-stateless switch.
This is not possible with a normal stateful switch.
Below are two example configurations of an stateless switch with three urls. One is using simple string array and the other is using simple urlObject arrays.
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"switchType": "stateless",
"onUrl": [
"http://localhost/api/switch1On",
"http://localhost/api/switch2On",
"http://localhost/api/switch3On"
]
}
]
}
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"switchType": "stateless",
"onUrl": [
{
"url": "http://localhost/api/switch1On"
},
{
"url": "http://localhost/api/switch2On"
},
{
"url": "http://localhost/api/switch3On"
}
]
}
]
}
When using multiple urls and "series" as multipleUrlExecutionStrategy
you can also specify so called delay urls in the
onUrl
or offUrl
arrays. This could be used to guarantee a certain delay between two urls.
The delay url has the following pattern: "delay(INTEGER)" where 'INTEGER' is replaced with the delay in milliseconds.
Here is an example:
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Delayed Switch",
"switchType": "stateless",
"multipleUrlExecutionStrategy": "series",
"onUrl": [
"http://localhost/api/switch1On",
"delay(1000)",
"http://localhost/api/switch2On"
]
}
]
}
The statusPattern
property can be used to change the phrase which is used to identify if the switch should be turned on
or off. So when you want the switch to be turned on when your server sends "true" in the body of the http response you
could specify the following pattern:
{
"statusPattern": "true"
}
However using Regular Expressions much more complex patterns are possible. Let's assume your http enabled device responds with the following json string as body, where one property has an random value an the other indicates the status of the switch:
{
"perRequestRandomValue": 89723789,
"switchState": true
}
Then you could use the following pattern:
{
"statusPattern": "{\n \"perRequestRandomValue\": [0-9]+,\n \"switchState\": true\n}"
}
Note: The statusPattern
must be placed on the same level as the statusUrl
property, not inside the statusUrl
object. See below for example.
{
"statusUrl": {
},
"statusPattern": "....",
}
More on how to build regex patterns: https://www.w3schools.com/jsref/jsref_obj_regexp.asp
homebridge-http-switch
can be used together with
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 homebridge-http-notification-server
, please refer to the
README of the repository first.
Down here is an example on how to configure homebridge-http-switch
to work with your implementation of the
homebridge-http-notification-server
.
{
"accessories": [
{
"accessory": "HTTP-SWITCH",
"name": "Switch",
"notificationID": "my-switch",
"notificationPassword": "superSecretPassword",
"onUrl": "http://localhost/api/switchOn",
"offUrl": "http://localhost/api/switchOff",
"statusUrl": "http://localhost/api/switchStatus"
}
]
}
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 value