homebridge-hubitat-makerapi

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

Current App version: 0.5.00

Table of Contents

Change Log
Installation
Configuration File Parameters
Capability Filtering
Attribute Filtering
Troubleshooting

Change Log

Hubitat App:

v0.1.0 - Ported app over from my tonesto7 version and added Websocket channel. Reworked Device Classification, HSM and modes currently not supported!!!
v0.1.2 - Fixed bug of not updating tiles in HomeKit after an hour expired
v0.1.7 - Fixed issuse with Siri, Show version number in logging output
v0.1.8 - Fixed issue with setting Thermostat temperature, make a device a Fan if it has the attributes switch and level and the device type contains the words "fan control"
v0.1.9 - Added ability to filter out attributes and capabilities
v0.1.10 - Fixed Hampton Bay Fan Component
v0.1.11 - v0.1.17 - Several attempts to mess with messy fans...
v0.2.0 - migrated to dynamic homebridge platform that removes the need of restarting homebridge after a device selection was changed in MakerAPI, configure homebridge to use Celsius, fixed fan tile on/off functionallity, ability to create switch tiles for modes and switching of modes, HSM integration, reduced load on Hubitat at plugin start by removing dependency on full detail API call, plugin startup speed improved, perform daily version check against NPMJS and print logging statement on newer versions available
v0.2.1 - v0.2.4 - Fixed attribute filtering for cached devices
v0.2.5 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-hubconnect plugin to allow faster cross-sharing of improvements
v0.2.6 Fixed issue with multi sensors not updating temperature and humidity, fixed issue that temperature can't go negative
v0.2.7 - v.0.2.8 problems with deasync module, removed it
v0.2.9 fixed on/off for hampton bay controller, fixed water valve
v0.2.10 Hampton Bay Fan Controllers say they have speed level even though they are off, let's fix that
v0.2.11 Added some debug for fans....
v0.2.13 Fixed garage door implementation and set obstruction when status is unknown/stopped
v0.2.14 Added "debug" mode to see calls to MakerAPI in output. See description below on how to enable it.
v0.2.15 Added ability to write logging to file
v0.2.16 Fixed rounding issue for thermostats in auto mode
v0.2.17 Added support for colorTemperature bulbs
v0.2.18 Added thermostat fan switch support (thanks @swiss6th), added ping/pong for websockets (thanks @asj)
v0.2.19 Added some additional testing on websocket status to track down an issue...
v0.3.0 Added Button support, limited to "push" for 1 button, see "programmable_buttons" for advanced programmable button support (thanks to @swiss6th for the code base)
v0.3.1 fixed double usage of switch if a button also has the switch attribute
v0.3.2 Another try to deal with websocket issues
v0.3.3 Fixed programmed buttons implementation, further testing on websocket connection, reloading of attribute states via HTTP if websocket connection is "broken", some refactoring
v0.4.0 Adapted to new MakerAPI event-stream released with Hubitat release 2.1.6, websocket connection is used as fallback if MakerAPI stream is not supported, new configuration options for "local_ip" and "local_port" added, clean reload after lost communication with hub
v0.4.1 Fixed an issue during start and concurrent requests to MakerAPI
v0.4.2 Added automatic detection of free port to listen on for event stream
v0.4.5 Added diagnostic website hosted by plugin to see/download log files and enable debug logging
v0.4.6 Fixed thermostat low battery warnings, fixed iOS13 duplicate calling of setThermostatOperationgMode, some UI changes in diagnostic website
v0.4.7 Fixed null attribute on battery for thermostats
v0.4.8 Fixed setting Thermostat temperatures in auto mode, fixed Alarm Tile in Home App when HSM is disarmed with 'Disarm All' by RM, better detection of local_ip based on app_url host
v0.4.9 Fixed Alarm Tile reset when custom rule alert was canceled
v0.4.10 Fixed thermostat setpoint in auto mode for Thermostats
v0.4.11 Fixed exception on button events
v0.4.12 Validation of values for accessoires to prevent warning messages in Homebridge 1.3
v0.4.13 Fixed null reference for validation of values
v0.4.14 Fix for newer output on MakerAPI with version 2.2.6
v0.4.15 Fixed error on Hubitat reboot
v0.5.00 applied Homebridge v2.0 changes

Explanation:

Direct Updates

This method is nearly instant.

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

[2019-4-12 14:22:51] [Hubitat] homebridge-hubitat-makerapi server listening on 20009
[2019-4-12 14:22:51] Homebridge is running on port 51826.

Installation

1. Hubitat MakerAPI App Configuration

• Under the Hubitat Web Interface, Click on Apps in the left side menu.
• Click on the button +Add Built-In App
• Select Maker API from the list of apps
• Enable Allow Access via Local IP Address
• Tap Done and you are finished with the App configuration.
• Go into the newly added Maker API app
• Select the devices you would like to have available via HomeKit
• Enable Include Location Events to support HSM and chaning of modes

2. 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-makerapi
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. There is also a tool to help you creating a config.json file located here

{
   "platform": "Hubitat-MakerAPI",
   "name": "Hubitat",
   "app_url": "http://192.168.10.169/apps/api/YOUR_APPS_ID/",
   "access_token": "THIS-SHOULD-BE-YOUR-TOKEN",
   "local_ip": "10.0.0.70",
   "local_port": 20010,
   "polling_seconds": 300,
   "temperature_unit": "F",
   "mode_switches": true,
   "hsm": true,   
   "debug": false,
   "programmable_buttons": [
        "97",
        "98"
   ],
   "excluded_capabilities": {
       "HUBITAT-DEVICE-ID-1": [
          "Switch",
          "TemperatureMeasurement"
       ]
   },
   "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 & access_token Required
  This is the base URL and access token for MakerAPI, check step 1 of the installation instructions on how to obtain the value Notice: The app_url in the example above may be different for you.

• 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 20010
  This is the port that homebridge-hubitat-makerapi plugin will listen on for events from your hub. Make sure your firewall allows incoming traffic on this port from your hub's IP address.

• polling_seconds Optional
  Configures the how often (in seconds) the plugin should check if devices were removed or added from/to the selection in MakerAPI. Default is every 300 seconds. Almost no need to restart homebridge anymore! Name changes and changing a device driver still requires a restart.

• excluded_capabilities Optional
  Defaults to None
  Specify the Hubitat device by ID and the associated capabilities you want the plugin to ignore
  This prevents a Hubitat device from creating unwanted or redundant HomeKit accessories

• 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

Capability Filtering

The homebridge-hubitat-makerapi creates Homekit devices based on the attributes of devices. See Attribute Filtering below. To allow backwards compatibilty to tonesto7's plugin, the homebridge-hubitat-makerapi plugin still allows filtering by capability. Capabilities are going to be matched to Hubitat's listed capabilities at Driver Capability List and the associated attributes are going to be removed.

Attribute Filtering

The homebridge-hubitat-makerapi 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-makerapi 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.4.5 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. In Hubitat, go open your MakerAPI Instance
2. Scroll down to find your "URL to send device events to by POST"
3. Copy the URL and enter the URL in a new browser window
4. 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