-
diff --git a/source/developers/component_deps_and_reqs.markdown b/source/developers/component_deps_and_reqs.markdown
index 3a5d847baf0..039948ea7df 100644
--- a/source/developers/component_deps_and_reqs.markdown
+++ b/source/developers/component_deps_and_reqs.markdown
@@ -11,7 +11,7 @@ footer: true
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
+## {% linkable_title Dependencies %}
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 an MQTT broker. If Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor component.
@@ -19,7 +19,7 @@ Dependencies are other Home Assistant components that should be setup before the
DEPENDENCIES = ['mqtt']
```
-## Requirements
+## {% linkable_title Requirements %}
Requirements are Python libraries that you would normally install using `pip` for your component. Home Assistant will try to install the requirements into the `deps` subdirectory of the Home Assistant configuration directory (`.home-assistant` by default) or verify it is already installed at startup. If that fails, the component will fail to load.
diff --git a/source/developers/component_initialization.markdown b/source/developers/component_initialization.markdown
deleted file mode 100644
index 6f6a5b31587..00000000000
--- a/source/developers/component_initialization.markdown
+++ /dev/null
@@ -1,36 +0,0 @@
----
-layout: page
-title: "Initializing your components"
-description: "Instructions how to handle initialization of your component."
-date: 2016-04-16 13:32
-sidebar: true
-comments: false
-sharing: true
-footer: true
----
-
-After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it.
-
-### {% linkable_title hass: the Home Assistant instance %}
-
-The Home Assistant instance contains four objects to help you interact with the system.
-
-| Object | Description |
-| ------ | ----------- |
-| `hass.config` | This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. [Details](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L687)
-| `hass.states` | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L434). |
-| `hass.bus` | This is the EventBus. It allows you to trigger and listen for events.
[See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L229). | -| `hass.services` | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L568). | - -### {% linkable_title config: User given configuration. %} - -The `config` parameter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration. - -If your configuration file contains the following lines: - -```yaml -example: - host: paulusschoutsen.nl -``` - -Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`. diff --git a/source/developers/development_101.markdown b/source/developers/development_101.markdown new file mode 100644 index 00000000000..851888479f2 --- /dev/null +++ b/source/developers/development_101.markdown @@ -0,0 +1,38 @@ +--- +layout: page +title: "Development 101" +description: "Introduction to the basics of Home Assistant." +date: 2017-05-13 05:40:00 +0000 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The goal of development 101 is to get you familiar with the basics of developing for Home Assistant. Before we start, please make sure you familiarize yourself with the [architecture]. + +To get our code running inside Home Assistant we're going to create a custom component. The first step is to locate your config folder. You can find the path to your config folder by opening the Home Assistant frontend, click on the
. It's the path after the text "Path to configuration.yaml".
+
+Inside your configuration directory create a new folder called `custom_components`. It might be that one already exists, that's fine too. This is the folder that Home Assistant will look at when looking for custom code.
+
++The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version. +
+ +To verify that everything is working correctly, let's create a small Hello World component. To do so, create a file called `hello_world.py` in your custom components folder. Copy paste the following content to it: + +```python +# The domain of your component. Equal to the filename of your component. +DOMAIN = "hello_world" + + +def setup(hass, config): + """Setup the hello_world component.""" + # States are in the format DOMAIN.OBJECT_ID. + hass.states.set('hello_world.Hello_World', 'Works!') + + # Return boolean to indicate that initialization was successfully. + return True +``` + +[architecture]: /developers/architecture/ diff --git a/source/developers/development_config.markdown b/source/developers/development_config.markdown new file mode 100644 index 00000000000..56382ecb615 --- /dev/null +++ b/source/developers/development_config.markdown @@ -0,0 +1,35 @@ +--- +layout: page +title: "Using Config" +description: "Introduction to the Config object in Home Assistant." +date: 2017-05-13 05:40:00 +0000 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Based on where you are in the code, `config` can mean various things. + +### {% linkable_title On the hass object %} + +On the hass object is an instance of the Config class. The Config class contains the users preferred units, the path to the config directory and which components are loaded. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.Config) + +### {% linkable_title Config passed into component setup %} + +The `config` parameter passed to a component setup is a dictionary containing all of the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration. + +The object will have already been validated using your `CONFIG_SCHEMA` or `PLATFORM_SCHEMA` if available. If you have defined a `PLATFORM_SCHEMA`, all references to your component (ie `light 2:` etc) will have been changed to be accessible as a list under `config[DOMAIN]`. + +If your configuration file contains the following lines: + +```yaml +example: + host: paulusschoutsen.nl +``` + +Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`. + +### {% linkable_title Passed into platform setup %} + +The `config` parameter passed to a platform setup function is only the config for that specific platform. diff --git a/source/developers/development_events.markdown b/source/developers/development_events.markdown new file mode 100644 index 00000000000..2c80e54d7ef --- /dev/null +++ b/source/developers/development_events.markdown @@ -0,0 +1,61 @@ +--- +layout: page +title: "Using Events" +description: "Introduction to using events in Home Assistant." +date: 2017-05-13 05:40:00 +0000 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The core of Home Assistant is driven by events. That means that if you want to respond to something happening, you'll have to respond to events. Most of the times you won't interact directly with the event system but use one of the [event listener helpers][helpers]. + +The event system is very flexible. There are no limitations on the event type, as long as it's a string. Each event can contain data. The data is a dictionary that can contain any data as long as it's JSON serializable. This means that you can use number, string, dictionary and list. + +[List of events that Home Assistant fires.][object] + +### {% linkable_title Firing events %} + +To fire an event, you have to interact with the event bus. The event bus is available on the Home Assistant instance as `hass.bus`. + +Example component that will fire an event when loaded. + +```python +DOMAIN = 'hello_event' + +def setup(hass, config): + """Set up is called when Home Assistant is loading our component.""" + + # Fire event my_cool_event with event data answer=42 + hass.bus.fire('my_cool_event', { + 'answer': 42 + }) +``` + +### {% linkable_title Listening to events %} + +Most of the times you'll not be firing events but instead listen to events. For example, the state change of an entity is broadcasted as an event. + +```python +DOMAIN = 'hello_event' + +def setup(hass, config): + """Set up is called when Home Assistant is loading our component.""" + count = 0 + + # Listener to handle fired events + def handle_event(event): + count += 1 + print('Total events received:', count) + + # Listen for when my_cool_event is fired + hass.bus.listen('my_cool_event', handle_event) +``` + +#### {% linkable_title Helpers %} + +Home Assistant comes with a lot of bundled helpers to listen to specific types of event. There are helpers to track a point in time, to track a time interval, a state change or the sun set. [See available methods.][helpers] + +[helpers]: https://dev-docs.home-assistant.io/en/master/api/helpers.html#module-homeassistant.helpers.event +[object]: /docs/configuration/events/ diff --git a/source/developers/development_hass_object.markdown b/source/developers/development_hass_object.markdown new file mode 100644 index 00000000000..5ab773a63a9 --- /dev/null +++ b/source/developers/development_hass_object.markdown @@ -0,0 +1,37 @@ +--- +layout: page +title: "Hass object" +description: "Introduction to developing with the hass object." +date: 2016-04-16 13:32 +sidebar: true +comments: false +sharing: true +footer: true +--- + +While developing Home Assistant you will see a variable that is everywhere: `hass`. This is the Home Assistant instance that will give you access to all the various parts of the system. + +### {% linkable_title The `hass` object %} + +The Home Assistant instance contains four objects to help you interact with the system. + +| Object | Description | +| ------ | ----------- | +| `hass` | This is the instance of Home Assistant. Allows starting, stopping and enqueing new jobs. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.HomeAssistant) +| `hass.config` | This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.Config) +| `hass.states` | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.StateMachine). | +| `hass.bus` | This is the EventBus. It allows you to trigger and listen for events. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.EventBus). | +| `hass.services` | This is the ServiceRegistry. It allows you to register services. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.ServiceRegistry). | + +### {% linkable_title Where to find `hass` %} + +Depending on what you're writing, there are different ways the `hass` object is made available. + +**Component**+Passed into `setup(hass, config)` or `async_setup(hass, config)`. + +**Platform**
+Passed into `setup_platform(hass, config, add_devices, discovery_info=None)` or `async_setup_platform(hass, config, async_add_devices, discovery_info=None)`. + +**Entity**
+Available as `self.hass` once the entity has been added via the `add_devices` callback inside a platform. diff --git a/source/_cookbook/python_component_basic_service.markdown b/source/developers/development_services.markdown similarity index 93% rename from source/_cookbook/python_component_basic_service.markdown rename to source/developers/development_services.markdown index 178750bec52..1aa11397ede 100644 --- a/source/_cookbook/python_component_basic_service.markdown +++ b/source/developers/development_services.markdown @@ -1,13 +1,12 @@ --- layout: page -title: "Basic Service Example" -description: "" -date: 2016-02-07 12:13 +title: "Using Services" +description: "Introduction to services in Home Assistant." +date: 2017-05-13 05:40:00 +0000 sidebar: true comments: false sharing: true footer: true -ha_category: Custom Python Component Examples --- This is a simple "hello world" example to show the basics of registering a service. To use this example, create the file `