From 14b886da62d97dd7d617cedc3699127ff446920a Mon Sep 17 00:00:00 2001 From: Johann Kellerman Date: Tue, 10 Jan 2017 21:11:11 +0200 Subject: [PATCH 1/5] Create packages --- source/_topics/packages | 86 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 source/_topics/packages diff --git a/source/_topics/packages b/source/_topics/packages new file mode 100644 index 00000000000..de83c1f4c2d --- /dev/null +++ b/source/_topics/packages @@ -0,0 +1,86 @@ +--- +layout: page +title: "Packages" +description: "Describes all there is to know about configuration packages in Home Assistant." +date: 2017-01-10 20:00 +0200 +sidebar: false +comments: false +sharing: true +footer: true +--- + +## {% linkable_title About } + +Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/getting-started/devices) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/topics/splitting_configuration). + +Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a packages name (no spaces, all lower case) followed by a dictionary with the package config. For example, package `pack_1` would be created as: + +```yaml +homeassistant: + ... + packages: + pack_1: + ...package config here... +``` + +The package configuration can include: `switch`, `light`, `automation`, `groups` or the majority of the Home Assistant components. + +It can be specified inline, or in a seperate yaml file using `!include` + +Inline example, main `configuration.yaml`: + +```yaml +homeassistant: + ... + packages: + pack_1: + switch: + - platform: rest + ... + light: + - platform: rpi + ... +``` + +Include example, main `configuration.yaml`: +```yaml +homeassistant: + ... + packages: + pack_1: !include my_package.yaml +``` +The file `my_package.yaml` contains the "top-level" configuration: +``` +switch: + - platform: rest + ... +light: + - platform: rpi + ... +``` + +There are some rules for packages that will be merged: + +1. Component names may only use the basic form (e.g. `switch` and `switch 1` or `switch aa` is not accepted) +2. Platform based components (`light`, `switch`, etc) can always be merged +3. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file (`input_boolean`, `group`) +4. Any component that is not a platform [2], or dictionaries with Entity ID keys [3] cannot be merged and can only occur once between all packages and the main config + +An example travel time package can be found [here](/cookbooks/travel_time) + +

+Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the component name. +

+ + +### {% linkable_title Create a packages folder } + +One way to organise packages would be to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a yaml file. This entry in your `configuration.yaml` will load all packages: + +```yaml +homeassistant: + packages: !include_dir_named packages +``` + +This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames. +See the documentation about [splitting the configuration](/topics/splitting_configuration) for more information about `!include_dir_named` and other include statements that might be helpful. From cac77d8f63b286e3859da9b489f3c9b03153ecad Mon Sep 17 00:00:00 2001 From: Johann Kellerman Date: Tue, 10 Jan 2017 21:16:52 +0200 Subject: [PATCH 2/5] Create packages.markdown --- source/_topics/packages.markdown | 85 ++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 source/_topics/packages.markdown diff --git a/source/_topics/packages.markdown b/source/_topics/packages.markdown new file mode 100644 index 00000000000..0c00417f474 --- /dev/null +++ b/source/_topics/packages.markdown @@ -0,0 +1,85 @@ +--- +layout: page +title: "Packages" +description: "Describes all there is to know about configuration packages in Home Assistant." +date: 2017-01-10 20:00 +0200 +sidebar: false +comments: false +sharing: true +footer: true +--- + +## {% linkable_title About } + +Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/getting-started/devices) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/topics/splitting_configuration). + +Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a packages name (no spaces, all lower case) followed by a dictionary with the package config. For example, package `pack_1` would be created as: + +```yaml +homeassistant: + ... + packages: + pack_1: + ...package config here... +``` + +The package configuration can include: `switch`, `light`, `automation`, `groups` or the majority of the Home Assistant components. + +It can be specified inline, or in a seperate yaml file using `!include` + +Inline example, main `configuration.yaml`: + +```yaml +homeassistant: + ... + packages: + pack_1: + switch: + - platform: rest + ... + light: + - platform: rpi + ... +``` + +Include example, main `configuration.yaml`: +```yaml +homeassistant: + ... + packages: + pack_1: !include my_package.yaml +``` +The file `my_package.yaml` contains the "top-level" configuration: +``` +switch: + - platform: rest + ... +light: + - platform: rpi + ... +``` + +There are some rules for packages that will be merged: + +1. Component names may only use the basic form (e.g. `switch` and `switch 1` or `switch aa` is not accepted) +2. Platform based components (`light`, `switch`, etc) can always be merged +3. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file (`input_boolean`, `group`) +4. Any component that is not a platform [2], or dictionaries with Entity ID keys [3] cannot be merged and can only occur once between all packages and the main config + + +

+Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the component name. +

