diff --git a/source/_addons/cec_scan.markdown b/source/_addons/cec_scan.markdown deleted file mode 100644 index 479236d6a74..00000000000 --- a/source/_addons/cec_scan.markdown +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "CEC Scanner" -description: "Scan HDMI-CEC devices." ---- - -Help you to discover the HDMI-CEC address. Start the add-on and look into the log to see all connected device on HDMI. diff --git a/source/_addons/check_config.markdown b/source/_addons/check_config.markdown deleted file mode 100644 index 160cde79184..00000000000 --- a/source/_addons/check_config.markdown +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "Check Home Assistant configuration" -description: "Check your current Home Assistant configuration against a new version." ---- - -You can use this add-on to check whether your configuration files are valid against the new version of Home Assistant before you actually update your Home Assistant installation. This add-on will help you avoid errors due to breaking changes, resulting in a smooth update. - -### How to use this add-on - -1. Just start the add-on. -2. Wait (On a Raspberry Pi it can take several minutes). -3. If you see the following output then you are good to go to update Home Assistant: `[Info] Configuration check finished - no error found! :)`. - -If you get errors, then you should look for **Breaking Changes** against the version you specified for this add-on and change your configuration accordingly. - -### Add-on configuration - -```json -{ - "version": "latest" -} -``` - -{% configuration %} -version: - description: Version of Home Assistant that you plan to install. - required: true - type: string -{% endconfiguration %} diff --git a/source/_addons/configurator.markdown b/source/_addons/configurator.markdown deleted file mode 100644 index 2560a866ded..00000000000 --- a/source/_addons/configurator.markdown +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Configurator" -description: "Browser-based configuration file editor for Home Assistant." -featured: true -og_image: /images/hassio/screenshots/addon-hass-configurator.png ---- - -You can use this add-on to add a browser-based file editor to your Hass.io installation. By default it will be available over Ingress only. - -More information and a standalone version for regular Home Assistant installations can be found in the [GitHub repository](https://github.com/danielperna84/hass-configurator). - -

- -Screenshot of the Configurator. -

