From 7d05122aa55cc8adde42e84e04ad502d95d8e9dc Mon Sep 17 00:00:00 2001 From: Tom Harris Date: Mon, 10 Sep 2018 13:23:36 -0400 Subject: [PATCH] Support for Insteon Hub Version 1 (#6211) * Support for Insteon Hub Version 1 * Spelling and gramar fixes * :pencil2: Tweaks --- .gitignore | 1 + source/_components/insteon.markdown | 98 +++++++++++++++++------------ 2 files changed, 60 insertions(+), 39 deletions(-) diff --git a/.gitignore b/.gitignore index f02128325f5..933ece07209 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ source/.jekyll-metadata /.vs/slnx.sqlite-journal /.vs/VSWorkspaceState.json .vscode +*.suo diff --git a/source/_components/insteon.markdown b/source/_components/insteon.markdown index e2518a09784..7cb8e635ec7 100644 --- a/source/_components/insteon.markdown +++ b/source/_components/insteon.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon" -description: "Instructions on how to setup an Insteon Modem (PLM or Hub) locally within Home Assistant." +description: "Instructions on how to set up an Insteon Modem (PLM or Hub) locally within Home Assistant." date: 2018-08-20 16:00 sidebar: true comments: false @@ -18,19 +18,20 @@ linked INSTEON devices to be used within Home Assistant as binary sensors, lights, fans, sensors and switches. Device support is provided by the underlying [insteonplm] package. It is known to work with the [2413U] USB and [2412S] RS242 flavors of PLM and the [2448A7] USB stick. It has also been -tested to work with the [2245] Hub. +tested to work with the [2242] and [2245] Hubs. [insteonplm]: https://github.com/nugget/python-insteonplm [2413U]: https://www.insteon.com/powerlinc-modem-usb [2412S]: https://www.insteon.com/powerlinc-modem-serial [2448A7]: https://www.smarthome.com/insteon-2448a7-portable-usb-adapter.html [2245]: https://www.insteon.com/insteon-hub/ +[2242]: https://www.insteon.com/support-knowledgebase/2014/9/26/insteon-hub-owners-manual ### {% linkable_title INSTEON Modem configuration %} -To setup a Powerline Modem (PLM) device such as the [2413U], use the following -configuration: +To set up an INSTEON Powerline Modem (PLM) device such as the [2413U], use the +following configuration: ```yaml # PLM configuration variables @@ -38,15 +39,26 @@ insteon: port: SERIAL_PORT ``` -To setup an INSTEON Hub such as the [2245], use the following configuration: - +To set up an INSTEON Hub model [2245], use the following configuration: + ```yaml -# Hub configuration variables +# Hub 2245 configuration variables insteon: host: HOST ip_port: IP_PORT username: USERNAME password: PASSWORD + hub_version: 2 +``` + +To set up an INSTEON Hub model [2242], use the following configuration: + +```yaml +# Hub 2242 configuration variables +insteon: + host: HOST + ip_port: IP_PORT + hub_version: 1 ``` Addtional configuration items are available: @@ -71,14 +83,23 @@ insteon: ``` Configuration variables: - **port** (*Required for PLM setup*): The serial or USB port for your device, - e.g., `/dev/ttyUSB0` -- **host** (*Required for Hub setup*): The host name or IP address of the Hub -- **ip_port** (*Optional for Hub setup*): The IP port number of the Hub. - (default value is 25105) -- **username** (*Required for Hub setup*): The username to login to the local - Hub -- **password** (*Required for Hub setup*): The password to login to the local - Hub + e.g., `/dev/ttyUSB0` or `COM3` +- **host** (*Required for Hub setup*): The host name or IP address of the Hub. +- **ip_port** (*Optional for Hub setup*): The IP port number of the Hub. For + Hub model [2245] (i.e. Hub version 2) the default port is 25105. For the Hub + model [2242] (i.e. Hub version 1) the default port is 9761. Use the Insteon + app to find the port number for your specific Hub. +- **username** (*Required for Hub version 2 setup*): The username to login in + to the local Hub. This is required for Hub [2245] (i.e. Hub version 2) setup. + You can find your Hub username on the bottom of the Hub or you can use the + Insteon app. +- **password** (*Required for Hub version 2 setup*): The password to login in + to the local Hub. This is required for Hub [2245] (i.e. Hub version 2) setup. + You can find your Hub password on the bottom of the Hub or you can use the + Insteon app. +- **hub_version** (*Required for Hub version 1 setup*): The Hub version number + where model [2242] is Hub version 1 and model [2245] is Hub version 2. + (Default is 2) - **device_override** (*Optional*): Override the default device definition - *ADDRESS* is found on the device itself in the form 1A.2B.3C or 1a2b3c - *CATEGORY* is found in the back of the device's User Guide in the form of @@ -92,16 +113,16 @@ Configuration variables: - *UNITCODE* is the X10 unit code values 1 - 16 - *PLATFORM* is the Home Assistant Platform to associate the device with. The following platforms are supported - - binary_sensor: Used for on/off devices or keypad buttons that are read only. + - binary_sensor: Used for on/off devices or keypad buttons that are read-only. - light: Used for dimmable X10 devices - switch: Used for On/Off X10 devices - *STEPS* is the number of dim/bright steps the device supports. Used for dimmable X10 devices only. Default value is 22. -- **x10_all_units_off** (*Optional*): Creates an binary_sensor that responds +- **x10_all_units_off** (*Optional*): Creates a binary_sensor that responds to the X10 standard command for All Units Off. -- **x10_all_lights_on** (*Optional*): Creates an binary_sensor that responds +- **x10_all_lights_on** (*Optional*): Creates a binary_sensor that responds to the X10 standard command for All Lights On -- **x10_all_lights_off** (*Optional*): Creates an binary_sensor that responds +- **x10_all_lights_off** (*Optional*): Creates a binary_sensor that responds to the X10 standard command for All Lights Off ### {% linkable_title Autodiscovery %} @@ -111,27 +132,27 @@ per device. Subsequent startups will occur much quicker using cached device information. If a device is not recognized during autodiscovery, you can add the device to the **device_override** configuration. -In order for a device to be discovered it must be linked to the INSTEON Modem +In order for a device to be discovered, it must be linked to the INSTEON Modem as either a responder or a controller. ### {% linkable_title Linking Devices to the INSTEON Modem %} In order for any two Insteon devices to talk with one another, they must be -linked. For an overview of device linking please read the Insteon page on +linked. For an overview of device linking, please read the Insteon page on [understanding linking]. The Insteon Modem module supports All-Linking through [Development Tools] service calls. The following services are available: - **insteon.add_all_link**: Puts the Insteon Modem (IM) into All-Linking -mode. The IM can be set as as controller or a responder. If the IM is a -controler, put the IM into linking mode then press the SET button on the -device. If the IM is a responer, press the SET button on the device then +mode. The IM can be set as a controller or a responder. If the IM is a +controller, put the IM into linking mode then press the SET button on the +device. If the IM is a responder, press the SET button on the device then put the IM into linking mode. - **insteon.delete_all_link**: Tells the Insteon Modem (IM) to remove an All-Link record from the All-Link Database of the IM and a device. Once the IM is set to delete the link, press the SET button on the corresponding device to complete the process. - **insteon.load_all_link_database**: Load the All-Link Database for a -device. WARNING - Loading a device All-Link database may take a LONG time and +device. WARNING - Loading a device All-Link database may take a LONG time and may need to be repeated to obtain all records. - **insteon.print_all_link_database**: Print the All-Link Database for a device. Requires that the All-Link Database is loaded first. @@ -174,7 +195,7 @@ devices. INSTEON devices are added to Home Assistant using the platform(s) that make the most sense given the model and features of the hardware. The features of the -INSTEON device are built into the Home Assistant platform. Changing the +INSTEON devices are built into the Home Assistant platform. Changing the platform is not recommended. There are two primary uses for the **device_override** feature. - Devices that do not respond during autodiscovery. This is common for battery @@ -185,7 +206,7 @@ platform is not recommended. There are two primary uses for the ### {% linkable_title Example Configuration with Options%} ```yaml -# Full example of insteon configuration with customizations and overrides +# Full example of Insteon configuration with customizations and overrides homeassistant: customize: @@ -205,7 +226,7 @@ insteon: ### {% linkable_title What NOT to do %} -Insteon Modem is a top level component and device discovery will identify +Insteon Modem is a top-level component and device discovery will identify the Home Assistant platform the device belongs in. As such, do not declare Insteon devices in other platforms. For example, this configuration will NOT work: @@ -224,19 +245,18 @@ events. The following events are available: - **insteon.button_on** - **address**: (required) The Insteon device address in lower case without dots (e.g. 1a2b3c) - - **button**: (Optional) The button id in lower case. For an 4 button remote - the values are a to d. For an 8 button remote the values are a to g. For - a one button remote this field is not used. + - **button**: (Optional) The button id in lower case. For a 4-button remote + the values are `a` to `d`. For an 8 button remote the values are `a` to `g`. For + a one-button remote this field is not used. - **insteon.button_of** - **address**: (required) The Insteon device address in lower case without dots (e.g. 1a2b3c) - - **button**: (Optional) The button id in lower case. For an 4 button remote - the values are a to d. For an 8 button remote the values are a to g. For - a one button remote this field is not used. + - **button**: (Optional) The button id in lower case. For a 4-button remote + the values are a to d. For an 8 button remote the values are `a` to `g`. For + a one-button remote this field is not used. -This allows the mini-remotes to be configured as - -Here is an example of how to use these events for automations: +This allows the mini-remotes to be configured as triggers for automations. Here +is an example of how to use these events for automations: ``` automation: @@ -276,8 +296,8 @@ The INSTEON Hub has three known issues that are inherent to the design of the Hub: 1. If you see multiple error messages in the log file stating the Hub -connection is closed and reconnection has failed, this generally requires -the Hub to be restarted in order to reconnect. +connection is closed, and reconnection has failed, this generally requires +the Hub to be restarted to reconnect. 2. You cannot use both Home Assistant and the INSTEON app. If you do, the changes made in the app will not appear in Home Assistant. Changes made in