diff --git a/website/versioned_docs/version-0.79.0/creating_component_code_review.md b/website/versioned_docs/version-0.79.0/creating_component_code_review.md new file mode 100644 index 00000000..ede6c04e --- /dev/null +++ b/website/versioned_docs/version-0.79.0/creating_component_code_review.md @@ -0,0 +1,50 @@ +--- +title: Checklist for creating a component +id: version-0.79.0-creating_component_code_review +original_id: creating_component_code_review +--- + +A checklist of things to do when you're adding a new component. + +> Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! + +### 0. Common + + 1. Follow our [Style guidelines](development_guidelines.md) + 2. Use existing constants from [`const.py`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/const.py) + * Only add new constants to `const.py` if they are widely used. Otherwise keep them on components level + +### 1. Requirements + + 1. Requirement version pinned: `REQUIREMENTS = ['phue==0.8.1']` + 2. We no longer want requirements hosted on GitHub. Please upload to PyPi. + 3. Requirements should only be imported inside functions. This is necessary because requirements are installed on the fly. + +### 2. Configuration + + 1. Voluptuous schema present for [configuration validation](development_validation.md) + 2. Default parameters specified in voluptuous schema, not in `setup(…)` + 3. Schema using as many generic config keys as possible from `homeassistant.const` + 4. If your component has platforms, define a `PLATFORM_SCHEMA` instead of a `CONFIG_SCHEMA`. + 5. If using a `PLATFORM_SCHEMA` to be used with `EntityComponent`, import base from `homeassistant.helpers.config_validation` + 6. Never depend on users adding things to `customize` to configure behavior inside your component. + +### 3. Component/platform communication + + 1. If you need to share global data with platforms, use the dictionary `hass.data`. `hass.data[DATA_XY]` while `XY` is the component is preferred over `hass.data[DOMAIN]`. + 2. If the component fetches data that causes its related platform entities to update, you can notify them using the dispatcher code in `homeassistant.helpers.dispatcher`. + + +### 4. Communication with devices/services + + 1. All API specific code has to be part of a third party library hosted on PyPi. Home Assistant should only interact with objects and not make direct calls to the API. + +```python +# bad +status = requests.get(url('/status')) + +# good +from phue import Bridge +bridge = Bridge(...) +status = bridge.status() +``` diff --git a/website/versioned_docs/version-0.79.0/creating_platform_code_review.md b/website/versioned_docs/version-0.79.0/creating_platform_code_review.md new file mode 100644 index 00000000..04f799d6 --- /dev/null +++ b/website/versioned_docs/version-0.79.0/creating_platform_code_review.md @@ -0,0 +1,79 @@ +--- +title: Checklist for creating a platform +id: version-0.79.0-creating_platform_code_review +original_id: creating_platform_code_review +--- + +A checklist of things to do when you're adding a new platform. + +> Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! + +### 0. Common + + 1. Follow our [Style guidelines](development_guidelines.md) + 2. Use existing constants from [`const.py`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/const.py) + * Only add new constants to `const.py` if they are widely used. Otherwise keep them on platform level + * Use `CONF_MONITORED_CONDITIONS` instead of `CONF_MONITORED_VARIABLES` + +### 1. Requirements + + 1. Requirement version should be pinned: `REQUIREMENTS = ['phue==0.8.1']` + 2. We no longer want requirements hosted on GitHub. Please upload to PyPi. + 3. Requirements should only be imported inside functions. This is necessary because requirements are installed on the fly. + +### 2. Dependencies + + 1. If you depend on a component for the connection, add it to your dependencies: `DEPENDENCIES = ['nest']` + +### 3. Configuration + + 1. Voluptuous schema present for [configuration validation](development_validation.md) + 2. Voluptuous schema extends schema from component
(e.g., `light.hue.PLATFORM_SCHEMA` extends `light.PLATFORM_SCHEMA`) + 3. Default parameters specified in voluptuous schema, not in `setup_platform(...)` + 4. Your `PLATFORM_SCHEMA` should use as many generic config keys as possible from `homeassistant.const` + ```python + import voluptuous as vol + + from homeassistant.const import CONF_FILENAME, CONF_HOST + from homeassistant.components.light import PLATFORM_SCHEMA + import homeassistant.helpers.config_validation as cv + + CONF_ALLOW_UNREACHABLE = 'allow_unreachable' + DEFAULT_UNREACHABLE = False + + PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ + vol.Required(CONF_HOST): cv.string, + vol.Optional(CONF_ALLOW_UNREACHABLE, + default=DEFAULT_UNREACHABLE): cv.boolean, + vol.Optional(CONF_FILENAME): cv.string, + }) + ``` + 5. Never depend on users adding things to `customize` to configure behavior inside your platform. + +### 4. Setup Platform + + 1. Test if passed in info (user/pass/host etc.) works. + 2. Group your calls to `add_devices` if possible. + 3. If platform adds extra services, format should be `._`. + +### 5. Entity + + 1. Extend entity from component, e.g., `class HueLight(Light)`. + 2. Avoid passing in `hass` as a parameter to the entity. When the entity has been added to Home Assistant, `hass` will be set on the entity by the helper in entity_platform.py. This means you can access `hass` as `self.hass` inside the entity. + 3. Do not call `update()` in constructor, use `add_entities(devices, True)` instead. + 4. Do not do any I/O inside properties. Cache values inside `update()` instead. + 5. The state and/or attributes should not contain relative time since something happened. Instead it should store UTC timestamps. + +### 6. Communication with devices/services + + 1. All API specific code has to be part of a third party library hosted on PyPi. Home Assistant should only interact with objects and not make direct calls to the API. + +```python +# bad +status = requests.get(url('/status')) + +# good +from phue import Bridge +bridge = Bridge(...) +status = bridge.status() +``` diff --git a/website/versioned_docs/version-0.79.0/development_environment.md b/website/versioned_docs/version-0.79.0/development_environment.md new file mode 100644 index 00000000..0e5658f2 --- /dev/null +++ b/website/versioned_docs/version-0.79.0/development_environment.md @@ -0,0 +1,114 @@ +--- +title: Set up Development Environment +id: version-0.79.0-development_environment +original_id: development_environment +--- + +You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up. + +## Preparing your environment + +### Developing on Linux + +Install the core dependencies. + +```bash +$ sudo apt-get install python3-pip python3-dev python3-venv +``` + +In order to run `script/setup` below you will need some more dependencies. + +```bash +$ sudo apt-get install autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev +``` + +> Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: `sudo yum install epel-release && sudo yum install python36 python36-devel mysql-devel gcc` + +Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](frontend_index.md) section to learn more. + +### Developing on Windows + +If you are using Windows as a development platform, make sure that you have the correct Microsoft [Visual C++ build tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) installed. The installation of the most requirements and validation using `tox` will fail if this is not done correctly. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. + +Due to Home Assistant is mainly designed and developed on Linux distributions it is not recommended to develop on Windows machines. However on Windows 10 machines you should decide to set up a [Linux subsystem](https://docs.microsoft.com/de-de/windows/wsl/install-win10). + +Setup Linux subsystem. + +```bash +$ sudo apt-get update +$ sudo apt-get upgrade +$ echo 'export DISPLAY=:0' >> ~/.bashrc && . ~/.bashrc +$ sudo apt-get install xubuntu-desktop -y +``` + +It is recommended using [PyCharm](https://www.jetbrains.com/pycharm/download/) as debugger. Download and start PyCharm. + +```bash +$ wget https://download.jetbrains.com/python/pycharm-community-20XX.X.tar.gz +$ tar -xzf pycharm-community-20XX.X +$ ./pycharm.sh +``` + +In order to display the PyCharm GUI on Windows you need to run a X-Server like [VcXserv](https://sourceforge.net/projects/vcxsrv/). + +Also, make sure to install or upgrade the `setuptools` Python package. It contains compatibility improvements and adds automatic use of compilers: + +```bash +$ pip install --upgrade setuptools +``` + +### Developing on OS X + +Install [Homebrew](https://brew.sh/), then use that to install Python 3: + +```bash +$ brew install python3 +``` + +## Setup Local Repository + +Visit the [Home Assistant repository](https://github.com/home-assistant/home-assistant) and click **Fork**. +Once forked, setup your local copy of the source using the commands: + +```bash +$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git +$ cd home-assistant +$ git remote add upstream https://github.com/home-assistant/home-assistant.git +``` + +## Setting up virtual environment + +To isolate your environment from the rest of the system, set up a [`venv`](https://docs.python.org/3/library/venv.html). Within the `home-assistant` directory, create and activate your virtual environment. + +```bash +$ python3 -m venv . +$ source bin/activate +``` + +Install the requirements with a provided script named `setup`. + +```bash +$ script/setup +``` + +Invoke your installation. + +```bash +$ hass +``` + +## Logging + +By default logging in home-assistant is tuned for operating in production (set to INFO by default, with some modules set to even less verbose logging levels). + +You can use the [logger](https://www.home-assistant.io/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on: + +```yaml +logger: + default: info + logs: + homeassistant.core: debug + nest.nest: debug + asyncio: debug + homeassistant.components.cloud.iot: debug +``` diff --git a/website/versioned_docs/version-0.79.0/documentation_create_page.md b/website/versioned_docs/version-0.79.0/documentation_create_page.md new file mode 100644 index 00000000..d9a89d49 --- /dev/null +++ b/website/versioned_docs/version-0.79.0/documentation_create_page.md @@ -0,0 +1,133 @@ +--- +title: Create a new page +id: version-0.79.0-documentation_create_page +original_id: documentation_create_page +--- + +For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](https://www.home-assistant.io/components/) and the [Examples section](https://www.home-assistant.io/cookbook/) are generated automatically, so there is no need to add a link to those pages. + +Please honor the [Standards](documentation_standards.md) we have for the documentation. + +If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers. + +```text +--- +layout: page +title: "Awesome Sensor" +description: "home-assistant.io web presence" +date: 2015-06-17 08:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: "0.38" +ha_category: Sensor +ha_iot_class: "Local Polling" +ha_qa_scale: silver +--- + +Content...Written in markdown. + +### {% linkable_title Linkable Header %} +... +``` + +Please keep in mind that if the `date:` entry is in the future then the page will not show up. + +Additional keys for the file header: + +- `logo`: Please check the separate section below. +- `ha_release`: The release when the intregration was included, e.g., "0.38". If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`. +- `ha_category`: This entry is used to group the integration on the [Components overview](https://www.home-assistant.io/components/). +- `ha_iot_class`: [IoT class(/blog/2016/02/12/classifying-the-internet-of-things) is the classifier for the device's behavior. +- `ha_qa_scale`: [Quality scale](https://www.home-assistant.io/docs/quality_scale/) is the representation of the integration's quality. + +There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation. + +A couple of points to remember: + +- Document the needed steps to retrieve API keys or access token for the third party service or device if needed. +- Add screenshot to support the user where it make sense. +- Add the type of the device(s) (incl. firmware) you have tested when you know that there are multiple out there. + +### Configuration + +Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file. + +The **Configuration Variables** section must use the `{% configuration %} ... {% endconfiguration %}` tag. + +```text +{% configuration %} +api_key: + description: The API key to access the service. + required: true + type: string +name: + description: Name to use in the frontend. + required: false + default: The default name to use in the frontend. + type: string +monitored_conditions: + description: Conditions to display in the frontend. + required: true + type: map + keys: + weather: + description: A human-readable text summary. + temperature: + description: The current temperature. +{% endconfiguration %} +``` + +Available keys: + +- **`description:`**: That the variable is about. +- **`required:`**: If the variable is required. + +```text +required: true #=> Required +required: false #=> Optional +required: inclusive #=> Inclusive +required: exclusive #=> Exclusive +required: any string here #=> Any string here +``` +- **`type:`**: The type of the variable. Allowed entries: `string`, `int`, `time`, `template` or `map` (for a list of entries). For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example). +- **`default:`**: The default value for the variable. + +### Embedding Code + +You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in back-ticks. + +When you're writing code that is to be executed on the terminal, prefix it with `$`. + +### Templates + +For the [configuration templating](https://www.home-assistant.io/docs/configuration/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](documentation_standards.md) for further details. + +If you are don't escape templates then they will be rendered and appear blank on the website. + +### HTML + +The direct usage of HTML is supported but not recommended. The note boxes are an exception. + +```html +