+ + +### {% linkable_title Create a packages folder } + +One way to organise packages would be to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a yaml file. This entry in your `configuration.yaml` will load all packages: + +```yaml +homeassistant: + packages: !include_dir_named packages +``` + +This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames. +See the documentation about [splitting the configuration](/topics/splitting_configuration) for more information about `!include_dir_named` and other include statements that might be helpful. From 5ff9fbd8b77d8562a07bdc637bc81114a6d932d4 Mon Sep 17 00:00:00 2001 From: Johann Kellerman Date: Tue, 10 Jan 2017 21:17:23 +0200 Subject: [PATCH 3/5] Delete packages --- source/_topics/packages | 86 ----------------------------------------- 1 file changed, 86 deletions(-) delete mode 100644 source/_topics/packages diff --git a/source/_topics/packages b/source/_topics/packages deleted file mode 100644 index de83c1f4c2d..00000000000 --- a/source/_topics/packages +++ /dev/null @@ -1,86 +0,0 @@ ---- -layout: page -title: "Packages" -description: "Describes all there is to know about configuration packages in Home Assistant." -date: 2017-01-10 20:00 +0200 -sidebar: false -comments: false -sharing: true -footer: true ---- - -## {% linkable_title About } - -Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/getting-started/devices) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/topics/splitting_configuration). - -Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a packages name (no spaces, all lower case) followed by a dictionary with the package config. For example, package `pack_1` would be created as: - -```yaml -homeassistant: - ... - packages: - pack_1: - ...package config here... -``` - -The package configuration can include: `switch`, `light`, `automation`, `groups` or the majority of the Home Assistant components. - -It can be specified inline, or in a seperate yaml file using `!include` - -Inline example, main `configuration.yaml`: - -```yaml -homeassistant: - ... - packages: - pack_1: - switch: - - platform: rest - ... - light: - - platform: rpi - ... -``` - -Include example, main `configuration.yaml`: -```yaml -homeassistant: - ... - packages: - pack_1: !include my_package.yaml -``` -The file `my_package.yaml` contains the "top-level" configuration: -``` -switch: - - platform: rest - ... -light: - - platform: rpi - ... -``` - -There are some rules for packages that will be merged: - -1. Component names may only use the basic form (e.g. `switch` and `switch 1` or `switch aa` is not accepted) -2. Platform based components (`light`, `switch`, etc) can always be merged -3. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file (`input_boolean`, `group`) -4. Any component that is not a platform [2], or dictionaries with Entity ID keys [3] cannot be merged and can only occur once between all packages and the main config - -An example travel time package can be found [here](/cookbooks/travel_time) - -

-Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the component name. -

- - -### {% linkable_title Create a packages folder } - -One way to organise packages would be to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a yaml file. This entry in your `configuration.yaml` will load all packages: - -```yaml -homeassistant: - packages: !include_dir_named packages -``` - -This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames. -See the documentation about [splitting the configuration](/topics/splitting_configuration) for more information about `!include_dir_named` and other include statements that might be helpful. From 004fffd839395023d85375781b294731d3f1921f Mon Sep 17 00:00:00 2001 From: Johann Kellerman Date: Tue, 10 Jan 2017 21:43:04 +0200 Subject: [PATCH 4/5] Update packages.markdown --- source/_topics/packages.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_topics/packages.markdown b/source/_topics/packages.markdown index 0c00417f474..befa1b8d12f 100644 --- a/source/_topics/packages.markdown +++ b/source/_topics/packages.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -## {% linkable_title About } +## {% linkable_title About %} Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/getting-started/devices) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/topics/splitting_configuration). @@ -72,7 +72,7 @@ Components inside packages can only specify platform entries using configuration

-### {% linkable_title Create a packages folder } +### {% linkable_title Create a packages folder %} One way to organise packages would be to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a yaml file. This entry in your `configuration.yaml` will load all packages: From 0ad85bf3091bddbbe17c6372ffb1035b37e44a2c Mon Sep 17 00:00:00 2001 From: Johann Kellerman Date: Tue, 10 Jan 2017 22:47:30 +0200 Subject: [PATCH 5/5] Update packages.markdown --- source/_topics/packages.markdown | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/source/_topics/packages.markdown b/source/_topics/packages.markdown index befa1b8d12f..94d58f294a3 100644 --- a/source/_topics/packages.markdown +++ b/source/_topics/packages.markdown @@ -63,7 +63,14 @@ There are some rules for packages that will be merged: 1. Component names may only use the basic form (e.g. `switch` and `switch 1` or `switch aa` is not accepted) 2. Platform based components (`light`, `switch`, etc) can always be merged -3. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file (`input_boolean`, `group`) +3. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file. + + For example if we have the following in the main config. You are not allowed to re-use "my_input" again for `input_boolean` in a package: + + ```yaml + input_boolean: + my_input: + ``` 4. Any component that is not a platform [2], or dictionaries with Entity ID keys [3] cannot be merged and can only occur once between all packages and the main config