diff --git a/source/_cookbook/python_component_basic_state.markdown b/source/_cookbook/python_component_basic_state.markdown index 3eca0d8bbab..7a95cec30ad 100644 --- a/source/_cookbook/python_component_basic_state.markdown +++ b/source/_cookbook/python_component_basic_state.markdown @@ -10,34 +10,116 @@ footer: true ha_category: Custom Python Component Examples --- -This is a simple hello world example to show the basics for setting a state. To use this example, create the file `/custom_components/hello_state.py` and copy the below example code. +This is a simple tutorial/example on how to write a component for [Home Assistant](https://home-assistant.io/). We will work on a component called "hello_state" to beginn with. 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. + +## {% linkable_title Component %} + +To get started, create the file `/custom_components/hello_state.py` and copy the below example code. ```python -# The domain of your component. Should be equal to the name of your component. +""" +Support for showing text in the frontend. + +For more details about this component, please refer to the documentation at +https://home-assistant.io/components/hello_state/ +""" +import logging + +_LOGGER = logging.getLogger(__name__) + DOMAIN = 'hello_state' +DEPENDENCIES = [] -CONF_NAME = 'name' -DEFAULT_NAME = 'World' +def setup(hass, config=None): + """Setup the Hello State component. """ + _LOGGER.info("The 'hello state' component is ready!") - -def setup(hass, config): - """Setup is called when Home Assistant is loading our component.""" - - # Get the name from the configuration. Use DEFAULT_NAME if no name provided. - name = config[DOMAIN].get(CONF_NAME, DEFAULT_NAME) - - # States are in the format DOMAIN.OBJECT_ID - hass.states.set('hello_state.hello', name) - - # Return boolean to indicate that initialization was successfully. return True ``` -Load the component by adding the following to your `configuration.yaml`: +1. In the file header we decided to add some details: 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 -# configuration.yaml entry hello_state: - # optional - name: Paulus ``` + +After a start or a restart of Home Assistant the component will create an entry in the log. + +```bash +16-03-12 14:16:42 INFO (MainThread) [custom_components.hello_state] The 'hello state' component is ready! +``` + +The next step is the introduction of configuration options. Most configuration details are coming out of the `configuration.yaml` file. To do that we need to update the `def setup()` method to accept configuration information and access the configuration variable in the `setup` method. + +More details about this topic can be found in the [User given configuration](/developers/creating_components/#config-user-given-configuration) section. + +```python +import logging + +_LOGGER = logging.getLogger(__name__) + +DOMAIN = 'hello_state' +DEPENDENCIES = [] + +CONF_TEXT = 'text' +DEFAULT_TEXT = 'No text!' + +def setup(hass, config): + """Setup the Hello State component. """ + # Get the text from the configuration. Use DEFAULT_TEXT if no name is provided. + text = config[DOMAIN].get(CONF_TEXT, DEFAULT_TEXT) + + # States are in the format DOMAIN.OBJECT_ID + hass.states.set('hello_state.Hello_State', text) + + return True +``` + +To add the latest feature of our component, update the entry in your `configuration.yaml` file. + +```yaml +information: + text: 'Hello, World!' +``` + +Thanks to `DEFAULT_TEXT` variable the component will launch even if no `text:` field is used in the `configuration.yaml` file. Quite often there are variables which are required. It's important to check if all mandatory configuration variables are provided. If not, the setup should fail. We will use the `validate_config` function as a helper to achive this. The next listing shows the essential parts. + +```python +from homeassistant.helpers import validate_config +[...] + if not validate_config(config, {DOMAIN: [CONF_TEXT]}, _LOGGER): + return False +``` + +If `text:` is missing, there will be a warning in the log file. + +```bash +16-03-12 14:37:37 ERROR (MainThread) [custom_components.hello_state] Missing required configuration items in hello_state: text +16-03-12 14:37:37 ERROR (MainThread) [homeassistant.bootstrap] component hello_state failed to initialize +``` + +After a start or a restart of Home Assistant the component will be visible in the frontend if the `configuration.yaml` file is up-to-date. + +

+ +

+ +To get your component included in the Home Assistant releases, follow the steps described in the [Submitting improvements](https://home-assistant.io/developers/#submitting-improvements) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request. +