Added documentation about ISY994 platform. Also added documentation about creating entities by using the Entity base class.

This commit is contained in:
Ryan Kraus 2015-04-24 23:13:32 -04:00
parent 66db921c8e
commit 5f84b4ad66
10 changed files with 189 additions and 3 deletions

View File

@ -88,8 +88,19 @@ 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>
</tr>
<tr>
<td><a href='/components/isy994.html'><img src='/images/supported_brands/universal_devices.png' class='brand overview' /></a></td>
<td><a href='/components/isy994.html'>Insteon and X10 Devices</a></td>
<td>ISY994 controller for Insteon and X10 devices as well as create custom switches and sensors.</td>
</tr>
</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 %}
| Type | Description
| ---- | -----------
@ -105,6 +116,10 @@ Home Assistant integrates with a variety of third party Home Automation hubs and
[<img src='/images/supported_brands/vera.png' class='brand' />](/components/vera.html)
[<img src='/images/supported_brands/wink.png' class='brand' />](/components/wink.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 %}

View 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
treated as 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 treat 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>

View File

@ -61,3 +61,29 @@ The Discovery component is capable of setting up your components before firing t
<p class='note warning'>
This option is currently limited to built-in components.
</p>
### {% linkable_title Creating Entities %}
Home Assistant will call a function with the following signature to initialize
your new component. This function must exist in the component module you
create.
```python
def setup_platform(hass, config, add_devices, discovery_info=None)
```
In this function, your component 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).

View File

@ -55,17 +55,42 @@ 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:
* [Device tracking]({{site_root}}/components/device_tracker.html)
* [ISY994 controller]({{site_root}}/components/isy994.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)
* [PushOver](/blog/2015/03/22/release-notes/#pushover)
* [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)
See the [components overview page](/components/) for a complete list of supported devices.
### {% linkable_title Hiding devices and services %}
By default, most of your devices will be visible on the Home Assistant Sates
page. You may find it desireable to hide some of these devices from the default
view. Some components may also hide some entities by default. You also have the
ability to show these previously hidden entities.
Most enties on the homepage may be hidden or shown in the configuration file by
adding the following lines to the homeassistant section:
```yaml
homeassistant:
# Add this to your existing configuration
visibility:
entity_id: hide
entity_id: show
```
Replace entity_id with the ID for the entity that you would like to either show
or hide. 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 %}
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:

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB