/homebridge-hubitat-hubconnect

Primary LanguageJavaScriptApache License 2.0Apache-2.0

homebridge-hubitat-hubconnect

This is based off of @tonesto7 homebridge-hubitat-tonesto7

npm version

Current App version: 0.3.12

Table of Contents

Change Log
Installation
Configuration File Parameters
Attribute Filtering
Troubleshooting

Change Log:

Homebridge Plugin:

v0.1.0 - Reworked alot of the code to allow for communication with Hubitat HubConnect
v0.1.4 - Support of HSM if enabled, Attribute filtering for devices is possible
Fixed bug of not updating tiles in HomeKit after an hour expired
Fixed issuse with Siri, Show version number in logging output
Fixed issue with setting Thermostat temperature
configure homebridge to use Celsius
v0.1.5 - Fixed issue when a single device is assigned to several groups
v0.2.0 - migrated to dynamic homebridge platform that removes the need of restarting homebridge after a device selection was changed in HubConnect, configure homebridge to use Celsius, fixed fan tile on/off functionallity, ability to create switch tiles for modes and switching of modes, HSM integration, perform daily version check against NPMJS and print logging statement on newer versions available, streamline code to share improvements with homebridge-hubitat-makerapi, ability to exclude attributes,allows correct usage of DNS host names instead of IP address to connect to hubitat, fans that support setLevel use setLevel instead of setSpeed to allow finer granularity, code baselined with homebridge-hubitat-makerapi plugin to allow faster cross-sharing of improvements,Fixed issue with multi sensors not updating temperature and humidity, fixed issue that temperature can't go negative
v0.2.4 - changed parameter list for remote commands to hubConnect, fixed water valves
v0.2.5 - fixed on/off for fan controllers with setLevel support
v0.2.6 - fixed issues with setting HSM and modes from Homekit and receiving an update response to it
v0.2.7 - always listen to event socket to receive mode updates
v0.2.8 - Hampton Bay Fan Controllers say they have speed level even though they are off, let's fix that, fixed on/off for hampton bay controller, fixed water valve
v0.2.9 Added some debug for fans....,Fixed garage door implementation and set obstruction when status is unknown/stopped,Added "debug" mode to see calls to MakerAPI in output. See description below on how to enable it, Added ability to write logging to file
v0.2.10 Fixed rounding issue with thermostats in auto mode
v0.2.11 Added thermostat fan switch support (thanks @swiss6th), added ping/pong for websockets (thanks @asj)
v0.3.5 Device updates retrieved via websocket, Added thermostat fan switch support, Added support for colorTemperature bulbs, Fixed thermostat low battery warnings, fixed iOS13 duplicate calling of setThermostatOperationgMode, Added Button support, limited to "push" for 1 button, see "programmable_buttons" for advanced programmable button support (thanks to @swiss6th for the code base), Added automatic detection of free port, Added diagnostic website hosted by plugin to see/download log files and enable debug logging, implemented new support interface for HubConnect 1.5
v0.3.6 Fixed reset of alarm tile when custom HSM rule alert was cancelled
v0.3.7 Escape mode names with special characters in set command
v0.3.8 Removed trailing / from url reported to HubConnect
v0.3.9 Fixed button push exceptions
v0.3.11 Fixed tsVersion report
v0.3.12 Validation of values for accessoires to prevent warning messages in Homebridge 1.3

Explanation:

Direct Updates

