home-assistant.io/source/_cookbook/python_component_basic_state.markdown

layout	title	description	date	sidebar	comments	sharing	footer	ha_category
page	Basic State Setting Example		2016-02-07 12:13	true	false	true	true	Custom Python Component Examples

This is a simple tutorial/example on how to write a component for Home Assistant. We will work on a component called "hello_state" to begin 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 of the documentation.

{% linkable_title Component %}

To get started, create the file <config dir>/custom_components/hello_state.py and copy the below example code.

"""
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 = []

def setup(hass, config=None):
    """Setup the Hello State component. """
    _LOGGER.info("The 'hello state' component is ready!")

    return True

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 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)

6. We return True if everything is ok.

Add the component to your configuration.yaml file.

hello_state:

After a start or a restart of Home Assistant the component will create an entry in the log.

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 section.

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.

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.

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.

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 section. Basically you only need to move your component in the homeassistant/component/ directory of your fork and create a Pull Request.