-
diff --git a/source/developers/add_new_platform.markdown b/source/developers/add_new_platform.markdown
index 0e17acc7a0..73bf3e5367 100644
--- a/source/developers/add_new_platform.markdown
+++ b/source/developers/add_new_platform.markdown
@@ -9,16 +9,23 @@ sharing: true
footer: true
---
-Components that interact with devices are structured in core- and platform logic. This allows the same logic to be used for different platforms.
+Components that interact with devices are called Entity Components. They are structured in core- and platform logic. This allows the same logic to handle a light to be used by different brands.
For example, the built-in `switch` component consists of various platform in [`homeassistant/components/switch/`](https://github.com/home-assistant/home-assistant/tree/master/homeassistant/components/switch). The file `__init__.py` contains the core logic of all platform and the `vendor_name.py` files only the relevant platform code.
-If you are planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add.
+If you are planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add:
+
+ - [Example sensor platform](/developers/platform_example_sensor): hello world of platforms.
+ - [Example light platform](/developers/platform_example_light): showing best practices.
### {% linkable_title Interfacing with devices %}
One of the rules for Home Assistant is that platform logic should never interface directly with devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share code with the Python community and we can keep the project maintainable.
+To integrate the third-party library you create an Entity class for your device. Entities are Home Assistant's representation of lights, switches, sensors, etc. and are derived from the [Entity Abstract Class](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py). This abstract class contains logic for integrating most standard features into your entities, such as visibility, entity IDs, updates, and much more.
+
+### {% linkable_title Requirements and dependencies %}
+
Platforms can specify dependencies and requirements the same way as a component does.
```python
@@ -26,75 +33,3 @@ REQUIREMENTS = ['some-package==2.0.0', 'some-other-package==2.5.0']
DEPENDENCIES = ['mqtt']
```
-### {% linkable_title Platform example %}
-
-
-
-Entities are Home Assistant's representation of lights, switches, sensors, etc. and are derived from the [Entity Abstract Class](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py). This abstract class contains logic for integrating most standard features into your entities, such as visibility, entity IDs, updates, and many more.
-
-This example is for adding support for the imaginary Awesome Lights.
-
-```python
-import logging
-
-# Import the device class from the component that you want to support
-from homeassistant.components.light import Light
-from homeassistant.const import CONF_HOST, CONF_USERNAME, CONF_PASSWORD
-
-# Home Assistant depends on 3rd party packages for API specific code.
-REQUIREMENTS = ['awesome_lights==1.2.3']
-
-_LOGGER = logging.getLogger(__name__)
-
-
-setup_platform(hass, config, add_devices, discovery_info=None):
- """Initialize Awesome Light platform."""
- import awesomelights
-
- # Validate passed in config
- host = config.get(CONF_HOST)
- username = config.get(CONF_USERNAME)
- password = config.get(CONF_PASSWORD)
-
- if host is None or username is None or password is None:
- _LOGGER.error('Invalid config. Expected %s, %s and %s',
- CONF_HOST, CONF_USERNAME, CONF_PASSWORD)
- return False
-
- # Setup connection with devices/cloud
- hub = awesomelights.Hub(host, username, password)
-
- # Verify that passed in config works
- if not hub.is_valid_login():
- _LOGGER.error('Could not connect to AwesomeLight hub')
- return False
-
- # Add devices
- add_devices(AwesomeLight(light) for light in hub.lights())
-
-class AwesomeLight(Light):
- """Represents an AwesomeLight in Home Assistant."""
-
- def __init__(self, light):
- """Initialize an AwesomeLight."""
- self._light = light
-
- def update(self):
- """Fetch new state data for this light.
-
- This is the only method that should fetch new data for Home Assitant.
- """
- self._light.update()
-
- def brightness(self):
- """Brightness of the light.
-
- This method is optional. Removing it indicates to Home Assistant
- that brightness is not supported for this light.
- """
- return self._light.brightness
-
- def is_on(self):
- """If light is on."""
- return self._light.is_on()
-```
diff --git a/source/developers/architecture_components.markdown b/source/developers/architecture_components.markdown
index a2f7f056be..ae8b36320d 100644
--- a/source/developers/architecture_components.markdown
+++ b/source/developers/architecture_components.markdown
@@ -11,6 +11,11 @@ footer: true
Home Assistant can be extended by **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/).
+
+
+Diagram showing interaction between components and the Home Assistant core.
+
[See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L229). | +| `hass.services` | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L568). | + +### {% linkable_title config: User given configuration. %} + +The `config` parameter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration. + +If your configuration file contains the following lines: + +```yaml +example: + host: paulusschoutsen.nl +``` + +Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`. diff --git a/source/developers/component_loading.markdown b/source/developers/component_loading.markdown new file mode 100644 index 0000000000..35b50ee975 --- /dev/null +++ b/source/developers/component_loading.markdown @@ -0,0 +1,25 @@ +--- +layout: page +title: "Loading your components" +description: "Instructions how to get your component loaded by Home Assistant." +date: 2016-04-16 13:32 +sidebar: true +comments: false +sharing: true +footer: true +--- + +A component will be loaded on start if a section (ie. `light:`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths: + + * `
+You can override a built-in component by having a component with the same name in your config/custom_components folder. This is not recommended and will probably break things!
+
+Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/.
+
-You can override a built-in component by having a component with the same name in your config/custom_components folder. This is not recommended and will probably break things!
-
-Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/.
-
[See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L229). | -| `hass.services` | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L568). | - -### {% linkable_title `config`: User given configuration. %} - -The `config` parameter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration. - -If your configuration file contains the following lines: - -```yaml -example: - host: paulusschoutsen.nl -``` - -Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`. - -## {% linkable_title Responding to events %} - -Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in [helper methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/event.py). Examples are `track_state_change`, `track_point_in_time`, `track_time_change`. +For more examples, see the [Custom Python Component Examples](/cookbook/#custom-python-component-examples) on our examples page. diff --git a/source/developers/platform_example_light.markdown b/source/developers/platform_example_light.markdown new file mode 100644 index 0000000000..b80e966907 --- /dev/null +++ b/source/developers/platform_example_light.markdown @@ -0,0 +1,77 @@ +--- +layout: page +title: "Example light platform" +description: "Minimum implementation of a Home Assistant platform." +date: 2016-04-16 14:24 -07:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +This example is for adding support for the imaginary Awesome Lights. It shows the different best practices for developing a platform. + +```python +import logging + +# Import the device class from the component that you want to support +from homeassistant.components.light import Light +from homeassistant.const import CONF_HOST, CONF_USERNAME, CONF_PASSWORD + +# Home Assistant depends on 3rd party packages for API specific code. +REQUIREMENTS = ['awesome_lights==1.2.3'] + +_LOGGER = logging.getLogger(__name__) + + +setup_platform(hass, config, add_devices, discovery_info=None): + """Initialize Awesome Light platform.""" + import awesomelights + + # Validate passed in config + host = config.get(CONF_HOST) + username = config.get(CONF_USERNAME) + password = config.get(CONF_PASSWORD) + + if host is None or username is None or password is None: + _LOGGER.error('Invalid config. Expected %s, %s and %s', + CONF_HOST, CONF_USERNAME, CONF_PASSWORD) + return False + + # Setup connection with devices/cloud + hub = awesomelights.Hub(host, username, password) + + # Verify that passed in config works + if not hub.is_valid_login(): + _LOGGER.error('Could not connect to AwesomeLight hub') + return False + + # Add devices + add_devices(AwesomeLight(light) for light in hub.lights()) + +class AwesomeLight(Light): + """Represents an AwesomeLight in Home Assistant.""" + + def __init__(self, light): + """Initialize an AwesomeLight.""" + self._light = light + + def update(self): + """Fetch new state data for this light. + + This is the only method that should fetch new data for Home Assitant. + """ + self._light.update() + + def brightness(self): + """Brightness of the light. + + This method is optional. Removing it indicates to Home Assistant + that brightness is not supported for this light. + """ + return self._light.brightness + + def is_on(self): + """If light is on.""" + return self._light.is_on() +``` diff --git a/source/developers/platform_example_sensor.markdown b/source/developers/platform_example_sensor.markdown new file mode 100644 index 0000000000..6519ced0ba --- /dev/null +++ b/source/developers/platform_example_sensor.markdown @@ -0,0 +1,49 @@ +--- +layout: page +title: "Example sensor platform" +description: "Minimum implementation of a Home Assistant platform." +date: 2016-04-16 14:24 -07:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +This is a minimum implementation of a platform for the sensor component. + +### {% linkable_title Installation %} + +Copy the code below and create it as a file in `