This method is nearly instant. This option allows the hub to send updates directly to your homebridge-hubitat-hubconnect installation. The hub must be setup as a HubConnect Server and a Remote Client has to be added. See here: (https://community.hubitat.com/t/release-hubconnect-share-devices-across-multiple-hubs-even-smartthings) The port used for this can be configured by the "local_port" setting and defaults to 20009. The program will attempt to determine your IP address automatically, but that can be overridden by "local_ip" which is useful if you have multiple addresses.

When properly setup, you should see something like this in your Homebridge startup immediately after the PIN:

[2019-4-12 12:46:45] Homebridge is running on port 51826.
[2019-4-12 12:46:45] [Hubitat Dev] homebridge-hubitat-hubconnect server listening on 20009

Installation:

Installation comes in two parts:

1. HubConnect Installation

3. Homebridge Plugin Installation:

  1. Install homebridge using: sudo npm i -g homebridge (For Homebridge Install: Homebridge Instructions)
  2. Install Hubitat plugin using: sudo npm i -g homebridge-hubitat-hubconnect
  3. Create your config.json configuration file. The config.json file has to be stored in the folder ~/.homebridge
  4. To help creating your inital configuration file, click here for some assistance.
  5. Start homebridge using the command: homebridge

Configuration File Parameters

Example of all settings. Not all settings are required. Read the breakdown below

{
   "platform": "Hubitat-HubConnect",
   "name": "Hubitat",
   "hubconnect_key": "THIS-SHOULD-BE-YOUR-CONNECTION-KEY",
   "local_ip": "10.0.0.70",
   "local_port": 20009,
   "temperature_unit": "F",
   "mode_switches": true,
   "hsm": true,   
   "debug": false,
   "programmable_buttons": [
        "97",
        "98"
   ],
   "excluded_attributes": {
       "HUBITAT-DEVICE-ID-1": [
          "power",
          "humidity"
       ]
   },
   "logFile": {
         "enabled": true,
         "path": "",
         "file": "",
         "compress": true,
         "keep": 5,
         "size": "10m"
   }
}

  • platform & name Required
    This information is used by homebridge to identify the plugin and should be the settings above.

  • app_url & hubconnect_key Required
    This is the HubConnect Connection Key to allow to retrieve the connection paramters to the HubConnect App.

  • local_ip Optional
    Defaults to first available IP on your computer
    Most installations won't need this, but if for any reason it can't identify your ip address correctly, use this setting to force the IP presented to Hubitat for the hub to send to.

  • local_port Optional
    Defaults to 20009
    This is the port that homebridge-hubitat-hubconnect plugin will listen on for traffic from your hub. Make sure your firewall allows incoming traffic on this port from your hub's IP address.

  • excluded_attributes Optional
    Defaults to None
    Specify the Hubitat device by ID and the associated attributes you want homebridge-hubitat-makerapi to ignore. This prevents a Hubitat device from creating unwanted or redundant HomeKit accessories

  • programmable_buttons Optional
    Defaults to None
    By default, pressing Buttons in Homekit trigger a "pushed" event for button number 1 in Hubitat. The setting "programmable_buttons" allows Hubitat to trigger HomeKit specific scenes. You can assign scenes to three types of events: Pushed, Held and DoubleTapped. This can be helpful to interact with Homekit only devices. E.g. a button press in HE can trigger a HomeKit only lock to lock. Note: there is no feedback if the Homekit scene was executed successfully or not. Specify the Hubitat device by ID in this setting to create a programmable button.

  • temperature_unit Optional
    Default to F
    Ability to configure between Celsius and Fahrenheit. Possible values: "F" or "C"

  • mode_switches Optional
    Default to false
    Create switches for modes and ability to switch modes by enabling such switches Possible values: true or false
    Requires HE fimrware 2.0.9 or newer

  • hsm Optional
    Default to false
    Integrates HSM into Home app and allow to arm/disarm the hsm and receive notifications on intrusions
    Requires HE firmware 2.0.9 or newer

  • debug Optional
    Default to false
    Enables debugging of HTTP calls to MakerAPI to troubleshoot issues

  • logFile Optional
    Settings to enable logging to file. Uses winston logging facility

    • enabled Optional
      Enable logging to file. Default is true. Set to true to enable file logging

    • path Optional
      Path to store log files. Defaults to path where config.json is stored - Only applicable if logFile -> enable is set to true

    • file Optional
      Filename of log file. Default is homebridge-hubitat.log - Only applicable if logFile -> enable is set to true

    • compress Optional
      Compress log files when they rotate. Default is true - Only applicable if logFile -> enable is set to true

    • keep Optional
      Number of log files to keep before deleting old log files. Default is 5 - Only applicable if logFile -> enable is set to true

    • size Optional
      Maximum size of log file. Default is 10m - Only applicable if logFile -> enable is set to true

Attribute Filtering

The homebridge-hubitat-hubconnect creates Homekit devices based on the attributes of devices. The following attributes are currently being handled:

Attribute HomeKit Devices
thermostatOperatingState Thermostat
switch and (level or hue or saturation) Light Bulb
switch Switch
motion Motion Sensor
presence Occupancy Sensor
lock Lock Mechanism
temperature (and not a thermostat) Temperature Sensor
contact Contact Sensor
door Garage Door Opener
smoke Smoke Sensor
carbonMonoxide Carbon Monoxide Sensor
carbonDioxideMeasurement Carbon Dioxide Sensor
water Leak Sensor
humidity Humidity Sensor
illuminance Light Sensor
battery Battery Service
position Window Covering
speed Fan Controller
valve Valve

The homebridge-hubitat-hubconnect plugin does not discriminate! The plugin will create multiple devices in Homekit if a device has multiple of these attributes. Let's take a window shade as an example. A window shade might have the attributes "switch" and "position" and would create two Homekit devices, one as a switch and one as window covering. This might not be the desired behavior and you might want to only have one Homekit devices that sets the position of the shade. The plugin allows you to filter out the "switch" attribute and won't create a Homekit device for that attribute. To do so, you would add the following configuration to your config.json:


   "excluded_attributes": {
       "HUBITAT-DEVICE-ID": [
          "switch"
       ]
   }

Troubleshooting

With version v0.3.0 a plugin dashboard is available to help troubeshooting. The dashboard is a website that can be reached while homebridge and the plugin are running. To reach the dashboard, you can follow these steps:

  1. Open a browser and go to the URL http://[IF-OF-HOMEBRIDGE-SERVER]:[LOCAL-PORT-OF-THIS-PLUGIN]/
  2. You will see a view like this, showing you the logging output of the plugin, the ability to download the log-file to your computer, enablign, disabling debug mode and see your current configuration alt text