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.

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
 ```