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>
|
||||
</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>
|
||||
|
||||
<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
|
||||
| ---- | -----------
|
||||
@ -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/vera.png' class='brand' />](/components/vera.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 %}
|
||||
|
||||
@ -158,6 +180,11 @@ Home Assistant integrates with a variety of third party Home Automation hubs and
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p class='note'>
|
||||
Support for these services is provided by the Home Assistant community and not
|
||||
the service providers.
|
||||
</p>
|
||||
|
||||
## {% linkable_title Automation %}
|
||||
|
||||
| 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'>
|
||||
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 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:
|
||||
|
||||
* [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 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 %}
|
||||
|
||||
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 |