README

Omni-Link Platform

This Homebridge Plugin allows you to control a HAI/Leviton Omni series Security & Home Automation System via the Omni-Link II protocol over a TCP/IP connection.

Functions available:

Arm/disarm the security system
Notify when alarm system is triggered
Notify when sensors are tripped (7 types of sensors supported)
Notify when system has troubles (eg. AC Power)
Execute buttons
Turn units (such as switches and lights) on/off
Control thermostats
Open/close garage doors
Activate emergency alarms (burglary, fire & auxiliary)
Bypass zones
Lock/unlock doors
Notify temperature/humidity from auxiliary sensors
Control audio zones
Sync Omni controller's date & time with Homebridge host
Pushover notifications when alarms are triggered or system has troubles
MQTT client (see section "MQTT Client" for further details)

Minimum Requirements

This plugin supports Omni systems that meet the following requirements:

Connectivity via TCP/IP
Omni-Link II Protocol
Firmware 3.0 or higher

Accessories

The plugin will discover what features your system has and create HomeKit accessories for them. The following are the currently supported Omni-Link objects and the available HomeKit accessories they can map to.

Installation

Note: This plugin requires Homebridge (version 1.3.0 or above) to be installed first.

It is highly recommended that you use Homebridge Config UI X to install and configure the plugin. Alternatively you can install from the command line as follows:

npm install -g homebridge-omnilink-platform

Configuration

This is a platform plugin that will register accessories and their services with the bridge provided by Homebridge. The plugin will attempt to discover your Omni controller's objects (ie. zones, areas, buttons, etc.) automatically thus requiring minimal configuration to the config.json file.

If you find the default config is not correct for your system or not to your liking there are some overrides you can define in the config.json file.

|Option|Required|Type|Description|Default Value (if not supplied)| |-|-|-|-|-| |platform|Yes|string|Must be "OmniLinkPlatform"|| |name|Yes|string|The name of the platform|"Omni"| |address|Yes|string|IP Address of the controller|| |port|Yes|number|Port of the controller|4369| |key1|Yes|string|First part of the hexadecimal private key
Format: 00-00-00-00-00-00-00-00|| |key2|Yes|string|Second part of the hexadecimal private key
Format: 00-00-00-00-00-00-00-00|| |includeAreas|No|boolean|Include all enabled areas from the Omni controller. Each area will be added as a "Security System" accessory|true| |includeZones|No|boolean|Include all named zones from the Omni controller. Each zone will be added as a "Sensor" accessory|true| |includeBypassZones|No|boolean|Include bypass for named zones. Each zone bypass will be added as a "Switch" accessory|false| |includeButtons|No|boolean|Include all named buttons from the Omni controller. Each button will be added as a "Switch" accessory|true| |includeUnits|No|boolean|Include all named units from the Omni controller|true| |includeThermostats|No|boolean|Include all named thermostats from the Omni controller. Each thermostat will be added as a "Thermostat" accessory|true| |includeEmergencyAlarms|No|boolean|Include emergency alarms (ie. burglary, fire and auxiliary). Each alarm for each area will be added as a "Switch" accessory|true| |includeAccessControls|No|boolean|Include all named Access Controls. Each access control will be added as a "Lock Mechanism" accessory|true| |includeAuxiliarySensors|No|boolean|Include all named Auxiliary Sensors. Each auxiliary sensor will be added as either a "Temperature Sensor" or "Humidity Sensor" accessory|true| |setHomeAsAway|No|boolean|Changes the security mode to "Away" if "Home" is selected. This may be useful if you don't use the "Home" mode and want to ensure the alarm is set to "Away" if accidently set to "Home"|false| |setNightAsAway|No|boolean|Changes the security mode to "Away" if "Night" is selected. Likewise, useful if you don't use the "Night" mode|false| |securityCode|No|string|The 4 digit security code used to arm and disarm the security system. Without this the security system cannot be operated|| |includeHumidityControls|No|boolean|Include the Humidity controls in the HomeKit Thermostat accessory|false| |targetHumiditySetPointType|No|number|Selects which type of Omni set point (ie. Humidify or Dehumidify) that HomeKit's Target Humidity will map to
[1 = Humidify, 2 = Dehumidify]|1| |targetHumidityDifference|No|number|The difference between the Humidify and Dehumidify set points. This allows the plugin to set the other Omni humidity set point. 0 means do not set|0| |defaultAccessoryMappings|No|object|Defines the default zone and unit HomeKit accessory mappings.
For zone and zoneFireEmergency the defaults can be either motion, smoke, contact, carbondioxide, carbonmonoxide, leak, occupancy or none
For unit the defaults can be either switch, lightbulb or none|{"zone": "motion", "zoneFireEmergency": "smoke", "unit": "switch"}| |map|No|object|See 'Map Configuration' below|| |exclude|No|object|See 'Exclude Configuration' below|| |garageDoors|No|array|Defines 1 or more garage door accessories. Each definition requires the following properties:

