Merge pull request #5 from automicus/master

Documentation for ISY994 Platform and Entity ABC

source/components/index.markdown

@@ -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

source/components/isy994.markdown

@@ -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>

source/developers/add_new_platform.markdown

@@ -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).

source/getting-started/configuration.markdown

@@ -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: