diff --git a/website/versioned_docs/version-0.76.0/auth_api.md b/website/versioned_docs/version-0.76.0/auth_api.md new file mode 100644 index 00000000..36ae3a05 --- /dev/null +++ b/website/versioned_docs/version-0.76.0/auth_api.md @@ -0,0 +1,128 @@ +--- +title: Authentication API +sidebar_label: API +id: version-0.76.0-auth_api +original_id: auth_api +--- + +This page will describe the steps required for your application to authorize against and integrate with Home Assistant instances. + +Each user has their own instance of Home Assistant which gives each user control over their own data. However, we also wanted to make it easy for third party developers to create applications that allow users to integrate with Home Assistant. To achieve this, we have adopted the [OAuth 2 specification][oauth2-spec] combined with the [OAuth 2 IndieAuth extension][indieauth-spec] for generating clients. + +## Clients + +Before you can ask the user to authorize their instance with your application, you will need a client. In traditional OAuth2, the server needs to generate a client before a user can authorize. However, as each server belongs to a user, we've adopted a slightly different approach from [IndieAuth][indieauth-clients]. + +The client ID you need to use is the website of your application. The redirect url has to be of the same host and port as the client ID. For example: + + - client id: `https://www.my-application.io` + - redirect uri: `https://www.my-application.io/hass/auth_callback` + +If you require a different redirect url (ie, if building a native app), you can add an HTML tag to the content of the website of your application (the client ID) with an approved redirect url. For example: + +```html + +``` + +Home Assistant will scan the first 10kB of a website for these tags. + +## Authorize + +[![Authorization flow sequence diagram](/img/en/auth/authorize_flow.png)](https://www.websequencediagrams.com/?lz=dGl0bGUgQXV0aG9yaXphdGlvbiBGbG93CgpVc2VyIC0-IENsaWVudDogTG9nIGludG8gSG9tZSBBc3Npc3RhbnQKABoGIC0-IFVzZXI6AEMJZSB1cmwgAD4JACgOOiBHbyB0bwAeBWFuZCBhAC0ICgBQDgB1DACBFw5jb2RlAHELAE4RZXQgdG9rZW5zIGZvcgAoBgBBGlQAJQUK&s=qsd) + +> All example URLs here are shown with extra spaces and new lines for clarity. Those should not be in the final url. + +The authorize url should contain `client_id` and `redirect_uri` as query parameters. + +``` +http://your-instance.com/auth/authorize? + client_id=ABCDE& + redirect_uri=https%3A%2F%2Fexample.com%2Fhass_callback +``` + +Optionally you can also include a `state` parameter, this will be added to the redirect uri. The state is perfect to store the instance url that you are authenticating with. Example: + +``` +http://your-instance.com/auth/authorize? + client_id=ABCDE& + redirect_uri=https%3A%2F%2Fexample.com%2Fhass_callback& + state=http%3A%2F%2Fhassio.local%3A8123 +``` + +The user will navigate to this link and be presented with instructions to log in and authorize your application. Once authorized, the user will be redirected back to the passed in redirect uri with the authorization code and state as part of the query parameters. Example: + +``` +https://example.com/hass_callback? + code=12345& + state=http%3A%2F%2Fhassio.local%3A8123 +``` + +This authorization code can be exchanged for tokens by sending it to the token endpoint (see next section). + +## Token + +The token endpoint returns tokens given valid grants. This grant is either an authorization code retrieved from the authorize endpoint or a refresh token. + +All interactions with this endpoint need to be HTTP POST requests to `http://your-instance.com/auth/token` with the request body encoded in `application/x-www-form-urlencoded`. + +### 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. + +Use the grant type `authorization_code` to retrieve the tokens after a user has successfully finished the authorize step. The request body is: + +``` +grant_type=authorization_code& +code=12345& +client_id=https%3A%2F%2Fwww.home-assistant.io%2Fios +``` + +The return response will be an access and refresh token: + +```json +{ + "access_token": "ABCDEFGH", + "expires_in": 1800, + "refresh_token": "IJKLMNOPQRST", + "token_type": "Bearer" +} +``` + +The access token is a short lived token that can be used to access the API. The refresh token can be used to fetch new access tokens. The `expires_in` value is seconds that the access token is valid. + +### Refresh token + +Once you have retrieved a refresh token via the grant type `authorization_code`, you can use it to fetch new access tokens. The request body is: + +``` +grant_type=refresh_token& +refresh_token=IJKLMNOPQRST +``` + +The return response will be an access token: + +```json +{ + "access_token": "ABCDEFGH", + "expires_in": 1800, + "token_type": "Bearer" +} +``` + +## Making authenticated requests + +Once you have an access token, you can make authenticated requests to the Home Assistant APIs. + +For the websocket connection, pass the access token in the [authentication message](https://developers.home-assistant.io/docs/en/external_api_websocket.html#authentication-phase). + +For HTTP requests, pass the token type and access token as the authorization header: + +``` +Authorization: Bearer ABCDEFGH +``` + +If the access token is no longer valid, you will get a response with HTTP status code 401 unauthorized. This means that you will need to refresh the token. If the refresh token doesn't work, the tokens are no longer valid and so the user is no longer logged in. You should clear the user's data and ask the user to authorize again. + +[oauth2-spec]: https://tools.ietf.org/html/rfc6749 +[indieauth-spec]: https://indieauth.spec.indieweb.org/ +[indieauth-clients]: https://indieauth.spec.indieweb.org/#client-identifier diff --git a/website/versioned_docs/version-0.76.0/auth_auth_provider.md b/website/versioned_docs/version-0.76.0/auth_auth_provider.md new file mode 100644 index 00000000..a19bc21d --- /dev/null +++ b/website/versioned_docs/version-0.76.0/auth_auth_provider.md @@ -0,0 +1,26 @@ +--- +title: Authentication Providers +id: version-0.76.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/.py`. The auth provider module will need to provide an implementation of the `AuthProvider` class and contain a credential flow. This flow is what asks user for information and validates it. + +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 can extend the following methods. + +| method | Required | Description +| ------ | -------- | ----------- +| async def async_credential_flow(self) | Yes | Return an instance of the credential flow for a user to identify itself. +| async def async_get_or_create_credentials(self, flow_result) | Yes | Given the result of a credential flow, return a credentials object. This can either be an existing one or a new one. +| async def async_initialize(self) | No | Callback callled once before interacting with the auth provider for the first time. +| 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. diff --git a/website/versioned_docs/version-0.76.0/development_environment.md b/website/versioned_docs/version-0.76.0/development_environment.md new file mode 100644 index 00000000..42e60d9e --- /dev/null +++ b/website/versioned_docs/version-0.76.0/development_environment.md @@ -0,0 +1,104 @@ +--- +title: Set up Development Environment +id: version-0.76.0-development_environment +original_id: development_environment +--- + +You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up. + +## Preparing your environment + +### Developing on Linux + +Install the core dependencies. + +```bash +$ sudo apt-get install python3-pip python3-dev python3-venv +``` + +In order to run `script/setup` below you will need some more dependencies. + +```bash +$ sudo apt-get install libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev +``` + +> Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: `sudo yum install epel-release && sudo yum install python36 python36-devel mysql-devel gcc` + +Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](frontend_index.md) section to learn more. + +### Developing on Windows + +If you are using Windows as a development platform, make sure that you have the correct Microsoft [Visual C++ build tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) installed. The installation of the most requirements and validation using `tox` will fail if this is not done correctly. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. + +Due to Home Assistant is mainly designed and developed on Linux distributions it is not recommended to develop on Windows machines. However on Windows 10 machines you should decide to set up a [Linux subsystem](https://docs.microsoft.com/de-de/windows/wsl/install-win10). + +Setup Linux subsystem. + +```bash +$ sudo apt-get update +$ sudo apt-get upgrade +$ echo 'export DISPLAY=:0' >> ~/.bashrc && . ~/.bashrc +$ sudo apt-get install xubuntu-desktop -y +``` + +It is recommended using [PyCharm](https://www.jetbrains.com/pycharm/download/) as debugger. Download and start PyCharm. + +```bash +$ wget https://download.jetbrains.com/python/pycharm-community-20XX.X.tar.gz +$ tar -xzf pycharm-community-20XX.X +$ ./pycharm.sh +``` + +In order to display the PyCharm GUI on Windows you need to run a X-Server like [VcXserv](https://sourceforge.net/projects/vcxsrv/). + +Also, make sure to install or upgrade the `setuptools` Python package. It contains compatibility improvements and adds automatic use of compilers: + +```bash +$ pip install --upgrade setuptools +``` + +### Developing on OS X + +Install [Homebrew](https://brew.sh/), then use that to install Python 3: + +```bash +$ brew install python3 +``` + +## Setup Local Repository + +Visit the [Home Assistant repository](https://github.com/home-assistant/home-assistant) and click **Fork**. +Once forked, setup your local copy of the source using the commands: + +```bash +$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git +$ cd home-assistant +$ git remote add upstream https://github.com/home-assistant/home-assistant.git +``` + +## Setting up virtual environment + +To isolate your environment from the rest of the system, set up a [`venv`](https://docs.python.org/3/library/venv.html). Within the `home-assistant` directory, create and activate your virtual environment. + +```bash +$ python3 -m venv . +$ source bin/activate +``` + +Install the requirements with a provided script named `setup`. + +```bash +$ script/setup +``` + +Invoke your installation. + +```bash +$ hass +``` + +## Logging + +By default logging in home-assistant is tuned for operating in production (set to INFO by default, with some modules set to even less verbose logging levels). + +You can use the [logger](https://www.home-assistant.io/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on. diff --git a/website/versioned_docs/version-0.76.0/documentation_create_page.md b/website/versioned_docs/version-0.76.0/documentation_create_page.md new file mode 100644 index 00000000..1cd6c7d7 --- /dev/null +++ b/website/versioned_docs/version-0.76.0/documentation_create_page.md @@ -0,0 +1,121 @@ +--- +title: Create a new page +id: version-0.76.0-documentation_create_page +original_id: documentation_create_page +--- + +For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](https://www.home-assistant.io/components/) and the [Examples section](https://www.home-assistant.io/cookbook/) are generated automatically, so there is no need to add a link to those pages. + +Please honor the [Standards](documentation_standards.md) we have for the documentation. + +If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers. + +```text +--- +layout: page +title: "Awesome Sensor" +description: "home-assistant.io web presence" +date: 2015-06-17 08:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: "0.38" +ha_category: Sensor +--- + +Content...Written in markdown. + +### {% linkable_title Linkable Header %} +... +``` + +There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation. + +A couple of points to remember: + +- Document the needed steps to retrieve API keys or access token for the third party service or device if needed. +- If you're adding a new component, for the `ha_release` part of the header, just increment of the current release. If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`. +- `ha_category:` is needed to list the platform or component in the appropriate category on the website. + +### Configuration + +Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file. + +The **Configuration Variables** section must use the `{% configuration %} ... {% endconfiguration %}` tag. + +```text +{% configuration %} +api_key: + description: The API key to access the service. + required: true + type: string +name: + description: Name to use in the frontend. + required: false + default: The default name to use in the frontend. + type: string +monitored_conditions: + description: Conditions to display in the frontend. + required: true + type: map + keys: + weather: + description: A human-readable text summary. + temperature: + description: The current temperature. +{% endconfiguration %} +``` + +Available keys: + +- **`description:`**: That the variable is about. +- **`required:`**: If the variable is required. + +```text +required: true #=> Required +required: false #=> Optional +required: inclusive #=> Inclusive +required: exclusive #=> Exclusive +required: any string here #=> Any string here +``` +- **`type:`**: The type of the variable. Allowed entries: `string`, `int`, `time`, `template` or `map` (for a list of entries). For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example). +- **`default:`**: The default value for the variable. + +### Embedding Code + +You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in back-ticks. + +When you're writing code that is to be executed on the terminal, prefix it with `$`. + +### Templates + +For the [configuration templating](https://www.home-assistant.io/docs/configuration/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](documentation_standards.md) for further details. + +If you are don't escape templates then they will be rendered and appear blank on the website. + +### HTML + +The direct usage of HTML is supported but not recommended. The note boxes are an exception. + +```html +

