mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-14 21:06:28 +00:00
Add version 0.77
This commit is contained in:
parent
8afcdbfd24
commit
334d29912a
65
website/versioned_docs/version-0.77.0/auth_auth_module.md
Normal file
65
website/versioned_docs/version-0.77.0/auth_auth_module.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Multi-factor Authentication Modules
|
||||
id: version-0.77.0-auth_auth_module
|
||||
original_id: auth_auth_module
|
||||
---
|
||||
|
||||
Multi-factor Authentication Modules are used in conjunction with [Authentication Provider](auth_auth_provider.html) to provide a fully configurable authentication framework. Each MFA module may provide one multi-factor authentication function. User can enable mulitple mfa module, but can only select one module in login process.
|
||||
|
||||
## Defining an mfa auth module
|
||||
|
||||
> We currently only support built-in mfa auth modules. Support for custom auth modules might arrive in the future.
|
||||
|
||||
Multi-facor 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.
|
||||
|
||||
For an example of a fully implemented auth module, please see [insecure_example.py](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/auth/mfa_modules/insecure_example.py).
|
||||
|
||||
Multi-factor Auth modules shall extend the following methods of `MultiFactorAuthModule` class.
|
||||
|
||||
| method | Required | Description
|
||||
| ------ | -------- | -----------
|
||||
| `@property def input_schema(self)` | Yes | Return a schema defined the user input form.
|
||||
| `async def async_setup_flow(self, user_id)` | Yes | Return a SetupFlow to handle the setup workflow.
|
||||
| `async def async_setup_user(self, user_id, setup_data)` | Yes | Set up user for use this auth module.
|
||||
| `async def async_depose_user(self, user_id)` | Yes | Remove user information from this auth module.
|
||||
| `async def async_is_user_setup(self, user_id)` | Yes | Return whether user is set up.
|
||||
| `async def async_validation(self, user_id, user_input)` | Yes | Given a user_id and user input, return valiidation result.
|
||||
|
||||
## Setup Flow
|
||||
|
||||
Before user can use a multi-factor auth module, it has to be enabled or set up. All availiable modules will be listed in user profile page, user can enable the module he/she wants to use. A setup data entry flow will guide user finish the neccessary steps.
|
||||
|
||||
Each MFA module need to implement a setup flow handler extends from `mfa_modules.SetupFlow` (if only one simple setup step need, `SetupFlow` can be used as well). For example for Google Authenticator (TOTP, Time-based One Time Password) module, the flow will need to be:
|
||||
- Generate a secret and store it on instance of setup flow
|
||||
- Return `async_show_form` with a QR code in the description (injected as base64 via `description_placeholders`)
|
||||
- User scans code and enters a code to verify it scanned correctly and clock in synced
|
||||
- TOTP module saved the secret along with user_id, module is enabled for user
|
||||
|
||||
## Workflow
|
||||
|
||||
> TODO: draw a diagram
|
||||
|
||||
User == select auth provider ==> LoginFlow.init == input/validate username/password ==> LoginFlow.finish ==> if user enabled mfa ==> LoginFlow.select_mfa_module ==> LoginFlow.mfa == input/validate MFA code ==> LoginFlow.finish ==> Done
|
||||
|
||||
## Configuration example
|
||||
|
||||
```yaml
|
||||
# configuration.xml
|
||||
homeassistant:
|
||||
auth_providers:
|
||||
- type: homeassistant
|
||||
- type: legacy_api_password
|
||||
auth_mfa_modules:
|
||||
- type: totp
|
||||
- type: insecure_example
|
||||
users: [{'user_id': 'a_32_bytes_length_user_id', 'pin': '123456'}]
|
||||
auth:
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Validation session
|
||||
|
||||
Not like auth provider, auth module use session to manage the validation. After auth provider validated, mfa module will create a validation session, include an experiation time and user_id from auth provider validate result. Mutli-factor auth moudle will not only verify the user input, and also verify the session is not experied. The validatoin session data storges in login flow instance.
|
44
website/versioned_docs/version-0.77.0/auth_auth_provider.md
Normal file
44
website/versioned_docs/version-0.77.0/auth_auth_provider.md
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Authentication Providers
|
||||
id: version-0.77.0-auth_auth_provider
|
||||
original_id: auth_auth_provider
|
||||
---
|
||||
|
||||
Authentication providers confirm the identity of users. The user proofs their identity by going through the login flow for an auth provider. The auth provider defines the login flow and can ask the user all information this needs. This will commonly be username and password but could also include a 2FA token or other challenges.
|
||||
|
||||
Once an authentication provider has confirmed the identity of a user, it will pass that on to Home Assistant in the form of a Credentials object.
|
||||
|
||||
## Defining an auth provider
|
||||
|
||||
> 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`.
|
||||
|
||||
For an example of a fully implemented auth provider, please see [insecure_example.py](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/auth/providers/insecure_example.py).
|
||||
|
||||
Auth providers shall extend the following methods of `AuthProvider` class.
|
||||
|
||||
| method | Required | Description
|
||||
| ------ | -------- | -----------
|
||||
| async def async_login_flow(self) | Yes | Return an instance of the login flow for a user to identify itself.
|
||||
| async def async_get_or_create_credentials(self, flow_result) | Yes | Given the result of a login flow, return a credentials object. This can either be an existing one or a new one.
|
||||
| async def async_user_meta_for_credentials(credentials) | No | Callback called Home Assistant is going to create a user from a Credentials object. Can be used to populate extra fields for the user.
|
||||
|
||||
Auth providers shall extend the following methods of `LoginFlow` class.
|
||||
|
||||
| method | Required | Description
|
||||
| ------ | -------- | -----------
|
||||
| async def async_step_init(self, user_input=None) | Yes | Handle the login form, see more detail in below.
|
||||
|
||||
## async_step_init of LoginFlow
|
||||
|
||||
> 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:
|
||||
|
||||
```python
|
||||
async def async_step_init(self, user_input=None):
|
||||
return self.async_show_form(step_id='init', data_schema='some schema to construct ui form') if user_input is None
|
||||
return self.async_show_form(step_id='init', errors) if user_input is invalid
|
||||
return await self.async_finish(username) if user_input is valid
|
||||
```
|
40
website/versioned_docs/version-0.77.0/auth_index.md
Normal file
40
website/versioned_docs/version-0.77.0/auth_index.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Authentication
|
||||
sidebar_label: Introduction
|
||||
id: version-0.77.0-auth_index
|
||||
original_id: auth_index
|
||||
---
|
||||
|
||||
Home Assistant has a built-in authentication system allowing different users to interact with Home Assistant. The authentication system consist of various parts.
|
||||
|
||||

