From d0830ba60047bed68c4397880eb3f85d1a844c16 Mon Sep 17 00:00:00 2001 From: Tom Harris Date: Mon, 26 Feb 2018 14:14:43 -0500 Subject: [PATCH] Insteon_plm updated to 0.8.2 (#4695) * Updated for recent Insteon version update * Fix linkable_title * Correct formating issues * Clean up yaml content * Exclude VS items * Remove tabs from line * Simplify description of config options * Clarify device_override * Remove newnames configuration option * Fix spelling and clearify autodiscovery * Remove tabs from yaml * Update for documentation review * Revert version back to original release version. --- .gitignore | 8 +- .../binary_sensor.insteon_plm.markdown | 2 +- source/_components/fan.insteon_plm.markdown | 24 ++++++ source/_components/insteon_plm.markdown | 84 +++++++++++++++---- source/_components/light.insteon_plm.markdown | 2 +- .../_components/sensor.insteon_plm.markdown | 22 +++++ .../_components/switch.insteon_plm.markdown | 2 +- 7 files changed, 122 insertions(+), 22 deletions(-) create mode 100644 source/_components/fan.insteon_plm.markdown create mode 100644 source/_components/sensor.insteon_plm.markdown diff --git a/.gitignore b/.gitignore index ec8690ad29c..6713e9e11c0 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,10 @@ vendor node_modules source/.jekyll-metadata *.iml -.idea/ \ No newline at end of file +.idea/ +/.vs/home-assistant.github.io/v15/.suo +/.vs/ProjectSettings.json +/.vs/slnx.sqlite +/.vs/config/applicationhost.config +/.vs/slnx.sqlite-journal +/.vs/VSWorkspaceState.json diff --git a/source/_components/binary_sensor.insteon_plm.markdown b/source/_components/binary_sensor.insteon_plm.markdown index bd685df7c29..e2930b02dc6 100644 --- a/source/_components/binary_sensor.insteon_plm.markdown +++ b/source/_components/binary_sensor.insteon_plm.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon PLM Binary Sensor" -description: "Instructions how to setup the Insteon PLM switches locally within Home Assistant." +description: "Instructions how to setup the Insteon PLM binary sensors locally within Home Assistant." date: 2017-02-19 17:00 sidebar: true comments: false diff --git a/source/_components/fan.insteon_plm.markdown b/source/_components/fan.insteon_plm.markdown new file mode 100644 index 00000000000..23c0cbac84b --- /dev/null +++ b/source/_components/fan.insteon_plm.markdown @@ -0,0 +1,24 @@ +--- +layout: page +title: "Insteon PLM Fan" +description: "Instructions how to setup the Insteon PLM fan locally within Home Assistant." +date: 2017-02-19 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: insteon.png +ha_category: Fan +ha_iot_class: "Local Push" +ha_version: 0.65 +--- + +The `insteon_plm` fan platform lets you control your [FanLinc] through +an INSTEON PowerLinc Modem (PLM) device connected directly to your system on a +USB or serial port. To add support, set up the primary [insteon_plm] +component. + +[insteon_plm]: /components/insteon_plm/ +[FanLinc]: https://www.smarthome.com/fanlinc-insteon-2475f-ceiling-fan-and-light-controller-fixture-module-dual-band.html + + diff --git a/source/_components/insteon_plm.markdown b/source/_components/insteon_plm.markdown index f28db9b74cd..e3fb65bcc97 100644 --- a/source/_components/insteon_plm.markdown +++ b/source/_components/insteon_plm.markdown @@ -16,13 +16,15 @@ ha_version: 0.39 This component adds "local push" support for INSTEON PowerLinc Modems allowing linked INSTEON devices to be used within Home Assistant as lights, switches, and binary sensors. Device support is provided by the underlying [insteonplm] -package. It is known to work with both the [2413U] USB and [2412S] -RS242 flavors of PLM. This component does not work with the IP-based hub -products. For that, you'll want the "Insteon (Local)" component instead. +package. It is known to work with the [2413U] USB and [2412S] RS242 flavors +of PLM and the [2448A7] USB stick. This component does not work with the +IP-based hub products. For that, you'll want the "Insteon (Local)" component +instead. [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 ```yaml @@ -30,14 +32,48 @@ products. For that, you'll want the "Insteon (Local)" component instead. insteon_plm: port: SERIAL_PORT device_override: - - address: INSTEON_ADDRESS - platform: DEVICE_PLATFORM + - address: ADDRESS + cat: CATEGORY + subcat: SUBCATEGORY + firmware: FIRMWARE + product_key: PRODUCT_KEY ``` - Configuration variables: - **port** (*Required*): The port for your device, e.g. `/dev/ttyUSB0` -- **device_override** (*Optional*): Override the default device platform - +- **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 + 0x00 - 0xff + - *SUBCATEGORY* is found in the back of the device's User Guide in the form + of 0x00 - 0xff + - *FIRMWARE* and *PRODUCT_KEY* are more advanced options and will typically + not be used. + +### {% linkable_title Autodiscovery %} + +The first time autodiscovery runs, the duration may require up to 20 seconds +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 PLM as either +a responder or a controller. + +### {% linkable_title Linking Devices to the PLM %} + +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]. Currently Insteon PLM does not support software +linking of devices. If you need software that can link your devices (if you +are using a USB Stick PLM for example), 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. HouseLinc is no longer supported by SmartHome but it +still works. Insteon Terminal is a very useful tool but please read the +disclaimers carefully, they are important. + +[understanding linking]: http://www.insteon.com/support-knowledgebase/2015/1/28/understanding-linking +[HouseLinc]: https://www.smarthome.com/houselinc.html +[Insteon Terminal]: https://github.com/pfrommerd/insteon-terminal ### {% linkable_title Customization %} @@ -58,14 +94,14 @@ devices. ### {% linkable_title 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. In most cases this is -unambiguous, but sometimes the component will not be able to guess the actual -usage of the device. For example, there might be a table lamp plugged into an -INSTEON appliance relay module. By default, this will show as a 'switch' -device in Home Assistant, but it really should be a 'light' device. For -exceptions like this, the component supports a device platform override. You -can set any device (by address) to explicitly use a specific platform if the -default is not correct. +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 +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. +- Devices that have not been fully developed. This allows an unknown device to + be mapped to a device that operates similarly to another device. ### {% linkable_title Example Configuration with Options%} @@ -83,7 +119,19 @@ homeassistant: insteon_plm: port: /dev/ttyUSB0 device_override: - - address: a1b2c3 # Icon Appliance Module for bedside lamp - platform: light # make it a light instead of a switch + - address: a1b2c3 # Hidden Door Sensor [2845-222] + cat: 0x10 + subcat: 0x11 +``` +### {% linkable_title What NOT to do %} +Insteon PLM 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: + +```yaml +light: + - platform: insteon_plm + address: 1a2b3c ``` diff --git a/source/_components/light.insteon_plm.markdown b/source/_components/light.insteon_plm.markdown index 7c95d8dfe4f..04ab92bdee6 100644 --- a/source/_components/light.insteon_plm.markdown +++ b/source/_components/light.insteon_plm.markdown @@ -13,5 +13,5 @@ ha_iot_class: "Local Push" ha_version: 0.39 --- -The `insteon_plm` light platform lets you control your sensors through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on an USB or serial port. To add support, set up the primary [insteon_plm](/components/insteon_plm/) component. +The `insteon_plm` light platform lets you control your dimmable light switches through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on an USB or serial port. To add support, set up the primary [insteon_plm](/components/insteon_plm/) component. diff --git a/source/_components/sensor.insteon_plm.markdown b/source/_components/sensor.insteon_plm.markdown new file mode 100644 index 00000000000..db9125f33ab --- /dev/null +++ b/source/_components/sensor.insteon_plm.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "Insteon PLM Sensor" +description: "Instructions how to setup the Insteon PLM sensors locally within Home Assistant." +date: 2017-02-19 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: insteon.png +ha_category: Sensor +ha_iot_class: "Local Push" +ha_version: 0.65 +--- + +The `insteon_plm` sensor platform lets you control your sensors through +an INSTEON PowerLinc Modem (PLM) device connected directly to your system on a +USB or serial port. To add support, set up the primary [insteon_plm] +component. + +[insteon_plm]: /components/insteon_plm/ + diff --git a/source/_components/switch.insteon_plm.markdown b/source/_components/switch.insteon_plm.markdown index 2e32a561603..0db0d143ccb 100644 --- a/source/_components/switch.insteon_plm.markdown +++ b/source/_components/switch.insteon_plm.markdown @@ -13,7 +13,7 @@ ha_iot_class: "Local Push" ha_version: 0.39 --- -The `insteon_plm` switch platform lets you control your switches through +The `insteon_plm` switch platform lets you control your on/off switches through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on a USB or serial port. To add support, set up the primary [insteon_plm] component.