diff --git a/.textlintrc.json b/.textlintrc.json index d8029d8f59d..8f6cb6299a0 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -303,6 +303,7 @@ ["colour", "color"], ["config\\b", "configuration"], ["DarkSky", "Dark Sky"], + ["docs\\b", "documentation"], ["e\\.g\\.", "e.g.,"], ["end ?to ?end", "end-to-end"], ["FRITZ!? ?Box", "FRITZ!Box"], diff --git a/source/_docs/asterisk_mbox.markdown b/source/_docs/asterisk_mbox.markdown index 8c6ba581112..a36c5439dcb 100644 --- a/source/_docs/asterisk_mbox.markdown +++ b/source/_docs/asterisk_mbox.markdown @@ -92,7 +92,7 @@ Before beginning make sure that you have the following: Type=simple User=asterisk Group=asterisk - ExecStart=/usr/local/bin/asterisk_mbox_server -cfg /etc/asterisk/asterisk_mbox.ini + ExecStart=/usr/local/bin/asterisk_mbox_server --cfg /etc/asterisk/asterisk_mbox.ini Restart=on-failure [Install] diff --git a/source/_docs/autostart/systemd.markdown b/source/_docs/autostart/systemd.markdown index ab4ce5ea93c..270fd374e70 100644 --- a/source/_docs/autostart/systemd.markdown +++ b/source/_docs/autostart/systemd.markdown @@ -77,24 +77,24 @@ WantedBy=multi-user.target You need to reload `systemd` to make the daemon aware of the new configuration. ```bash -$ sudo systemctl --system daemon-reload +sudo systemctl --system daemon-reload ``` To have Home Assistant start automatically at boot, enable the service. ```bash -$ sudo systemctl enable home-assistant@YOUR_USER +sudo systemctl enable home-assistant@YOUR_USER ``` To disable the automatic start, use this command. ```bash -$ sudo systemctl disable home-assistant@YOUR_USER +sudo systemctl disable home-assistant@YOUR_USER ``` To start Home Assistant now, use this command. ```bash -$ sudo systemctl start home-assistant@YOUR_USER +sudo systemctl start home-assistant@YOUR_USER ``` You can also substitute the `start` above with `stop` to stop Home Assistant, `restart` to restart Home Assistant, and 'status' to see a brief status report as seen below. @@ -114,18 +114,18 @@ $ sudo systemctl status home-assistant@YOUR_USER To get Home Assistant's logging output, simple use `journalctl`. ```bash -$ sudo journalctl -f -u home-assistant@YOUR_USER +sudo journalctl -f -u home-assistant@YOUR_USER ``` Because the log can scroll quite quickly, you can select to view only the error lines: ```bash -$ sudo journalctl -f -u home-assistant@YOUR_USER | grep -i 'error' +sudo journalctl -f -u home-assistant@YOUR_USER | grep -i 'error' ``` When working on Home Assistant, you can easily restart the system and then watch the log output by combining the above commands using `&&` ```bash -$ sudo systemctl restart home-assistant@YOUR_USER && sudo journalctl -f -u home-assistant@YOUR_USER +sudo systemctl restart home-assistant@YOUR_USER && sudo journalctl -f -u home-assistant@YOUR_USER ``` ### Automatically restarting Home Assistant on failure diff --git a/source/_docs/installation.markdown b/source/_docs/installation.markdown index ab7a9651a09..94f822f7b73 100644 --- a/source/_docs/installation.markdown +++ b/source/_docs/installation.markdown @@ -47,7 +47,7 @@ These install options are fully supported by Home Assistant's documentation. For
diff --git a/source/_integrations/aws.markdown b/source/_integrations/aws.markdown index ce1254c79bc..598d1424e99 100644 --- a/source/_integrations/aws.markdown +++ b/source/_integrations/aws.markdown @@ -103,7 +103,7 @@ context: ## Lambda Notify Usage -AWS Lambda is a notification platform and thus can be controlled by calling the `notify` service [as described here](/integrations/notify/). It will invoke a Lambda for all targets given in the notification payload. A target can be formatted as a function name, an entire ARN ([Amazon Resource Name](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)) or a partial ARN. For more information, please see the [botocore docs](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/lambda.html#Lambda.Client.invoke). +AWS Lambda is a notification platform and thus can be controlled by calling the `notify` service [as described here](/integrations/notify/). It will invoke a Lambda for all targets given in the notification payload. A target can be formatted as a function name, an entire ARN ([Amazon Resource Name](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)) or a partial ARN. For more information, please see the [botocore documentation](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/lambda.html#Lambda.Client.invoke). The Lambda event payload will contain everything passed in the service call payload. Here is an example payload that would be sent to Lambda: @@ -131,7 +131,7 @@ The context will look like this: ## SNS Notify Usage -AWS SNS is a notification platform and thus can be controlled by calling the `notify` service [as described here](/integrations/notify/). It will publish a message to all targets given in the notification payload. A target must be a SNS topic or endpoint ARN ([Amazon Resource Name](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)). For more information, please see the [botocore docs](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/sns.html#SNS.Client.publish). +AWS SNS is a notification platform and thus can be controlled by calling the `notify` service [as described here](/integrations/notify/). It will publish a message to all targets given in the notification payload. A target must be a SNS topic or endpoint ARN ([Amazon Resource Name](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)). For more information, please see the [botocore documentation](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/sns.html#SNS.Client.publish). If one exists, the SNS Subject will be set to the title. All attributes from the payload, except the message, will be sent as stringified message attributes. @@ -157,7 +157,7 @@ If you do not download them, you will lose them and will have to recreate a new ## SQS Notify Usage -AWS SQS is a notification platform and thus can be controlled by calling the `notify` service [as described here](/integrations/notify/). It will publish a message to the queue for all targets given in the notification payload. A target must be a SQS topic URL. For more information, please see the [SQS docs](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/ImportantIdentifiers.html) and [bototcore docs](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/sqs.html#SQS.Client.send_message) +AWS SQS is a notification platform and thus can be controlled by calling the `notify` service [as described here](/integrations/notify/). It will publish a message to the queue for all targets given in the notification payload. A target must be a SQS topic URL. For more information, please see the [SQS documentation](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/ImportantIdentifiers.html) and [bototcore documentation](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/services/sqs.html#SQS.Client.send_message) The SQS event payload will contain everything passed in the service call payload. SQS payloads will be published as stringified JSON. All attributes from the payload, except message, will also be sent as stringified message attributes. Here is an example message that would be published to the SQS queue: diff --git a/source/_integrations/bom.markdown b/source/_integrations/bom.markdown index 6833a3aa2d4..9068b3910f1 100644 --- a/source/_integrations/bom.markdown +++ b/source/_integrations/bom.markdown @@ -34,7 +34,7 @@ name: required: false type: string station: - description: "The station ID string. See the [`sensor.bom` docs](#sensor) for details on how to find the ID of a station." + description: "The station ID string. See the [`sensor.bom` documentation](#sensor) for details on how to find the ID of a station." required: false type: string default: The closest station diff --git a/source/_integrations/caldav.markdown b/source/_integrations/caldav.markdown index ebd456a87a9..e15962d2029 100644 --- a/source/_integrations/caldav.markdown +++ b/source/_integrations/caldav.markdown @@ -8,22 +8,13 @@ ha_release: '0.60' ha_domain: caldav --- -The `caldav` platform allows you to connect to your WebDAV calendar and generate -binary sensors. A different sensor will be created for each individual calendar, -or you can specify custom calendars which match a criteria you define (more on -that below). These sensors will be `on` if you have an on going event in that -calendar or `off` if the event is later in time, or if there is no event at all. -The WebDAV calendar get updated roughly every 15 minutes. +The `caldav` platform allows you to connect to your WebDAV calendar and generate binary sensors. A different sensor will be created for each individual calendar, or you can specify custom calendars which match a criteria you define (more on that below). These sensors will be `on` if you have an on going event in that calendar or `off` if the event is later in time, or if there is no event at all. The WebDAV calendar get updated roughly every 15 minutes. ### Prerequisites -You need to have a CalDAV server and credentials for it. This integration was -tested against [Baikal](http://sabre.io/baikal/) but any integration complying -with the RFC4791 should work. [Nextcloud](https://nextcloud.com/) -and [Owncloud](https://owncloud.org/) work fine. +You need to have a CalDAV server and credentials for it. This integration was tested against [Baikal](http://sabre.io/baikal/) but any integration complying with the RFC4791 should work. [Nextcloud](https://nextcloud.com/) and [Owncloud](https://owncloud.org/) work fine. -You might need some additional system packages to compile the -Python CalDAV library. On a Debian based system, install them by: +You might need some additional system packages to compile the Python CalDAV library. On a Debian based system, install them by: ```bash $ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev @@ -31,8 +22,7 @@ $ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev ### Basic Setup -To integrate a WebDAV calendar in Home Assistant, -add the following section to your `configuration.yaml` file: +To integrate a WebDAV calendar in Home Assistant, add the following section to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry for baikal @@ -52,16 +42,11 @@ calendar: url: https://nextcloud.example.com/remote.php/dav ``` -This example will generate default binary sensors for each calendar you have in -your account. Those calendars will be `on` when there is an ongoing event and -`off` if not. Events that last a whole day are ignored in those calendars. -You have to setup custom calendars in order to take them into account or for -advanced event filtering. +This example will generate default binary sensors for each calendar you have in your account. Those calendars will be `on` when there is an ongoing event and `off` if not. Events that last a whole day are ignored in those calendars. You have to setup custom calendars in order to take them into account or for advanced event filtering. ### Custom calendars -You have the possibility to create multiple binary -sensors for events that match certain conditions. +You have the possibility to create multiple binary sensors for events that match certain conditions. ```yaml # Example configuration.yaml entry @@ -79,13 +64,9 @@ calendar: search: 'Warmup' ``` -This will create two binary sensors for the calendar name Agenda: "HomeOffice" -and "WarmupFlat". Those sensors will be `on` if there is an ongoing event -matching the regular expression specified in `search`. -In custom calendars, events that last a whole day are taken into account. +This will create two binary sensors for the calendar name Agenda: "HomeOffice" and "WarmupFlat". Those sensors will be `on` if there is an ongoing event matching the regular expression specified in `search`. In custom calendars, events that last a whole day are taken into account. -Please note that when you configure custom calendars, -the default ones are not created anymore. +Please note that if you use the `custom_calendars` option, only those calendars will be loaded. You cannot use `calendars` and `custom_calendars` in the same configuration. {% configuration %} url: @@ -102,13 +83,11 @@ password: type: string calendars: required: false - description: > - List of the calendars to filter. - Empty or absent means no filtering, i.e., all calendars will be added. + description: List of the calendars to filter. Empty or absent means no filtering, i.e., all calendars will be added. It cannot be used if `custom_calender` option is used. type: list custom_calendars: required: false - description: Details on any custom binary sensor calendars you want to create. + description: Details on any custom binary sensor calendars you want to create. Using this will only load the custom calendars supplied. No other calendars will load. type: list keys: name: @@ -121,9 +100,7 @@ custom_calendars: type: string search: required: true - description: > - Regular expression for filtering the events based on - the content of their summary, description or location. + description: Regular expression for filtering the events based on the content of their summary, description or location. type: string {% endconfiguration %} @@ -140,6 +117,7 @@ custom_calendars: ### Examples All events of the calendars "private" and "holidays". Note that all day events are not included. + ```yaml # Example configuration.yaml entry for nextcloud calendar: @@ -152,12 +130,9 @@ calendar: - holidays ``` -Full example with automation to wake up to music if not holiday. -Prerequisite: you have a calendar named "work" where -you create calendar entries containing "Holiday". +Full example with automation to wake up to music if not holiday. Prerequisite: you have a calendar named "work" where you create calendar entries containing "Holiday". -Custom calendar names are built from the -main calendar + name of the custom calendar. +Custom calendar names are built from the main calendar + name of the custom calendar. Using the option of `'.*'` will load all calendar events. ```yaml # configuration.yaml @@ -170,6 +145,9 @@ calendar: - name: holiday calendar: work search: 'Holiday' + - name: vacation + calendar: vacation + search: '.*' # automations.yaml - id: wakeup diff --git a/source/_integrations/cast.markdown b/source/_integrations/cast.markdown index d21398e18f0..8a326f576ac 100644 --- a/source/_integrations/cast.markdown +++ b/source/_integrations/cast.markdown @@ -1,7 +1,6 @@ --- title: Google Cast description: Instructions on how to integrate Google Cast into Home Assistant. -logo: google_cast.png ha_category: - Media Player featured: true diff --git a/source/_integrations/dialogflow.markdown b/source/_integrations/dialogflow.markdown index 8064cbc38a7..2e7b45ec041 100644 --- a/source/_integrations/dialogflow.markdown +++ b/source/_integrations/dialogflow.markdown @@ -11,7 +11,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 ([docs](/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 `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). Dialogflow could be [integrated](https://dialogflow.com/docs/integrations/) with many popular messaging, virtual assistant and IoT platforms. diff --git a/source/_integrations/envisalink.markdown b/source/_integrations/envisalink.markdown index 1550427f383..26e348a4a35 100644 --- a/source/_integrations/envisalink.markdown +++ b/source/_integrations/envisalink.markdown @@ -105,7 +105,7 @@ panic_type: default: Police type: string zones: - description: "Envisalink boards have no way to tell us which zones are actually in use, so each zone must be configured in Home Assistant. For each zone, at least a name must be given. For more information on the available zone types, take a look at the [Binary Sensor](/integrations/envisalink) docs. *Note: If no zones are specified, Home Assistant will not load any binary_sensor components.*" + description: "Envisalink boards have no way to tell us which zones are actually in use, so each zone must be configured in Home Assistant. For each zone, at least a name must be given. For more information on the available zone types, take a look at the [Binary Sensor](/integrations/envisalink) documentation. *Note: If no zones are specified, Home Assistant will not load any binary_sensor components.*" required: false type: integer keys: diff --git a/source/_integrations/google_domains.markdown b/source/_integrations/google_domains.markdown index f1fd752907d..34d2e7bc35b 100644 --- a/source/_integrations/google_domains.markdown +++ b/source/_integrations/google_domains.markdown @@ -1,7 +1,6 @@ --- title: Google Domains description: Keep your computer registered with the Google Domains dynamic DNS. -logo: google_domains.png ha_category: - Network ha_release: 0.57 diff --git a/source/_integrations/google_translate.markdown b/source/_integrations/google_translate.markdown index 58505907da7..eade1d2951a 100644 --- a/source/_integrations/google_translate.markdown +++ b/source/_integrations/google_translate.markdown @@ -1,7 +1,6 @@ --- title: Google Translate Text-to-Speech description: Instructions on how to setup Google Translate Text-to-Speech with Home Assistant. -logo: google.png ha_category: - Text-to-speech ha_release: 0.35 diff --git a/source/_integrations/habitica.markdown b/source/_integrations/habitica.markdown index 37645019ed2..bc5e2bd939b 100644 --- a/source/_integrations/habitica.markdown +++ b/source/_integrations/habitica.markdown @@ -73,7 +73,7 @@ A successful call to this service will fire an event `habitica_api_call_success` |----------------------|--------|----------------| | `name` | string | Copied from service data attribute. | | `path` | [string] | Copied from service data attribute. | -| `data` | map | Deserialized `data` field of JSON object Habitica's server returned in response to API call. For more info see [docs](https://habitica.com/apidoc/). | +| `data` | map | Deserialized `data` field of JSON object Habitica's server returned in response to API call. For more info see the [API documentation](https://habitica.com/apidoc/). | #### Let's consider some examples on how to call the service. @@ -87,7 +87,7 @@ So let's call the API on `habitica.api_call`. * Remove `https://habitica.com/api/v3/` at the beginning of the endpoint URL. * Split the remaining on slashes (/) and **append the lowercase method** at the end. * You should get `["tasks", "user", "post"]`. To get a better idea of the API you are recommended to try all of the API calls in IPython console [using this package](https://github.com/ASMfreaK/habitipy/blob/master/README.md). -* The `args` key is more or less described in the [docs](https://habitica.com/apidoc/). +* The `args` key is more or less described in the [API documentation](https://habitica.com/apidoc/). Combining all together: call `habitica.api_call` with data diff --git a/source/_integrations/html5.markdown b/source/_integrations/html5.markdown index e39e9ba0896..7c38d3ef9ef 100644 --- a/source/_integrations/html5.markdown +++ b/source/_integrations/html5.markdown @@ -90,7 +90,7 @@ The `html5` platform can only function if all of the following requirements are ### Configuring the platform -1. Make sure you can access your Home Assistant installation from outside your network over HTTPS ([see docs](/docs/configuration/remote/)) or can perform an alternative [Domain Name Verification Method](https://support.google.com/webmasters/answer/9008080#domain_name_verification) on the domain used by Home Assistant. +1. Make sure you can access your Home Assistant installation from outside your network over HTTPS ([see documentation](/docs/configuration/remote/)) or can perform an alternative [Domain Name Verification Method](https://support.google.com/webmasters/answer/9008080#domain_name_verification) on the domain used by Home Assistant. 2. Create a new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard), this project will be imported into Firebase later (alternatively, the project can also be created during step 4). 3. Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain via Google Webmaster Central / Search Console - [see below](#verify-your-domain). 4. With the domain verified, go to [https://console.firebase.google.com](https://console.firebase.google.com), select import Google project and select the project you created. diff --git a/source/_integrations/hue.markdown b/source/_integrations/hue.markdown index 7c9475c443e..453d7179f52 100644 --- a/source/_integrations/hue.markdown +++ b/source/_integrations/hue.markdown @@ -1,4 +1,4 @@ ---- +-- title: Philips Hue description: Instructions on setting up Philips Hue within Home Assistant. ha_category: @@ -148,4 +148,4 @@ The Hue API doesn't activate scenes directly; rather, they must be associated wi Neither group names nor scene names are guaranteed unique in Hue. If you are observing unexpected behavior from calling Hue scenes in Home Assistant, make the names of your Hue scenes more specific in the Hue app. -The Hue hub has limited space for scenes and will delete scenes if new ones get created that would overflow that space. The API docs say this is based on the scenes that are "least recently used." +The Hue hub has limited space for scenes and will delete scenes if new ones get created that would overflow that space. The API documentation says this is based on the scenes that are "least recently used." diff --git a/source/_integrations/ifttt.markdown b/source/_integrations/ifttt.markdown index f527ff26244..c7af255d885 100644 --- a/source/_integrations/ifttt.markdown +++ b/source/_integrations/ifttt.markdown @@ -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 ([docs](/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 `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)). ### Setting up the integration diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index e34d38da473..2712d5d1a78 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -8,7 +8,7 @@ ha_release: 0.8 ha_domain: mqtt --- -The `mqtt` light platform lets you control your MQTT enabled lights through one of the supported message schemas. +The `mqtt` light platform lets you control your MQTT enabled lights through one of the supported message schemas, `default`, `json` or `template`. ## Comparison of light MQTT schemas @@ -214,6 +214,11 @@ rgb_value_template: description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value." required: false type: string +schema: + description: The schema to use. Must be `default` or omitted to select the default schema". + required: false + type: string + default: default state_topic: description: The MQTT topic subscribed to receive state updates. required: false @@ -501,6 +506,11 @@ rgb: required: false type: boolean default: false +schema: + description: The schema to use. Must be `json` to select the JSON schema". + required: false + type: string + default: default state_topic: description: The MQTT topic subscribed to receive state updates. required: false @@ -784,6 +794,11 @@ red_template: description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value." required: false type: string +schema: + description: The schema to use. Must be `template` to select the template schema". + required: false + type: string + default: default state_template: description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value." required: false diff --git a/source/_integrations/mailgun.markdown b/source/_integrations/mailgun.markdown index e36d0d176f7..e4414ce9370 100644 --- a/source/_integrations/mailgun.markdown +++ b/source/_integrations/mailgun.markdown @@ -9,7 +9,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 ([docs](/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 `base_url` configured for the HTTP integration ([documentation](/integrations/http/#base_url)). 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. diff --git a/source/_integrations/map.markdown b/source/_integrations/map.markdown index 757913c4a83..33c096743c6 100644 --- a/source/_integrations/map.markdown +++ b/source/_integrations/map.markdown @@ -18,3 +18,7 @@ map: