mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-13 20:36:52 +00:00
Remove base_url, add external_url & internal_url (#13307)
This commit is contained in:
Franck Nijhof
GitHub
parent
e1f68bc73f
commit
3701a98e9f
@ -10,18 +10,24 @@ If you prefer YAML, you can add the following information to your `configuration
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
name: Home
|
||||
latitude: 32.87336
|
||||
longitude: 117.22743
|
||||
elevation: 430
|
||||
unit_system: metric
|
||||
time_zone: America/Los_Angeles
|
||||
name: Home
|
||||
external_url: "https://www.example.com"
|
||||
internal_url: "http://homeassistant.local:8123"
|
||||
whitelist_external_dirs:
|
||||
- /usr/var/dumping-ground
|
||||
- /tmp
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
name:
|
||||
description: Name of the location where Home Assistant is running.
|
||||
required: false
|
||||
type: string
|
||||
latitude:
|
||||
description: Latitude of your location required to calculate the time the sun rises and sets.
|
||||
required: false
|
||||
@ -46,8 +52,12 @@ time_zone:
|
||||
description: "Pick your time zone from the column **TZ** of [Wikipedia's list of tz database time zones](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)"
|
||||
required: false
|
||||
type: string
|
||||
name:
|
||||
description: Name of the location where Home Assistant is running.
|
||||
external_url:
|
||||
description: "The URL that Home Assistant is available on from the internet. For example: `https://example.duckdns.org:8123`. Note that this setting may only contain a protocol, hostname and port; using a path is not supported."
|
||||
required: false
|
||||
type: string
|
||||
internal_url:
|
||||
description: "The URL that Home Assistant is available on from your local network. For example: `http://homeassistant.local:8123`. Note that this setting may only contain a protocol, hostname and port; using a path is not supported."
|
||||
required: false
|
||||
type: string
|
||||
customize:
|
||||
@ -68,6 +78,6 @@ whitelist_external_dirs:
|
||||
type: list
|
||||
{% endconfiguration %}
|
||||
|
||||
### Reload Core Service
|
||||
## Reload Core Service
|
||||
|
||||
Home Assistant offers a service to reload the core configuration while Home Assistant is running called `homeassistant.reload_core_config`. This allows you to change any of the above sections and see it being applied without having to restart Home Assistant. To call this service, go to the "Service" tab under Developer Tools, select the `homeassistant.reload_core_config` service and click the "CALL SERVICE" button. Alternatively, you can press the "Reload Location & Customizations" button under Configuration > Server Control.
|
||||
|
||||
@ -45,8 +45,6 @@ On your `configuration.yaml` file, edit the `http` component.
|
||||
http:
|
||||
# For extra security set this to only accept connections on localhost if Caddy is on the same machine
|
||||
# server_host: 127.0.0.1
|
||||
# Update this line to be your domain
|
||||
base_url: https://example.com
|
||||
use_x_forwarded_for: true
|
||||
# You must set the trusted proxy IP address so that Home Assistant will properly accept connections
|
||||
# Set this to your Caddy machine IP, or localhost if hosted on the same machine.
|
||||
@ -57,4 +55,3 @@ http:
|
||||
|
||||
You can either start Caddy or [install it as a service](https://github.com/mholt/caddy/wiki/Caddy-as-a-service-examples), pass the Caddyfile path as a `conf` parameter.
|
||||
Home Assistant will be listening on port 443 (HTTPS) and all insecure traffic on port 80 will be redirected.
|
||||
|
||||
|
||||
@ -333,9 +333,10 @@ Now edit your `configuration.yaml` file to reflect the SSL entries and your base
|
||||
http:
|
||||
ssl_certificate: /etc/letsencrypt/live/examplehome.duckdns.org/fullchain.pem
|
||||
ssl_key: /etc/letsencrypt/live/examplehome.duckdns.org/privkey.pem
|
||||
base_url: examplehome.duckdns.org
|
||||
```
|
||||
|
||||
Go to the Home Assistant UI -> **Configuration** -> **General** and set the external URL to your new URL, for example: `https://examplehome.duckdns.org`. Please note, advanced mode on your user profile must be enabled in order to see the external URL option.
|
||||
|
||||
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.
|
||||
|
||||
@ -57,7 +57,6 @@ The [`http`](/integrations/http/) section must contain the full path to the need
|
||||
|
||||
```yaml
|
||||
http:
|
||||
base_url: https://mydomain.com:8123
|
||||
ssl_certificate: /etc/letsencrypt/live/mydomain.com/fullchain.pem
|
||||
ssl_key: /etc/letsencrypt/live/mydomain.com/privkey.pem
|
||||
```
|
||||
|
||||
@ -96,14 +96,16 @@ In your `configuration.yaml` file, edit the [HTTP component](/integrations/http/
|
||||
http:
|
||||
# For extra security set this to only accept connection on localhost if HAProxy is on the same machine
|
||||
# server_host: 127.0.0.1
|
||||
# Update this line to be your domain
|
||||
base_url: https://example.com
|
||||
use_x_forwarded_for: true
|
||||
# You must set the trusted proxy IP address so that Home Assistant will properly accept connections
|
||||
# Set this to your HAProxy machine IP, or localhost if hosted on the same machine.
|
||||
trusted_proxies: <HAProxy IP address here, 127.0.0.1 if same machine>
|
||||
```
|
||||
|
||||
Go to the Home Assistant UI -> **Configuration** -> **General** and set the external URL
|
||||
to your new URL, for example: `https://examplehome.duckdns.org`.
|
||||
Please note, advanced mode on your user profile must be enabled in order to see the external URL option.
|
||||
|
||||
### Restart or Reload HAProxy
|
||||
|
||||
Use your OS method of restarting or reloading HAProxy. Use Google for this.
|
||||
|
||||
@ -89,14 +89,14 @@ On your `configuration.yaml` file, edit the `http` component.
|
||||
http:
|
||||
# For extra security set this to only accept connections on localhost if NGINX is on the same machine
|
||||
# server_host: 127.0.0.1
|
||||
# Update this line to be your domain
|
||||
base_url: https://example.com
|
||||
use_x_forwarded_for: true
|
||||
# You must set the trusted proxy IP address so that Home Assistant will properly accept connections
|
||||
# Set this to your NGINX machine IP, or localhost if hosted on the same machine.
|
||||
trusted_proxies: <NGINX IP address here, or 127.0.0.1 if hosted on the same machine>
|
||||
```
|
||||
|
||||
Go to the Home Assistant UI -> **Configuration** -> **General** and set the external URL to your new URL, for example: `https://examplehome.duckdns.org`. Please note, advanced mode on your user profile must be enabled in order to see the external URL option.
|
||||
|
||||
### NGINX configuration
|
||||
|
||||
```nginx
|
||||
|
||||
@ -13,7 +13,7 @@ ha_domain: ambiclimate
|
||||
Integrates [Ambiclimate](https://ambiclimate.com/) Air Conditioning controller into Home Assistant.
|
||||
|
||||
You must create an application [here](https://api.ambiclimate.com/clients) to obtain a `client_id` and `client_secret`.
|
||||
The `callback url` should be configured as your Home Assistant `base_url` + `/api/ambiclimate`, e.g., `https://example.com/api/ambiclimate`.
|
||||
The `callback url` should be configured as your Home Assistant external URL + `/api/ambiclimate`, e.g., `https://example.com/api/ambiclimate`.
|
||||
|
||||
To enable this platform, add the following lines to your `configuration.yaml` file:
|
||||
|
||||
|
||||
@ -30,13 +30,14 @@ Home Assistant has its own Cast application to show the Home Assistant UI on any
|
||||
```
|
||||
<div class='note'>
|
||||
|
||||
Home Assistant Cast requires your Home Assistant installation to be accessible via `https://`. If you're using Home Assistant Cloud, you don't need to do anything. Otherwise you must make sure that you have configured the `base_url` for [the `http` integration](/integrations/http/).
|
||||
Home Assistant Cast requires your Home Assistant installation to be accessible via `https://`. If you're using Home Assistant Cloud, you don't need to do anything. Otherwise you must make sure that you have configured the `external_url` in your [configuration](/docs/configuration/basic).
|
||||
|
||||
</div>
|
||||
|
||||
## Advanced use
|
||||
|
||||
### Manual configuration
|
||||
|
||||
By default, any discovered Cast device is added to Home Assistant. This can be restricted by supplying a white list of wanted chrome casts.
|
||||
|
||||
```yaml
|
||||
|
||||
@ -10,7 +10,7 @@ ha_domain: dialogflow
|
||||
|
||||
The `dialogflow` integration is designed to be used with the [webhook](https://dialogflow.com/docs/fulfillment#webhook) integration of [Dialogflow](https://dialogflow.com/). When a conversation ends with a user, Dialogflow sends an action and parameters to the webhook.
|
||||
|
||||
To be able to receive messages from Dialogflow, your Home Assistant instance needs to be accessible from the web and you need to have the `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)). Dialogflow will return fallback answers if your server does not answer or takes too long (more than 5 seconds).
|
||||
To be able to receive messages from Dialogflow, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic). Dialogflow will return fallback answers if your server does not answer or takes too long (more than 5 seconds).
|
||||
|
||||
Dialogflow could be [integrated](https://dialogflow.com/docs/integrations/) with many popular messaging, virtual assistant and IoT platforms.
|
||||
|
||||
|
||||
@ -42,11 +42,3 @@ tts:
|
||||
- platform: google_translate
|
||||
language: 'de'
|
||||
```
|
||||
|
||||
If you are using SSL certificate or Docker, you may need to add the `base_url` configuration variable to your `http` integration as follows:
|
||||
|
||||
```yaml
|
||||
#Example configuration.yaml entry
|
||||
http:
|
||||
base_url: https://example.duckdns.org
|
||||
```
|
||||
|
||||
@ -42,11 +42,6 @@ server_port:
|
||||
required: false
|
||||
type: integer
|
||||
default: 8123
|
||||
base_url:
|
||||
description: "The URL that Home Assistant is available on the internet. For example: `https://hass-example.duckdns.org:8123`. The iOS app finds local installations, if you have an outside URL use this so that you can auto-fill when discovered in the app. Note that this setting may only contain a protocol, hostname and port; using a path is *not* currently supported."
|
||||
required: false
|
||||
type: string
|
||||
default: Your local IP address
|
||||
ssl_certificate:
|
||||
description: Path to your TLS/SSL certificate to serve Home Assistant over a secure connection.
|
||||
required: false
|
||||
|
||||
@ -14,7 +14,7 @@ ha_domain: ifttt
|
||||
|
||||
## Sending events from IFTTT to Home Assistant
|
||||
|
||||
To be able to receive events from IFTTT, your Home Assistant instance needs to be accessible from the web and you need to have the `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)).
|
||||
To be able to receive events from IFTTT, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic).
|
||||
|
||||
### Setting up the integration
|
||||
|
||||
|
||||
@ -7,12 +7,6 @@ ha_domain: image_processing
|
||||
|
||||
Image processing enables Home Assistant to process images from [cameras](/integrations/#camera). Only camera entities are supported as sources.
|
||||
|
||||
<div class='note'>
|
||||
|
||||
If you are running Home Assistant over SSL or from within a container, you will have to setup a base URL (`base_url`) inside the [HTTP component](/integrations/http/).
|
||||
|
||||
</div>
|
||||
|
||||
## ALPR
|
||||
|
||||
ALPR entities have a vehicle counter attribute `vehicles` and all found plates are stored in the `plates` attribute.
|
||||
|
||||
@ -98,7 +98,7 @@ Once all zones are configured you'll be presented with the configuration for add
|
||||
|
||||
**Blink panel LED on when sending state change:** The desired LED behavior for the panel.
|
||||
|
||||
**Override default Home Assistant API host panel URL:** The Konnected Alarm Panel post sensor states back to the Home Assistant API. If this value is unchecked the panel will default postbacks using `base_url` in the `http` component. If you've set `base_url` to an external hostname, then you'll want to check this field and set the **Override API host URL** to your _local_ IP address and port (e.g., `http://192.168.1.101:8123`).
|
||||
**Override default Home Assistant API host panel URL:** The Konnected Alarm Panel post sensor states back to the Home Assistant API. If this value is unchecked the panel will default postbacks using the URL [configured](/docs/configuration/basic) in Home Assistant. By default, the integration will use the internal URL. However, if you check this field and set the **Override API host URL** to your _local_ IP address and port (e.g., `http://192.168.1.101:8123`), it will be used instead of the internal URL.
|
||||
|
||||
**Override API host URL (optional):** The host info to use if you checked **Override default Home Assistant API host panel URL** in the step above. This is ignored if **Override default Home Assistant API host panel URL** is unchecked.
|
||||
|
||||
@ -132,10 +132,10 @@ access_token:
|
||||
required: true
|
||||
type: string
|
||||
api_host:
|
||||
description: Override the IP address/host (and port number) of Home Assistant that the Konnected device(s) will use to communicate sensor state updates. If omitted, this is defaulted to the value of `base_url` in the `http` component. If you've set `base_url` to an external hostname, then you'll want to set this value back to your _local_ IP address and port (e.g., `http://192.168.1.101:8123`).
|
||||
description: Override the IP address/host (and port number) of Home Assistant that the Konnected device(s) will use to communicate sensor state updates. If omitted, this is defaulted to the value of internal URL from the Home Assistant configuration is used.
|
||||
required: false
|
||||
type: string
|
||||
default: value of `base_url`
|
||||
default: value of internal URL
|
||||
devices:
|
||||
description: A list of Konnected devices that you have on your network.
|
||||
required: true
|
||||
|
||||
@ -8,7 +8,7 @@ ha_config_flow: true
|
||||
ha_domain: mailgun
|
||||
---
|
||||
|
||||
To be able to receive webhooks from Mailgun, your Home Assistant instance needs to be accessible from the web and you need to have the `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)).
|
||||
To be able to receive webhooks from Mailgun, your Home Assistant instance needs to be accessible from the web and you need to have the extern URL [configured](/docs/configuration/basic)).
|
||||
|
||||
To set it up, go to the integrations page in the configuration screen and find Mailgun. Click on configure. Follow the instructions on the screen to configure Mailgun.
|
||||
|
||||
|
||||
@ -86,7 +86,7 @@ The `netatmo` sensor platform is consuming the information provided by a [Netatm
|
||||
|
||||
The [Netatmo Smart Indoor](https://www.netatmo.com/en-gb/security/cam-indoor) or [Outdoor](https://www.netatmo.com/en-gb/security/cam-outdoor) cameras, [Smart Door and Window Sensors](https://www.netatmo.com/en-gb/security/cam-indoor/tag), as well as the [Netatmo Smart Smoke Alarm](https://www.netatmo.com/en-gb/security/smoke-alarm), send instant events to Home Assistant by using webhooks. It is required to have your camera enabled in Home Assistant.
|
||||
|
||||
To be able to receive events from [Netatmo](https://www.netatmo.com/en-gb/), your Home Assistant instance needs to be accessible from the web over port `80` or `443`. To achieve this you can either use your Nabu Casa account or for example Duck DNS ([Home Assistant instructions](/addons/duckdns/)). You also need to have the `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)).
|
||||
To be able to receive events from [Netatmo](https://www.netatmo.com/en-gb/), your Home Assistant instance needs to be accessible from the web over port `80` or `443`. To achieve this you can either use your Nabu Casa account or for example Duck DNS ([Home Assistant instructions](/addons/duckdns/)). You also need to have the external URL configured in the Home Assistant [configuration](/docs/configuration/basic).
|
||||
|
||||
Events coming in from Netatmo will be available as an event in Home Assistant and are fired as `netatmo_event`, along with their data. You can use these events to trigger automations.
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ ha_codeowners:
|
||||
ha_domain: point
|
||||
---
|
||||
|
||||
The Point hub enables integration with the [Minut Point](https://minut.com/). To connect with Point, you will have to [sign up for a developer account](https://minut.com/community/developers/) and get a `client_id` and `client_secret` with the `callback url` configured as your Home Assistant `base_url` + `/api/minut`, e.g., `http://localhost:8123/api/minut`. The `client_id` and `client_secret` should be used as below.
|
||||
The Point hub enables integration with the [Minut Point](https://minut.com/). To connect with Point, you will have to [sign up for a developer account](https://minut.com/community/developers/) and get a `client_id` and `client_secret` with the `callback url` configured as your Home Assistant URL + `/api/minut`, e.g., `http://localhost:8123/api/minut`. The `client_id` and `client_secret` should be used as below.
|
||||
|
||||
Once Home Assistant is started, a configurator will pop up asking you to Authenticate your Point account via a link. When you follow the link and click on **Accept** you will be redirected to the `callback url` and the Point integration will be automatically configured and you can go back to the original dialog and press **Submit**.
|
||||
|
||||
|
||||
@ -52,7 +52,7 @@ The PAT is used to create a Home Assistant SmartApp in your SmartThings account
|
||||
This integration requires an internet accessible incoming webhook to receive push updates from SmartThings. The preferred approach is to subscribe to [Home Assistant Cloud (Nabu Casa)](https://www.nabucasa.com/) and the integration will configure and use a cloudhook automatically. Alternatively, you will have to configure and setup a internet accessible webhook in Home Assistant as described below:
|
||||
|
||||
1. Setup [remote access](/docs/configuration/remote/) via a domain name secured with SSL. *Self-signed SSL certificates are not supported by the SmartThings Cloud API.*
|
||||
1. Set [`base_url` of the HTTP integration](/integrations/http#base_url) to the URL that Home Assistant is available on the internet (this must start with `https://`).
|
||||
1. Set the external URL in the Home Assistant [configuration](/docs/configuration/basic) to the URL that Home Assistant is available on the internet (this must start with `https://`).
|
||||
|
||||
## Setup instructions
|
||||
|
||||
@ -282,7 +282,7 @@ The SmartThings Switch platform lets you control devices that have the [`switch`
|
||||
|
||||
#### Aborted: Home Assistant is not configured correctly to receive updates from SmartThings
|
||||
|
||||
This error message occurs when you do not have an active Home Assistant Cloud (Nabu Casa) subscription and the `base_url` is not configured correctly (it must start with `https`). Update your Home Assistant configuration per the prerequisites above, restart, and try again.
|
||||
This error message occurs when you do not have an active Home Assistant Cloud (Nabu Casa) subscription and the external URL is not configured correctly (it must start with `https`). Update your Home Assistant configuration per the prerequisites above, and try again.
|
||||
|
||||
#### Error: The token must be in the UID/GUID format
|
||||
|
||||
@ -306,7 +306,7 @@ This error message occurs when all of the SmartThings locations under the accoun
|
||||
|
||||
#### Webhook Troubleshooting Checklist
|
||||
|
||||
1. Ensure `base_url` is properly set to the _external address_ that Home Assistant is available to the internet. SmartThings must be able to reach this address.
|
||||
1. Ensure external URL is properly set to the _external address_ that Home Assistant is available to the internet. SmartThings must be able to reach this address.
|
||||
1. Validate there are no problems with your certificate or SSL configuration by using an online checker, such as [https://www.digicert.com/help/](https://www.digicert.com/help/).
|
||||
1. Some reverse proxy configuration settings can interfere with communication from SmartThings. For example, TLSv1.3 is not supported. Setting the supported cipher suite too restrictly will prevent handshaking. The following NGINX SSL configuration is known to work:
|
||||
```nginx
|
||||
@ -324,9 +324,9 @@ This error message occurs when all of the SmartThings locations under the accoun
|
||||
```
|
||||
1. While the error message (above) is being displayed, run the following command from outside your local network to confirm it is responding to the ping lifecycle event:
|
||||
```bash
|
||||
curl -X POST https://{BASE_URL}/api/webhook/{WEBHOOK_ID} -H "Content-Type: application/json; charset=utf-8" -d $'{"lifecycle": "PING", "executionId": "00000000-0000-0000-0000-000000000000", "locale": "en", "version": "1.0.0", "pingData": { "challenge": "00000000-0000-0000-0000-000000000000"}}'
|
||||
curl -X POST https://{EXTERNAL_URL}/api/webhook/{WEBHOOK_ID} -H "Content-Type: application/json; charset=utf-8" -d $'{"lifecycle": "PING", "executionId": "00000000-0000-0000-0000-000000000000", "locale": "en", "version": "1.0.0", "pingData": { "challenge": "00000000-0000-0000-0000-000000000000"}}'
|
||||
```
|
||||
Where `{BASE_URL}` is your external address and `{WEBHOOK_ID}` is the value of `webhook_id` from `.storage/smartthings` in your Home Assistant configuration directory.
|
||||
Where `{EXTERNAL_URL}` is your external address and `{WEBHOOK_ID}` is the value of `webhook_id` from `.storage/smartthings` in your Home Assistant configuration directory.
|
||||
|
||||
The expected response is:
|
||||
```bash
|
||||
|
||||
@ -35,8 +35,6 @@ To create the required Spotify application:
|
||||
- If you are using SSL: `https://<your_home_assistant_url_or_local_ip>:<port>/auth/external/callback`
|
||||
- Click **Save** after adding the URI.
|
||||
|
||||
If you are using an externally accessible address, you will likely also need to set the `base_url` attribute of the [HTTP Integration](/integrations/http/). This should be set using the same base URL as the redirect URI, e.g., if you used a domain name (not local IP) in the redirect, then use the same domain name in your `base_url`.
|
||||
|
||||
## Configuration
|
||||
|
||||
To add Spotify to your installation, add the following to your `configuration.yaml` file:
|
||||
|
||||
@ -19,9 +19,6 @@ To integrate this into Home Assistant, add the following section to your `config
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
http:
|
||||
base_url: <public_url> # the Home Assistant https url which is exposed to the internet.
|
||||
|
||||
telegram_bot:
|
||||
- platform: webhooks
|
||||
api_key: YOUR_API_KEY
|
||||
@ -54,7 +51,7 @@ proxy_params:
|
||||
required: false
|
||||
type: string
|
||||
url:
|
||||
description: Allow to overwrite the `base_url` from the [`http`](/integrations/http/) integration for different configurations (`https://<public_url>:<port>`).
|
||||
description: Allow to overwrite the external URL from the Home Assistant [configuration](/docs/configuration/basic/) for different setups (`https://<public_url>:<port>`).
|
||||
required: false
|
||||
type: string
|
||||
trusted_networks:
|
||||
@ -72,9 +69,6 @@ The configuration sample below shows how an entry can look like:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
http:
|
||||
base_url: <public_url>
|
||||
|
||||
telegram_bot:
|
||||
- platform: webhooks
|
||||
api_key: YOUR_API_KEY
|
||||
|
||||
@ -21,7 +21,7 @@ tts:
|
||||
|
||||
<div class='note'>
|
||||
|
||||
Depending on your setup, you might need to set a base URL (`base_url`) inside the [HTTP component](/integrations/http/) or in the parameters of this component.
|
||||
Depending on your setup, you might need to set a external URL (`external_url`) inside the [configuration](/docs/configuration/basic/) or in the parameters of this component.
|
||||
|
||||
</div>
|
||||
|
||||
@ -44,10 +44,10 @@ time_memory:
|
||||
type: integer
|
||||
default: 300
|
||||
base_url:
|
||||
description: A base URL to use *instead* of the one set in the [HTTP component](/integrations/http/). It is used as-is by the `tts` component. In particular, you need to include the protocol scheme `http://` or `https://` and the correct port number. They will not be automatically added for you.
|
||||
description: A base URL to use *instead* of the one set in the Home Assistant [configuration](/docs/configuration/basic). It is used as-is by the `tts` component. In particular, you need to include the protocol scheme `http://` or `https://` and the correct port number. They will not be automatically added for you.
|
||||
required: false
|
||||
type: string
|
||||
default: value of ``http.base_url``
|
||||
default: value of internal URL
|
||||
service_name:
|
||||
description: Define the service name.
|
||||
required: false
|
||||
@ -70,21 +70,21 @@ tts:
|
||||
|
||||
<div class='note'>
|
||||
|
||||
In the above example, `base_url` is custom to this particular TTS platform configuration. It is not suggesting that you use the `base_url` that you have set for your core Home Assistant configuration. The reason you might need to do this is outlined in the next section.
|
||||
In the above example, `base_url` is custom to this particular TTS platform configuration. It is not suggesting that you use the internal URL that you have set for your core Home Assistant configuration. The reason you might need to do this is outlined in the next section.
|
||||
|
||||
</div>
|
||||
|
||||
## When do you need to set `base_url` here?
|
||||
|
||||
The general answer is "whenever the global `base_url` set in [HTTP component](/integrations/http/) is not adequate to allow the `say` service to run". The `say` service operates by generating a media file that contains the speech corresponding to the text passed to the service. Then the `say` service sends a message to the media device with a URL pointing to the file. The device fetches the media file at the URL and plays the media. Some combinations of a media device, network configuration and Home Assistant configuration can make it so that the device cannot fetch the media file.
|
||||
The general answer is "whenever the global internal URL set in the [configuration](/docs/configuration/basic/) of Home Assistant is not adequate to allow the `say` service to run". The `say` service operates by generating a media file that contains the speech corresponding to the text passed to the service. Then the `say` service sends a message to the media device with a URL pointing to the file. The device fetches the media file at the URL and plays the media. Some combinations of a media device, network configuration and Home Assistant configuration can make it so that the device cannot fetch the media file.
|
||||
|
||||
The following sections describe some of the problems encountered with media devices.
|
||||
|
||||
### Self-signed certificates
|
||||
|
||||
This problem occurs when your Home Assistant instance is configured to be accessed through SSL, and you are using a self-signed certificate.
|
||||
This problem occurs when your Home Assistant instance is configured to be accessed through SSL, and you are using a self-signed certificate on your internal URL.
|
||||
|
||||
The `tts` service will send an `https://` URL to the media device, which will check the certificate, and reject it. So it won't play your file. If you could make the device accept your certificate, it would play the file. However, many media devices do not allow changing settings to accept self-signed certificates. Ultimately, your option may be to serve files to the device as `http://` rather than `https://`. To do this, you *could* change the `base_url` setting in [HTTP component](/integrations/http/), but that would turn off SSL for all services that use `base_url`. Instead, setting a `base_url` for the `tts` service allows turning off SSL only for this component.
|
||||
The `tts` service will send an `https://` URL to the media device, which will check the certificate, and reject it. So it won't play your file. If you could make the device accept your certificate, it would play the file. However, many media devices do not allow changing settings to accept self-signed certificates. Ultimately, your option may be to serve files to local devices as `http://` rather than `https://`.
|
||||
|
||||
### Google cast devices
|
||||
|
||||
@ -92,9 +92,7 @@ The Google cast devices (Google Home, Chromecast, etc.) present the following pr
|
||||
|
||||
* They [reject self-signed certificates](#self-signed-certificates).
|
||||
|
||||
* They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). Setting a `base_url` that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
|
||||
|
||||
* An alternative way to force Google cast devices to use internal DNS is to block them from accessing Google DNS at the firewall/router level. This would be useful in the case, for example, where your internal IP of Home Assistant is a private IP and you have your internal DNS server (quite often a split-brain DNS scenario). This method works on both Google Home Mini and Google Chromecasts.
|
||||
* They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). Setting a internal URL that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
|
||||
|
||||
## Service say
|
||||
|
||||
|
||||
@ -39,7 +39,7 @@ auth_token:
|
||||
|
||||
After configuring the base Twilio component, add and configure either or both of the [Twilio SMS](/integrations/twilio_sms) and [Twilio Phone](/integrations/twilio_call) integrations to utilize the notification functionality.
|
||||
|
||||
To be able to receive events from Twilio, your Home Assistant instance needs to be accessible from the web and you need to have the `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)).
|
||||
To be able to receive events from Twilio, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic) in Home Assistant..
|
||||
|
||||
To set it up, go to the integrations page in the configuration screen and find Twilio. Click on configure. Follow the instructions on the screen to configure Twilio.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user