Merge pull request #432 from krkeegan/Hub_2012

Add Documentation for 2242-222 Hubs (~2012)

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Additions
 
 - As promised @lnr0626 added support for the Resume_Dim feature for non-i2cs devices. ([PR 423][P423])
+- Add instructions for using older (~2012) model 2242-222 hubs.  Thanks @tbirdsaw. ([PR 432][P432])
 
 ## [1.0.0]
 
@@ -777,3 +778,4 @@ will add new features.
 [P414]: https://github.com/TD22057/insteon-mqtt/pull/414
 [P417]: https://github.com/TD22057/insteon-mqtt/pull/417
 [P423]: https://github.com/TD22057/insteon-mqtt/pull/423
+[P432]: https://github.com/TD22057/insteon-mqtt/pull/432

config-example.yaml

@@ -49,8 +49,12 @@ insteon:
 
   # PLM Modem option (Serial or USB)
   port: '/dev/insteon'
+  # If using a 2242-222 Hub vintage ~2012 change the above line to:
+  # port: "socket://<IP Address>:9761"
+  # where <IP Address> is the address of your hub.
+  # KEEP `use_hub: False` below
 
-  # Insteon Hub option
+  # Insteon Hub 2245-222 (Modern Vintages)
   # See https://github.com/TD22057/insteon-mqtt/blob/master/docs/hub.md
   # for a discussion of the details of using a Hub as your modem.
   # If set to true, will use the Hub settings below and ignore the Serial

docs/hub.md

@@ -1,50 +1,86 @@
 # Insteon Hub as a Modem
-The following Hub model numbers are known to work, others may as well.
-- 2245-222
+The Hub can be used as a modem instead of a PLM device.  However, you
+must use either a PLM or a Hub, you cannot use both.
 
-The Hub can be used as a modem instead of a PLM device.  However, you must use
-either a PLM or a Hub, you cannot use both.
+Hubs do not have any technical benefit over a PLM. But it may save you from
+having to purchase a PLM if you already own a Hub.
 
-## Benefits
+> You can't use the features of the Hub (the Insteon Mobile app) with
+> Insteon-Mqtt.  Any changes made using the Insteon Apps
+> will not be reflected inside Insteon-Mqtt.
 
-The only real benefit to using a Hub is that it may make it easier for you to
-locate the modem more in the center of your house.  It also saves you from
-having to purchase a PLM if you already own a Hub.
+The interfaces available on Insteon Hubs have changed a bit over the years, be
+sure to check you model number and follow the instructions for your hub.
 
-## Drawbacks
+<!-- TOC -->
 
-There are no major issues with using a Hub as your modem, but there are a few
-downsides:
-- Slightly slower response because of how the Hub works approximately 1/4 of a
-second.
-- You can't use the features of the Hub (the Insteon Mobile app) with
-Insteon-Mqtt.  At least currently, any changes made using the Insteon Apps
-will not be reflected inside Insteon-Mqtt.
-- Similarly if you use any of the direct integrations with the Hub such as
-Alexa, Google Home, Logitech,... the states of your devices will not be
-properly reflected in Insteon-Mqtt.  However, if these integrations are made
-through Home Assistant, everything will work as normal.
+  - [Older Generation Hubs](#older-generation-hubs)
+    - [Configuration](#configuration)
+  - [Current Generation Hubs](#current-generation-hubs)
+    - [Configuration](#configuration-1)
+    - [Caveats](#caveats)
+    - [Notes](#notes)
+
+<!-- /TOC -->
+
+## Older Generation Hubs
+Models:
+- 2242-222 (~2012)
+
+These hubs have a port(9761) that allows for direct serial commands.
+
+### Configuration
 
-## Notes
+```yaml
+insteon:
+  port: "socket://<IP Address>:9761"
+  # where <IP Address> is the address of your hub.
+  use_hub: False
+```
 
-If you use the hub, you may notice a lot of the following warnings in your log
-file.  This is normal and they can be ignored:
+> Be sure `use_hub` is false.
 
-*WARNING Protocol: No read handler found for message type*
+## Current Generation Hubs
+Models:
+- 2245-222 (~2016)
 
-These occur because the Hub, even when not using the Insteon App, periodically
-polls the devices as well as performs other tasks.
+These hubs only have a http interface.  So all commands have to be issued over
+http.
 
-## Configuration
+### Configuration
 
 Configuring Insteon-Mqtt to use a Hub rather than the PLM is easy.  Simply
 add the following lines to your config.yaml file.  In the sample file you will
 see that they are near the top.
 
-use_hub: True
-hub_ip: <<ip address of Hub>>
-hub_user: <<username>>
-hub_password: <<password>>
+```yaml
+insteon:
+  use_hub: True
+  hub_ip: <<ip address of Hub>>
+  hub_user: <<username>>
+  hub_password: <<password>>
+```
 
 The username and password can be found on a printed label on the underside of
 your hub.  These values are unchangable.
+
+### Caveats
+
+Because modern hubs only have an http interface there are a few
+downsides:
+- Slightly slower response (approximately 1/4 of a second) because of how the
+Hub works.
+- If you use any of the direct integrations with the Hub such as
+Alexa, Google Home, Logitech,... the states of your devices will not be
+properly reflected in Insteon-Mqtt.  However, if these integrations are made
+through Home Assistant, everything will work as normal.
+
+### Notes
+
+You may notice a lot of the following warnings in your log file.  This is
+normal and they can be ignored:
+
+`WARNING Protocol: No read handler found for message type`
+
+These occur because the Insteon cloud, even when not using the Insteon App,
+periodically polls the devices as well as performs other tasks.