From 5796657a44ba3f31a40bc1b7485ff879ee93d57d Mon Sep 17 00:00:00 2001 From: TKTF50 Date: Wed, 5 Jan 2022 18:22:56 -0500 Subject: [PATCH] Emphasize use of state variable for custom devices (#20559) --- source/_integrations/isy994.markdown | 34 ++++++++++-------- .../isy994/isy994_switch_variable_example.png | Bin 0 -> 4255 bytes 2 files changed, 19 insertions(+), 15 deletions(-) create mode 100644 source/images/isy994/isy994_switch_variable_example.png diff --git a/source/_integrations/isy994.markdown b/source/_integrations/isy994.markdown index bbdc9070558..31a2637e5cb 100644 --- a/source/_integrations/isy994.markdown +++ b/source/_integrations/isy994.markdown @@ -45,7 +45,7 @@ There is currently support for the following device types within Home Assistant: - Sensor - Switch -Home Assistant is capable of communicating with any binary sensor, cover, fan, light, lock, sensor and switch that is configured on the controller. Using the programs on the controller, custom binary sensors, cover, fan, lock, and switches can also be created. +Home Assistant is capable of communicating with any binary sensor, cover, fan, light, lock, sensor and switch that is configured on the controller. Using the programs on the controller, custom binary sensors, covers, fans, locks, and switches can also be created. {% include integrations/config_flow.md %} @@ -67,20 +67,20 @@ host: required: true type: string username: - description: The username that used to access the ISY interface. + description: The username that is used to access the ISY interface. required: true type: string password: - description: The password that used to access the ISY interface. + description: The password that is used to access the ISY interface. required: true type: string sensor_string: - description: This is the string that is used to identify which devices are to be assumed to be sensors instead of lights of switches. If this string is found in the device name or folder, Home Assistant will assume it is as a sensor or binary sensor (if the device has on/off or true/false states). This is only necessary for nodes that are not automatically detected as sensors by Home Assistant. Insteon door, window, motion and leak sensors should all be detected automatically. + description: This is the string that is used to identify which devices are to be assumed to be sensors instead of lights or switches. If this string is found in the device name or folder, Home Assistant will assume it is a sensor or binary sensor (if the device has on/off or true/false states). This is only necessary for nodes that are not automatically detected as sensors by Home Assistant. Insteon door, window, motion and leak sensors should all be detected automatically. required: false type: string default: sensor variable_sensor_string: - description: This is the string that is used to identify which Integer or State Variables are to be added as sensors. If this string is found in the device name, Home Assistant will assume it is as a sensor. + description: This is the string that is used to identify which Integer or State Variables are to be added as sensors. If this string is found in the device name, Home Assistant will assume it is a sensor. required: false type: string default: sensor @@ -149,7 +149,7 @@ All `isy994_control` events will have an `entity_id` and `control` parameter in ### Insteon Scenes & Keypad/Remote Buttons -All Insteon scenes configured in the ISY994 will show up as a `switch` in Home Assistant, as they do not support dimming or setting specific brightness settings as Home Assisstant's `light` component. +All Insteon scenes configured in the ISY994 will show up as a `switch` in Home Assistant, as they do not support dimming or setting specific brightness settings as Home Assistant's `light` component. Insteon Secondary Keypad buttons and Remote buttons are added to Home Assistant to allow support for using Control Events in Automations. These devices are added as `sensors` since they cannot be directly controlled (turned on/off); their state is the last ON level command they sent, in a range from `0` (Off) to `255` (On 100%). Note: these devices may report incorrect states before being used after a reboot of the ISY. Secondary Keypad buttons may be turned on or off using ISY Scenes (refer to ISY Documentation for more details). @@ -167,7 +167,7 @@ Send a command to an ISY Device using its Home Assistant entity ID. Valid comman | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of entities to send the command, e.g., `light.front_porch`. | +| `entity_id` | no | Name(s) of target entities for the command, e.g., `light.front_porch`. | | `command` | no | The command to be sent to the device, e.g., `"fast_on"` | #### Service `isy994.send_raw_node_command` @@ -176,7 +176,7 @@ Send a "raw" (e.g., `DON`, `DOF`) ISY REST Device Command to a Node using its Ho | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of entities to send the command, e.g., `light.front_porch`. | +| `entity_id` | no | Name(s) of target entities for the command, e.g., `light.front_porch`. | | `command` | no | The ISY REST Command to be sent to the device, e.g., `"DON"` | | `value` | yes | The integer value to be sent with the command, if required by the command, e.g., `255` | | `parameters` | yes | A `dict` of parameters to be sent in the query string for controlling colored bulbs or advanced parameters, e.g., `{ GV2: 0, GV3: 0, GV4: 255 }` | @@ -188,7 +188,7 @@ Request a Z-Wave Device parameter via the ISY. The parameter value will be retur | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------- | -| `entity_id` | no | Name of entity to send the command, e.g., `light.front_porch`. This must be an ISY Z-Wave Node. | +| `entity_id` | no | Name of target entity for the command, e.g., `light.front_porch`. This must be an ISY Z-Wave Node. | | `parameter` | no | The parameter number to retrieve from the end device. | #### Service `isy994.set_zwave_parameter` @@ -197,7 +197,7 @@ Update a Z-Wave Device parameter via the ISY. The parameter value will also be r | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------- | -| `entity_id` | no | Name of entity to send the command, e.g., `light.front_porch`. This must be an ISY Z-Wave Node. | +| `entity_id` | no | Name of target entity for the command, e.g., `light.front_porch`. This must be an ISY Z-Wave Node. | | `parameter` | no | The parameter number to set on the end device. | | `value` | no | The value to set for the parameter. May be an integer or byte string (e.g. "0xFFFF"). | | `size` | no | The size of the parameter, either 1, 2, or 4 bytes. | @@ -208,7 +208,7 @@ Rename a node or group (scene) on the ISY994. Note: this will not automatically | Service data attribute | Optional | Description | | ---------------------- | -------- | -------------------------------------------------------------- | -| `entity_id` | no | Name of entity to send the command, e.g., `light.front_porch`. | +| `entity_id` | no | Name of target entity for the command, e.g., `light.front_porch`. | | `name` | no | The new name to use within the ISY994. | #### Service `isy994.set_on_level` @@ -217,7 +217,7 @@ Send an ISY set_on_level command to a `light` Node to set the devices' local On | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of entities to send the command, e.g., `light.front_porch`. | +| `entity_id` | no | Name(s) of target entities for the command, e.g., `light.front_porch`. | | `value` | no | The integer value to set the On Level to in a range of 0-255, e.g., `255` | #### Service `isy994.set_ramp_rate` @@ -226,7 +226,7 @@ Send an ISY set_ramp_rate command to a `light` Node to set the devices' ramp rat | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of entities to send the command, e.g., `light.front_porch`. | +| `entity_id` | no | Name(s) of target entities for the command, e.g., `light.front_porch`. | | `value` | no | The integer index value to set the Ramp Rate to in a range of `0` (9.5 minutes) to `31` (0.1 Seconds), e.g., `28` | #### Service `isy994.system_query` @@ -330,13 +330,17 @@ A device is created by creating a directory, with the name for the device, under - *HA.lock* will create a lock. - *HA.switch* will create a switch. -A program, named *status*, is required under the program device directory. A program, named *actions*, is required for all program devices except for binary_sensor. Any other programs in these device directories will be ignored. The *status* program requires that you create a variable with the name of your choice. This variable will store the actual status of the new device and will be updated by the *action* program. +A program, named *status*, is required under the program device directory. A program, named *actions*, is required for all program devices except for binary_sensor. Any other programs in these device directories will be ignored.

-The *status* program in this directory is what indicates the state of the device: +The *status* program requires that you create a state variable with the name of your choice. Note that you must use a state variable, not an integer variable. This variable will store the actual status of the new device and will be updated by the *action* program. + +![Screenshot of switch variable](/images/isy994/isy994_switch_variable_example.png) + +The IF clause of the *status* program in the device directory is what indicates the state of the device: - *binary_sensor* on if the clause returns true, otherwise off. - *cover* closed if the clause returns true, otherwise open. diff --git a/source/images/isy994/isy994_switch_variable_example.png b/source/images/isy994/isy994_switch_variable_example.png new file mode 100644 index 0000000000000000000000000000000000000000..bdd0700471c4ccbef0cbe4c5affcf676e2ee6ee8 GIT binary patch literal 4255 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