buttonId - the button number correspnding to the button that opens/closes the door
zoneId - the zone number corresponding to the sensor that determines if the garage door is closed or not
openTime - the time taken (in seconds) for the garage door to fully open

Example garage door definition: { "buttonId": 2, "zoneId": 3, "openTime": 10 }|| |pushover|No|object|See 'Pushover Notification Configuration' below|| |mqtt|No|object|See 'MQTT Configuration' below|| |syncTime|No|boolean|Sync the controller's date and time with the Homebridge host|false| |showHomebridgeEvents|No|boolean|Show Homebridge events in the Homebridge log|false| |showOmniEvents|No|boolean|Show Omni notification events in the Homebridge log|false| |showRequestResponse|No|boolean|Show requests to and responses from controller in the Homebridge log|false| |clearCache|No|boolean|Clear all the plugin's cached accessories from homebridge to force re-creation of HomeKit accessories on restart
This is equivalent to deleting the cachedAccessories file|false| |forceAutoDiscovery|No|boolean|Force auto-discovery of Omni-Link devices on restart
This is equivalent to deleting the OmnilinkPlatform.json file|false|

TIP: The area, zone, button, unit and themostat numbers are displayed in the Homebridge logs when it starts up.

NOTE: Config options sensors & units may be removed in a future version of the plugin. Please migrate to the new map option ASAP.

Map Configuration

Defines how Omni zones and units are to be mapped to HomeKit accessories. This can be useful to override an accessory if the default one is not the correct type or you wish to exclude it from HomeKit.

NOTE: The lists are to be supplied as comma seperated (eg. "1,2,3")

Exclude Configuration

Defines which Omni objects (areas, zones etc) are to be excluded when creating HomeKit accessories

NOTE: The lists are to be supplied as comma seperated (eg. "1,2,3")

Pushover Notification Configuration

This plugin can be configured to send Push notifications to your phone when alarms are trigggered or the system encounters troubles. To do this you'll need a Pushover account. The following describes the configuration options available:

|Option|Required|Type|Description|Default Value (if not supplied)| |-|-|-|-|-| |token|Yes|string|Application API Token supplied by Pushover|| |users|Yes|array|One or more User Keys supplied by Pushover. Each user will receive a push notification|| |alarms|No|object|Specifies which triggered alarms will send a push notification. The following alarm types can be specified: burglary, fire, gas, auxiliary, freeze, water, duress and temperature.
Each alarm type has a value of either true or false|| |troubles|No|object|Specifies which system troubles will send a push notification. The following troubles can be specified: freeze, batterylow, acpower, phoneline, digitalcommunicator and fuse.
Each trouble has a value of either true or false||

MQTT Configuration

Option|Required|Type|Description|Default Value (if not supplied)| |-|-|-|-|-| |host|Yes|string|MQTT Broker host name|| |port|Yes|number|MQTT Broker port|1883| |username|No|string|Credentials for MQTT Broker|| |password|No|string||| |topicPrefix|No|string|Optional text to prefix to each topic name|| |showMqttEvents|No|boolean|Include MQTT events in the logs|false|

Example:

