Add Services to ISY994 (#13390)

This commit is contained in:
shbatm 2020-05-12 03:07:53 -05:00 committed by GitHub
parent 1a58a3d9b9
commit 80a9c2bd34
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -138,6 +138,105 @@ All Insteon scenes configured in the ISY994 will show up as a `switch` in Home A
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).
### Services
Once loaded, the following services will be exposed with the `isy994.` prefix, to allow advanced control over the ISY and its connected devices:
- Entity services for Home Assistant-connected entities: `send_node_command`, `send_raw_node_command`, `set_on_level`, and `set_ramp_rate`.
- Generic ISY services: `system_query`, `set_variable`, `send_program_command`, and `run_network_resource`.
- Management services for the ISY994 Home Assistant integration: `reload` and `cleanup_entities`.
#### Service `isy994.send_node_command`
Send a command to an ISY Device using its Home Assistant entity ID. Valid commands are: `beep`, `brighten`, `dim`, `disable`, `enable`, `fade_down`, `fade_stop`, `fade_up`, `fast_off`, `fast_on`, and `query`.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Name(s) of entities to send 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`
Send a "raw" (e.g., `DON`, `DOF`) ISY REST Device Command to a Node using its Home Assistant Entity ID. This is useful for devices that aren't fully supported in Home Assistant yet, such as controls for many NodeServer nodes. Refer to the ISY (or PyISY Python Module) Documentation for details of valid commands.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Name(s) of entities to send 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 }` |
| `unit_of_measurement` | yes | The ISY Unit of Measurement (UOM) to send with the command, if required, e.g., `67` |
#### Service `isy994.set_on_level`
Send an ISY set_on_level command to a `light` Node to set the devices' local On Level.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Name(s) of entities to send 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`
Send an ISY set_ramp_rate command to a `light` Node to set the devices' ramp rate. Refer to the PyISY documentation for the [available values](https://github.com/automicus/PyISY/blob/d053369f7531370a907136bf25a177632adccd1e/pyisy/constants.py#L630).
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Name(s) of entities to send 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`
Request the ISY Query the connected devices.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `address` | yes | ISY Address to Query. Omitting this requests a system-wide scan (typically recommended by UDI to be scheduled once per day), e.g., `"1A 2B 3C 1"` |
| `isy` | yes | If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). Omitting this will cause all ISYs to be queried, e.g., `"ISY"` |
#### Service `isy994.set_variable`
Set an ISY variable's current or initial value. Variables can be set by either type/address or by name.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `value` | no | The integer value to be sent, e.g., `255` |
| `address` | no | The address of the variable for which to set the value, e.g., `5` |
| `type` | no | The variable type, 1 = Integer, 2 = State, e.g., `2` |
| `name` | yes | The name of the variable to set (Optional, use `name` instead of `type` and `address`), e.g., `"my_variable_name"` |
| `init` | yes | If True, the initial (init) value will be updated instead of the current value, e.g., `false` |
| `isy` | yes | If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). If you have the same variable name or address on multiple ISYs, omitting this will run the command on them all, e.g., `"ISY"` |
#### Service `isy994.send_program_command`
Send a command to control an ISY program or folder. Valid commands are `run`, `run_then`, `run_else`, `stop`, `enable`, `disable`, `enable_run_at_startup`, and `disable_run_at_startup`.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `command` | no | The ISY Program Command to be sent, e.g., `"run"` |
| `address` | yes | The address of the program to control (optional, use either `address` or `name`), e.g., `"04B1"` |
| `name` | yes | The name of the program to control (optional, use either `address` or `name`), e.g., `"My Program"` |
| `isy` | yes | (Optional) If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). If you have the same program name or address on multiple ISYs, omitting this will run the command on them all, e.g., `"ISY"` |
#### Service `isy994.run_network_resource`
Run a network resource on the ISY.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `address` | yes | The address of the network resource to execute (optional, use either `address` or `name`), e.g., `121` |
| `name` | yes | The name of the network resource to execute (optional, use either `address` or `name`), e.g., `"Network Resource 1"` |
| `isy` | yes | (Optional) If you have more than one ISY connected, provide the name of the ISY to query (as shown on the Device Registry or as the top-first node in the ISY Admin Console). If you have the same resource name or address on multiple ISYs, omitting this will run the command on them all, e.g., `"ISY"` |
#### Service `isy994.reload`
Reload the ISY994 connection(s) without restarting Home Assistant. Use this service to pick up new devices that have been added or changed on the ISY since the last restart of Home Assistant.
#### Service `isy994.cleanup_entities`
Cleanup old entities no longer used by the ISY994 integrations. Useful if you've removed devices from the ISY or changed the filter string options in the configuration to exclude additional items and they were not properly removed
by Home Assistant.
### Creating Custom Devices using ISY Programs
Using the Programs tab in the controller's Administrative Console, custom devices can be created that will appear natively inside of Home Assistant. Home Assistant will scan the following folders and build the device to the associated domains: