homebridge-smartthings-v2

About

V2 of this plugin is a complete rewrite of the homebridge-smartthings-tonesto7 plugin using modern Javascript structure using classes, promises, arrow functions.

Latest SmartApp Version: 2.0.3

What's New for 2.x.x:

Plugin

• Completely rewrote the entire plugin using modern javascript structure.
• The code is now much cleaner, easier to update/maintain, and easier for others to follow.
• This translates into a faster/leaner and way more stable plugin than previous versions.
• The plugin now uses the Homebridge Dynamic platform API, meaning it no longer requires a restart of the Homebridge service for device changes to occur.
• The plugin now utilizes the device cache on service restart to prevent losing all of your devices when the plugin fails to start for an extended period of time.
• It will now remove devices no longer selected under SmartThings.
• Introduced an all-new logging system to provide more insight into issues and status, as well as write them to a file.
• I used all of the issues from my existing plugin to repair this new version.
• Many, many other bug fixes for devices, commands and many other items.
• Important NOTICE: Due to the changes in the plugin API you can not directly update the plugin, you will need to add as a new accessory and setup your devices/automations/scenes again. On a positive note, you can use the same SmartApp instance though as long as you update to the latest code.

SmartApp

• Reworked and cleaned up the UI so it's now more organized and easier to follow.
• Added new capability filter options.
• Optimized the command/event streaming system to perform faster and more reliably.
• Added duplicate device detection cleanups so Homekit doesn't try to create duplicate devices and throw an error.
• Many, many other bug fixes and cleanups.

Credits

Big thanks for @Areson for his help/motivation in rewriting this.

I also wanted to mention the following projects I referenced for inspiration for design and fixes:

• homebridge-wink3
• homebridge-hubconnect-hubitat

Change Log:

SmartThing App:

• See CHANGELOG

Homebridge Plugin:

• See CHANGELOG

Direct Updates from SmartThings

• This method is nearly instant.
• This option allows the hub to send updates directly to your homebridge-smartthings installation.
• The hub must be able to send an http packet to your device so make sure to allow incoming traffic on the applicable port.
• The port used for this can be configured by the "direct_port" setting and defaults to 8000.
• The program will attempt to determine your IP address automatically, but that can be overridden by "direct_ip" which is useful if you have multiple addresses.
• As a note, the hub isn't actual doing any of the processing so if you lose Internet, updates will stop. I'm told it "doesn't currently" support it, so there is hope.

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

[11/25/2019, 4:44:46 PM] [SmartThings-v2] Devices to Remove: (0) []
[11/25/2019, 4:44:46 PM] [SmartThings-v2] Devices to Update: (40)
[11/25/2019, 4:44:46 PM] [SmartThings-v2] Devices to Create: (0) []
[11/25/2019, 4:44:46 PM] [SmartThings-v2] Total Initialization Time: (2 seconds)
[11/25/2019, 4:44:46 PM] [SmartThings-v2] Unknown Capabilities: ["Power Source"]
[11/25/2019, 4:44:46 PM] [SmartThings-v2] SmartThings DeviceCache Size: (40)
[11/25/2019, 4:44:46 PM] [SmartThings-v2] WebServer Initiated...
[11/25/2019, 4:44:46 PM] [SmartThings-v2] Sending StartDirect Request to SmartThings | SendToLocalHub: (false)
[11/25/2019, 4:44:46 PM] [SmartThings-v2] Direct Connect is Listening On 10.0.0.163:8000

Installation

Installation comes in two parts:

1. SmartApp Installation

Option 1: Automated Install

Install using my SmartThings Community Installer

Option 2: GitHub Integration or Manual Install

Note New SmartThings users: You must first enable github integration. (If you use github for work you will probably want to set up a new account as it will request access to your private repos). Only after enabling integration will you see the settings button. Non-US users can set it up here.

Note to users updating from homebridge-smartthings-tonesto7: You can continue to use the original Homebridge-SmartThings app if you choose, but to keep it aligned with any changes made to the homebridge-smartthings-v2 plugin you should consider migrating the app to point to homebridge-smartthings-v2 repository instead of homebridge-smartthings-tonesto7 or homebridge-smartthings.

• Log into your SmartThings account at SmartThings IDE

• Click on My SmartApps

• Click on Settings and Add the New repository:

  • Owner: tonesto7
  • Name: homebridge-smartthings-v2
  • Branch: master
  • Click Save.

• Click Update From Repo

  • Select homebridge-smartthings-v2

• You should have homebridge-v2.groovy in the New section.

  • Check the Box next to homebridge-v2.groovy
  • Check Publish at the bottom
  • Click Execute Update.