"platforms": [
  {
    "platform": "OmniLinkPlatform",
    "name": "OmniPro",
    "address": "10.0.0.200",
    "port": 4369,
    "key1": "00-00-00-00-00-00-00-00",
    "key2": "00-00-00-00-00-00-00-00",
    "includeAreas": true,
    "includeZones": true,
    "includeBypassZones": true,
    "includeButtons": true,
    "includeUnits": true,
    "includeThermostats": true,
    "includeEmergencyAlarms": true,
    "includeAccessControls": true,
    "includeAuxiliarySensors": true,
    "setHomeToAway": true,
    "setNightToAway": true,
    "securityCode": "0000",
    "defaultAccessoryMappings": {
      "zone": "motion",
      "zoneFireEmergency": "smoke",
      "unit": "switch"
    },
    "map": {
      "zones": {
        "contact": "1,2,3",
        "occupancy": "6"
      },
      "units": {
        "lightbulb": "1,3"
      }
    },
    "exclude": {
      "zones": "7,8,9",
      "units": "6,7",
      "buttons": "4"
    },
    "garageDoors": [
      {
        "buttonId": 2,
        "zoneId": 11,
        "openTime": 10
      },
      {
        "buttonId": 3,
        "zoneId": 12,
        "openTime": 10
      }
    ],
    "pushover": {
      "token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "users": [
          "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
          "cccccccccccccccccccccccccccccc"
      ],
      "alarms": {
        "burglary": true,
        "fire": true,
        "gas": false,
        "auxiliary": false,
        "freeze": false,
        "water": false,
        "duress": false,
        "temperature": false
      },
      "troubles": {
        "freeze": false,
        "batterylow": false,
        "acpower": false,
        "phoneline": true,
        "digitalcommunicator": false,
        "fuse": false
      }
    },
    "mqtt": {
      "host": "mqtt://192.168.1.111",
      "port": 1883,
      "username": "mantorok",
      "password": "password",
      "topicPrefix": "omni",
      "showMqttEvents": true
    },
    "syncTime": true,
    "showHomebridgeEvents": true,
    "showOmniEvents": true,
    "showRequestResponse": false,
    "clearCache": false,
    "forceAutoDiscovery": false
  }
],
...

Audio Zones

Each audio zone is configured as a Television accessory (shown with a speaker icon) in HomeKit. Volume controls are not supported within the Home app so you need to use the Remote app in the Control Center to do this. Here's a list of the functionaly that's possible:

Remote App (in Control Center)

How to add an Audio Zone:

Each audio zone is published as an external accessory so it needs to be added manually the first time (unlike other types of accessories that are automatically added). To do this follow these steps for each Audio Zone:

Open the Home app and tap the + button at the top left
Then select Add Accessory
Select More options... and the Audio Zones should be shown
Select one of them and tap Add Anyway
Enter your 8 digit Homebridge code and tap Continue
After a short while you will be asked a few questions such as its location, name, sources. Just tap Continue on each of these
Finally you should get to the point that the Audio Zone has been added. Tap on either Done or View in Home and you're finished

How to remove an Audio Zone:

If you no longer want to see the Audio Zone in the Home app follow these steps:

Find the accessory you want to remove in the Home app
Tap and hold the accessory tile until it opens up
Swipe up until you see the Remove Accessory button at the bottom
Tap the button and then tap Remove to confirm

Troubleshooting

After removing an Audio Zone there are some Homebridge files which may need to be manually deleted before you can re-add the accessory again. If you don't see your Audio Zone when following the 'How to add an Audio Zone' procedure above try the following:

