Powerful http lightbulb for Homebridge: https://github.com/homebridge/homebridge
ISC License
homebridge-http-lightbulb
is a Homebridge plugin with which you can configure
HomeKit light bulbs 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.
First of all you need to have Homebridge installed. Refer to the repo for
instructions.
Then run the following command to install homebridge-http-lightbulb
sudo npm install -g homebridge-http-lightbulb
All characteristic from the 'lightbulb' service have the permission to notify
the HomeKit controller of state
changes. homebridge-http-lightbulb
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-lightbulb
requests the
state of the light 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 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-lightbulb
whenever
values change. This is more efficient as the new value is updated instantly and homebridge-http-lightbulb
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-lightbulb
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 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:
accessory
<string> required: Defines the plugin used and must be set to "HTTP-LIGHTBULB" for this plugin.name
<string> required: Defines the name which is later displayed in HomeKitonUrl
<string | urlObject> required: Defines the url (and other properties when usingoffUrl
<string | urlObject> required: Defines the url (and other properties when usingstatusUrl
<string | urlObject> required: Defines the url (and other properties when usingstatusPattern
option (see below).statusPattern
<string> optional (Default: "1"): Defines a regex pattern which is compared to thestatusUrl
. When matching the status of the light bulb is set to ON otherwise OFF.brightness
<object> optional: Defines everything related to the 'Brightness' characteristic:
setUrl
<string | urlObject> required: Defines the url (and other properties when usingstatusUrl
<string | urlObject> required: Defines the url (and other properties when usingunit
property below.unit
<string> optional (Default: "percent"): Defines unit expected from the http server. The followingstatusPattern
<string> optional (Default: "([0-9]{1,3})"): Defines a regex pattern with which thebrightness.statusUrl
. The group which shouldbrightness.patternGroupToExtract
property.patternGroupToExtract
<\number> optional (Default: 1): Defines the regex group of which the brightnesswithholdPowerUpdate
<\boolean> optional (Default: false): The Home App has the quirk that when settinghue
<object> optional: Defines everything related to the 'Hue' characteristic:
setUrl
<string | urlObject> required: Defines the url (and other properties when usingstatusUrl
<string | urlObject> required: Defines the url (and other properties when usingunit
<string> optional (Default: "hsv"): Defines unit expected from the http server. The followingstatusPattern
<string> optional (Default: "([0-9]{1,3})" ["/([0-9]{1,5})/" when using zigbee unit]):hue.statusUrl
. The group which should be extracted can be configured with thehue.patternGroupToExtract
property.patternGroupToExtract
<\number> optional (Default: 1): Defines the regex group of which the huesaturation
<object> optional: Defines everything related to the 'Saturation' characteristic:
setUrl
<string | urlObject> required: Defines the url (and other properties when usingstatusUrl
<string | urlObject> required: Defines the url (and other properties when usingunit
<string> optional (Default: "percent"): Defines unit expected from the http server. The followingstatusPattern
<string> optional (Default: "([0-9]{1,3})"): Defines a regex pattern with which thesaturation.statusUrl
. The group which shouldsaturation.patternGroupToExtract
property.patternGroupToExtract
<\number> optional (Default: 1): Defines the regex group of which the saturationcolorTemperature
<object> optional: Defines everything related to the 'ColorTemperature' characteristic:colorTemperature
, hue
and saturation
must notHue
and Saturation
characteristics.ColorTemperature
characteristic.colorTemperature
is not specified, the color temperature is sent via the Hue
and Saturation
characteristics.
setUrl
<string | urlObject> required: Defines the url (and other properties when usingstatusUrl
<string | urlObject> required: Defines the url (and other properties when usingunit
property below.unit
<string> optional (Default: "mired"): Defines unit expected from the http server. The followingminValue
<number> optional (Default: 50): Defines the minimum supported temperature in theunit
. The defaut is 50 mired or 20.000 Kelvin.maxValue
<number> optional (Default: 400): Defines the maximum supported temperature in theunit
. The fault is 400 mired or 2.500 Kelvin.statusPattern
<string> optional (Default: "([0-9]{2,3})" ["([0-9]{4,5})" when using Kelvin]): Defines a regex pattern with which thecolorTemperature.statusUrl
.colorTemperature.patternGroupToExtract
property.patternGroupToExtract
<\number> optional (Default: 1): Defines the regex group of which the color temperatureauth
<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.statusCache
<number> optional (Default: 0): Defines the amount of time in milliseconds a queried valuebrightnessCache
<number> optional (Default: 0): Same as above, but for the BrightnesshueCache
<number> optional (Default: 0): Same as above, but for the Hue characteristicsaturationCache
<number> optional (Default: 0): Same as above, but for the SaturationcolorTemperatureCache
<number> optional (Default: 0): Same as above, but for thepullInterval
<integer> optional: The property expects an interval in milliseconds in which the pluginmqtt
<mqttObject> optional: Defines all properties used for mqtt connection (More on MQTT).debug
<boolean> optional: If set to true debug mode is enabled and the plugin prints more detailed information.In the Examples section are some example configurations to get you started.
The options in this section are all part of some experimental features and can change in any update.
I'm currently experimenting with allowing setting and querying device status with mqtt alongside http. So that you are for example able to manage the ON characteristic fully over mqtt and the color and brightness values over http. Currently this is only supported for the ON characteristic but I'm planning to add this for any combination of characteristics and in the long run also to get added into my homebridge-http-switch plugin if everything works well.
setPowerTopic
<string | object> optional: Defines the mqtt topic to which a message is published when youtopic
<string> required:qos
<number> optional (Default: 0):retain
<boolean> optional (Default: false):dup
<boolean> optional (Default: false):payloadFormatter
<function body> optional:getPowerTopic
<string | object> optional: Defines the mqtt topic which is subscribed to in ordertopic
<string> required:qos
<number> optional (Default: 0):messagePattern
<string> optional:patternGroupToExtract
<number> optional (Default: 1):setUrl
propertiesOn every set there are the following placeholders available which will be replaced with the respective value.
Note that for example when the setUrl
for the brightness characteristic is called, %s
will be replaced with the
new value and %brightness
will be replaced with the current/old value.
The value for the placeholders will be supplied in the specified unit.
%s
will always be replaced with the new value which will be set for the current characteristic%brightness
- current brightness level%hue
- current hue%saturation
- current saturation%colorTemperature
- current color temperature (case sensitise)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. This is usually a string for maximum flexibility with placeholders. If the 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 httpBelow is an example of an urlObject containing all 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 light bulb service:
{
"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": "Brightens",
"messagePattern": "([0-9]{1,3})"
}
]
}
This is a basic light bulb configuration supporting the required On and the optional brightness characteristic. Note that every url is simply a string and are only examples. You could also define every url using a urlObject.
{
"accessory": "HTTP-LIGHTBULB",
"name": "Light",
"onUrl": "http://localhost/api/lightOn",
"offUrl": "http://localhost/api/lightOff",
"statusUrl": "http://localhost/api/lightStatus",
"brightness": {
"setUrl": "http://localhost/api/setBrightness?brightness=%s",
"statusUrl": "http://localhost/api/getBrightness"
}
}
{
"accessory": "HTTP-LIGHTBULB",
"name": "Light",
"onUrl": "http://localhost/api/lightOn",
"offUrl": "http://localhost/api/lightOff",
"statusUrl": "http://localhost/api/lightStatus",
"brightness": {
"setUrl": "http://localhost/api/setBrightness?brightness=%s",
"statusUrl": "http://localhost/api/getBrightness"
},
"hue": {
"setUrl": "http://localhost/api/setHue?hue=%s",
"statusUrl": "http://localhost/api/getHue"
},
"saturation": {
"setUrl": "http://localhost/api/setSaturation?saturation=%s",
"statusUrl": "http://localhost/api/getSaturation"
}
}
{
"accessory": "HTTP-LIGHTBULB",
"name": "Light",
"onUrl": "http://localhost/api/lightOn",
"offUrl": "http://localhost/api/lightOff",
"statusUrl": "http://localhost/api/lightStatus",
"brightness": {
"setUrl": "http://localhost/api/setBrightness?brightness=%s",
"statusUrl": "http://localhost/api/getBrightness"
},
"colorTemperature": {
"setUrl": "http://localhost/api/setColorTemperature?temperature=%s",
"statusUrl": "http://localhost/api/getColorTemperature",
"unit": "mired"
}
}
{
"accessory": "HTTP-LIGHTBULB",
"name": "Light",
"debug": true,
"onUrl": {
"url": "http://localhost/api/light",
"method": "PUT",
"body": "{ \"on\": 1 }"
},
"offUrl": {
"url": "http://localhost/api/light",
"method": "PUT",
"body": "{ \"on\": 0 }"
},
"statusUrl": "http://localhost/api/light",
"brightness": {
"statusUrl": "http://localhost/api/light",
"setUrl": {
"url": "http://localhost/api/light",
"method": "PUT",
"body": "{ \"brightness\": %s }"
}
},
"colorTemperature": {
"statusUrl": "http://localhost/api/light",
"unit": "mired",
"minValue": 143,
"maxValue": 344,
"setUrl": {
"url": "http://localhost/api/light",
"method": "PUT",
"body": "{\"temperature\": %s }"
}
}
}
homebridge-http-lightbulb
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-lightbulb
to work with your implementation of the
homebridge-http-notification-server
.
{
"accessories": [
{
"accessory": "HTTP-LIGHTBULB",
"name": "Light",
"notificationID": "my-switlightch",
"notificationPassword": "superSecretPassword",
"onUrl": "http://localhost/api/lightOn",
"offUrl": "http://localhost/api/lightOff",
"statusUrl": "http://localhost/api/lightStatus"
}
]
}
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
characteristic
"Brightness": expects a number value
in miredcharacteristic
"Hue": expects a number value
characteristic
"Saturation": expects a number value
characteristic
"ColorTemperature": expects a number value
TODO