search

anthonywebb / homebridge-cbus

CBus plugin for homebridge
MIT License
35 stars 20 forks source link

readme

C-Bus for Homebridge

Build Status Coverage Status

HomeKit-enable your C-Bus installation with the homebridge-cbus plugin for the Homebridge server.

homebridge-cbus provides a bridge between Clipsal's C-Bus C-Gate server and Apple's HomeKit.

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:

In Action

To see some action of HomeKit controlling a Clipsal C-Bus system, check out the following videos:

Device Support

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:

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.

Installation

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 config.json.

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.

Configuration

As with other Homebridge plugins, you configure the homebridge-cbus plugin by adding it to your config.json.

  "platforms": [
    {
      "platform": "homebridge-cbus.CBus",
      "name": "CBus",
      "client_ip_address": "127.0.0.1",
      "client_controlport": 20023,
      "client_cbusname": "HOME",
      "client_network": 254,
      "client_application": 56,
      "client_debug": true,

      "platform_export": "my-platform.json",

      "accessories": [ ... ]
     }
]

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 cgate/config/access.txt.

Configuration platform fields

(NB. client_eventport and client_statusport are no longer required, and will be safely ignored)

Registering accessories

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:

(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)

Functional example config.json

{
  "bridge": {
    "name": "My Home",
    "username": "CC:22:3D:E3:CE:30",
    "port": 51826,
    "pin": "031-45-154"
  },

  "description": "My home HomeKit API configuration file",

  "platforms": [
    {
      "platform": "homebridge-cbus.CBus",
      "name": "CBus",
      "client_ip_address": "127.0.0.1",
      "client_controlport": 20023,
      "client_cbusname": "WEBB",
      "client_network": 254,
      "client_application": 56,
      "client_debug": true,

      "platform_export": "my-platform.json",

      "accessories": [
        { "type": "light", "id": 0, "name": "Flood" },
        { "type": "light", "id": 1, "name": "Main Bay" },
        { "type": "light", "id": 2, "name": "3rd Bay" },
        { "type": "light", "network": "250", "id": 1, "name": "Outside Light" },
        { "type": "light", "network": "250", "application": "203", "id": 3, "name": "Backdoor" },

        { "type": "dimmer", "id": 3, "name": "Closet" },

        { "type": "dimmer", "id": 22, "name": "Wake Up Lights", "rampDuration": "10 min"},      

        { "type": "shutter", "id": 145, "name": "Living Blinds" },
        { "type": "shutter", "id": 142, "name": "Dining Blinds", "invert": "true"},

        { "type": "fan", "id": 7, "name": "Kitchen Fan"},

        { "type": "motion", "id": 51, "name": "Main" },

        { "type": "security", "application": 208, "id": 1, "name": "Entry Zone" },

        { "type": "switch", "id": "9", "name": "Garden Lights", "activeDuration": "2.5 hrs" },

        { "type": "trigger", "application": 202, "id": 0, "action": 1, "name": "recall preset 2" },

        { "type": "temperature", "id": 245, "application": 228, "channel": 1, "name": "Living Room Temperature" },

    { "type": "contact","id": 5, "name": "Bedroom Window" },

    { "type": "smoke","id": 3, "name": "Kitchen Smoke Detector" }
      ]
    }
  ],
  "accessories": [ ]
}

Unified Accessory List

If the 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 config.json file.

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 config.json file.

Logging

homebridge-cbus has four logging channels:

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

Unit testing

homebridge-cbus uses the excellent tape unit-testing framework.

To run tests:

npm test

To run tests and generate code coverage reports:

npm run test-coverage

Changes Since 0.5.0

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.

Contributions

Contributions are surely welcome!