Merge pull request #5 from automicus/master
Documentation for ISY994 Platform and Entity ABC
@ -88,8 +88,25 @@ Entities are things that you want to observe within Home Assistant. Support for
|
|||||||
<td>Track what is being played and control playback. (temporarely disabled awaiting protobuf 3 release)</td>
|
<td>Track what is being played and control playback. (temporarely disabled awaiting protobuf 3 release)</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td><a href='/components/isy994.html'><img src='/images/supported_brands/insteon.png' class='brand overview' /></a></td>
|
||||||
|
<td><a href='/components/isy994.html'>Insteon Devices</a></td>
|
||||||
|
<td>Insteon devices can be controlled with the ISY994 controller.</td>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td><a href='/components/isy994.html'><img src='/images/supported_brands/x10.gif' class='brand overview' /></a></td>
|
||||||
|
<td><a href='/components/isy994.html'>X10 Devices</a></td>
|
||||||
|
<td>X10 devices can be controlled with the ISY994 controller.</td>
|
||||||
|
</tr>
|
||||||
|
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
<p class='note'>
|
||||||
|
Support for these devices is provided by the Home Assistant community and not
|
||||||
|
the manufacturers of these devices.
|
||||||
|
</p>
|
||||||
|
|
||||||
## {% linkable_title Organization %}
|
## {% linkable_title Organization %}
|
||||||
| Type | Description
|
| Type | Description
|
||||||
| ---- | -----------
|
| ---- | -----------
|
||||||
@ -104,7 +121,12 @@ Home Assistant integrates with a variety of third party Home Automation hubs and
|
|||||||
[<img src='/images/supported_brands/telldus_tellstick.png' class='brand' />](/components/tellstick.html)
|
[<img src='/images/supported_brands/telldus_tellstick.png' class='brand' />](/components/tellstick.html)
|
||||||
[<img src='/images/supported_brands/vera.png' class='brand' />](/components/vera.html)
|
[<img src='/images/supported_brands/vera.png' class='brand' />](/components/vera.html)
|
||||||
[<img src='/images/supported_brands/wink.png' class='brand' />](/components/wink.html)
|
[<img src='/images/supported_brands/wink.png' class='brand' />](/components/wink.html)
|
||||||
|
[<img src='/images/supported_brands/universal_devices.png' class='brand' />](/components/isy994.html)
|
||||||
|
|
||||||
|
<p class='note'>
|
||||||
|
Support for these devices is provided by the Home Assistant community and not
|
||||||
|
the manufacturers of these devices.
|
||||||
|
</p>
|
||||||
|
|
||||||
## {% linkable_title Services %}
|
## {% linkable_title Services %}
|
||||||
|
|
||||||
@ -158,6 +180,11 @@ Home Assistant integrates with a variety of third party Home Automation hubs and
|
|||||||
</tr>
|
</tr>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
<p class='note'>
|
||||||
|
Support for these services is provided by the Home Assistant community and not
|
||||||
|
the service providers.
|
||||||
|
</p>
|
||||||
|
|
||||||
## {% linkable_title Automation %}
|
## {% linkable_title Automation %}
|
||||||
|
|
||||||
| Type | Description
|
| Type | Description
|
||||||
|
120
source/components/isy994.markdown
Normal file
@ -0,0 +1,120 @@
|
|||||||
|
---
|
||||||
|
layout: page
|
||||||
|
title: "ISY-994 Controller"
|
||||||
|
description: "Instructions how to setup the ISY994 controller within Home Assistant."
|
||||||
|
date: 2015-01-20 22:36
|
||||||
|
sidebar: false
|
||||||
|
comments: false
|
||||||
|
sharing: true
|
||||||
|
footer: true
|
||||||
|
---
|
||||||
|
|
||||||
|
### Basic Configuration ###
|
||||||
|
|
||||||
|
The ISY994 is a home automation controller that is capable of controlling
|
||||||
|
Insteon and X10 devices. The controller is also capable of controlling Z-Wave
|
||||||
|
devices but that functionality has not yet been confirmed with Home Assistant.
|
||||||
|
The ISY994 controller is manufactured by [Universal
|
||||||
|
Devices](https://www.universal-devices.com/residential/isy994i-series/).
|
||||||
|
|
||||||
|
Home Assistant is capable of communicating with any switch, sensor, and light
|
||||||
|
that is configured on the controller. Using the programs on the controller,
|
||||||
|
custom switches and sensors can also be created.
|
||||||
|
|
||||||
|
To integrate your ISY994 controller with Home Assistant, add the following
|
||||||
|
section to your configuration.yaml file:
|
||||||
|
|
||||||
|
```
|
||||||
|
isy994:
|
||||||
|
# requried
|
||||||
|
host: ISY_ADDRESS
|
||||||
|
username: ISY_USERNAME
|
||||||
|
password: ISY_PASSWORD
|
||||||
|
|
||||||
|
# optional
|
||||||
|
sensor_string: SENSOR_STRING
|
||||||
|
hidden_string: HIDDEN_STRING
|
||||||
|
```
|
||||||
|
|
||||||
|
The ISY_ADDRESS should be in full URL format. For example:
|
||||||
|
http://192.168.10.100:80
|
||||||
|
|
||||||
|
The ISY_USERNAME and ISY_PASSWORD are the configured username and password used
|
||||||
|
to access the ISY interface.
|
||||||
|
|
||||||
|
The SENSOR_STRING is a string that is used to identify which devices are to be
|
||||||
|
assumed to be sensors instead of lights of switches. By default, this string is
|
||||||
|
'Sensor'. If this string is found in the device name, Home Assistant will
|
||||||
|
assume it is as a sensor.
|
||||||
|
|
||||||
|
The HIDDEN_STRING is a string that is used to identify which devices are to be
|
||||||
|
hidden on Home Assistant's front page. This string will be stripped from the
|
||||||
|
device's name before being used. By default, this value is '{HIDE ME}'.
|
||||||
|
|
||||||
|
Once the ISY controller is configured, it will automatically import any lights,
|
||||||
|
switches, and sensors it can locate.
|
||||||
|
|
||||||
|
### Creating Custom Switches ###
|
||||||
|
|
||||||
|
Using the Programs tab in the controller's Administrative Console, custom
|
||||||
|
switches can be created that will appear natively inside of Home Assistant.
|
||||||
|
Home Assistant will scan two different directories for switch configurations on
|
||||||
|
the controller. These directories must exist at the root level. The two
|
||||||
|
directories used to make switches are *HA.doors* and *HA.switches*. Currently,
|
||||||
|
the two receive identical treatment in Home Assistant.
|
||||||
|
|
||||||
|
A switch is created by creating a directory under either of these root
|
||||||
|
dirctories with the name you would like to call the switch. Two programs are
|
||||||
|
then required in this directory: *status* and *actions*. The image below shows
|
||||||
|
a sample configuration. This sample includes an extra program called *auto on*.
|
||||||
|
This is ignored by Home Assistant.
|
||||||
|
|
||||||
|
<p class='img'>
|
||||||
|
<img src='{{site_root}}/images/isy994/isy994_SwitchExample.png' />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
The *status* program in this directory is what indicates if the switch is on or
|
||||||
|
off. Only the IF clause is evaluated. If the clause returns True, the switch
|
||||||
|
will be on. False will indicate the switch is off.
|
||||||
|
|
||||||
|
<p class='img'>
|
||||||
|
<img src='{{site_root}}/images/isy994/isy994_SwitchStatusExample.png' />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
The *actions* program indicates what should be performed to turn the switch on
|
||||||
|
or off. The THEN clause gives instructions for turning the switch on while the
|
||||||
|
ELSE clause gives instructions for turning the switch off. Below is an example.
|
||||||
|
|
||||||
|
<p class='img'>
|
||||||
|
<img src='{{site_root}}/images/isy994/isy994_SwitchActionsExample.png' />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
The example program above shows how to control a legacy X10 device from Home
|
||||||
|
Assistant using an ISY controller.
|
||||||
|
|
||||||
|
### Creating Custom Sensors ###
|
||||||
|
|
||||||
|
Custom sensors can also be created using the Programs tab in the ISY
|
||||||
|
controller's Administrative Console. For programs, three different root level
|
||||||
|
folders are evaluated that are all handled a little differently inside of Home
|
||||||
|
Assistant.
|
||||||
|
|
||||||
|
* *HA.sensors* will have states of Open or Closed
|
||||||
|
* *HA.states* will have states of On or Off
|
||||||
|
* *HA.locations* will have states of Home or Away
|
||||||
|
|
||||||
|
To create a custom sensor, create a program under any of the three root
|
||||||
|
directories. The name of the program will be the name of the sensor. An example
|
||||||
|
below shows a location indicator setup.
|
||||||
|
|
||||||
|
<p class='img'>
|
||||||
|
<img src='{{site_root}}/images/isy994/isy994_SensorExample.png' />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
The program created only needs an IF clause. It will be evaluated to either
|
||||||
|
Open/On/Home when it returns True and Closed/Off/Away when it returns False. An
|
||||||
|
example is below.
|
||||||
|
|
||||||
|
<p class='img'>
|
||||||
|
<img src='{{site_root}}/images/isy994/isy994_SensorStatusExample.png' />
|
||||||
|
</p>
|
@ -61,3 +61,28 @@ The Discovery component is capable of setting up your components before firing t
|
|||||||
<p class='note warning'>
|
<p class='note warning'>
|
||||||
This option is currently limited to built-in components.
|
This option is currently limited to built-in components.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
### {% linkable_title Creating Entities %}
|
||||||
|
|
||||||
|
Home Assistant will call a function with the following signature to initialize
|
||||||
|
your new platform. This function must exist in the platform module you create.
|
||||||
|
|
||||||
|
```python
|
||||||
|
def setup_platform(hass, config, add_devices, discovery_info=None)
|
||||||
|
```
|
||||||
|
|
||||||
|
In this function, your platform should create the appropriate entities and
|
||||||
|
register them with the Home Assistant core. Entities are Home Assistant's
|
||||||
|
representation of lights, switches, sensors, etc. It is best practice for all
|
||||||
|
new entities to inherit the
|
||||||
|
[Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18).
|
||||||
|
This abstract class contains logic for integrating most standard features into
|
||||||
|
your entities, such as visibility, entity IDs, updates, and many more. That is
|
||||||
|
why it is best practice to reference the existing class.
|
||||||
|
|
||||||
|
A list of entities can be registered with Home Assitant using the *add_devices*
|
||||||
|
function that is provided as an input to *setup_platform*. Once entities are
|
||||||
|
registered with with Home Assistant their updates will be provided to the core
|
||||||
|
and the core will have control over them. For more information on how Entites
|
||||||
|
can be customized, take a look at the [Entity Abstract
|
||||||
|
Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18).
|
||||||
|
@ -55,17 +55,44 @@ Home Assistant will be able to automatically discover and configure any Google C
|
|||||||
|
|
||||||
Not all devices can be discovered, so if you have any of the following devices or services, please see their respective pages for installation instructions:
|
Not all devices can be discovered, so if you have any of the following devices or services, please see their respective pages for installation instructions:
|
||||||
|
|
||||||
|
* [Device tracking]({{site_root}}/components/device_tracker.html)
|
||||||
|
* [ISY994 controller]({{site_root}}/components/isy994.html)
|
||||||
* [Nest thermostat]({{site_root}}/components/thermostat.html)
|
* [Nest thermostat]({{site_root}}/components/thermostat.html)
|
||||||
* [Wink hub]({{site_root}}/components/wink.html)
|
|
||||||
* [TellStick](/components/tellstick.html)
|
|
||||||
* [PushBullet]({{site_root}}/components/notify.html)
|
* [PushBullet]({{site_root}}/components/notify.html)
|
||||||
* [PushOver](/blog/2015/03/22/release-notes/#pushover)
|
* [PushOver](/blog/2015/03/22/release-notes/#pushover)
|
||||||
* [SABnzbd](/blog/2015/03/22/release-notes/#sabnzbd)
|
* [SABnzbd](/blog/2015/03/22/release-notes/#sabnzbd)
|
||||||
* [Device tracking]({{site_root}}/components/device_tracker.html)
|
* [TellStick](/components/tellstick.html)
|
||||||
|
* [Wink hub]({{site_root}}/components/wink.html)
|
||||||
* [Add support for your own device or service]({{site_root}}/developers/add_new_platform.html)
|
* [Add support for your own device or service]({{site_root}}/developers/add_new_platform.html)
|
||||||
|
|
||||||
See the [components overview page](/components/) for a complete list of supported devices.
|
See the [components overview page](/components/) for a complete list of supported devices.
|
||||||
|
|
||||||
|
### {% linkable_title Customizing devices and services %}
|
||||||
|
|
||||||
|
By default, most of your devices will be visible on the Home Assistant States
|
||||||
|
page and have a default icon determined by their domain. You may find it
|
||||||
|
desireable to customize the look and feel of your front page by altering some
|
||||||
|
of these parameters.
|
||||||
|
|
||||||
|
By adding the following parameters to the *homeassistant* section of your
|
||||||
|
*configuration.yaml* file, you can customize the attributes of any state on
|
||||||
|
your front page.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
homeassistant:
|
||||||
|
|
||||||
|
# Add this to your existing configuration
|
||||||
|
|
||||||
|
customize:
|
||||||
|
SOME_ENTITY_ID:
|
||||||
|
hidden: true
|
||||||
|
entity_picture: http://URL.TO/PICTURE
|
||||||
|
friendly_name: SOME CUSTOM NAME
|
||||||
|
```
|
||||||
|
|
||||||
|
Entity IDs can be retrieved from the web interface by using the Set State page
|
||||||
|
in the Developer Tools.
|
||||||
|
|
||||||
### {% linkable_title Setting up Home Automation %}
|
### {% linkable_title Setting up Home Automation %}
|
||||||
|
|
||||||
When all your devices are set up it's time to put the cherry on the pie: automation. There are many ways to automate your home with Home Assistant so we have divided it into a couple of topics:
|
When all your devices are set up it's time to put the cherry on the pie: automation. There are many ways to automate your home with Home Assistant so we have divided it into a couple of topics:
|
||||||
|
BIN
source/images/isy994/isy994_SensorExample.png
Normal file
After Width: | Height: | Size: 2.8 KiB |
BIN
source/images/isy994/isy994_SensorStatusExample.png
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
source/images/isy994/isy994_SwitchActionsExample.png
Normal file
After Width: | Height: | Size: 22 KiB |
BIN
source/images/isy994/isy994_SwitchExample.png
Normal file
After Width: | Height: | Size: 4.2 KiB |
BIN
source/images/isy994/isy994_SwitchStatusExample.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
source/images/supported_brands/insteon.png
Normal file
After Width: | Height: | Size: 16 KiB |
BIN
source/images/supported_brands/universal_devices.png
Normal file
After Width: | Height: | Size: 16 KiB |
BIN
source/images/supported_brands/x10.gif
Normal file
After Width: | Height: | Size: 5.4 KiB |