From 49132570dd215cef8e4f5f7979e5eb13964db218 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 30 Sep 2022 08:39:15 +0200 Subject: [PATCH] Document brand files (#1475) * Document brand files * Update docs/creating_integration_brand.md Co-authored-by: Martin Hjelmare Co-authored-by: Paulus Schoutsen Co-authored-by: Martin Hjelmare --- docs/creating_integration_brand.md | 56 ++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 57 insertions(+) create mode 100644 docs/creating_integration_brand.md diff --git a/docs/creating_integration_brand.md b/docs/creating_integration_brand.md new file mode 100644 index 00000000..b09a1cd0 --- /dev/null +++ b/docs/creating_integration_brand.md @@ -0,0 +1,56 @@ +--- +title: "Grouping integrations by brand" +sidebar_label: "Grouping integrations by brand" +--- + +A commercial brand may have several integrations which provide support for different offerings under that brand. Also, a brand may offer devices which comply with an IoT standard, for example Zigbee or Z-Wave. +As an example of the first case, there are multiple integrations providing support for different Google products, e.g. Google Calendar by the `google` integration and Google Sheets by the `google_sheets` integration. +As an example of the second case, Innovelli offers Zigbee and Z-Wave devices and doesn't need its own integration. + + +To make these integrations easier to find by the user, they should be collected in a file within the `homeassistant/brands`folder. + +Examples: +```json +{ + "domain": "google", + "name": "Google", + "integrations": ["google", "google_sheets"] +} +``` + +```json +{ + "domain": "innovelli", + "name": "Innovelli", + "iot_standards": ["zigbee", "zwave"] +} +``` + +Or a minimal example that you can copy into your project: + +```json +{ + "domain": "your_brand_domain", + "name": "Your Brand", + "integrations": [], + "iot_standards": [], +} +``` + +## Domain + +The domain is a short name consisting of characters and underscores. This domain has to be unique and cannot be changed. Example of the domain for the Google brand: `google`. The domain key has to match the file name of the brand file it is in. If there's an integration with the same +domain, it has to be listed in the brand's `integrations`. + +## Name + +The name of the brand. + +## Integrations + +A list of integration domains implementing offerings of the brand. + +## IoT standards + +A list of IoT standards which are supported by devices of the brand. Possible values are `homekit`, `zigbee` and `zwave`. Note that a certain device may not support any of the listed IoT standards. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 3e665c8a..9fe5a6ae 100644 --- a/sidebars.js +++ b/sidebars.js @@ -127,6 +127,7 @@ module.exports = { "Building Integrations": [ "creating_component_index", "creating_integration_file_structure", + "creating_integration_brand", "creating_integration_manifest", "config_entries_config_flow_handler", "config_entries_options_flow_handler",