diff --git a/source/developers/tutorial.markdown b/source/developers/tutorial.markdown new file mode 100644 index 00000000000..fb149a8b8a3 --- /dev/null +++ b/source/developers/tutorial.markdown @@ -0,0 +1,117 @@ +--- +layout: page +title: "Development tuorial" +description: "Tutorial about the first steps on Home Assistant development" +date: 2016-02-20 07:00 +sidebar: false +comments: false +sharing: true +footer: true +--- + +This is a simple tutorial on how to write a component for [Home Assistant](https://home-assistant.io/). We will work on a component called "information". The purpose of this component is to display a given text in the frontend. + +The setup of a development environment is described in the [Developers section](/developers/#starting-development) of the documentation. + +As a start, create a file `information.py` in your Git checkout of Home Assistant in the folder `homeassistant/component/`. + +```python +""" +homeassistant.components.information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The information component allows to show text in the frontend. + +For more details about this component, please refer to the documentation at +https://home-assistant.io/components/information/ +""" +import logging + +_LOGGER = logging.getLogger(__name__) + +DOMAIN = 'information' +DEPENDENCIES = [] + +def setup(hass, config=None): + """ Setup the Information component. """ + + _LOGGER.info("The 'information' component is ready!") + + return True +``` + +1. In the file header we decided to add some details. Like the path, a short description, and the link to the documentation. +2. We want to do some logging. This means that we import the Python logging module and create an alias. +3. The component name is equal to the domain name. +4. At the moment this component has no dependencies. For detail check [dependencies](/developers/creating_components/#dependencies) section. +5. The `setup` function will take care of the initialization of our component. + The component will only write a log message. Keep in mind for later that you have several options for the severity: + + - _LOGGER.info(msg) + - _LOGGER.warning(msg) + - _LOGGER.error(msg) + - _LOGGER.critical(msg) + - _LOGGER.exception(msg) + +7. We return `True` if everything is ok. + +Add the component to your `configuration.yaml` file. + +```yaml +information: +``` + +If you replace `_LOGGER.info("The 'information' component is ready!")` with or add + +```python +hass.states.set('information.Text', 'Info component') +``` + +Then the component will not be different to the sample included in the `config/custom_components` folder or shown as an [example](/cookbook/python_component_basic_state/). After a start or a restart of Home Assistant the component will be visible in the frontend. + +
+
+