mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-26 10:46:29 +00:00
Replace quotes with tip boxes (#458)
* Replace quotes with tip boxes The use of quotes was making important content less clear than the body. Docusaurus now has native tip boxes use remark-admonitions so use these instead. * Replace json5 codeblock language with json json5 doesn't have native syntax colouring. Rather than handle with custom css just flip block to have `json` set as language to create same result. All blocks were standard JSON anyway
This commit is contained in:
Tom Brien
GitHub
parent
00d02ee1f4
commit
d6e06a716d
@ -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`.
|
||||
|
||||
|
||||
@ -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 `<config>/.storage/auth`. Find the key `"groups"` and add a new group:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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": "<type of message>",
|
||||
"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.
|
||||
|
||||
@ -29,7 +29,9 @@ Home Assistant will scan the first 10kB of a website for link tags.
|
||||
<img class='invertDark' src='/img/en/auth/authorize_flow.png' alt='Overview of how the different parts interact' />
|
||||
</a>
|
||||
|
||||
> 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:
|
||||
|
||||
```
|
||||
|
||||
@ -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/<name of module>.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
|
||||
|
||||
|
||||
@ -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/<name of provider>.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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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"
|
||||
}
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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/).
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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 |
|
||||
| ----------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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."""
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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 |
|
||||
| ----------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
|
||||
@ -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."""
|
||||
```
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
| ---- | ---- | ------- | -----------
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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);
|
||||
</script>
|
||||
```
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
@ -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.
|
||||
:::
|
||||
|
||||
@ -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`
|
||||
|
||||
|
||||
@ -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: <code>error creating aufs mount to /var/lib/docker/aufs/mnt/<SOME_ID>-init: invalid argument</code>. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: <code>"storage-driver" : "aufs"</code> 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/<SOME_ID>-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
|
||||
|
||||
@ -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 <b>developers</b> 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 <b>developers</b> 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
|
||||
|
||||
@ -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)).
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user