mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-19 15:26:29 +00:00
Update URLs (#1745)
This commit is contained in:
parent
52eb140dac
commit
da60ee6f6a
@ -2,7 +2,7 @@
|
|||||||
title: "Push Notifications"
|
title: "Push Notifications"
|
||||||
---
|
---
|
||||||
|
|
||||||
The `mobile_app` component has a notify platform built in that allows for a generic way to send push notifications to your users without requiring installation of an external custom component. Push notifications can either be delivered via a websocket connection or via a cloud service.
|
The `mobile_app` integration has a notify platform built in that allows for a generic way to send push notifications to your users without requiring installation of an external custom component. Push notifications can either be delivered via a websocket connection or via a cloud service.
|
||||||
|
|
||||||
## Enabling websocket push notifications
|
## Enabling websocket push notifications
|
||||||
|
|
||||||
|
@ -106,11 +106,11 @@ Here are the libraries we suggest using, although you should feel free to use wh
|
|||||||
|
|
||||||
- Swift/Objective-C: [swift-sodium](https://github.com/jedisct1/swift-sodium) (official library maintained by Sodium developers).
|
- Swift/Objective-C: [swift-sodium](https://github.com/jedisct1/swift-sodium) (official library maintained by Sodium developers).
|
||||||
|
|
||||||
For other languages, please see the list of [Bindings for other languages](https://download.libsodium.org/doc/bindings_for_other_languages). If more than one choice is available, we recommend using the choice most recently updated as well as most peer reviewed (a easy way to check this is seeing how many GitHub stars a project has).
|
For other languages, please see the list of [Bindings for other languages](https://doc.libsodium.org/bindings_for_other_languages). If more than one choice is available, we recommend using the choice most recently updated as well as most peer reviewed (a easy way to check this is seeing how many GitHub stars a project has).
|
||||||
|
|
||||||
### Configuration
|
### Configuration
|
||||||
|
|
||||||
We use the [secret-key cryptography](https://download.libsodium.org/doc/secret-key_cryptography) features of Sodium to encrypt and decrypt payloads. All payloads are JSON encoded in Base64. For Base64 type, use `sodium_base64_VARIANT_ORIGINAL` (that is, "original", no padding, not URL safe). If the payload does not contain a `data` key when unencrypted (such as with the [get_config](https://developers.home-assistant.io/docs/api/native-app-integration/sending-data#get-config) request), an empty JSON object (`{}`) must be encrypted instead.
|
We use the [secret-key cryptography](https://doc.libsodium.org/secret-key_cryptography) features of Sodium to encrypt and decrypt payloads. All payloads are JSON encoded in Base64. For Base64 type, use `sodium_base64_VARIANT_ORIGINAL` (that is, "original", no padding, not URL safe). If the payload does not contain a `data` key when unencrypted (such as with the [get_config](https://developers.home-assistant.io/docs/api/native-app-integration/sending-data#get-config) request), an empty JSON object (`{}`) must be encrypted instead.
|
||||||
|
|
||||||
### Signaling encryption support
|
### Signaling encryption support
|
||||||
|
|
||||||
|
@ -2,7 +2,7 @@
|
|||||||
title: "Sensors"
|
title: "Sensors"
|
||||||
---
|
---
|
||||||
|
|
||||||
The `mobile_app` component supports exposing custom sensors that can be managed entirely via your app.
|
The `mobile_app` integration supports exposing custom sensors that can be managed entirely via your app.
|
||||||
|
|
||||||
## Registering a sensor
|
## Registering a sensor
|
||||||
|
|
||||||
@ -36,7 +36,7 @@ The valid keys are:
|
|||||||
| Key | Type | Required | Description |
|
| Key | Type | Required | Description |
|
||||||
|---------------------|-------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|---------------------|-------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
| attributes | object | No | Attributes to attach to the sensor |
|
| attributes | object | No | Attributes to attach to the sensor |
|
||||||
| device_class | string | No | One of the valid device classes. [Binary Sensor Classes](https://www.home-assistant.io/components/binary_sensor/#device-class), [Sensor Classes](https://www.home-assistant.io/components/sensor/#device-class) |
|
| device_class | string | No | One of the valid device classes. [Binary Sensor Classes](https://www.home-assistant.io/integrations/binary_sensor/#device-class), [Sensor Classes](https://www.home-assistant.io/integrations/sensor/#device-class) |
|
||||||
| icon | Material Design Icon (string) | No | Must be prefixed `mdi:`. If not provided, default value is `mdi:cellphone` |
|
| icon | Material Design Icon (string) | No | Must be prefixed `mdi:`. If not provided, default value is `mdi:cellphone` |
|
||||||
| name | string | Yes | The name of the sensor |
|
| name | string | Yes | The name of the sensor |
|
||||||
| state | bool, float, int, string | Yes | The state of the sensor |
|
| state | bool, float, int, string | Yes | The state of the sensor |
|
||||||
|
@ -6,11 +6,11 @@ When a user first opens the app, they will need to connect to their local instan
|
|||||||
|
|
||||||
## Authenticating the user
|
## Authenticating the user
|
||||||
|
|
||||||
The local instance can be discovered if Home Assistant has the [zeroconf component] configured by searching for `_home-assistant._tcp.local.`. If not configured, the user will need to be asked for the local address of their instance.
|
The local instance can be discovered if Home Assistant has the [zeroconf integration] configured by searching for `_home-assistant._tcp.local.`. If not configured, the user will need to be asked for the local address of their instance.
|
||||||
|
|
||||||
When the address of the instance is known, the app will ask the user to authenticate via [OAuth2 with Home Assistant]. Home Assistant uses IndieAuth, which means that to be able to redirect to a url that triggers your app, you need to take some extra steps. Make sure to read the last paragraph of the "Clients" section thoroughly.
|
When the address of the instance is known, the app will ask the user to authenticate via [OAuth2 with Home Assistant]. Home Assistant uses IndieAuth, which means that to be able to redirect to a url that triggers your app, you need to take some extra steps. Make sure to read the last paragraph of the "Clients" section thoroughly.
|
||||||
|
|
||||||
[zeroconf component]: https://www.home-assistant.io/components/zeroconf
|
[zeroconf integration]: https://www.home-assistant.io/integrations/zeroconf
|
||||||
[OAuth2 with Home Assistant]: auth_api.md
|
[OAuth2 with Home Assistant]: auth_api.md
|
||||||
|
|
||||||
## Registering the device
|
## Registering the device
|
||||||
@ -19,13 +19,13 @@ _This requires Home Assistant 0.90 or later._
|
|||||||
|
|
||||||
Home Assistant has a `mobile_app` component that allows applications to register themselves and interact with the instance. This is a generic component to handle most common mobile application tasks. This component is extendable with custom interactions if your app needs more types of interactions than are offered by this component.
|
Home Assistant has a `mobile_app` component that allows applications to register themselves and interact with the instance. This is a generic component to handle most common mobile application tasks. This component is extendable with custom interactions if your app needs more types of interactions than are offered by this component.
|
||||||
|
|
||||||
Once you have tokens to authenticate as a user, it's time to register the app with the mobile app component in Home Assistant.
|
Once you have tokens to authenticate as a user, it's time to register the app with the mobile app integration in Home Assistant.
|
||||||
|
|
||||||
### Getting Ready
|
### Getting Ready
|
||||||
|
|
||||||
First, you must ensure that the `mobile_app` component is loaded. There are two ways to do this:
|
First, you must ensure that the `mobile_app` integration is loaded. There are two ways to do this:
|
||||||
|
|
||||||
- You can publish a Zeroconf/Bonjour record `_hass-mobile-app._tcp.local.` to trigger the automatic load of the `mobile_app` component. You should wait at least 60 seconds after publishing the record before continuing.
|
- You can publish a Zeroconf/Bonjour record `_hass-mobile-app._tcp.local.` to trigger the automatic load of the `mobile_app` integration. You should wait at least 60 seconds after publishing the record before continuing.
|
||||||
- You can ask the user to add `mobile_app` to their configuration.yaml and restart Home Assistant. If the user already has `default_config` in their configuration, then `mobile_app` will have been already loaded.
|
- You can ask the user to add `mobile_app` to their configuration.yaml and restart Home Assistant. If the user already has `default_config` in their configuration, then `mobile_app` will have been already loaded.
|
||||||
|
|
||||||
You can confirm the `mobile_app` component has been loaded by checking the `components` array of the [`/api/config` REST API call](/api/rest.md#get-apiconfig). If you continue to device registration and receive a 404 status code, then it most likely hasn't been loaded yet.
|
You can confirm the `mobile_app` component has been loaded by checking the `components` array of the [`/api/config` REST API call](/api/rest.md#get-apiconfig). If you continue to device registration and receive a 404 status code, then it most likely hasn't been loaded yet.
|
||||||
|
@ -23,7 +23,7 @@ curl \
|
|||||||
http://IP_ADDRESS:8123/ENDPOINT
|
http://IP_ADDRESS:8123/ENDPOINT
|
||||||
```
|
```
|
||||||
|
|
||||||
Another option is to use Python and the [Requests](https://requests.readthedocs.io/en/master/) module.
|
Another option is to use Python and the [Requests](https://requests.readthedocs.io/en/latest/) module.
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from requests import get
|
from requests import get
|
||||||
|
@ -42,4 +42,4 @@ You will have to start over the git fetch and rebase process described above, or
|
|||||||
git push origin --force
|
git push origin --force
|
||||||
```
|
```
|
||||||
|
|
||||||
Other workflows are covered in detail in the [Github documentation](https://help.github.com/articles/fork-a-repo/).
|
Other workflows are covered in detail in the [Github documentation](https://docs.github.com/get-started/quickstart/fork-a-repo).
|
||||||
|
@ -5,13 +5,13 @@ sidebar_label: Introduction
|
|||||||
|
|
||||||
Before you commit any changes, check your work against these requirements:
|
Before you commit any changes, check your work against these requirements:
|
||||||
|
|
||||||
- All communication to external devices or services must be wrapped in an external Python library hosted on [pypi](https://pypi.python.org/pypi).
|
- All communication to external devices or services must be wrapped in an external Python library hosted on [pypi](https://pypi.org/).
|
||||||
- Issue trackers must be enabled for external Python libraries that has communication with external devices or services.
|
- Issue trackers must be enabled for external Python libraries that has communication with external devices or services.
|
||||||
- If the library is mainly used for Home Assistant and you are a code owner of the integration it is encouraged to use an issue template picker with links to [Home Assistant Core Issues](https://github.com/home-assistant/core/issues). For example: [zwave-js-server-python - New Issue](https://github.com/home-assistant-libs/zwave-js-server-python/issues/new/choose)
|
- If the library is mainly used for Home Assistant and you are a code owner of the integration it is encouraged to use an issue template picker with links to [Home Assistant Core Issues](https://github.com/home-assistant/core/issues). For example: [zwave-js-server-python - New Issue](https://github.com/home-assistant-libs/zwave-js-server-python/issues/new/choose)
|
||||||
- New dependencies are added to `requirements_all.txt` (if applicable), using `python3 -m script.gen_requirements_all`
|
- New dependencies are added to `requirements_all.txt` (if applicable), using `python3 -m script.gen_requirements_all`
|
||||||
- New codeowners are added to `CODEOWNERS` (if applicable), using `python3 -m script.hassfest`
|
- New codeowners are added to `CODEOWNERS` (if applicable), using `python3 -m script.hassfest`
|
||||||
- The `.coveragerc` file is updated to exclude your platform if there are no tests available or your new code uses a third-party library for communication with the device, service, or sensor. `config_flow.py` can't be excluded as it must be fully tested (100% coverage).
|
- The `.coveragerc` file is updated to exclude your platform if there are no tests available or your new code uses a third-party library for communication with the device, service, or sensor. `config_flow.py` can't be excluded as it must be fully tested (100% coverage).
|
||||||
- The `.strict-typing` file is updated to include your code if it does provide a fully type hinted source.
|
- The `.strict-typing` file is updated to include your code if it does provide a fully type hinted source.
|
||||||
- The code is formatted using Black, as per these [guidelines](https://developers.home-assistant.io/blog/2019/07/31/black.html). This can be done running the command `black --fast homeassistant tests`.
|
- The code is formatted using Black, as per these [guidelines](https://developers.home-assistant.io/blog/2019/07/31/black/). This can be done running the command `black --fast homeassistant tests`.
|
||||||
- Documentation is developed for [home-assistant.io](https://home-assistant.io/)
|
- Documentation is developed for [home-assistant.io](https://home-assistant.io/)
|
||||||
- Visit the [website documentation](/documenting.md) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.io).
|
- Visit the [website documentation](/documenting.md) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.io).
|
||||||
|
@ -19,7 +19,7 @@ You'll need to set up a development environment if you want to develop a new fea
|
|||||||
|
|
||||||
## Developing with Visual Studio Code + devcontainer
|
## Developing with Visual Studio Code + devcontainer
|
||||||
|
|
||||||
The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/remote/containers)
|
The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/devcontainers/containers)
|
||||||
|
|
||||||
**Prerequisites**
|
**Prerequisites**
|
||||||
|
|
||||||
@ -67,7 +67,7 @@ sudo apt-get install python3-pip python3-dev python3-venv autoconf libssl-dev li
|
|||||||
|
|
||||||
### Developing on Windows
|
### Developing on Windows
|
||||||
|
|
||||||
To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the [WSL installation instructions](https://docs.microsoft.com/windows/wsl/install) and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions.
|
To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the [WSL installation instructions](https://learn.microsoft.com/windows/wsl/install) and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions.
|
||||||
|
|
||||||
:::tip
|
:::tip
|
||||||
If you find that you cannot open the development instance via <http://localhost:8123> when using WSL, instead, within a WSL terminal, find the `inet` address of the `eth0` adaptor by running `ip addr show eth0`. Then use this address, excluding the CIDR block, to access the development instance, i.e. if your `inet` is listed as `172.20.37.6/20`, use <http://172.20.37.6:8123>.
|
If you find that you cannot open the development instance via <http://localhost:8123> when using WSL, instead, within a WSL terminal, find the `inet` address of the `eth0` adaptor by running `ip addr show eth0`. Then use this address, excluding the CIDR block, to access the development instance, i.e. if your `inet` is listed as `172.20.37.6/20`, use <http://172.20.37.6:8123>.
|
||||||
|
@ -2,21 +2,21 @@
|
|||||||
title: "Style guidelines"
|
title: "Style guidelines"
|
||||||
---
|
---
|
||||||
|
|
||||||
Home Assistant enforces quite strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/) compliance on all code submitted.
|
Home Assistant enforces quite strict [PEP8 style](https://peps.python.org/pep-0008/) and [PEP 257 (Docstring Conventions)](https://peps.python.org/pep-0257/) compliance on all code submitted.
|
||||||
|
|
||||||
We use [Black](https://github.com/psf/black) for uncompromised code formatting. Every pull request is automatically checked as part of the linting process and we never merge submissions that diverge.
|
We use [Black](https://github.com/psf/black) for uncompromised code formatting. Every pull request is automatically checked as part of the linting process and we never merge submissions that diverge.
|
||||||
|
|
||||||
Summary of the most relevant points:
|
Summary of the most relevant points:
|
||||||
|
|
||||||
- Comments should be full sentences and end with a period.
|
- Comments should be full sentences and end with a period.
|
||||||
- [Imports](https://www.python.org/dev/peps/pep-0008/#imports) should be ordered.
|
- [Imports](https://peps.python.org/pep-0008/#imports) should be ordered.
|
||||||
- Constants and the content of lists and dictionaries should be in alphabetical order.
|
- Constants and the content of lists and dictionaries should be in alphabetical order.
|
||||||
|
|
||||||
It is advisable to adjust IDE or editor settings to match those requirements.
|
It is advisable to adjust IDE or editor settings to match those requirements.
|
||||||
|
|
||||||
## Our recommendations
|
## Our recommendations
|
||||||
|
|
||||||
For some cases [PEPs](https://www.python.org/dev/peps/) don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code consistent.
|
For some cases [PEPs](https://peps.python.org/) don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code consistent.
|
||||||
|
|
||||||
### File headers
|
### File headers
|
||||||
|
|
||||||
@ -43,7 +43,7 @@ Also note that `_LOGGER.info` is reserved for the core, use `_LOGGER.debug` for
|
|||||||
|
|
||||||
### Ordering of imports
|
### Ordering of imports
|
||||||
|
|
||||||
Instead of ordering the imports manually, use [`isort`](https://github.com/timothycrosley/isort).
|
Instead of ordering the imports manually, use [`isort`](https://github.com/PyCQA/isort).
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
pip3 install isort
|
pip3 install isort
|
||||||
|
@ -6,7 +6,7 @@ title: "Submit your work"
|
|||||||
Always base your Pull Requests off of the current **`dev`** branch, not `master`.
|
Always base your Pull Requests off 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:
|
Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). Here are the steps:
|
||||||
|
|
||||||
1. From your fork's dev branch, create a new branch to hold your changes:
|
1. From your fork's dev branch, create a new branch to hold your changes:
|
||||||
|
|
||||||
@ -33,7 +33,7 @@ Submit your improvements, fixes, and new features to Home Assistant one at a tim
|
|||||||
|
|
||||||
`git push origin HEAD`
|
`git push origin HEAD`
|
||||||
|
|
||||||
6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request.
|
6. Follow [these steps](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to create your pull request.
|
||||||
|
|
||||||
- On GitHub, navigate to the [main page of the Home Assistant repository](https://github.com/home-assistant/core).
|
- On GitHub, navigate to the [main page of the Home Assistant repository](https://github.com/home-assistant/core).
|
||||||
- In the "Branch" menu, choose the branch that contains your commits (from your fork).
|
- In the "Branch" menu, choose the branch that contains your commits (from your fork).
|
||||||
|
@ -4,7 +4,7 @@ title: "Documentation"
|
|||||||
|
|
||||||
The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section is the place where we provide documentation and additional details about creating or modifying content.
|
The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section is the place where we provide documentation and additional details about creating or modifying content.
|
||||||
|
|
||||||
The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](http://github.com/mojombo/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know HTML.
|
The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](https://github.com/jekyll/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](https://daringfireball.net/projects/markdown/). To add a page, you don't need to know HTML.
|
||||||
|
|
||||||
## Small changes
|
## Small changes
|
||||||
|
|
||||||
|
@ -6,7 +6,7 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo
|
|||||||
|
|
||||||
## General Documentation
|
## General Documentation
|
||||||
|
|
||||||
Broadly speaking documentation should be written following Microsoft's house style, which is detailed [here](https://docs.microsoft.com/en-us/style-guide).
|
Broadly speaking documentation should be written following Microsoft's house style, which is detailed [here](https://learn.microsoft.com/style-guide/welcome/).
|
||||||
|
|
||||||
- The language of the documentation should be American-English.
|
- The language of the documentation should be American-English.
|
||||||
- Don't put two spaces after a period.
|
- Don't put two spaces after a period.
|
||||||
|
@ -6,7 +6,7 @@ By default Home Assistant will try to show the cards in a masonry layout (like P
|
|||||||
|
|
||||||
## API
|
## API
|
||||||
|
|
||||||
You define your custom view as a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Lit Element, Preact, or any other popular framework (except for React – [more info on React here](https://custom-elements-everywhere.com/#react)).
|
You define your custom view as a [custom element](https://developer.mozilla.org/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Lit Element, Preact, or any other popular framework (except for React – [more info on React here](https://custom-elements-everywhere.com/#react)).
|
||||||
|
|
||||||
Custom Views receive the following:
|
Custom Views receive the following:
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user