diff --git a/blog/2018-07-02-trying-new-auth.md b/blog/2018-07-02-trying-new-auth.md index e09a8eab..0a0e575b 100644 --- a/blog/2018-07-02-trying-new-auth.md +++ b/blog/2018-07-02-trying-new-auth.md @@ -39,7 +39,9 @@ homeassistant: auth: ``` -> This rest of the instructions are no longer necessary in Home Assistant 0.74 or later. +:::info +This rest of the instructions are no longer necessary in Home Assistant 0.74 or later. +::: Next step is to create users. Open a terminal and navigate to your Home Assistant installation. The script for managing users is built into Home Assistant and can be invoked using `hass --script auth --config /path/to/config`. diff --git a/blog/2019-03-11-user-permissions.md b/blog/2019-03-11-user-permissions.md index fa8b9762..0ee5e99c 100644 --- a/blog/2019-03-11-user-permissions.md +++ b/blog/2019-03-11-user-permissions.md @@ -22,7 +22,9 @@ Although we support the creation of custom groups, don't expect it publicly expo That being said, if you do want to play with it, it's possible. -> This is risky. Make backups, etc. +:::danger +This is risky. Make backups, etc. +::: Turn off Home Assistant and open up `/.storage/auth`. Find the key `"groups"` and add a new group: diff --git a/blog/2019-10-05-simple-mode.md b/blog/2019-10-05-simple-mode.md index 54a34b8f..bf875f82 100644 --- a/blog/2019-10-05-simple-mode.md +++ b/blog/2019-10-05-simple-mode.md @@ -8,7 +8,9 @@ title: Simple Mode in Home Assistant 1.0 import DiscussionBox from '../static/js/discourse_discussion.jsx' -> This blog post references simple and advanced mode. This has since been renamed to standard mode and advanced mode. +:::info +This blog post references simple and advanced mode. This has since been renamed to standard mode and advanced mode. +::: The Home Assistant UI has two different modes. There is a simple mode and an advanced mode. Simple mode has been introduced recently in [Home Assistant 0.96](https://www.home-assistant.io/blog/2019/07/17/release-96/#advanced-mode). In this post I want to outline my vision for simple mode in Home Assistant 1.0. diff --git a/blog/2020-02-18-106-custom-card-changes.md b/blog/2020-02-18-106-custom-card-changes.md index 4457470e..e46908b9 100644 --- a/blog/2020-02-18-106-custom-card-changes.md +++ b/blog/2020-02-18-106-custom-card-changes.md @@ -16,7 +16,9 @@ Please check if your custom card still works with 0.106 and make adjustments to ### Helper functions -> We decided to postpone this change until 0.107. +:::info +We decided to postpone this change until 0.107. +::: A second change that was made, is that we no longer load all element types by default. We load them when they are needed. This will also help performance but might break your custom card. diff --git a/docs/api_lib_index.md b/docs/api_lib_index.md index c3051bb5..85106d84 100644 --- a/docs/api_lib_index.md +++ b/docs/api_lib_index.md @@ -9,7 +9,9 @@ For this guide we're going to assume that we're building a library for a Rest AP This guide is not a perfect fit for every API. You might have to tweak the examples. -> If you are a manufacturer designing a new API for your product, [please read about the best type of API to add to your products here](https://www.home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things/#local-device-pushing-new-state). +:::info +If you are a manufacturer designing a new API for your product, [please read about the best type of API to add to your products here](https://www.home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things/#local-device-pushing-new-state). +::: HTTP API requests consist of four different parts: diff --git a/docs/app_integration_sending_data.md b/docs/app_integration_sending_data.md index 6eec4929..5f756502 100644 --- a/docs/app_integration_sending_data.md +++ b/docs/app_integration_sending_data.md @@ -30,7 +30,7 @@ All interaction will be done by making HTTP POST requests to the webhook url. Th The payload format depends on the type of interaction, but it all shares a common base: -```json5 +```json { "type": "", "data": {} @@ -39,7 +39,7 @@ The payload format depends on the type of interaction, but it all shares a commo If you received a `secret` during registration, you **MUST** encrypt your message and put it in the payload like this: -```json5 +```json { "type": "encrypted", "encrypted": true, @@ -60,7 +60,9 @@ As a general rule, expect to receive a 200 response for all your requests. There `mobile_app` supports two way encrypted communication via [Sodium](https://libsodium.gitbook.io/doc/). -> Sodium is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing and more. +:::info +Sodium is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing and more. +::: ### Choosing a library Libraries that wrap Sodium exist for most modern programming languages and platforms. Sodium itself is written in C. diff --git a/docs/auth_api.md b/docs/auth_api.md index 95410a13..26a667a9 100644 --- a/docs/auth_api.md +++ b/docs/auth_api.md @@ -29,7 +29,9 @@ Home Assistant will scan the first 10kB of a website for link tags. Overview of how the different parts interact -> All example URLs here are shown with extra spaces and new lines for display purposes only. +:::info + All example URLs here are shown with extra spaces and new lines for display purposes only. +::: The authorize url should contain `client_id` and `redirect_uri` as query parameters. @@ -66,7 +68,9 @@ All interactions with this endpoint need to be HTTP POST requests to `http://you ### Authorization code -> All requests to the token endpoint need to contain the exact same client ID as was used to redirect the user to the authorize endpoint. +:::tip +All requests to the token endpoint need to contain the exact same client ID as was used to redirect the user to the authorize endpoint. +::: Use the grant type `authorization_code` to retrieve the tokens after a user has successfully finished the authorize step. The request body is: @@ -129,8 +133,9 @@ An HTTP status code of 400 will be returned if an invalid request has been issue ### Revoking a refresh token -> client_id is not need for revoke refresh token - +:::tip +`client_id` is not need for revoke refresh token +::: The token endpoint is also capable of revoking a refresh token. Revoking a refresh token will immediately revoke the refresh token and all access tokens that it has ever granted. To revoke a refresh token, make the following request: ``` diff --git a/docs/auth_auth_module.md b/docs/auth_auth_module.md index 3f83f75a..aafa5e8a 100644 --- a/docs/auth_auth_module.md +++ b/docs/auth_auth_module.md @@ -6,7 +6,9 @@ Multi-factor Authentication Modules are used in conjunction with [Authentication ## Defining an mfa auth module -> We currently only support built-in mfa auth modules. Support for custom auth modules might arrive in the future. +:::info +We currently only support built-in mfa auth modules. Support for custom auth modules might arrive in the future. +::: Multi-factor Auth modules are defined in `homeassistant/auth/mfa_modules/.py`. The auth module will need to provide an implementation of the `MultiFactorAuthModule` class. @@ -59,7 +61,9 @@ homeassistant: In this example, user will first select from `homeassistant` or `legacy_api_password` auth provider. For `homeassistant` auth provider, user will first input username/password, if that user enabled both `totp` and `insecure_example`, then user need select one auth module, then input Google Authenticator code or input pin code base on the selection. -> insecure_example is only for demo purpose, please do not use it in production. +:::tip +`insecure_example` is only for demo purpose, please do not use it in production. +::: ## Validation session diff --git a/docs/auth_auth_provider.md b/docs/auth_auth_provider.md index 8880c3db..d37c4186 100644 --- a/docs/auth_auth_provider.md +++ b/docs/auth_auth_provider.md @@ -8,7 +8,9 @@ Once an authentication provider has confirmed the identity of a user, it will pa ## Defining an auth provider -> We currently only support built-in auth providers. Support for custom auth providers might arrive in the future. +:::info +We currently only support built-in auth providers. Support for custom auth providers might arrive in the future. +::: Auth providers are defined in `homeassistant/auth/providers/.py`. The auth provider module will need to provide an implementation of the `AuthProvider` class and `LoginFlow` class, it is what asks user for information and validates it base on `data_entry_flow`. @@ -30,7 +32,9 @@ Auth providers shall extend the following methods of `LoginFlow` class. ## async_step_init of LoginFlow -> We may change this inteface in near future. +:::info +We may change this inteface in near future. +::: `LoginFlow` extends `data_entry_flow.FlowHandler`. The first step of data entry flow is hard coded as `init`, so each flow has to implement `async_step_init` method. The pattern of `async_step_init` likes following pseudo-code: diff --git a/docs/auth_permissions.md b/docs/auth_permissions.md index 5feddf12..3e57c9ee 100644 --- a/docs/auth_permissions.md +++ b/docs/auth_permissions.md @@ -2,7 +2,9 @@ title: "Permissions" --- -> This is an experimental feature that is not enabled or enforced yet +:::info +This is an experimental feature that is not enabled or enforced yet +::: Permissions limit the things a user has access to or can control. Permissions are attached to groups, of which a user can be a member. The combined permissions of all groups a user is a member of decides what a user can and cannot see or control. diff --git a/docs/creating_component_code_review.md b/docs/creating_component_code_review.md index 92a7dd73..c44f944d 100644 --- a/docs/creating_component_code_review.md +++ b/docs/creating_component_code_review.md @@ -5,7 +5,9 @@ sidebar_label: Component Checklist A checklist of things to do when you're adding a new component. -> Not all existing code follow the requirements in this checklist. This cannot be used as a reason to not follow them! +:::info +Not all existing code follow the requirements in this checklist. This cannot be used as a reason to not follow them! +::: ### 0. Common diff --git a/docs/creating_integration_manifest.md b/docs/creating_integration_manifest.md index 842b7f78..fd8a122c 100644 --- a/docs/creating_integration_manifest.md +++ b/docs/creating_integration_manifest.md @@ -59,7 +59,7 @@ GitHub usernames or team names of people that are responsible for this integrati Specify the `config_flow` key if your integration has a config flow to create a config entry. When specified, the file `config_flow.py` needs to exist in your integration. -```json5 +```json { "config_flow": true } @@ -94,7 +94,7 @@ hass --skip-pip If your integration supports discovery via [Zeroconf](https://en.wikipedia.org/wiki/Zero-configuration_networking), you can add the type to your manifest. If the user has the `zeroconf` integration loaded, it will load the `zeroconf` step of your integration's config flow when it is discovered. -```json5 +```json { "zeroconf": ["_googlecast._tcp.local."] } @@ -106,7 +106,7 @@ If your integration supports discovery via [SSDP](https://en.wikipedia.org/wiki/ The following example has one matcher consisting of three items, all of which must match for discovery to happen by this config. -```json5 +```json { "ssdp": [ { @@ -124,7 +124,7 @@ If your integration supports discovery via HomeKit, you can add the supported mo HomeKit discovery works by testing if the discovered modelname starts with any of the model names specified in the manifest.json. -```json5 +```json { "homekit": { "models": [ @@ -146,7 +146,7 @@ When your integration has no score, then don't add it to the manifest of your in We highly recommend getting your integration scored. -```json5 +```json { "quality_scale": "silver" } diff --git a/docs/creating_platform_code_review.md b/docs/creating_platform_code_review.md index a4aca759..7a256a54 100644 --- a/docs/creating_platform_code_review.md +++ b/docs/creating_platform_code_review.md @@ -5,7 +5,9 @@ sidebar_label: Platform Checklist 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! +:::info +Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! +::: ### 0. Common diff --git a/docs/dev_101_index.md b/docs/dev_101_index.md index e057bdcb..103f9303 100644 --- a/docs/dev_101_index.md +++ b/docs/dev_101_index.md @@ -9,7 +9,9 @@ To get our code running inside Home Assistant we're going to create a custom com 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. +:::info +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: diff --git a/docs/dev_101_states.md b/docs/dev_101_states.md index 74e40e64..7a48637d 100644 --- a/docs/dev_101_states.md +++ b/docs/dev_101_states.md @@ -123,6 +123,7 @@ def device_state_attributes(self): return self._attributes ``` -> Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead. - +:::tip +Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead. +::: To get your component included in the Home Assistant releases, follow the steps described in the [Submit your work](development_submitting.md) section. Basically you only need to move your component into the `homeassistant/component/` directory of your fork and create a Pull Request. diff --git a/docs/development_catching_up.md b/docs/development_catching_up.md index 10bc1fac..4ba0c72f 100644 --- a/docs/development_catching_up.md +++ b/docs/development_catching_up.md @@ -4,7 +4,9 @@ title: "Catching up with Reality" If it's taking a while to develop your feature, and you want to catch up with what's in the current Home Assistant `dev` branch, you can use `git rebase`. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant, and replay all of your commits on top. -> If you use the workflow below, it is important that you force push the update as described. Git might prompt you to do `git pull` first. Do **NOT** do that! It would mess up your commit history. +:::tip +If you use the workflow below, it is important that you force push the update as described. Git might prompt you to do `git pull` first. Do **NOT** do that! It would mess up your commit history. +::: ```shell # Run this from your feature branch @@ -33,4 +35,3 @@ $ git remote add upstream https://github.com/home-assistant/core.git ``` Then, `git pull --rebase upstream dev`. - diff --git a/docs/development_environment.md b/docs/development_environment.md index 9283e29f..11cdb163 100644 --- a/docs/development_environment.md +++ b/docs/development_environment.md @@ -54,7 +54,9 @@ $ sudo apt-get install autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev $ sudo apt-get install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-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` +:::tip + 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. @@ -132,7 +134,7 @@ Install the requirements with a provided script named `setup`. $ script/setup ``` -Invoke your installation, adjusting the [configuration](https://www.home-assistant.io/docs/configuration/) if required. +Invoke your installation, adjusting the [configuration](https://www.home-assistant.io/docs/configuration/) if required. ```shell $ hass diff --git a/docs/development_submitting.md b/docs/development_submitting.md index 1e141f43..0a54e872 100644 --- a/docs/development_submitting.md +++ b/docs/development_submitting.md @@ -2,7 +2,9 @@ title: "Submit your work" --- -> Always base your Pull Requests of of the current **`dev`** branch, not `master`. +:::tip +Always base your Pull Requests of of the current **`dev`** branch, not `master`. +::: Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://help.github.com/articles/using-pull-requests). Here are the steps: @@ -39,4 +41,3 @@ Submit your improvements, fixes, and new features to Home Assistant one at a tim * Click **Create pull request**. 7. Check for comments and suggestions on your pull request and keep an eye on the [CI output](https://travis-ci.org/home-assistant/home-assistant/). - diff --git a/docs/device_registry_index.md b/docs/device_registry_index.md index ce88fc71..21f5bbd7 100644 --- a/docs/device_registry_index.md +++ b/docs/device_registry_index.md @@ -18,7 +18,9 @@ If you connect a sensor to another device to read some of its data, it should st A device that offers multiple endpoints, where parts of the device sense or output in different areas, should be split into separate devices and refer back to parent device with the `via_device` attribute. This allows the separate endpoints to be assigned to different areas in the building. -> Although not currently available, we could consider offering an option to users to merge devices. +:::info +Although not currently available, we could consider offering an option to users to merge devices. +::: ## Device properties @@ -37,7 +39,9 @@ A device that offers multiple endpoints, where parts of the device sense or outp ## Defining devices -> Entity device info is only read if the entity is loaded via a [config entry](config_entries_index.md). +:::tip +Entity device info is only read if the entity is loaded via a [config entry](config_entries_index.md). +::: Each entity is able to define a device via the `device_info` property. This property is read when an entity is added to Home Assistant via a config entry. A device will be matched up with an existing device via supplied identifiers and connections, like serial numbers or MAC addresses. diff --git a/docs/entity_air_quality.md b/docs/entity_air_quality.md index 30f0033b..a7a91fe1 100644 --- a/docs/entity_air_quality.md +++ b/docs/entity_air_quality.md @@ -5,7 +5,9 @@ sidebar_label: Air Quality ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- @@ -23,4 +25,3 @@ sidebar_label: Air Quality | volatile_organic_compounds | float | `None` | The volatile organic compounds (VOC) level. Properties have to follow the units defined in the `unit_system`. - diff --git a/docs/entity_alarm_control_panel.md b/docs/entity_alarm_control_panel.md index 6e9d62b6..14f75410 100644 --- a/docs/entity_alarm_control_panel.md +++ b/docs/entity_alarm_control_panel.md @@ -3,11 +3,15 @@ title: Alarm Control Panel Entity sidebar_label: Alarm Control Panel --- -> This entry is incomplete. Contribution welcome. +:::info Incomplete +This entry is incomplete. Contribution welcome. +::: ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_binary_sensor.md b/docs/entity_binary_sensor.md index b5d8489d..f2ed4b93 100644 --- a/docs/entity_binary_sensor.md +++ b/docs/entity_binary_sensor.md @@ -7,7 +7,9 @@ A binary sensor is a sensor that can only have two states. ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_climate.md b/docs/entity_climate.md index 7189330d..ddda8e9c 100644 --- a/docs/entity_climate.md +++ b/docs/entity_climate.md @@ -7,7 +7,9 @@ A climate entity is a device that controls temperature, humidity, or fans, such ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | | ----------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ | diff --git a/docs/entity_cover.md b/docs/entity_cover.md index 615a52fb..045272c7 100644 --- a/docs/entity_cover.md +++ b/docs/entity_cover.md @@ -7,7 +7,9 @@ A cover entity is a device that controls an opening or cover, such as a garage d ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: ### Platform Properties (to be implemented by deriving platform classes) @@ -27,7 +29,7 @@ A cover entity is a device that controls an opening or cover, such as a garage d | supported_features | int (bitwise) | Value determined from `current_cover_position` and `current_cover_tilt_position` | Describes the supported features. See the related table below for details. ### Device Classes -| Constant | Description +| Constant | Description |----------|-----------------------| | `DEVICE_CLASS_AWNING` | Control of an awning, such as an exterior retractible window, door, or patio cover. | `DEVICE_CLASS_BLIND` | Control of blinds, which are linked slats that expand or collapse to cover an opening or may be tilted to partially cover an opening, such as window blinds. diff --git a/docs/entity_fan.md b/docs/entity_fan.md index 7b1dc341..4c4bb3d1 100644 --- a/docs/entity_fan.md +++ b/docs/entity_fan.md @@ -7,13 +7,15 @@ A fan entity is a device that controls the different vectors of your fan such as ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | current_direction | str | None | Return the current direction of the fan | | is_on | boolean | None |Return true if the entity is on | -| speed | str | None | Return the current speed. One of the values in speed_list. | +| speed | str | None | Return the current speed. One of the values in speed_list. | | speed_list | list | None| Get the list of available speeds. The allowed values are "off", "low", "medium" and "high". Use the corresponding constants SPEED_OFF, SPEED_LOW, SPEED_MEDIUM, SPEED_HIGH. | | supported_features | int | 0 | Flag supported features | @@ -115,8 +117,3 @@ class FanEntity(ToggleEntity): async def async_oscillate(self, oscillating: bool) -> None: """Oscillate the fan.""" ``` - - - - - diff --git a/docs/entity_index.md b/docs/entity_index.md index b837f88b..f834156f 100644 --- a/docs/entity_index.md +++ b/docs/entity_index.md @@ -54,7 +54,9 @@ Whenever you receive new state from your subscription, you can tell Home Assista The entity base class has a few properties that are common among all entities in Home Assistant. These can be added to any entity regardless of the type. All these properties are optional and don't need to be implemented. -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | | ----------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/docs/entity_lock.md b/docs/entity_lock.md index 67ca8486..15096f8a 100644 --- a/docs/entity_lock.md +++ b/docs/entity_lock.md @@ -7,7 +7,9 @@ A lock entity is a device which is able to lock and unlock. Locking and unlockin ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- @@ -32,7 +34,7 @@ class MyLock(LockDevice): def lock(self, **kwargs): """Lock all or specified locks. A code to lock the lock with may optionally be specified.""" - + async def async_lock(self, **kwargs): """Lock all or specified locks. A code to lock the lock with may optionally be specified.""" ``` @@ -44,7 +46,7 @@ class MyLock(LockDevice): def unlock(self, **kwargs): """Unlock all or specified locks. A code to unlock the lock with may optionally be specified.""" - + async def async_unlock(self, **kwargs): """Unlock all or specified locks. A code to unlock the lock with may optionally be specified.""" ``` @@ -58,7 +60,7 @@ class MyLock(LockDevice): def open(self, **kwargs): """Open (unlatch) all or specified locks. A code to open the lock with may optionally be specified.""" - + async def async_open(self, **kwargs): """Open (unlatch) all or specified locks. A code to open the lock with may optionally be specified.""" ``` diff --git a/docs/entity_media_player.md b/docs/entity_media_player.md index 309d25f7..ab1242e6 100644 --- a/docs/entity_media_player.md +++ b/docs/entity_media_player.md @@ -3,11 +3,15 @@ title: Media Player Entity sidebar_label: Media Player --- -> This entry is incomplete. Contribution welcome. +:::info Incomplete +This entry is incomplete. Contribution welcome. +::: ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_remote.md b/docs/entity_remote.md index 75725f62..77cf3f03 100644 --- a/docs/entity_remote.md +++ b/docs/entity_remote.md @@ -3,14 +3,17 @@ title: Remote Entity sidebar_label: Remote --- -> This entry is incomplete. Contribution welcome. +:::info Incomplete +This entry is incomplete. Contribution welcome. +::: ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- ## Methods - diff --git a/docs/entity_sensor.md b/docs/entity_sensor.md index 23f93bb8..97786b1a 100644 --- a/docs/entity_sensor.md +++ b/docs/entity_sensor.md @@ -7,7 +7,9 @@ A sensor is a read-only entity that provides some information. Information has a ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_switch.md b/docs/entity_switch.md index 66a8c7b9..376d96d0 100644 --- a/docs/entity_switch.md +++ b/docs/entity_switch.md @@ -5,7 +5,9 @@ sidebar_label: Switch ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_vacuum.md b/docs/entity_vacuum.md index acc0c1de..4109eb65 100644 --- a/docs/entity_vacuum.md +++ b/docs/entity_vacuum.md @@ -5,7 +5,9 @@ sidebar_label: Vacuum ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_water_heater.md b/docs/entity_water_heater.md index 3476a3f6..f6a08e8c 100644 --- a/docs/entity_water_heater.md +++ b/docs/entity_water_heater.md @@ -5,7 +5,9 @@ sidebar_label: Water Heater ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/entity_weather.md b/docs/entity_weather.md index bc75fc45..e2ba8d48 100644 --- a/docs/entity_weather.md +++ b/docs/entity_weather.md @@ -5,7 +5,9 @@ sidebar_label: Weather ## Properties -> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +:::tip +Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. +::: | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/external_api_rest.md b/docs/external_api_rest.md index cc0685d6..1b3929e2 100644 --- a/docs/external_api_rest.md +++ b/docs/external_api_rest.md @@ -349,7 +349,9 @@ $ curl -X GET -H "Authorization: Bearer ABCDEFGH" \ Updates or creates a state. You can create any state that you want, it does not have to be backed by an entity in Home Assistant. -> :info: NOTE: This endpoint sets the representation of a device within Home Asistant and will not communicate with the actual device. To communicate with the device, use the [POST /api/services/<domain>/<service>](#post-apiservicesltdomainltservice) endpoint. +:::info +This endpoint sets the representation of a device within Home Asistant and will not communicate with the actual device. To communicate with the device, use the [POST /api/services/<domain>/<service>](#post-apiservicesltdomainltservice) endpoint. +::: Expects a JSON object that has at least a state attribute: @@ -459,7 +461,9 @@ $ curl -X POST \ http://localhost:8123/api/services/mqtt/publish ``` -> The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system. +:::tip +The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system. +::: #### POST /api/template diff --git a/docs/external_api_server_sent_events.md b/docs/external_api_server_sent_events.md index b820dc8a..3fb44233 100644 --- a/docs/external_api_server_sent_events.md +++ b/docs/external_api_server_sent_events.md @@ -15,7 +15,9 @@ $ curl -X GET -H 'Authorization: Bearer ABCDEFGH' \ -H "Content-Type: application/json" http://localhost:8123/api/stream ``` -> Will no longer work with the new Authentication system. +:::caution +Will no longer work with the new Authentication system. +::: You can create a convenient view for this by creating an HTML file (`sse.html`) in the `www` folder of your Home Assistant configuration directory (`.homeassistant`). Paste this snippet into the file: @@ -47,7 +49,9 @@ $ http --stream http://localhost:8123/api/stream 'Authorization:Bearer ABCDEFGH' ### Website -> Will no longer work with the new Authentication system. +:::caution +Will no longer work with the new Authentication system. +::: The [home-assistant-sse](https://github.com/fabaff/home-assistant-sse) repository contains a more advanced example. diff --git a/docs/frontend_creating_custom_ui.md b/docs/frontend_creating_custom_ui.md index d9f1f3c1..1983cf0a 100644 --- a/docs/frontend_creating_custom_ui.md +++ b/docs/frontend_creating_custom_ui.md @@ -2,8 +2,9 @@ title: "Creating custom UI" --- -> This feature has been deprecated and is no longer supported. To add custom UI to Home Assistant, build a [custom Lovelace card](lovelace_custom_card.md) instead. - +:::warning Deprecated +This feature has been deprecated and is no longer supported. To add custom UI to Home Assistant, build a [custom Lovelace card](lovelace_custom_card.md) instead. +::: ### State card If you would like to use your own [State card](frontend_add_card.md) without merging your code into [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer/) you can create your own implementation. @@ -89,7 +90,9 @@ customElements.define(StateCardMyCustomLight.is, StateCardMyCustomLight); ``` -> Some browsers don't support latest ECMAScript standards, these require a separate ES5 compatible file (`extra_html_url_es5`). +:::tip +Some browsers don't support latest ECMAScript standards, these require a separate ES5 compatible file (`extra_html_url_es5`). +::: For more possibilities, see the [Custom UI section](https://www.home-assistant.io/cookbook/#user-interface) on our Examples page. diff --git a/docs/frontend_data.md b/docs/frontend_data.md index 74223538..5ccdd69d 100644 --- a/docs/frontend_data.md +++ b/docs/frontend_data.md @@ -143,4 +143,6 @@ If you need to pass in data, pass a third argument: hass.callApi('delete', 'notify.html5', { subscription: 'abcdefgh' }); ``` -_We're moving away from API calls and are migrating everything to `hass.callWS(message)` calls._ +:::info +We're moving away from API calls and are migrating everything to `hass.callWS(message)` calls. +::: diff --git a/docs/frontend_development.md b/docs/frontend_development.md index 76e45c47..cb712835 100644 --- a/docs/frontend_development.md +++ b/docs/frontend_development.md @@ -5,7 +5,9 @@ sidebar_label: "Development" The Home Assistant frontend is built using web components. For more background about our technology choices, [see this blog post](https://developers.home-assistant.io/blog/2019/05/22/internet-of-things-and-the-modern-web.html). -> Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes. +:::caution +Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes. +::: ## Setting up the environment @@ -59,7 +61,9 @@ $ script/develop Make sure you have cache disabled and correct settings to avoid stale content: -> Instructions are for Google Chrome +:::info +Instructions are for Google Chrome +::: 1. Disable cache by ticking the box in `Network` > `Disable cache` diff --git a/docs/hassio_addon_publishing.md b/docs/hassio_addon_publishing.md index f961916e..30301cfb 100644 --- a/docs/hassio_addon_publishing.md +++ b/docs/hassio_addon_publishing.md @@ -53,6 +53,8 @@ $ docker run --rm --privileged -v \ --all -t /data ``` -> If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: error creating aufs mount to /var/lib/docker/aufs/mnt/-init: invalid argument. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: "storage-driver" : "aufs" or map the docker socket into container. +:::tip +If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: `error creating aufs mount to /var/lib/docker/aufs/mnt/-init: invalid argument`. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: `"storage-driver" : "aufs"` or map the docker socket into container. +::: [builder]: https://github.com/home-assistant/hassio-builder diff --git a/docs/hassio_debugging.md b/docs/hassio_debugging.md index 7ea35148..1611880c 100644 --- a/docs/hassio_debugging.md +++ b/docs/hassio_debugging.md @@ -2,7 +2,9 @@ title: "Debugging Home Assistant" --- -> This section is not for end users. End users should use the [SSH add-on] to SSH into Home Assistant. This is for developers of Home Assistant. Do not ask for support if you are using these options. +:::info +This section is not for end users. End users should use the [SSH add-on] to SSH into Home Assistant. This is for developers of Home Assistant. Do not ask for support if you are using these options. +::: [SSH add-on]: https://www.home-assistant.io/addons/ssh/ @@ -35,12 +37,16 @@ Visual Studio Code config: You need set the dev mode on supervisor and enable debug with options. You need also install the Remote debug Add-on from Developer Repository to expose the debug port to Host. ## SSH access to the host -> SSH access through the [SSH add-on] (which will give you SSH access through port 22) will not provide you with all the necessary privileges, and you will be asked for a username and password when typing the 'login' command. You need to follow the steps below, which will setup a separate SSH access through port 22222 with all necessary privileges. +:::info +SSH access through the [SSH add-on] (which will give you SSH access through port 22) will not provide you with all the necessary privileges, and you will be asked for a username and password when typing the 'login' command. You need to follow the steps below, which will setup a separate SSH access through port 22222 with all necessary privileges. +::: ### Home Assistant OS Use a USB drive formatted with FAT, ext4, or NTFS and name it CONFIG (case sensitive). Create an `authorized_keys` file (no extension) containing your public key, and place it in the root of the USB drive. File needs to be ANSI encoded (not UTF-8) and must have Unix line ends (LF), not Windows (CR LF). See [Generating SSH Keys](#generating-ssh-keys) section below if you need help generating keys. From the UI, navigate to the Supervisor system page and choose "Import from USB". You can now access your device as root over SSH on port 22222. Alternatively, the file will be imported from the USB when the Home Assistant OS device is rebooted. -> Make sure when you are copying the public key to the root of the USB drive that you rename the file correctly to `authorized_keys` with no `.pub` file extension. +:::tip +Make sure when you are copying the public key to the root of the USB drive that you rename the file correctly to `authorized_keys` with no `.pub` file extension. +::: You should then be able to SSH into your Home Assistant device. On Mac/Linux, use: @@ -48,7 +54,7 @@ You should then be able to SSH into your Home Assistant device. On Mac/Linux, us ssh root@hassio.local -p 22222 ``` -You will initially be logged in to Home Assistant CLI for HassOS where you can perform normal [CLI functions]. If you need access to the host system use the 'login' command. [Home Assistant OS] is a hypervisor for Docker. See the [Supervisor Architecture] documentation for information regarding the supervisor. The supervisor offers an API to manage the host and running the Docker containers. Home Assistant itself and all installed addon's run in separate Docker containers. +You will initially be logged in to Home Assistant CLI for HassOS where you can perform normal [CLI functions]. If you need access to the host system use the 'login' command. [Home Assistant OS] is a hypervisor for Docker. See the [Supervisor Architecture] documentation for information regarding the supervisor. The supervisor offers an API to manage the host and running the Docker containers. Home Assistant itself and all installed addon's run in separate Docker containers. [CLI functions]: https://www.home-assistant.io/hassio/commandline/ [Home Assistant OS]: https://github.com/home-assistant/hassos diff --git a/docs/hassio_hass.md b/docs/hassio_hass.md index e0f349a2..91aa3e29 100644 --- a/docs/hassio_hass.md +++ b/docs/hassio_hass.md @@ -33,7 +33,9 @@ Voila. Your local Home Assistant installation will now connect to a remote Hass. ## Frontend development -> This requires Home Assistant 0.71 or later. +:::tip +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)). diff --git a/docs/integration_fetching_data.md b/docs/integration_fetching_data.md index 5b4312ed..fa9c7233 100644 --- a/docs/integration_fetching_data.md +++ b/docs/integration_fetching_data.md @@ -143,7 +143,9 @@ SCAN_INTERVAL = timedelta(seconds=5) # Request Parallelism -> This is an advanced topic. +:::info +This is an advanced topic. +::: Home Assistant has built-in logic to make sure that integrations do not hammer APIs and consume all available resources in Home Assistant. This logic is built around limiting the number of parallel requests. This logic is automatically used during service calls and entity updates. diff --git a/docs/integration_quality_scale_index.md b/docs/integration_quality_scale_index.md index cea2d053..526b8f12 100644 --- a/docs/integration_quality_scale_index.md +++ b/docs/integration_quality_scale_index.md @@ -4,7 +4,9 @@ title: "Integration Quality Scale" 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/). +:::info +Suggestions for changes can be done by creating an issue in the [architecture repo](https://github.com/home-assistant/architecture/issues/). +::: # No score diff --git a/docs/internationalization_translation.md b/docs/internationalization_translation.md index 0ebc0c3a..658c01bf 100644 --- a/docs/internationalization_translation.md +++ b/docs/internationalization_translation.md @@ -11,7 +11,9 @@ Translations for Home Assistant are managed through [Lokalise](https://lokalise. For more information about the translation workflow, please see the [Lokalise translation workflow documents](https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators). -> The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon. +:::info +The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon. +::: ## Translation placeholders @@ -32,7 +34,9 @@ English Name: German Native Name: Deutsch ``` -> Region specific translations (`en-US`, `fr-CA`) will only be included if translations for that region need to differ from the base language translation. +:::info +Region specific translations (`en-US`, `fr-CA`) will only be included if translations for that region need to differ from the base language translation. +::: ### Maintainer steps to add a new language 1. Language tags have to follow [BCP 47](https://tools.ietf.org/html/bcp47). A list of most language tags can be found here: [IANA sutbtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). Examples: `fr`, `fr-CA`, `zh-Hans`. Only include the country code if country specific overrides are being included, and the base language is already translated.