From 9982a04814ee9d91dc9c3cab9992719e574174f7 Mon Sep 17 00:00:00 2001 From: David McNett Date: Sat, 25 Feb 2017 23:18:14 -0600 Subject: [PATCH] New component insteon_plm and related platforms (#2092) * Initial pass at insteon_plm documentation * Amend transcription error * Transcription error two * Revise references to sensor_class to device_class I just noticed PR # 5860 in hom-assistant is merged, so in anticipation of that change I proactively updated this documentation to refer to device_class instead of sensor_class in configuration examples. * Oops! replace stale reference * Revise customize: syntax to new (old) format --- .../binary_sensor.insteon_plm.markdown | 22 +++++ source/_components/insteon_plm.markdown | 89 +++++++++++++++++++ source/_components/light.insteon_plm.markdown | 22 +++++ .../_components/switch.insteon_plm.markdown | 22 +++++ 4 files changed, 155 insertions(+) create mode 100644 source/_components/binary_sensor.insteon_plm.markdown create mode 100644 source/_components/insteon_plm.markdown create mode 100644 source/_components/light.insteon_plm.markdown create mode 100644 source/_components/switch.insteon_plm.markdown diff --git a/source/_components/binary_sensor.insteon_plm.markdown b/source/_components/binary_sensor.insteon_plm.markdown new file mode 100644 index 00000000000..bd685df7c29 --- /dev/null +++ b/source/_components/binary_sensor.insteon_plm.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "Insteon PLM Binary Sensor" +description: "Instructions how to setup the Insteon PLM switches locally within Home Assistant." +date: 2017-02-19 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: insteon.png +ha_category: Binary Sensor +ha_iot_class: "Local Push" +ha_version: 0.39 +--- + +The `insteon_plm` binary 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/insteon_plm.markdown b/source/_components/insteon_plm.markdown new file mode 100644 index 00000000000..8949d4872ed --- /dev/null +++ b/source/_components/insteon_plm.markdown @@ -0,0 +1,89 @@ +--- +layout: page +title: "Insteon PLM" +description: "Instructions how to setup an Insteon USB PLM locally within Home Assistant." +date: 2017-02-19 16:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: insteon.png +ha_category: Hub +ha_iot_class: "Local Push" +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. + +[insteonplm]: https://github.com/nugget/python-insteonplm +[2413U]: https://www.insteon.com/powerlinc-modem-usb +[2412S]: https://www.insteon.com/powerlinc-modem-serial + + +```yaml +# insteon_plm supported configuration variables +insteon_plm: + port: SERIAL_PORT + device_override: + - address: INSTEON_ADDRESS + platform: DEVICE_PLATFORM +``` + +Configuration variables: +- **port** (*Required*): The port for your device, e.g. `/dev/ttyUSB0` +- **device_override** (*Optional*): Override the default device platform + + +### {% linkable_title Customization %} + +The only configuration item that is absolutely necessary is the port so that +Home Assistant can connect to the PLM. 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/ + +### {% 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 plaform override. You +can set any device (by address) to explicitly use a specific platform if the +default is not correct. + +### {% linkable_title Example Configuration with Options%} + +```yaml +# Full example of insteon_plm configuration with customizations and overrides + +homeassistant: + customize: + light.a1b2c3: + friendly_name: Bedside Lamp + binary_sensor.a2b3c4: + friendly_name: Garage Door + device_class: opening + +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 +``` + diff --git a/source/_components/light.insteon_plm.markdown b/source/_components/light.insteon_plm.markdown new file mode 100644 index 00000000000..9a069488597 --- /dev/null +++ b/source/_components/light.insteon_plm.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "Insteon PLM Light" +description: "Instructions how to setup Insteon PLM lights locally within Home Assistant." +date: 2017-02-19 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: insteon.png +ha_category: Light +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 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 new file mode 100644 index 00000000000..2e32a561603 --- /dev/null +++ b/source/_components/switch.insteon_plm.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "Insteon PLM Switch" +description: "Instructions how to setup the Insteon PLM switches locally within Home Assistant." +date: 2017-02-19 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: insteon.png +ha_category: Switch +ha_iot_class: "Local Push" +ha_version: 0.39 +--- + +The `insteon_plm` switch platform lets you control your 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. + +[insteon_plm]: /components/insteon_plm/ +