+ You need to enable telnet on your router. +

+``` + +### Images, icons and logos + +The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent. + +| Type | Location | +| :----------- |:----------------------------------------------| +| logos | source/images/supported_brands | +| blog | source/images/blog | +| screenshots | source/images/components | + +Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). + +### Linking From The Sidebar + +If you are adding a new page that requires linking from the sidebar you need to edit the `docs_navigation.html` file in `home-assistant.github.io/source/_includes/asides/docs_navigation.html`. diff --git a/website/versioned_docs/version-0.76.0/documentation_standards.md b/website/versioned_docs/version-0.76.0/documentation_standards.md new file mode 100644 index 00000000..ad92319c --- /dev/null +++ b/website/versioned_docs/version-0.76.0/documentation_standards.md @@ -0,0 +1,114 @@ +--- +title: Standards +id: version-0.76.0-documentation_standards +original_id: documentation_standards +--- + +To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation. + +## General Documentation + +* The language of the documentation should be American-English. +* Don't put two spaces after a period and avoid the "Oxford comma". +* There is no limit for the line length. You are allowed to write in a flowing text style. This will make it easier to use the GitHub online editor in the future. +* Be objective and not gender favoring, polarizing, race related or religion inconsiderate. +* The case of brand names, services, protocols, components, and platforms must match its respective counterpart. e.g., "Z-Wave" **not** "Zwave", "Z-wave", "Z Wave" or "ZWave". Also, "Input Select" **not** "input select" or "Input select". +* All headings should use the `{% linkable_title %}` tag. +* Do not use ALL CAPITALS for emphasis - use italics instead + +## Component and Platform Pages + +* The **Configuration Variables** section must use the `{% configuration %}` tag. +* Configuration variables must document the requirement status. +* Configuration variables must document the default value, if any. +* Configuration variables must document the accepted value types. + * For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, int`). +* Use YAML sequence syntax in the sample code if it is supported. +* All examples should be formatted to be included in `configuration.yaml` unless explicitly stated. + * Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`. + * If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note. +* Component and platform names should be a link to their respective documentation pages. + +## Templates + +* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the `{% raw %}` tag. +* Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`. +* Use double quotes (`"`) for ([more information](#single-vs-double-quotation-marks)): + * `friendly_name` + * Single-line templates: + * `value_template` + * `level_template` + * `icon_template` + * Children of `data_template` +* Use single quotes (`'`) for ([more information](#single-vs-double-quotation-marks): + * Strings inside of templates: + * States + * Entity IDs + * `unit_of_measurement` +* No whitespace around pipe character (`|`) for Jinja2 filters. +* Single whitespace after Jinja2 opening delimiters ({% raw %}`{{`{% endraw %}). +* Single whitespace before Jinja2 closing delimiters ({% raw %}`}}`{% endraw %}). +* Do not quote values for: + * `device_class` + * `platform` + * `condition` + * `service` + +## Renaming Pages + +It can happen that a component or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add `redirect_from:` to the file header and let it point to the old location/name of the page. Please consider to add details, like release number or old component/platform name, to the page in a [note](/developers/documentation/create_page/#html). + +```text +--- +... +redirect_from: /getting-started/android/ +--- +``` + +Adding a redirect also applies if you move content around in the [documentation](/docs/). + +## Single vs. Double Quotation Marks + +Use single quotes (`'`) for strings inside of a template. It is more obvious to escape a single quote when necessary (i.e. `name` is a possessive noun), because the single quotes that wrap the string are closer in position to the apostrophe inside the string. Use double quotes (`"`) outside of a template (unless it is a multi-line template, in which case outside quotes are not required). + +### Examples + +#### {% linkable_title Double Quotes Outside, Single Quotes Inside (Valid) %} + +```yaml +automation: + ... + action: + - service: notify.notify + data_template: + message: "{% if trigger.to_state.name == 'Dale\'s Bedroom' %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}" +``` + +#### Single Quotes Outside, Double Quotes Inside (Invalid) + +```yaml +automation: + ... + action: + - service: notify.notify + data_template: + message: '{% if trigger.to_state.name == "Dale's Bedroom" %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}' +``` + +#### Multi-Line Template (Valid) + + +```yaml +automation: + ... + action: + - service: notify.notify + data_template: + message: >- + {% if trigger.to_state.name == 'Dale\'s Bedroom' %} + Someone's in your base, killing your noobs! + {% else %} + It's just another door. + {% endif %} +``` + diff --git a/website/versioned_docs/version-0.76.0/frontend_creating_custom_panels.md b/website/versioned_docs/version-0.76.0/frontend_creating_custom_panels.md new file mode 100644 index 00000000..39d36ce3 --- /dev/null +++ b/website/versioned_docs/version-0.76.0/frontend_creating_custom_panels.md @@ -0,0 +1,44 @@ +--- +title: Creating custom panels +id: version-0.76.0-frontend_creating_custom_panels +original_id: frontend_creating_custom_panels +--- + +Panels are pages that show information within Home Assistant and can allow controlling it. Panels are linked from the sidebar and rendered full screen. They have real-time access to the Home Assistant object via JavaScript. Examples of panels in the app are Map, Logbook and History. + +Besides components registering panels, users can also register panels using the `panel_custom` component. This allows users to quickly build their own custom interfaces for Home Assistant. + +## Introduction + +Panels are defined as custom elements. You can use any framework that you want, as long as you wrap it up as a custom element. To quickly get started with a panel, we've created a [React custom panel starter kit](https://github.com/home-assistant/custom-panel-starter-kit-react). + +## API reference + +The Home Assistant frontend will pass information to your panel by setting properties on your custom element. The following properties are set: + +| Property | Type | Description +| -------- | ---- | ----------- +| hass | object | Current state of Home Assistant +| narrow | boolean | if the panel should render in narrow mode +| showMenu | boolean | if the sidebar is currently shown +| panel | object | Panel information. Config is available as `panel.config`. + +## JavaScript versions + +The Home Assistant user interface is currently served to browsers in modern JavaScript and older JavaScript (ES5). The older version has a wider browser support but that comes at a cost of size and performance. + +To keep things easy, we advice you to tell your users to force the modern version of the frontend. That way you won't need any build tools while developing your panel. Add this to your config: + +```yaml +# configuration.yaml example +frontend: + javascript_version: latest +``` + +If you do need to run with ES5 support, you will need to load the ES5 custom elements adapter before defining your element: + +```js +window.loadES5Adapter().then(function() { + customElements.define('my-panel', MyCustomPanel) +}); +``` diff --git a/website/versioned_docs/version-0.76.0/frontend_data.md b/website/versioned_docs/version-0.76.0/frontend_data.md new file mode 100644 index 00000000..3fe100db --- /dev/null +++ b/website/versioned_docs/version-0.76.0/frontend_data.md @@ -0,0 +1,139 @@ +--- +title: Frontend data +sidebar_label: Data +id: version-0.76.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, thte 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 method 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 issueing 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._ diff --git a/website/versioned_docs/version-0.76.0/hassio_addon_config.md b/website/versioned_docs/version-0.76.0/hassio_addon_config.md new file mode 100644 index 00000000..fe42813f --- /dev/null +++ b/website/versioned_docs/version-0.76.0/hassio_addon_config.md @@ -0,0 +1,204 @@ +--- +title: Add-On Configuration +id: version-0.76.0-hassio_addon_config +original_id: hassio_addon_config +--- + +Each add-on is stored in a folder. The file structure looks like this: + +```text +addon_name/ + build.json + CHANGELOG.md + config.json + Dockerfile + icon.png + logo.png + README.md + run.sh +``` + +## Add-on script + +As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things. + +When developing your script: + + - `/data` is a volume for persistent storage. + - `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data. However, you might have to install `jq` as a separate package in your container (see `Dockerfile` below). + +```bash +CONFIG_PATH=/data/options.json + +TARGET="$(jq --raw-output '.target' $CONFIG_PATH)" +``` + +So if your `options` contain +```json +{ "target": "beer" } +``` +then there will be a variable `TARGET` containing `beer` in the environment of your bash file afterwards. + +## Add-on Docker file + +All add-ons are based on Alpine Linux 3.6. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images. + +``` +ARG BUILD_FROM +FROM $BUILD_FROM + +ENV LANG C.UTF-8 + +# Install requirements for add-on +RUN apk add --no-cache jq + +# Copy data for add-on +COPY run.sh / +RUN chmod a+x /run.sh + +CMD [ "/run.sh" ] +``` + +If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include: +``` +LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64|i386|amd64" +``` + +It is possible to use own base image with `build.json` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`. + +### Build Args + +We support the following build arguments by default: + +| ARG | Description | +|-----|-------------| +| BUILD_FROM | Hold image for dynamic builds or buildings over our systems. +| BUILD_VERSION | Add-on version (read from `config.json`). +| BUILD_ARCH | Hold current build arch inside. + +## Add-on config + +The config for an add-on is stored in `config.json`. + +```json +{ + "name": "xy", + "version": "1.2", + "slug": "folder", + "description": "long description", + "arch": ["amd64"], + "url": "website with more information about add-on (ie a forum thread for support)", + "startup": "application", + "boot": "auto", + "ports": { + "123/tcp": 123 + }, + "map": ["config:rw", "ssl"], + "options": {}, + "schema": {}, + "image": "repo/{arch}-my-custom-addon" +} +``` + +| Key | Type | Required | Description | +| --- | ---- | -------- | ----------- | +| name | string | yes | Name of the add-on +| version | string | yes | Version of the add-on +| slug | string | yes | Slug of the add-on +| description | string | yes | Description of the add-on +| arch | list | no | List of supported arch: `armhf`, `aarch64`, `amd64`, `i386`. Default all. +| url | url | no | Homepage of the addon. Here you can explain the add-ons and options. +| startup | bool | yes | `initialize` will start addon on setup of Hass.io. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon. +| webui | string | no | A URL for web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the proto part to a config options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and he lookup if they is True and going to `https`. +| boot | string | yes | `auto` by system and manual or only `manual` +| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`. +| host_network | bool | no | If that is True, the add-on run on host network. +| host_ipc | bool | no | Default False. Allow to share the IPC namespace with others. +| host_dbus | bool | no | Default False. Map Host dbus service into add-on. +| devices | list | no | Device list to map into the add-on. Format is: `::`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm` +| auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on. +| hassio_api | bool | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`. +| homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://hassio/homeassistant/api`. +| docker_api | bool | no | Allow read-oly access to docker API for add-on. Work only for not protected add-ons. +| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `S40-DFS-P01` +| full_access | bool | no | Give full access to hardware like the privileged mode in docker. Work only for not protected add-ons. +| apparmor | bool/string | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile. +| map | list | no | List of maps for additional Hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name. +| environment | dict | no | A dict of environment variable to run add-on. +| audio | bool | no | Boolean. Mark this add-on to use internal an audio system. The ALSA configuration for this add-on will be mount automatic. +| gpio | bool | no | Boolean. If this is set to True, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some library need also `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On system with AppArmor enabled, you need disable AppArmor or better for security, provide you own profile for the add-on. +| devicetree | bool | no | Boolean. If this is set to True, `/device-tree` will map into add-on. +| stdin | bool | no | Boolean. If that is enable, you can use the STDIN with Hass.io API. +| legacy | bool | no | Boolean. If the docker image have no hass.io labels, you can enable the legacy mode to use the config data. +| options | dict | yes | Default options value of the add-on +| schema | dict | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options. +| image | string | no | For use with Docker Hub and other container registries. +| timeout | integer | no | Default 10 (second). The timeout to wait until the docker is done or will be killed. +| tmpfs | string | no | Mount a tmpfs file system in `/tmpfs`. Valide format for this option is : `size=XXXu,uid=N,rw`. Size is mandatory, valid units (`u`) are `k`, `m` and `g` and `XXX` has to be replaced by a number. `uid=N` (with `N` the uid number) and `rw` are optional. + +### Options / Schema + +The `options` dictionary contains all available options and their default value. Set the default value to `null` if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put `?` to the end of data type, otherwise it will be a required value. + +```json +{ + "message": "custom things", + "logins": [ + { "username": "beer", "password": "123456" }, + { "username": "cheep", "password": "654321" } + ], + "random": ["haha", "hihi", "huhu", "hghg"], + "link": "http://example.com/", + "size": 15, + "count": 1.2 +} +``` + +The `schema` looks like `options` but describes how we should validate the user input. For example: + +```json +{ + "message": "str", + "logins": [ + { "username": "str", "password": "str" } + ], + "random": ["match(^\w*$)"], + "link": "url", + "size": "int(5,20)", + "count": "float", + "not_need": "str?" +} +``` + +We support: +- str +- bool +- int / int(min,) / int(,max) / int(min,max) +- float / float(min,) / float(,max) / float(min,max) +- email +- url +- port +- match(REGEX) + +## Add-on extended build + +Additional build options for an add-on is stored in `build.json`. This file will be read from our build systems. +You need this only, if you not use the default images or need additionals things. + +```json +{ + "build_from": { + "armhf": "mycustom/base-image:latest" + }, + "squash": false, + "args": { + "my_build_arg": "xy" + } +} +``` + +| Key | Required | Description | +| --- | -------- | ----------- | +| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value. +| squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that! +| args | no | Allow to set additional Docker build arguments as a dictionary. diff --git a/website/versioned_docs/version-0.76.0/hassio_debugging.md b/website/versioned_docs/version-0.76.0/hassio_debugging.md new file mode 100644 index 00000000..51ea1577 --- /dev/null +++ b/website/versioned_docs/version-0.76.0/hassio_debugging.md @@ -0,0 +1,49 @@ +--- +title: Debugging Hass.io +id: version-0.76.0-hassio_debugging +original_id: hassio_debugging +--- + +> This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is for developers of Hass.io. Do not ask for support if you are using these options. + +[SSH add-on]: https://www.home-assistant.io/addons/ssh/ + +The following debug tips and tricks are for people who are running the Hass.io image and are working on the base image. If you use the generic Linux installer script, you should be able to access your host and logs as per your host. + +## SSH access to the host + +### resinOS based Hass.io (deprecated) +Create an `authorized_keys` file containing your public key, and place it in the root of the boot partition of your SD card. Once the device is booted, you can access your device as root over SSH on port 22222. + +### HassOS based Hass.io +Use a USB drive formatted with FAT, ext4, or NTFS and name it CONFIG (case sensitive). Create an `authorized_keys` file containing your public key, and place it in the root of the USB drive. From the UI, navigate to the hass.io 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 hass.io device is rebooted. + +Windows instructions how to generate and use private/public keys with Putty are [here][windows-keys]. Instead of the droplet instructions, add the public key as per above instructions. + +Alternative instructions, for Mac, Windows and Linux can be found [here](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#platform-mac). + +Follow steps 1-4 under 'Generating a new SSH key' (The other sections are not applicable to Hass.io and can be ignored.) + +Step 3 in the link above, shows the path to the private key file `id_rsa` for your chosen operating system. Your public key, `id_rsa.pub`, is saved in the same folder. Next, select all text from text box "Public key for pasting into OpenSSH authorized_keys file" and save it to the root of your SD card as `authorized_keys`. + +> Make sure when you are copying the public key to the root of the /resin-boot partition of the SD card that you rename the file correctly to `authorized_keys` with no `.pub` file extension. + +You should then be able to SSH into your Hass.io device. On mac/linux, use: +``` +ssh root@hassio.local -p 22222 +``` + +## Checking the logs + +```bash +# Logs from the supervisor service on the Host OS +journalctl -f -u hassos-supervisor.service + +# Hass.io supervisor logs +docker logs hassos_supervisor + +# Home Assistant logs +docker logs homeassistant +``` + +[windows-keys]: https://www.digitalocean.com/community/tutorials/how-to-use-ssh-keys-with-putty-on-digitalocean-droplets-windows-users diff --git a/website/versioned_sidebars/version-0.76.0-sidebars.json b/website/versioned_sidebars/version-0.76.0-sidebars.json new file mode 100644 index 00000000..0df8307a --- /dev/null +++ b/website/versioned_sidebars/version-0.76.0-sidebars.json @@ -0,0 +1,152 @@ +{ + "version-0.76.0-Architecture": { + "Architecture": [ + "version-0.76.0-architecture_index", + "version-0.76.0-architecture_components", + "version-0.76.0-architecture_entities", + "version-0.76.0-architecture_hassio" + ], + "Entities": [ + "version-0.76.0-entity_index", + "version-0.76.0-entity_alarm_control_panel", + "version-0.76.0-entity_binary_sensor", + "version-0.76.0-entity_climate", + "version-0.76.0-entity_cover", + "version-0.76.0-entity_fan", + "version-0.76.0-entity_light", + "version-0.76.0-entity_lock", + "version-0.76.0-entity_media_player", + "version-0.76.0-entity_remote", + "version-0.76.0-entity_sensor", + "version-0.76.0-entity_switch", + "version-0.76.0-entity_vacuum", + "version-0.76.0-entity_weather" + ], + "Authentication": [ + "version-0.76.0-auth_index", + "version-0.76.0-auth_api", + "version-0.76.0-auth_auth_provider" + ], + "Configuration.yaml": [ + "version-0.76.0-configuration_yaml_index" + ], + "Config Entries": [ + "version-0.76.0-config_entries_index", + "version-0.76.0-config_entries_config_flow_handler" + ], + "Data Entry Flow": [ + "version-0.76.0-data_entry_flow_index" + ], + "Entity Registry": [ + "version-0.76.0-entity_registry_index" + ] + }, + "version-0.76.0-Extending Frontend": { + "Frontend": [ + "version-0.76.0-frontend_index", + "version-0.76.0-frontend_architecture", + "version-0.76.0-frontend_development", + "version-0.76.0-frontend_data" + ], + "Extending the frontend": [ + "version-0.76.0-frontend_add_card", + "version-0.76.0-frontend_add_more_info", + "version-0.76.0-frontend_add_websocket_api" + ], + "Custom UI": [ + "version-0.76.0-lovelace_custom_card", + "version-0.76.0-frontend_creating_custom_ui", + "version-0.76.0-frontend_creating_custom_panels" + ] + }, + "version-0.76.0-Extending HASS": { + "Developing a feature": [ + "version-0.76.0-development_index", + "version-0.76.0-development_environment", + "version-0.76.0-development_submitting", + "version-0.76.0-development_checklist", + "version-0.76.0-development_guidelines", + "version-0.76.0-development_testing", + "version-0.76.0-development_catching_up", + "version-0.76.0-development_validation", + "version-0.76.0-development_typing" + ], + "Development 101": [ + "version-0.76.0-dev_101_index", + "version-0.76.0-dev_101_hass", + "version-0.76.0-dev_101_events", + "version-0.76.0-dev_101_states", + "version-0.76.0-dev_101_services", + "version-0.76.0-dev_101_config" + ], + "Creating Platforms": [ + "version-0.76.0-creating_platform_index", + "version-0.76.0-creating_platform_code_review", + "version-0.76.0-creating_platform_example_light", + "version-0.76.0-creating_platform_example_sensor" + ], + "Creating Components": [ + "version-0.76.0-creating_component_index", + "version-0.76.0-creating_component_code_review", + "version-0.76.0-creating_component_deps_and_reqs", + "version-0.76.0-creating_component_events", + "version-0.76.0-creating_component_states", + "version-0.76.0-creating_component_discovery", + "version-0.76.0-creating_component_loading", + "version-0.76.0-creating_component_generic_discovery" + ] + }, + "version-0.76.0-Misc": { + "Introduction": [ + "version-0.76.0-misc" + ], + "External API": [ + "version-0.76.0-external_api_rest", + "version-0.76.0-external_api_rest_python", + "version-0.76.0-external_api_websocket", + "version-0.76.0-external_api_server_sent_events" + ], + "Internationalization": [ + "version-0.76.0-internationalization_index", + "version-0.76.0-internationalization_backend_localization", + "version-0.76.0-internationalization_custom_component_localization", + "version-0.76.0-internationalization_translation" + ], + "Documentation": [ + "version-0.76.0-documentation_index", + "version-0.76.0-documentation_standards", + "version-0.76.0-documentation_create_page" + ], + "Intents": [ + "version-0.76.0-intent_index", + "version-0.76.0-intent_firing", + "version-0.76.0-intent_handling", + "version-0.76.0-intent_conversation", + "version-0.76.0-intent_builtin" + ], + "asyncio": [ + "version-0.76.0-asyncio_index", + "version-0.76.0-asyncio_101", + "version-0.76.0-asyncio_categorizing_functions", + "version-0.76.0-asyncio_working_with_async" + ], + "Hass.io": [ + "version-0.76.0-hassio_debugging", + "version-0.76.0-hassio_hass" + ], + "Hass.io Add-Ons": [ + "version-0.76.0-hassio_addon_index", + "version-0.76.0-hassio_addon_tutorial", + "version-0.76.0-hassio_addon_config", + "version-0.76.0-hassio_addon_communication", + "version-0.76.0-hassio_addon_testing", + "version-0.76.0-hassio_addon_publishing", + "version-0.76.0-hassio_addon_presentation", + "version-0.76.0-hassio_addon_repository" + ], + "Maintainer docs": [ + "version-0.76.0-maintenance", + "version-0.76.0-releasing" + ] + } +} diff --git a/website/versions.json b/website/versions.json index b405681a..f5c3ef37 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "0.76.0", "0.75.0", "0.74.0", "0.73.0",