- -### Feature list - -- Web-based editor to modify your files with syntax highlighting and YAML linting. -- Upload and download files. -- Stage, stash and commit changes in Git repositories, create and switch between branches, push to remotes, view diffs. -- Lists with available entities, triggers, events, conditions and services. -- Restart Home Assistant directly with the click of a button. Reloading groups, automations, etc. can be done as well. An API password is required. -- Direct links to Home Assistant documentation and icons. -- Execute shell commands within the add-on container. -- Editor settings are saved in your browser. -- And much more... - -### Add-on Configuration - -```json -{ - "dirsfirst": false, - "enforce_basepath": false -} -``` - -{% configuration %} -dirsfirst: - description: List directories before files in the file browser. - required: true - type: boolean - default: false -enforce_basepath: - description: If set to `true`, access is limited to files within the `/config` directory. - required: true - type: boolean - default: false -{% endconfiguration %} - -### Old port based Access - -You can set a network Port and the Add-on listens on that Port with Home Assistant user credential. That is as a backup if you are not able to connect to Home Assistant anymore. Today, you can restart Home Assistant with broken config, but maybe some times usefully. diff --git a/source/_addons/dhcp_server.markdown b/source/_addons/dhcp_server.markdown deleted file mode 100644 index 8a19901d0b9..00000000000 --- a/source/_addons/dhcp_server.markdown +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "DHCP server" -description: "A simple DHCP server." ---- - -Create a simple DHCP server for your network and allow setting fixed IPs for devices. - -```json -{ - "domain": "mynetwork.local", - "dns": ["8.8.8.8", "8.8.4.4"], - "networks": [ - { - "subnet": "192.168.1.0", - "netmask": "255.255.255.0", - "range_start": "192.168.1.100", - "range_end": "192.168.1.200", - "broadcast": "192.168.1.255", - "gateway": "192.168.1.1", - "interface": "eth0" - } - ], - "hosts": [ - { - "name": "webcam_xy", - "mac": "aa:bb:ee:cc", - "ip": "192.168.1.40" - } - ] -} -``` - -{% configuration %} -domain: - description: Your network domain name. - required: true - type: string -dns: - description: A list of DNS server for your network. - required: true - type: list -networks: - description: A list of network to provide DHCP. - required: false - type: list - keys: - subnet: - description: Your network schema. - required: true - type: string - netmask: - description: Your network netmask. - required: true - type: string - range_start: - description: Start address for DHCP leases. - required: true - type: string - range_end: - description: End address for DHCP leases. - required: true - type: string - broadcast: - description: Network broadcast address. - required: true - type: string - gateway: - description: A List of gateways. - required: true - type: list - interface: - description: Interface on that will be listen. Normally is `eth0` for ethernet wired connection and `wlan0` for wireless connection. - required: true - type: string -hosts: - description: A list of fixed IPs for devices. - required: false - type: list - keys: - name: - description: Name/hostname of your device. - required: true - type: string - mac: - description: Mac address of your device. - required: true - type: string - ip: - description: Fix IP address for device. - required: true - type: string -{% endconfiguration %} diff --git a/source/_addons/dnsmasq.markdown b/source/_addons/dnsmasq.markdown deleted file mode 100644 index 0efc9b8af88..00000000000 --- a/source/_addons/dnsmasq.markdown +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Dnsmasq" -description: "A simple DNS server." ---- - -Setup and manage a [Dnsmasq](http://thekelleys.org.uk/dnsmasq/doc.html) DNS server. This allows you to manipulate DNS requests. For example, you can have your Home Assistant domain resolve with an internal address inside your network. - -```json -{ - "defaults": ["8.8.8.8", "8.8.4.4"], - "forwards": [ - {"domain": "mystuff.local", "server": "192.168.1.40"} - ], - "hosts": [ - {"host": "home.mydomain.io", "ip": "192.168.1.10"} - ] -} -``` - -{% configuration %} -defaults: - description: A list of DNS servers to forward default requests to. - required: true - type: list -forwards: - description: A list of domains that will forward to a specific server. - required: false - type: list -hosts: - description: A list of hosts to resolve statically. - required: false - type: list -{% endconfiguration %} diff --git a/source/_addons/duckdns.markdown b/source/_addons/duckdns.markdown deleted file mode 100644 index 068ccc65b75..00000000000 --- a/source/_addons/duckdns.markdown +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "DuckDNS" -description: "Automatically update your Duck DNS IP address with integrated HTTPS support via Let's Encrypt." -featured: true ---- - -[Duck DNS](https://www.duckdns.org/) is a free service which will point a DNS (sub domains of duckdns.org) to an IP of your choice. This add-on includes support for Let's Encrypt and will automatically create and renew your certificates. You will need to sign up for a Duck DNS account before using this add-on. - -```json -{ - "lets_encrypt": { - "accept_terms": true, - "certfile": "fullchain.pem", - "keyfile": "privkey.pem" - }, - "token": "sdfj-2131023-dslfjsd-12321", - "domains": ["my-domain.duckdns.org"], - "seconds": 300 -} -``` - -{% configuration %} -lets_encrypt: - description: Let's Encrypt is a free, automated, and open certificate authority. - required: true - type: map - keys: - accept_terms: - description: If you accept the [Let's Encrypt Subscriber Agreement](https://letsencrypt.org/repository/), it will generate and update Let's Encrypt certificates for your DuckDNS domain. - required: true - type: boolean - default: false -token: - description: Your Duck DNS API key, from your DuckDNS account page. - required: true - type: string -domains: - description: A list of domains to update DNS. - required: true - type: list -seconds: - description: Seconds between updates to Duck DNS. - required: true - type: integer -{% endconfiguration %} - -## Home Assistant configuration - -Use the following configuration in Home Assistant to use the generated certificate: - -```yaml -http: - base_url: https://my-domain.duckdns.org:8123 - ssl_certificate: /ssl/fullchain.pem - ssl_key: /ssl/privkey.pem -``` - -If you use a port other than `8123` or an SSL proxy, change the port number accordingly. - -## Router configuration - -You'll need to forward the port you listed in your configuration (8123 in the example above) on your router to your Home Assistant system. You can find guides on how to do this on [Port Forward](https://portforward.com/). Noting that you'll only need to forward the TCP port. - -Ensure that you allocate the Home Assistant system a fixed IP on your network before you configure port forwarding. You can do this either on the computer itself (see the [install guide](/hassio/installation/) or via a static lease on your router. - -Restart Home Assistant for the configured changes to take effect. When you access the Home Assistant frontend you will now need to use `https`, even when accessing local instances, for example at `https://192.168.0.1:8123`. - -Note: Some routers prevent "hairpinning", or communication from a given host to itself through an external IP. This will prevent you from being able to access Home Assistant through duckdns from within your local network. For troubleshooting purposes, you can attempt to access your system from an external network via VPN, or through your mobile network after disabling WIFI on your mobile device. - -## Generate Let's Encrypt certificate for Duck DNS sub sub domains - -To generate certificates for nr.my-domain.duckdns.org update the domain JSON settings to: - -```json -{ - ... - "domains": ["my-domain.duckdns.org","*.my-domain.duckdns.org"], - ... -} -``` diff --git a/source/_addons/git_pull.markdown b/source/_addons/git_pull.markdown deleted file mode 100644 index 1314f06caf2..00000000000 --- a/source/_addons/git_pull.markdown +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Git pull" -description: "Load and update configuration files for Home Assistant from a GIT repository." ---- - -Load and update configuration files for Home Assistant from a [Git](https://git-scm.com/) repository. - -```json -{ - "git_branch": "master", - "git_command": "pull", - "git_remote": "origin", - "git_prune": "false", - "repository": "https://example.com/my_configs.git", - "auto_restart": false, - "restart_ignore": [ - "ui-lovelace.yaml", - ".gitignore", - "exampledirectory/" - ], - "repeat": { - "active": false, - "interval": 300 - }, - "deployment_user": "", - "deployment_password": "", - "deployment_key": [ -"-----BEGIN RSA PRIVATE KEY-----", -"MIIEowIBAAKCAQEAv3hUrCvqGZKpXQ5ofxTOuH6pYSOZDsCqPqmaGBdUzBFgauQM", -"xDEcoODGHIsWd7t9meAFqUtKXndeiKjfP0MMKsttnDohL1kb9mRvHre4VUqMsT5F", -"...", -"i3RUtnIHxGi1NqknIY56Hwa3id2yk7cEzvQGAAko/t6PCbe20AfmSQczs7wDNtBD", -"HgXRyIqIXHYk2+5w+N2eunURIBqCI9uWYK/r81TMR6V84R+XhtvM", -"-----END RSA PRIVATE KEY-----" - ], - "deployment_key_protocol": "rsa" -} -``` - -- **git_branch** (*Required*): Branch name of the Git repo. If left empty, the currently checked out branch will be updated. Leave this as 'master' if you are unsure. -- **git_command** (*Required*): `pull`/`reset`: Command to run. Leave this as `pull` if you are unsure. -* **pull**: Incorporates changes from a remote repository into the current branch. Will preserve any local changes to tracked files. -* **reset**: Will execute `git reset --hard` and overwrite any local changes to tracked files and update from the remote repository. Use with caution. - -
- -Using the `reset` option will overwrite changes to tracked files. Tracked files are those visible in the git repository or those given by the output on this command: `git ls-tree -r master --name-only`. - -
- -- **git_remote** (*Required*): Name of the tracked repository. Leave this as `origin` if you are unsure. -- **git_prune** (*Required*): `true`/`false`: If set to true, the add-on will clean-up branches that are deleted on the remote repository, but still have cached entries on the local machine. Leave this as `false` if you are unsure. - -- **repository** (*Required*): Git URL to your repository (make sure to use double quotes). You have to add `.git` to your repository URL (see example configuration). -- **auto_restart** (*Required*): `true`/`false`: Restart Home Assistant when the configuration has changed (and is valid). -- **restart_ignore** (*Optional*): When `auto_restart` is enabled, changes to these files will not make HA restart. Full directories to ignore can be specified. -- **repeat**: Poll the repository for updates periodically automatically. -* **active** (*Required*): `true`/`false`: Enable/disable automatic polling. -* **interval** (*Required*): The interval in seconds to poll the repo for if automatic polling is enabled. -- **deployment_user** (*Optional*): Username to use when authenticating to a repository with a username and password. -- **deployment_password** (*Optional*): Password to use when authenticating to a repository. Ignored if `deployment_user` is not set. -- **deployment_key** (*Optional*): A private SSH key that will be used for communication during Git operations. This key is mandatory for ssh-accessed repositories, which are the ones with the following pattern: `@:`. This key has to be created without a passphrase. -- **deployment_key_protocol** (*Optional*): The key protocol. Default is `rsa`. Valid protocols are: - - * **dsa** - * **ecdsa** - * **ed25519** - * **rsa** - -The protocol is typically known by the suffix of the private key --e.g., a key file named `id_rsa` will be a private key using `rsa` protocol. - -
- -You should only use this add-on if you do not have an existing configuration or if your existing configuration is already in a Git repository. If the script does not find the necessary Git files in your configuration folder, it will delete anything that might be there. Please ensure that there is a `.git` folder before using this. You can verify this by listing the items in the configuration folder including hidden files. The command is `ls -a /config`. - -
diff --git a/source/_addons/google_assistant.markdown b/source/_addons/google_assistant.markdown deleted file mode 100644 index e159fcda86f..00000000000 --- a/source/_addons/google_assistant.markdown +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Google Assistant" -description: "Enhance your Hass.io installation with Google Assistant." -featured: true ---- - -
- -If you want to integrate your Google Home or mobile phone running Google Assistant, with Home Assistant, then you want the [Google Assistant component][AssistantIntergration]. - -
- -[Google Assistant][GoogleAssistant] is an AI-powered voice assistant that runs on the Raspberry Pi and x86 platforms and interacts via the [DialogFlow][comp] integration or the [Google Assistant component][AssistantIntergration] with Home-Assistant. You can also use [Google Actions][GoogleActions] to extend its functionality. - -To enable access to the Google Assistant API, do the following: -1. Go to the [Google Actions Console][GActionsConsole] and create a new project. -1. After you created the project on the bottom of the page click "Device registration". Keep this tab open for later use. -1. Enable the Google Assistant API on the new project through [this][enableAPI] link. Make sure you have the right project selected (shown in the middle of the screen in the top bar). If you can't select the right project, it may help to open the link in an incognito window. -1. Configure the [OAuth consent screen][OAuthConcent]. Also again check that you have the right project and don't forget to hit "Save" at the bottom of the page. You only have to fill in a project name and your e-mail. -1. You back to you device registration tab and click "Device registration". Or open you project in the [Google Actions Console][GActionsConsole] start the Quick setup, and in the left bar click "Device registration". -1. Give you project a name, think of a nice manufacturer and for device type select "speaker". -1. Edit you "model id", if you want to and copy it for later use. -1. Download the credentials. -1. Click "Next" and click "Skip". -1. Upload your credentials as "google_assistant.json" to the "hassio/share" folder, for example by using the [Samba] add-on. -1. In the Add-on configuration field fill-in you "project id" and your "model-id" and hit "Save". Your project id can be found in the Google Actions console by clicking on the top right menu button and selecting "Project settings". This id may differ from the project name that you choose! -1. Below the "Config" window select the microphone and speaker that you want to use. On a Raspberry Pi 3, ALSA device 0 is the built-in headset port and ALSA device 1 is the HDMI port. Also don't forget to click "Save". -1. Start the add-on. Check the log and click refresh till it says: "ENGINE Bus STARTED". -1. Now click "Open Web UI" and follow the authentication process. You will get an empty response after you have send your token. - -That's it. You should now be able to use the Google Voice assistant. - -### Add-on configuration - -```json -{ - "client_secrets": "google_assistant.json", - "project_id": "you-project-id", - "model_id": "your-model-id" -} -``` - -{% configuration %} -client_secrets: - description: The file downloaded from the [Google Actions Console](https://console.actions.google.com/), you can redownload them under the "Develop - Device registration" tab. By default the add-on look in the "hassio/share" folder. - required: true - type: string -project_id: - description: The project id can be found in your "google_assistant.json" file or under project settings in the [Google Actions Console](https://console.actions.google.com/). - required: true - type: string -model_id: - description: The model id can also be found under the "Develop - Device registration tab" in the [Google Actions Console](https://console.actions.google.com/). - required: true - type: string -{% endconfiguration %} - -### Home Assistant configuration - -Use the Home Assistant [DialogFlow component][comp] to integrate the add-on into Home Assistant or combine it with the [Google Assistant component][AssistantIntergration]. - -[AssistantIntergration]: /integrations/google_assistant/ -[GoogleAssistant]: https://assistant.google.com/ -[GoogleActions]: https://actions.google.com/ -[GActionsConsole]: https://console.actions.google.com/ -[enableAPI]: https://console.developers.google.com/apis/api/embeddedassistant.googleapis.com/overview -[OAuthConcent]: https://console.developers.google.com/apis/credentials/consent -[Samba]: /addons/samba/ -[comp]: /integrations/dialogflow/ -[project]: https://console.cloud.google.com/project -[API]: https://console.developers.google.com/apis/api/embeddedassistant.googleapis.com/overview -[oauthclient]: https://console.developers.google.com/apis/credentials/oauthclient -[cloudConsole]: https://console.cloud.google.com/cloud-resource-manager diff --git a/source/_addons/homematic.markdown b/source/_addons/homematic.markdown deleted file mode 100644 index 4ff78f9e420..00000000000 --- a/source/_addons/homematic.markdown +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "HomeMatic" -description: "HomeMatic hardware support to turn Home Assistant into a CCU." ---- - -You can't import an existing configuration, you'll need re-learn it into Home Assistant. There is an experimental WebUI alias Regahss support since 9.0. Before it was required to use a third-party tool. - -Follow devices will be supported and tested: - -- [HM-MOD-RPI-PCB](https://www.elv.ch/homematic-funkmodul-fuer-raspberry-pi-bausatz.html) -- [HmIP-RFUSB](https://www.elv.ch/elv-homematic-ip-rf-usb-stick-hmip-rfusb-fuer-alternative-steuerungsplattformen-arr-bausatz.html) - -```json -{ - "rf_enable": true, - "rf": [ - { - "type": "CCU2", - "device": "/dev/ttyAMA0" - } - ], - "wired_enable": false, - "wired": [ - { - "serial": "xy", - "key": "abc", - "ip": "192.168.0.0" - } - ], - "hmip_enable": false, - "hmip": [ - { - "type": "HMIP_CCU2", - "device": "/dev/ttyUSB0" - } - ] -} -``` - -{% configuration %} -rf_enable: - description: Enable or disable BidCoS-RF. - required: true - type: boolean - default: false -rf: - description: RF devices. - required: true - type: list - keys: - type: - description: Device type for RFD service. Look into the manual of your device. - required: true - type: string - device: - description: Device on the host. - required: true - type: string -wired_enable: - description: Enable or disable BidCoS-Wired. - required: true - type: boolean - default: false -wired: - description: Wired devices. - required: true - type: list - keys: - serial: - description: Serial number of the device. - required: true - type: string - key: - description: The encrypted key. - required: true - type: string - ip: - description: The IP address of LAN gateway. - required: true - type: string -hmip_enable: - description: Enable or disable hmip. - required: true - type: boolean - default: false -hmip: - description: HMIP devices. - required: true - type: list - keys: - type: - description: Device type for RFD service. Look into the manual of your device. - required: true - type: string - device: - description: Device on the host. - required: true - type: string -{% endconfiguration %} - -## Home Assistant configuration - -Use the following configuration in Home Assistant to use it: - -```yaml -homematic: - interfaces: - rf: - host: core-homematic - port: 2001 - wired: - host: core-homematic - port: 2000 - hmip: - host: core-homematic - port: 2010 -``` - -## Raspberry Pi3 - -With HM-MOD-RPI-PCB you need to add follow into your `config.txt` on boot partition: - -```text -dtoverlay=pi3-miniuart-bt -``` - -## HmIP-RFUSB - -HassOS > 1.11 support HmIP-RFUSB by default and don't need any configuration. If you run a Linux installation, you need to follow the installation guide from the documentation to set up the UART USB interface on your computer. - -## Web UI - -To enable the experimental WebUI for built-in CCU specify a port number for "Regahss Webinterface" on the addon configuration page under the network section. After saving the changes, click on the "Open Web UI" button and proceed with the [Homematic WebUI](https://www.eq-3.de/downloads/download/handbuecher/WebUI_Handbuch_eQ-3.pdf) configuration. diff --git a/source/_addons/lets_encrypt.markdown b/source/_addons/lets_encrypt.markdown deleted file mode 100644 index 172cfd37d79..00000000000 --- a/source/_addons/lets_encrypt.markdown +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Let's Encrypt" -description: "Automatically manage your SSL certificate using Let's Encrypt." ---- - -
- -You should not use this if you are also using the [DuckDNS add-on]. The DuckDNS add-on has integrated Let's Encrypt support. - -
- -Setup and manage a [Let's Encrypt](https://letsencrypt.org/) certificate. This add-on will create a certificate on the first run and will auto-renew if the certificate is within 30 days of expiration. This add-on uses port 80 to verify the certificate request. You will need to stop all other add-ons that also use this port. - -```json -{ - "email": "example@example.com", - "domains": ["example.com", "mqtt.example.com", "hass.example.com"], - "certfile": "fullchain.pem", - "keyfile": "privkey.pem" -} -``` - -{% configuration %} -email: - description: Your email address for registration on Let's Encrypt. - required: true - type: string -domains: - description: A list of domains to create/renew the certificate. - required: true - type: list -certfile: - description: Name of the certfile that is created. Leave as default value. - required: true - type: string - default: fullchain.pem -keyfile: - description: Name of the keyfile that is created. Leave as default value. - required: true - type: string - default: privkey.pem -{% endconfiguration %} - -## Home Assistant configuration - -Use the following configuration in Home Assistant to use the generated certificate: - -```yaml -http: - base_url: https://my-domain.tld:8123 - ssl_certificate: /ssl/fullchain.pem - ssl_key: /ssl/privkey.pem -``` - -If you use another port such as `8123` or an SSL proxy, change the port number. - -## Enabling auto-renewals - -Out of the box, the add-on will not automatically renew your certificate. In fact, it only starts, tries to get/renew your certificate, and then stops. It's up to you to manually start it again whenever your certificate comes close to expiry. - -However, you can automate this process using Home Assistant. - -Use this in your `automations.yaml` to attempt certificate renewal each day at midnight: - -```yaml -- id: letsencrypt-renewal - alias: "Let's Encrypt Renewal" - trigger: - - platform: time - at: '00:00:00' - action: - - service: hassio.addon_restart - data: - addon: core_letsencrypt -``` - -If you are using the [Nginx Proxy add-on] you will need need to stop this during the renewal process. This can be achieved by stopping the add-on whilst restarting the Let's Encrypt add-on. This can be achieved the following configuration: - -```yaml -- id: letsencrypt-renewal - alias: 'LetsEncrypt renewal' - trigger: - - platform: time - at: '00:00:00' - action: - - service: hassio.addon_stop - data: - addon: core_nginx_proxy - - service: hassio.addon_restart - data: - addon: core_letsencrypt - - delay: '00:01:30' - - service: hassio.addon_start - data: - addon: core_nginx_proxy -``` - -[DuckDNS add-on]: /addons/duckdns/ -[Nginx Proxy add-on]: /addons/nginx_proxy/ diff --git a/source/_addons/mariadb.markdown b/source/_addons/mariadb.markdown deleted file mode 100644 index 844f77a88ae..00000000000 --- a/source/_addons/mariadb.markdown +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "MariaDB" -description: "MariaDB Server is one of the most popular database servers in the world." ---- - -Set up a [MariaDB](https://mariadb.org/) SQL server. It supports multiple databases, users and permission settings. If you want to only connect from inside Home Assistant use `core-mariadb` as the host address. - -```json -{ - "databases": ["homeassistant"], - "logins": [ - { - "username": "hass", - "host": "%.local.hass.io", - "password": "securePassword" - } - ], - "rights": [ - { - "username": "hass", - "host": "%.local.hass.io", - "database": "homeassistant", - "grant": "ALL PRIVILEGES ON" - } - ] -} -``` - -{% configuration %} -databases: - description: List of databases. - required: true - type: list -logins: - description: List of SQL accounts to create or update. - required: true - type: list - keys: - username: - description: Username for account. - required: true - type: string - host: - description: Host for account. Use '%', to accept connections for this account from any host. - required: true - type: string - password: - description: Password for account. - required: true - type: string -rights: - description: List of rights to be granted. - required: true - type: list - keys: - username: - description: Username for granted rights. - required: true - type: string - host: - description: Host is a part of username like above. - required: true - type: string - database: - description: Database name on which to grant user rights. - required: true - type: string - grant: - description: SQL grant part for access too. - required: true - type: string -{% endconfiguration %} - -## Home Assistant configuration - -Use the following configuration in Home Assistant to use the database above: - -```yaml -recorder: - db_url: mysql://hass:securePassword@core-mariadb/homeassistant?charset=utf8 -``` diff --git a/source/_addons/mosquitto.markdown b/source/_addons/mosquitto.markdown deleted file mode 100644 index 67e74ff8f00..00000000000 --- a/source/_addons/mosquitto.markdown +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Mosquitto MQTT broker" -description: "Fast and reliable MQTT broker." -featured: true ---- - -Set up [Mosquitto](https://mosquitto.org/) as MQTT broker. - -```json -{ - "logins": [ - {"username": "local-user", "password": "mypw"} - ], - "anonymous": false, - "customize": { - "active": false, - "folder": "mosquitto" - }, - "certfile": "fullchain.pem", - "keyfile": "privkey.pem" -} -``` - -
- -Since version 4.1 of the addon, an explicit ACL definition is now required if you plan to use legacy logins and `"anonymous": true` [see these instructions](https://www.home-assistant.io/addons/mosquitto/#access-control-lists-acls). - -
- -{% configuration %} -anonymous: - description: Allow anonymous connections. If *logins* is set, the anonymous user can only read data. - required: false - default: false - type: boolean -logins: - description: A list of local users that will be created with *username* and *password*. You don't need do this because you can use Home Assistant users too without any configuration. - required: false - type: list -customize: - description: If you enable it, it reads additional configuration files (`*.conf`) from `/share/mosquitto`. - required: false - type: [boolean, string] - default: false -cafile: - description: Path to the CA certificate. If not set, will default to the *certfile* value. - required: false - default: certfile - type: string -require_certificate: - description: Restrict to users with a valid certificate only. - required: false - default: false - type: boolean -{% endconfiguration %} - -### Home Assistant user management - -This add-on is attached to the Home Assistant user system, so mqtt clients can make use of these credentials. Local users may also still be set independently within the configuration options for the add-on. For the internal Hass.io ecosystem we register `homeassistant` and `addons`, so these may not be used as user names. - -### Home Assistant configuration - -To use the Mosquitto as [broker](/docs/mqtt/broker/#run-your-own), go to the integration page and install the configuration with one click. If you have old MQTT settings available, remove this old integration and restart Home Assistant to see the new one. - -#### Using Mosquitto with Hass.io - -1. Install the [Mosquitto add-on](/addons/mosquitto/) with the default configuration via 'Hass.io > ADD-ON STORE'. (Don't forget to start the add-on & verify that 'Start on boot' is enabled.) - -2. Create a new user for MQTT via the `Configuration > Users (manage users)`. (Note: This name cannot be "homeassistant" or "addon") - -3. Once back on-line, return to `Configuration > Integrations` and select configure next to `MQTT`. - -```text - Broker: YOUR_HASSIO_IP_ADDRESS - Port: 1883 - Username: MQTT_USERNAME - Password: MQTT_PASSWORD -``` - -If you are using the ACL, remember to enter the newly created user and homeassistant in `/share/mosquitto/accesscontrollist` as follows: - -```text -user [YOUR_MQTT_USER] -topic readwrite # -user homeassistant -topic readwrite # -``` - - -Note: .yaml modifications are not required. -See [testing your setup](/docs/mqtt/testing/) to verify the steps above. - -### Disable listening on insecure (1883) ports - -Remove the ports from the add-on page network card (set them as blank) to disable them. - -### Access Control Lists (ACLs) - -It is possible to restrict access to topics based upon the user logged in to Mosquitto. In this scenario it is recommended to create individual users for each of your clients and create an appropriate ACL. - -See the following links for more information: - -* [Mosquitto topic restrictions](http://www.steves-internet-guide.com/topic-restriction-mosquitto-configuration/) -* [Mosquitto.conf man page](https://mosquitto.org/man/mosquitto-conf-5.html) - -Add the following configuration to enable **unrestricted** access to all topics. - - 1. Enable the customize flag -```json - "customize": { - "active": true, - "folder": "mosquitto" - }, -``` - -2. Create `/share/mosquitto/acl.conf` with the contents: -```text -acl_file /share/mosquitto/accesscontrollist -``` - -3. Create `/share/mosquitto/accesscontrollist` with the contents: -```text -user [YOUR_MQTT_USER] -topic readwrite # -``` - -The `/share` folder can be accessed via SMB, or on the host filesystem under `/usr/share/hassio/share`. diff --git a/source/_addons/nginx_proxy.markdown b/source/_addons/nginx_proxy.markdown deleted file mode 100644 index 53d45c6d607..00000000000 --- a/source/_addons/nginx_proxy.markdown +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "NGINX SSL proxy" -description: "NGINX Home Assistant SSL proxy." ---- - -Sets up an SSL proxy with NGINX and redirect port 80 to 443. Make sure you have generated a certificate before you start this add-on. - -In the `http` section of the `configuration.yaml` file remove `ssl_certificate`, `ssl_key` and `server_port` and don't enter the port in the `base_url` to avoid an HTTP 502 error. - -```json -{ - "domain": "home.example.com", - "certfile": "fullchain.pem", - "keyfile": "privkey.pem", - "hsts": "max-age=31536000; includeSubDomains", - "customize": { - "active": false, - "default": "nginx_proxy_default*.conf", - "servers": "nginx_proxy/*.conf" - }, - "cloudflare": false -} -``` - -{% configuration %} -domain: - description: The Domain to use for the proxy. - required: true - type: string -certfile: - description: The certificate file to use in the `/ssl` directory. - required: true - type: string -keyfile: - description: Private key file to use in the `/ssl` directory. - required: true - type: string -hsts: - description: Value for the [`Strict-Transport-Security`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) HTTP header to send. If empty, the header is not sent. - required: true - type: string -customize: - description: If true, additional NGINX configuration files for the default server and additional servers are read from files in the `/share` directory specified by the `default` and `servers` variables. - required: false - type: boolean - default: false -cloudflare: - description: If enabled, configure Nginx with a list of IP addresses directly from Cloudflare that will be used for `set_real_ip_from` directive Nginx config. - required: false - type: boolean - default: false -{% endconfiguration %} - -
- -It is possible to deactivate port 80 if you need this for things like `emulated_hue`. Remove the host port from Network option of this add-on. - -
diff --git a/source/_addons/rpc_shutdown.markdown b/source/_addons/rpc_shutdown.markdown deleted file mode 100644 index ba5bfb790d4..00000000000 --- a/source/_addons/rpc_shutdown.markdown +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "RPC Shutdown" -description: "Simple way for remote windows shutdowns." ---- - -Allows you to shut down a Windows computer with a service call from Home Assistant. - -```json -{ - "computers": [ - { - "alias": "test-pc-1", - "address": "192.168.0.1", - "credentials": "user%password" - }, - { - "alias": "test-pc-2", - "address": "192.168.0.2", - "credentials": "user%password" - } - ] -} -``` - -- **computers** (*Required*): A list of computer objects to shutdown from Home-Assistant. -- **computers/alias** (*Required*): Set an alias for this record which becomes the name for the input. -- **computers/address** (*Required*): IP address or NetBIOS name of the computer for the shutdown. -- **computers/credentials** (*Required*): Credentials for logging into computer. Use a `%` as the delimiter of username and password. - -### Home Assistant configuration - -Use the following inside Home Assistant service call to use it: - -```yaml -service: hassio.addon_stdin -data: - addon: core_rpc_shutdown - input: test-pc -``` - -
- -The `user` specified in the credentials should be an applicable user listed in `C:/Users`. This may differ from the username used to login to Windows. Depending on your settings and privileges within Windows, changes to the firewall, UAC (User Account Control) and registry settings may be required to allow this add-on to remotely shut down your computer. There are many guides available online on how to adjust these settings. - -
diff --git a/source/_addons/samba.markdown b/source/_addons/samba.markdown deleted file mode 100644 index 324d8a5bdfd..00000000000 --- a/source/_addons/samba.markdown +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Samba" -description: "Manage your Home Assistant and custom add-ons over Samba." -featured: true ---- - -This add-on allows you to set up a [Samba](https://www.samba.org) server to access Hass.io folders using Windows network shares. - -
- -Be careful when setting up port forwarding for remote access. If you don't restrict access by setting a username and strong password, your configuration could be exposed to the entire Internet! - -
- -
- -Sometimes shares will not show up under network in Windows. Then you could open the file browser, click the address field where it says "> Network" and type `\\HASSIO` to access Hass.io shares. - -
- -```json -{ - "workgroup": "WORKGROUP", - "username": "", - "password": "", - "interface": "eth0", - "allow_hosts": [ - "10.0.0.0/8", - "172.16.0.0/12", - "192.168.0.0/16" - ], - "veto_files": [ - "._*", - ".DS_Store", - "Thumbs.db", - "icon?", - ".Trashes" - ] -} -``` - -{% configuration %} -workgroup: - description: Set network workgroup name. - required: false - default: "`WORKGROUP`" - type: string -username: - description: Username for logging in. - required: true - type: string -password: - description: Password for `username`. An empty password is not supported. - required: true - type: string -interface: - description: Interface that will start the share. Normally this is `eth0` for ethernet wired connection and `wlan0` for wireless connection. If you are running on an Intel NUC this could also be `enp3s0` for ethernet or `wlp5s0` for wireless connection. - required: false - type: string -allow_hosts: - description: The hosts that are allowed to connect to your Samba server. By default it is limited to people within the same local network. - required: false - default: '`["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]`' - type: list -veto_files: - description: List of files that are neither visible nor accessible. Useful to stop clients from littering the share with temporary hidden files (e.g. macOS .DS_Store, Windows Thumbs.db) - required: false - default: '`["._*", ".DS_Store", "Thumbs.db", "icon?", ".Trashes"]`' - type: list -{% endconfiguration %} diff --git a/source/_addons/snips.markdown b/source/_addons/snips.markdown deleted file mode 100644 index b418fa00ef5..00000000000 --- a/source/_addons/snips.markdown +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Snips.ai" -description: "Enhance your Hass.io installation with a local voice assistant." ---- - -[Snips.ai](https://snips.ai/) is an AI-powered voice assistant that runs on the Raspberry Pi 3 and x86 platforms. It runs on-device and is Private by Design. - -
- -The Snips add-on depends on the Mosquitto add on to bridge to Home Assistant, so make sure that is installed. - -
- -Home Assistant comes with certain Intents builtin to handle common tasks. A complete list of Intents can be found in this wiki [Hass Snips Bundle](https://github.com/tschmidty69/hass-snips-bundle-intents/wiki). - -The Snips add-on by default comes with an assistant that allows you to turn on lights or switches, open covers, or add and list items to a [Shopping List](/integrations/shopping_list/) if that integration is enabled. - -If using a USB microphone and speakers plugged into the Raspberry Pi output, Snips will work without any change to the configuration. Trying saying things like: - -```txt -Turn on kitchen light -Open garage door -What is on my shopping list -``` - -To get started creating your own configuration, follow [their tutorial](https://docs.snips.ai/getting-started/quick-start-console) to create an assistant and download the training data. You can also add the Home Assistant Skill to your assistant to enable the built-in intents, and add or create your own intents to do more complex tasks. - -Now install and activate the [Samba](/addons/samba/) add-on so you can upload your training data. Connect to the "share" Samba share and copy your assistant over. Name the file `assistant.zip` or whatever you have configured in the configuration options. - -Now it's time to start Snips for the first time. You can configure the microphone and sound card using the Add-on interface. Now start the add-on. - -### Add-On configuration - -```json -{ - "mqtt_bridge": { - "active": true, - "host": "172.17.0.1", - "port": 1883, - "user": "", - "password": "" - }, - "assistant": "assistant.zip", - "language": "en", - "custom_tts": false, - "tts_platform": "amazon_polly" -} -``` - -{% configuration %} -assistant: - description: The name of your custom assistant in `/share`. If no assistant is found then a default assistant will be used. - type: string -language: - description: Language. This is used to select the default custom assistant, Currently `en`, `de` and `fr` are supported. - type: string -custom_tts: - description: Whether to use a TTS provider from Home Assistant for a variety of voices. - type: boolean - default: false -tts_platform: - description: Which TTS platform to use. - type: string -{% endconfiguration %} - -### Home Assistant configuration - -A simple configuration just requires this. Consult [Snips.ai integration](/integrations/snips/) for more options. - -```yaml -snips: -``` - -### Home Assistant configuration - -There is an active [discord](https://discordapp.com/invite/3939Kqx) channel and [Snips forum](https://forum.snips.ai/) for further support. - -### Examples - -So now you can turn lights on and off, let's check the weather. Log on to the [console](https://console.snips.ai/). If this is your first time, create a new assistant and add the Home Assistant skill, along with the Weather skill by snips. Download your assistant manually and copy it to the `/share` folder on your Hass.io installation using the Samba add-on. - -Next create a weather sensor, e.g., one for [Dark Sky](/integrations/darksky/), and put the `api_key` in your `secrets.yaml` file. For this example to work you will need to have a valid API key from [Dark Sky](https://darksky.net/dev). - -```yaml -- platform: darksky - name: "Dark Sky Weather" - api_key: !secret dark_sky_key - update_interval: - minutes: 10 - monitored_conditions: - - summary - - hourly_summary - - temperature - - temperature_max - - temperature_min -``` - -Next add this to your `configuration.yaml` file to reference a new `intent_script` integration. This is a good practice to [split your configuration files](/docs/configuration/splitting_configuration/) up. - -```yaml -intent_script: !include intent_script.yaml -``` - -Finally, create this `intent_script.yaml` file in your configuration directory. - -{% raw %} - -```yaml -searchWeatherForecast: - speech: - type: plain - text: > - The weather is currently - {{ states('sensor.dark_sky_weather_temperature') | round(0) }} - degrees outside and {{ states('sensor.dark_sky_weather_summary') }}. - The high today will be - {{ states('sensor.dark_sky_weather_daily_high_temperature') | round(0)}} - and {{ states('sensor.dark_sky_weather_hourly_summary') }} -``` - -{% endraw %} - -Now just restart Hass.io and ask it what the weather is like. - -[their tutorial]: https://github.com/snipsco/snips-platform-documentation/wiki/2.-Create-an-assistant-using-an-existing-bundle diff --git a/source/_addons/ssh.markdown b/source/_addons/ssh.markdown deleted file mode 100644 index 0458117bb9d..00000000000 --- a/source/_addons/ssh.markdown +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "SSH Server" -description: "Allow logging in remotely to Hass.io using SSH." -featured: true ---- - -Setting up an [SSH](https://openssh.com/) server allows access to your Hass.io folders with any SSH client. It also includes a command-line tool to access the [Hass.io API](https://github.com/home-assistant/hassio/blob/dev/API.md). Try it out: - -```bash -hassio help -``` - -
- -This add-on will not enable you to install packages or do anything as root. This is not allowed with Hass.io. - -
- -To use this add-on, you must have a private/public key to log in. To generate them, follow the [instructions for Windows][win] and [these for other platforms][other]. It is possible to set a password for login since version 2.0 but for high security use private/public keys. You can not run both variants at the same time. - -To start this add-on for the first time, you either need to include a key (enclosed in quotation marks, on a single line without line breaks) or set a password in the options section. - -```json -{ - "authorized_keys": [ - "ssh-rsa AKDJD3839...== my-key" - ], - "password": "" -} -``` - -The username for login over SSH is `root`. The complete login command is `ssh root@hassio.local`. - -After logging in, you will find yourself in this add-on's container. The Home Assistant configuration directory is mounted on the path `/config`. - -{% configuration %} -authorized_keys: - description: Your public keys for the authorized key file. Every element will be a line inside that file. - required: false - type: string -password: - description: Set a password for login. We do **NOT** recommend this variant. - required: false - type: string -{% endconfiguration %} - -
- -
- -[win]: https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps -[other]: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/ - -
-This add-on is not compatible if Hass.io was installed via the generic Linux installer. -
diff --git a/source/_addons/tellstick.markdown b/source/_addons/tellstick.markdown deleted file mode 100644 index c618bd9f03b..00000000000 --- a/source/_addons/tellstick.markdown +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "TellStick" -description: "Telldus TellStick service enabler and tools." ---- - -Setting up the [Tellstick](http://telldus.com) service and tools contained in the [telldus-core](http://developer.telldus.com/) package and adding configuration to enable Tellstick and Tellstick Duo to work on your Hass.io. - -To use this add-on, you first install it from the list of Built-in add-ons in Hass.io. -After installation you are presented with a default and example configuration, to alter this you must follow both the JSON format and also be aligned with the [valid parameters for Tellstick configuration file (tellstick.conf)](http://developer.telldus.com/wiki/TellStick_conf). - -After any changes have been made to the configuration, you need to restart the add-on for the changes to take effect. - -You will need to add internal communication details to `configuration.yaml` to enable the integration from Hass.io and the add-on. - -```yaml -# Example configuration.yaml entry -tellstick: - host: core-tellstick - port: [50800, 50801] -``` - -To add [lights](/integrations/tellstick#light), [sensors](/integrations/tellstick#sensor) and [switches](/integrations/tellstick#switch) you follow the guidelines for each type individually that is [described for Home Assistant](/integrations/tellstick/) - -The add-on will also enable you to interact with the `tdtool` via a Home Assistant services call, see example below for self-learning device. - -## Examples - -Example for adding more devices in the add-on configuration (note the comma separator between devices): - -```json -{ - "devices": [ - { - "id": 1, - "name": "Outdoor light", - "protocol": "everflourish", - "model": "selflearning-switch", - "house": "A", - "unit": "1" - }, - { - "id": 2, - "name": "Hallway dimmer", - "protocol": "risingsun", - "model": "selflearning-dimmer", - "house": "A", - "unit": "2" - } - ] -} -``` - -{% configuration %} -id: - description: A number and must be unique for each device. - required: true - type: integer -name: - description: A name for easy identification of the device. - required: true - type: string -protocol: - description: This is the protocol the device uses. More on the different protocols later down. - required: true - type: string -model: - description: The model parameter is only used by some protocols where there exists different types of devices using the same protocol. This can be dimmers versus non-dimmers, codeswitch versus self-learning, etc. - required: false - type: string -house: - description: Depending on protocol the values here can vary a lot to identify or group per house or type. - required: false - type: string -unit: - description: Unit identifier, in most cases a value between 1 to 16 and often used in combination with the house. - required: false - type: integer -fade: - description: Fade is either `true` or `false` and tells a dimmer if it should fade smooth or instant between values (only for IKEA protocol as it seems). - required: false - type: boolean - default: false -code: - description: A number series based on ones and zeroes often used for dip-switch based devices. - required: false - type: string -{% endconfiguration %} - -For more information about the configuration including protocols, see the [telldus documentation](http://developer.telldus.com/wiki/TellStick_conf). - -## Service calls - -If you wish to teach a self-learning device in your TellStick configuration: - -Go to Home Assistant service call in Developer tools and select. - -- Service: `hassio.addon_stdin` -- Enter service Data: - `{"addon":"core_tellstick","input":{"function":"learn","device":"1"}}` - -Replace `1` with the corresponding ID of the device in your TellStick configuration. - -You can also use this to list devices or sensors and read the output in the add-on log: -`{"addon":"core_tellstick","input":{"function":"list-sensors"}}` - -### Supported service commands - -- `"function":"list"`: List currently configured devices with name and device id and all discovered sensors. - -- `"function":"list-sensors"` -- `"function":"list-devices"`: Alternative devices/sensors listing: Shows devices and/or sensors using key=value format (with tabs as separators, one device/sensor per line, no header lines.) - -- `"function":"on","device":"x"`: Turns on device. ’x’ could either be an integer of the device-id, or the name of the device. - -- `"function":"off","device":"x"`: Turns off device. ’x’ could either be an integer of the device-id, or the name of the device. - -- `"function":"bell","device":"x"`: Sends bell command to devices supporting this. ’x’ could either be an integer of the device-id, or the name of the device. - -- `"function":"learn","device":"x"`: Sends a special learn command to devices supporting this. This is normally devices of ’selflearning’ type. ’x’ could either be an integer of the device-id, or the name of the device. diff --git a/source/_docs/autostart/init.d.markdown b/source/_docs/autostart/init.d.markdown index f5e47d2ff11..7aaf41acdf5 100644 --- a/source/_docs/autostart/init.d.markdown +++ b/source/_docs/autostart/init.d.markdown @@ -6,31 +6,31 @@ redirect_from: /getting-started/autostart-init.d/ Home Assistant can run as a daemon within init.d with the script below. -### 1. Copy script +## 1. Copy script Copy either the daemon script or the Python environment script at the end of this page to `/etc/init.d/hass-daemon` depending on your installation. After that, set the script to be executable: ```bash -$ sudo chmod +x /etc/init.d/hass-daemon +sudo chmod +x /etc/init.d/hass-daemon ``` -### 2. Select a user. +## 2. Select a user -Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute hass. +Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute Home Assistant. -### 3. Change hass executable and other variables if required. +## 3. Change `hass` executable and other variables if required Some installation environments may require a change in the Home Assistant executable `hass`. Update script to set `HASS_BIN` to the appropriate `hass` executable path. Please also check the other variables for the appropriate value. In general the defaults should work -### 4. Install this service +## 4. Install this service ```bash -$ sudo service hass-daemon install +sudo service hass-daemon install ``` -### 5. Create logrotate rule +## 5. Create logrotate rule This logrotate script at `/etc/logrotate.d/homeassistant` will create an outage of a few seconds every week at night. If you do not want this add `--log-rotate-days 7` to the `FLAGS` variable in the init script. @@ -55,11 +55,11 @@ File `/var/log/homeassistant/home-assistant.log`: That's it. Restart your machine and Home Assistant should start automatically. -If HA does not start, check the log file output for errors at `/var/log/homeassistant/home-assistant.log` +If Home Assistant does not start, check the log file output for errors at `/var/log/homeassistant/home-assistant.log` -### Extra: Running commands before hass executes +### Extra: Running commands before Home Assistant executes -If any commands need to run before executing hass (like loading a virtual environment), put them in PRE_EXEC. This command must end with a semicolon. +If any commands need to run before executing Home Assistant (like loading a virtual environment), put them in PRE_EXEC. This command must end with a semicolon. ### Daemon script diff --git a/source/_docs/backend/updater.markdown b/source/_docs/backend/updater.markdown index 9f02d765402..3fb75020da2 100644 --- a/source/_docs/backend/updater.markdown +++ b/source/_docs/backend/updater.markdown @@ -6,7 +6,7 @@ redirect_from: /details/updater/ Starting with 0.31 the [updater component](/integrations/updater/) sends an optional report about Home Assistant instance. -If you want to opt-in to include integration information, add `include_used_components` to your config. This will allow the Home Assistant developers to focus development efforts on the most popular components. +If you want to opt-in to include integration information, add `include_used_components` to your configuration. This will allow the Home Assistant developers to focus development efforts on the most popular components. ```yaml updater: @@ -16,7 +16,7 @@ updater: We are only collecting this information to better understand our user base to provide better long term support and feature development. | Name | Description | Example | Data Source | -|-----------------------|--------------------------------------------|------------------------------------|----------------| +| --------------------- | ------------------------------------------ | ---------------------------------- | -------------- | | `arch` | CPU Architecture | `x86_64` | Local Instance | | `distribution` | Linux Distribution name (only Linux) | `Ubuntu` | Local Instance | | `docker` | True if running inside Docker | `false` | Local Instance | diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown index 30528baefb2..adf1fabb702 100644 --- a/source/_docs/configuration.markdown +++ b/source/_docs/configuration.markdown @@ -9,19 +9,19 @@ The web interface can be found at `http://ip.ad.dre.ss:8123/` - for example if y The location of the folder differs between operating systems: -| OS | Path | -| -- | ---- | -| macOS | `~/.homeassistant` | -| Linux | `~/.homeassistant` | +| OS | Path | +| ------- | -------------------------- | +| macOS | `~/.homeassistant` | +| Linux | `~/.homeassistant` | | Windows | `%APPDATA%/.homeassistant` | -| Hass.io | `/config` | -| Docker | `/config` | +| Hass.io | `/config` | +| Docker | `/config` | -If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`. +If you want to use a different folder for configuration, use the configuration command line parameter: `hass --config path/to/config`. Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains integrations to be loaded with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable functionality. -If you run into trouble while configuring Home Assistant, have a look at the [configuration troubleshooting page](/getting-started/troubleshooting-configuration/) and at the [configuration.yaml examples](/cookbook/#example-configurationyaml). +If you run into trouble while configuring Home Assistant, have a look at the [configuration troubleshooting page](/getting-started/troubleshooting-configuration/) and at the [`configuration.yaml` examples](/cookbook/#example-configurationyaml).
diff --git a/source/_docs/ecosystem/certificates/lets_encrypt.markdown b/source/_docs/ecosystem/certificates/lets_encrypt.markdown index be1a62d2bd8..7bd0408b9e7 100644 --- a/source/_docs/ecosystem/certificates/lets_encrypt.markdown +++ b/source/_docs/ecosystem/certificates/lets_encrypt.markdown @@ -11,28 +11,28 @@ If you are using Hass.io do not use this guide. Instead, use the [DuckDNS add-on This guide was added by mf_social on 16/03/2017 and was valid at the time of writing. This guide makes the following assumptions: - * You can access your Home Assistant instance across your local network, and access the device that it is on via SSH from your local network. - * You know the internal IP address of your router and can access your router's configuration pages. - * You have already secured your Home Assistant instance, following the advice on [this page](/docs/configuration/securing/) - * You want to access your Home Assistant instance when you are away from home (ie, not connected to your local network) and secure it with a TLS/SSL certificate. - * You have a basic understanding of the phrases I have used so far. - * You are not currently running anything on port 80 on your network (you'd know if you were). - * If you are not using Home Assistant on a Debian/Raspian system you will be able to convert any of the terminology I use in to the correct syntax for your system. - * You understand that this is a 'guide' covering the general application of these things to the general masses and there are things outside of the scope of it, and it does not cover every eventuality (although I have made some notes where people may stumble). Also, I have used some turns of phrase to make it easier to understand for the novice reader which people of advanced knowledge may say is inaccurate. My goal here is to get you through this guide with a satisfactory outcome and have a decent understanding of what you are doing and why, not to teach you advanced internet communication protocols. - * Each step presumes you have fully completed the previous step successfully, so if you did an earlier step following a different guide, please ensure that you have not missed anything out that may affect the step you have jumped to, and ensure that you adapt any commands to take in to account different file placements from other guides. +- You can access your Home Assistant instance across your local network, and access the device that it is on via SSH from your local network. +- You know the internal IP address of your router and can access your router's configuration pages. +- You have already secured your Home Assistant instance, following the advice on [this page](/docs/configuration/securing/) +- You want to access your Home Assistant instance when you are away from home (ie, not connected to your local network) and secure it with a TLS/SSL certificate. +- You have a basic understanding of the phrases I have used so far. +- You are not currently running anything on port 80 on your network (you'd know if you were). +- If you are not using Home Assistant on a Debian/Raspian system you will be able to convert any of the terminology I use in to the correct syntax for your system. +- You understand that this is a 'guide' covering the general application of these things to the general masses and there are things outside of the scope of it, and it does not cover every eventuality (although I have made some notes where people may stumble). Also, I have used some turns of phrase to make it easier to understand for the novice reader which people of advanced knowledge may say is inaccurate. My goal here is to get you through this guide with a satisfactory outcome and have a decent understanding of what you are doing and why, not to teach you advanced internet communication protocols. +- Each step presumes you have fully completed the previous step successfully, so if you did an earlier step following a different guide, please ensure that you have not missed anything out that may affect the step you have jumped to, and ensure that you adapt any commands to take in to account different file placements from other guides. Steps we will take: - - 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding - - 1 - Set your device to have a static IP address - - 2 - Set up port forwarding without TLS/SSL and test connection - - 3 - Set up a DuckDNS account - - 4 - Obtain a TLS/SSL certificate from Let's Encrypt - - 5 - Check the incoming connection - - 6 - Clean up port forwards - - 7 - Set up a sensor to monitor the expiry date of the certificate - - 8 - Set up an automatic renewal of the TLS/SSL certificate - - 9 - Set up an alert to warn us if something went wrong +- 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding +- 1 - Set your device to have a static IP address +- 2 - Set up port forwarding without TLS/SSL and test connection +- 3 - Set up a DuckDNS account +- 4 - Obtain a TLS/SSL certificate from Let's Encrypt +- 5 - Check the incoming connection +- 6 - Clean up port forwards +- 7 - Set up a sensor to monitor the expiry date of the certificate +- 8 - Set up an automatic renewal of the TLS/SSL certificate +- 9 - Set up an alert to warn us if something went wrong ### 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding @@ -49,10 +49,11 @@ We will be looking for a system to run like this (in this example I will pretend ```text Outside world -> 203.0.113.12:8123 -> your router -> 192.168.0.200:8123 ``` + Sounds simple? It really is except for two small, but easy to overcome, complications: - * IP addresses are often dynamically allocated, so they can change. - * Because of the way the internet works you cannot chain IP addresses together to get from where you are, to where you want to go. +- IP addresses are often dynamically allocated, so they can change. +- Because of the way the internet works you cannot chain IP addresses together to get from where you are, to where you want to go. To get around the issue of changing IP addresses we must remember that there are two IP addresses affected. Your external one (which we will 'call' to get on to your network from the internet) and your internal one (192.168.0.200 in the example I am currently using). @@ -60,11 +61,12 @@ So, we can use a static IP to ensure that whenever our device running Home Assis We then have no control over our external IP, as our Service Provider will give us a new one at random intervals. To fix this we will use a service called DuckDNS which will give us a name for our connection (something like examplehome.duckdns.org) and behind the scenes will continue to update your external IP. So no matter how many times the IP address changes, typing examplehome.duckdns.org in to our browser will convert to the correct, up-to-date, IP address. This is covered in step 3 below. -To get around the issue of not being able to chain the IP addresses together (I can't say I want to call 203.0.113.12 and be put through to 192.168.0.200, and then be put through to extension 8123) we use port forwarding. Port forwarding is the process of telling your router which device to allow the outside connection to speak to. In the doctors surgery example, port forwarding is the receptionist. This takes a call from outside, and forwards it to the correct extension number inside. It is important to note that port forwarding can forward an incoming request for one port to a different port on your internal network if you so choose, and we will be doing this later on. The end result being that when we have our TLS/SSL certificate our incoming call will by default be requesting port 443 (because that is the default HTTPS port, like the default SSH port is 22), our port forwarding rule can forward this to our HA instance on port 8123 (or we can specify the port number in the URL). When this guide is completed we will run something like this: +To get around the issue of not being able to chain the IP addresses together (I can't say I want to call 203.0.113.12 and be put through to 192.168.0.200, and then be put through to extension 8123) we use port forwarding. Port forwarding is the process of telling your router which device to allow the outside connection to speak to. In the doctors surgery example, port forwarding is the receptionist. This takes a call from outside, and forwards it to the correct extension number inside. It is important to note that port forwarding can forward an incoming request for one port to a different port on your internal network if you so choose, and we will be doing this later on. The end result being that when we have our TLS/SSL certificate our incoming call will by default be requesting port 443 (because that is the default HTTPS port, like the default SSH port is 22), our port forwarding rule can forward this to our Home Assistant instance on port 8123 (or we can specify the port number in the URL). When this guide is completed we will run something like this: ```text Outside world -> https://examplehome.duckdns.org -> 203.0.113.12:443 -> your router -> 192.168.0.200:8123 ``` + So, let's make it happen... ### 1 - Set your device to have a static IP address @@ -136,7 +138,7 @@ All working? Hooray! You now have a static IP. This will now always be your in ### 2 - Set up port forwarding without TLS/SSL and test connection -Log in to your router's configuration pages and find the port forwarding options. This bit is hard to write a guide for because each router has a different way of presenting these options. Searching google for "port forwarding" and the name of your router may help. When you find it you will likely have options similar to: +Log in to your router's configuration pages and find the port forwarding options. This bit is hard to write a guide for because each router has a different way of presenting these options. Searching Google for "port forwarding" and the name of your router may help. When you find it you will likely have options similar to: Service name - Port Range - Local IP - Local Port - Protocol @@ -162,7 +164,7 @@ https://whatismyipaddress.com/ This will tell you your current external IP address -Type the external IP address in to the URL bar with http:// in front and :8123 after like so (203.0.113.12 is my example!): +Type the external IP address in to the URL bar with `http://` in front and :8123 after like so (203.0.113.12 is my example!): ```text http://203.0.113.12:8123 @@ -170,7 +172,7 @@ http://203.0.113.12:8123 Can you see your Home Assistant instance? If not, your router may not support 'loopback' - try the next step anyway and if that works, and this one still doesn't, just remember that you cannot use loopback, so will have to use internal addresses when you're on your home network. More on this later on if it's relevant to you. -Just to verify this isn't some kind of witchcraft that is actually using your internal network, pick up your phone, disconnect it from your WiFi so that you are on your mobile data and not connected to the home network, put the same URL in the browser on your phone. +Just to verify this isn't some kind of witchcraft that is actually using your internal network, pick up your phone, disconnect it from your Wi-Fi so that you are on your mobile data and not connected to the home network, put the same URL in the browser on your phone. Can you see it now, from a device that is definitely not connected to your local network? Excellent! You now have a remotely accessible Home Assistant instance. @@ -178,7 +180,7 @@ But what if your external IP changes? Plus, remembering all those numbers is pr ### 3 - Set up a DuckDNS account -Open your browser and go to https://duckdns.org. +Open your browser and go to . Sign in and create an account using one of the id validation options in the top right corner. @@ -208,7 +210,7 @@ What now happens behind the scenes is this: - DuckDNS receives the request and forwards the request to your router's external IP address (which has been kept up to date by your device running Home Assistant) - Your router receives the request on port 8123 and checks the port forwarding rules -- It finds the rule you created in step 2 and forwards the request to your HA instance +- It finds the rule you created in step 2 and forwards the request to your Home Assistant instance - Your browser displays your Home Assistant instance frontend. Did it work? Super! @@ -326,7 +328,7 @@ Protocol - Both Remember to save the rule changes. -Now edit your configuration.yaml file to reflect the SSL entries and your base URL (changing the `examplehome` subdomain to yours in all three places): +Now edit your `configuration.yaml` file to reflect the SSL entries and your base URL (changing the `examplehome` subdomain to yours in all three places): ```yaml http: @@ -335,9 +337,9 @@ http: base_url: examplehome.duckdns.org ``` -You may wish to set up other options for the [http](/integrations/http/) integration at this point, these extra options are beyond the scope of this guide. +You may wish to set up other options for the [HTTP](/integrations/http/) integration at this point, these extra options are beyond the scope of this guide. -Save the changes to configuration.yaml. Restart Home Assistant. +Save the changes to `configuration.yaml`. Restart Home Assistant. In step 3 we accessed our Home Assistant from the outside world with our DuckDNS URL and our port number. We are going to use a slightly different URL this time. @@ -345,7 +347,7 @@ In step 3 we accessed our Home Assistant from the outside world with our DuckDNS https://examplehome.duckdns.org ``` -Note the **S** after http, and that no port number is added. This is because https will use port 443 automatically, and we have already set up our port forward to redirect this request to our Home Assistant instance on port 8123. +Note the **S** after http, and that no port number is added. This is because HTTPS will use port 443 automatically, and we have already set up our port forward to redirect this request to our Home Assistant instance on port 8123. You should now be able to see your Home Assistant instance via your DuckDNS URL, and importantly note that your browser shows the connection as secure. @@ -379,8 +381,8 @@ If you have any more for Home Assistant you should delete them now. If you only You are now part of one of two groups: - * If you have BOTH rules you are able to set up auto renewals of your certificates using port 80 and the standard http challenge, as performed above. - * If you only have one, you are still able to set up auto renewals of your certificates, but will have to specify additional options when renewing that will temporarily stop Home Assistant and use port 8123 for certificate renewal. +- If you have BOTH rules you are able to set up auto renewals of your certificates using port 80 and the standard HTTP challenge, as performed above. +- If you only have one, you are still able to set up auto renewals of your certificates, but will have to specify additional options when renewing that will temporarily stop Home Assistant and use port 8123 for certificate renewal. Please remember whether you are a ONE-RULE person or a BOTH-RULE person for step 8! @@ -392,10 +394,10 @@ Move on to step 7 to see how to monitor your certificates expiry date, and be re Setting a sensor to read the number of days left on your TLS/SSL certificate before it expires is not required, but it has the following advantages: - * You can physically see how long you have left, pleasing your inner control freak - * You can set automations based on the number of days left - * You can set alerts to notify you if your certificate has not been renewed and is coming close to expiry. - * If you cannot set up automatic renewals due to your ISP blocking port 80, you will have timely reminders to complete the process manually. +- You can physically see how long you have left, pleasing your inner control freak +- You can set automations based on the number of days left +- You can set alerts to notify you if your certificate has not been renewed and is coming close to expiry. +- If you cannot set up automatic renewals due to your ISP blocking port 80, you will have timely reminders to complete the process manually. If you do not wish to set up a sensor you can skip straight to step 8 to learn how to update your certificates. @@ -423,13 +425,13 @@ sensor: command: "ssl-cert-check -b -c /etc/letsencrypt/live/examplehome.duckdns.org/cert.pem | awk '{ print $NF }'" ``` -Save the configuration.yaml. Restart Home Assistant. +Save the `configuration.yaml`. Restart Home Assistant. On your default_view you should now see a sensor badge containing your number of days until expiry. If you've been following this guide from the start and have not taken any breaks in between, this should be 89 or 90. The sensor will update every 3 hours. You can place this reading on a card using groups, or hide it using customize. These topics are outside of the scope of this guide, but information can be found on their respective integrations pages: [Group](/integrations/group/) and [Customize](/docs/configuration/customizing-devices/) Got your sensor up and running and where you want it? Top drawer! Nearly there, now move on to the final steps to ensure that you're never without a secure connection in the future. -### 8 - Set up an automatic renewal of the TLS/SSL certificate. +### 8 - Set up an automatic renewal of the TLS/SSL certificate The certbot program we downloaded in step 4 contains a script that will renew your certificate. The script will only obtain a new certificate if the current one has less than 30 days left on it, so running the script more often than is actually needed will not cause any harm. @@ -439,47 +441,49 @@ If you are a TWO-RULE person (from step 6), you can automatically renew your cer There are a number of options for automating the renewal process: -#### Option 1: +#### Option 1 + Your certificate can be renewed as a 'cron job' - cron jobs are background tasks run by the computer at specified intervals (and are totally independent of Home Assistant). Defining cron is outside of the scope of this guide but you will have had dealings with `crontab` when setting up DuckDNS in step 3 To set a cron job to run the script at regular intervals: - * SSH in to your device running Home Assistant. - * Change to your Home Assistant user (where `homeassistant` is the name of the user): +- SSH in to your device running Home Assistant. +- Change to your Home Assistant user (where `homeassistant` is the name of the user): -```bash -sudo -u homeassistant -H -s -``` + ```bash + sudo -u homeassistant -H -s + ``` - * Open the crontab: +- Open the crontab: -```bash -crontab -e -``` + ```bash + crontab -e + ``` - * If you are a TWO-RULE Person: Scroll to the bottom of the file and paste in the following line +- If you are a TWO-RULE Person: Scroll to the bottom of the file and paste in the following line -```text -30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01 -``` + ```text + 30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01 + ``` -* If you are a ONE-RULE Person: Scroll to the bottom of the file and paste in the following line +- If you are a ONE-RULE Person: Scroll to the bottom of the file and paste in the following line -```text -30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service" -``` -* Let's take a moment to look at the differences here: - 1. This method uses a `tls-sni` challenge, so the Let's Encrypt CA will attempt to bind port 443 externally (which you have forwarded) - 2. `--tls-sni-01-port 8123` tells certbot to bind port 8123 internally, which matches with the port forwarding rules that are already in place. - 3. We define pre-hooks and post-hooks that stop our Home Assistant service before certbot runs, freeing port 8123 for certificate renewal, and restart Home Assistant after renewal is complete. + ```text + 30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service" + ``` - * Save the file and exit +- Let's take a moment to look at the differences here: + 1. This method uses a `tls-sni` challenge, so the Let's Encrypt CA will attempt to bind port 443 externally (which you have forwarded) + 2. `--tls-sni-01-port 8123` tells certbot to bind port 8123 internally, which matches with the port forwarding rules that are already in place. + 3. We define pre-hooks and post-hooks that stop our Home Assistant service before certbot runs, freeing port 8123 for certificate renewal, and restart Home Assistant after renewal is complete. +- Save the file and exit + +#### Option 2 -#### Option 2: You can set an automation in Home Assistant to run the certbot renewal script. -Add the following sections to your configuration.yaml if you are a TWO-RULE person +Add the following sections to your `configuration.yaml` if you are a TWO-RULE person ```yaml shell_command: @@ -494,37 +498,39 @@ automation: action: service: shell_command.renew_ssl ``` + If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"` -#### Option 3: +#### Option 3 + You can manually update the certificate when your certificate is less than 30 days to expiry. To manually update: - * SSH in to your device running Home Assistant. - * Change to your Home Assistant user (where `homeassistant` is the name of the user): +- SSH in to your device running Home Assistant. +- Change to your Home Assistant user (where `homeassistant` is the name of the user): -```bash -sudo -u homeassistant -H -s -``` + ```bash + sudo -u homeassistant -H -s + ``` - * Change to your certbot folder +- Change to your certbot folder -```bash -cd ~/certbot/ -``` + ```bash + cd ~/certbot/ + ``` - * Run the renewal command +- Run the renewal command -```bash -./certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01 -``` + ```bash + ./certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01 + ``` -* If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"` +- If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"` So, now were all set up. We have our secured, remotely accessible Home Assistant instance and we're on track for keeping our certificates up to date. But what if something goes wrong? What if the automation didn't fire? What if the cron job forgot to run? What if the dog ate my homework? Read on to set up an alert so you can be notified in plenty of time if you need to step in and sort out any failures. -### 9 - Set up an alert to warn us if something went wrong. +### 9 - Set up an alert to warn us if something went wrong We set up our automatic renewal of our certificates and whatever method we used the certificate should be renewed on or around 30 days before it expires. But what if a week later it still hasn't been? This alert will go off if the expiry time on the certificate gets down to 21 days. This will give you 3 weeks to fix the problem, get your new certificate installed and get another 90 days of secure Home Assistant connections in play. diff --git a/source/_docs/installation/docker.markdown b/source/_docs/installation/docker.markdown index 780244d65ee..01a99b4cc6e 100644 --- a/source/_docs/installation/docker.markdown +++ b/source/_docs/installation/docker.markdown @@ -11,19 +11,19 @@ Installation with Docker is straightforward. Adjust the following command so tha ### Linux ```bash -$ docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable +docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable ``` ### Raspberry Pi 3 (Raspbian) ```bash -$ docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/raspberrypi3-homeassistant:stable +docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/raspberrypi3-homeassistant:stable ``` You need to replace `/PATH_TO_YOUR_CONFIG` with your path to the configuration, for example if you choose your configuration path to be `/home/pi/homeassistant`, then command would be: - + ```bash -$ docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /home/pi/homeassistant:/config --net=host homeassistant/raspberrypi3-homeassistant:stable +docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /home/pi/homeassistant:/config --net=host homeassistant/raspberrypi3-homeassistant:stable ``` ### macOS @@ -33,7 +33,7 @@ When using `docker-ce` (or `boot2docker`) on macOS, you are unable to map the lo If you wish to browse directly to `http://localhost:8123` from your macOS host, meaning forward ports directly to the container, replace the `--net=host` switch with `-p 8123:8123`. More detail can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10). ```bash -$ docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config -p 8123:8123 homeassistant/home-assistant:stable +docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config -p 8123:8123 homeassistant/home-assistant:stable ``` Alternatively, `docker-compose` works with any recent release of `docker-ce` on macOS. Note that (further down this page) we provide an example `docker-compose.yml` however it differs from the `docker run` example above. To make the .yml directives match, you would need to make _two_ changes: first add the equivalent `ports:` directive, then _remove_ the `network_mode: host` section. This is because `Port mapping is incompatible with network_mode: host:`. More details can be found at [Docker networking docs](https://docs.docker.com/network/). Note also the `/dev/tty*` device name used by your Arduino etc. devices will differ from the Linux example, so the compose `mount:` may require updates. @@ -48,13 +48,13 @@ Before proceeding, make sure you have shared out a drive for docker to mount to. ```powershell -$ docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable +docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable ``` It’s easier to understand the trick when put into practice. Here we would like to mount a current working directory (something like `C:\Users\\homeassistant` make sure this exists first) into the `homeassistant/home-assistant:stable` image at the `/config` location in the container. We would do that as so: ```powershell -$ docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v //c/Users//homeassistant:/config --net=host homeassistant/home-assistant:stable +docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v //c/Users//homeassistant:/config --net=host homeassistant/home-assistant:stable ``` When running Home Assistant in Docker on Windows, you may have some difficulty getting ports to map for routing (since the `--net=host` switch actually applies to the hypervisor's network interface). To get around this, you will need to add port proxy ipv4 rules to your local Windows machine, like so (Replacing '192.168.1.10' with whatever your Windows IP is, and '10.0.50.2' with whatever your Docker container's IP is): @@ -71,23 +71,24 @@ This will let you access your Home Assistant portal from `http://localhost:8123` As Synology within DSM now supports Docker (with a neat UI), you can simply install Home Assistant using docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see The steps would be: -* Install "Docker" package on your Synology NAS -* Launch Docker-app and move to "Registry"-section -* Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will make version updates easier later on. -* Wait for some time until your NAS has pulled the image -* Move to the "Image"-section of the Docker-app -* Click on "Launch" -* Choose a container-name you want (e.g., "homeassistant") -* Click on "Advanced Settings" -* Set "Enable auto-restart" if you like -* Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount path" has to be "/config", so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named "config" or "homeassistant/config" to avoid confusion when referencing it within service calls. -* Within "Network" select "Use same network as Docker Host" -* To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) -* Confirm the "Advanced Settings" -* Click on "Next" and then "Apply" -* Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`) -To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS: +- Install "Docker" package on your Synology NAS +- Launch Docker-app and move to "Registry"-section +- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will make version updates easier later on. +- Wait for some time until your NAS has pulled the image +- Move to the "Image"-section of the Docker-app +- Click on "Launch" +- Choose a container-name you want (e.g., "homeassistant") +- Click on "Advanced Settings" +- Set "Enable auto-restart" if you like +- Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount path" has to be "/config", so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named "config" or "homeassistant/config" to avoid confusion when referencing it within service calls. +- Within "Network" select "Use same network as Docker Host" +- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +- Confirm the "Advanced Settings" +- Click on "Next" and then "Apply" +- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`) + +To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS: @@ -99,7 +100,7 @@ Adjust the following Terminal command as follows : - Replace `/PATH_TO_YOUR_CONFIG` points at the folder where you want to store your configuration - Replace `/PATH_TO_YOUR_USB_STICK` matches the path for your USB stick (e.g., `/dev/ttyACM0` for most Synology users) -- Replace "Australia/Melbourne" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +- Replace "Australia/Melbourne" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) Run it in Terminal. @@ -111,17 +112,18 @@ Complete the remainder of the Z-Wave configuration by [following the instruction Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following: -* Go to the Docker-app and move to "Registry"-section -* Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will overwrite your current image to the latest version. -* Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar) -* Move to "Container"-section -* Stop your container if it's running -* Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your config-directory -* Start the container again - it will then boot up with the new Home Assistant image +- Go to the Docker-app and move to "Registry"-section +- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will overwrite your current image to the latest version. +- Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar) +- Move to "Container"-section +- Stop your container if it's running +- Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your config-directory +- Start the container again - it will then boot up with the new Home Assistant image Remark: to restart your Home Assistant within Synology NAS, you just have to do the following: -* Go to the Docker-app and move to "Container"-section -* Right-click on it and select "Action"->"Restart". + +- Go to the Docker-app and move to "Container"-section +- Right-click on it and select "Action"->"Restart".
If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assistant on Synology Docker these instructions do not correctly configure the container to access the USB devices. To configure these devices on your Synology Docker Home Assistant you can follow the instructions provided here by Phil Hawthorne. @@ -129,23 +131,23 @@ If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assista ### QNAP NAS -As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see https://www.qnap.com/solution/container_station/en/index.php +As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see The steps would be: - - Install "Container Station" package on your Qnap NAS - - Launch Container Station and move to "Create Container"-section - - Search image "homeassistant/home-assistant" with Docker hub and click on "Install" - Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is "homeassistant/armhf-homeassistant" - - Choose "latest" version and click next - - Choose a container-name you want (e.g., "homeassistant") - - Click on "Advanced Settings" - - Within "Shared Folders" click on "Volume from host" > "Add" and choose either an existing folder or add a new folder. The "mount point has to be `/config`, so that Home Assistant will use it for the configuration and logs. - - Within "Network" and select Network Mode to "Host" - - To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - - Click on "Create" - - Wait for some time until your NAS has created the container - - Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example `http://192.xxx.xxx.xxx:8123`) +- Install "Container Station" package on your Qnap NAS +- Launch Container Station and move to "Create Container"-section +- Search image "homeassistant/home-assistant" with Docker hub and click on "Install" + Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is "homeassistant/armhf-homeassistant" +- Choose "latest" version and click next +- Choose a container-name you want (e.g., "homeassistant") +- Click on "Advanced Settings" +- Within "Shared Folders" click on "Volume from host" > "Add" and choose either an existing folder or add a new folder. The "mount point has to be `/config`, so that Home Assistant will use it for the configuration and logs. +- Within "Network" and select Network Mode to "Host" +- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +- Click on "Create" +- Wait for some time until your NAS has created the container +- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example `http://192.xxx.xxx.xxx:8123`) Remark: To update your Home Assistant on your Docker within Qnap NAS, you just remove container and image and do steps again (Don't remove "config" folder). @@ -153,38 +155,38 @@ If you want to use a USB Bluetooth adapter or Z-Wave USB stick with Home Assista #### Z-Wave - - Connect to your NAS over SSH - - Load cdc-acm kernel module(when nas restart need to run this command) - `insmod /usr/local/modules/cdc-acm.ko` - - Find USB devices attached. Type command: - `ls /dev/tty*` - The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. Like : `ttyACM0` - - - Run Docker command: - `docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable` - - `-v` is your config path - `-e` is set timezone - - - Edit `configuration.yaml` +- Connect to your NAS over SSH +- Load cdc-acm kernel module(when nas restart need to run this command) + `insmod /usr/local/modules/cdc-acm.ko` +- Find USB devices attached. Type command: + `ls /dev/tty*` + The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. Like : `ttyACM0` + +- Run Docker command: + `docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable` + + `-v` is your config path + `-e` is set timezone + +- Edit `configuration.yaml` ```yaml zwave: usb_path: /dev/ttyACM0 ``` -That will tell Home Assistant where to look for our Z-wave radio. +That will tell Home Assistant where to look for our Z-Wave radio. #### Bluetooth - - Connect to your NAS over SSH - - Run Docker command: - `docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable` - - First `-v` is your config path - `-e` is set timezone - - - Edit the `configuration.yaml` file +- Connect to your NAS over SSH +- Run Docker command: + `docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable` + + First `-v` is your config path + `-e` is set timezone + +- Edit the `configuration.yaml` file ```yaml device_tracker: @@ -219,13 +221,13 @@ As the docker command becomes more complex, switching to `docker-compose` can be Then start the container with: ```bash -$ docker-compose up -d +docker-compose up -d ``` To restart Home Assistant when you have changed configuration: ```bash -$ docker-compose restart +docker-compose restart ``` ## Exposing Devices diff --git a/source/_docs/installation/freenas.markdown b/source/_docs/installation/freenas.markdown index e4179928d32..4ce9bbf28d4 100644 --- a/source/_docs/installation/freenas.markdown +++ b/source/_docs/installation/freenas.markdown @@ -8,6 +8,7 @@ description: "Installation of Home Assistant on your FreeNAS." This has been tested on FreeNAS 11.2 and should also work on FreeBSD 11.x as well. These instructions assume you already have a running and accessible jail. For more information on creating a jail read the official FreeNAS User Guide regarding [Jails](https://www.ixsystems.com/documentation/freenas/11.2/jails.html). Once you have the jail available, follow the steps below. Directories used follow standard BSD conventions but can be adjusted as you wish. Enter the Home Assistant jail. If you don't know which name you have given the jail, you can use the `iocage list` command to check. + ```bash # If the jail is called 'HomeAssistant' iocage exec HomeAssistant @@ -87,13 +88,13 @@ vi /usr/local/etc/rc.d/homeassistant # KEYWORD: shutdown # # homeassistant_user: The user account used to run the homeassistant daemon. -# This is optional, however do not specifically set this to an -# empty string as this will cause the daemon to run as root. -# Default: homeassistant +# This is optional, however do not specifically set this to an +# empty string as this will cause the daemon to run as root. +# Default: homeassistant # homeassistant_group: The group account used to run the homeassistant daemon. -# This is optional, however do not specifically set this to an -# empty string as this will cause the daemon to run with group wheel. -# Default: homeassistant +# This is optional, however do not specifically set this to an +# empty string as this will cause the daemon to run with group wheel. +# Default: homeassistant # # homeassistant_venv: Directory where homeassistant virtualenv is installed. # Default: "/usr/local/share/homeassistant" @@ -217,11 +218,11 @@ You can also restart the jail to ensure that Home Assistant starts on boot.
-USB Z-wave sticks may give `dmesg` warnings similar to "data interface 1, has no CM over data, has no break". This doesn't impact the function of the Z-Wave stick in Home Assistant. Just make sure the proper `/dev/cu*` is used in the Home Assistant `configuration.yaml` file. +USB Z-Wave sticks may give `dmesg` warnings similar to "data interface 1, has no CM over data, has no break". This doesn't impact the function of the Z-Wave stick in Home Assistant. Just make sure the proper `/dev/cu*` is used in the Home Assistant `configuration.yaml` file.
-# Adding support for Z-wave stick +## Adding support for Z-Wave stick The following two packages need to be installed in the jail @@ -230,7 +231,8 @@ pkg install gmake pkg install libudev-devd ``` -Then you can install the zwave package +Then you can install the Z-Wave package + ```bash su homeassistant cd /usr/local/share/homeassistant @@ -240,36 +242,42 @@ deactivate exit ``` -Stop the hass Jail +Stop the Home Assistant Jail + ```bash sudo iocage stop HomeAssistant ``` -Edit the devfs rules on the Freenas Host +Edit the devfs rules on the FreenNAS Host + ```bash vi /etc/devfs.rules ``` -Add the following lines +Add the following lines + ```bash [devfsrules_jail_allow_usb=7] add path 'cu\*' mode 0660 group 8123 unhide ``` Reload devfs + ```bash sudo service devfs restart ``` -Edit the ruleset used by the jail in the Freenas GUI by going to Jails -> hass -> Edit -> Jail Properties -> devfs_ruleset +Edit the ruleset used by the jail in the FreeNAS GUI by going to Jails -> `hass` -> Edit -> Jail Properties -> devfs_ruleset Set it to 7 -Start the hass jail +Start the Home Assistant jail + ```bash sudo iocage start HomeAssistant ``` -Connect to the hass jail and verify that you see the modem devices +Connect to the Home Assistant jail and verify that you see the modem devices + ```bash sudo iocage console HomeAssistant ``` @@ -277,15 +285,19 @@ sudo iocage console HomeAssistant ```bash ls /dev/cu* ``` + This should output the following + ```bash /dev/cuau0 /dev/cuaU0 ``` -Add the zwave config to your `configuration.yaml` and restart HA +Add the Z-Wave config to your `configuration.yaml` and restart Home Assistant + ```bash vi /home/homeassistant/.homeassistant/configuration.yaml ``` + ```yaml zwave: usb_path: /dev/cuaU0 @@ -296,8 +308,8 @@ zwave: service homeassistant restart ``` +## Updating -# Updating Before updating, read the changelog to see what has changed and how it affects your Home Assistant instance. Enter the jail using `iocage exec `. Stop the Home Assistant service: ```bash diff --git a/source/_docs/z-wave/controllers.markdown b/source/_docs/z-wave/controllers.markdown index 261e84da83f..067fa2a8d74 100644 --- a/source/_docs/z-wave/controllers.markdown +++ b/source/_docs/z-wave/controllers.markdown @@ -13,13 +13,13 @@ There have [been reports](https://www.raspberrypi.org/forums/viewtopic.php?f=28&
-* Aeotec Z-Stick Series 5 -* Everspring USB stick - Gen 5 -* Sigma Designs UZB stick -* Vision USB stick - Gen5 -* Zooz Z-Wave Plus S2 stick ZST10 -* ZWave.me Razberry Board -* ZWave.me UZB1 stick +- Aeotec Z-Stick Series 5 +- Everspring USB stick - Gen 5 +- Sigma Designs UZB stick +- Vision USB stick - Gen5 +- Zooz Z-Wave Plus S2 stick ZST10 +- ZWave.me Razberry Board +- ZWave.me UZB1 stick We recommend that you purchase a [Z-Wave Plus](https://z-wavealliance.org/z-wave_plus_certification/) controller, to take advantage of the improvements this provides. As OpenZWave doesn't support S2 or Smart Start, there's no need to buy one just for support of these features. @@ -31,10 +31,10 @@ We recommend that you purchase a [Z-Wave Plus](https://z-wavealliance.org/z-wave The alternative to a stick is a hub that supports Z-Wave. Home Assistant supports the following hubs with Z-Wave support: - - [Vera](/integrations/vera/) - - [Wink](/integrations/wink/) - - [Fibaro](/integrations/fibaro/) - - [SmartThings](/integrations/smartthings/) +- [Vera](/integrations/vera/) +- [Wink](/integrations/wink/) +- [Fibaro](/integrations/fibaro/) +- [SmartThings](/integrations/smartthings/) ## Controller Notes diff --git a/source/_docs/z-wave/entities.markdown b/source/_docs/z-wave/entities.markdown index d958447edbb..830fcde6212 100644 --- a/source/_docs/z-wave/entities.markdown +++ b/source/_docs/z-wave/entities.markdown @@ -5,7 +5,7 @@ description: "A summary of common entity names."
-This is a work in progress, based upon reports in the forum, the author's own devices and reading of various documentation. It will be incomplete, so if you have a device that isn't reported here or have a device that reports a different value, please provide a report in the [Z-Wave section](https://community.home-assistant.io/c/configuration/zwave) of the forum or the #zwave channel on [Discord](https://discord.gg/RkajcgS). +This is a work in progress, based upon reports in the forum, the author's own devices and reading of various documentation. It will be incomplete, so if you have a device that isn't reported here or have a device that reports a different value, please provide a report in the [Z-Wave section](https://community.home-assistant.io/c/configuration/zwave) of the forum or the `#zwave` channel on [Discord](https://discord.gg/RkajcgS).
@@ -22,6 +22,7 @@ This is for a single purpose sensor, multi sensors are explained under Multi Sen Devices (usually sensors) that support the Alarm command class will create entities starting with `sensor`, and with some generic suffixes, and a suffix that relates to the supported alarm class. For example, the smoke detector `lounge` will have an entity `sensor.lounge_smoke`, and possibly also `sensor.lounge_alarm_type` and `sensor.lounge_alarm_level`. If the device creates a `binary_sensor` entity, it is recommended to use that rather then the `sensor` entity. Note that the older Z-Wave alarm command class version 1 didn't have standardized types, and so each manufacturer specified their own version and type info. With Version 2 the alarm type was standardized to the below list. See the [openzwave alarm command class documents](https://github.com/OpenZWave/open-zwave/wiki/Alarm-Command-Class) for more info. You can see which version your sensor supports via the zwcfg_0x\*.xml file. An example with version 2 support: + ```xml ``` @@ -70,74 +71,74 @@ The meaning of the `alarm_level` entity depends on the nature of the alarm senso #### Smoke, CO, and CO2 - - **1**: Detection - will include a Node Location Report - - **2**: Detection (unknown location) - - **254**: Unknown event +- **1**: Detection - will include a Node Location Report +- **2**: Detection (unknown location) +- **254**: Unknown event #### Heat - - **1**: Overheat detected - will include a Node Location Report - - **2**: Overheat detected (unknown location) - - **3**: Rapid temperature rise - will include a Node Location Report - - **4**: Rapid temperature rise (unknown location) - - **5**: Underheat detection - will include a Node Location Report - - **6**: Underheat detection (unknown location) - - **254**: Unknown event +- **1**: Overheat detected - will include a Node Location Report +- **2**: Overheat detected (unknown location) +- **3**: Rapid temperature rise - will include a Node Location Report +- **4**: Rapid temperature rise (unknown location) +- **5**: Underheat detection - will include a Node Location Report +- **6**: Underheat detection (unknown location) +- **254**: Unknown event #### Water leak - - **1**: Water leak detected - will include a Node Location Report - - **2**: Water leak detected (unknown location) - - **3**: Water level dropped - will include a Node Location Report - - **4**: Water level dropped (unknown location) - - **254**: Unknown event +- **1**: Water leak detected - will include a Node Location Report +- **2**: Water leak detected (unknown location) +- **3**: Water level dropped - will include a Node Location Report +- **4**: Water level dropped (unknown location) +- **254**: Unknown event #### Access control - - **1**: Manual lock - - **2**: Manual unlock - - **3**: RF lock - - **4**: RF unlock - - **5**: Keypad lock - will include the User Identifier of the User Code Report - - **6**: Keypad unlock - will include the User Identifier of the User Code Report - - **254**: Unknown event +- **1**: Manual lock +- **2**: Manual unlock +- **3**: RF lock +- **4**: RF unlock +- **5**: Keypad lock - will include the User Identifier of the User Code Report +- **6**: Keypad unlock - will include the User Identifier of the User Code Report +- **254**: Unknown event #### Burglar - - **1**: Intrusion - will include a Node Location Report - - **2**: Intrusion (unknown location) - - **3**: Tampering (case opened) - - **4**: Tampering (invalid code) - - **5**: Glass break - will include a Node Location Report - - **6**: Glass break (invalid code) - - **254**: Unknown event +- **1**: Intrusion - will include a Node Location Report +- **2**: Intrusion (unknown location) +- **3**: Tampering (case opened) +- **4**: Tampering (invalid code) +- **5**: Glass break - will include a Node Location Report +- **6**: Glass break (invalid code) +- **254**: Unknown event #### Power Management - - **1**: Power applied - - **2**: AC disconnected - - **3**: AC re-connected - - **4**: Surge detection - - **5**: Voltage drop or drift - - **254**: Unknown event +- **1**: Power applied +- **2**: AC disconnected +- **3**: AC re-connected +- **4**: Surge detection +- **5**: Voltage drop or drift +- **254**: Unknown event #### System Alarm - - **1**: System hardware failure - - **2**: System software failure - - **254**: Unknown event +- **1**: System hardware failure +- **2**: System software failure +- **254**: Unknown event #### Emergency Alarm - - **1**: Contact Police - - **2**: Contact Fire Service - - **3**: Contact Medical Service - - **254**: Unknown event +- **1**: Contact Police +- **2**: Contact Fire Service +- **3**: Contact Medical Service +- **254**: Unknown event #### Alarm Clock - - **1**: Wake up - - **254**: Unknown event +- **1**: Wake up +- **254**: Unknown event ### Access Control Entity @@ -150,41 +151,45 @@ The meaning of the `alarm_level` entity depends on the nature of the alarm senso If your device has an `access_control` entity, but not a `binary_sensor` equivalent, you can use a [template binary sensor](/integrations/binary_sensor.template/) to create one (here we've defined it as a door, but you can use [any relevant device class](/integrations/binary_sensor/#device-class): {% raw %} + ```yaml binary_sensor: - platform: template - sensors: + sensors: YOUR_SENSOR: friendly_name: "Friendly name here" device_class: door value_template: "{{ is_state('sensor.YOUR_ORIGINAL_SENSOR_access_control', '22') }}" ``` + {% endraw %} ### Burglar Entity - **burglar**: These *may* vary between brands - - **0**: Not active - - **2**: Smoke (?) - - **3**: Tamper - - **8**: Motion - - **22**: Open - - **23**: Closed - - **254**: Deep sleep - - **255**: Case open + - **0**: Not active + - **2**: Smoke (?) + - **3**: Tamper + - **8**: Motion + - **22**: Open + - **23**: Closed + - **254**: Deep sleep + - **255**: Case open If your device has a `burglar` entity, but not a `binary_sensor` equivalent, you can use a [template binary sensor](/integrations/binary_sensor.template/) to create one (here we've defined it as a motion sensor, but you can use [any relevant device class](/integrations/binary_sensor/#device-class): {% raw %} + ```yaml binary_sensor: - platform: template - sensors: + sensors: YOUR_SENSOR: friendly_name: "Friendly name here" device_class: motion value_template: "{{ is_state('sensor.YOUR_SENSOR_burglar', '8') }}" ``` + {% endraw %} ### Source Node ID Entity diff --git a/source/_docs/z-wave/installation.markdown b/source/_docs/z-wave/installation.markdown index fa4de6f11e2..7927a10b858 100644 --- a/source/_docs/z-wave/installation.markdown +++ b/source/_docs/z-wave/installation.markdown @@ -15,7 +15,7 @@ zwave: device_config: !include zwave_device_config.yaml ``` -{% configuration zwave %} +{% configuration Z-Wave %} usb_path: description: The port where your device is connected to your Home Assistant host. Z-Wave sticks will generally be `/dev/ttyACM0` and GPIO hats will generally be `/dev/ttyAMA0`. required: false @@ -32,12 +32,12 @@ config_path: type: string default: the 'config' that is installed by python-openzwave polling_interval: - description: The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the zwave network and cause problems. + description: The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the Z-Wave network and cause problems. required: false type: integer default: 60000 debug: - description: Print verbose z-wave info to log. + description: Print verbose Z-Wave info to log. required: false type: boolean default: false diff --git a/source/_docs/z-wave/query-stage.markdown b/source/_docs/z-wave/query-stage.markdown index ce56787a752..81f5f1f5b7d 100644 --- a/source/_docs/z-wave/query-stage.markdown +++ b/source/_docs/z-wave/query-stage.markdown @@ -7,24 +7,24 @@ When the Z-Wave mesh is first started, the controller will go through all the fo Your devices will still function normally while marked as `Initializing`. -| Stage | Description | -|------------------------|--------------------------------------------------------------------| -| None | Query process hasn't started for this node | -| ProtocolInfo | Retrieve protocol information | -| Probe | Ping device to see if alive | -| WakeUp | Start wake up process if a sleeping node | -| ManufacturerSpecific1 | Retrieve manufacturer name and product ids if ProtocolInfo lets us | -| NodeInfo | Retrieve info about supported, controlled command classes | -| NodePlusInfo | Retrieve Z-Wave+ info and update device classes | -| SecurityReport | Retrieve a list of Command Classes that require Security | -| ManufacturerSpecific2 | Retrieve manufacturer name and product ids | -| Versions | Retrieve version information | -| Instances | Retrieve information about multiple command class instances | -| Static | Retrieve static information (doesn't change) | -| CacheLoad | Ping a device upon restarting with cached config for the device | -| Associations | Retrieve information about associations | -| Neighbors | Retrieve node neighbor list | -| Session | Retrieve session information (changes infrequently) | -| Dynamic | Retrieve dynamic information (changes frequently) | -| Configuration | Retrieve configurable parameter information (only done on request) | -| Complete | Query process is completed for this node | +| Stage | Description | +| --------------------- | ---------------------------------------------------------------------- | +| None | Query process hasn't started for this node | +| ProtocolInfo | Retrieve protocol information | +| Probe | Ping device to see if alive | +| WakeUp | Start wake up process if a sleeping node | +| ManufacturerSpecific1 | Retrieve manufacturer name and product ids if ProtocolInfo lets us | +| NodeInfo | Retrieve info about supported, controlled command classes | +| NodePlusInfo | Retrieve Z-Wave+ info and update device classes | +| SecurityReport | Retrieve a list of Command Classes that require Security | +| ManufacturerSpecific2 | Retrieve manufacturer name and product ids | +| Versions | Retrieve version information | +| Instances | Retrieve information about multiple command class instances | +| Static | Retrieve static information (doesn't change) | +| CacheLoad | Ping a device upon restarting with cached configuration for the device | +| Associations | Retrieve information about associations | +| Neighbors | Retrieve node neighbor list | +| Session | Retrieve session information (changes infrequently) | +| Dynamic | Retrieve dynamic information (changes frequently) | +| Configuration | Retrieve configurable parameter information (only done on request) | +| Complete | Query process is completed for this node | diff --git a/source/_docs/z-wave/services.markdown b/source/_docs/z-wave/services.markdown index a6014382cb9..ba6a914e3b6 100644 --- a/source/_docs/z-wave/services.markdown +++ b/source/_docs/z-wave/services.markdown @@ -5,32 +5,32 @@ description: "Services exposed by the Z-Wave component." The `zwave` integration exposes multiple services to help maintain the network. All of these are available through the Z-Wave control panel. -| Service | Description | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| add_node | Put the Z-Wave controller in inclusion mode. Allows you to add a new device to the Z-Wave network. | -| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows you to add a new device with secure communications to the Z-Wave network. | -| cancel_command | Cancels a running Z-Wave command. If you have started an add_node or remove_node command, and decide you are not going to do it, then this must be used to stop the inclusion/exclusion command. | -| change_association | Add or remove an association in the Z-Wave network | -| heal_network | Tells the controller to "heal" the Z-Wave network. Basically asks the nodes to tell the controller all of their neighbors so the controller can re-figure out optimal routing. | -| heal_node | Tells the controller to "heal" a specific node on the network. Requires `node_id` field. You can also force return route update with `return_routes` field. -| print_config_parameter | Prints Z-Wave node's config parameter value to the (console) log. | -| print_node | Print all states of Z-Wave node. | -| refresh_entity | Refresh the Z-Wave entity by refreshing dependent values. | -| refresh_node | Refresh the Z-Wave node. | -| refresh_node_value | Refresh the specified value of a Z-Wave node. | -| remove_node | Put the Z-Wave controller in exclusion mode. Allows you to remove a device from the Z-Wave network. | -| rename_node | Sets a node's name. Requires a `node_id` and `name` field. | -| rename_value | Sets a value's name. Requires a `node_id`, `value_id`, and `name` field. | -| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail. | -| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail. | -| reset_node_meters | Reset a node's meter values. Only works if the node supports this. | -| set_config_parameter | Lets the user set a config parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g., `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g., `"value": 1`). | -| set_node_value | Set the specified value of a Z-Wave node. | -| soft_reset | Tells the controller to do a "soft reset." This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command. | -| start_network | Starts the Z-Wave network. | -| stop_network | Stops the Z-Wave network. | -| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead." | -| test_node | Tells the controller to send no-op command(s) to a specific node. Requires `node_id` field. You can specify amount of test_messages to send by specifying it with `messages` field. In theory, this could bring back nodes marked as "presumed dead" +| Service | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| add_node | Put the Z-Wave controller in inclusion mode. Allows you to add a new device to the Z-Wave network. | +| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows you to add a new device with secure communications to the Z-Wave network. | +| cancel_command | Cancels a running Z-Wave command. If you have started an add_node or remove_node command, and decide you are not going to do it, then this must be used to stop the inclusion/exclusion command. | +| change_association | Add or remove an association in the Z-Wave network | +| heal_network | Tells the controller to "heal" the Z-Wave network. Basically asks the nodes to tell the controller all of their neighbors so the controller can re-figure out optimal routing. | +| heal_node | Tells the controller to "heal" a specific node on the network. Requires `node_id` field. You can also force return route update with `return_routes` field. | +| print_config_parameter | Prints Z-Wave node's configuration parameter value to the (console) log. | +| print_node | Print all states of Z-Wave node. | +| refresh_entity | Refresh the Z-Wave entity by refreshing dependent values. | +| refresh_node | Refresh the Z-Wave node. | +| refresh_node_value | Refresh the specified value of a Z-Wave node. | +| remove_node | Put the Z-Wave controller in exclusion mode. Allows you to remove a device from the Z-Wave network. | +| rename_node | Sets a node's name. Requires a `node_id` and `name` field. | +| rename_value | Sets a value's name. Requires a `node_id`, `value_id`, and `name` field. | +| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail. | +| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail. | +| reset_node_meters | Reset a node's meter values. Only works if the node supports this. | +| set_config_parameter | Lets the user set a configuration parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g., `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g., `"value": 1`). | +| set_node_value | Set the specified value of a Z-Wave node. | +| soft_reset | Tells the controller to do a "soft reset." This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command. | +| start_network | Starts the Z-Wave network. | +| stop_network | Stops the Z-Wave network. | +| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead." | +| test_node | Tells the controller to send no-op command(s) to a specific node. Requires `node_id` field. You can specify amount of test_messages to send by specifying it with `messages` field. In theory, this could bring back nodes marked as "presumed dead" | The `soft_reset` and `heal_network` commands can be used to help keep a Z-Wave network running reliably. This is a configuration option for the `zwave` component. The option defaults to `false` but can be enabled by setting `autoheal` to true. This, however, is bad practice since it introduces overhead that can be avoided since you only need to do a `heal_network` whenever one of the following actions are done: diff --git a/source/_integrations/alexa.intent.markdown b/source/_integrations/alexa.intent.markdown index f67737a01f9..b434486c9b2 100644 --- a/source/_integrations/alexa.intent.markdown +++ b/source/_integrations/alexa.intent.markdown @@ -28,7 +28,7 @@ The built-in Alexa integration allows you to integrate Home Assistant into Alexa - Click the yellow "Add a new skill" button in the top right - Skill Type: Custom Interaction Model (default) - Name: Home Assistant - - Invocation name: home assistant (or be creative, up to you) + - Invocation name: `home assistant` (or be creative, up to you) - Version: 1.0 - Endpoint: This will be the ARN for the Lambda Function you will create next. @@ -40,7 +40,7 @@ The Alexa Custom skill will trigger a AWS Lambda function to process the request OK, let's go. You first need sign in your [AWS console](https://console.aws.amazon.com/), if you don't have an AWS account yet, you can create a new user [here](https://aws.amazon.com/free/) with 12-month free tier benefit. You don't need worry the cost if your account has already passed the first 12 months, AWS provides up to 1 million Lambda requests, 1GB of outbound data and unlimited inbound data for free every month for all users. See [Lambda pricing](https://aws.amazon.com/lambda/pricing/) for details. -#### Create an IAM Role for Lambda +#### Create an IAM Role for Lambda The first thing you need to do after you sign in to the [AWS console](https://console.aws.amazon.com/) is to create an IAM Role for Lambda execution. AWS has very strict access control, you have to explicitly define and assign the permissions. @@ -61,9 +61,9 @@ Next you need to create a Lambda function. - Click `Service` in top navigation bar, expand the menu to display all AWS services, click `Lambda` under `Compute` section to navigate to Lambda console. Or you may use this [link](https://console.aws.amazon.com/lambda/home) - **IMPORTANT** Your current region will be displayed on the top right corner, make sure you select right region base on your Amazon account's country: - * **US East (N.Virginia)** region for English (US) or English (CA) skills - * **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills - * **US West (Oregon)** region for Japanese and English (AU) skills. + - **US East (N.Virginia)** region for English (US) or English (CA) skills + - **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills + - **US West (Oregon)** region for Japanese and English (AU) skills. - Click `Functions` in the left navigation bar, display list of your Lambda functions. - Click `Create function`, select `Author from scratch`, then input a `Function name`. - Select *Python 3.6* or *Python 3.7* as `Runtime`. @@ -74,10 +74,10 @@ Next you need to create a Lambda function. - Click your Lambda Function icon in the middle of the diagram and scroll down, you will see a `Function code` window. - Clear the example code and copy the Python script from: [https://gist.github.com/lpomfrey/97381cf4316553b03622c665ae3a47da](https://gist.github.com/lpomfrey/97381cf4316553b03622c665ae3a47da) - Scroll down again and you will find `Environment variables`, add the following environment variables as needed: - * BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*. - * NOT_VERIFY_SSL *(optional)*: set to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate. - * DEBUG *(optional)*: set to *True* to log debugging messages. - * LONG_LIVED_ACCESS_TOKEN *(optional, not recommended)*: you will connect your Alexa Custom skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to reading the token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.) + - BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*. + - NOT_VERIFY_SSL *(optional)*: set to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate. + - DEBUG *(optional)*: set to *True* to log debugging messages. + - LONG_LIVED_ACCESS_TOKEN *(optional, not recommended)*: you will connect your Alexa Custom skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to reading the token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)

Screenshot: Environment variables in Lambda function @@ -93,20 +93,20 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom - Sign in to the [Alexa Developer Console][alexa-dev-console] and go to the `Alexa Skills` page. - Find the skill you just created and click `Edit` in the `Actions` column. - Click `ACCOUNT LINKING` in the left navigation bar of build page -- Input all information required. Assuming your Home Assistant can be accessed by https://[YOUR HOME ASSISTANT URL:PORT] - * `Authorization URI`: https://[YOUR HOME ASSISTANT URL]/auth/authorize - * `Access Token URI`: https://[YOUR HOME ASSISTANT URL]/auth/token +- Input all information required. Assuming your Home Assistant can be accessed by `https://[YOUR HOME ASSISTANT URL:PORT]` + - `Authorization URI`: `https://[YOUR HOME ASSISTANT URL]/auth/authorize` + - `Access Token URI`: `https://[YOUR HOME ASSISTANT URL]/auth/token` - Note: you must use a valid/trusted SSL Certificate and port 443 for account linking to work - * `Client ID`: - - https://pitangui.amazon.com/ if you are in US - - https://layla.amazon.com/ if you are in EU - - https://alexa.amazon.co.jp/ if you are in JP or AU - + - `Client ID`: + - `https://pitangui.amazon.com/` if you are in US + - `https://layla.amazon.com/` if you are in EU + - `https://alexa.amazon.co.jp/` if you are in JP or AU + The trailing slash is important here. - * `Client Secret`: input anything you like, Home Assistant does not check this field - * `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*. - * `Scope`: input `intent`. Home Assistant doesn't use this yet, we may use it in the future when we allow more fine-grained access control. + - `Client Secret`: input anything you like, Home Assistant does not check this field + - `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*. + - `Scope`: input `intent`. Home Assistant doesn't use this yet, we may use it in the future when we allow more fine-grained access control. - You can leave `Domain List` and `Default Access Token Expiration Time` as empty.

@@ -115,11 +115,11 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom - Click `Save` button in the top right corner. - Next, you will use the Alexa Mobile App or [Alexa web-based app](#alexa-web-based-app) to link your account. - * Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills` - * Click the Custom skill you just created. - * Click `Enable`. - * A new window will open to direct you to your Home Assistant's login screen. - * After you successfully login, you will be redirected back to Alexa app. + - Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills` + - Click the Custom skill you just created. + - Click `Enable`. + - A new window will open to direct you to your Home Assistant's login screen. + - After you successfully login, you will be redirected back to Alexa app. ### Configuring your Amazon Alexa skill @@ -288,6 +288,7 @@ To start, you need to get the skill id: - Click the "View Skill ID" link and copy the ID The configuration is the same as an intent with the exception being you will use your skill ID instead of the intent name. + ```yaml intent_script: amzn1.ask.skill.08888888-7777-6666-5555-444444444444: @@ -340,7 +341,6 @@ text: !include alexa_confirm.yaml Alexa will now respond with a random phrase each time. You can use the include for as many different intents as you like so you only need to create the list once. - [amazon-dev-console]: https://developer.amazon.com [large-icon]: /images/integrations/alexa/alexa-512x512.png [small-icon]: /images/integrations/alexa/alexa-108x108.png diff --git a/source/_integrations/alexa.smart_home.markdown b/source/_integrations/alexa.smart_home.markdown index 5b079708272..0280afa3017 100644 --- a/source/_integrations/alexa.smart_home.markdown +++ b/source/_integrations/alexa.smart_home.markdown @@ -12,10 +12,10 @@ ha_codeowners: Amazon Alexa provides a Smart Home API for richer home automation control without requiring the user to say the skill name, such as: -* _"Alexa, turn off the light."_ -* _"Alexa, set the thermostat to cool."_ -* _"Alexa, is the garage door open?"_ - +- _"Alexa, turn off the light."_ +- _"Alexa, set the thermostat to cool."_ +- _"Alexa, is the garage door open?"_ + It takes considerable effort to configure. Your Home Assistant instance must be accessible from the Internet, and you need to create an Amazon Developer account and an Amazon Web Services (AWS) account. An easier solution is to use [Home Assistant Cloud](/integrations/cloud/). The [Emulated Hue integration][emulated-hue-component] provides a simpler alternative to use utterances such as _"Alexa, turn on the kitchen light"_. However, it has some limitations since everything looks like a light bulb. @@ -29,7 +29,7 @@ For Home Assistant Cloud Users, documentation can be found [here](https://www.na

-**Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant** +Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant: - [Requirements](#requirements) - [Create an Amazon Alexa Smart Home Skill](#create-an-amazon-alexa-smart-home-skill) @@ -40,7 +40,7 @@ For Home Assistant Cloud Users, documentation can be found [here](https://www.na - [Configure the Smart Home Service Endpoint](#configure-the-smart-home-service-endpoint) - [Account Linking](#account-linking) - [Alexa Smart Home Component Configuration](#alexa-smart-home-component-configuration) -- [Supported Integrations](#supported-integrations) +- [Supported Platforms](#supported-platforms) - [Alexa Web-Based App](#alexa-web-based-app) - [Troubleshooting](#troubleshooting) - [Debugging](#debugging) @@ -102,9 +102,9 @@ Next you need create a Lambda function. - Click `Service` in top navigation bar, expand the menu to display all AWS services, click `Lambda` under `Compute` section to navigate to Lambda console. Or you may use this [link](https://console.aws.amazon.com/lambda/home) - **IMPORTANT** Your current region will be displayed on the top right corner, make sure you select right region base on your Amazon account's country: - * **US East (N.Virginia)** region for English (US) or English (CA) skills - * **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills - * **US West (Oregon)** region for Japanese and English (AU) skills. + - **US East (N.Virginia)** region for English (US) or English (CA) skills + - **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills + - **US West (Oregon)** region for Japanese and English (AU) skills. - Click `Functions` in the left navigation bar, display list of your Lambda functions. - Click `Create function`, select `Author from scratch`, then input a `Function name`. - Select *Python 3.6* or *Python 3.7* as `Runtime`. @@ -115,10 +115,10 @@ Next you need create a Lambda function. - Click your Lambda function icon in the middle of the diagram, scroll down you will see a `Function code` window. - Clear the example code, copy the Python script from: [https://gist.github.com/matt2005/744b5ef548cc13d88d0569eea65f5e5b](https://gist.github.com/matt2005/744b5ef548cc13d88d0569eea65f5e5b) (modified code to support Alexa's proactive mode, see details below) - Scroll down a little bit, you will find `Environment variables`, you need add 4 environment variables: - * BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*. - * NOT_VERIFY_SSL *(optional)*: you can set it to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate. - * DEBUG *(optional)*: set to *True* to log the debug message - * LONG_LIVED_ACCESS_TOKEN *(optional, not recommend)*: you will connect your Alexa Smart Home skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to read token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.) + - BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*. + - NOT_VERIFY_SSL *(optional)*: you can set it to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate. + - DEBUG *(optional)*: set to *True* to log the debug message + - LONG_LIVED_ACCESS_TOKEN *(optional, not recommend)*: you will connect your Alexa Smart Home skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to read token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)

Screenshot: Environment variables in Lambda function @@ -182,20 +182,20 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom - Sign in [Alexa Developer Console][alexa-dev-console], go to `Alexa Skills` page if you are not. - Find the skill you just created, click `Edit` link in the `Actions` column. - Click `ACCOUNT LINKING` in the left navigation bar of build page -- Input all information required. Assuming your Home Assistant can be accessed by https://[YOUR HOME ASSISTANT URL:PORT] - * `Authorization URI`: https://[YOUR HOME ASSISTANT URL]/auth/authorize - * `Access Token URI`: https://[YOUR HOME ASSISTANT URL]/auth/token +- Input all information required. Assuming your Home Assistant can be accessed by `https://[YOUR HOME ASSISTANT URL:PORT]` + - `Authorization URI`: `https://[YOUR HOME ASSISTANT URL]/auth/authorize` + - `Access Token URI`: `https://[YOUR HOME ASSISTANT URL]/auth/token` - Note: you must use a valid/trusted SSL Certificate and port 443 for account linking to work - * `Client ID`: - - https://pitangui.amazon.com/ if you are in US - - https://layla.amazon.com/ if you are in EU - - https://alexa.amazon.co.jp/ if you are in JP and AU (not verified yet) + - `Client ID`: + - `https://pitangui.amazon.com/` if you are in US + - `https://layla.amazon.com/` if you are in EU + - `https://alexa.amazon.co.jp/` if you are in JP and AU (not verified yet) The trailing slash is important here. - * `Client Secret`: input anything you like, Home Assistant does not check this field - * `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*. - * `Scope`: input `smart_home`, Home Assistant is not using it yet, we may use it in the future when we allow more fine-grained access control. + - `Client Secret`: input anything you like, Home Assistant does not check this field + - `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*. + - `Scope`: input `smart_home`, Home Assistant is not using it yet, we may use it in the future when we allow more fine-grained access control. - You can leave `Domain List` and `Default Access Token Expiration Time` as empty.

@@ -204,12 +204,12 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom - Click `Save` button in the top right corner. - Next, you will use Alexa Mobile App or [Alexa web-based app](#alexa-web-based-app) to link your account. - * Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills` - * Click the Smart Home skill you just created. - * Click `Enable`. - * A new window will open to direct you to your Home Assistant's login screen. - * After you success login, you will be redirected back to Alexa app. - * You can discovery your devices now. + - Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills` + - Click the Smart Home skill you just created. + - Click `Enable`. + - A new window will open to direct you to your Home Assistant's login screen. + - After you success login, you will be redirected back to Alexa app. + - You can discovery your devices now. - Now, you can ask your Echo or in Alexa App, _"Alexa, turn on bedroom"_ 🎉 ## Alexa Smart Home Component Configuration @@ -238,6 +238,7 @@ alexa: switch.stairs: display_categories: LIGHT ``` + {% configuration %} alexa: description: Alexa configuration @@ -321,6 +322,7 @@ alexa: The `locale` should match the location and language used for your Amazon echo devices. The supported locales are: + - `de-DE` - `en-AU` - `en-CA` @@ -346,9 +348,10 @@ The `endpoint`, `client_id` and `client_secret` are optional, and are only requi ### Configure Filter -By default, no entity will be excluded. To limit which entities are being exposed to Alexa, you can use the `filter` parameter. Keep in mind that only [supported components](#supported-integrations) can be added. +By default, no entity will be excluded. To limit which entities are being exposed to Alexa, you can use the `filter` parameter. Keep in mind that only [supported platforms](#supported-platforms) can be added. {% raw %} + ```yaml # Example filter to include specified domains and exclude specified entities alexa: @@ -360,6 +363,7 @@ alexa: exclude_entities: - light.kitchen_light ``` + {% endraw %} Filters are applied as follows: @@ -368,14 +372,14 @@ Filters are applied as follows: 2. Includes, no excludes - only include specified entities 3. Excludes, no includes - only exclude specified entities 4. Both includes and excludes: - * Include domain specified + - Include domain specified - if domain is included, and entity not excluded, pass - if domain is not included, and entity not included, fail - * Exclude domain specified + - Exclude domain specified - if domain is excluded, and entity not included, fail - if domain is not excluded, and entity not excluded, pass - if both include and exclude domains specified, the exclude domains are ignored - * Neither include or exclude domain specified + - Neither include or exclude domain specified - if entity is included, pass (as #2 above) - if entity include and exclude, the entity exclude is ignored @@ -401,6 +405,7 @@ See [Alexa Display Categories][alexa-display-categories] for a complete list Home Assistant supports the following integrations through Alexa using a Smart Home Skill. For Home Assistant Cloud Users, documentation can be found [here](https://www.nabucasa.com/config/amazon_alexa/). The following integrations are currently supported: + - [Alarm Control Panel](#alarm-control-panel) - [Alert](#alert-automation-group-input-boolean) - [Automation](#alert-automation-group-input-boolean) @@ -437,10 +442,10 @@ The following integrations are currently supported: Arm and disarm Alarm Control Panel entities. Ask Alexa for the state of the Alarm Control Panel entity. -* _"Alexa, arm my home in away mode."_ -* _"Alexa, arm my home."_ -* _"Alexa, disarm my home."_ -* _"Alexa, is my home armed?"_ +- _"Alexa, arm my home in away mode."_ +- _"Alexa, arm my home."_ +- _"Alexa, disarm my home."_ +- _"Alexa, is my home armed?"_ #### Arming @@ -472,28 +477,28 @@ The existing code is never communicated to Alexa from Home Assistant. During dis Turn on and off Alerts, Automations, Groups, and Input Boolean entities as switches. -* _"Alexa, turn on the front door alert."_ -* _"Alexa, turn off energy saving automations."_ -* _"Alexa, Downstairs to on."_ - +- _"Alexa, turn on the front door alert."_ +- _"Alexa, turn off energy saving automations."_ +- _"Alexa, Downstairs to on."_ + ### Binary Sensor Requires [Proactive Events](#proactive-events) enabled. Binary Sensors with a [`device_class`](/integrations/binary_sensor/#device-class) attribute of `door` `garage_door` `opening` `window` `motion` `presense` are supported. -|`device_class`|Alexa Sensor Type| -| :---: | :---: | -|`door`|Contact| -|`garage_door`|Contact| -|`opening`|Contact| -|`window`|Contact| -|`motion`|Motion| -|`presense`|Motion| +| `device_class` | Alexa Sensor Type | +| :------------: | :---------------: | +| `door` | Contact | +| `garage_door` | Contact | +| `opening` | Contact | +| `window` | Contact | +| `motion` | Motion | +| `presense` | Motion | Ask Alexa for the state of a contact sensor. -* _"Alexa, is the bedroom window open?"_ +- _"Alexa, is the bedroom window open?"_ #### Routines @@ -508,6 +513,7 @@ Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#cus Requires [Proactive Events](#proactive-events) enabled. Configure a `binary_sensor` with `display_category` of `DOORBELL` in the [`entity_config`](#entity_config) to gain access to the doorbell notification settings in the Alexa App. + ```yaml alexa: smart_home: @@ -563,16 +569,17 @@ Each Echo device will need the communication and Announcements setting enabled, ### Climate Single, double, and triple set-point thermostats are supported. The temperature value from the thermostat will also be exposed at a separate [temperature sensor](#sensor). + #### Set Thermostat Temperature -* _"Alexa, set thermostat to 20."_ -* _"Alexa, set the AC to 75."_ -* _"Alexa, make it warmer in here."_ -* _"Alexa, make it cooler in here."_ +- _"Alexa, set thermostat to 20."_ +- _"Alexa, set the AC to 75."_ +- _"Alexa, make it warmer in here."_ +- _"Alexa, make it cooler in here."_ #### Thermostat Mode -* _"Alexa, set living room thermostat to automatic."_ +- _"Alexa, set living room thermostat to automatic."_ - `DRY` is shown in Alexa app as `DEHUMIDIFY` - `ECO` is handled as a `preset` in Home Assistant, and will not display in the Alexa app. @@ -580,23 +587,23 @@ Single, double, and triple set-point thermostats are supported. The temperature To change the thermostat mode, the exact utterance must be used: -* _"Alexa, set [entity name] to [mode utterance]."_ +- _"Alexa, set [entity name] to [mode utterance]."_ If the climate entity supports on/off, use _"turn on"_ and _"turn off"_ utterances with the entity name or the mode utterance. -* _"Alexa, turn on the [mode utterance]."_ -* _"Alexa, turn off the [entity name]."_ +- _"Alexa, turn on the [mode utterance]."_ +- _"Alexa, turn off the [entity name]."_ Alexa supports the following utterances value for climate thermostat mode: -|HA Climate Mode | Alexa Mode Utterances | -|--- |--- | -|`AUTO` | _"auto"_, _"automatic"_| -|`COOL` | _"cool"_, _"cooling"_| -|`HEAT` | _"heat"_, _"heating"_| -|`ECO` | _"eco"_, _"economical"_| -|`DRY` | _"dry"_, _"dehumidify"_| -|`OFF` | _"off"_| +| HA Climate Mode | Alexa Mode Utterances | +| --------------- | ----------------------- | +| `AUTO` | _"auto"_, _"automatic"_ | +| `COOL` | _"cool"_, _"cooling"_ | +| `HEAT` | _"heat"_, _"heating"_ | +| `ECO` | _"eco"_, _"economical"_ | +| `DRY` | _"dry"_, _"dehumidify"_ | +| `OFF` | _"off"_ | ### Cover @@ -612,10 +619,10 @@ Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#cus Home Assistant configures covers with semantics that provide _"raise"_, _"lower"_, _"open"_, _"close"_ utterances for covers. In addition to semantics _"turn on"_ / _"turn off"_ utterances will also work. -* _"Alexa, open the garage door."_ -* _"Alexa, close the curtain."_ -* _"Alexa, lower the shades."_ -* _"Alexa, raise the roof!"_ +- _"Alexa, open the garage door."_ +- _"Alexa, close the curtain."_ +- _"Alexa, lower the shades."_ +- _"Alexa, raise the roof!"_ Semantics are assigned based on the features supported by the cover. If the cover supports tilt functionality, the semantics _"open"_ and _"close"_ are assigned to the tilt functionality, and the semantics _"raise"_ and _"lower"_ are assigned to the position functionality. @@ -625,13 +632,13 @@ If the cover does not support tilt, all semantics _"raise"_, _"lower"_, _"open"_ Covers that support a set position can be controlled using percentages. -* _"Alexa, set the [entity name] position to thirty percent."_ -* _"Alexa, increase [entity name] position by ten percent."_ -* _"Alexa, decrease [entity name] position by twenty percent."_ +- _"Alexa, set the [entity name] position to thirty percent."_ +- _"Alexa, increase [entity name] position by ten percent."_ +- _"Alexa, decrease [entity name] position by twenty percent."_ -|Locale|Friendly Name Synonyms| -|---|---| -|`en-US`|_"position"_, _"opening"_| +| Locale | Friendly Name Synonyms | +| ------- | ------------------------- | +| `en-US` | _"position"_, _"opening"_ | Currently, Alexa only supports friendly name synonyms for the `en-US` locale. @@ -639,13 +646,13 @@ Currently, Alexa only supports friendly name synonyms for the `en-US` locale. Covers that support tilt position can be controlled using percentages. -* _"Alexa, set the [entity name] tilt to thirty percent."_ -* _"Alexa, increase [entity name] tilt by ten percent."_ -* _"Alexa, decrease [entity name] tilt by twenty percent."_ +- _"Alexa, set the [entity name] tilt to thirty percent."_ +- _"Alexa, increase [entity name] tilt by ten percent."_ +- _"Alexa, decrease [entity name] tilt by twenty percent."_ -|Locale|Friendly Name Synonyms| -|---|---| -|`en-US`|_"tilt"_, _"angle"_, _"direction"_| +| Locale | Friendly Name Synonyms | +| ------- | ---------------------------------- | +| `en-US` | _"tilt"_, _"angle"_, _"direction"_ | Currently, Alexa only supports friendly name synonyms for the `en-US` locale. @@ -666,28 +673,28 @@ Control fan speed, direction, and oscillation. The fan device must support the `speed` attribute. `speed` can be set using a percentage or a range value determined from the `speed_list` attribute. -* _"Alexa, set the fan speed to three."_ -* _"Alexa, set the fan speed to fifty percent."_ -* _"Alexa, set the fan power level to fifty percent."_ -* _"Alexa, turn up the speed on the tower fan."_ -* _"Alexa, set the air speed on the tower fan to maximum."_ +- _"Alexa, set the fan speed to three."_ +- _"Alexa, set the fan speed to fifty percent."_ +- _"Alexa, set the fan power level to fifty percent."_ +- _"Alexa, turn up the speed on the tower fan."_ +- _"Alexa, set the air speed on the tower fan to maximum."_ The `speed_list` attribute is used to determine the range value. For example, using a `speed_list` consisting of `[off, low, medium, high]` the range values would be `0:off`, `1:low`, `2:medium`, `3:high`. The following table lists the possible friendly name synonyms available for a fan with `speed_list: [off, low, medium, high]`. - -|Fan Range|Friendly Name Synonyms| -|---|---| -|0|_"zero"_, _"off"_| -|1|_"one"_, _"thirty-three percent"_, _"low"_, _"minimum"_, _"min"_| -|2|_"two"_, _"sixty-six percent"_, _"medium"_| -|3|_"three"_, _"one hundred percent"_, _"high"_, _"maximum"_, _"max"_| + +| Fan Range | Friendly Name Synonyms | +| --------- | ------------------------------------------------------------------ | +| 0 | _"zero"_, _"off"_ | +| 1 | _"one"_, _"thirty-three percent"_, _"low"_, _"minimum"_, _"min"_ | +| 2 | _"two"_, _"sixty-six percent"_, _"medium"_ | +| 3 | _"three"_, _"one hundred percent"_, _"high"_, _"maximum"_, _"max"_ | The following synonyms can be used for _"fan speed"_ -|Locale|Friendly Name Synonyms| -|---|---| -|`en-US`|_"fan speed"_, _"airflow speed"_, _"wind speed"_, _"air speed"_, _"air velocity"_, _"power level"_| +| Locale | Friendly Name Synonyms | +| ------- | -------------------------------------------------------------------------------------------------- | +| `en-US` | _"fan speed"_, _"airflow speed"_, _"wind speed"_, _"air speed"_, _"air velocity"_, _"power level"_ | Currently, Alexa only supports friendly name synonyms for the `en-US` locale. @@ -695,20 +702,20 @@ Currently, Alexa only supports friendly name synonyms for the `en-US` locale. The fan device must support the `direction` attribute. -* _"Alexa, set the fan direction to forward."_ -* _"Alexa, set the fan direction to reverse."_ +- _"Alexa, set the fan direction to forward."_ +- _"Alexa, set the fan direction to reverse."_ #### Fan Oscillation The fan device must support the `oscillating` attribute. -* _"Alexa, is oscillate on for the tower fan?"_ -* _"Alexa, turn on swivel for the tower fan."_ -* _"Alexa, turn on oscillation mode for the table fan."_ +- _"Alexa, is oscillate on for the tower fan?"_ +- _"Alexa, turn on swivel for the tower fan."_ +- _"Alexa, turn on oscillation mode for the table fan."_ -|Locale|Friendly Name Synonyms| -|---|---| -|`en-US`|_"oscillate"_, _"swivel"_, _"oscillation"_, _"spin"_, _"back and forth"_| +| Locale | Friendly Name Synonyms | +| ------- | ------------------------------------------------------------------------ | +| `en-US` | _"oscillate"_, _"swivel"_, _"oscillation"_, _"spin"_, _"back and forth"_ | Currently, Alexa only supports friendly name synonyms for the `en-US` locale. @@ -737,29 +744,29 @@ Display category will default to `CAMERA` to enable presence detected notificati Control an `input_number` entity with Alexa. Configures Alexa with the `min`, `max`, `step`, and `unit_of_measurement` attributes for the entity. -* _"Alexa, set [entity name] to forty five [unit of measurement]."_ -* _"Alexa, increase the [entity name] by two."_ -* _"Alexa, set the [entity name] to maximum."_ +- _"Alexa, set [entity name] to forty five [unit of measurement]."_ +- _"Alexa, increase the [entity name] by two."_ +- _"Alexa, set the [entity name] to maximum."_ The following table lists the possible friendly name synonyms available for a Input Number with `min: -90, max: 90, step: 45, unit_of_measurement: degrees`. - -|Fan Range|Friendly Name Synonyms| -|---|---| -|-90|_"negative ninety"_, _"minimum"_, _"min"_| -|-45|_"negative forty five"_| -|0|_"zero"_| -|45|_"forty five"_| -|90|_"ninety"_, _"maximum"_, _"max"_| + +| Fan Range | Friendly Name Synonyms | +| --------- | ----------------------------------------- | +| -90 | _"negative ninety"_, _"minimum"_, _"min"_ | +| -45 | _"negative forty five"_ | +| 0 | _"zero"_ | +| 45 | _"forty five"_ | +| 90 | _"ninety"_, _"maximum"_, _"max"_ | ### Light -* _"Alexa, dim the bathroom light."_ -* _"Alexa, set the bedroom light to fifty percent."_ +- _"Alexa, dim the bathroom light."_ +- _"Alexa, set the bedroom light to fifty percent."_ ### Lock -* _"Alexa, lock my front door."_ -* _"Alexa, unlock the dungeon."_ +- _"Alexa, lock my front door."_ +- _"Alexa, unlock the dungeon."_ #### Unlocking @@ -769,27 +776,27 @@ To unlock, Alexa will require a 4 digit voice personal identification number (PI #### Change Channel -* _"Alexa, change the channel to 200 on the Living Room TV."_ -* _"Alexa, change the channel to PBS on the TV."_ -* _"Alexa, next channel on the Living Room TV."_ -* _"Alexa, channel up on the TV."_ -* _"Alexa, channel down on the TV."_ +- _"Alexa, change the channel to 200 on the Living Room TV."_ +- _"Alexa, change the channel to PBS on the TV."_ +- _"Alexa, next channel on the Living Room TV."_ +- _"Alexa, channel up on the TV."_ +- _"Alexa, channel down on the TV."_ #### Speaker Volume -* _"Alexa, set the volume of the speakers to 50."_ -* _"Alexa, turn the volume down on the stereo by 20."_ -* _"Alexa, turn the volume down on Living Room TV."_ -* _"Alexa, mute speakers."_ -* _"Alexa, unmute speakers."_ -* _"Alexa, lower the volume on the stereo."_ -* _"Alexa, volume up 20 on the speakers."_ +- _"Alexa, set the volume of the speakers to 50."_ +- _"Alexa, turn the volume down on the stereo by 20."_ +- _"Alexa, turn the volume down on Living Room TV."_ +- _"Alexa, mute speakers."_ +- _"Alexa, unmute speakers."_ +- _"Alexa, lower the volume on the stereo."_ +- _"Alexa, volume up 20 on the speakers."_ #### Equalizer Mode Supports changing the Media Player `sound_mode` from the preset `sound_mode_list`. -* _"Alexa, set mode to movie on the TV."_ +- _"Alexa, set mode to movie on the TV."_ Alexa only supports the following modes: `movie`, `music`, `night`, `sport`, `tv`. @@ -797,7 +804,7 @@ Alexa only supports the following modes: `movie`, `music`, `night`, `sport`, `tv Supports changing the Media Player `source` from the preset `source_list`. -* _"Alexa, change the input to DVD on the Living Room TV."_ +- _"Alexa, change the input to DVD on the Living Room TV."_ Home Assistant will attempt to translate the the `media_player` `source_list` into a valid `source` name for Alexa. Alexa only supports the following input names: @@ -809,23 +816,23 @@ Requires [Proactive Events](#proactive-events) enabled. #### Seek -* _"Alexa, skip 30 seconds on device."_ -* _"Alexa, go back 10 seconds on device."_ +- _"Alexa, skip 30 seconds on device."_ +- _"Alexa, go back 10 seconds on device."_ ### Scene Activate scenes with scene name, or _"turn on"_ utterance. Home Assistant does not support deactivate or _"turn off"_ for scenes at this time. -* _"Alexa, Party Time."_ -* _"Alexa, turn on Party Time."_ +- _"Alexa, Party Time."_ +- _"Alexa, turn on Party Time."_ ### Script Run script with script name, or _"turn on"_ utterance. Deactivate a running script with _"turn off"_ utterance. -* _"Alexa, Party Time."_ -* _"Alexa, turn on Party Time."_ -* _"Alexa, turn off Party Time."_ +- _"Alexa, Party Time."_ +- _"Alexa, turn on Party Time."_ +- _"Alexa, turn off Party Time."_ ### Sensor @@ -833,24 +840,24 @@ Requires [Proactive Events](#proactive-events) enabled. Only temperature sensors are configured at this time. -* _"Alexa, what's the temperature in the kitchen?"_ -* _"Alexa, what's the upstairs temperature?"_ -* _"Alexa, what's the temperature of my ex-girlfriend's heart?"_ +- _"Alexa, what's the temperature in the kitchen?"_ +- _"Alexa, what's the upstairs temperature?"_ +- _"Alexa, what's the temperature of my ex-girlfriend's heart?"_ ### Switch Support _"turn on"_ and _"turn off"_ utterances. -* _"Alexa, turn on the vacuum."_ -* _"Alexa, turn off the lights."_ +- _"Alexa, turn on the vacuum."_ +- _"Alexa, turn off the lights."_ ### Timer Start, Pause, and Restart Timer entities in Home Assistant. -* _"Alexa, pause the microwave."_ -* _"Alexa, hold the sous vide."_ -* _"Alexa, restart the microwave."_ +- _"Alexa, pause the microwave."_ +- _"Alexa, hold the sous vide."_ +- _"Alexa, restart the microwave."_

To avoid issues with Alexa built in timer functionality. The timer entity can not include the word "timer" in the friendly name. @@ -860,21 +867,22 @@ To avoid issues with Alexa built in timer functionality. The timer entity can no Support _"turn on"_ and _"turn off"_ utterances. Pause and Resume -* _"Alexa, turn on the vacuum."_ -* _"Alexa, pause the vacuum."_ -* _"Alexa, restart the vacuum."_ +- _"Alexa, turn on the vacuum."_ +- _"Alexa, pause the vacuum."_ +- _"Alexa, restart the vacuum."_ ## Alexa Web-Based App The following is a list of regions and the corresponding URL for the web-based Alexa app: - * United States: `https://alexa.amazon.com` - * United Kingdom: `https://alexa.amazon.co.uk` - * Germany: `https://alexa.amazon.de` - * Japan: `https://alexa.amazon.co.jp` - * Canada: `https://alexa.amazon.ca` - * Australia: `https://alexa.amazon.com.au` - * India: `https://alexa.amazon.in` - * Spain: `https://alexa.amazon.es` + +- United States: `https://alexa.amazon.com` +- United Kingdom: `https://alexa.amazon.co.uk` +- Germany: `https://alexa.amazon.de` +- Japan: `https://alexa.amazon.co.jp` +- Canada: `https://alexa.amazon.ca` +- Australia: `https://alexa.amazon.com.au` +- India: `https://alexa.amazon.in` +- Spain: `https://alexa.amazon.es` ## Troubleshooting diff --git a/source/_integrations/cover.markdown b/source/_integrations/cover.markdown index a38a7cf21c1..774ce3a41f5 100644 --- a/source/_integrations/cover.markdown +++ b/source/_integrations/cover.markdown @@ -35,7 +35,7 @@ Available services: `cover.open_cover`, `cover.close_cover`, `cover.stop_cover`, | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all. ### Service `cover.set_cover_position` @@ -43,7 +43,7 @@ Set cover position of one or multiple covers. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all. | `position` | no | Integer between 0 and 100. #### Automation example @@ -66,7 +66,7 @@ Set cover tilt position of one or multiple covers. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of covers. Use `entity_id: all` to target all. | `tilt_position` | no | Integer between 0 and 100. #### Automation example diff --git a/source/_integrations/ecobee.markdown b/source/_integrations/ecobee.markdown index a5daca81752..9f21e05efef 100644 --- a/source/_integrations/ecobee.markdown +++ b/source/_integrations/ecobee.markdown @@ -195,7 +195,7 @@ Resumes the currently active schedule. | Service data attribute | Optional | Description | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------ | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Use `entity_id: all` to target all. | | `resume_all` | no | true or false | ### Service `ecobee.set_fan_min_on_time` @@ -204,5 +204,5 @@ Sets the minimum amount of time that the fan will run per hour. | Service data attribute | Optional | Description | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------ | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Use `entity_id: all` to target all. | | `fan_min_on_time` | no | integer (e.g. 5) | diff --git a/source/_integrations/foscam.markdown b/source/_integrations/foscam.markdown index a85e62b9a61..3805bba44f0 100644 --- a/source/_integrations/foscam.markdown +++ b/source/_integrations/foscam.markdown @@ -64,7 +64,7 @@ If your Foscam camera supports PTZ, you will be able to pan or tilt your camera. | Service data attribute | Description | | -----------------------| ----------- | -| `entity_id` | String or list of strings that point at `entity_id`s of cameras. Else targets all. | +| `entity_id` | String or list of strings that point at `entity_id`s of cameras. Use `entity_id: all` to target all. | | `movement` | Direction of the movement. Allowed values: `up`, `down`, `left`, `right`, `top_left`, `top_right`, `bottom_left`, `bottom_right` | | `travel_time` | (Optional) Travel time in seconds. Allowed values: float from 0 to 1. Default: 0.125 | diff --git a/source/_integrations/konnected.markdown b/source/_integrations/konnected.markdown index 876f2913231..1343c6cecf5 100644 --- a/source/_integrations/konnected.markdown +++ b/source/_integrations/konnected.markdown @@ -30,7 +30,7 @@ Konnected devices communicate with Home Assistant over your local LAN -- there i
-### Configuration +## Configuration A `konnected` section must be present in the `configuration.yaml` file that specifies the Konnected devices on the network and the sensors or actuators attached to them: @@ -69,7 +69,7 @@ devices: type: list keys: id: - description: The MAC address of the NodeMCU WiFi module with colons/punctuation removed, for example `68c63a8bcd53`. You can usually find the mac address in your router's client list. Or, check the home-assistant.log for log messages from automatically discovered devices. + description: The MAC address of the NodeMCU Wi-Fi module with colons/punctuation removed, for example `68c63a8bcd53`. You can usually find the mac address in your router's client list. Or, check the home-assistant.log for log messages from automatically discovered devices. required: true type: string binary_sensors: @@ -146,7 +146,7 @@ devices: repeat: description: Number of times to repeat a momentary pulse. Set to `-1` to make an infinite repeat. This is useful as an alarm or warning when used with a piezo buzzer. required: false - host: + host: type: string required: false description: Optionally specify the Konnected device's IP address or hostname to set up without discovery. @@ -167,12 +167,12 @@ devices: {% endconfiguration%} -#### Configuration Notes +### Configuration Notes - Either **pin** or **zone** is required for each actuator or sensor. Do not use both in the same definition. - Pin `D8` or the `out` zone will only work when activation is set to high (the default). -### Extended Configuration +## Extended Configuration ```yaml # Example configuration.yaml entry @@ -223,10 +223,9 @@ konnected: - pin: 6 name: Kitchen type: dht - ``` -### Unique IDs and the Entity Registry +## Unique IDs and the Entity Registry Beginning in Home Assistant release 0.90, unique IDs are generated for each sensor or switch entity. This enables end users to modify the entity names and entity IDs through the Home Assistant UI on the _Entity Registry_ page (under _Configuration_). @@ -242,60 +241,60 @@ Unique IDs are internally generated as follows: \* Switches are identified by a unique hash including the pin number, `momentary`, `pause`, and `repeat` values. If these values are modified, a new entity will be created and the old entity must be removed manually from the _Entity Registry_. -### Pin Mapping +## Pin Mapping -Konnected runs on an ESP8266 board with the NodeMCU firmware. It is commonly used with the NodeMCU dev kit WiFi module and optionally Konnected's Alarm Panel hardware. The following table shows the pin mapping between the Konnected hardware labeled zones, the NodeMCU labeled pins and the ESP8266 GPIO pins. +Konnected runs on an ESP8266 board with the NodeMCU firmware. It is commonly used with the NodeMCU dev kit Wi-Fi module and optionally Konnected's Alarm Panel hardware. The following table shows the pin mapping between the Konnected hardware labeled zones, the NodeMCU labeled pins and the ESP8266 GPIO pins. -| Konnected Alarm Panel Zone | NodeMCU pin | IO Index | ESP8266 GPIO | -|---|---|---|---| -| 1 | D1 | 1 | GPIO5 | -| 2 | D2 | 2 | GPIO4 | -| 3 | D5 | 5 | GPIO14 | -| 4 | D6 | 6 | GPIO12 | -| 5 | D7 | 7 | GPIO13 | -| 6 | RX | 9 | GPIO3 | -| ALARM or OUT | D8 | 8 | GPIO15 | +| Konnected Alarm Panel Zone | NodeMCU pin | IO Index | ESP8266 GPIO | +| -------------------------- | ----------- | -------- | ------------ | +| 1 | D1 | 1 | GPIO5 | +| 2 | D2 | 2 | GPIO4 | +| 3 | D5 | 5 | GPIO14 | +| 4 | D6 | 6 | GPIO12 | +| 5 | D7 | 7 | GPIO13 | +| 6 | RX | 9 | GPIO3 | +| ALARM or OUT | D8 | 8 | GPIO15 | -### Revision History +## Revision History -#### 0.91 +### 0.91 - Improved Unique ID generation for Konnected switches -#### 0.90 +### 0.90 - Added support for `dht` and `ds18b20` temperature sensors - Added Unique IDs -#### 0.80 +### 0.80 - Added ability to specify `host` and `port` to set up devices without relying on discovery. -- Added `discovery` and `blink` config options to enable/disable these features. +- Added `discovery` and `blink` configuration options to enable/disable these features. -#### 0.79 +### 0.79 - Added `inverse` configuration option for binary sensors. -#### 0.77 +### 0.77 - Added support for momentary and beep/blink switches. [[#15973](https://github.com/home-assistant/home-assistant/pull/15973)] - Decouple entity initialization from discovery, enabling devices to recover faster after a Home Assistant reboot. [[#16146](https://github.com/home-assistant/home-assistant/pull/16146)] - **Breaking change:** Device `id` in `configuration.yaml` must now be the full 12-character device MAC address. Previously, omitting the first 6 characters was allowed. -#### 0.72 +### 0.72 - Adds `api_host` configuration option [[#14896](https://github.com/home-assistant/home-assistant/pull/14896)] -#### 0.70 +### 0.70 - Initial release -### Binary Sensor +## Binary Sensor -The `konnected` binary sensor allows you to monitor wired door sensors, window sensors, motion sensors, smoke detectors, CO detectors, glass-break sensors, water leak sensors or any other simple wired open/close circuit attached to a NodeMCU ESP8266 WiFi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security). +The `konnected` binary sensor allows you to monitor wired door sensors, window sensors, motion sensors, smoke detectors, CO detectors, glass-break sensors, water leak sensors or any other simple wired open/close circuit attached to a NodeMCU ESP8266 Wi-Fi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security). This integration supports all of the built-in device classes of the generic [Binary Sensor](/integrations/binary_sensor/) component. -### Switch +## Switch -The `konnected` switch platform allows you to actuate an alarm system siren, strobe light, buzzer or any other wired device using a [Konnected Alarm Panel board](https://konnected.io) or relay module and a NodeMCU ESP8266 WiFi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security). +The `konnected` switch platform allows you to actuate an alarm system siren, strobe light, buzzer or any other wired device using a [Konnected Alarm Panel board](https://konnected.io) or relay module and a NodeMCU ESP8266 Wi-Fi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security). diff --git a/source/_integrations/life360.markdown b/source/_integrations/life360.markdown index 55bdcee2609..3f9756e6a21 100644 --- a/source/_integrations/life360.markdown +++ b/source/_integrations/life360.markdown @@ -19,7 +19,7 @@ You must first [create a Life360 account](https://www.life360.com/websignup). Then in the Home Assistant user interface (UI), click on Configuration in the left pane, then on Integrations and then on the yellow circle in the lower-right corner to "Set up a new integration." Scroll through the list and click on Life360. Enter your Life360 username and password and click SUBMIT. You can add as many Life360 accounts as you like. -If you would like to set any advanced options, see the following section. You may want to do this before entering your Life360 account information in the UI, or you can change it at any time. Any of the advanced options you want to set from the section below will need to be set manually in your configuration.yaml file. They are not able to be set from the UI. You can also enter your account information in the configuration file (in addition to, or instead of, the UI) if you prefer. +If you would like to set any advanced options, see the following section. You may want to do this before entering your Life360 account information in the UI, or you can change it at any time. Any of the advanced options you want to set from the section below will need to be set manually in your `configuration.yaml` file. They are not able to be set from the UI. You can also enter your account information in the configuration file (in addition to, or instead of, the UI) if you prefer. After configuring, it is expected for the Life360 integration page to show "This integration has no devices". You should see a new Life360 device tracker entity showing up on the States page. If it does not: @@ -109,18 +109,18 @@ warning_threshold: ## Additional attributes -Attribute | Description --|- -address | Address of the current location, or `none`. -at_loc_since | Date and time when first at current location (in UTC.) -battery_charging | Device is charging (`true`/`false`.) -driving | Device movement indicates driving (`true`/`false`.) -last_seen | Date and time when Life360 last updated device location (in UTC.) -moving | Device is moving (`true`/`false`.) -place | Name of Life360 Place where the device is located, or `none` if not located within one. -raw_speed | "Raw" speed value provided by Life360 server. (Units unknown.) -speed | Estimated speed of device (in MPH or KPH depending on Home Assistant's unit system configuration.) -wifi_on | Device WiFi is turned on (`true`/`false`.) +| Attribute | Description | +| ---------------- | -------------------------------------------------------------------------------------------------- | +| address | Address of the current location, or `none`. | +| at_loc_since | Date and time when first at current location (in UTC.) | +| battery_charging | Device is charging (`true`/`false`.) | +| driving | Device movement indicates driving (`true`/`false`.) | +| last_seen | Date and time when Life360 last updated device location (in UTC.) | +| moving | Device is moving (`true`/`false`.) | +| place | Name of Life360 Place where the device is located, or `none` if not located within one. | +| raw_speed | "Raw" speed value provided by Life360 server. (Units unknown.) | +| speed | Estimated speed of device (in MPH or KPH depending on Home Assistant's unit system configuration.) | +| wifi_on | Device Wi-Fi is turned on (`true`/`false`.) | ## Filtering @@ -142,7 +142,7 @@ Normally Home Assistant device trackers are "Home" when they enter `zone.home`. ## Home Assistant Zones & Life360 Places -See [Zone documentation](/integrations/zone/#home-zone) for details about how HA zones are defined. If you'd like to create HA zones from Life360 Places (e.g., to make HA's `zone.home` be identical to Life360's "Home Place"), make sure `logger` is set to `debug`. Then when HA starts the details of all the Places defined in the included Circles will be written to `home-assistant.log` in a format that can be copied into your configuration under `zone:`. E.g., you would see something like this: +See [Zone documentation](/integrations/zone/#home-zone) for details about how Home Assistant zones are defined. If you'd like to create Home Assistant zones from Life360 Places (e.g., to make Home Assistant's `zone.home` be identical to Life360's "Home Place"), make sure `logger` is set to `debug`. Then when Home Assistant starts the details of all the Places defined in the included Circles will be written to `home-assistant.log` in a format that can be copied into your configuration under `zone:`. E.g., you would see something like this: ```text 2019-05-31 12:16:58 DEBUG (SyncWorker_3) [homeassistant.components.life360.device_tracker] My Family Circle: will be included, id=xxxxx @@ -164,6 +164,7 @@ Therefore, an optional filtering mechanism has been implemented to prevent incon ### Typical configuration {% raw %} + ```yaml life360: # MPH, assuming imperial units. @@ -182,11 +183,13 @@ life360: warning_threshold: 2 error_threshold: 3 ``` + {% endraw %} ### Circle and Member Filtering Example {% raw %} + ```yaml life360: # Only track Members that are in these Circles. @@ -196,22 +199,26 @@ life360: members: exclude: John Doe ``` + {% endraw %} ### Entering accounts in configuration {% raw %} + ```yaml life360: accounts: - username: LIFE360_USERNAME password: LIFE360_PASSWORD ``` + {% endraw %} ### Example overdue update automations {% raw %} + ```yaml automation: - alias: Life360 Overdue Update @@ -242,6 +249,7 @@ automation: trigger.event.data.entity_id }} restored after {{ trigger.event.data.wait }}. ``` + {% endraw %} ## Disclaimer diff --git a/source/_integrations/lifx.markdown b/source/_integrations/lifx.markdown index 406fab6e5e5..ae434aba53c 100644 --- a/source/_integrations/lifx.markdown +++ b/source/_integrations/lifx.markdown @@ -27,7 +27,7 @@ Change the light to a new state. | Service data attribute | Description | | ---------------------- | ----------- | -| `entity_id` | String or list of strings that point at `entity_id`s of lights. Else targets all. +| `entity_id` | String or list of strings that point at `entity_id`s of lights. Use `entity_id: all` to target all. | `transition` | Duration (in seconds) for the light to fade to the new state. | `zones` | List of integers for the zone numbers to affect (each LIFX Z strip has 8 zones, starting at 0). | `infrared` | Automatic infrared level (0..255) when light brightness is low (for compatible bulbs). @@ -72,7 +72,7 @@ Run a flash effect by changing to a color and then back. | Service data attribute | Description | | ---------------------- | ----------- | -| `entity_id` | String or list of strings that point at `entity_id`s of lights. Else targets all. +| `entity_id` | String or list of strings that point at `entity_id`s of lights. Use `entity_id: all` to target all. | `color_name` | A color name such as `red` or `green`. | `rgb_color` | A list containing three integers representing the RGB color you want the light to be. | `brightness` | Integer between 0 and 255 for how bright the color should be. @@ -87,7 +87,7 @@ Run an effect with colors looping around the color wheel. All participating ligh | Service data attribute | Description | | ---------------------- | ----------- | -| `entity_id` | String or list of strings that point at `entity_id`s of lights. Else targets all. +| `entity_id` | String or list of strings that point at `entity_id`s of lights. Use `entity_id: all` to target all. | `brightness` | Number between 0 and 255 indicating brightness of the effect. Leave this out to maintain the current brightness of each participating light. | `period` | Duration (in seconds) between starting a new color change. | `transition` | Duration (in seconds) where lights are actively changing color. @@ -101,7 +101,7 @@ Run an effect that does nothing, thereby stopping any other effect that might be | Service data attribute | Description | | ---------------------- | ----------- | -| `entity_id` | String or list of strings that point at `entity_id`s of lights. Else targets all. +| `entity_id` | String or list of strings that point at `entity_id`s of lights. Use `entity_id: all` to target all. ## Advanced configuration diff --git a/source/_integrations/lock.markdown b/source/_integrations/lock.markdown index 10aac50e55c..3e963d1cac2 100644 --- a/source/_integrations/lock.markdown +++ b/source/_integrations/lock.markdown @@ -61,4 +61,4 @@ Go to the **Developer Tools**, then to **Call Service** in the frontend, and cho | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | Only act on specific lock. Else targets all. +| `entity_id` | yes | Only act on specific lock. Use `entity_id: all` to target all. diff --git a/source/_integrations/nuheat.markdown b/source/_integrations/nuheat.markdown index 1264d9d500d..5331e6676a3 100644 --- a/source/_integrations/nuheat.markdown +++ b/source/_integrations/nuheat.markdown @@ -144,7 +144,7 @@ Puts the thermostat into an indefinite hold at the given temperature. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Use `entity_id: all` to target all. | `temperature` | no | Desired target temperature (when not in auto mode) Only the target temperatures relevant for the current operation mode need to @@ -156,7 +156,7 @@ Sets the thermostat's preset mode. Without a preset mode set it run the thermost | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Use `entity_id: all` to target all. | `hold_mode` | no | New value of hold mode. ### Service `nuheat.resume_program` @@ -165,4 +165,4 @@ Resumes the currently active schedule. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Use `entity_id: all` to target all. diff --git a/source/_integrations/onvif.markdown b/source/_integrations/onvif.markdown index 337684ca5aa..da4d8b0bead 100644 --- a/source/_integrations/onvif.markdown +++ b/source/_integrations/onvif.markdown @@ -65,7 +65,7 @@ If your ONVIF camera supports PTZ, you will be able to pan, tilt or zoom your ca | Service data attribute | Description | | -----------------------| ----------- | -| `entity_id` | String or list of strings that point at `entity_id`s of cameras. Else targets all. +| `entity_id` | String or list of strings that point at `entity_id`s of cameras. Use `entity_id: all` to target all. | `tilt` | Tilt direction. Allowed values: `UP`, `DOWN`, `NONE` | `pan` | Pan direction. Allowed values: `RIGHT`, `LEFT`, `NONE` | `zoom` | Zoom. Allowed values: `ZOOM_IN`, `ZOOM_OUT`, `NONE` diff --git a/source/_integrations/proxmoxve.markdown b/source/_integrations/proxmoxve.markdown index ea40c027202..a4d75364037 100644 --- a/source/_integrations/proxmoxve.markdown +++ b/source/_integrations/proxmoxve.markdown @@ -120,7 +120,7 @@ Before creating the user, we need to create a permissions role for the user. ### Create Home Assistant User -Creating a dedicated user for home assistant limited to only the role just created is the most secure method. These instructions use the `pve` realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections. If you use the `pve` realm, just be sure to add `realm: pve` to your config. +Creating a dedicated user for Home Assistant, limited to only the role just created is the most secure method. These instructions use the `pve` realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections. If you use the `pve` realm, just be sure to add `realm: pve` to your config. * Click `Datacenter` * Open `Permissions` and click `Users` diff --git a/source/_integrations/time_date.markdown b/source/_integrations/time_date.markdown index b4cfe86c2ad..a446e4ce245 100644 --- a/source/_integrations/time_date.markdown +++ b/source/_integrations/time_date.markdown @@ -12,7 +12,7 @@ ha_codeowners: --- The time and date (`time_date`) sensor platform adds one or more sensors to your Home Assistant state machine. -To have these sensors available in your installation, add the following to your `configuration.yaml` file (each option creates a separate sensor that contains appropriate data): +To have these sensors available in your installation, add the following to your `configuration.yaml` file (each option creates a separate sensor that contains appropriate data, e.g. `sensor.date` for the `date` option): ```yaml # Example configuration.yaml entry diff --git a/source/_integrations/vacuum.markdown b/source/_integrations/vacuum.markdown index 7c669b99270..891f0995f1b 100644 --- a/source/_integrations/vacuum.markdown +++ b/source/_integrations/vacuum.markdown @@ -30,7 +30,7 @@ Start a new cleaning task. For the Xiaomi Vacuum and Neato use `vacuum.start` in | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.turn_off` @@ -38,7 +38,7 @@ Stop the current cleaning task and return to the dock. For the Xiaomi Vacuum and | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.start_pause` @@ -46,7 +46,7 @@ Start, pause or resume a cleaning task. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.start` @@ -54,7 +54,7 @@ Start or resume a cleaning task. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.pause` @@ -62,7 +62,7 @@ Pause a cleaning task. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.stop` @@ -70,7 +70,7 @@ Stop the current activity of the vacuum. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.return_to_base` @@ -78,7 +78,7 @@ Tell the vacuum to return home. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.locate` @@ -86,7 +86,7 @@ Locate the vacuum cleaner robot. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.clean_spot` @@ -94,7 +94,7 @@ Tell the vacuum cleaner to do a spot clean-up. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | #### Service `vacuum.set_fan_speed` @@ -102,7 +102,7 @@ Set the fan speed of the vacuum. The `fanspeed` can be a label, as `balanced` or | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | | `fan_speed` | no | Platform dependent vacuum cleaner fan speed, with speed steps, like 'medium', or by percentage, between 0 and 100. | #### Service `vacuum.send_command` @@ -111,6 +111,6 @@ Send a platform-specific command to the vacuum cleaner. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific vacuum. Else targets all. | +| `entity_id` | yes | Only act on specific vacuum. Use `entity_id: all` to target all. | | `command` | no | Command to execute. | | `params` | yes | Parameters for the command. | diff --git a/source/_integrations/water_heater.markdown b/source/_integrations/water_heater.markdown index aa82a25ffbd..d748f687871 100644 --- a/source/_integrations/water_heater.markdown +++ b/source/_integrations/water_heater.markdown @@ -32,7 +32,7 @@ Sets target temperature of water heater device. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of water heater devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of water heater devices to control. Use `entity_id: all` to target all. | `temperature` | no | New target temperature for water heater | `operation_mode` | yes | Operation mode to set the temperature to. This defaults to current_operation mode if not set, or set incorrectly. @@ -57,7 +57,7 @@ Set operation mode for water heater device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of water heater devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of water heater devices to control. Use `entity_id: all` to target all. | `operation_mode` | no | New value of operation mode #### Automation example @@ -80,7 +80,7 @@ Turn away mode on or off for water heater device | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | yes | String or list of strings that point at `entity_id`'s of water heater devices to control. Else targets all. +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of water heater devices to control. Use `entity_id: all` to target all. | `away_mode` | no | New value of away mode. 'on'/'off' or True/False #### Automation example diff --git a/source/_integrations/wink.markdown b/source/_integrations/wink.markdown index 06caf43330f..f30bdf59380 100644 --- a/source/_integrations/wink.markdown +++ b/source/_integrations/wink.markdown @@ -52,7 +52,7 @@ Wink requests three pieces of information from the user when they sign up for a 2. `Website:` The external address of your Home Assistant instance. If not externally accessible you can use your email address. 3. `Redirect URI:` This should be `http://192.168.1.5:8123/auth/wink/callback` replacing the IP with the internal IP of your Home Assistant box. -No settings are required in the `configuration.yaml` other than `wink:`. +No settings are required in the `configuration.yaml` other than `wink:`. After adding `wink:` to your `configuration.yaml` and restarting Home Assistant you will see a persistent notification on the frontend with a `CONFIGURE` button that will guide you through the setup via the frontend configurator. @@ -136,19 +136,19 @@ You can use the service wink/add_new_devices to pull any newly paired Wink devic You can use the service wink/delete_wink_device to remove/unpair a device from Wink. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | String that points at the `entity_id` of device to delete. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ---------------------------------------------------------- | +| `entity_id` | no | String that points at the `entity_id` of device to delete. | ## Service `pair_new_device` You can use the service wink/pair_new_device to pair a new device to your Wink hub/relay -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `hub_name` | no | The name of the hub to pair a new device to. -| `pairing_mode` | no | One of the following [zigbee, zwave, zwave_exclusion, zwave_network_rediscovery, lutron, bluetooth, kidde] -| `kidde_radio_code` | conditional | A string of 8 1s and 0s one for each dip switch on the kidde device left --> right = 1 --> 8 (Required if pairing_mode = kidde) +| Service data attribute | Optional | Description | +| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `hub_name` | no | The name of the hub to pair a new device to. | +| `pairing_mode` | no | One of the following [zigbee, zwave, zwave_exclusion, zwave_network_rediscovery, lutron, bluetooth, kidde] | +| `kidde_radio_code` | conditional | A string of 8 1s and 0s one for each dip switch on the kidde device left --> right = 1 --> 8 (Required if pairing_mode = kidde) |
Calling service wink/pull_newly_added_wink_devices after a device is paired will add that new device to Home Assistant. The device will also show up on the next restart of Home Assistant. @@ -158,10 +158,10 @@ Calling service wink/pull_newly_added_wink_devices after a device is paired will You can use the service wink/rename_wink_device to change the name of a device. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | String that points at the `entity_id` of device to rename. -| `name` | no | The name to change it to. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ---------------------------------------------------------- | +| `entity_id` | no | String that points at the `entity_id` of device to rename. | +| `name` | no | The name to change it to. |
Home Assistant entity_ids for Wink devices are based on the Wink device's name. Calling this service will not change the entity_id of the device until Home Assistant is restarted. @@ -181,10 +181,10 @@ The Wink hub, by default, can only be accessed via the cloud. This means it requ You can use the service wink/set_siren_auto_shutoff to set how long the siren will sound before shutting off. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `auto_shutoff` | no | Int. One of [None, -1, 30, 60, 120] (None and -1 are forever. Use None for gocontrol, and -1 for Dome) -| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------ | +| `auto_shutoff` | no | Int. One of [None, -1, 30, 60, 120] (None and -1 are forever. Use None for gocontrol, and -1 for Dome) | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren. | Example: @@ -205,10 +205,10 @@ The following services only work with the Dome siren/chime. You can use the service wink/set_chime_volume to set the volume for the chime on your Dome siren/chime. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `volume` | no | String. One of ["low", "medium", "high"] -| `entity_id` | yes | String or list of strings that point at `entity_id`s of the siren/chime. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ------------------------------------------------------------------------ | +| `volume` | no | String. One of ["low", "medium", "high"] | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of the siren/chime. | Example: @@ -225,10 +225,10 @@ script: You can use the service wink/set_chime_volume to set the volume for the chime on your Dome siren/chime. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `volume` | no | String. One of ["low", "medium", "high"] -| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------------- | +| `volume` | no | String. One of ["low", "medium", "high"] | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. | Example: @@ -245,10 +245,10 @@ script: You can use the service wink/enable_chime to set the tone and enable the chime on your Dome siren/chime. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep", "inactive"] -| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep", "inactive"] | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. | Example: @@ -265,10 +265,10 @@ script: You can use the service wink/set_siren_tone to set the tone on your Dome siren. This tone will be used the next time the siren is executed. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep"] -| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep"] | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. | Example: @@ -285,10 +285,10 @@ script: You can use the service wink/set_siren_strobe_enabled to enable or disable the strobe when the siren is executed. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `enabled` | no | Boolean. True or False. -| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------------- | +| `enabled` | no | Boolean. True or False. | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. | Example: @@ -305,10 +305,10 @@ script: You can use the service wink/set_chime_strobe_enabled to enable or disable the strobe when the chime is executed. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `enabled` | no | Boolean. True or False. -| `entity_id` | yes | String or list of strings that point at `entity_id`s of chime/chime. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------------- | +| `enabled` | no | Boolean. True or False. | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of chime/chime. | Example: @@ -325,11 +325,11 @@ script: You can use the service wink/set_nimbus_dial_state to update an individual dial's value/position and its labels -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime. -| `value` | no | A number, should be between the dials min and max value (See set_nimbus_dial_configuration below) -| `labels` | yes | A list of strings the first being the value set on the dial's face and the second being the value on the dial face when the Nimbus is pressed +| Service data attribute | Optional | Description | +| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime. | +| `value` | no | A number, should be between the dials min and max value (See set_nimbus_dial_configuration below) | +| `labels` | yes | A list of strings the first being the value set on the dial's face and the second being the value on the dial face when the Nimbus is pressed | Example: @@ -350,16 +350,16 @@ script: You can use the service wink/set_nimbus_dial_configuration to update an individual dial's configuration. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime. -| `rotation` | yes | One of "cw" or "ccw" the direction the dial hand should rotate. -| `ticks` | yes | A positive number, the number of times the hand should move. -| `scale` | yes | One of "linear" or "log" How the dial should move in response to higher values. -| `min_value` | yes | A number, the minimum value that the dial can have. -| `max_value` | yes | A number, the maximum value that the dial can have. -| `min_position` | yes | A number generally [0-360], the minimum position for the dial's hand. -| `max_value` | yes | A number generally [0-360], the maximum position for the dial's hand. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ------------------------------------------------------------------------------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime. | +| `rotation` | yes | One of "cw" or "ccw" the direction the dial hand should rotate. | +| `ticks` | yes | A positive number, the number of times the hand should move. | +| `scale` | yes | One of "linear" or "log" How the dial should move in response to higher values. | +| `min_value` | yes | A number, the minimum value that the dial can have. | +| `max_value` | yes | A number, the maximum value that the dial can have. | +| `min_position` | yes | A number generally [0-360], the minimum position for the dial's hand. | +| `max_value` | yes | A number generally [0-360], the maximum position for the dial's hand. | Example: @@ -400,7 +400,7 @@ The requirement is that you have setup [Wink](/integrations/wink/) from above. - Motion sensors - Ring Door bells (No hub required) - Liquid presence sensors -- Z-wave lock key codes +- Z-Wave lock key codes - Lutron connected bulb remote buttons - Wink Relay buttons and presence detection - Wink spotter loudness and vibration (No Wink hub required) @@ -474,7 +474,7 @@ The requirement is that you have setup [Wink](/integrations/wink/) from above. ### Supported light devices -- Z-wave switches with dimming +- Z-Wave switches with dimming - Hue - Lightify - GE link @@ -495,7 +495,7 @@ The requirement is that you have setup [Wink](/integrations/wink/) from above. - Kwikset - Schlage - August (No Wink hub required) (August Connect required) -- Generic Z-wave +- Generic Z-Wave
The following services have only been confirmed on Schlage locks. @@ -505,10 +505,10 @@ The following services have only been confirmed on Schlage locks. You can use the service wink/set_lock_alarm_mode to set the alarm mode of your lock. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `mode` | no | String one of tamper, activity, or forced_entry -| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------- | +| `mode` | no | String one of tamper, activity, or forced_entry | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | Example: @@ -525,10 +525,10 @@ script: You can use the service wink/set_lock_alarm_sensitivity to set the alarm sensitivity of your lock. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `sensitivity` | no | String one of low, medium_low, medium, medium_high, high. -| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------- | +| `sensitivity` | no | String one of low, medium_low, medium, medium_high, high. | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | Example: @@ -545,10 +545,10 @@ script: You can use the service wink/set_lock_alarm_state to set the alarm state of your lock. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `enabled` | no | Boolean enabled or disabled, true or false -| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------- | +| `enabled` | no | Boolean enabled or disabled, true or false | | | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | | | Example: @@ -565,10 +565,10 @@ script: You can use the service wink/set_lock_beeper_state to set the beeper state of your lock. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `enabled` | no | Boolean enabled or disabled, true or false -| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------- | +| `enabled` | no | Boolean enabled or disabled, true or false | | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | | Example: @@ -585,10 +585,10 @@ script: You can use the service wink/set_lock_vacation_mode to set the vacation mode of your lock. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `enabled` | no | Boolean enabled or disabled, true or false -| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------- | +| `enabled` | no | Boolean enabled or disabled, true or false | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | Example: @@ -605,11 +605,11 @@ script: You can use the service wink/add_new_lock_key_code to add a new user code to your Wink lock. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `entity_id` | no | String or list of strings that point at `entity_id`s of locks. -| `name` | no | the name of the new key code -| `code` | no | The new code. Must match length of existing codes. +| Service data attribute | Optional | Description | +| ---------------------- | -------- | -------------------------------------------------------------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of locks. | +| `name` | no | the name of the new key code | +| `code` | no | The new code. Must match length of existing codes. |
Calling service wink/pull_newly_added_wink_devices will add the new key code to Home Assistant. The device will also show up on the next restart of Home Assistant. @@ -648,7 +648,7 @@ The requirement is that you have set up [Wink](/integrations/wink/) from above. ## Supported switch devices - Wink Pivot power genius (No Wink hub required) -- non-dimming Z-wave in-wall switches (dimming switches show up as lights) +- non-dimming Z-Wave in-wall switches (dimming switches show up as lights) - Wink Relay load controlling switches - Rachio sprinkler controller (No Wink hub required) - iHome smart plug (No Wink hub required) diff --git a/source/_integrations/yeelight.markdown b/source/_integrations/yeelight.markdown index 82c30b65fa7..03d370c5ac3 100644 --- a/source/_integrations/yeelight.markdown +++ b/source/_integrations/yeelight.markdown @@ -11,16 +11,16 @@ ha_codeowners: - '@zewelor' --- -The `yeelight` integration allows you to control your Yeelight Wifi bulbs with Home Assistant. There are two possible methods for configuration of the Yeelight: Manual or Automatic. +The `yeelight` integration allows you to control your Yeelight Wi-Fi bulbs with Home Assistant. There are two possible methods for configuration of the Yeelight: Manual or Automatic. There is currently support for the following device types within Home Assistant: -- **Light** - The yeelight platform for supporting lights. -- **Sensor** - The yeelight platform for supporting sensors. Currently only nightlight mode sensor, for ceiling lights. +- **Light** - The Yeelight platform for supporting lights. +- **Sensor** - The Yeelight platform for supporting sensors. Currently only nightlight mode sensor, for ceiling lights. ## Example configuration (Automatic) -After the lights are connected to the WiFi network and have been detected in Home Assistant, the discovered names will be shown in the `Light` section of the `Overview` view. Add the following lines to your `customize.yaml` file: +After the lights are connected to the Wi-Fi network and have been detected in Home Assistant, the discovered names will be shown in the `Light` section of the `Overview` view. Add the following lines to your `customize.yaml` file: ```yaml # Example customize.yaml entry @@ -139,10 +139,10 @@ This integration is tested to work with the following models. If you have a diff | `color2` | YLDP06YL | LED Bulb (Color) - 2nd generation | | `strip1` | YLDD01YL | Lightstrip (Color) | | `strip1` | YLDD02YL | Lightstrip (Color) | -| ? | YLDD04YL | Lightstrip (Color) -| `bslamp1` | MJCTD01YL | Xiaomi Mijia Bedside Lamp - WIFI Version! | +| ? | YLDD04YL | Lightstrip (Color) | +| `bslamp1` | MJCTD01YL | Xiaomi Mijia Bedside Lamp - Wi-Fi Version! | | `bslamp1` | MJCTD02YL | Xiaomi Mijia Bedside Lamp II | -| `RGBW` | MJDP02YL | Mi Led smart Lamp - white and color WIFI Version | +| `RGBW` | MJDP02YL | Mi Led smart Lamp - white and color Wi-Fi Version| | `lamp1` | MJTD01YL | Xiaomi Mijia Smart LED Desk Lamp (autodiscovery isn't possible because the device doesn't support mDNS due to the small amount of RAM) | | `ceiling1` | YLXD01YL | Yeelight Ceiling Light | | `ceiling2` | YLXD03YL | Yeelight Ceiling Light - Youth Version | diff --git a/source/_lovelace/conditional.markdown b/source/_lovelace/conditional.markdown index e26ee05ca74..ed3b6e9fff8 100644 --- a/source/_lovelace/conditional.markdown +++ b/source/_lovelace/conditional.markdown @@ -18,7 +18,7 @@ conditions: keys: entity: required: true - description: HA entity ID. + description: Home Assistant entity ID. type: string state: required: false @@ -38,7 +38,7 @@ card: Note: Conditions with more than one entity are treated as an 'and' condition. This means that for the card to show, *all* entities must meet the state requirements set. -### Examples +## Examples ```yaml type: conditional diff --git a/source/_lovelace/entities.markdown b/source/_lovelace/entities.markdown index aba855d4f98..bb937ba384b 100644 --- a/source/_lovelace/entities.markdown +++ b/source/_lovelace/entities.markdown @@ -306,13 +306,13 @@ type: type: string url: required: true - description: "Website URL (or internal URL e.g. `/hassio/dashboard` or `/panel_custom_name`)" + description: "Website URL (or internal URL e.g., `/hassio/dashboard` or `/panel_custom_name`)" type: string name: required: false description: Link label type: string - default: url path + default: URL path icon: required: false description: "Icon to display (e.g., `mdi:home`)" diff --git a/source/_lovelace/entity-button.markdown b/source/_lovelace/entity-button.markdown index 812c77eb185..98c27862259 100644 --- a/source/_lovelace/entity-button.markdown +++ b/source/_lovelace/entity-button.markdown @@ -47,7 +47,7 @@ show_icon: default: "true" icon_height: required: false - description: Set the height for the icon. This is in pixels which is handled by the config ui. (Advanced users can use other CSS values if they like) + description: Set the height for the icon. This is in pixels which is handled by the configuration UI. (Advanced users can use other CSS values if they like) type: string default: auto tap_action: diff --git a/source/_lovelace/history-graph.markdown b/source/_lovelace/history-graph.markdown index 29d155e143d..0ab31ec0ddf 100644 --- a/source/_lovelace/history-graph.markdown +++ b/source/_lovelace/history-graph.markdown @@ -4,7 +4,7 @@ sidebar_label: History Graph description: "History graph is a basic card, allowing you to display a graph for each of the entities in the list specified as config." --- -History graph is a basic card, allowing you to display a graph for each of the entities in the list specified as config. +History graph is a basic card, allowing you to display a graph for each of the entities in the list specified configuration.

Screenshot of the history graph card for entities without a unit_of_measurement diff --git a/source/_lovelace/markdown.markdown b/source/_lovelace/markdown.markdown index 87a6e06d5a7..fd34e2dd64d 100644 --- a/source/_lovelace/markdown.markdown +++ b/source/_lovelace/markdown.markdown @@ -7,7 +7,6 @@ description: "Markdown card is used to render markdown" Markdown card is used to render [Markdown](https://commonmark.org/help/). The renderer uses [Marked.js](https://marked.js.org), which supports [several specifications of Markdown](https://marked.js.org/#/README.md#specifications), including CommonMark, GitHub Flavored Markdown (GFM) and `markdown.pl`. -

Screenshot of the markdown card @@ -32,7 +31,7 @@ card_size: required: false type: integer default: none - description: The algorithm for placing cards aesthetically in lovelace may have problems with the markdown card if it contains templates. You can use this value to help it estimate the height of the card in units of 50 pixels (approximately 3 lines of text in default size). (e.g., `4`) + description: The algorithm for placing cards aesthetically in Lovelace may have problems with the markdown card if it contains templates. You can use this value to help it estimate the height of the card in units of 50 pixels (approximately 3 lines of text in default size). (e.g., `4`) entity_id: required: false type: [string, list] @@ -58,8 +57,10 @@ content: > A special template variable - `config` is set up for the `content` of the card. It contains the configuration of the card. -E.g. +For example: + {% raw %} + ```yaml type: entity-filter entities: @@ -78,4 +79,5 @@ card: And the door is {% if is_state('binary_sensor.door', 'on') %} open {% else %} closed {% endif %}. ``` + {% endraw %} diff --git a/source/_lovelace/picture-elements.markdown b/source/_lovelace/picture-elements.markdown index 59920f2a60a..98196750fa0 100644 --- a/source/_lovelace/picture-elements.markdown +++ b/source/_lovelace/picture-elements.markdown @@ -765,7 +765,7 @@ conditions: keys: entity: required: true - description: HA entity ID. + description: Home Assistant entity ID. type: string state: required: false diff --git a/source/_posts/2020-01-29-changing-the-home-assistant-brand.markdown b/source/_posts/2020-01-29-changing-the-home-assistant-brand.markdown new file mode 100644 index 00000000000..f3060b43057 --- /dev/null +++ b/source/_posts/2020-01-29-changing-the-home-assistant-brand.markdown @@ -0,0 +1,45 @@ +--- +title: "Changing the Home Assistant Brand" +description: "Re-branding Home Assistant to make naming things easier!" +date: 2020-01-29 00:00:00 +date_formatted: "January 29, 2020" +author: Paulus Schoutsen +author_twitter: balloob +categories: Announcements +og_image: /images/blog/2020-01-29-changing-the-home-assistant-brand/social.png +--- + +Over the last few years, we have accumulated a wide range of projects under our +umbrella. We started out as a Python application (called Home Assistant) and +later added an operating system (HassOS) and management system (Hass.io Supervisor) +to it, to allow users to easily manage their homes, but also to provide a +system that is easy to keep up to date. + +These different projects all come together in Hass.io. A system that is secure, +easy to keep up to date and runs the most powerful home automation platform in +the world. But having Hass.io and Home Assistant has been confusing for a lot of +people, especially for newcomers to our great community. + +The next step in making Home Assistant simpler is by making our naming simpler. +It’s our goal to make private home automation accessible to everyone. +And as part of that, people need to know how to refer to it. + +Home Assistant is a home automation operating system for your home. +And to make this message clear, we’re renaming Hass.io to Home Assistant, +and Home Assistant to Home Assistant Core. + +**Note:** this is only about renaming projects and does not impact any +functionality of any of the projects. + +If you run Home Assistant today in a Docker container or run it inside a Python +virtual environment, you are running “Home Assistant Core”. +Home Assistant Core will forever remain a standalone application like it is today. +We promise. + +This name change is a huge thing! Not just a big thing we all need to get used +to, but even bigger for everything that needs to be renamed! It definitely +takes a couple of weeks to get the main parts re-branded. + +So bear with us while we do so. + +Paulus diff --git a/source/_redirects b/source/_redirects index d285413a4f3..964c4ae1cb1 100644 --- a/source/_redirects +++ b/source/_redirects @@ -2060,3 +2060,23 @@ /docs/ecosystem/ios/notifications/requesting_location_updates https://companion.home-assistant.io/notifications/location /docs/ecosystem/ios/notifications/sounds https://companion.home-assistant.io/notifications/sounds /ecosystem/ios/notifications https://companion.home-assistant.io/en/getting_started/migration#5---known-issues + +# Add-ons +/addons/cec_scan https://github.com/home-assistant/hassio-addons/blob/master/cec_scan/README.md +/addons/check_config https://github.com/home-assistant/hassio-addons/blob/master/check_config/README.md +/addons/configurator https://github.com/home-assistant/hassio-addons/blob/master/configurator/README.md +/addons/dhcp_server https://github.com/home-assistant/hassio-addons/blob/master/dhcp_server/README.md +/addons/dnsmasq https://github.com/home-assistant/hassio-addons/blob/master/dnsmasq/README.md +/addons/duckdns https://github.com/home-assistant/hassio-addons/blob/master/duckdns/README.md +/addons/git_pull https://github.com/home-assistant/hassio-addons/blob/master/git_pull/README.md +/addons/google_assistant https://github.com/home-assistant/hassio-addons/blob/master/google_assistant/README.md +/addons/homematic https://github.com/home-assistant/hassio-addons/blob/master/homematic/README.md +/addons/lets_encrypt https://github.com/home-assistant/hassio-addons/blob/master/letsencrypt/README.md +/addons/mariadb https://github.com/home-assistant/hassio-addons/blob/master/mariadb/README.md +/addons/mosquitto https://github.com/home-assistant/hassio-addons/blob/master/mosquitto/README.md +/addons/nginx_proxy https://github.com/home-assistant/hassio-addons/blob/master/nginx_proxy/README.md +/addons/rpc_shutdown https://github.com/home-assistant/hassio-addons/blob/master/rpc_shutdown/README.md +/addons/samba https://github.com/home-assistant/hassio-addons/blob/master/samba/README.md +/addons/snips https://github.com/home-assistant/hassio-addons/blob/master/snips/README.md +/addons/ssh https://github.com/home-assistant/hassio-addons/blob/master/ssh/README.md +/addons/tellstick https://github.com/home-assistant/hassio-addons/blob/master/tellstick/README.md diff --git a/source/addons/index.html b/source/addons/index.html index c0114b2bf91..b8a3ca0390a 100644 --- a/source/addons/index.html +++ b/source/addons/index.html @@ -1,39 +1,38 @@ --- title: "Hass.io Add-ons" -description: "List of the built-in add-ons of Hass.io." +description: "Find add-ons to install with Home Assistant." regenerate: false --- -

Add-ons for Hass.io allow the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Hass.io panel in Home Assistant.

+

+ Add-ons for Hass.io allow the user to extend the functionality around Home + Assistant by installing additional applications. +

+

+ This can be running an application that Home Assistant can integrate with + (like an MQTT broker) or to share the configuration via Samba for easy editing + from other computers. Add-ons can be configured via the Hass.io panel in Home + Assistant. +

+ +

+ + Add-ons for Hass.io are freely available in the add-on store. +

- Check the Hass.io forums for add-on repositories managed by the community. + To install add-ons, navigate to the Hass.io panel in your Home Assistant + frontend, and click on the "ADD-ON STORE" tab. All add-ons, including their documentation, are available right from the store. + Click on a add-on you are interested in, to read the documentation or to install the add-on.

-

-Add-ons are only available if you've used the Hass.io installer. If you installed Home Assistant using any other method then you cannot use add-ons (but you can achieve the same result manually). +

+ Add-ons are only available if you've used the Hass.io installer. If you + installed Home Assistant using any other method then you cannot use add-ons + (but you can achieve the same result manually).

-{% assign addons = site.addons | sort: 'title' %} - -

Featured add-ons

- -
    -{% for addon in addons %}{% if addon.featured %} -
  • - {{ addon.title }}
    - {{ addon.description }} -
    • -{% endif %}{% endfor %} -
- -

Other add-ons

- -
    -{% for addon in addons %}{% if addon.featured != true %} -
  • - {{ addon.title }}
    - {{ addon.description }} -
    • -{% endif %}{% endfor %} -
+

+ Check the Hass.io forums for + add-on repositories managed by the community. +

diff --git a/source/images/addons/addon-store.png b/source/images/addons/addon-store.png new file mode 100644 index 00000000000..f949208c97f Binary files /dev/null and b/source/images/addons/addon-store.png differ diff --git a/source/images/blog/2020-01-29-changing-the-home-assistant-brand/social.png b/source/images/blog/2020-01-29-changing-the-home-assistant-brand/social.png new file mode 100644 index 00000000000..074d7cb428d Binary files /dev/null and b/source/images/blog/2020-01-29-changing-the-home-assistant-brand/social.png differ