Homebridge-hdl-buspro NPM

homebridge-hdl-buspro

HomeKit integration for HDL Buspro relays

homebridge-hdl-buspro is a homebridge plugin to control your devices on the HDL Buspro buses from Home app on iOS. It currently supports the following types of devices:

Features

Relay Lightbulbs
Relay Dimmable Lightbulbs
Sensors 8 in 1 (dry contacts not supported yet)
Dry contact relays
Relay locks
Relay curtains (including custom valve usage)

Heaters and security systems may be supported in later versions.

Installation

If you are new to homebridge, please first read the homebridge documentation. If you are running on a Raspberry, you will find a tutorial in the homebridge wiki.

Install homebridge:

sudo npm install -g homebridge

Install homebridge-hdl-buspro:

sudo npm install -g homebridge-hdl-buspro

Configuration

Add the HDLBusproHomebridge platform in config.json in your home directory inside .homebridge.

This plugin cannot discover devices on its own, for this you should use software like HDL Buspro setup tool v2 (you can download it here). Use it to get info on your bus ip, port, its subnets, devices and all separate channels on relays to use these numbers in config with your custom names. You should also give a number for a virtual device on each subnet that will be used by plugin to send and receive commands and data on behalf of this plugin. Just choose whatever number is not occupied by other devices.

Typical HDL structure goes like this: bus-subnet-device-channel

Example configuration:

        {
            "buses": [
                "bus_name": "Main Bus",
                "bus_IP": "10.0.0.1",
                "bus_port": 6000
                {
                    "subnets": [
                        {
                            "subnet_number": 1,
                            "cd_number": 55,
                            "devices": [
                                {
                                    "device_name": "Living room lights",
                                    "device_address": 13,
                                    "device_type": "relaylightbulb",
                                    "channel": 4
                                },
                                {
                                    "device_name": "Dining room sensor",
                                    "device_address": 21,
                                    "device_type": "sensor8in1"
                                },
                                {
                                    "device_name": "Bathroom leak sensor",
                                    "device_address": 69,
                                    "device_type": "drycontact",
                                    "area": 1,
                                    "channel": 1,
                                    "drycontact_type": "leaksensor",
                                    "nc": false
                                },
                                {
                                    "device_name": "Garden backdoor",
                                    "device_address": 6,
                                    "device_type": "relaylock",
                                    "channel": 2,
                                    "nc": true
                                }
                            ]
                        }
                    ]
                }
            ],
            "platform": "HDLBusproHomebridge"
        },

Parameters

Platform Configuration fields

platform required Should always be "HDLBusproHomebridge".
buses required A list of your buses

Bus configuration fields

bus_name required Name of your bus.
bus_ip required ip address of your bus
port required port of your bus
subnets required A list of subnets on this bus

Subnet configuration fields

subnet_number required Separate number for each subnet
cd_number required Any unoccupied number on subnet to control your devices from
devices optional Add all devices on subnet you need

Device configuration fields

device_name optional Your custom name for device, will be shown in Home app by default
device_address required Number of device in subnet
device_type required Specify the type of device
- Available values:
  - "relaylightbulb" - relay lights
  - "relaydimmablelightbulb" - relay dimmable lights
  - "sensor8in1" - multisensor
  - "relaylock" - custom use of light relay to control a lock
  - "drycontact" - dry contact relay
  - "relaycurtains" - relay curtains (have to be calibrated in HDL)
  - "relaycurtainvalve" - custom usage of curtains relay to control a water valve
channel optional Specify channel for a specific light group, curtains or dry contact of relay
area optional Needed for some dry contact relays
nc required You can flip the logic of dry contact relay or lock with this parameter
drycontact_type required Specify what your dry contact sensor does
- Available values:
  - "leaksensor" - leak sensor
  - "contactsensor" - contact sensor
  - "smokesensor" - smoke sensor
  - "occupancysensor" - occupancy sensor
lock_timeout required An option to close lock automatically after specified time in seconds. Default is 0, which is usual lock behavior
duration required HDL can only control partial curtain opening by timer, so you have to calibrate how long it takes to fully open curtain, put this value to HDL and copy it here to avoid misalignment
curtains_precision required Due to a lag between HDL and HB curtain timers there has to be some precision offset, or it might get bugged in "opening" status. Increase this value if you encounter it.
valvetype required You can choose 4 valve types: "General Valve", "Irrigation", "Shower Head", "Water Faucet".

Troubleshooting

If you have any issues with the plugin then you can run homebridge in debug mode, which will provide some additional information. This might be useful for debugging issues.

Please keep in mind that I could only test how plugin works on devices I have at home, and some devices were coded only based on documentation. So feel free to open issues here if you encounter problems/need your device supported!

Homebridge debug mode: