jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

More tweaks to developer docs

Browse source
This commit is contained in:
Paulus Schoutsen 2016-04-16 23:00:45 -07:00
parent c5bc6c0cfb
commit d8c8cf4c8d
13 changed files with 272 additions and 149 deletions
Download patch file Download diff file Expand all files Collapse all files

83
source/developers/add_new_platform.markdown
View file

@ -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()
```