homebridge-http-rgb-push

Homebridge plugin to control a HTTP-based RGB device.

Supports RGB HTTP(S) devices on the HomeBridge Platform and provides a readable callback for getting and setting the following characteristics to Homekit:

• Characteristic.On
• Characteristic.Brightness
• Characteristic.Hue
• Characteristic.Saturation

What is this fork?

This fork differs from the original jnovack/homebridge-better-http-rgb in the following ways:

• Supports homebridge-http-notifiation-server to allow the device to push it's status changes instead of poll based pull. E.g. if you have one device that allows for multiple different effects while only one can be active at the same time. HomeKit can then show multiple switches representing one device. The group of switches will function as a radio button since the device will push the off status for the other switches. Or when you manually reboot the device to notify HomeKit of its updated state after reboot.
• Supports regular expression pattern matching for on/off switches to determine whether the body reflects an on or off status.
• Fixes a bug which causes the original plugin to not report the correct manufacturer, make and model towards HomeKit.
• Briefly turn off/on or on/off the light/switch to locate the device's physical location when HomeKit requests 'identify'.
• Added timeout parameter to prevent HomeBridge from getting stuck on a single unresponsive device. Credits: Tommrodrigues/homebridge-better-http-rgb.
• Added error handling for non HTTP 200 status code replies.
• README rewrite and corrections.
• Allow GET requests with body matching for colour and status. Credits: Michael Mezger

Installation

1. Install homebridge using: npm install -g homebridge
2. Install homebridge-http-rgb-push using: sudo npm install -g homebridge-http-rgb-push
3. Update your configuration file. See below for examples.

Note: See Installing packages globally when you experience permission problems.

Uninstall

To uninstall homebridge-better-http-rgb, simply run:

sudo npm uninstall -g homebridge-http-rgb-push

Configuration

Examples

Full RGB Device

 "accessories": [
     {
         "accessory": "HttpPushRgb",
         "name": "RGB Led Strip",
         "service": "Light",
         "timeout": 3000,

         "switch": {
             "status": "http://localhost/api/v1/status",
             "powerOn": "http://localhost/api/v1/on",
             "powerOff": "http://localhost/api/v1/off"
         },

         "brightness": {
             "status": "http://localhost/api/v1/brightness",
             "url": "http://localhost/api/v1/brightness/%s"
         },

         "color": {
             "status": "http://localhost/api/v1/set",
             "url": "http://localhost/api/v1/set/%s",
             "brightness": true
         }
     }
 ]

Single Color Light that only turns "off" and "on"

 "accessories": [
     {
         "accessory": "HttpPushRgb",
         "name": "Single Color Light",
         "service": "Light",

         "switch": {
             "status": "http://localhost/api/v1/status",
             "powerOn": "http://localhost/api/v1/on",
             "powerOff": "http://localhost/api/v1/off"
         }
     }
 ]

Single Color Light with Brightness

 "accessories": [
     {
         "accessory": "HttpPushRgb",
         "name": "Single Color Light",
         "service": "Light",

         "switch": {
             "status": "http://localhost/api/v1/status",
             "powerOn": "http://localhost/api/v1/on",
             "powerOff": "http://localhost/api/v1/off"
         },

         "brightness": {
             "status": "http://localhost/api/v1/brightness",
             "url": "http://localhost/api/v1/brightness/%s"
         }
     }
 ]

RGB Light without Brightness

 "accessories": [
     {
         "accessory": "HttpPushRgb",
         "name": "Single Color Light",
         "service": "Light",

         "switch": {
             "status": "http://localhost/api/v1/status",
             "powerOn": "http://localhost/api/v1/on",
             "powerOff": "http://localhost/api/v1/off"
         },

         "color": {
             "status": "http://localhost/api/v1/set",
             "url": "http://localhost/api/v1/set/%s"
         }
     }
 ]

This normally will not occur, however, you may not want your application to display a "brightness" slider to the user. In this case, you will want to remove the brightness component from the config.

Full RGB Device with advanced SET / GET Handling

Following configuration is a real world example for a accessory that combines a shelly switch / relay with a hue light bulb. ON/OFF-Signals will be sent to the shelly switch. On the other hand, changes to brightness / color are going to the hue bulb.

"accessories": [
    {
        "accessory": "HttpPushRgb",
        "name": "Full RGB Device with advanced SET / GET Handling",
        "service": "Light",
        "timeout": 3000,
        "switch": {
            "notificationID": "47110815",
            "status": {
                "url": "http://192.168.0.110/status",
                "bodyRegEx": "\"ison\":true"
             },
             "powerOn": "http://192.168.0.110/relay/0?turn=on",
             "powerOff": "http://192.168.0.110/relay/0?turn=off"
        },
        "brightness": {
            "status": {
                "url": "http://192.168.0.120/api/<apikey>/lights/6/",
                "bodyRegEx": "\"bri\":([0-9]+)"
            },
            "url": {
                "url":"http://192.168.0.120/api/<apikey>/lights/6/state",
                "body": "{\"bri\": %s}"
            },
            "http_method": "PUT",
            "max": 254
        },
        "color": {
            "status": {
                "url": "http://192.168.0.120/api/<apikey>/lights/6/",
                "bodyRegEx": "\"bri\":([0-9]+)"
            },
            "url": {
                "url":"http://192.168.0.120/api/<apikey>/lights/6/state",
                "body": "{\"xy\": [%xy-x,%xy-y]}"
            },
            "brightness": false,
            "http_method": "PUT"
        }
    }
]

Regular expression on-body matching

"accessories": [
    {
        "accessory": "HttpPushRgb",
        "name": "JSON body matching",
        "service": "Light",

        "switch": {
            "status": {
                "url": "http://localhost/api/v1/status",
                "bodyRegEx": "\"switch\":\s*\"on\""
            }
            "powerOn": "http://localhost/api/v1/on",
            "powerOff": "http://localhost/api/v1/off"
        }
        }
    }
]

Structure

Switch object

Switch status object

Brightness object

Brightness status object

Brightness url object

Color object

Color status object

Color url object

Device responses

Pull method: HomeBridge polls

All .status urls expect a 200 HTTP status code.

switch.status Can be configured to parse the body to determine the switch status. When the specified switch.status.bodyRegEx matches the body the switch is considered to be in the on status. If this parameter is left out switch.status expects 0 for Off, and 1 for On.

All other .status urls expect a body of a single string with no HTML markup.

• brightness.status expects a number from 0 to 100.
• color.status expects a 6-digit hexidemial number.

Push responses: Device pushes updates

This accessory supports push notification from the physical device via homebridge-http-notification-server. This allows the device to modify the switch's status by pushing the new status instead of Homebridge pulling it. This can be realized by supplying the notificationID as part of this accesory's configuration. Your device should then push the On characteristic towards the notification server. E.g. a POST request towards http://<homebridge-host>:<notification-server-port>/<notificationID> with the following body:

{
   "characteristic": "On",
   "value": true
}

To get more details about the push configuration have a look at the notification server's README.