Navigate to the persist folder in Homebridge. Here you should see a number of files named AccessoryInfo.xxxxxxxxxxxx.json (where xxxxxxxxxxxx is some hexidecimal number)
Open up each one in a text editor until you find the one that corresponds to the Audio Zone you are trying to add. You can see its name at the top after displayName. Example: {"displayName":"My Audio Zone ...
Take note of the hexidecimal number in the filename
Now delete the AccessoryInfo.xxxxxxxxxxxx.json and IdentifierCache.xxxxxxxxxxxx.json files with the hexidecimal number from the previous step
Restart Homebridge

MQTT Client

The plugin is able to operate as an MQTT client. It publishes various topics containing information about the Omni controller which other clients can subscribe to. It also subscribes to topics allowing other clients to send commands to the controller. This can be useful for interacting with external applications such as Home Assistant and Node-RED.

Published topics end with /get and subscribed topics end with /set

Area Topics

|Topic|Description|Payload| |-|-|-| |area/{number}/name/get|Gets the name of area {number}|string| |area/{number}/arm/get|Gets the armed state of area {number}|"off", "away", "night", "day" "vacation", "day_instant", "night_delayed"| |area/{number}/arm/set|Sets the armed state of area {number}
(0 = all areas)|"off", "away", "night", "day", "vacation", "day_instant", "night_delayed"| |area/{number}/burglary/get|Gets the triggered state of the burglary alarm of area {number}|"true", "false"| |area/{number}/fire/get|Gets the triggered state of the fire alarm of area {number}|"true", "false"| |area/{number}/gas/get|Gets the triggered state of the gas alarm of area {number}|"true", "false"| |area/{number}/auxiliary/get|Gets the triggered state of the auxiliary alarm of area {number}|"true", "false"| |area/{number}/freeze/get|Gets the triggered state of the freeze alarm of area {number}|"true", "false"| |area/{number}/water/get|Gets the triggered state of the water alarm of area {number}|"true", "false"| |area/{number}/duress/get|Gets the triggered state of the duress alarm of area {number}|"true", "false"| |area/{number}/temperature/get|Gets the triggered state of the temperature alarm of area {number}|"true", "false"| |area/{number}/alarm/set|Activates emergency alarm of area {number}|"burglary", "fire", "auxiliary"|

Zone Topics

|Topic|Description|Payload| |-|-|-| |zone/{number}/name/get|Gets the name of zone {number}|string| |zone/{number}/ready/get|Gets the ready state of zone {number}|"true", "false"| |zone/{number}/trouble/get|Gets the trouble state of zone {number}|"true", "false"| |zone/{number}/bypass/get|Gets the bypass state of zone {number}|"true", "false"| |zone/{number}/bypass/set|Sets the bypass state of zone {number}|"true", "false"|

Button Topics

|Topic|Description|Payload| |-|-|-| |button/{number}/name/get|Gets the name of button {number}|string| |button/{number}/execute/set|Executes button {number}|"true"|

Unit Topics

|Topic|Description|Payload| |-|-|-| |unit/{number}/name/get|Gets the name of unit {number}|string| |unit/{number}/state/get|Gets the state of unit {number}|"on", "off"| |unit/{number}/state/set|Sets the state of unit {number}|"on", "off"| |unit/{number}/brightness/get|Gets the brightness level of unit {number}|number
(see note)| |unit/{number}/brightness/set|Sets the brightness level of unit {number}|number
(see note)|

Note: Brightness level is specified as an integer between 0 and 100 inclusive

Thermostat Topics

|Topic|Description|Payload| |-|-|-| |thermostat/{number}/name/get|Gets the name of thermostat {number}|string| |thermostat/{number}/mode/get|Gets the mode of thermostat {number}|"off", "heat", "cool", "auto", "emergencyheat"| |thermostat/{number}/mode/set|Sets the mode of thermostat {number}|"off", "heat", "cool", "auto", "emergencyheat"| |thermostat/{number}/state/get|Gets the state of thermostat {number}|"idle", "heating", "cooling"| |thermostat/{number}/temperature/get|Gets the current temperature of thermostat {number}|number
(see note)| |thermostat/{number}/coolsetpoint/get|Gets the Cooling Set Point of thermostat {number}|number
(see note)| |thermostat/{number}/coolsetpoint/set|Sets the Cooling Set Point of thermostat {number}|number
(see note)| |thermostat/{number}/heatsetpoint/get|Gets the Heating Set Point of thermostat {number}|number
(see note)| |thermostat/{number}/heatsetpoint/set|Sets the Heating Set Point of thermostat {number}|number
(see note)| |thermostat/{number}/humidity/get|Gets the current humidity of thermostat {number}|number
(0 - 100)| |thermostat/{number}/humidifysetpoint/get|Gets the Humidify Set Point of thermostat {number}|number
(0 - 100)| |thermostat/{number}/humidifysetpoint/set|Sets the Humidify Set Point of thermostat {number}|number
(0 - 100)| |thermostat/{number}/dehumidifysetpoint/get|Gets the Dehumidify Set Point of thermostat {number}|number
(0 - 100)| |thermostat/{number}/dehumidifysetpoint/set|Sets the Dehumidify Set Point of thermostat {number}|number
(0 - 100)|

Note: Temperatures are specified in either Celsius or Fahrenheit depending on how your Omni controller is configured.

Access Control Topics

|Topic|Description|Payload| |-|-|-| |accesscontrol/{number}/name/get|Gets the name of access control {number}|string| |accesscontrol/{number}/locked/get|Gets the locked state of access control {number}|"true", "false"| |accesscontrol/{number}/locked/set|Sets the locked state of access control {number}|"true", "false"|

Auxiliary Sensor Topics

|Topic|Description|Payload| |-|-|-| |auxiliary/{number}/name/get|Gets the name of auxiliary sensor {number}|string| |auxiliary/{number}/temperature/get|Gets the temperature of auxiliary sensor {number}|number
(see note)| |auxiliary/{number}/humidity/get|Gets the humidity of auxiliary sensor {number}|number|