mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 09:17:06 +00:00
Update developer documentation
This commit is contained in:
parent
fe2b626446
commit
81f2e68af4
@ -21,11 +21,38 @@ For example, the built-in `switch` component consists of the following files in
|
||||
|
||||
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.
|
||||
|
||||
<p class='note'>
|
||||
Platform logic should not interface directly with the devices but use a third-party Python 3 library that speaks the actual API.
|
||||
</p>
|
||||
### {% 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.
|
||||
|
||||
Platforms can specify dependencies and requirements the same way as a component does. Please see
|
||||
[the component page](/developers/creating_components.html#dependencies) for more information.
|
||||
|
||||
### {% 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. and are derived from the
|
||||
[Entity Abstract Class](https://github.com/balloob/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.
|
||||
|
||||
A list of entities can be registered with Home Assistant 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 Entities
|
||||
can be customized, take a look at the [Entity Abstract
|
||||
Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18).
|
||||
|
||||
<a name='discovery'></a>
|
||||
## {% linkable_title Allowing your platform to be discovered %}
|
||||
|
||||
Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event.
|
||||
@ -61,28 +88,3 @@ 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 Assistant 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 Entities
|
||||
can be customized, take a look at the [Entity Abstract
|
||||
Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18).
|
||||
|
@ -42,6 +42,22 @@ You can override a built-in component by having a component with the same name i
|
||||
Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the <code>config</code> folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
|
||||
</p>
|
||||
|
||||
## {% linkable_title Dependencies %}
|
||||
|
||||
Home Assistant allows components and platforms to specify their dependencies and requirements using the variables
|
||||
`DEPENDENCIES` and `REQUIREMENTS`. Both are lists that contain strings.
|
||||
|
||||
Dependencies are other Home Assistant components that should be setup before the platform is loaded.
|
||||
An example is the MQTT sensor component, which requires an active connection to a MQTT broker. If
|
||||
Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor
|
||||
component.
|
||||
|
||||
Requirements are Python libraries that you would normally install using `pip`. Each entry in a
|
||||
requirement list is a pip compatible string. For example, the media player Cast platform depends
|
||||
on the Python package PyChromecast thus `REQUIREMENTS = ['pychromecast==0.6.12']`. If Home
|
||||
Assistant is unable to install the package or verify it is installed, the component will fail to
|
||||
load.
|
||||
|
||||
## {% linkable_title Initializing components %}
|
||||
|
||||
After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. The following parameters are passed in:
|
||||
|
@ -9,9 +9,49 @@ sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Home Assistant is build from the ground-up to be easily extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Webcomponents)](https://www.polymer-project.org/) for the frontend.
|
||||
Home Assistant is build from the ground-up to be easily extensible by other developers using
|
||||
components. It uses [Python 3](https://www.python.org/) for the backend and
|
||||
[Polymer (Webcomponents)](https://www.polymer-project.org/) for the frontend.
|
||||
|
||||
Home Assistant is open-source and MIT licensed. The source can be found here:
|
||||
|
||||
- [home-assistant](https://github.com/home-assistant) - Python server-backend
|
||||
- [home-assistant-js](https://github.com/home-assistant-js) - javascript-backend powering the client
|
||||
- [home-assistant-polymer](https://github.com/home-assistant-polymer) - Polymer UI
|
||||
|
||||
### {% linkable_title Starting development %}
|
||||
|
||||
You will need to setup a development environment if you want to start developing a new feature or
|
||||
component for Home Assistant.
|
||||
|
||||
1. Clone the Home Assistant repository:<br>
|
||||
`git clone https://github.com/balloob/home-assistant.git`
|
||||
2. Setup your computer for development:<br>
|
||||
`python3 setup.py develop`
|
||||
|
||||
After following these steps, running `hass` will invoke your local installation.
|
||||
|
||||
### {% linkable_title Submitting improvements %}
|
||||
|
||||
Improvements to Home Assistant should be submitted one feature at a time using Github pull
|
||||
requests.
|
||||
|
||||
1. Go to [the Home Assistant repository](https://github.com/balloob/home-assistant)
|
||||
and click fork in the top right.
|
||||
2. Follow steps in the previous section but with your forked repository.
|
||||
3. Create a new branch to hold your changes<br>
|
||||
`git checkout -b some-feature`
|
||||
4. Make the changes you want
|
||||
5. Commit the changes<br>
|
||||
`git add .`<br>
|
||||
`git commit -m "Added some-feature"`
|
||||
6. Push your commited changes back to your fork on Github<br>
|
||||
`git push origin HEAD`
|
||||
7. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your
|
||||
pull request.
|
||||
|
||||
### {% linkable_title Further reading %}
|
||||
|
||||
For further reading, see:
|
||||
<ul>
|
||||
<li><a href="{{ root_url }}/developers/architecture.html">
|
||||
Home Assistant Architecture
|
||||
|
Loading…
x
Reference in New Issue
Block a user