• Click on the homebridge-v2 app in the list:

  • Click App Settings
  • Scroll down to the OAuth section and click Enable OAuth in Smartapp
  • Click Update at the bottom.

2. SmartApp Configuration

• In the SmartThings Classic Mobile App, goto Marketplace and select SmartApps.

• At the bottom of the list, select My Apps

• Select Homebridge v2 from the choices on thelist.

• Configuring the App:

  There are 4 inputs at the top that can be used to force a device to be discovered as a specific type in HomeKit

  Any other devices being added just Tap on the input next to an appropriate device group and then select each device you would like to use (The same devices can be in any of the Sensor, Switch, Other inputs)

  • There are several categories because of the way SmartThings assigns capabilities. So you might not see your device in one, but might in another.
  • Almost all devices contain the Refresh capability and are under the "Other Devices" group
  • Some sensors don't have a refresh and are under the "Sensor Devices" group.
  • Some devices, mainly Virtual Switches, only have the Switch Capability and are in the "Switch Devices".

  Selecting the same device in multiple categories it will only be shown once in HomeKit, so you can safely check them all in all groups

• Tap Done

• Tap Done You are finished with the App configuration!

3. Homebridge Plugin Installation:

NOTICE: I highly recommend installing the plugin homebridge-config-ui-x to manage your homebridge instance and configs. This will allow you to use the web based form to configure this plugin.

1. Install homebridge using: npm i -g homebridge (For Homebridge Install: Homebridge Instructions)
2. Install SmartThings plugin using: npm i -g homebridge-smartthings-v2
3. Update your configuration file. See sample config.json snippet below.

Config.json Settings Example

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

      "platform": "SmartThings-v2",
      "name": "SmartThings-v2",
      "app_url": "https://graph.api.smartthings.com:443/api/smartapps/installations/",
      "app_id": "ffc2dd6e-6fa5-48a9-b274-35c4185ed9ac",
      "access_token": "1888d2bc-7792-1114-9f32-e4724e388a26",
      "direct": true,
      "direct_port": 8000,
      "excluded_capabilities": {
         "SMARTTHINGS-DEVICE-ID-1": [
            "Switch",
            "Temperature Measurement"
         ]
      },
      "logConfig": {
         "debug": false,
         "showChanges": true,
         "hideTimestamp": false,
         "hideNamePrefix": false,
         "file": {
            "enabled": true,
            "level": "good"
         }
      }

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

• app_url & app_id & access_token Required
  To get this information, open Homebridge (SmartThings) SmartApp in your SmartThings Classic Mobile App, and tap on "View Configuration Data for Homebridge"
  Notice: The app_url in the example will be different for you.

• direct_ip Optional | Default: `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 SmartThings for the hub to send to.

• direct_port Optional | Default: `8000`
  This is the port that homebridge-smartthings 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.

• local_commands Optional | Default: `false`
  This will allow the service to send homekit commands to hub locally, this is also available under the SmartApp settings.

• temperature_unit Optional | Default: `F`
  This will allow you to define the temp unit to use. This can also be set in the SmartApp

• excluded_capabilities Optional | Default: `{}` (None)
  NOTICE: The smartapp offers many inputs to help filter out device capabilities. Only use this if the available inputs don't meet your needs. Specify the SmartThings device by ID and the associated capabilities you want the plugin to ignore
  This prevents a SmartThings device creating unwanted or redundant HomeKit accessories.

• logConfig Optional
  Define log output format options as well as enable the log file output

  • debug Optional | Default: false
    Enables Debug log output

  • showChanges Optional | Default: true
    Logs device event changes received from SmartThings

  • hideTimestamp Optional | Default: false
    Hides timestamp prefix from console log output

  • hideNamePrefix Optional | Default: false
    Hides pluglin name prefix [SmartThings-v2] from console log output

  • file Optional
    Enable log file output and configure options

    • enabled Optional | Default: false
      Activates logging to file (homebridge-smartthings-v2.log) stored in the same folder as the homebridge config.json

    • level Optional | Default: good
      Defines the log entry levels that are written to the file. good(recommended) is the default which will write all necessary entries.

Frequently Asked Question:

Q: Can this support Samsung Washer, Dryers, Window AC, Robot Vacuum's
A: Not in the way you hoped. There are no characteristics in Homekit to allow it beyond simple On/Off Switches

Q: Can this support Axis Blinds
A: Maybe, I can support any device that has windowShade capability and/or level attributes

Known Issues:

• When you change capability filters on a device already created under homekit it will not remove the old capabilities from the device (I'm working on this)

DONATIONS:

PayPal Donations Link