|
||||
|
||||
## Authentication providers
|
||||
|
||||
An authentication provider is used for users to authenticate themselves. It's up to the authentication provider to choose the method of authentication and the backend to use. By default we enable the built-in Home Assistant authentication provider which stores the users securely inside your configuration directory.
|
||||
|
||||
The authentication providers that Home Assistant will use are specified inside `configuration.yaml`. It is possible to have multiple instances of the same authentication provider active. In that case, each will be identified by a unique identifier. Authentication providers of the same type will not share credentials.
|
||||
|
||||
## Credentials
|
||||
|
||||
Credentials store the authentication of a user with a specific authentication provider. It is produced when a user successfully authenticates. It will allow the system to find the user in our system. If the user does not exist, a new user will be created. This user will not be activated but will require approval by the owner.
|
||||
|
||||
It is possible for a user to have multiple credentials linked to it. However, it can only have a single credential per specific authentication provider.
|
||||
|
||||
## Users
|
||||
|
||||
Each person is a user in the system. To log in as a specific user, authenticate with any of the authentication providers that are linked to this user. When a user logs in, it will get a refresh and an access token to make requests to Home Assistant.
|
||||
|
||||
### Owner
|
||||
|
||||
The first user to log in to Home Assistant will be marked as the owner. This user is able to manage users.
|
||||
|
||||
## Clients
|
||||
|
||||
Clients are applications that users use to access the Home Assistant API. Each client has a client identifier, a redirect uri and an optional client secret. The redirect uri is used to redirect the user after it has successfully authorized.
|
||||
|
||||
## Access and refresh tokens
|
||||
|
||||
The client will be provided with an authorization code when a user successfully authorizes with Home Assistant. This code can be used to retrieve an access and a refresh token. The access token will have a limited lifetime while refresh tokens will remain valid until a user deletes it.
|
||||
|
||||
The access token is used to access the Home Assistant APIs. The refresh token is used to retrieve a new valid access token.
|
@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Config Flow Handlers
|
||||
id: version-0.77.0-config_entries_config_flow_handler
|
||||
original_id: config_entries_config_flow_handler
|
||||
---
|
||||
|
||||
Config Entries uses the [Data Flow Entry framework](data_entry_flow_index.md) to allow users to create entries. Components that want to support config entries will need to define a Config Flow Handler. This handler will manage the creation of entries from user input, discovery or other sources (like hassio).
|
||||
|
||||
Config Flow Handlers controll the data that is stored in a config entry. This means that there is no need to validate that the config is correct when Home Assistant starts up. It will also prevent breaking changes, because we will be able to migrate configuration entries to new formats if the version changes.
|
||||
|
||||
When instantiating the handler, Home Assistant will make sure to load all dependencies and install the requirements of the component.
|
||||
|
||||
To register your config flow handler with Home Assistant, register it with the config entries `HANDLERS` registry:
|
||||
|
||||
```python
|
||||
from homeassistant import config_entries, data_entry_flow
|
||||
|
||||
@config_entries.HANDLERS.register(DOMAIN)
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
```
|
||||
|
||||
> Temporarily, all config flow handlers will also need to add their component name to the `FLOWS` constant in `homeassistant/config_entries.py`. We are working on automating discovery.
|
||||
|
||||
## Initializing a config flow from an external source
|
||||
|
||||
You might want to initialize a config flow programmatically. For example, if we discover a device on the network that requires user interaction to finish setup. To do so, pass a source parameter and optional user input when initializing the config entry:
|
||||
|
||||
```python
|
||||
await hass.config_entries.flow.async_init(
|
||||
'hue', data=discovery_info,
|
||||
context={'source': config_entries.SOURCE_DISCOVERY})
|
||||
```
|
||||
|
||||
The config flow handler will need to add a step to support the given source. The step should follow the same return values as a normal step.
|
||||
|
||||
```python
|
||||
@config_entries.HANDLERS.register(DOMAIN)
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_discovery(self, info):
|
||||
# Handle discovery info
|
||||
```
|
||||
|
||||
If the result of the step is to show a form, the user will be able to continue the flow from the config panel.
|
||||
|
||||
## Translations
|
||||
|
||||
Translations for the config flow handlers are defined under the `config` key in the component translation file `strings.json`. Example of the Hue component:
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"title": "Philips Hue Bridge",
|
||||
"step": {
|
||||
"init": {
|
||||
"title": "Pick Hue bridge",
|
||||
"data": {
|
||||
"host": "Host"
|
||||
}
|
||||
},
|
||||
"link": {
|
||||
"title": "Link Hub",
|
||||
"description": "Press the button on the bridge to register Philips Hue with Home Assistant.\n\n"
|
||||
}
|
||||
},
|
||||
"error": {
|
||||
"register_failed": "Failed to register, please try again",
|
||||
"linking": "Unknown linking error occurred."
|
||||
},
|
||||
"abort": {
|
||||
"discover_timeout": "Unable to discover Hue bridges",
|
||||
"no_bridges": "No Philips Hue bridges discovered",
|
||||
"all_configured": "All Philips Hue bridges are already configured",
|
||||
"unknown": "Unknown error occurred",
|
||||
"cannot_connect": "Unable to connect to the bridge",
|
||||
"already_configured": "Bridge is already configured"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
223
website/versioned_docs/version-0.77.0/data_entry_flow_index.md
Normal file
223
website/versioned_docs/version-0.77.0/data_entry_flow_index.md
Normal file
@ -0,0 +1,223 @@
|
||||
---
|
||||
title: Data Entry Flow
|
||||
sidebar_label: Introduction
|
||||
id: version-0.77.0-data_entry_flow_index
|
||||
original_id: data_entry_flow_index
|
||||
---
|
||||
|
||||
Data Entry Flow is a data entry framework that is part of Home Assistant. Data entry is done via data entry flows. A flow can represent a simple login form or a multi-step setup wizard for a component. A Flow Manager is managing all flows that are in progress and handles creation of new flows.
|
||||
|
||||
Data Entry Flow is being used in Home Assistant to create config entries.
|
||||
|
||||
## Flow Manager
|
||||
|
||||
This is the class that manages the flows that are in progress. When instantiating one, you pass in two async callbacks:
|
||||
|
||||
```python
|
||||
async def async_create_flow(handler, context=context, data=data)
|
||||
```
|
||||
|
||||
The manager delegates instantiating of config flow handlers to this async callback. This allows the parent of the manager to define their own way of finding handlers and preparing a handler for instantiation. For example, in the case of the config entry manager, it will make sure that the dependencies and requirements are setup.
|
||||
|
||||
```python
|
||||
async def async_finish_flow(flow, result)
|
||||
```
|
||||
|
||||
This async callback is called when a flow is finished or aborted. i.e. `result['type'] in [RESULT_TYPE_CREATE_ENTRY, RESULT_TYPE_ABORT]`. The callback function can modify result and return it back, if the result type changed to `RESULT_TYPE_FORM`, the flow will continue running, display another form.
|
||||
|
||||
If the result type is `RESULT_TYPE_FORM`, the result should like:
|
||||
```python
|
||||
{
|
||||
# The result type of the flow
|
||||
'type': RESULT_TYPE_FORM,
|
||||
# the id of the flow
|
||||
'flow_id': 'abcdfgh1234,
|
||||
# handler name
|
||||
'handler': 'hue',
|
||||
# name of the step, flow.async_step_[step_id] will be called when form submitted
|
||||
'step_id': 'init',
|
||||
# a voluptuous schema to build and validate user input
|
||||
'data_schema': vol.Schema(),
|
||||
# an errors dict, None if no errors
|
||||
'errors': errors,
|
||||
# a detail information about the step
|
||||
'description_placeholders': description_placeholders,
|
||||
}
|
||||
```
|
||||
|
||||
If the result type is `RESULT_TYPE_CREATE_ENTRY`, the result should like:
|
||||
```python
|
||||
{
|
||||
# Data schema version of the entry
|
||||
'version': 2,
|
||||
# The result type of the flow
|
||||
'type': RESULT_TYPE_CREATE_ENTRY,
|
||||
# the id of the flow
|
||||
'flow_id': 'abcdfgh1234,
|
||||
# handler name
|
||||
'handler': 'hue',
|
||||
# title and data as created by the handler
|
||||
'title': 'Some title',
|
||||
'result': {
|
||||
'some': 'data'
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
If the result type is `RESULT_TYPE_ABORT`, the result should like:
|
||||
```python
|
||||
{
|
||||
# The result type of the flow
|
||||
'type': RESULT_TYPE_ABORT,
|
||||
# the id of the flow
|
||||
'flow_id': 'abcdfgh1234,
|
||||
# handler name
|
||||
'handler': 'hue',
|
||||
# the abort reason
|
||||
'reason': 'already_configured',
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Flow Handler
|
||||
|
||||
Flow handlers will handle a single flow. A flow contains one or more steps. When a flow is instantiated, the `FlowHandler.init_step` step will be called. Each step has three different possible results: "Show Form", "Abort" and "Create Entry".
|
||||
|
||||
At a minimum, each flow handler will have to define a version number and a step. This doens't have to be `init`, as `async_create_flow` can assign `init_step` depends on diffreent workflow, for example in configuration, `context.source` will be use as `init_step`.
|
||||
|
||||
The bare minimum config flow:
|
||||
|
||||
```python
|
||||
from homeassistant import data_entry_flow
|
||||
|
||||
@config_entries.HANDLERS.register(DOMAIN)
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
# The schema version of the entries that it creates
|
||||
# Home Assistant will call your migrate method if the version changes
|
||||
# (this is not implemented yet)
|
||||
VERSION = 1
|
||||
|
||||
async def async_step_user(self, user_input=None):
|
||||
# Do something
|
||||
```
|
||||
|
||||
### Show Form
|
||||
|
||||
This result type will show a form to the user to fill in. You define the current step, the schema of the data (using voluptuous) and optionally a dictionary of errors. Title and description of the step will be provided via the translation file. Where this is defined depends on the context of the data entry flow.
|
||||
|
||||
```python
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_user(self, user_input=None):
|
||||
# Use OrderedDict to guarantee order of the form shown to the user
|
||||
data_schema = OrderedDict()
|
||||
data_schema[vol.Required('username')] = str
|
||||
data_schema[vol.Required('password')] = str
|
||||
|
||||
return self.async_show_form(
|
||||
step_id='init',
|
||||
data_schema=vol.Schema(data_schema)
|
||||
)
|
||||
```
|
||||
|
||||
After the user has filled in the form, the step method will be called again and the user input is passed in. Your step will only be called if the user input passes your data schema. When the user passes in data, you will have to do extra validation of the data. For example, you can verify that the passed in username and password are valid.
|
||||
|
||||
If something is wrong, you can return a dictionary with errors. Each key in the error dictionary refers to a field name that contains the error. Use the key `base` if you want to show an error unrelated to a specific field. The specified errors need to refer to a key in a translation file.
|
||||
|
||||
```python
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_user(self, user_input=None):
|
||||
errors = {}
|
||||
if user_input is not None:
|
||||
# Validate user input
|
||||
valid = await is_valid(user_input)
|
||||
if valid:
|
||||
# See next section on create entry usage
|
||||
return self.create_entry(...)
|
||||
|
||||
errors['base'] = 'auth_error'
|
||||
|
||||
# Use OrderedDict to guarantee order of the form shown to the user
|
||||
data_schema = OrderedDict()
|
||||
data_schema[vol.Required('username')] = str
|
||||
data_schema[vol.Required('password')] = str
|
||||
|
||||
return self.async_show_form(
|
||||
step_id='init',
|
||||
data_schema=vol.Schema(data_schema),
|
||||
errors=errors
|
||||
)
|
||||
```
|
||||
|
||||
#### Multi-step flows
|
||||
|
||||
If the user input passes validation, you can again return one of the three return values. If you want to navigate the user to the next step, return the return value of that step:
|
||||
|
||||
```python
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_init(self, user_input=None):
|
||||
errors = {}
|
||||
if user_input is not None:
|
||||
# Validate user input
|
||||
valid = await is_valid(user_input)
|
||||
if valid:
|
||||
# Store info to use in next step
|
||||
self.init_info = user_input
|
||||
# Return the form of the next step
|
||||
return await self.async_step_account()
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
### Create Entry
|
||||
|
||||
When the result is "Create Entry", an entry will be created and passed to the parent of the flow manager. A success message is shown to the user and the flow is finished. You create an entry by passing a title and data. The title can be used in the UI to indicate to the user which entry it is. Data can be any data type, as long as it is JSON serializable.
|
||||
|
||||
```python
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_user(self, user_input=None):
|
||||
return self.create_entry(
|
||||
title='Title of the entry',
|
||||
data={
|
||||
'something_special': user_input['username']
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Abort
|
||||
|
||||
When a flow cannot be finished, you need to abort it. This will finish the flow and inform the user that the flow has finished. Reasons for a flow to not be able to finish can be that a device is already configured or not compatible with Home Assistant.
|
||||
|
||||
```python
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_user(self, user_input=None):
|
||||
return self.async_abort(
|
||||
reason='not_supported'
|
||||
)
|
||||
```
|
||||
|
||||
## Translations
|
||||
|
||||
Data entry flows depend on translations for showing the text in the forms. It depends on the parent of a data entry flow manager where this is stored.
|
||||
|
||||
## Initializing a config flow from an external source
|
||||
|
||||
You might want to initialize a config flow programmatically. For example, if we discover a device on the network that requires user interaction to finish setup. To do so, pass a source parameter and optional user input when initializing a flow:
|
||||
|
||||
```python
|
||||
await flow_mgr.async_init('hue', context={'source': data_entry_flow.SOURCE_DISCOVERY}, data=discovery_info)
|
||||
```
|
||||
|
||||
The config flow handler will not start with the `init` step. Instead, it will be instantiated with a step name equal to the source. The step should follow the same return values as a normal step.
|
||||
|
||||
```python
|
||||
class ExampleConfigFlow(data_entry_flow.FlowHandler):
|
||||
|
||||
async def async_step_discovery(self, info):
|
||||
# Handle discovery info
|
||||
```
|
139
website/versioned_docs/version-0.77.0/frontend_data.md
Normal file
139
website/versioned_docs/version-0.77.0/frontend_data.md
Normal file
@ -0,0 +1,139 @@
|
||||
---
|
||||
title: Frontend data
|
||||
sidebar_label: Data
|
||||
id: version-0.77.0-frontend_data
|
||||
original_id: frontend_data
|
||||
---
|
||||
|
||||
The frontend passes a single `hass` object around. This object contains the latest state and allows you to send commands back to the server.
|
||||
|
||||
Whenever a state changes, a new version of the objects that changed are created. So you can easily see if something has changed by doing a strict equality check:
|
||||
|
||||
```js
|
||||
const changed = newVal !== oldVal;
|
||||
```
|
||||
|
||||
## Data
|
||||
|
||||
### `hass.states`
|
||||
|
||||
An object containing the states of all entities in Home Assistant. The key is the entity_id, the value is the state object.
|
||||
|
||||
```json
|
||||
{
|
||||
"sun.sun": {
|
||||
"entity_id": "sun.sun",
|
||||
"state": "above_horizon",
|
||||
"attributes": {
|
||||
"next_dawn": "2018-08-18T05:39:19+00:00",
|
||||
"next_dusk": "2018-08-17T18:28:52+00:00",
|
||||
"next_midnight": "2018-08-18T00:03:51+00:00",
|
||||
"next_noon": "2018-08-18T12:03:58+00:00",
|
||||
"next_rising": "2018-08-18T06:00:33+00:00",
|
||||
"next_setting": "2018-08-17T18:07:37+00:00",
|
||||
"elevation": 60.74,
|
||||
"azimuth": 297.69,
|
||||
"friendly_name": "Sun"
|
||||
},
|
||||
"last_changed": "2018-08-17T13:46:59.083836+00:00",
|
||||
"last_updated": "2018-08-17T13:49:30.378101+00:00",
|
||||
"context": {
|
||||
"id": "74c2b3b429c844f18e59669e4b41ec6f",
|
||||
"user_id": null
|
||||
},
|
||||
},
|
||||
"light.ceiling_lights": {
|
||||
"entity_id": "light.ceiling_lights",
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"min_mireds": 153,
|
||||
"max_mireds": 500,
|
||||
"brightness": 180,
|
||||
"color_temp": 380,
|
||||
"hs_color": [
|
||||
56,
|
||||
86
|
||||
],
|
||||
"rgb_color": [
|
||||
255,
|
||||
240,
|
||||
35
|
||||
],
|
||||
"xy_color": [
|
||||
0.459,
|
||||
0.496
|
||||
],
|
||||
"white_value": 200,
|
||||
"friendly_name": "Ceiling Lights",
|
||||
"supported_features": 151
|
||||
},
|
||||
"last_changed": "2018-08-17T13:46:59.129248+00:00",
|
||||
"last_updated": "2018-08-17T13:46:59.129248+00:00",
|
||||
"context": {
|
||||
"id": "2c6bbbbb66a84a9dae097b6ed6c93383",
|
||||
"user_id": null
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `hass.user`
|
||||
|
||||
The logged in user.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "758186e6a1854ee2896efbd593cb542c",
|
||||
"name": "Paulus",
|
||||
"is_owner": true,
|
||||
"credentials": [
|
||||
{
|
||||
"auth_provider_type": "homeassistant",
|
||||
"auth_provider_id": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
All methods starting with `call` are async methods. This means that they will return a `Promise` that will resolve with the result of the call.
|
||||
|
||||
### `hass.callService(domain, service, data)`
|
||||
|
||||
Call a service on the backend.
|
||||
|
||||
```js
|
||||
hass.callService('light', 'turn_on', {
|
||||
entity_id: 'light.kitchen'
|
||||
});
|
||||
```
|
||||
|
||||
### `hass.callWS(message)`
|
||||
|
||||
Call a WebSocket command on the backend.
|
||||
|
||||
```js
|
||||
this.hass.callWS({
|
||||
type: 'config/auth/create',
|
||||
name: 'Paulus',
|
||||
}).then(userResponse =>
|
||||
console.log("Created user", userResponse.user.id));
|
||||
```
|
||||
|
||||
### `hass.callApi(method, path, data)`
|
||||
|
||||
Call an API on the Home Assistant server. For example, if you want to fetch all Hass.io snapshots by issuing a GET request to `/api/hassio/snapshots`:
|
||||
|
||||
```js
|
||||
hass.callApi('get', 'hassio/snapshots')
|
||||
.then(snapshots => console.log('Received snapshots!', snapshots));
|
||||
```
|
||||
|
||||
If you need to pass in data, pass a third argument:
|
||||
|
||||
```js
|
||||
hass.callApi('delete', 'notify.html5', { subscription: 'abcdefgh' });
|
||||
```
|
||||
|
||||
_We're moving away from API calls and are migrating everything to `hass.callWS(message)` calls._
|
152
website/versioned_sidebars/version-0.77.0-sidebars.json
Normal file
152
website/versioned_sidebars/version-0.77.0-sidebars.json
Normal file
@ -0,0 +1,152 @@
|
||||
{
|
||||
"version-0.77.0-Architecture": {
|
||||
"Architecture": [
|
||||
"version-0.77.0-architecture_index",
|
||||
"version-0.77.0-architecture_components",
|
||||
"version-0.77.0-architecture_entities",
|
||||
"version-0.77.0-architecture_hassio"
|
||||
],
|
||||
"Entities": [
|
||||
"version-0.77.0-entity_index",
|
||||
"version-0.77.0-entity_alarm_control_panel",
|
||||
"version-0.77.0-entity_binary_sensor",
|
||||
"version-0.77.0-entity_climate",
|
||||
"version-0.77.0-entity_cover",
|
||||
"version-0.77.0-entity_fan",
|
||||
"version-0.77.0-entity_light",
|
||||
"version-0.77.0-entity_lock",
|
||||
"version-0.77.0-entity_media_player",
|
||||
"version-0.77.0-entity_remote",
|
||||
"version-0.77.0-entity_sensor",
|
||||
"version-0.77.0-entity_switch",
|
||||
"version-0.77.0-entity_vacuum",
|
||||
"version-0.77.0-entity_weather"
|
||||
],
|
||||
"Authentication": [
|
||||
"version-0.77.0-auth_index",
|
||||
"version-0.77.0-auth_api",
|
||||
"version-0.77.0-auth_auth_provider",
|
||||
"version-0.77.0-auth_auth_module"
|
||||
],
|
||||
"Configuration.yaml": [
|
||||
"version-0.77.0-configuration_yaml_index"
|
||||
],
|
||||
"Config Entries": [
|
||||
"version-0.77.0-config_entries_index",
|
||||
"version-0.77.0-config_entries_config_flow_handler"
|
||||
],
|
||||
"Data Entry Flow": [
|
||||
"version-0.77.0-data_entry_flow_index"
|
||||
],
|
||||
"Entity Registry": [
|
||||
"version-0.77.0-entity_registry_index"
|
||||
]
|
||||
},
|
||||
"version-0.77.0-Extending Frontend": {
|
||||
"Frontend": [
|
||||
"version-0.77.0-frontend_index",
|
||||
"version-0.77.0-frontend_architecture",
|
||||
"version-0.77.0-frontend_development",
|
||||
"version-0.77.0-frontend_data"
|
||||
],
|
||||
"Extending the frontend": [
|
||||
"version-0.77.0-frontend_add_card",
|
||||
"version-0.77.0-frontend_add_more_info",
|
||||
"version-0.77.0-frontend_add_websocket_api"
|
||||
],
|
||||
"Custom UI": [
|
||||
"version-0.77.0-lovelace_custom_card",
|
||||
"version-0.77.0-frontend_creating_custom_ui",
|
||||
"version-0.77.0-frontend_creating_custom_panels"
|
||||
]
|
||||
},
|
||||
"version-0.77.0-Extending HASS": {
|
||||
"Developing a feature": [
|
||||
"version-0.77.0-development_index",
|
||||
"version-0.77.0-development_environment",
|
||||
"version-0.77.0-development_submitting",
|
||||
"version-0.77.0-development_checklist",
|
||||
"version-0.77.0-development_guidelines",
|
||||
"version-0.77.0-development_testing",
|
||||
"version-0.77.0-development_catching_up",
|
||||
"version-0.77.0-development_validation",
|
||||
"version-0.77.0-development_typing"
|
||||
],
|
||||
"Development 101": [
|
||||
"version-0.77.0-dev_101_index",
|
||||
"version-0.77.0-dev_101_hass",
|
||||
"version-0.77.0-dev_101_events",
|
||||
"version-0.77.0-dev_101_states",
|
||||
"version-0.77.0-dev_101_services",
|
||||
"version-0.77.0-dev_101_config"
|
||||
],
|
||||
"Creating Platforms": [
|
||||
"version-0.77.0-creating_platform_index",
|
||||
"version-0.77.0-creating_platform_code_review",
|
||||
"version-0.77.0-creating_platform_example_light",
|
||||
"version-0.77.0-creating_platform_example_sensor"
|
||||
],
|
||||
"Creating Components": [
|
||||
"version-0.77.0-creating_component_index",
|
||||
"version-0.77.0-creating_component_code_review",
|
||||
"version-0.77.0-creating_component_deps_and_reqs",
|
||||
"version-0.77.0-creating_component_events",
|
||||
"version-0.77.0-creating_component_states",
|
||||
"version-0.77.0-creating_component_discovery",
|
||||
"version-0.77.0-creating_component_loading",
|
||||
"version-0.77.0-creating_component_generic_discovery"
|
||||
]
|
||||
},
|
||||
"version-0.77.0-Misc": {
|
||||
"Introduction": [
|
||||
"version-0.77.0-misc"
|
||||
],
|
||||
"External API": [
|
||||
"version-0.77.0-external_api_rest",
|
||||
"version-0.77.0-external_api_websocket",
|
||||
"version-0.77.0-external_api_server_sent_events"
|
||||
],
|
||||
"Internationalization": [
|
||||
"version-0.77.0-internationalization_index",
|
||||
"version-0.77.0-internationalization_backend_localization",
|
||||
"version-0.77.0-internationalization_custom_component_localization",
|
||||
"version-0.77.0-internationalization_translation"
|
||||
],
|
||||
"Documentation": [
|
||||
"version-0.77.0-documentation_index",
|
||||
"version-0.77.0-documentation_standards",
|
||||
"version-0.77.0-documentation_create_page"
|
||||
],
|
||||
"Intents": [
|
||||
"version-0.77.0-intent_index",
|
||||
"version-0.77.0-intent_firing",
|
||||
"version-0.77.0-intent_handling",
|
||||
"version-0.77.0-intent_conversation",
|
||||
"version-0.77.0-intent_builtin"
|
||||
],
|
||||
"asyncio": [
|
||||
"version-0.77.0-asyncio_index",
|
||||
"version-0.77.0-asyncio_101",
|
||||
"version-0.77.0-asyncio_categorizing_functions",
|
||||
"version-0.77.0-asyncio_working_with_async"
|
||||
],
|
||||
"Hass.io": [
|
||||
"version-0.77.0-hassio_debugging",
|
||||
"version-0.77.0-hassio_hass"
|
||||
],
|
||||
"Hass.io Add-Ons": [
|
||||
"version-0.77.0-hassio_addon_index",
|
||||
"version-0.77.0-hassio_addon_tutorial",
|
||||
"version-0.77.0-hassio_addon_config",
|
||||
"version-0.77.0-hassio_addon_communication",
|
||||
"version-0.77.0-hassio_addon_testing",
|
||||
"version-0.77.0-hassio_addon_publishing",
|
||||
"version-0.77.0-hassio_addon_presentation",
|
||||
"version-0.77.0-hassio_addon_repository"
|
||||
],
|
||||
"Maintainer docs": [
|
||||
"version-0.77.0-maintenance",
|
||||
"version-0.77.0-releasing"
|
||||
]
|
||||
}
|
||||
}
|
@ -1,4 +1,5 @@
|
||||
[
|
||||
"0.77.0",
|
||||
"0.76.0",
|
||||
"0.75.0",
|
||||
"0.74.0",
|
||||
|
Loading…
x
Reference in New Issue
Block a user