C-Bus for Homebridge
HomeKit-enable your C-Bus installation with the
homebridge-cbus plugin for the Homebridge server.
Once setup, a homebridge server with the
homebridge-cbus plugin will allow you to instantly monitor and control all of your supported C-Bus accessories.
What does that mean? You'll be able to control your home with:
- Siri voice commands
- the built-in iOS 10+ Home app
- iOS apps that support HomeKit.
To see some action of HomeKit controlling a Clipsal C-Bus system, check out the following videos:
This project provides a bridge which 'exposes' your devices in a way that you can control then using HomeKit.
homebrige-cbus is currently able to control and/or monitor:
- switches (with optional timeout)
- shutter relays
- motion sensors
- security presence detectors
- trigger events
- contact sensors
- smoke Sensor
- temperature sensors
If you need support for a new device type, feel free to open an issue, or have a go cutting code yourself. If you have some familiarity with Node.js you'll find it pretty straightforward.
After installing and setting up Homebridge, you can install the
homebridge-cbus plugin with:
npm install -g homebridge-cbus
Once installed, update your Homebridge's
N.B. you will need a C-Bus C-Gate server on your network. This is a cross platform Java application which runs on most platforms.
As with other Homebridge plugins, you configure the
homebridge-cbus plugin by adding it to your
N.B. If you are connecting to a remote C-Gate server, you will likely need to configure C-Gate for remote connections by adding an interface entry to the file
Configuration platform fields
name: platform and name – you may leave these values
client_ip_address: (required) IP address of your C-Gate server
client_controlport: (optional, defaults to 20023) port number of the C-Gate control port
client_cbusname: (required) project name of your C-Bus network
client_network: (optional, defaults to 254) default network address for your C-Bus devices
client_application: (optional, defaults to 56) default application address for your C-Bus devices
client_debug: (optional, defaults to
false) set to
trueto write C-Bus client debug logs to the console
accessories: (required) list of accessories to expose to the Homebridge server
platform_export: (optional) path to file for exporting a unified accessory list, see below.
client_statusport are no longer required, and will be safely ignored)
You must register devices by hand in a config file, however to make this easier for you,
homebridge-cbus can automatically build most of the file for you. See Unified Accessory List, below.
The platform definition in the
config.json file contains an
accessories array, which defines the available accessories using the following keys:
type: (required) type of the accessory. The valid values are "light", "switch", "dimmer", "shutter", "motion", "security", "trigger" and "contact".
name: (required) name of the accessory (e.g. "Living Room Light", "Bedroom Light", "Living Room Curtain" etc.)
network: (optional, defaults to
client_network) C-Bus network address of the device
application: (optional, defaults to
client_application) The C-Bus Application address of the device
id: (required) C-Bus address of the device — every accessory in C-Bus has one
invert: (optional, defaults to false) only used by the shutter relay accessory and indicates that the shutter has been wired to open when commanded closed and vice versa
activeDuration: (optional) only used by the switch accessory, indicating a timeout period, after which the switch will automatically switch off. This allows a HomeKit switch accessory to be used to generate a Bell Press event.
rampDuration: (optional, maximum 17 minutes) only used by the dimmer accessory, indicating the ramp up/down time when dimming.
enabled: (optional, default: true) set to false to inhibit the accessory from loading.
action: (required by the trigger accessory) sets the action selector to be triggered.
(NB. Durations can be specified in days, hours, minutes, seconds or milliseconds. (eg.: "2 days", "2.5h", "5s", "100 ms", etc. ) For more information on allowable formats, please see the ms library)
Unified Accessory List
platform_export property is set to a valid pathname, upon startup
homebridge-cbus will export a suggested accessory list. The list will include all groups found in your C-Gate database. By default found groups are disabled, unless they are already defined as enabled in your current
It is suggested that you check this file after your first successful run of
homebridge with this plug-in loaded. You'll then be able to open the generated file and copy the entries of interest into your
homebridge-cbus has four logging channels:
cbus:platform: highest level startup/shutdown and fatal error reporting (enabled by default)
cbus:level: all level change events reported by C-Gate
cbus:client: all communication with C-Gate
cbus:db: significant events reported by the database syncing module
On startup, the status of the channels will be determined from the environment variable DEBUG. eg.:
# all C-Bus logging > DEBUG=cbus:* homebridge # just level change events > DEBUG=cbus:level homebridge # very verbose logging from all of homebridge > DEBUG=* homebridge
N.B. If provided, the
client_debug setting (from
config.json) will override the configuration for
cbus:client from the environment.
Example logging output
homebridge-cbus uses the excellent tape unit-testing framework.
To run tests:
To run tests and generate code coverage reports:
npm run test-coverage
Changes Since 0.5.0
0.6.5: adds support for
0.6.4: adds support for
- when building the Unified Accessory List, use the unitType of the C-Bus units controlled by the group to make a semi-intelligent guess of the accessory's type.
- improved support for C-Bus installations with multiple networks
0.6.0: relax tests for project name validity
0.5.9: adds support for
rampDuration(for dimmers) and remove extraneous C-Bus comms when dimming or changing fan speed
0.5.8: adds support for
- adds support for
switchaccessories including optional
- adds Unified Accessory List export
- adds support for
enabledproperty on accessories
- adds support for
0.5.6: fetch and cache a copy of the C-Gate database for improved logging
0.5.5: introduces unit testing and more robust configuration file checking
0.5.4: fixes issue where some required files were missing
0.5.3: adds support for
0.5.2: adds support for
securityaccessory, for PIR presence detectors, typically on application 208
0.5.1: adds optional
applicationparameters per accessory, allowing accessories to be monitored or controlled across multiple networks and applications.
N.B. If you are upgrading from an ealier version of
homebridge-cbus, you may need to remove the files in your
~/.homebridge/persist/ directory before running for the first time due to new device UUIDs.
- create a feature branch
- open a Pull Request
Contributions are surely welcome!