+ You need to enable telnet on your router. +

+``` + +### Images, icons and logos + +The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent. + +| Type | Location | +| :----------- |:----------------------------------------------| +| logos | source/images/supported_brands | +| blog | source/images/blog | +| screenshots | source/images/components | + +Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). + +### Linking From The Sidebar + +If you are adding a new page that requires linking from the sidebar you need to edit the `docs_navigation.html` file in `home-assistant.github.io/source/_includes/asides/docs_navigation.html`. diff --git a/website/versioned_docs/version-0.79.0/documentation_index.md b/website/versioned_docs/version-0.79.0/documentation_index.md new file mode 100644 index 00000000..1ffc718a --- /dev/null +++ b/website/versioned_docs/version-0.79.0/documentation_index.md @@ -0,0 +1,38 @@ +--- +title: Documentation +id: version-0.79.0-documentation_index +original_id: documentation_index +--- + +The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section here is the place where we provide documentation and additional details about creating or modifying content. + +The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](http://github.com/mojombo/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know about HTML. + +You can use the "**Edit this page on GitHub**" link to edit pages without creating a fork. Keep in mind that you can't upload images while working this way. + +For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a Pull Request (PR). + +To test your changes locally, you need to install **Ruby** and its dependencies (gems): + +- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. Ruby version 2.3.0 or higher is required. +- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler` +- In your home-assistant.io root directory, run `$ bundle` to install the gems you need. + +Shortcut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle` + +Then you can work on the documentation: + +- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.io). +- Create/edit/update a page in the directory `source/_components/` for your platform/component. The Home Assistant documention itself is located in the directory `source/_docs/`. +- Test your changes to home-assistant.io locally: run `rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000) +- Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is a new feature, platform, or component. +- Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation. + +It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview. + +Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding: + +```bash +$ ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine +``` + diff --git a/website/versioned_docs/version-0.79.0/hassio_addon_communication.md b/website/versioned_docs/version-0.79.0/hassio_addon_communication.md new file mode 100644 index 00000000..ca52ff40 --- /dev/null +++ b/website/versioned_docs/version-0.79.0/hassio_addon_communication.md @@ -0,0 +1,42 @@ +--- +title: Add-On Communication +id: version-0.79.0-hassio_addon_communication +original_id: hassio_addon_communication +--- + +There are different ways for communication between add-ons inside Hass.io. + +## Network + +We use an internal network that allows to communicate with every add-on, even to/from Home Assistant, by using its name or alias. Only the add-ons which run on the host network are a bit limited. These can talk with all internal add-ons by their name but all other add-on can't address these add-on by name - using an alias works for both! + +Name/alias are used for communication inside Hass.io. +The name is generated using the following format: `{REPO}_{SLUG}`, e.g., `local_xy` or `3283fh_myaddon`. In this example, `{SLUG}` is defined in an add-ons `config.json`. You can use this name also as DNS name but you need replace the `_` with `-` to have a valid hostname. If an add-on is installed locally, `{REPO}` will be `local`. If the add-on is installed from a Github repository, `{REPO}` is a hashed identifier generated from the GitHub repository's URL (ex: https://github.com/xy/my_hassio_addons). See [here](https://github.com/home-assistant/hassio/blob/587047f9d648b8491dc8eef17dc6777f81938bfd/hassio/addons/utils.py#L17) to understand how this identifier is generated. Note that this identifier is required in certain service calls that use the [Hass.io add-on API][hassio-addon-api]. You can view the repository identifiers for all currently installed add-ons via a GET request to the hassio API `addons` endpoint. + +Use `hassio` for communication with the internal API. + +## Home Assistant + +An add-on can talk to the [Home Assistant API][hass-api] using the internal proxy. That makes it very easy to communicate with the API without knowing the password, port or any other information of the Home Assistant instance. Use this URL: `http://hassio/homeassistant/api` and internal communication is redirected to the right place. The next stept is to add `homeassistant_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN` and use this as Home-Assistant password. + +There is also a proxy for the [Home Assistant Websocket API][hass-websocket]. It works like the API proxy above and requires `HASSIO_TOKEN` as password. Use this URL: `http://hassio/homeassistant/websocket`. + +It is also possible to talk direct to the Home Assistant instance which is named `homeassistant` over the internal network. But you need to know the configuration that is used by the running instance. + +We have severals services for Hass.io inside Home Assistant to run tasks. To send data over STDIN to an add-on use the `hassio.addon_stdin` service. + +## Hass.io API + +To enables calls to the [Hass.io API][hassio-api], add `hassio_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN`. Now you can use the API over the URL: `http://hassio/`. Use the `HASSIO_TOKEN` with header `X-HASSIO-KEY`. It could be that you need also change the Hass.io API role like `hassio_role: default`. + +Add-ons can call some API commands without need set `hassio_api: true`: +- `/homeassistant/api` +- `/homeassistant/websocket` +- `/homeassistant/stream` +- `/addons/self/...` +- `/services*` + +[hass-api]: https://www.home-assistant.io/developers/rest_api/ +[hass-websocket]: https://www.home-assistant.io/developers/websocket_api/ +[hassio-api]: https://github.com/home-assistant/hassio/blob/master/API.md +[hassio-addon-api]: https://github.com/home-assistant/hassio/blob/dev/API.md#restful-for-api-addons diff --git a/website/versioned_docs/version-0.79.0/hassio_hass.md b/website/versioned_docs/version-0.79.0/hassio_hass.md new file mode 100644 index 00000000..deededd5 --- /dev/null +++ b/website/versioned_docs/version-0.79.0/hassio_hass.md @@ -0,0 +1,54 @@ +--- +title: Hass.io <> Home Assistant integration development +sidebar_label: HASS Integration development +id: version-0.79.0-hassio_hass +original_id: hassio_hass +--- + +These steps will help you connect your local Home Assistant to a remote Hass.io instance. You can then make changes locally to either the Hass.io component or the frontend and test it out against a real instance. + +For this guide, we're going to assume that you have an Hass.io instance up and running. If you don't, you can use the generic installation method to install it inside a [virtual machine](https://github.com/home-assistant/hassio-build/tree/master/install#install-hassio). + +## API Access + +To develop for the frontend, we're going to need API access to the supervisor. + +- Add our developer Add-on repository: https://github.com/home-assistant/hassio-addons-development +- Install the Add-on "Remote API proxy" + + ## Having Home Assistant connect to remote Hass.io + + The connection with the supervisor is hidden inside the host and is only accessible from applications running on the host. So to make it accessible for our Home Assistant instance, we will need to route the connection to our computer running Home Assistant. We're going to do this by forwarding the API with "Remote API proxy" Add-on. + +First, make sure Home Assistant will load the Hass.io component by adding `hassio:` to your `configuration.yaml` file. Next, we will need to tell Hass.io component how to connect to the remote Hass.io instance, we do this by setting the `HASSIO` and `HASSIO_TOKEN` environment variables when starting Home Assistant. Note that the `HASSIO` value is not the same as the one that we saw above and the `HASSIO_TOKEN` is available inside log output of "Remote API Add-on" (This change every restart of this Add-on!). + +```bash +HASSIO=:80 HASSIO_TOKEN= hass +``` + +Voila. Your local Home Assistant installation will now connect to a remote Hass.io instance. + +## Frontend development + +> This requires Home Assistant 0.71 or later. + +We need a couple more steps to do frontend development. First, make sure you have a Home Assistant frontend development set up ([instructions](frontend_index.md)). + +Update the Hass.io component configuration in your `configuration.yaml` to point at the frontend repository: + +```yaml +# configuration.yaml +hassio: + development_repo: /home/paulus/dev/hass/home-assistant-polymer +``` + +To build a local version of the Hass.io panel, go to the frontend repository and run: + +```bash +cd hassio +script/build_hassio +``` + +Now start Home Assistant as discussed in the previous section and it will now connect to the remote Hass.io but show your local frontend. + +We're currently transitioning in how we're building the frontend so we don't have an incremental development mode just yet. For now, after making a local change, run `script/build_hassio` again. diff --git a/website/versioned_docs/version-0.79.0/integration_quality_scale_index.md b/website/versioned_docs/version-0.79.0/integration_quality_scale_index.md new file mode 100644 index 00000000..eedba120 --- /dev/null +++ b/website/versioned_docs/version-0.79.0/integration_quality_scale_index.md @@ -0,0 +1,51 @@ +--- +title: Integration Quality Scale +sidebar_label: Introduction +id: version-0.79.0-integration_quality_scale_index +original_id: integration_quality_scale_index +--- + +The Integration Quality Scale scores each integration based on the code quality and user experience. Each level of the quality scale consists of a list of requirements. If an integration matches all requirements, it's considered to have reached that level. + +> Suggestions for changes can be done by creating an issue in the [architecture repo](https://github.com/home-assistant/architecture/issues/). + +# No score + +This integration passes the bare minimum requirements to become part of the index. + + - Satisfy all requirements for [creating components](creating_component_code_review.md) and [creating platforms](creating_platform_code_review.md). + - Configurable via `configuration.yaml` + +# Silver 🥈 + +This integration is able to cope when things go wrong. It will not print any exceptions nor will it fill the log with retry attempts. + +- Set an appropriate `SCAN_INTERVAL` (if a polling integration) +- Raise `PlatformNotReady` if unable to connect during platform setup (if appropriate) +- Handles expiration of auth credentials. Refresh if possible or print correct error and fail setup. If based on a config entry, should trigger a new config entry flow to re-authorize. +- Handles internet unavailable. Log a warning once when unavailable, log once when reconnected. +- Handles device/service unavailable. Log a warning once when unavailable, log once when reconnected. +- Set `available` property to `False` if appropriate ([docs](entity_index.md#generic-properties)) +- Entities have unique ID (if available) ([docs](entity_registry_index.md#unique-id-requirements)) + +# Gold 🥇 + +This is a solid integration that is able to survive poor conditions and can be configured via the user interface. + +- Configurable via config entries. + - Don't allow configuring already configured device/service (example: no 2 entries for same hub) + - Tests for the config flow + - Discoverable (if available) +- Entities have device info (if available) ([docs](device_registry_index.md#defining-devices)) +- States are translated in the frontend (text-based sensors only, [docs](internationalization_index.md)) +- Tests for reading data from/controlling the integration ([docs](development_testing.md)) +- Has a code owner + +# Platinum 🏆 + +Best of the best. The integration is completely async, meaning it's super fast. Integrations that reach platinum level will require approval by the code owner for each PR. + +- Set appropriate `PARALLEL_UPDATES` constant +- Support config entry unloading (called when config entry is removed) +- Integration + dependency are async +- Uses aiohttp and allows passing in websession (if making HTTP requests) diff --git a/website/versioned_sidebars/version-0.79.0-sidebars.json b/website/versioned_sidebars/version-0.79.0-sidebars.json new file mode 100644 index 00000000..ea115fab --- /dev/null +++ b/website/versioned_sidebars/version-0.79.0-sidebars.json @@ -0,0 +1,160 @@ +{ + "version-0.79.0-Architecture": { + "Architecture": [ + "version-0.79.0-architecture_index", + "version-0.79.0-architecture_components", + "version-0.79.0-architecture_entities", + "version-0.79.0-architecture_hassio" + ], + "Entities": [ + "version-0.79.0-entity_index", + "version-0.79.0-entity_alarm_control_panel", + "version-0.79.0-entity_binary_sensor", + "version-0.79.0-entity_climate", + "version-0.79.0-entity_cover", + "version-0.79.0-entity_fan", + "version-0.79.0-entity_light", + "version-0.79.0-entity_lock", + "version-0.79.0-entity_media_player", + "version-0.79.0-entity_remote", + "version-0.79.0-entity_sensor", + "version-0.79.0-entity_switch", + "version-0.79.0-entity_vacuum", + "version-0.79.0-entity_weather" + ], + "Authentication": [ + "version-0.79.0-auth_index", + "version-0.79.0-auth_api", + "version-0.79.0-auth_auth_provider", + "version-0.79.0-auth_auth_module" + ], + "Configuration.yaml": [ + "version-0.79.0-configuration_yaml_index" + ], + "Config Entries": [ + "version-0.79.0-config_entries_index", + "version-0.79.0-config_entries_config_flow_handler" + ], + "Data Entry Flow": [ + "version-0.79.0-data_entry_flow_index" + ], + "Entity Registry": [ + "version-0.79.0-entity_registry_index" + ], + "Device Registry": [ + "version-0.79.0-device_registry_index" + ] + }, + "version-0.79.0-Extending Frontend": { + "Frontend": [ + "version-0.79.0-frontend_index", + "version-0.79.0-frontend_architecture", + "version-0.79.0-frontend_development", + "version-0.79.0-frontend_data", + "version-0.79.0-frontend_external_auth" + ], + "Extending the frontend": [ + "version-0.79.0-frontend_add_card", + "version-0.79.0-frontend_add_more_info", + "version-0.79.0-frontend_add_websocket_api" + ], + "Custom UI": [ + "version-0.79.0-lovelace_custom_card", + "version-0.79.0-frontend_creating_custom_ui", + "version-0.79.0-frontend_creating_custom_panels" + ] + }, + "version-0.79.0-Extending HASS": { + "Developing a feature": [ + "version-0.79.0-development_index", + "version-0.79.0-development_environment", + "version-0.79.0-development_submitting", + "version-0.79.0-development_checklist", + "version-0.79.0-development_guidelines", + "version-0.79.0-development_testing", + "version-0.79.0-development_catching_up", + "version-0.79.0-development_validation", + "version-0.79.0-development_typing" + ], + "Development 101": [ + "version-0.79.0-dev_101_index", + "version-0.79.0-dev_101_hass", + "version-0.79.0-dev_101_events", + "version-0.79.0-dev_101_states", + "version-0.79.0-dev_101_services", + "version-0.79.0-dev_101_config" + ], + "Integration Quality Scale": [ + "version-0.79.0-integration_quality_scale_index" + ], + "Creating Platforms": [ + "version-0.79.0-creating_platform_index", + "version-0.79.0-creating_platform_code_review", + "version-0.79.0-creating_platform_example_light", + "version-0.79.0-creating_platform_example_sensor" + ], + "Creating Components": [ + "version-0.79.0-creating_component_index", + "version-0.79.0-creating_component_code_review", + "version-0.79.0-creating_component_deps_and_reqs", + "version-0.79.0-creating_component_events", + "version-0.79.0-creating_component_states", + "version-0.79.0-creating_component_discovery", + "version-0.79.0-creating_component_loading", + "version-0.79.0-creating_component_generic_discovery" + ] + }, + "version-0.79.0-Misc": { + "Introduction": [ + "version-0.79.0-misc" + ], + "External API": [ + "version-0.79.0-external_api_rest", + "version-0.79.0-external_api_websocket", + "version-0.79.0-external_api_server_sent_events" + ], + "Internationalization": [ + "version-0.79.0-internationalization_index", + "version-0.79.0-internationalization_backend_localization", + "version-0.79.0-internationalization_custom_component_localization", + "version-0.79.0-internationalization_translation" + ], + "Documentation": [ + "version-0.79.0-documentation_index", + "version-0.79.0-documentation_standards", + "version-0.79.0-documentation_create_page" + ], + "Intents": [ + "version-0.79.0-intent_index", + "version-0.79.0-intent_firing", + "version-0.79.0-intent_handling", + "version-0.79.0-intent_conversation", + "version-0.79.0-intent_builtin" + ], + "asyncio": [ + "version-0.79.0-asyncio_index", + "version-0.79.0-asyncio_101", + "version-0.79.0-asyncio_categorizing_functions", + "version-0.79.0-asyncio_working_with_async" + ], + "Hass.io": [ + "version-0.79.0-hassio_debugging", + "version-0.79.0-hassio_hass" + ], + "Hass.io Add-Ons": [ + "version-0.79.0-hassio_addon_index", + "version-0.79.0-hassio_addon_tutorial", + "version-0.79.0-hassio_addon_config", + "version-0.79.0-hassio_addon_communication", + "version-0.79.0-hassio_addon_testing", + "version-0.79.0-hassio_addon_publishing", + "version-0.79.0-hassio_addon_presentation", + "version-0.79.0-hassio_addon_repository", + "version-0.79.0-hassio_addon_security" + ], + "Maintainer docs": [ + "version-0.79.0-maintenance", + "version-0.79.0-releasing" + ] + } +} diff --git a/website/versions.json b/website/versions.json index 025d8d9f..42dad8c9 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "0.79.0", "0.78.0", "0.77.0", "0.76.0",