From eee6766c084507fba5d4ae3bbd78634056e5ac03 Mon Sep 17 00:00:00 2001 From: Tom Harris Date: Mon, 31 Aug 2020 14:00:44 -0400 Subject: [PATCH] Add Config flow to the Insteon component (#13763) Co-authored-by: Franck Nijhof --- source/_integrations/insteon.markdown | 255 ++++++++++++-------------- 1 file changed, 119 insertions(+), 136 deletions(-) diff --git a/source/_integrations/insteon.markdown b/source/_integrations/insteon.markdown index b0d0f0c15e8..5ddf26ab69f 100644 --- a/source/_integrations/insteon.markdown +++ b/source/_integrations/insteon.markdown @@ -30,6 +30,8 @@ There is currently support for the following device types within Home Assistant: Device support is provided by the underlying [pyinsteon] 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 [2242] and [2245] Hubs. +You can configure the Insteon integration by going to the integrations page inside the configuration panel. + [pyinsteon]: https://github.com/pyinsteon/pyinsteon [2413U]: https://www.insteon.com/powerlinc-modem-usb [2412S]: https://www.insteon.com/powerlinc-modem-serial @@ -37,7 +39,120 @@ Device support is provided by the underlying [pyinsteon] package. It is known to [2245]: https://www.insteon.com/insteon-hub/ [2242]: https://www.insteon.com/support-knowledgebase/2014/9/26/insteon-hub-owners-manual -### INSTEON Modem configuration +## Autodiscovery + +The first time autodiscovery runs, the duration may require up to 60 seconds per device. Subsequent startups will occur much quicker using cached device information. If a device is not recognized during autodiscovery, trigger the device, such as toggling a button, to force the device to send a message to the modem. The device will then be discovered. You may need to trigger the device a few times. If for any reason this approach does not work, you can add the device to a **device override** in configuration options from the integrations page inside the configuration panel. + +In order for a device to be discovered, it must be linked to the INSTEON Modem as either a responder or a controller. + +## 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 [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 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 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. +- **insteon.print_im_all_link_database**: Print the All-Link Database for the INSTEON Modem (IM). + +If you are looking for more advanced options, you can use the [insteon_tools] command-line tool that is distributed with the [pyinsteon] Python module. Please see the documentation on the [pyinsteon] GitHub site. Alternatively, you can download [HouseLinc], which runs on any Windows PC, or you can use [Insteon Terminal] which is open source and runs on most platforms. SmartHome no longer supports HouseLinc, but it still works. Insteon Terminal is a very useful tool but please read the disclaimers carefully, they are important. + +[understanding linking]: https://www.insteon.com/support-knowledgebase/2015/1/28/understanding-linking +[Development Tools]: /docs/tools/dev-tools/ +[HouseLinc]: https://www.smarthome.com/houselinc.html +[Insteon Terminal]: https://github.com/pfrommerd/insteon-terminal +[insteon_tools]: https://github.com/pyinsteon/pyinsteon + +## Customization + +The only configuration item that is necessary is the PLM port or Hub IP address, username and password so that Home Assistant can connect to the INSTEON Modem. This will expose all the supported INSTEON devices which exist in the modem’s ALL-Link database. However, devices will only be shown by their INSTEON hex address (e.g., “1A.2B.3C”) which can be a bit unwieldy. As you link and unlink devices using the ‘Set’ buttons, they’ll be added and removed from Home Assistant automatically. + +You can use the normal Home Assistant [device customization] section of your configuration to assign friendly names and special icons to your devices. This is especially useful for setting device_class on your binary_sensor INSTEON devices. + +[device customization]: /getting-started/customizing-devices/ + +## Device Overrides + +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 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 operated devices. Before using a device override, please trigger the device a few times and it will likely be discovered by Home Assistant. +- Devices that have not been fully developed. This allows an unknown device to be mapped to a device that operates similarly to another device. + +Device overrides can be set up using the integrations page inside the configuration panel. + +## INSTEON Scenes + +Trigger an INSTEON scene on or off, is done via automations. Two services are provided to support this feature: + +- **insteon.scene_on** + - **group**: (required) The INSTEON scene number to trigger. +- **insteon.scene_off** + - **group**: (required) The INSTEON scene to turn off + +```yaml +automation: + # Trigger an INSTEON scene 25 + - id: trigger_scene_25_on + alias: Turn on scene 25 + action: + - service: insteon.scene_on + group: 25 +``` + +## Events and Mini-Remotes + +Mini-Remote devices do not appear as Home Assistant entities, they generate 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 a 4-button remote the values are `a` to `d`. For an 8 button remote the values are `a` to `h`. For a one-button remote this field is not used. +- **insteon.button_off** + - **address**: (required) The Insteon device address in lower case without dots (e.g., 1a2b3c) + - **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 `h`. For a one-button remote this field is not used. + +This allows the mini-remotes to be configured as triggers for automations. Here is an example of how to use these events for automations: + +```yaml +automation: + # 4 or 8 button remote with button c pressed + - id: light_on + alias: Turn a light on + trigger: + - platform: event + event_type: insteon.button_on + event_data: + address: 1a2b3c + button: c + condition: + - condition: state + entity_id: light.some_light + state: 'off' + action: + - service: light.turn_on + entity_id: light.some_light + + # single button remote + - id: light_off + alias: Turn a light off + trigger: + - platform: event + event_type: insteon.button_on + event_data: + address: 1a2b3c + condition: + - condition: state + entity_id: light.some_light + state: 'off' + action: + - service: light.turn_on + entity_id: light.some_light +``` + +## Manual configuration + +Manual configuration is not required as all configuration options are available through the integrations page inside the configuration panel. However, manual setup is available using the following settings. To set up an INSTEON Powerline Modem (PLM) device such as the [2413U], use the following configuration: @@ -92,7 +207,7 @@ port: required: false type: string host: - description: The host name or IP address of the Hub. Required with Hub. + description: The hostname or IP address of the Hub. Required with Hub. required: false type: string ip_port: @@ -100,11 +215,11 @@ ip_port: required: true type: integer username: - description: The username to login in to the local Hub. You can find your Hub username on the bottom of the Hub or you can use the Insteon app. Required for Hub version 2 setup. + description: The username to login into the local Hub. You can find your Hub username on the bottom of the Hub or you can use the Insteon app. Required for Hub version 2 setup. required: false type: string password: - description: The password to login in to the local Hub. You can find your Hub password on the bottom of the Hub or you can use the Insteon app. Required for Hub version 2 setup. + description: The password to login into the local Hub. You can find your Hub password on the bottom of the Hub or you can use the Insteon app. Required for Hub version 2 setup. required: false type: string hub_version: @@ -160,135 +275,3 @@ x10_devices: default: 22 type: integer {% endconfiguration %} - -### Autodiscovery - -The first time autodiscovery runs, the duration may require up to 60 seconds per device. Subsequent startups will occur much quicker using cached device information. If a device is not recognized during autodiscovery, trigger the device, such as toggling a button, to force the device to send a message to the modem. The device will then be discovered. You may need to trigger the device a few times. If for any reason this approach does not work, 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 as either a responder or a controller. - -### 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 [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 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 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. -- **insteon.print_im_all_link_database**: Print the All-Link Database for the INSTEON Modem (IM). - -If you are looking for more advanced options, you can use the [insteon_tools] command line tool that is distributed with the [pyinsteon] Python module. Please see the documentation on the [pyinsteon] GitHub site. Alternatively, you can download [HouseLinc] which runs on any Windows PC, or you can use [Insteon Terminal] which is open source and runs on most platforms. SmartHome no longer supports HouseLinc, but it still works. Insteon Terminal is a very useful tool but please read the disclaimers carefully, they are important. - -[understanding linking]: https://www.insteon.com/support-knowledgebase/2015/1/28/understanding-linking -[Development Tools]: /docs/tools/dev-tools/ -[HouseLinc]: https://www.smarthome.com/houselinc.html -[Insteon Terminal]: https://github.com/pfrommerd/insteon-terminal -[insteon_tools]: https://github.com/pyinsteon/pyinsteon - -### Customization - -The only configuration item that is necessary is the PLM port or Hub IP address, username and password so that Home Assistant can connect to the INSTEON Modem. This will expose all the supported INSTEON devices which exist in the modem’s ALL-Link database. However, devices will only be shown by their INSTEON hex address (e.g., “1A.2B.3C”) which can be a bit unwieldy. As you link and unlink devices using the ‘Set’ buttons, they’ll be added and removed from Home Assistant automatically. - -You can use the normal Home Assistant [device customization] section of your configuration to assign friendly names and special icons to your devices. This is especially useful for setting device_class on your binary_sensor INSTEON devices. - -[device customization]: /getting-started/customizing-devices/ - -### Device Overrides - -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 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 operated devices. Before using a device override, please trigger the device a few times and it will likely be discovered by Home Assistant. -- Devices that have not been fully developed. This allows an unknown device to be mapped to a device that operates similarly to another device. - -### Example Configuration with Options - -```yaml -# Full example of Insteon configuration with a device override - -insteon: - port: /dev/ttyUSB0 - device_override: - - address: a1b2c3 # Hidden Door Sensor [2845-222] - cat: 0x10 - subcat: 0x11 -``` - -### What NOT to do - -Insteon Modem is a top-level integration 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: - -```yaml -light: - - platform: insteon - address: 1a2b3c -``` - -### INSTEON Scenes - -Trigger an INSTEON scene on or off is done via automations. Two services are provided to support this feature: - -- **insteon.scene_on** - - **group**: (required) The INSTEON scene number to trigger. -- **insteon.scene_off** - - **group**: (required) The INSTEON scene to turn off - -```yaml -automation: - # Trigger an INSTEON scene 25 - - id: trigger_scene_25_on - alias: Turn on scene 25 - action: - - service: insteon.scene_on - group: 25 -``` - -### Events and Mini-Remotes - -Mini-Remote devices do not appear as Home Assistant entities, they generate 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 a 4-button remote the values are `a` to `d`. For an 8 button remote the values are `a` to `h`. For a one-button remote this field is not used. -- **insteon.button_off** - - **address**: (required) The Insteon device address in lower case without dots (e.g., 1a2b3c) - - **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 `h`. For a one-button remote this field is not used. - -This allows the mini-remotes to be configured as triggers for automations. Here is an example of how to use these events for automations: - -```yaml -automation: - # 4 or 8 button remote with button c pressed - - id: light_on - alias: Turn a light on - trigger: - - platform: event - event_type: insteon.button_on - event_data: - address: 1a2b3c - button: c - condition: - - condition: state - entity_id: light.some_light - state: 'off' - action: - - service: light.turn_on - entity_id: light.some_light - - # single button remote - - id: light_off - alias: Turn a light off - trigger: - - platform: event - event_type: insteon.button_on - event_data: - address: 1a2b3c - condition: - - condition: state - entity_id: light.some_light - state: 'off' - action: - - service: light.turn_on - entity_id: light.some_light -```