Homebridge Domapic Plugin

Domapic Plugin that automatically register Domapic abilities as Apple's HomeKit accessories (using the awesome Homebridge)

Intro

The Homebridge Domapic Plugin retrieves the information about modules and abilities registered in your Domapic Controller, and automatically configures and starts an underlay Homebridge server that will act as a bridge between Apple's HomeKit and the Domapic abilities.

Since Siri supports devices added through HomeKit, this means that with this plugin you can ask Siri to control your own-made Domapic modules:

• "Siri, turn on the living room light"
• "Siri, open the garage door"
• "Siri, activate my awesome webhook"

Prerequisites

Domapic Controller has to be installed and running in your LAN.
At least one Domapic module, such as relay-domapic-module has to be installed and connected to the Controller.
Also read the system requisites of Homebridge, which is used underlay to connect with HomeKit.

Installation

npm i homebridge-domapic-plugin -g --unsafe-perm

Start the plugin

Start the plugin providing the Controller url and connection token:

domapic-homebridge start --controller=http://192.168.1.100:3000 --controllerApiKey=foo-api-key

The plugin will be started in background using pm2

To display logs, type:

domapic-homebridge logs --lines=200

Once the Plugin has connected with the Controller, the Homebridge server will be started, and a QR code will be displayed in logs:

Scan this code with your HomeKit app on your iOS device to add your accessories.

From now, all modules added to your Controller will automatically be added to your HomeKit app too, and will be available through Siri.

Options

The plugin, apart of all common domapic services options, provides custom options for configuring it:

• homebridgePort - Number defining the port that Homebridge server will use.

domapic-homebridge start --homebridgePort=3200

Configuring modules

This plugin requires some extra configuration in modules in order to match the module abilities with the correspondant HomeKit accessory characteristics.

This configuration can be found in the Domapic Controller, as "servicePluginConfigs" entities. Modules can define a default configuration for this plugin using the addPluginConfig method. (Read the domapic-service documentation for further info)

Certain types of abilities are registered as accessories automatically if no plugin configuration is found for the module:
- Abilities that have "boolean" data type and have both state and action are being exposed as HomeKit Switch accessories.
- Abilities without data type that have an action defined are being exposed as HomeKit Switch accessories, but returning always false as state.

Here is an example of an hypothetical module configuration:

{
  "pluginPackageName": "homebridge-domapic-plugin", // DEFINE PLUGIN CONFIGURATION FOR THIS MODULE
  "config": {
    "accessories": [ // HomeKit Accessories for this module
      {
        "accessory": "Switch", // HomeKit Accessory name
        "characteristics": [
          {
            "characteristic": "On", // HomeKit Characteristic
            "get": {
              "ability": "switch" // Module ability state to use when Homekit calls to "read" Characteristic
            },
            "set": {
              "ability": "switch" // Module ability action to use when Homekit calls to "write" Characteristic
            },
            "notify": {
              "ability": "switch" // Module ability event that will change accessory value, and trigger notifications
            }
          }
        ]
      },
      {
        "accessory": "ContactSensor", // HomeKit Accessory name
        "characteristics": [
          {
            "characteristic": "ContactSensorState", // HomeKit Characteristic
            "get": {
              "fixture": true // When Homekit calls to "read" Characteristic will always return true.
            }
          }
        ]
      }
    ]
  }
}

Some points to take into account when defining configuration are:

• Data type that a module ability handles has to be equivalent to the data type that the correspondant HomeKit Characteristic expects.
• You can use the fixture property when a required Characteristic is not available in your module. (In this way, an ability with only an action and no state (a "button" behavior, for example), can be mapped into a "Switch" accessory, as seen in the example above)
• A Domapic module can be mapped into one or many Homekit accessories, as seen in the example above.
• Configuration can be modified by Domapic administrators in the Domapic Controller. The configuration defined programatically from module through the addPluginConfig method will define only the default configuration.
• Read the HAP-NodeJs documentation to check all available HomeKit Accessories and required Characteristics for each of them, as well as expected data type for each Characteristic. Supported Accessories by this plugin are listed below.

Supported HomeKit Accessories

Here is the list of currently supported HomeKit Accessories, and its related Characteristics:

• Switch
  • On - <boolean> data type.
• ContactSensor
  • ContactSensorState - <boolean> data type.
• TemperatureSensor
  • CurrentTemperature - <number> data type.
• HumiditySensor
  • CurrentRelativeHumidity - <number> data type.

Accessories support will increase on next versions of this plugin.