diff --git a/source/_components/abode.markdown b/source/_components/abode.markdown index 87b689230bc..63789926840 100644 --- a/source/_components/abode.markdown +++ b/source/_components/abode.markdown @@ -13,9 +13,12 @@ ha_release: 0.52 ha_iot_class: "Cloud Push" --- -The `abode` component will allow users to integrate their Abode Home Security systems into Home Assistant and use its alarm system and sensors to automate their homes. +The `abode` component will allow users to integrate their Abode Home Security +systems into Home Assistant and use its alarm system and sensors to automate +their homes. -Please visit the [Abode website](https://goabode.com/) for further information about Abode Security. +Please visit the [Abode website](https://goabode.com/) for further information +about Abode Security. There is currently support for the following device types within Home Assistant: @@ -30,7 +33,8 @@ There is currently support for the following device types within Home Assistant: ## {% linkable_title Configuration %} -To use Abode devices in your installation, add the following `abode` section to your `configuration.yaml` file: +To use Abode devices in your installation, +add the following `abode` section to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -38,7 +42,7 @@ abode: username: abode_username password: abode_password name: Abode Alarm System - polling: False + polling: false exclude: - 'ZW:0000000034' - 'RF:00000011' @@ -46,18 +50,44 @@ abode: - 'ZW:0000000022' ``` -Configuration variables: - -- **username** (*Required*): Username for your Abode account. -- **password** (*Required*): Password for your Abode account. -- **name** (*Optional*): The name for your alarm controller. -- **polling** (*Optional*): Enable polling if cloud push updating is less reliable. Will update the devices once every 30 seconds. Defaults to False. -- **exclude** (*Optional*): A list of devices to exclude from Home Assistant by their Abode `device_id` or `automation_id`, found within the component attributes. -- **lights** (*Optional*): A list of switch devices that Home Assistant should treat as lights by the switches Abode `device_id`, found within the component attributes. +{% configuration %} +username: + description: Username for your Abode account. + required: true + type: string +password: + description: Password for your Abode account. + required: true + type: string +name: + description: The name for your alarm controller. + required: false + type: string +polling: + description: > + Enable polling if cloud push updating is less reliable. + Will update the devices once every 30 seconds. + required: false + type: boolean + default: false +exclude: + description: > + A list of devices to exclude from Home Assistant by their Abode `device_id` + or `automation_id`, found within the component attributes. + required: false + type: list +lights: + description: > + A list of switch devices that Home Assistant should treat as lights by the + switches Abode `device_id`, found within the component attributes. + required: false + type: list +{% endconfiguration %} ## {% linkable_title Events %} -There are a number of events that can be triggered from Abode. They are grouped into the below events: +There are a number of events that can be triggered from Abode. +They are grouped into the below events: - **abode_alarm**: Fired when an alarm event is triggered from Abode. This includes Smoke, CO, Panic, and Burglar alarms. - **abode_alarm_end**: Fired when an alarm end event is triggered from Abode. @@ -80,13 +110,16 @@ Field | Description `date` | The date of the event in the format `MM/DD/YYYY`. `time` | The time of the event in the format `HH:MM AM`. -There is a unique list of known event_codes that can be found [here](https://github.com/MisterWil/abodepy/files/1262019/timeline_events.txt). +There is a unique list of known event_codes that can be found +[here](https://github.com/MisterWil/abodepy/files/1262019/timeline_events.txt). ## {% linkable_title Services %} ### {% linkable_title Service `change_setting` %} -Change settings on your Abode system. For a full list of settings and valid values, consult the [AbodePy settings section](https://github.com/MisterWil/abodepy/blob/master/README.rst#settings). +Change settings on your Abode system. +For a full list of settings and valid values, consult the +[AbodePy settings section](https://github.com/MisterWil/abodepy/blob/master/README.rst#settings). | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index e1af527f5f2..1d06c44254a 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -12,17 +12,25 @@ ha_category: Automation ha_release: 0.38 --- -The `alert` component is designed to notify you when problematic issues arise. For example, if the garage door is left open, the `alert` component can be used remind you of this by sending you repeating notifications at customizable intervals. This is also used for low battery sensors, water leak sensors, or any condition that may need your attention. +The `alert` component is designed to notify you when problematic issues arise. +For example, if the garage door is left open, the `alert` component can be used +remind you of this by sending you repeating notifications at customizable +intervals. This is also used for low battery sensors, +water leak sensors, or any condition that may need your attention. -Alerts will add an entity to the front end only when they are firing. This entity allows you to silence an alert until it is resolved. +Alerts will add an entity to the front end only when they are firing. +This entity allows you to silence an alert until it is resolved.

-When using the `alert` component, it is important that the time zone used for Home Assistant and the underlying operating system match. Failing to do so may result in multiple alerts being sent at the same time (such as when Home Assistant is set to the `America/Detroit` time zone but the operating system uses `UTC`). +When using the `alert` component, it is important that the time zone used for Home Assistant and the underlying operating system match. +Failing to do so may result in multiple alerts being sent at the same time (such as when Home Assistant is set to the `America/Detroit` time zone but the operating system uses `UTC`).

### {% linkable_title Basic Example %} -The `alert` component makes use of any of the `notifications` components. To setup the `alert` component, first, you must setup a `notification` component. Then, add the following to your configuration file: +The `alert` component makes use of any of the `notifications` components. To +setup the `alert` component, first, you must setup a `notification` component. +Then, add the following to your configuration file: ```yaml # Example configuration.yaml entry @@ -39,20 +47,65 @@ alert: - ryans_phone - kristens_phone ``` -Configuration variables: -- **name** (*Required*): The friendly name of the alert. -- **done_message** (*Optional*): A message sent after an alert transitions from `on` to `off`. Is only sent if an alert notification was sent for transitioning from `off` to `on`. -- **entity_id** (*Required*): The ID of the entity to watch. -- **state** (*Optional*): The problem condition for the entity. Defaults to `on`. -- **repeat** (*Required*): Number of minutes before the notification should be repeated. Can be either a number or a list of numbers. -- **can_acknowledge** (*Optional*): Allows the alert to be unacknowledgeable. Defaults to `true`. -- **skip_first** (*Optional*): Controls whether the notification should be sent immediately or after the first delay. Defaults to `false`. -- **notifiers** (*Required*): List of `notification` components to use for alerts. +{% configuration %} +name: + description: The friendly name of the alert. + required: true + type: string +done_message: + description: > + A message sent after an alert transitions from `on` to `off`. Is only sent + if an alert notification was sent for transitioning from `off` to `on`. + required: false + type: string +entity_id: + description: The ID of the entity to watch. + required: true + type: string +state: + description: The problem condition for the entity. + required: false + type: string + default: on +repeat: + description: > + Number of minutes before the notification should be repeated. + Can be either a number or a list of numbers. + required: true + type: [int, list] +can_acknowledge: + description: Allows the alert to be unacknowledgeable. + required: false + type: boolean + default: true +skip_first: + description: > + Controls whether the notification should be + sent immediately or after the first delay. + required: false + type: boolean + default: false +notifiers: + description: "List of `notification` components to use for alerts." + required: true + type: list +{% endconfiguration %} -In this example, the garage door status (`input_boolean.garage_door`) is watched and this alert will be triggered when its status is equal to `on`. This indicates that the door has been opened. Because the `skip_first` option was set to `True`, the first notification will not be delivered immediately. However, every 30 minutes, a notification will be delivered until either `input_boolean.garage_door` no longer has a state of `on` or until the alert is acknowledged using the Home Assistant frontend. +In this example, the garage door status (`input_boolean.garage_door`) is watched +and this alert will be triggered when its status is equal to `on`. +This indicates that the door has been opened. Because the `skip_first` option +was set to `True`, the first notification will not be delivered immediately. +However, every 30 minutes, a notification will be delivered until either +`input_boolean.garage_door` no longer has a state of `on` or until the alert is +acknowledged using the Home Assistant frontend. -For notifiers that require other parameters (such as `twilio_sms` which requires you specify a `target` parameter when sending the notification), you can use the `group` notification to wrap them for an alert. Simply create a `group` notification type with a single notification member (such as `twilio_sms`) specifying the required parameters other than `message` provided by the `alert` component: +For notifiers that require other parameters (such as `twilio_sms` which requires +you specify a `target` parameter when sending the notification), you can use the +`group` notification to wrap them for an alert. +Simply create a `group` notification type with a single notification member +(such as `twilio_sms`) specifying the required parameters other than `message` +provided by the `alert` component: ```yaml - platform: group @@ -77,7 +130,13 @@ freshwater_temp_alert: ### {% linkable_title Complex Alert Criteria %} -By design, the `alert` component only handles very simple criteria for firing. That is, it only checks if a single entity's state is equal to a value. At some point, it may be desirable to have an alert with a more complex criteria. Possibly, when a battery percentage falls below a threshold. Maybe you want to disable the alert on certain days. Maybe the alert firing should depend on more than one input. For all of these situations, it is best to use the alert in conjunction with a `Template Binary Sensor`. The following example does that. +By design, the `alert` component only handles very simple criteria for firing. +That is, it only checks if a single entity's state is equal to a value. At some +point, it may be desirable to have an alert with a more complex criteria. +Possibly, when a battery percentage falls below a threshold. Maybe you want to +disable the alert on certain days. Maybe the alert firing should depend on more +than one input. For all of these situations, it is best to use the alert in +conjunction with a `Template Binary Sensor`. The following example does that. ```yaml binary_sensor: @@ -97,11 +156,16 @@ alert: - kristens_phone ``` -This example will begin firing as soon as the entity `sensor.motion`'s `battery` attribute falls below 15. It will continue to fire until the battery attribute raises above 15 or the alert is acknowledged on the frontend. +This example will begin firing as soon as the entity `sensor.motion`'s `battery` +attribute falls below 15. It will continue to fire until the battery attribute +raises above 15 or the alert is acknowledged on the frontend. ### {% linkable_title Dynamic Notification Delay Times %} -It may be desirable to have the delays between alert notifications dynamically change as the alert continues to fire. This can be done by setting the `repeat` configuration key to a list of numbers rather than a single number. Altering the first example would look like the following. +It may be desirable to have the delays between alert notifications dynamically +change as the alert continues to fire. This can be done by setting the `repeat` +configuration key to a list of numbers rather than a single number. +Altering the first example would look like the following. ```yaml # Example configuration.yaml entry @@ -121,4 +185,8 @@ alert: - kristens_phone ``` -Now the first message will be sent after a 15 minute delay, the second will be sent 30 minutes after that, and a 60 minute delay will fall between every following notification. For example, if the garage door opens at 2:00, a notification will be sent at 2:15, 2:45, 3:45, 4:45, etc., continuing every 60 minutes. +Now the first message will be sent after a 15 minute delay, the second will be +sent 30 minutes after that, and a 60 minute delay will fall between every +following notification. +For example, if the garage door opens at 2:00, a notification will be +sent at 2:15, 2:45, 3:45, 4:45, etc., continuing every 60 minutes. diff --git a/source/_components/amcrest.markdown b/source/_components/amcrest.markdown index 220ab96d17f..fae4d0ff5e0 100644 --- a/source/_components/amcrest.markdown +++ b/source/_components/amcrest.markdown @@ -13,11 +13,13 @@ ha_iot_class: "Local Polling" ha_release: 0.49 --- -The `amcrest` camera platform allows you to integrate your [Amcrest](https://amcrest.com/) IP camera in Home Assistant. +The `amcrest` camera platform allows you to integrate your +[Amcrest](https://amcrest.com/) IP camera in Home Assistant. ## {% linkable_title Configuration %} -To enable your camera in your installation, add the following to your `configuration.yaml` file: +To enable your camera in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -41,31 +43,114 @@ amcrest: - ptz_preset ``` -Configuration variables: +{% configuration %} +host: + description: > + The IP address or hostname of your camera. + If using a hostname, make sure the DNS works as expected. + required: true + type: string +username: + description: The username for accessing your camera. + required: true + type: string +password: + description: The password for accessing your camera. + required: true + type: string +name: + description: > + This parameter allows you to override the name of your camera. In the case of multi-camera setups, + this is highly recommended as camera id number will be randomly changed at each reboot if a name is not allocated. + required: false + type: string + default: Amcrest Camera +port: + description: The port that the camera is running on. + required: false + type: int + default: 80 +resolution: + description: > + This parameter allows you to specify the camera resolution. + For a high resolution (1080/720p), specify the option `high`. + For VGA resolution (640x480p), specify the option `low`. + required: false + type: string + default: high +stream_source: + description: > + The data source for the live stream. `mjpeg` will use the camera's native + MJPEG stream, whereas `snapshot` will use the camera's snapshot API to + create a stream from still images. You can also set the `rtsp` option to + generate the streaming via RTSP protocol. + required: false + type: string + default: snapshot +ffmpeg_arguments: + description: > + Extra options to pass to ffmpeg, e.g., + image quality or video filter options. + required: false + type: string +authentication: + description: > + Defines which authentication method to use only when **stream_source** + is **mjpeg**. Currently, *aiohttp* only support *basic*. + required: false + type: string + default: basic +scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: int + default: 10 +sensors: + description: > + Conditions to display in the frontend. + The following conditions can be monitored: + required: false + type: list + default: None + keys: + motion_detector: + description: "Return `true`/`false` when a motion is detected." + sdcard: + description: Return the SD card usage by reporting the total and used space. + ptz_preset: + description: > + Return the number of PTZ preset positions + configured for the given camera. +switches: + description: > + Switches to display in the frontend. + The following switches can be monitored: + required: false + type: list + default: None + keys: + motion_detection: + description: Enable/disable motion detection setting. + motion_recording: + description: Enable/disable recording on motion detection setting. +{% endconfiguration %} -- **host** (*Required*): The IP address or hostname of your camera. If using a hostname, make sure the DNS works as expected. -- **username** (*Required*): The username for accessing your camera. -- **password** (*Required*): The password for accessing your camera. -- **name** (*Optional*): This parameter allows you to override the name of your camera. The default is "Amcrest Camera". In the case of multi-camera setups, this is highly recommended as camera id number will be randomly changed at each reboot if a name is not allocated. -- **port** (*Optional*): The port that the camera is running on. The default is 80. -- **resolution** (*Optional*): This parameter allows you to specify the camera resolution. For a high resolution (1080/720p), specify the option `high`. For VGA resolution (640x480p), specify the option `low`. If omitted, it defaults to *high*. -- **stream_source** (*Optional*): The data source for the live stream. `mjpeg` will use the camera's native MJPEG stream, whereas `snapshot` will use the camera's snapshot API to create a stream from still images. You can also set the `rtsp` option to generate the streaming via RTSP protocol. If omitted, it defaults to *snapshot*. -- **ffmpeg_arguments**: (*Optional*): Extra options to pass to ffmpeg, e.g., image quality or video filter options. -- **authentication**: (*Optional*): Defines which authentication method to use only when **stream_source** is **mjpeg**. Currently, *aiohttp* only support *basic*. It defaults to *basic*. -- **scan_interval** (*Optional*): Defines the update interval of the sensor in seconds. The default is 10 seconds. -- **sensors** array (*Optional*): Conditions to display in the frontend. By default, *none* of the conditions are enabled. The following conditions can be monitored. - - **motion_detector**: Return True/False when a motion is detected - - **sdcard**: Return the SD card usage by reporting the total and used space - - **ptz_preset**: Return the number of PTZ preset positions configured for the given camera -- **switches** array (*Optional*): Switches to display in the frontend. By default, *none* of the switches are shown. The following switches can be monitored. - - **motion_detection**: Enable/disable motion detection setting - - **motion_recording**: Enable/disable recording on motion detection setting +**Note:** Amcrest cameras with newer firmware no longer have the ability to +stream `high` definition video with MJPEG encoding. You may need to use `low` +resolution stream or the `snapshot` stream source instead. If the quality seems +too poor, lower the `Frame Rate (FPS)` and max out the `Bit Rate` settings in +your camera's configuration manager. If you defined the *stream_source* to +**mjpeg**, make sure your camera supports *Basic* HTTP authentication. +Newer Amcrest firmware may not work, then **rtsp** is recommended instead. -**Note:** Amcrest cameras with newer firmware no longer have the ability to stream `high` definition video with MJPEG encoding. You may need to use `low` resolution stream or the `snapshot` stream source instead. If the quality seems too poor, lower the `Frame Rate (FPS)` and max out the `Bit Rate` settings in your camera's configuration manager. If you defined the *stream_source* to **mjpeg**, make sure your camera supports *Basic* HTTP authentication. Newer Amcrest firmware may not work, then **rtsp** is recommended instead. +**Note:** If you set the `stream_source` option to `rtsp`, +make sure to follow the steps mentioned at [FFMPEG](/components/ffmpeg/) +documentation to install the `ffmpeg`. -**Note:** If you set the `stream_source` option to `rtsp`, make sure to follow the steps mentioned at -[FFMPEG](/components/ffmpeg/) documentation to install the `ffmpeg`. +Finish its configuration by visiting the +[Amcrest sensor page](/components/sensor.amcrest/) or +[Amcrest camera page](/components/camera.amcrest/). -Finish its configuration by visiting the [Amcrest sensor page](/components/sensor.amcrest/) or [Amcrest camera page](/components/camera.amcrest/). - -To check if your Amcrest camera is supported/tested, visit the [supportability matrix](https://github.com/tchellomello/python-amcrest#supportability-matrix) link from the `python-amcrest` project. +To check if your Amcrest camera is supported/tested, visit the +[supportability matrix](https://github.com/tchellomello/python-amcrest#supportability-matrix) +link from the `python-amcrest` project. diff --git a/source/_components/automation.markdown b/source/_components/automation.markdown index 658c0ebc63c..57a11fe8115 100644 --- a/source/_components/automation.markdown +++ b/source/_components/automation.markdown @@ -11,7 +11,8 @@ logo: home-assistant.png ha_category: Automation --- -Please see the [docs section](/docs/automation/) for in-depth documentation on how to use the automation component. +Please see the [docs section](/docs/automation/) for in-depth +documentation on how to use the automation component. Starting with 0.28 your automation rules can be controlled with the frontend. @@ -19,12 +20,16 @@ Starting with 0.28 your automation rules can be controlled with the frontend.

-This allows one to reload the automation without restarting Home Assistant itself. If you don't want to see the automation rule in your frontend use `hide_entity: True` to hide it. You can also use `initial_state: 'off'` so that the automation is not automatically turned on after a Home Assistant reboot. +This allows one to reload the automation without restarting Home Assistant +itself. If you don't want to see the automation rule in your frontend use +`hide_entity: true` to hide it. +You can also use `initial_state: 'off'` so that the automation +is not automatically turned on after a Home Assistant reboot. ```yaml automation: - alias: Door alarm - hide_entity: True + hide_entity: true initial_state: 'off' trigger: - platform: state diff --git a/source/_components/binary_sensor.hikvision.markdown b/source/_components/binary_sensor.hikvision.markdown index 97c63757163..d77e38d757c 100644 --- a/source/_components/binary_sensor.hikvision.markdown +++ b/source/_components/binary_sensor.hikvision.markdown @@ -13,22 +13,36 @@ ha_release: 0.35 ha_iot_class: "Local Push" --- -The Hikvision Binary Sensor is a platform that parses the event stream of a [Hikvision IP Camera or NVR](http://www.hikvision.com/) and presents the camera/nvr events to Home Assistant as binary sensors with either an "off" or "on" state. +The Hikvision Binary Sensor is a platform that parses the event stream of a +[Hikvision IP Camera or NVR](http://www.hikvision.com/) and presents the +camera/nvr events to Home Assistant as binary sensors with either an "off" or +"on" state. -The platform will automatically add all sensors to Home Assistant that are configured within the camera/nvr interface to "Notify the surveillance center" as a trigger. If you would like to hide a sensor type you can do so by either unchecking "Notify the surveillance center" in the camera configuration or by using the "ignored" customize option detailed below. +The platform will automatically add all sensors to Home Assistant that are +configured within the camera/nvr interface to "Notify the surveillance center" +as a trigger. If you would like to hide a sensor type you can do so by either +unchecking "Notify the surveillance center" in the camera configuration or by +using the "ignored" customize option detailed below.

-In order for the sensors to work the hikvision user must have the 'Remote: Notify Surveillance Center/Trigger Alarm Output' permission which can be enabled from the user management section of the web interface. Also the 'WEB Authentication' needs to be set to 'digest/basic' in the security/authentication section. +In order for the sensors to work the hikvision user must have the 'Remote: Notify Surveillance Center/Trigger Alarm Output' permission which can be enabled from the user management section of the web interface. +Also the 'WEB Authentication' needs to be set to 'digest/basic' in the security/authentication section.

-For example, if you configure a camera with the name "Front Porch" that has motion detection and line crossing events enabled to notify the surveillance center the following binary sensors will be added to Home Assistant: +For example, if you configure a camera with the name "Front Porch" that has +motion detection and line crossing events enabled to notify the surveillance +center the following binary sensors will be added to Home Assistant: ```text binary_sensor.front_porch_motion binary_sensor.front_port_line_crossing ``` -When used with a NVR device the sensors will be appended with the channel number they represent. For example, if you configure an NVR with the name "Home" that supports 2 cameras with motion detection and line crossing events enabled to notify the surveillance center the following binary sensors will be added to Home Assistant: +When used with a NVR device the sensors will be appended with the channel number +they represent. For example, +if you configure an NVR with the name "Home" that supports 2 cameras with +motion detection and line crossing events enabled to notify the surveillance +center the following binary sensors will be added to Home Assistant: ```text binary_sensor.home_motion_1 @@ -37,7 +51,8 @@ binary_sensor.home_line_crossing_1 binary_sensor.home_line_crossing_2 ``` -This platform should work with all Hikvision cameras and nvrs, and has been confirmed to work with the following models: +This platform should work with all Hikvision cameras and nvrs, +and has been confirmed to work with the following models: - DS-2CD3132-I - DS-2CD2232-I5 @@ -46,7 +61,8 @@ This platform should work with all Hikvision cameras and nvrs, and has been conf - DS-2CD2142FWD-I - DS-2CD2155FWD-IS -To enable this sensor, the following lines are required in your `configuration.yaml` file: +To enable this sensor, +add the following lines are required in your `configuration.yaml` file: ```yaml binary_sensor: @@ -56,17 +72,56 @@ binary_sensor: password: pass ``` -Configuration options for a Hikvision Sensor: - -- **host** (*Required*): The IP address of the camera you would like to connect to. -- **username** (*Required*): The username to authenticate with. -- **password** (*Required*): The password to authenticate with. -- **name** (*Optional*): The name you'd like to give the camera in Home Assistant, defaults to name defined in the camera. -- **port** (*Optional*): The port to connect to the camera on, defaults to 80. -- **ssl** (*Optional*): True if you want to connect with https. Be sure to set the port also. -- **customize** (*Optional*): This attribute contains sensor-specific override values. Only sensor name needs defined: - - **ignored** (*Optional*): Ignore this sensor completely. It won't be shown in the Web Interface and no events are generated for it. - - **delay** (*Optional*): Specify the delay to wait after a sensor event ends before notifying Home Assistant. This is useful to catch multiple quick trips in one window without the state toggling on and off. The default delay is 5 seconds. +{% configuration %} +host: + description: The IP address of the camera you would like to connect to. + required: true + type: string +username: + description: The username to authenticate with. + required: true + type: string +password: + description: The password to authenticate with. + required: true + type: string +name: + description: > + The name you would like to give the camera in Home Assistant, + defaults to name defined in the camera. + required: false + type: string +port: + description: The port to connect to the camera on. + required: false + type: int + default: 80 +ssl: + description: "`true` if you want to connect with https. Be sure to set the port also." + required: false + type: boolean +customize: + description: > + This attribute contains sensor-specific override values. + Only sensor name needs defined: + required: false + type: map + keys: + ignored: + description: > + Ignore this sensor completely. It won't be shown in + the Web Interface and no events are generated for it. + required: false + type: boolean + delay: + description: > + Specify the delay to wait after a sensor event ends before notifying + Home Assistant in seconds. This is useful to catch multiple quick trips + in one window without the state toggling on and off. + required: false + type: int + default: 5 +{% endconfiguration %} Supported sensor/event types are: @@ -87,36 +142,38 @@ Supported sensor/event types are: - Face Detection - Scene Change Detection -Example of a configuration in your `configuration.yaml` that utilizes the customize options for a camera: +Example of a configuration in your `configuration.yaml` +that utilizes the customize options for a camera: ```yaml binary_sensor: - platform: hikvision host: 192.168.X.X port: 80 - ssl: False + ssl: false username: user password: pass customize: motion: delay: 30 line_crossing: - ignored: True + ignored: true ``` -Example of a configuration in your `configuration.yaml` that utilizes the customize options for a nvr: +Example of a configuration in your `configuration.yaml` +that utilizes the customize options for a nvr: ```yaml binary_sensor: - platform: hikvision host: 192.168.X.X port: 80 - ssl: False + ssl: false username: user password: pass customize: motion_1: delay: 30 field_detection_2: - ignored: True + ignored: true ``` diff --git a/source/_components/binary_sensor.ihc.markdown b/source/_components/binary_sensor.ihc.markdown index da5aac7615e..31d14bb69fb 100644 --- a/source/_components/binary_sensor.ihc.markdown +++ b/source/_components/binary_sensor.ihc.markdown @@ -13,19 +13,22 @@ ha_release: 0.62 ha_iot_class: "Local Push" --- -Before you can use the IHC Binary Sensor platform, you must setup the [IHC Component](/components/ihc/) +Before you can use the IHC Binary Sensor platform, +you must setup the [IHC Component](/components/ihc/). -When auto setup is enabled the following products will be found in the IHC project and setup as binary sensors: +When auto setup is enabled the following products will +be found in the IHC project and setup as binary sensors: -* Dataline magnet contacts -* Dataline Pir sensors -* Dataline Pir sensors with twilight detection -* Dataline Pir alarm sensor -* Dataline smoke detector -* Dataline gas detector -* Dataline light sensor +- Dataline magnet contacts +- Dataline Pir sensors +- Dataline Pir sensors with twilight detection +- Dataline Pir alarm sensor +- Dataline smoke detector +- Dataline gas detector +- Dataline light sensor -To manually configure IHC Binary Sensors insert this section in your configuration: +To manually configure IHC Binary Sensors +insert this section in your configuration: ```yaml binary_sensor: @@ -52,18 +55,20 @@ binary_sensors: inverting: description: If True the sensor will be inverted. required: false - type: bool + type: boolean default: false name: description: The name of the component required: false type: string type: - description: The binary sensor type. See [Home Assistant binary sensor](/components/binary_sensor/) for available types. + description: > + The binary sensor type. + See [Home Assistant binary sensor](/components/binary_sensor/) + for available types. required: false type: string {% endconfiguration %} -The resource id should be an id of a boolean IHC resource. -For more information about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup) - +The resource id should be an id of a boolean IHC resource. For more information +about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup). diff --git a/source/_components/binary_sensor.iss.markdown b/source/_components/binary_sensor.iss.markdown index 0d4e4276b30..f9b0da08de8 100644 --- a/source/_components/binary_sensor.iss.markdown +++ b/source/_components/binary_sensor.iss.markdown @@ -13,11 +13,16 @@ ha_release: 0.36 redirect_from: /components/sensor.iss/ --- -The `iss` platform uses the [Open Notify API](http://open-notify.org/Open-Notify-API/ISS-Location-Now/) to let you know if the station is above your home location. This means that ISS is 10° above the horizon of your home. +The `iss` platform uses the +[Open Notify API](http://open-notify.org/Open-Notify-API/ISS-Location-Now/) +to let you know if the station is above your home location. +This means that ISS is 10° above the horizon of your home. -You can check in the attributes of the sensor to see the timestamp for the next rise of the station, its current coordinates, and the number of people in space. +You can check in the attributes of the sensor to see the timestamp for the next +rise of the station, its current coordinates, and the number of people in space. -To add ISS binary sensor to your installation, add the following to your `configuration.yaml` file: +To add ISS binary sensor to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -34,13 +39,14 @@ show_on_map: {% endconfiguration %}

-If you set `show_on_map` `True` then the location attributes are named `latitude` and `longitude`. The default name of the location attributes is `lat` and `long` to avoid showing them on the map. +If you set `show_on_map: true` then the location attributes are named `latitude` and `longitude`. +The default name of the location attributes is `lat` and `long` to avoid showing them on the map.

- ### {% linkable_title Show position on map with camera platform %} -The [generic camera platform](/components/camera.mjpeg/) offers the possibility to show the location of the ISS on Google Maps. +The [generic camera platform](/components/camera.mjpeg/) offers +the possibility to show the location of the ISS on Google Maps. {% raw %} ```yaml diff --git a/source/_components/binary_sensor.mqtt.markdown b/source/_components/binary_sensor.mqtt.markdown index 8d4b8b38e27..114c974cbbf 100644 --- a/source/_components/binary_sensor.mqtt.markdown +++ b/source/_components/binary_sensor.mqtt.markdown @@ -13,15 +13,32 @@ ha_release: 0.9 ha_iot_class: "depends" --- -The `mqtt` binary sensor platform uses an MQTT message payload to set the binary sensor to one of two states: `on` or `off`. +The `mqtt` binary sensor platform uses an MQTT message payload +to set the binary sensor to one of two states: `on` or `off`. -The binary sensor state will be updated only after a new message is published on `state_topic` matching `payload_on` or `payload_off`. If these messages are published with the `retain` flag set, the binary sensor will receive an instant state update after subscription and Home Assistant will display the correct state on startup. Otherwise, the initial state displayed in Home Assistant will be `unknown`. +The binary sensor state will be updated only after a new message is published on +`state_topic` matching `payload_on` or `payload_off`. +If these messages are published with the `retain` flag set, +the binary sensor will receive an instant state update after subscription and +Home Assistant will display the correct state on startup. +Otherwise, the initial state displayed in Home Assistant will be `unknown`. ## {% linkable_title Configuration %} -The `mqtt` binary sensor platform optionally supports an `availability_topic` to receive online and offline messages (birth and LWT messages) from the MQTT device. During normal operation, if the MQTT cover device goes offline (i.e., publishes `payload_not_available` to `availability_topic`), Home Assistant will display the binary sensor as `unavailable`. If these messages are published with the `retain` flag set, the binary sensor will receive an instant update after subscription and Home Assistant will display the correct availability state of the binary sensor when Home Assistant starts up. If the `retain` flag is not set, Home Assistant will display the binary sensor as `unavailable` when Home Assistant starts up. If no `availability_topic` is defined, Home Assistant will consider the MQTT device to be available. +The `mqtt` binary sensor platform optionally supports an `availability_topic` to +receive online and offline messages (birth and LWT messages) from the MQTT +device. During normal operation, if the MQTT cover device goes offline +(i.e., publishes `payload_not_available` to `availability_topic`), Home +Assistant will display the binary sensor as `unavailable`. If these messages are +published with the `retain` flag set, the binary sensor will receive an instant +update after subscription and Home Assistant will display the correct +availability state of the binary sensor when Home Assistant starts up. +If the `retain` flag is not set, Home Assistant will display the binary sensor +as `unavailable` when Home Assistant starts up. If no `availability_topic` +is defined, Home Assistant will consider the MQTT device to be available. -To use an MQTT binary sensor in your installation, add the following to your `configuration.yaml` file: +To use an MQTT binary sensor in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -51,7 +68,11 @@ payload_off: type: string default: "OFF" availability_topic: - description: "The MQTT topic subscribed to receive birth and LWT messages from the MQTT device. If `availability_topic` is not defined, the binary sensor availability state will always be `available`. If `availability_topic` is defined, the binary sensor availability state will be `unavailable` by default." + description: > + The MQTT topic subscribed to receive birth and LWT messages from the MQTT + device. If `availability_topic` is not defined, the binary sensor availability + state will always be `available`. If `availability_topic` is defined, + the binary sensor availability state will be `unavailable` by default. required: false type: string payload_available: @@ -70,32 +91,41 @@ qos: type: integer default: 0 unique_id: - description: "An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception." + description: > + An ID that uniquely identifies this sensor. If two sensors have + the same unique ID, Home Assistant will raise an exception. required: false type: string device_class: - description: "The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend." + description: > + The [type/class](/components/binary_sensor/) of + the sensor to set the icon in the frontend. required: false type: string value_template: - description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload." + description: > + Defines a [template](/docs/configuration/templating/#processing-incoming-data) + to extract a value from the payload. required: false type: string force_update: - description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history. + description: > + Sends update events even if the value has not changed. + Useful if you want to have meaningful value graphs in history. reqired: false type: boolean - default: False + default: false {% endconfiguration %} - ## {% linkable_title Examples %} In this section, you will find some real-life examples of how to use this sensor. ### {% linkable_title Full configuration %} -To test, you can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. To set the state of the binary sensor manually: +To test, you can use the command line tool `mosquitto_pub` shipped with +`mosquitto` or the `mosquitto-clients` package to send MQTT messages. +To set the state of the binary sensor manually: ```bash $ mosquitto_pub -h 127.0.0.1 -t home-assistant/window/contact -m "OFF" @@ -123,7 +153,14 @@ binary_sensor: ### {% linkable_title Get the state of a device with ESPEasy %} -Assuming that you have flashed your ESP8266 unit with [ESPEasy](https://github.com/letscontrolit/ESPEasy). Under "Config" is a name ("Unit Name:") set for your device (here it's "bathroom"). A configuration for a "Controller" for MQTT with the protocol "OpenHAB MQTT" is present and the entries ("Controller Subscribe:" and "Controller Publish:") are adjusted to match your needs. In this example, the topics are prefixed with "home". Also, add a "Switch Input" in the "Devices" tap with the name "switch" and "button" as value. +Assuming that you have flashed your ESP8266 unit with +[ESPEasy](https://github.com/letscontrolit/ESPEasy). +Under "Config" is a name ("Unit Name:") set for your device +(here it's "bathroom"). A configuration for a "Controller" for MQTT with the +protocol "OpenHAB MQTT" is present and the entries ("Controller Subscribe:" and +"Controller Publish:") are adjusted to match your needs. +In this example, the topics are prefixed with "home". Also, add a "Switch Input" +in the "Devices" tap with the name "switch" and "button" as value. As soon as the unit is online, you will get the state of the attached button. diff --git a/source/_components/binary_sensor.netatmo.markdown b/source/_components/binary_sensor.netatmo.markdown index da2f8ab1fe1..44be87ffe53 100644 --- a/source/_components/binary_sensor.netatmo.markdown +++ b/source/_components/binary_sensor.netatmo.markdown @@ -14,13 +14,19 @@ ha_release: 0.31 ### {% linkable_title Basic Configuration %} -The `netatmo` binary sensor platform is consuming the information provided by a [Netatmo](https://www.netatmo.com) camera. This component allows you to get the latest event seen by the camera. +The `netatmo` binary sensor platform is consuming the information provided by a +[Netatmo](https://www.netatmo.com) camera. +This component allows you to get the latest event seen by the camera. -To enable the Netatmo binary sensor, you have to set up [netatmo](/components/netatmo/), this will use discovery to add your binary sensor. +To enable the Netatmo binary sensor, you have to set up +[netatmo](/components/netatmo/), +this will use discovery to add your binary sensor. ### {% linkable_title Advanced configuration %} -If you want to select a specific sensor, set discovery to False for [netatmo](/components/netatmo/) and add the following lines to your `configuration.yaml`: +If you want to select a specific sensor, +set discovery to `false` for [netatmo](/components/netatmo/) +and add the following lines to your `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -41,20 +47,36 @@ binary_sensor: - Outdoor vehicle ``` -Configuration variables: +{% configuration %} +home: + description: Will use the cameras of this home only. + required: false + type: string +timeout: + description: > + The Welcome/Presence binary sensors will + stay on for X seconds after detection. + required: false + type: int + default: 90 +cameras: + description: List of cameras entity IDs to display. + required: false + type: list +welcome_sensors: + description: > + List of monitored conditions. Possible values are + 'Someone known', 'Someone unknown' and 'Motion'. + required: false + type: list +presence_sensors: + description: > + List of monitored conditions. Possible values are 'Outdoor motion', + 'Outdoor human', 'Outdoor animal' and 'Outdoor vehicle'. + required: false + type: list +{% endconfiguration %} -- **home** (*Optional*): Will use the cameras of this home only. -- **timeout** (*Optional*): The Welcome/Presence binary sensors will stay on for X seconds after detection. (default: 90) -- **cameras** array (*Optional*): Cameras to use. Multiple entities allowed. - - 'camera_name': Name of the camera to display. -- **welcome_sensors** array (*Optional*): List of monitored conditions. - - 'Someone known' - - 'Someone unknown' - - 'Motion' -- **presence_sensors** array (*Optional*): List of monitored conditions. - - 'Outdoor motion' - - 'Outdoor human' - - 'Outdoor animal' - - 'Outdoor vehicle' - -If **home** and **cameras** is not provided, all cameras will be used. If multiple cameras are available then each monitored conditions will create a specific sensor for each camera +If **home** and **cameras** is not provided, all cameras will be used. +If multiple cameras are available then each monitored conditions +will create a specific sensor for each camera diff --git a/source/_components/binary_sensor.pilight.markdown b/source/_components/binary_sensor.pilight.markdown index ef71c754602..3761bd06631 100644 --- a/source/_components/binary_sensor.pilight.markdown +++ b/source/_components/binary_sensor.pilight.markdown @@ -13,11 +13,16 @@ ha_release: 0.44 ha_iot_class: "Local Polling" --- -The `pilight` binary sensor platform implement the [pilight hub](/components/pilight/) binary sensor functionality. Two type of Pilight binary sensor configuration available. A normal sensor which send the on and off state cyclical and a trigger sensor which send only a trigger when an event happened (for example lots of cheap PIR motion detector). +The `pilight` binary sensor platform implement the +[pilight hub](/components/pilight/) binary sensor functionality. +Two type of Pilight binary sensor configuration available. A normal sensor which +send the on and off state cyclical and a trigger sensor which send only a +trigger when an event happened (for example lots of cheap PIR motion detector). ## {% linkable_title Configuration %} -To enable a Pilight binary sensor in your installation, add the following to your `configuration.yaml` file: +To enable a Pilight binary sensor in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -26,15 +31,41 @@ binary_sensor: variable: 'state' ``` -Configuration variables: - -- **variable** (*Required*): The variable name in the data stream that defines the sensor value. -- **payload** (*Required*): Message payload identifiers. Only if all identifiers are matched the sensor value is set. -- **name** (*Optional*): Name of the sensor. -- **payload_on** (*Optional*): Variable `on` value. The component will recognize this as logical '1'. -- **payload_off** (*Optional*): Variable `off` value. The component will recognize this as logical '0'. -- **disarm_after_trigger:** (*Optional*): Configure sensor as trigger type. -- **reset_delay_sec** (*Optional*): Seconds before the sensor is disarmed if `disarm_after_trigger` is set to true. Default is 30 seconds. +{% configuration %} +variable: + description: The variable name in the data stream that defines the sensor value. + required: true + type: string +payload: + description: > + Message payload identifiers. + Only if all identifiers are matched the sensor value is set. + required: true + type: string +name: + description: Name of the sensor. + required: false + type: string +payload_on: + description: "Variable `on` value. The component will recognize this as logical '1'." + required: false + type: string +payload_off: + description: "Variable `off` value. The component will recognize this as logical '0'." + required: false + type: string +disarm_after_trigger: + description: Configure sensor as trigger type. + required: false + type: boolean +reset_delay_sec: + description: > + Seconds before the sensor is disarmed if + `disarm_after_trigger` is set to true. + required: false + type: int + default: 30 +{% endconfiguration %} A full configuration example could look like this: diff --git a/source/_components/binary_sensor.random.markdown b/source/_components/binary_sensor.random.markdown index 3fdc95eb617..dece1477fae 100644 --- a/source/_components/binary_sensor.random.markdown +++ b/source/_components/binary_sensor.random.markdown @@ -13,8 +13,9 @@ ha_iot_class: "Local Polling" ha_release: 0.57 --- - -The `random` binary sensor platform is creating random states (`True`, 1, `on` or `False`, 0, `off`). This can be useful if you want to test automation rules. It generates a new state every time it is polled. +The `random` binary sensor platform is creating random states (`true`, 1, `on` +or `false`, 0, `off`). This can be useful if you want to test automation rules. +It generates a new state every time it is polled. ## {% linkable_title Configuration %} @@ -33,5 +34,6 @@ name: type: string {% endconfiguration %} -See the [entity component options](/docs/configuration/platform_options/) to control how often the main component polls the random binary sensor. The default is 30 seconds. - +See the [entity component options](/docs/configuration/platform_options/) +to control how often the main component polls the random binary sensor. +The default is 30 seconds. diff --git a/source/_components/binary_sensor.rest.markdown b/source/_components/binary_sensor.rest.markdown index 488643e18c4..7c36530f59a 100644 --- a/source/_components/binary_sensor.rest.markdown +++ b/source/_components/binary_sensor.rest.markdown @@ -13,10 +13,15 @@ ha_release: "0.10" ha_iot_class: "Local Polling" --- +The `rest` binary sensor platform is consuming a given endpoint which is exposed +by a +[RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) +of a device, an application, or a web service. +The binary sensor has support for GET and POST requests. -The `rest` binary sensor platform is consuming a given endpoint which is exposed by a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) of a device, an application, or a web service. The binary sensor has support for GET and POST requests. - -The JSON messages can contain different values like `1`, `"1"`, `TRUE`, `true`, `on`, or `open`. If the value is nested then use a [template](/docs/configuration/templating/#processing-incoming-data). +The JSON messages can contain different values like `1`, `"1"`, +`TRUE`, `true`, `on`, or `open`. If the value is nested then use a +[template](/docs/configuration/templating/#processing-incoming-data). ```json { @@ -28,7 +33,8 @@ The JSON messages can contain different values like `1`, `"1"`, `TRUE`, `true`, } ``` -To enable this sensor, add the following lines to your `configuration.yaml` file for a GET request: +To enable this sensor, +add the following lines to your `configuration.yaml` file for a GET request: ```yaml # Example configuration.yaml entry @@ -64,11 +70,15 @@ name: type: string default: REST Binary Sensor device_class: - description: "The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend." + description: > + The [type/class](/components/binary_sensor/) of + the sensor to set the icon in the frontend. required: false type: string value_template: - description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value." + description: > + Defines a [template](/docs/configuration/templating/#processing-incoming-data) + to extract the value. required: false type: template payload: @@ -79,9 +89,9 @@ verify_ssl: description: Verify the certification of the endpoint. required: false type: boolean - default: True + default: true authentication: - description: Type of the HTTP authentication. `basic` or `digest`. + description: "Type of the HTTP authentication. `basic` or `digest`." required: false type: string username: @@ -108,7 +118,9 @@ In this section you find some real-life examples of how to use this sensor. ### {% linkable_title aREST sensor %} -Instead of using an [aREST](/components/binary_sensor.arest/) binary sensor, you could retrieve the value of a device supporting aREST directly with a REST binary sensor. +Instead of using an [aREST](/components/binary_sensor.arest/) binary sensor, +you could retrieve the value of a device supporting +aREST directly with a REST binary sensor. ```yaml binary_sensor: @@ -136,7 +148,8 @@ binary_sensor: Content-Type: application/json ``` -The headers will contain all relevant details. This will also give you the ability to access endpoints that are protected by tokens. +The headers will contain all relevant details. This will also give +you the ability to access endpoints that are protected by tokens. ```bash Content-Length: 1024 diff --git a/source/_components/binary_sensor.rfxtrx.markdown b/source/_components/binary_sensor.rfxtrx.markdown index 0aaefbad7d6..ff54c0a0e2b 100644 --- a/source/_components/binary_sensor.rfxtrx.markdown +++ b/source/_components/binary_sensor.rfxtrx.markdown @@ -11,23 +11,35 @@ logo: rfxtrx.png ha_category: Binary Sensor --- -The `rfxtrx` platform support binary sensors that communicate in the frequency range of 433.92 MHz. The rfxtrx binary sensor component provides support for them. +The `rfxtrx` platform support binary sensors that +communicate in the frequency range of 433.92 MHz. +The rfxtrx binary sensor component provides support for them. -Many cheap sensors available on the web today are based on a particular RF chip called *PT-2262*. Depending on the running firmware on the RFXcom box, some of them may be recognized under the X10 protocol but most of them are recognized under the *Lighting4* protocol. The rfxtrx binary sensor component provides some special options for them, while other rfxtrx protocols should work too. +Many cheap sensors available on the web today are based on a particular RF chip +called *PT-2262*. Depending on the running firmware on the RFXcom box, some of +them may be recognized under the X10 protocol but most of them are recognized +under the *Lighting4* protocol. The rfxtrx binary sensor component provides +some special options for them, while other rfxtrx protocols should work too. # Setting up your devices -Once you have set up your [rfxtrx hub](/components/rfxtrx/), the easiest way to find your binary sensors is to add this to your `configuration.yaml`: + +Once you have set up your [rfxtrx hub](/components/rfxtrx/), the easiest way +to find your binary sensors is to add this to your `configuration.yaml`: ```yaml # Example configuration.yaml entry binary_sensor: platform: rfxtrx - automatic_add: True + automatic_add: true ``` -Open your local home-assistant web UI and go to the "states" page. Then make sure to trigger your sensor. You should see a new entity appear in the *Current entities* list, starting with "binary_sensor." and some hexadecimal digits. Those hexadecimal digits are your device id. +Open your local home-assistant web UI and go to the "states" page. +Then make sure to trigger your sensor. You should see a new entity +appear in the *Current entities* list, starting with "binary_sensor." +and some hexadecimal digits. Those hexadecimal digits are your device id. -For example: "binary_sensor.0913000022670e013b70". Here your device id is `0913000022670e013b70`. Then you should update your configuration to: +For example: "binary_sensor.0913000022670e013b70". Here your device id +is `0913000022670e013b70`. Then you should update your configuration to: ```yaml # Example configuration.yaml entry @@ -45,20 +57,28 @@ Configuration variables: - **off_delay** (*Optional*): For sensors that only sends 'On' state updates, this variable sets a delay after which the sensor state will be updated back to 'Off'.

-This component and the [rfxtrx switch](/components/switch/rfxtrx/) can steal each other's devices when setting the `automatic_add` configuration parameter to `true`. Set `automatic_add` only when you have some devices to add to your installation, otherwise leave it to `False`. +This component and the [rfxtrx switch](/components/switch/rfxtrx/) can steal each other's devices when setting the `automatic_add` configuration parameter to `true`. +Set `automatic_add` only when you have some devices to add to your installation, otherwise leave it to `false`.

-If a device ID consists of only numbers, please make sure to surround it with quotes. +If a device ID consists of only numbers, please make sure to surround it with quotes. This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise.

-Binary sensors have only two states - "on" and "off". Many door or window opening sensors will send a signal each time the door/window is open or closed. However, depending on their hardware or on their purpose, some sensors are only able to signal their "on" state: +Binary sensors have only two states - "on" and "off". Many door or window +opening sensors will send a signal each time the door/window is open or closed. +However, depending on their hardware or on their purpose, +some sensors are only able to signal their "on" state: -- Most motion sensors send a signal each time they detect motion. They stay "on" for a few seconds and go back to sleep, ready to signal other motion events. Usually, they do not send a signal when they go back to sleep. +- Most motion sensors send a signal each time they detect motion. They stay "on" for a few seconds and go back to sleep, ready to signal other motion events. Usually, they do not send a signal when they go back to sleep. - Some doorbells may also only send "on" signals when their toggle switch is pressed, but no "off" signal when the switch is released. -For those devices, use the *off_delay* parameter. It defines a delay after which a device will go back to an "Off" state. That "Off" state will be fired internally by Home Assistant, just as if the device fired it by itself. If a motion sensor can only send signals once every 5 seconds, sets the *off_delay* parameter to *seconds: 5*. +For those devices, use the *off_delay* parameter. +It defines a delay after which a device will go back to an "Off" state. +That "Off" state will be fired internally by Home Assistant, just as if +the device fired it by itself. If a motion sensor can only send signals +once every 5 seconds, sets the *off_delay* parameter to *seconds: 5*. Example configuration: @@ -66,7 +86,7 @@ Example configuration: # Example configuration.yaml entry binary_sensor: platform: rfxtrx - automatic_add: True + automatic_add: true devices: 091300006ca2c6001080: name: motion_hall @@ -77,15 +97,22 @@ binary_sensor: ## Options for PT-2262 devices under the Lighting4 protocol -When a data packet is transmitted by a PT-2262 device using the Lighting4 protocol, there is no way to automatically extract the device identifier and the command from the packet. Each device has its own id/command length combination and the fields lengths are not included in the data. One device that sends 2 different commands will be seen as 2 devices on Home Assistant. For such cases, the following options are available in order to circumvent the problem: +When a data packet is transmitted by a PT-2262 device using the Lighting4 +protocol, there is no way to automatically extract the device identifier and the +command from the packet. Each device has its own id/command length combination +and the fields lengths are not included in the data. One device that sends 2 +different commands will be seen as 2 devices on Home Assistant. For such cases, +the following options are available in order to circumvent the problem: - **data_bits** (*Optional*): Defines how many bits are used for commands inside the data packets sent by the device. - **command_on** (*Optional*): Defines the data bits value that is sent by the device upon an 'On' command. - **command_off** (*Optional*): Defines the data bits value that is sent by the device upon an 'Off' command. -Let's try to add a new PT-2262 sensor using the "automatic_add" option and have a look at Home Assistant system log. +Let's try to add a new PT-2262 sensor using the "automatic_add" +option and have a look at Home Assistant system log. -Have your sensor trigger the "On" state for the first time. Some messages will appear: +Have your sensor trigger the "On" state for the first time. +Some messages will appear: ```text INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 0913000022670e013970 (Device_id: 22670e Class: LightingDevice Sub: 0) @@ -93,21 +120,27 @@ INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sen Here the sensor has the id *22670e*. -Now have your sensor trigger the "Off" state and look for the following message in the Home Assistant log. You should see that your device has been detected as a *new* device when triggering its "Off" state: +Now have your sensor trigger the "Off" state and look for the following +message in the Home Assistant log. You should see that your device +has been detected as a *new* device when triggering its "Off" state: ```text INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 09130000226707013d70 (Device_id: 226707 Class: LightingDevice Sub: 0) ``` -Here the device id is *226707*, which is almost similar to the *22670e* we had on the "On" event a few seconds ago. +Here the device id is *226707*, which is almost similar to +the *22670e* we had on the "On" event a few seconds ago. -From those two values, you can guess that the actual id of your device is *22670*, and that *e* and *7* are commands for "On" and "Off" states respectively. As one hexadecimal digit uses 4 bits, we can conclude that the device is using 4 data bits. +From those two values, you can guess that the actual id of your device is +*22670*, and that *e* and *7* are commands for "On" and "Off" states +respectively. As one hexadecimal digit uses 4 bits, +we can conclude that the device is using 4 data bits. So here is the actual configuration section for the binary sensor: ```yaml platform: rfxtrx -automatic_add: True +automatic_add: true devices: 0913000022670e013b70: name: window_room2 @@ -117,7 +150,8 @@ devices: command_off: 0x7 ``` -The *automatic_add* option makes the rfxtrx binary sensor component calculate and display the configuration options for you in the Home Assistant logs: +The *automatic_add* option makes the rfxtrx binary sensor component calculate +and display the configuration options for you in the Home Assistant logs: ```text INFO (Thread-6) [homeassistant.components.rfxtrx] rfxtrx: found possible device 226707 for 22670e with the following configuration: @@ -127,12 +161,14 @@ command_off=0x7 INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Found possible matching deviceid 22670e. ``` -This automatic guess should work most of the time but there is no guarantee on that. You should activate it only when you want -to configure your new devices and leave it off otherwise. +This automatic guess should work most of the time but there is +no guarantee on that. You should activate it only when you +want to configure your new devices and leave it off otherwise. ## Known working devices -The following devices are known to work with the rfxtrx binary sensor component. There are too many other to list. +The following devices are known to work with the rfxtrx binary sensor component. +There are too many other to list. - Motion detectors: - Kerui P817 and P829. diff --git a/source/_components/binary_sensor.trend.markdown b/source/_components/binary_sensor.trend.markdown index 11f48b0f992..d1c68e87af9 100644 --- a/source/_components/binary_sensor.trend.markdown +++ b/source/_components/binary_sensor.trend.markdown @@ -13,11 +13,16 @@ ha_release: 0.28 ha_iot_class: "Local Push" --- -The `trend` platform allows you to create sensors which show the trend of numeric `state` or`state_attributes` from other entities. This sensor requires at least two updates of the underlying sensor to establish a trend. Thus it can take some time to show an accurate state. It can be useful as part of automations, where you want to base an action on a trend. +The `trend` platform allows you to create sensors which show the trend of +numeric `state` or`state_attributes` from other entities. This sensor requires +at least two updates of the underlying sensor to establish a trend. +Thus it can take some time to show an accurate state. It can be useful +as part of automations, where you want to base an action on a trend. ## {% linkable_title Configuration %} -To enable Trend binary sensors in your installation, add the following to your `configuration.yaml` file: +To enable Trend binary sensors in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -28,25 +33,74 @@ binary_sensor: entity_id: sensor.cpu_speed ``` -Configuration variables: - -- **sensors** array (*Required*): List of your sensors. - - **entity_id** (*Required*): The entity that this sensor tracks. - - **attribute** (*Optional*): The attribute of the entity that this sensor tracks. If no attribute is specified then the sensor will track the state. - - **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend. - - **friendly_name** (*Optional*): Name to use in the Frontend. - - **invert** (*Optional*): Invert the result. A `true` value would mean descending rather than ascending. Defaults to `False` - - **max_samples** (*Optional*): Limit the maximum number of stored samples. Defaults to `2`. - - **min_gradient** (*Optional*): The minimum rate at which the observed value must be changing for this sensor to switch on. The gradient is measured in sensor units per second. Defaults to `0.0` - - **sample_duration** (*Optional*): The duration **in seconds** to store samples for. Samples older than this value will be discarded. Defaults to `0` +{% configuration %} +sensors: + description: List of your sensors. + required: true + type: map + keys: + entity_id: + description: The entity that this sensor tracks. + required: true + type: string + attribute: + description: > + The attribute of the entity that this sensor tracks. + If no attribute is specified then the sensor will track the state. + required: false + type: string + device_class: + description: > + The [type/class](/components/binary_sensor/) of + the sensor to set the icon in the frontend. + required: false + type: string + friendly_name: + description: Name to use in the Frontend. + required: false + type: string + invert: + description: > + Invert the result. A `true` value would + mean descending rather than ascending. + required: false + type: boolean + default: false + max_samples: + description: Limit the maximum number of stored samples. + required: false + type: int + default: 2 + min_gradient: + description: > + The minimum rate at which the observed value + must be changing for this sensor to switch on. + The gradient is measured in sensor units per second. + required: false + type: string + default: 0.0 + sample_duration: + description: > + The duration **in seconds** to store samples for. + Samples older than this value will be discarded. + required: false + type: int + default: 0 +{% endconfiguration %} ## {% linkable_title Using Multiple Samples %} -If the optional `sample_duration` and `max_samples` parameters are specified then multiple samples can be stored and used to detect long-term trends. +If the optional `sample_duration` and `max_samples` parameters are specified +then multiple samples can be stored and used to detect long-term trends. -Each time the state changes, a new sample is stored along with the sample time. Samples older than `sample_duration` seconds will be discarded. +Each time the state changes, a new sample is stored along with the sample time. +Samples older than `sample_duration` seconds will be discarded. -A trend line is then fitted to the available samples, and the gradient of this line is compared to `min_gradient` to determine the state of the trend sensor. The gradient is measured in sensor units per second - so if you want to know when the temperature is falling by 2 degrees per hour, use a gradient of (-2) / (60 x 60) = -0.00055 +A trend line is then fitted to the available samples, and the gradient of this +line is compared to `min_gradient` to determine the state of the trend sensor. +The gradient is measured in sensor units per second - so if you want to know +when the temperature is falling by 2 degrees per hour, +use a gradient of (-2) / (60 x 60) = -0.00055 The current number of stored samples is displayed on the States page. @@ -65,8 +119,9 @@ binary_sensor: attribute: elevation ``` - -This example creates two sensors to indicate whether the temperature is rising or falling at a rate of at least 3 degrees an hour, and collects samples over a two hour period: +This example creates two sensors to indicate whether the temperature is +rising or falling at a rate of at least 3 degrees an hour, +and collects samples over a two hour period: ```yaml binary_sensor: diff --git a/source/_components/binary_sensor.workday.markdown b/source/_components/binary_sensor.workday.markdown index 21280a72ba4..b32983d2027 100644 --- a/source/_components/binary_sensor.workday.markdown +++ b/source/_components/binary_sensor.workday.markdown @@ -13,13 +13,19 @@ ha_iot_class: "Local Polling" ha_release: 0.41 --- -The `workday` binary sensor indicates, whether the current day is a workday or not. It allows specifying, which days of the week counts as workdays and also uses the python module [holidays](https://pypi.python.org/pypi/holidays) to incorporate information about region-specific public holidays. +The `workday` binary sensor indicates, whether the current day is a workday or +not. It allows specifying, which days of the week counts as workdays and also +uses the python module [holidays](https://pypi.python.org/pypi/holidays) +to incorporate information about region-specific public holidays. ## {% linkable_title Configuration %} -Check the [country list](https://github.com/dr-prodigy/python-holidays#available-countries) for available province. +Check the +[country list](https://github.com/dr-prodigy/python-holidays#available-countries) +for available province. -To enable the `workday` sensor in your installation, add the following to your `configuration.yaml` file: +To enable the `workday` sensor in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -29,20 +35,50 @@ binary_sensor: workdays: [mon, wed, fri] ``` -Configuration variables: +{% configuration %} +name: + description: A name for this sensor. + required: false + type: string + default: Workday Sensor +country: + description: > + Country code according to + [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. + required: true + type: string +province: + description: > + Province code according to + [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. + required: false + type: string +workdays: + description: List of workdays. + required: false + type: list + default: "[mon, tue, wed, thu, fri]" +excludes: + description: List of workday excludes. + required: false + type: list + default: "[sat, sun, holiday]" +days_offset: + description: Set days offset. + required: false + type: int + default: 0 +{% endconfiguration %} -- **name** (*Optional*): A name for this sensor. Defaults to *Workday Sensor* -- **country** (*Required*): Country code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. -- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. Defaults to None. -- **workdays** (*Optional*): List of workdays. Defaults to `mon`, `tue`, `wed`, `thu`, `fri`. -- **excludes** (*Optional*): List of workday excludes. Defaults to `sat`, `sun`, `holiday`. -- **days_offset** (*Optional*): Set days offset. Defaults to `0`. - -Days are specified as follows: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. The keyword `holiday` is used for public holidays identified by the holidays module. +Days are specified as follows: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. +The keyword `holiday` is used for public +holidays identified by the holidays module.

-If you use the sensor for Norway (`NO`) you need to wrap `NO`in quotes or write the name in full. Otherwise the value is evaluated as `False`. -If you use the sensor for Canada (`CA`) with Ontario (`ON`) as `province:` then you need to wrap `ON` in quotes. Otherwise the value is evaluated as `True` (check the YAML documentation for further details) and the sensor will not work. +If you use the sensor for Norway (`NO`) you need to wrap `NO` in quotes or write the name in full. +Otherwise the value is evaluated as `false`. +If you use the sensor for Canada (`CA`) with Ontario (`ON`) as `province:` then you need to wrap `ON` in quotes. +Otherwise the value is evaluated as `true` (check the YAML documentation for further details) and the sensor will not work.

Example usage for automation: diff --git a/source/_components/blink.markdown b/source/_components/blink.markdown index 217dcce7438..54c2afbabf3 100644 --- a/source/_components/blink.markdown +++ b/source/_components/blink.markdown @@ -13,9 +13,11 @@ ha_release: "0.40" ha_iot_class: "Cloud Polling" --- -The `blink` component lets you view camera images and motion events from [Blink](http://blinkforhome.com) camera and security systems. +The `blink` component lets you view camera images and motion events +from [Blink](http://blinkforhome.com) camera and security systems. -You will need your Blink login information (username, usually you email address, and password) to use this module. +You will need your Blink login information (username, which is +usually your email address, and password) to use this module. To set it up, add the following information to your `configuration.yaml` file: @@ -26,21 +28,32 @@ blink: password: YOUR_PASSWORD ``` -Configuration variables: - -- **username** (*Required*): Your username to login to Blink. -- **password** (*Required*): Your password to login to Blink. +{% configuration %} +username: + description: Your username to login to Blink. + required: true + type: string +password: + description: Your password to login to Blink. + required: true + type: string +{% endconfiguration %} Once loaded, your front end will have the following components: -* A camera image for each camera in your system. -* A binary_sensor per camera that indicates whether motion detection is enabled. -* A binary_sensor for the system that indicates if the system is armed or disarmed. -* A sensor per camera that reports temperature. -* A sensor per camera that reports battery level. -* A sensor per camera that reports unread notification (i.e., detected motion events). +- A camera image for each camera in your system. +- A binary_sensor per camera that indicates whether motion detection is enabled. +- A binary_sensor for the system that indicates if the system is armed or disarmed. +- A sensor per camera that reports temperature. +- A sensor per camera that reports battery level. +- A sensor per camera that reports unread notification (i.e., detected motion events). -Since the cameras are battery operated, the images are only updated in Home Assistant when the user manually forces a new photo. This image can be updated with the `snap_picture` service to force Home Assistant to request an update from Blink's servers. As a note, all of the camera-specific sensors are only polled when a new image is requested from the camera. This means that relying on any of these sensors to provide timely and accurate data is not recommended. +Since the cameras are battery operated, the images are only updated in Home +Assistant when the user manually forces a new photo. This image can be updated +with the `snap_picture` service to force Home Assistant to request an update +from Blink's servers. As a note, all of the camera-specific sensors are only +polled when a new image is requested from the camera. This means that relying on +any of these sensors to provide timely and accurate data is not recommended. Services: @@ -51,7 +64,8 @@ This services are available for the `blink` component: - snap_picture -For `arm_system`, the value sent can be either `True` or `False` and will arm and disarm the whole Blink system. Arm system example: +For `arm_system`, the value sent can be either `true` or `false` +and will arm and disarm the whole Blink system. Arm system example: ```json { @@ -59,7 +73,11 @@ For `arm_system`, the value sent can be either `True` or `False` and will arm an } ``` -Arm camera follows a similar structure, but each individual camera can have motion detection enabled or disabled. Because of this, you also need to supply a name. For example, if you have a camera named "Living Room" and you want to turn off motion detection on that camera, you would call the `arm_camera` service with the following payload: +Arm camera follows a similar structure, but each individual camera can have +motion detection enabled or disabled. Because of this, +you also need to supply a name. For example, if you have a camera named +"Living Room" and you want to turn off motion detection on that camera, +you would call the `arm_camera` service with the following payload: ```json { @@ -68,7 +86,8 @@ Arm camera follows a similar structure, but each individual camera can have moti } ``` -The `snap_picture` service takes the camera name as the payload and with take a new picture with your camera. +The `snap_picture` service takes the camera name as the +payload and with take a new picture with your camera. ```json { diff --git a/source/_components/calendar.caldav.markdown b/source/_components/calendar.caldav.markdown index 8ea6b6ad087..8f27342be6c 100644 --- a/source/_components/calendar.caldav.markdown +++ b/source/_components/calendar.caldav.markdown @@ -12,14 +12,22 @@ ha_iot_class: "Cloud Polling" ha_release: "0.60" --- - -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. ### {% linkable_title Prerequisites %} -You need to have a CalDav server and credentials for it. This component was tested against [Baikal](http://sabre.io/baikal/) but any component 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 component was +tested against [Baikal](http://sabre.io/baikal/) but any component 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 @@ -27,7 +35,8 @@ $ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev ### {% linkable_title 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 @@ -47,12 +56,16 @@ 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. ### {% linkable_title 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 @@ -70,9 +83,13 @@ 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 when you configure custom calendars, +the default ones are not created anymore. {% configuration %} url: @@ -89,7 +106,9 @@ 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. type: list custom_calendars: required: false @@ -106,11 +125,12 @@ 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 %} - ### {% linkable_title Sensor attributes %} - **offset_reached**: If set in the event title and parsed out will be on/off once the offset in the title in minutes is reached. So the title Very important meeting !!-10 would trigger this attribute to be on 10 minutes before the event starts. @@ -136,9 +156,12 @@ 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. ```yaml # configuration.yaml @@ -165,5 +188,4 @@ calendar: - condition: state entity_id: calendar.work_holiday state: 'off' - ``` diff --git a/source/_components/calendar.google.markdown b/source/_components/calendar.google.markdown index d44f7d9ff5e..2c18ccd65a8 100644 --- a/source/_components/calendar.google.markdown +++ b/source/_components/calendar.google.markdown @@ -13,12 +13,17 @@ ha_iot_class: "Cloud Polling" ha_release: 0.33 --- - -The `google` calendar platform allows you to connect to your [Google Calendars](https://calendar.google.com) and generate binary sensors. The sensors created can trigger based on any event on the calendar or only for matching events. When you first setup this component it will generate a new configuration file `google_calendars.yaml` that will contain information about all of the calendars you can see. +The `google` calendar platform allows you to connect to your +[Google Calendars](https://calendar.google.com) and generate binary sensors. +The sensors created can trigger based on any event on the calendar or only for +matching events. When you first setup this component it will generate a new +configuration file `google_calendars.yaml` that will contain information about +all of the calendars you can see. ## {% linkable_title Prerequisites %} -Generate a Client ID and Client Secret on [Google Developers Console](https://console.developers.google.com/start/api?id=calendar). +Generate a Client ID and Client Secret on +[Google Developers Console](https://console.developers.google.com/start/api?id=calendar). 1. Follow the wizard using the following information. 1. When it gets to the point of asking _Which API are you using?_ just click cancel. @@ -32,7 +37,8 @@ Generate a Client ID and Client Secret on [Google Developers Console](https://co ## {% linkable_title Configuration %} -To integrate Google Calendar in Home Assistant, add the following section to your `configuration.yaml` file: +To integrate Google Calendar in Home Assistant, +add the following section to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -51,7 +57,9 @@ client_secret: required: true type: string track_new_calendar: - description: Will automatically generate a binary sensor when a new calendar is detected. The system scans for new calendars only on startup. + description: > + Will automatically generate a binary sensor when a new calendar + is detected. The system scans for new calendars only on startup. required: false type: boolean default: true @@ -59,7 +67,10 @@ track_new_calendar: The next steps will require you to have Home Assistant running. -After you have it running complete the Google authentication that pops up. It will give you a URL and a code to enter. This will grant your Home Assistant service access to all the Google Calendars that the account you authenticate with can read. This is a Read-Only view of these calendars. +After you have it running complete the Google authentication that pops up. +It will give you a URL and a code to enter. This will grant your Home Assistant +service access to all the Google Calendars that the account you +authenticate with can read. This is a Read-Only view of these calendars. ## {% linkable_title Calendar Configuration %} @@ -86,23 +97,61 @@ A basic entry for a single calendar looks like: search: "#UnImportant" ``` -Variables: +{% configuration %} +cal_id: + description: The Google *generated* unique id for this calendar. + required: true + type: string + default: "**DO NOT CHANGE THE DEFAULT VALUE**" +entities: + description: Yes, you can have multiple sensors for a calendar! + required: true + type: list + keys: + device_id: + description: > + The name that all your automations/scripts + will use to reference this device. + required: true + type: string + name: + description: What is the name of your sensor that you'll see in the frontend. + required: true + type: string + track: + description: "Should we create a sensor `true` or ignore it `false`?" + required: true + type: boolean + search: + description: If set will only trigger for matched events. + required: false + type: string + offset: + description: > + A set of characters that precede a number in the event title + for designating a pre-trigger state change on the sensor. + required: false + type: string + default: "!!" + ignore_availability: + description: "Should we respect `free`/`busy` flags?" + required: false + type: boolean + default: true +{% endconfiguration %} -- **cal_id**: The Google generated unique id for this calendar. **DO NOT CHANGE** -- **entities**: Yes, you can have multiple sensors for a calendar! - - **device_id**: (*Required*): The name that all your automations/scripts will use to reference this device. - - **name**: (*Required*): What is the name of your sensor that you'll see in the frontend. - - **track**: (*Required*): Should we create a sensor `True` or ignore it `False`? - - **search**: (*Optional*): If set will only trigger for matched events. - - **offset**: (*Optional*): A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. (Default: `!!`) - - **ignore_availability**: (*Optional*): Should we respect `free`/`busy` flags? (Defaults to `true`) +From this we will end up with the binary sensors `calendar.test_unimportant` and +`calendar.test_important` which will toggle themselves on/off based on events on +the same calendar that match the search value set for each. +You'll also have a sensor `calendar.test_everything` that will +not filter events out and always show the next event available. -From this we will end up with the binary sensors `calendar.test_unimportant` and `calendar.test_important` which will toggle themselves on/off based on events on the same calendar that match the search value set for each. You'll also have a sensor `calendar.test_everything` that will not filter events out and always show the next event available. - -But what if you only wanted it to toggle based on all events? Just leave out the *search* parameter. +But what if you only wanted it to toggle based on all events? +Just leave out the *search* parameter.

-If you use a `#` sign for `search` then wrap the whole search term in quotes. Otherwise everything following the hash sign would be considered a YAML comment. +If you use a `#` sign for `search` then wrap the whole search term in quotes. +Otherwise everything following the hash sign would be considered a YAML comment.

### {% linkable_title Sensor attributes %} diff --git a/source/_components/camera.mjpeg.markdown b/source/_components/camera.mjpeg.markdown index de03528200f..d8d10a0448b 100644 --- a/source/_components/camera.mjpeg.markdown +++ b/source/_components/camera.mjpeg.markdown @@ -13,10 +13,11 @@ ha_release: pre 0.7 ha_iot_class: "depends" --- +The `mjpeg` camera platform allows you to integrate IP cameras which are capable +to stream their video with MJPEG into Home Assistant. -The `mjpeg` camera platform allows you to integrate IP cameras which are capable to stream their video with MJPEG into Home Assistant. - -To enable this camera in your installation, add the following to your `configuration.yaml` file: +To enable this camera in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -25,17 +26,36 @@ camera: mjpeg_url: http://192.168.1.92/mjpeg ``` -Configuration variables: - -- **mjpeg_url** (*Required*): The URL your camera serves the video on, eg. http://192.168.1.21:2112/ -- **still_image_url** (*Optional*): The URL for thumbnail picture if camera support that. -- **name** (*Optional*): This parameter allows you to override the name of your camera. -- **username** (*Optional*): The username for accessing your camera. -- **password** (*Optional*): The password for accessing your camera. -- **authentication** (*Optional*): `basic` (default) or `digest` auth for requests. +{% configuration %} +mjpeg_url: + description: The URL your camera serves the video on, eg. http://192.168.1.21:2112/ + required: true + type: string +still_image_url: + description: The URL for thumbnail picture if camera support that. + required: false + type: string +name: + description: This parameter allows you to override the name of your camera. + required: false + type: string +username: + description: The username for accessing your camera. + required: false + type: string +password: + description: The password for accessing your camera. + required: false + type: string +authentication: + description: "`basic` or `digest` auth for requests." + required: false + type: string + default: basic +{% endconfiguration %}

-There is a known issue in urllib3 that you will get error messages in your logs like [StartBoundaryNotFoundDefect(), MultipartInvariantViolationDefect()], unparsed data: '' but the component still works fine. You can ignore the messages. +There is a known issue in urllib3 that you will get error messages in your logs like [StartBoundaryNotFoundDefect(), MultipartInvariantViolationDefect()], unparsed data: '' but the component still works fine. You can ignore the messages.

## {% linkable_title Examples %} diff --git a/source/_components/cast.markdown b/source/_components/cast.markdown index 7243ad78a09..1bd86aef388 100644 --- a/source/_components/cast.markdown +++ b/source/_components/cast.markdown @@ -15,15 +15,20 @@ ha_iot_class: "Local Polling" redirect_from: /components/media_player.cast/ --- - -Google Cast devices like Android TVs and Chromecasts will be automatically discovered if you enable [the discovery component]({{site_root}}/components/discovery/). If you don't have the discovery component enabled, you can enable the Cast component by going to the Integrations page inside the config panel. +Google Cast devices like Android TVs and Chromecasts will be automatically +discovered if you enable [the discovery component](/components/discovery/). If +you don't have the discovery component enabled, you can enable the Cast +component by going to the Integrations page inside the config panel. ## {% linkable_title Advanced use %} -The Cast component has some extra configuration options available for advanced users. You will still need to create a config entry to initialize the Cast component. - -For example, Cast devices can only be discovered if they are on the same subnet as Home Assistant. If this is not the case, you want to configure the IP address of the Cast device directly: +The Cast component has some extra configuration options available for advanced +users. You will still need to create a config entry to initialize the Cast +component. +For example, Cast devices can only be discovered if they are on the same subnet +as Home Assistant. If this is not the case, +you want to configure the IP address of the Cast device directly: ```yaml # Example configuration.yaml entry @@ -32,7 +37,31 @@ cast: - host: 192.168.1.10 ``` -Configuration variables: +{% configuration %} +media_player: + description: A list that contains all Cast devices. + required: true + type: list + keys: + host: + description: Use only if you don't want to scan for devices. + required: false + type: string + ignore_cec: + description: > + A list of Chromecasts that should ignore CEC data for determining the + active input. [See the upstream documentation for more information.](https://github.com/balloob/pychromecast#ignoring-cec-data) + required: false + type: list +{% endconfiguration %} -- **host** (*Optional*): Use only if you don't want to scan for devices. -- **ignore_cec** (*Optional*) A list of Chromecasts that should ignore CEC data for determining the active input. [See the upstream documentation for more information.](https://github.com/balloob/pychromecast#ignoring-cec-data) +If you want to manually configure multiple Cast media players, you can define +those as follows: + +```yaml +# Example configuration.yaml entry for multiple devices +cast: + media_player: + - host: IP_ADDRESS_DEVICE_1 + - host: IP_ADDRESS_DEVICE_2 +``` diff --git a/source/_components/cover.template.markdown b/source/_components/cover.template.markdown index c6eb6392f20..fc3f6b8db92 100644 --- a/source/_components/cover.template.markdown +++ b/source/_components/cover.template.markdown @@ -13,12 +13,14 @@ ha_iot_class: "Local Push" logo: home-assistant.png --- -The `template` platform can create covers that combine components and provides the ability to run scripts or invoke services for each of the open, close, stop, position and tilt commands of a cover. +The `template` platform can create covers that combine components and provides +the ability to run scripts or invoke services for each of the open, +close, stop, position and tilt commands of a cover. ## {% linkable_title Configuration %} -To enable Template Covers in your installation, add the following to your -`configuration.yaml` file: +To enable Template Covers in your installation, +add the following to your `configuration.yaml` file: {% raw %} ```yaml @@ -87,12 +89,12 @@ cover: optimistic: description: Force cover position to use [optimistic mode](#optimistic-mode). required: false - type: bool + type: boolean default: false tilt_optimistic: description: Force cover tilt position to use [optimistic mode](#optimistic-mode). required: false - type: bool + type: boolean default: false tilt_template: description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). @@ -103,8 +105,8 @@ cover: ## {% linkable_title Considerations %} If you are using the state of a platform that takes extra time to load, the -Template Cover may get an `unknown` state during startup. This results -in error messages in your log file until that platform has completed loading. +Template Cover may get an `unknown` state during startup. This results in error +messages in your log file until that platform has completed loading. If you use `is_state()` function in your template, you can avoid this situation. For example, you would replace {% raw %}`{{ states.switch.source.state == 'on' }}`{% endraw %} @@ -114,14 +116,14 @@ result: ## {% linkable_title Optimistic Mode %} -In optimistic mode, the cover position state is maintained internally. This -mode is automatically enabled if neither [`value_template`](#value_template) or +In optimistic mode, the cover position state is maintained internally. This mode +is automatically enabled if neither [`value_template`](#value_template) or [`position_template`](#position_template) are specified. Note that this is unlikely to be very reliable without some feedback mechanism, since there is otherwise no way to know if the cover is moving properly. The cover can be -forced into optimistic mode by using the [`optimistic`](#optimistic) -attribute. There is an equivalent mode for `tilt_position` that is enabled -when [`tilt_template`](#tilt_template) is not specified or when the +forced into optimistic mode by using the [`optimistic`](#optimistic) attribute. +There is an equivalent mode for `tilt_position` that is enabled when +[`tilt_template`](#tilt_template) is not specified or when the [`tilt_optimistic`](#tilt_optimistic) attribute is used. ## {% linkable_title Examples %} diff --git a/source/_components/device_tracker.tomato.markdown b/source/_components/device_tracker.tomato.markdown index 998b528d510..6543004c7ab 100644 --- a/source/_components/device_tracker.tomato.markdown +++ b/source/_components/device_tracker.tomato.markdown @@ -12,12 +12,21 @@ ha_category: Presence Detection ha_release: pre 0.7 --- +The `tomato` platform requires an extra config variable called `http_id`. The +value can be obtained by logging in to the Tomato admin interface and search for +`http_id` in the page source code. -The `tomato` platform requires an extra config variable called `http_id`. The value can be obtained by logging in to the Tomato admin interface and search for `http_id` in the page source code. +Because of a limitation in Tomato's API, this platform will only track wireless +devices. If tracking wired devices like a Philips Hue Hub is necessary, it is +possible to use another platform like +[NMAP](/components/device_tracker.nmap_tracker/). -Because of a limitation in Tomato's API, this platform will only track wireless devices. If tracking wired devices like a Philips Hue Hub is necessary, it is possible to use another platform like [Nmap](/components/device_tracker.nmap_tracker/). +Because of a limitation in Tomato's API, this platform will only track wireless devices. +If tracking wired devices like a Philips Hue Hub is necessary, +it is possible to use another platform like [Nmap](/components/device_tracker.nmap_tracker/). -To use this device tracker in your installation, add the following to your `configuration.yaml` file: +To use this device tracker in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -42,12 +51,12 @@ port: ssl: description: "Whether to connect via `https`." required: false - type: bool + type: boolean default: false verify_ssl: description: "If SSL verification for https resources needs to be turned off (for self-signed certs, etc.) this can take on boolean values `False` or `True` or you can pass a location on the device where a certificate can be used for verification e.g., `/mnt/NAS/router_cert.pem`." required: false - type: [string, bool] + type: [string, boolean] default: true username: description: "The username of an user with administrative privileges, usually *admin*." @@ -63,13 +72,17 @@ http_id: type: string {% endconfiguration %} -See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. +See the [device tracker component page](/components/device_tracker/) for +instructions how to configure the people to be tracked. -A description of the API s available in this [Tomato API](http://paulusschoutsen.nl/blog/2013/10/tomato-api-documentation/) blog post. +A description of the API s available in this +[Tomato API](http://paulusschoutsen.nl/blog/2013/10/tomato-api-documentation/) +blog post. SSL Certificate: -Gathering the SSL Certificate of your router can be accomplished with this (or a similar) command: +Gathering the SSL Certificate of your router can be accomplished with this (or +a similar) command: ```bash openssl s_client -showcerts -connect 172.10.10.1:443 /dev/null | openssl x509 -outform PEM > router_cert.pem -``` \ No newline at end of file +``` diff --git a/source/_components/history.markdown b/source/_components/history.markdown index 206678c5107..cb8056ff091 100644 --- a/source/_components/history.markdown +++ b/source/_components/history.markdown @@ -12,10 +12,14 @@ ha_category: History ha_release: pre 0.7 --- +The `history` component will track everything that is going on within Home +Assistant and allows the user to browse through it. It depends on the `recorder` +component for storing the data and uses the same database setting. +If any entities are excluded from being recorded, +no history will be available for these entities. -The `history` component will track everything that is going on within Home Assistant and allows the user to browse through it. It depends on the `recorder` component for storing the data and uses the same database setting. If any entities are excluded from being recorded, no history will be available for these entities. - -To enable the history option in your installation, add the following to your `configuration.yaml` file: +To enable the history option in your installation, +add the following to your `configuration.yaml` file: ```yaml # Basic configuration.yaml entry @@ -29,22 +33,48 @@ history:

-Events are saved in a local database. Google Graphs is used to draw the graph. Drawing is happening 100% in your browser. No data is transferred to anyone at any time. +Events are saved in a local database. Google Graphs is used to draw the graph. +Drawing is happening 100% in your browser. No data is transferred to anyone at any time.

+{% configuration %} +exclude: + description: Configure which components should **not** be displayed. + required: false + type: map + keys: + entities: + description: The list of entity ids to be excluded from the history. + required: false + type: list + domains: + description: The list of domains to be excluded from the history. + required: false + type: list +include: + description: Configure which components should be displayed. + required: false + type: map + keys: + entities: + description: The list of entity ids to be included in the history. + required: false + type: list + domains: + description: The list of domains to be included in the history. + required: false + type: list +{% endconfiguration %} -Configuration variables: +Without any `include` or `exclude` configuration the history displays graphs for + every entity (well that's not exactly true - for instance `hidden` entities or + `scenes` are never shown) on a given date. If you are only interested in some + of the entities you have several options: -- **exclude** (*Optional*): Configure which components should **not** be displayed. - - **entities** (*Optional*): The list of entity ids to be excluded from the history. - - **domains** (*Optional*): The list of domains to be excluded from the history. -- **include** (*Optional*): Configure which components should be displayed. - - **entities** (*Optional*): The list of entity ids to be included to the history. - - **domains** (*Optional*): The list of domains to be included to the history. - -Without any `include` or `exclude` configuration the history displays graphs for every entity (well that's not exactly true - for instance `hidden` entities or `scenes` are never shown) on a given date. If you are only interested in some of the entities you have several options: - -Define domains and entities to `exclude` (aka. blacklist). This is convenient when you are basically happy with the information displayed, but just want to remove some entities or domains. Usually these are entities/domains which do not change (like `weblink`) or rarely change (like `updater` or `automation`). +Define domains and entities to `exclude` (aka. blacklist). This is convenient +when you are basically happy with the information displayed, but just want to +remove some entities or domains. Usually these are entities/domains which do not +change (like `weblink`) or rarely change (like `updater` or `automation`). ```yaml # Example configuration.yaml entry with exclude @@ -59,7 +89,10 @@ history: - sensor.date ``` -Define domains and entities to display by using the `include` configuration (aka. whitelist). If you have a lot of entities in your system and your `exclude` list is getting too large, it might be better just to define the entities or domains to `include`. +Define domains and entities to display by using the `include` configuration +(aka. whitelist). If you have a lot of entities in your system and your +`exclude` list is getting too large, it might be better just to define the +entities or domains to `include`. ```yaml # Example configuration.yaml entry with include @@ -71,7 +104,13 @@ history: - media_player ``` -Use the `include` list to define the domains/entities to display, and exclude some of them within the `exclude` list. This makes sense if you, for instance, include the `sensor` domain, but want to exclude some specific sensors. Instead of adding every sensor entity to the `include` `entities` list just include the `sensor` domain and exclude the sensor entities you are not interested in. Note that the order of any `include` `entities` will be displayed as listed in the configuration, otherwise, the display order is arbitrary. +Use the `include` list to define the domains/entities to display, and exclude +some of them within the `exclude` list. This makes sense if you, for instance, +include the `sensor` domain, but want to exclude some specific sensors. Instead +of adding every sensor entity to the `include` `entities` list just include the +`sensor` domain and exclude the sensor entities you are not interested in. +Note that the order of any `include` `entities` will be displayed as listed in +the configuration, otherwise, the display order is arbitrary. ```yaml # Example configuration.yaml entry with include and exclude @@ -87,9 +126,9 @@ history: - sensor.date ``` -If you'd like the order of display of the sensors to follow the way -they are listed in the included entity list, you can set the flag -`use_include_order` to True. +If you'd like the order of display of the sensors to follow the way they are +listed in the included entity list, +you can set the flag `use_include_order` to true. ```yaml # Example configuration.yaml entry using specified entity display order @@ -101,10 +140,10 @@ history: - light.front_porch ``` - #### {% linkable_title Implementation details %} -The history is stored in a SQLite database `home-assistant_v2.db` within your configuration directory unless the `recorder` component is set up differently. +The history is stored in a SQLite database `home-assistant_v2.db` within your +configuration directory unless the `recorder` component is set up differently. - events table is all events except `time_changed` that happened while recorder component was running. - states table contains all the `new_state` values of `state_changed` events. @@ -116,11 +155,14 @@ The history is stored in a SQLite database `home-assistant_v2.db` within your co - `last_updated`: timestamp anything has changed (state, attributes) - `created`: timestamp this entry was inserted into the database -When the `history` component queries the states table it only selects states where the state has changed: `WHERE last_changed=last_updated` +When the `history` component queries the states table it only selects states +where the state has changed: `WHERE last_changed=last_updated` -#### {% linkable_title On dates %} +#### {% linkable_title On dates %} -SQLite databases do not support native dates. That's why all the dates are saved in seconds since the UNIX epoch. Convert them manually using [this site](https://www.epochconverter.com/) or in Python: +SQLite databases do not support native dates. That's why all the dates are saved +in seconds since the UNIX epoch. Convert them manually using +[this site](https://www.epochconverter.com/) or in Python: ```python from datetime import datetime @@ -129,4 +171,5 @@ datetime.fromtimestamp(1422830502) #### {% linkable_title API %} -The history information is also available through the [RESTful API](/developers/rest_api/#get-apihistory). +The history information is also available through the +[RESTful API](/developers/rest_api/#get-apihistory). diff --git a/source/_components/http.markdown b/source/_components/http.markdown index 775cdb4624f..643f143fc84 100644 --- a/source/_components/http.markdown +++ b/source/_components/http.markdown @@ -11,10 +11,13 @@ logo: http.png ha_category: "Other" --- -The `http` component serves all files and data required for the Home Assistant frontend. You only need to add this to your configuration file if you want to change any of the default settings. +The `http` component serves all files and data required for the Home Assistant +frontend. You only need to add this to your configuration file if you want to +change any of the default settings.

-It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet. +It is HIGHLY recommended that you set the `api_password`, +especially if you are planning to expose your installation to the internet.

@@ -27,27 +30,26 @@ http: api_password: YOUR_PASSWORD ``` -Configuration variables: - -{% configuration http %} +{% configuration %} api_password: description: Protect Home Assistant with a password. required: false type: string server_host: - description: 'Only listen to incoming requests on specific IP/host (default: bind to `0.0.0.0` which means accept all IPv4 connections). Use `server_host: "::0"` if you want to listen to (and only) IPv6.' + description: "Only listen to incoming requests on specific IP/host. By default it will accept all IPv4 connections. Use `server_host: ::0` if you want to listen to (and only) IPv6." required: false type: string + default: 0.0.0.0 server_port: description: Let you set a port to use. required: false - type: integer + type: int default: 8123 base_url: - description: "The URL that Home Assistant is available on the internet. For example: `hass-example.duckdns.org:8123`. Defaults to the local IP address. 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." + description: "The URL that Home Assistant is available on the internet. For example: `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." required: false type: string - default: The local IP address + default: Your local IP address ssl_certificate: description: Path to your TLS/SSL certificate to serve Home Assistant over a secure connection. required: false @@ -64,15 +66,15 @@ cors_allowed_origins: description: "A list of origin domain names to allow [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) requests from. Enabling this will set the `Access-Control-Allow-Origin` header to the Origin header if it is found in the list, and the `Access-Control-Allow-Headers` header to `Origin, Accept, X-Requested-With, Content-type, X-HA-access`. You must provide the exact Origin, i.e. `https://www.home-assistant.io` will allow requests from `https://www.home-assistant.io` but __not__ `http://www.home-assistant.io`." required: false type: string, list -trusted_proxies: - description: "List of trusted proxies, consisting of IP addresses or networks, that are allowed to set the `X-Forwarded-For` header. This is required when using `use_x_forwarded_for` because all requests to Home Assistant, regardless of source, will arrive from the reverse proxy IP address. Therefore in a reverse proxy scenario, this option should be set with extreme care." - required: false - type: string, list use_x_forwarded_for: description: "Enable parsing of the `X-Forwarded-For` header, passing on the client's correct IP address in proxied setups. You **must** also whitelist trusted proxies using the `trusted_proxies` setting above for this to work. Non-whitelisted requests with this header will be considered IP spoofing attacks, and the header will, therefore, be ignored." required: false type: boolean default: false +trusted_proxies: + description: "List of trusted proxies, consisting of IP addresses or networks, that are allowed to set the `X-Forwarded-For` header. This is required when using `use_x_forwarded_for` because all requests to Home Assistant, regardless of source, will arrive from the reverse proxy IP address. Therefore in a reverse proxy scenario, this option should be set with extreme care." + required: false + type: string, list trusted_networks: description: "List of trusted networks, consisting of IP addresses or networks, that are allowed to bypass password protection when accessing Home Assistant. If using a reverse proxy with the `use_x_forwarded_for` and `trusted_proxies` options enabled, requests proxied to Home Assistant with a trusted `X-Forwarded-For` header will appear to come from the IP given in that header instead of the proxy IP." required: false @@ -83,9 +85,9 @@ ip_ban_enabled: type: boolean default: false login_attempts_threshold: - description: "Number of failed login attempt from single IP after which it will be automatically banned if `ip_ban_enabled` is True. When set to -1 no new automatic bans will be added." + description: "Number of failed login attempt from single IP after which it will be automatically banned if `ip_ban_enabled` is `true`. When set to -1 no new automatic bans will be added." required: false - type: integer + type: int default: -1 ssl_profile: description: The [Mozilla SSL profile](https://wiki.mozilla.org/Security/Server_Side_TLS) to use. Only lower if you are experiencing integrations causing SSL handshake errors. @@ -106,7 +108,7 @@ http: cors_allowed_origins: - https://google.com - https://www.home-assistant.io - use_x_forwarded_for: True + use_x_forwarded_for: true trusted_proxies: - 127.0.0.1 - ::1 @@ -115,36 +117,55 @@ http: - ::1 - 192.168.0.0/24 - fd00::/8 - ip_ban_enabled: True + ip_ban_enabled: true login_attempts_threshold: 5 ``` -The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/). +The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) +blog post gives you details about the encryption of your traffic using free +certificates from [Let's Encrypt](https://letsencrypt.org/). -Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/). +Or use a self signed certificate following the instructions here +[Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/). ## {% linkable_title APIs %} -On top of the `http` component is a [REST API](/developers/rest_api/), [Python API](/developers/python_api/) and [WebSocket API](/developers/websocket_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/). +On top of the `http` component is a [REST API](/developers/rest_api/), +[Python API](/developers/python_api/) and +[WebSocket API](/developers/websocket_api/) available. There is also support for +[Server-sent events](/developers/server_sent_events/). -The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP. +The `http` platforms are not real platforms within the meaning of the +terminology used around Home Assistant. Home Assistant's +[REST API](/developers/rest_api/) sends and receives messages over HTTP. ## {% linkable_title HTTP sensors %} -To use those kind of [sensors](/components/sensor.http/) or [binary sensors](components/binary_sensor.http/) in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themselves. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived. +To use those kind of [sensors](/components/sensor.http/) or +[binary sensors](components/binary_sensor.http/) in your installation no +configuration in Home Assistant is needed. All configuration is done on the +devices themselves. This means that you must be able to edit the target URL or +endpoint and the payload. +The entity will be created after the first message has arrived. -All [requests](/developers/rest_api/#post-apistatesltentity_id) need to be sent to the endpoint of the device and must be **POST**. +All [requests](/developers/rest_api/#post-apistatesltentity_id) need to be sent +to the endpoint of the device and must be **POST**. ## {% linkable_title IP filtering and banning %} -If you want to apply additional IP filtering, and automatically ban brute force attempts, set `ip_ban_enabled` to `True` and the maximum number of attempts. After the first ban, an `ip_bans.yaml` file will be created in the root configuration folder. It will have the banned IP address and time in UTC when it was added: +If you want to apply additional IP filtering, and automatically ban brute force +attempts, set `ip_ban_enabled` to `true` and the maximum number of attempts. +After the first ban, an `ip_bans.yaml` file will be created in the root +configuration folder. +It will have the banned IP address and time in UTC when it was added: ```yaml 127.0.0.1: banned_at: '2016-11-16T19:20:03' ``` -After a ban is added a Persistent Notification is populated to the Home Assistant frontend. +After a ban is added a Persistent Notification is populated to the Home +Assistant frontend.

Please note, that sources from `trusted_networks` won't be banned automatically. @@ -152,7 +173,11 @@ Please note, that sources from `trusted_networks` won't be banned automatically. ## {% linkable_title Hosting files %} -If you want to use Home Assistant to host or serve static files then create a directory called `www` under the configuration path (`/config` on Hass.io, `.homeassistant` elsewhere). The static files in `www/` can be accessed by the following URL `http://your.domain:8123/local/`, for example `audio.mp3` would be accessed as `http://your.domain:8123/local/audio.mp3`. +If you want to use Home Assistant to host or serve static files then create a +directory called `www` under the configuration path (`/config` on Hass.io, +`.homeassistant` elsewhere). The static files in `www/` can be accessed by the +following URL `http://your.domain:8123/local/`, for example `audio.mp3` would +be accessed as `http://your.domain:8123/local/audio.mp3`.

If you've had to create the `www/` folder for the first time, you'll need to restart Home Assistant. diff --git a/source/_components/ihc.markdown b/source/_components/ihc.markdown index 0030d30361f..5fca84708fe 100644 --- a/source/_components/ihc.markdown +++ b/source/_components/ihc.markdown @@ -13,30 +13,32 @@ ha_release: "0.62" ha_iot_class: "Local Push" --- -IHC Controller integration for Home Assistant allows you to connect the LK IHC controller to Home Assistant. -(The controller is sold under other names in different countries - "ELKO Living system" in Sweden and Norway) +IHC Controller integration for Home Assistant allows you to connect the LK IHC +controller to Home Assistant. The controller is sold under other names in +different countries - "ELKO Living system" in Sweden and Norway -An `ihc` section must be present in the `configuration.yaml` file and contain the following options: +An `ihc` section must be present in the `configuration.yaml` file and contain +the following options: ```yaml # Example configuration.yaml entry ihc: url: http://192.168.1.3 - username: admin - password: mysecret - auto_setup: True - info: True + username: YOUR_USERNAME + password: YOUR_PASSWORD + info: true ``` {% configuration %} auto_setup: - description: True to have IHC products auto setup. + description: Automatic setup of IHC products. required: false - type: bool + type: boolean + default: true info: - description: If True additional IHC info will be shown on each component. + description: Shows the IHC "name", "note" and "position" attributes of each component. This will make it easier to identify the IHC products within Home Assistant. required: false - type: bool + type: boolean password: description: The password for the IHC Controller. required: true @@ -51,40 +53,44 @@ username: type: string {% endconfiguration %} -The info option will show the IHC "name", "note" and "position" attributes. -This will make it easier to identify the IHC products within Home Assistant - There is currently support for the following device types within Home Assistant: -- [Binary Sensor](/components/binary_sensor.ihc/) -- [Sensor](/components/sensor.ihc/) -- [Light](/components/light.ihc/) -- [Switch](/components/switch.ihc/) +- [Binary Sensor](/components/binary_sensor.ihc/) +- [Sensor](/components/sensor.ihc/) +- [Light](/components/light.ihc/) +- [Switch](/components/switch.ihc/) ### Auto setup of IHC products -If the auto setup is enabled, the `ihc` component will automatically find IHC products and insert these as devices in Home Assistant. -To disable this set auto_setup to False. (Auto setup is on by default) -See the individual device types for a list of IHC products to be recognized automatically. +If the auto setup is enabled, the `ihc` component will automatically find IHC +products and insert these as devices in Home Assistant. +To disable this set auto_setup to false. See the individual device types for a +list of IHC products to be recognized automatically. -Components will get a default name that is a combination of the IHC group and IHC resource id. -If you want to change the display names use the [Customizing entities](/docs/configuration/customizing-devices/) +Components will get a default name that is a combination of the IHC group and +IHC resource id. +If you want to change the display names use the +[Customizing entities](/docs/configuration/customizing-devices/). ### {% linkable_title Manual setup %} -Each device is associated with an IHC resource id. -To manually setup components you specify resource ids from the IHC project. -(The IHC project is the file you edit/upload to the IHC Controller using LK IHC Visual - or similar program if your controller is not the LK brand). -The project file is an XML file and you can view it with any text/XML editor. -You can rename it to have the XML extension and use a browser like Chrome or Internet Explorer. -The resources are the \ or \ eleements. -Shown as inputs or outputs of products in the IHC application. -You can also use inputs and outputs from function blocks. -These are the \ and \ elements from the project file. +Each device is associated with an IHC resource id. To manually setup components +you specify resource ids from the IHC project. The IHC project is the file you +edit/upload to the IHC Controller using LK IHC Visual - or similar program if +your controller is not the LK brand. +The project file is an XML file and you can view it with any text/XML editor. +You can rename it to have the XML extension and use a browser like Chrome or +Internet Explorer. The resources are the \ or \ +elements. Shown as inputs or outputs of products in the IHC application. You can +also use inputs and outputs from function blocks. These are the +\ and \ elements from the project file. -The IHC resource id should be specified as an integer value. (In the project file the id will be specified as a hex number) +The IHC resource id should be specified as an integer value. In the project file +the id will be specified as a hex number. -If you want an easier way to get the IHC resource ids, you can download the [Alternative Service View application](https://www.dingus.dk/updated-ihc-alternative-service-view/). -The application will show the product tree. You can expand it, select inputs and outputs and when selected you can see the resource id. +If you want an easier way to get the IHC resource ids, you can download the +[Alternative Service View application](https://www.dingus.dk/updated-ihc-alternative-service-view/). +The application will show the product tree. You can expand it, select inputs and +outputs and when selected you can see the resource id. See the manual of each device type for configuration options. diff --git a/source/_components/image_processing.microsoft_face_detect.markdown b/source/_components/image_processing.microsoft_face_detect.markdown index 06cca72d260..18698a70ec5 100644 --- a/source/_components/image_processing.microsoft_face_detect.markdown +++ b/source/_components/image_processing.microsoft_face_detect.markdown @@ -13,13 +13,18 @@ featured: false ha_release: 0.38 --- -The `microsoft_face_detect` image processing platform allows you to use the [Microsoft Face Identify](https://www.microsoft.com/cognitive-services/en-us/) API through Home Assistant. This platform enables you do detect face on camera and fire an event with attributes. +The `microsoft_face_detect` image processing platform allows you to use the +[Microsoft Face Identify](https://www.microsoft.com/cognitive-services/en-us/) +API through Home Assistant. This platform enables you do detect face on camera +and fire an event with attributes. -Please refer to the [component](/components/microsoft_face/) configuration on how to setup the API key. +Please refer to the [component](/components/microsoft_face/) configuration on +how to setup the API key. -For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page. +For using the result inside an automation rule, +take a look at the [component](/components/image_processing/) page. -### {% linkable_title Configuration Home Assistant %} +### {% linkable_title Configuration %} ```yaml # Example configuration.yaml entry @@ -29,10 +34,28 @@ image_processing: - entity_id: camera.door ``` -Configuration variables: - -- **confidence** (*Optional*): The minimum of confidence in percent to process with Home Assistant. Defaults to 80. -- **source** array (*Required*): List of image sources. - - **entity_id** (*Required*): A camera entity id to get picture from. - - **name** (*Optional*): This parameter allows you to override the name of your `image_processing` entity. -- **attributes** array (*Optional*): The image search attributes. Supported: `age`, `gender`, `glasses`. Default `age`, `gender`. +{% configuration %} +confidence: + description: The minimum of confidence in percent to process with Home Assistant. + required: false + type: int + default: 80 +source: + description: List of image sources. + required: true + type: list + keys: + entity_id: + description: A camera entity id to get picture from. + required: true + type: string + name: + description: This parameter allows you to override the name of your `image_processing` entity. + required: false + type: string +attributes: + description: "The image search attributes. Supported: `age`, `gender`, `glasses`." + required: false + type: list + default: "[age, gender]" +{% endconfiguration %} diff --git a/source/_components/image_processing.microsoft_face_identify.markdown b/source/_components/image_processing.microsoft_face_identify.markdown index 7f0de67938f..3e4b7527fee 100644 --- a/source/_components/image_processing.microsoft_face_identify.markdown +++ b/source/_components/image_processing.microsoft_face_identify.markdown @@ -13,13 +13,18 @@ featured: false ha_release: 0.37 --- -The `microsoft_face_identify` image processing platform lets you use [Microsoft Face identify](https://www.microsoft.com/cognitive-services/en-us/) API through Home Assistant. This platform allow you do identify persons on camera and fire an event with attributes. +The `microsoft_face_identify` image processing platform lets you use +[Microsoft Face identify](https://www.microsoft.com/cognitive-services/en-us/) +API through Home Assistant. This platform allow you do identify persons on +camera and fire an event with attributes. -Please refer to the [component](/components/microsoft_face/) configuration on how to setup the API key. +Please refer to the [component](/components/microsoft_face/) configuration on +how to setup the API key. -For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page. +For using the result inside an automation rule, +take a look at the [component](/components/image_processing/) page. -### {% linkable_title Configuration Home Assistant %} +### {% linkable_title Configuration %} ```yaml # Example configuration.yaml entry @@ -30,10 +35,27 @@ image_processing: - entity_id: camera.door ``` -Configuration variables: - -- **group** (*Required*): Micrsoft face group to detect person from it. -- **confidence** (*Optional*): The minimum of confidence in percent to process with Home Assistant. Defaults to 80. -- **source** array (*Required*): List of image sources. - - **entity_id** (*Required*): A camera entity id to get picture from. - - **name** (*Optional*): This parameter allows you to override the name of your `image_processing` entity. +{% configuration %} +group: + description: Micrsoft face group to detect person from it. + required: true + type: string +confidence: + description: The minimum of confidence in percent to process with Home Assistant. + required: false + type: int + default: 80 +source: + description: List of image sources. + required: true + type: list + keys: + entity_id: + description: A camera entity id to get picture from. + required: true + type: string + name: + description: This parameter allows you to override the name of your `image_processing` entity. + required: false + type: string +{% endconfiguration %} diff --git a/source/_components/image_processing.openalpr_cloud.markdown b/source/_components/image_processing.openalpr_cloud.markdown index 96e180a7055..31759b9bd70 100644 --- a/source/_components/image_processing.openalpr_cloud.markdown +++ b/source/_components/image_processing.openalpr_cloud.markdown @@ -13,11 +13,14 @@ featured: false ha_release: 0.36 --- -[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](/components/automation/). +[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you +to process licences plates from a camera. You can use them to open a garage door +or trigger any other [automation](/components/automation/). -For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page. +For using the result inside an automation rule, +take a look at the [component](/components/image_processing/) page. -### {% linkable_title Configuration Home Assistant %} +### {% linkable_title Configuration %} ```yaml # Example configuration.yaml entry @@ -29,11 +32,31 @@ image_processing: - entity_id: camera.garage ``` -Configuration variables: - -- **region** (*Required*): Country or region. List of supported [values](https://github.com/openalpr/openalpr/tree/master/runtime_data/config). -- **api_key** (*Required*): You need an API key from [OpenALPR Cloud](https://cloud.openalpr.com/). -- **confidence** (*Optional*): The minimum of confidence in percent to process with Home Assistant. Defaults to 80. -- **source** array (*Required*): List of image sources. - - **entity_id** (*Required*): A list of devices to add in Home Assistant. - - **name** (*Optional*): This parameter allows you to override the name of your OpenALPR entity. +{% configuration %} +region: + description: Country or region. List of supported [values](https://github.com/openalpr/openalpr/tree/master/runtime_data/config). + required: true + type: string +api_key: + description: You need an API key from [OpenALPR Cloud](https://cloud.openalpr.com/). + required: true + type: string +confidence: + description: The minimum of confidence in percent to process with Home Assistant. + required: false + type: int + default: 80 +source: + description: List of image sources. + required: true + type: list + keys: + entity_id: + description: A camera entity id to get picture from. + required: true + type: string + name: + description: This parameter allows you to override the name of your OpenALPR entity. + required: false + type: string +{% endconfiguration %} diff --git a/source/_components/image_processing.openalpr_local.markdown b/source/_components/image_processing.openalpr_local.markdown index d5da4bab3ee..d7d05162c05 100644 --- a/source/_components/image_processing.openalpr_local.markdown +++ b/source/_components/image_processing.openalpr_local.markdown @@ -14,24 +14,32 @@ ha_release: 0.36 redirect_from: /components/openalpr/ --- -[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](/components/automation/). +[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you +to process licences plates from a camera. You can use them to open a garage door +or trigger any other [automation](/components/automation/). -For using inside automation look on [component](/components/image_processing) page. +For using the result inside an automation rule, take a look at the +[component](/components/image_processing) page. ### {% linkable_title Local installation %} -If you want process all data locally, you need version 2.3.1 or higher of the `alpr` commandline tool. +If you want process all data locally, you need version 2.3.1 or higher of the +`alpr` commandline tool. -If you don't find binaries for your distribution you can compile from source. Documentation of how to build OpenALPR is found [here](https://github.com/openalpr/openalpr/wiki). +If you don't find binaries for your distribution you can compile from source. +Documentation of how to build OpenALPR is found +[here](https://github.com/openalpr/openalpr/wiki). -On a Debian system you can use this `cmake` command to build only the command line tool: +On a Debian system you can use this `cmake` command to build only the command +line tool: ```bash $ cmake -DWITH_TEST=FALSE -DWITH_BINDING_JAVA=FALSE --DWITH_BINDING_PYTHON=FALSE \ --DWITH_BINDING_GO=FALSE -DWITH_DAEMON=FALSE -DCMAKE_INSTALL_PREFIX:PATH=/usr .. ``` -For other operating system please refer to the [OpenALPR wiki](https://github.com/openalpr/openalpr/wiki). +For other operating system please refer to the +[OpenALPR wiki](https://github.com/openalpr/openalpr/wiki). Verify your `alpr` installation with: @@ -39,8 +47,7 @@ Verify your `alpr` installation with: $ wget -O- -q http://plates.openalpr.com/h786poj.jpg | alpr - ``` -### {% linkable_title Configuration Home Assistant %} - +### {% linkable_title Configuration %} ```yaml # Example configuration.yaml entry @@ -50,12 +57,33 @@ image_processing: source: - entity_id: camera.garage ``` -Configuration variables: - -- **region** (*Required*): Country or region. List of supported [values](https://github.com/openalpr/openalpr/tree/master/runtime_data/config). -- **alpr_bin** (*Optional*): The command line tool alpr from OpenALPR software for local processing. Defaults to `alpr`. -- **confidence** (*Optional*): The minimum of confidence in percent to process with Home Assistant. Defaults to 80. -- **source** array (*Required*): List of image sources. - - **entities** (*Required*): A list of devices to add in Home Assistant. - - **name** (*Optional*): This parameter allows you to override the name of your OpenALPR entity. +{% configuration %} +region: + description: Country or region. List of supported [values](https://github.com/openalpr/openalpr/tree/master/runtime_data/config). + required: true + type: string +alpr_bin: + description: The command line tool alpr from OpenALPR software for local processing. + required: false + type: string + default: alpr +confidence: + description: The minimum of confidence in percent to process with Home Assistant. + required: false + type: int + default: 80 +source: + description: List of image sources. + required: true + type: list + keys: + entity_id: + description: A camera entity id to get picture from. + required: true + type: string + name: + description: This parameter allows you to override the name of your OpenALPR entity. + required: false + type: string +{% endconfiguration %} diff --git a/source/_components/input_datetime.markdown b/source/_components/input_datetime.markdown index e8a793ae6a3..be7024142a2 100644 --- a/source/_components/input_datetime.markdown +++ b/source/_components/input_datetime.markdown @@ -12,9 +12,13 @@ ha_category: Automation ha_release: 0.55 --- -The `input_datetime` component allows the user to define date and time values that can be controlled via the frontend and can be used within automations and templates. +The `input_datetime` component allows the user to define date and time values +that can be controlled via the frontend and can be used within automations and +templates. -To add three datetime inputs to your installation, one with both date and time, and one with date or time each, add the following lines to your `configuration.yaml`: +To add three datetime inputs to your installation, +one with both date and time, and one with date or time each, +add the following lines to your `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -46,12 +50,12 @@ input_datetime: has_time: description: Set to `true` if the input should have a time. At least one `has_time` or `has_date` must be defined. required: false - type: Boolean + type: boolean default: false has_date: description: Set to `true` if the input should have a date. At least one `has_time` or `has_date` must be defined. required: false - type: Boolean + type: boolean default: false initial: description: Set the initial value of this input, depending on `has_time` and `has_date`. @@ -62,7 +66,8 @@ input_datetime: ### {% linkable_title Attributes %} -A datetime input entity's state exports several attributes that can be useful in automations and templates. +A datetime input entity's state exports several attributes that can be useful in +automations and templates. | Attribute | Description | | ----- | ----- | @@ -74,7 +79,12 @@ A datetime input entity's state exports several attributes that can be useful in ### {% linkable_title Restore State %} -This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. +This component will automatically restore the state it had prior to Home +Assistant stopping as long as you have the `recorder` component enabled and your +entity does **not** have a set value for `initial`. To disable this feature, set +a valid value for `initial`. Additional information can be found in the +[Restore state](/components/recorder/#restore-state) section of the +[`recorder`](/components/recorder/) component documentation. ### {% linkable_title Services %} @@ -87,7 +97,9 @@ This component provides a service to modify the state of the `input_datetime`. ## {% linkable_title Automation Examples %} -The following example shows the usage of the `input_datetime` as a trigger in an automation (note that you will need a [time sensor](/components/sensor.time_date/) elsewhere in your configuration): +The following example shows the usage of the `input_datetime` as a trigger in an +automation (note that you will need a +[time sensor](/components/sensor.time_date/) elsewhere in your configuration): {% raw %} ```yaml @@ -103,7 +115,9 @@ automation: ``` {% endraw %} -To dynamically set the `input_datetime` you can call `input_datetime.set_datetime`. The following example can be used in an automation rule: +To dynamically set the `input_datetime` you can call +`input_datetime.set_datetime`. The following example can be used in an +automation rule: ```yaml # Example configuration.yaml entry diff --git a/source/_components/iota.markdown b/source/_components/iota.markdown index d50ad4f5452..4a367e2e38c 100644 --- a/source/_components/iota.markdown +++ b/source/_components/iota.markdown @@ -13,9 +13,11 @@ ha_release: 0.62 ha_iot_class: "Cloud Polling" --- -[IOTA](http://iota.org/) is a new blockless distributed ledger which is scalable, lightweight and makes it possible to transfer value without any fees. +[IOTA](http://iota.org/) is a new blockless distributed ledger which is +scalable, lightweight and makes it possible to transfer value without any fees. -The `iota` component displays various details (e.g., the balance, node attributes) of IOTA wallets. +The `iota` component displays various details +(e.g., the balance, node attributes) of IOTA wallets. ```yaml # configuration.yaml example @@ -34,8 +36,8 @@ iri: testnet: description: Flag for indicating "testnet". required: false + type: boolean default: false - type: bool wallets: description: List of IOTA wallets. required: true diff --git a/source/_components/joaoapps_join.markdown b/source/_components/joaoapps_join.markdown index 822a14604ba..61ef1c09c9c 100644 --- a/source/_components/joaoapps_join.markdown +++ b/source/_components/joaoapps_join.markdown @@ -12,9 +12,15 @@ ha_category: Hub ha_release: "0.24" --- -The `joaoapps_join` component exposes services from [Join](http://joaoapps.com/join). In Home Assistant, the Join features are divided up in two locations, the Join component, and the Join notify platform. The notify platform allows us to send messages to Join devices, the component allows us to access the other special features that Join offers. +The `joaoapps_join` component exposes services from +[Join](http://joaoapps.com/join). In Home Assistant, the Join features are +divided up in two locations, the Join component, and the Join notify platform. +The notify platform allows us to send messages to Join devices, the component +allows us to access the other special features that Join offers. -In the `configuration.yaml` file you need to provide the api key and device id or name of the target device. You can find your device id and api key [here](https://joinjoaomgcd.appspot.com/). +In the `configuration.yaml` file you need to provide the api key and device id +or name of the target device. You can find your device id and api key +[here](https://joinjoaomgcd.appspot.com/). To set it up, add the following information to your `configuration.yaml` file: @@ -33,20 +39,41 @@ joaoapps_join: api_key: asd97823jb628a34fwsdfwefd5384345tf2d ``` -Configuration variables: +{% configuration %} +api_key: + description: The API key for Join. + required: true + type: string +device_id: + description: The id of your device. + required: false + type: string +device_ids: + description: Comma separated list of device ids. + required: false + type: string +device_names: + description: Comma separated list of device names. + required: false + type: string +{% endconfiguration %} -- **api_key** (*Required*): The API key for Join. -- **device_id** (*Optional*): The id of your device. -- **device_ids** (*Optional*): Comma separated list of device ids. -- **device_names** (*Optional*): Comma separated list of device names. - -The notify service has two optional parameters: `icon` and `vibration`. You can use them like so: +The notify service has two optional parameters: `icon` and `vibration`. +You can use them like so: ```json -{"message":"Hello from Home Assistant!","title":"Home Assistant","data":{"icon":"https://goo.gl/xeetdy", "vibration":"0,65,706,86,657,95,668,100"}} +{ + "message": "Hello from Home Assistant!", + "title": "Home Assistant", + "data": { + "icon": "https://goo.gl/xeetdy", + "vibration": "0,65,706,86,657,95,668,100" + } +} ``` -The services exposed in the `joaoapps_join` component can be used with the service data described below: +The services exposed in the `joaoapps_join` component can be used with the +service data described below: | Service | Data | |------------------------------ |------------------------------------------------------------------ | diff --git a/source/_components/light.ihc.markdown b/source/_components/light.ihc.markdown index 214f19564be..cb2a1c986de 100644 --- a/source/_components/light.ihc.markdown +++ b/source/_components/light.ihc.markdown @@ -13,17 +13,19 @@ ha_release: 0.62 ha_iot_class: "Local Push" --- -Before you can use the IHC Light platform, you must setup the [IHC Component](/components/ihc/) +Before you can use the IHC Light platform, you must setup the +[IHC Component](/components/ihc/) -When auto setup is enabled the following products will be found in the IHC project and setup as light devices: +When auto setup is enabled the following products will be found in the IHC +project and setup as light devices: -* Wireless lamp outlet dimmer -* Wireless dimmer -* Wireless combi dimmer 4 buttons -* Wireless lamp outlet relay -* Wireless combi relay 4 buttons -* Wireless mobile dimmer -* Dataline lamp outlet +- Wireless lamp outlet dimmer +- Wireless dimmer +- Wireless combi dimmer 4 buttons +- Wireless lamp outlet relay +- Wireless combi relay 4 buttons +- Wireless mobile dimmer +- Dataline lamp outlet To manually configure IHC lights insert this section in your configuration: @@ -48,7 +50,7 @@ lights: dimmable: description: Set to True if the IHC resource is a light level required: false - type: bool + type: boolean default: false id: description: The IHC resource id. @@ -60,6 +62,7 @@ lights: type: string {% endconfiguration %} -In the example above 12345 is ihc resource id and "tablelight" is the name. -The IHC resource id can be a light level for dimmers or a boolean output of a relay. -For more information about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup) +In the example above 12345 is ihc resource id and "tablelight" is the name. +The IHC resource id can be a light level for dimmers or a boolean output of a +relay. For more information about IHC resource ids see +[Manual Setup](/components/ihc/#manual-setup). diff --git a/source/_components/logbook.markdown b/source/_components/logbook.markdown index 438e7474306..eb3682fb339 100644 --- a/source/_components/logbook.markdown +++ b/source/_components/logbook.markdown @@ -11,25 +11,55 @@ logo: logbook.png ha_category: "History" --- - The logbook component provides a different perspective on the history of your house by showing all the changes that happened to your house in reverse chronological order. [See the demo for a live example](/demo/). It depends on the `recorder` component for storing the data. This means that if the [`recorder`](/components/recorder/) component is set up to use e.g., MySQL or PostgreSQL as data store, the `logbook` component does not use the default SQLite database to store data. + -To enable the logbook in your installation, add the following to your `configuration.yaml` file: +The logbook component provides a different perspective on the history of your +house by showing all the changes that happened to your house in reverse +chronological order. [See the demo for a live example](/demo/). It depends on +the `recorder` component for storing the data. This means that if the +[`recorder`](/components/recorder/) component is set up to use e.g., MySQL or +PostgreSQL as data store, the `logbook` component does not use the default +SQLite database to store data. + +To enable the logbook in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry logbook: ``` -Configuration variables: +{% configuration %} +exclude: + description: "Configure which components should **not** create logbook entries." + required: false + type: map + keys: + entities: + description: The list of entity ids to be excluded from creating logbook entries. + required: false + type: list + domains: + description: The list of domains to be excluded from creating logbook entries. + required: false + type: list +include: + description: Configure which components should create logbook entries. + required: false + type: map + keys: + entities: + description: The list of entity ids to be included in creating logbook entries. + required: false + type: list + domains: + description: The list of domains to be included in creating logbook entries. + required: false + type: list +{% endconfiguration %} -- **exclude** (*Optional*): Configure which components should **not** create logbook entries. - - **entities** (*Optional*): The list of entity ids to be excluded from creating logbook entries. - - **domains** (*Optional*): The list of domains to be excluded from creating logbook entries. -- **include** (*Optional*): Configure which components should create logbook entries. - - **entities** (*Optional*): The list of entity ids to be included in creating logbook entries. - - **domains** (*Optional*): The list of domains to be included in creating logbook entries. - -If you want to exclude messages of some entities or domains from the logbook just add the `exclude` parameter like: +If you want to exclude messages of some entities or domains from the logbook +just add the `exclude` parameter like: ```yaml # Example of excluding domains and entities from the logbook @@ -43,7 +73,8 @@ logbook: - weblink ``` -In case you just want to see messages from some specific entities or domains use the `include` configuration: +In case you just want to see messages from some specific entities or domains use +the `include` configuration: ```yaml # Example to show how to include only the listed domains and entities in the logbook @@ -55,7 +86,9 @@ logbook: - media_player ``` -You can also use the `include` list and filter out some entities or domains with an `exclude` list. Usually this makes sense if you define domains on the include side and filter out some specific entities. +You can also use the `include` list and filter out some entities or domains with +an `exclude` list. Usually this makes sense if you define domains on the include +side and filter out some specific entities. ```yaml # Example of combining include and exclude configurations @@ -73,14 +106,22 @@ logbook: ### {% linkable_title Exclude Events %} -Entities customized as hidden are excluded from the logbook by default, but sometimes you want to show the entity in the UI and not in the logbook. For instance you use the `sensor.date`to show the current date in the UI, but you do not want a logbook entry for that sensor every day. -To exclude these entities just add them to the `exclude` > `entities` list in the configuration of the logbook. +Entities customized as hidden are excluded from the logbook by default, +but sometimes you want to show the entity in the UI and not in the logbook. +For instance you use the `sensor.date`to show the current date in the UI, +but you do not want a logbook entry for that sensor every day. +To exclude these entities just add them to the `exclude` > `entities` list in +the configuration of the logbook. -To exclude all events from a whole domain add it to the `exclude` > `domain` list. For instance you use the `sun` domain only to trigger automations on the `azimuth attribute, then you possible are not interested in the logbook entries for sun rise and sun set. +To exclude all events from a whole domain add it to the `exclude` > `domain` +list. For instance you use the `sun` domain only to trigger automations on the +`azimuth` attribute, then you possible are not interested in the logbook entries +for sun rise and sun set. ### {% linkable_title Custom Entries %} -It is possible to add custom entries to the logbook by using the script component to fire an event. +It is possible to add custom entries to the logbook by using the script +component to fire an event. ```yaml # Example configuration.yaml entry diff --git a/source/_components/logger.markdown b/source/_components/logger.markdown index d3cef23a013..cbbf133ac79 100644 --- a/source/_components/logger.markdown +++ b/source/_components/logger.markdown @@ -11,16 +11,19 @@ logo: home-assistant.png ha_category: "Utility" --- -The `logger` component lets you define the level of logging activities in Home Assistant. +The `logger` component lets you define the level of logging activities in Home +Assistant. -To enable the `logger` component in your installation, add the following to your `configuration.yaml` file: +To enable the `logger` component in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry logger: ``` -To log all messages and ignore events lower than critical for specified components: +To log all messages and ignore events lower than critical for specified +components: ```yaml # Example configuration.yaml entry @@ -31,7 +34,8 @@ logger: homeassistant.components.camera: critical ``` -To ignore all messages lower than critical and log event for specified components: +To ignore all messages lower than critical and log event for specified +components: ```yaml # Example configuration.yaml entry @@ -102,9 +106,10 @@ data: homeassistant.components.media_player.yamaha: debug ``` -The log information are stored in the [configuration directory](/docs/configuration/) -as `home-assistant.log` and you can read it with the command-line tool `cat` or -follow it dynamically with `tail -f`. +The log information are stored in the +[configuration directory](/docs/configuration/) as `home-assistant.log` +and you can read it with the command-line tool `cat` or follow it dynamically +with `tail -f`. If you are a Hassbian user you can use the example below: diff --git a/source/_components/media_player.epson.markdown b/source/_components/media_player.epson.markdown index e24397901d7..604cef1f731 100644 --- a/source/_components/media_player.epson.markdown +++ b/source/_components/media_player.epson.markdown @@ -13,9 +13,11 @@ ha_release: 0.72 ha_iot_class: "Local Polling" --- -The `epson` platform allows you to control a Epson projector from Home Assistant. +The `epson` platform allows you to control a Epson projector from Home +Assistant. -To add Epson to your installation, add the following to your `configuration.yaml` file: +To add Epson to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -40,9 +42,9 @@ name: type: string default: 'EPSON Projector' ssl: - description: Enable SSL. **Feature not tested.** + description: "Enable SSL. **Feature not tested.**" required: false - type: bool + type: boolean default: false {% endconfiguration %} @@ -60,4 +62,5 @@ Supported devices: Tested devices: - Epson EH-TW5350 -To make this module work you need to connect your projector to your LAN. The best is to use iProjection app by Epson to test if it is working. +To make this module work you need to connect your projector to your LAN. +The best is to use iProjection app by Epson to test if it is working. diff --git a/source/_components/media_player.samsungtv.markdown b/source/_components/media_player.samsungtv.markdown index 69174a09969..407c3823e7f 100644 --- a/source/_components/media_player.samsungtv.markdown +++ b/source/_components/media_player.samsungtv.markdown @@ -14,11 +14,14 @@ ha_release: 0.13 ha_iot_class: "Local Polling" --- -The `samsungtv` platform allows you to control a [Samsung Smart TV](http://www.samsung.com/uk/consumer/tv-audio-video/televisions/). +The `samsungtv` platform allows you to control a +[Samsung Smart TV](http://www.samsung.com/uk/consumer/tv-audio-video/televisions/). -When the TV is first connected, you will need to accept Home Assistant on the TV to allow communication. +When the TV is first connected, +you will need to accept Home Assistant on the TV to allow communication. -To add a TV to your installation, add the following to your `configuration.yaml` file: +To add a TV to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -27,13 +30,30 @@ media_player: host: 192.168.0.10 ``` -Configuration variables: - -- **host** (*Required*): The IP of the Samsung Smart TV, eg. `192.168.0.10`. -- **port** (*Optional*): The port of the Samsung Smart TV. Defaults to 55000. If set to 8001, the new websocket connection will be used (required for 2016+ TVs). -- **name** (*Optional*): The name you would like to give to the Samsung Smart TV. -- **timeout** (*Optional*): The time-out in seconds for the communication with the TV. Defaults to 0 (no timeout). -- **mac** (*Optional*): The MAC address of the Samsung Smart TV, eg. `00:11:22:33:44:55:66`. Required for power on support via wake on lan. +{% configuration %} +host: + description: "The IP of the Samsung Smart TV, eg. `192.168.0.10`." + required: true + type: string +port: + description: The port of the Samsung Smart TV. If set to 8001, the new websocket connection will be used (required for 2016+ TVs). + required: false + type: int + default: 55000 +name: + description: The name you would like to give to the Samsung Smart TV. + required: false + type: string +timeout: + description: The timeout for communication with the TV in seconds. + required: false + type: time + default: 0 (no timeout) +mac: + description: "The MAC address of the Samsung Smart TV, eg. `00:11:22:33:44:55:66`. Required for power on support via wake on lan." + required: false + type: string +{% endconfiguration %} Currently known supported models: @@ -82,14 +102,21 @@ Currently tested but not working models: - JS9000 - State is always "on" and unable to control (but port 8001 *is* open) - JS9500 - State is always "on" and unable to control (but port 8001 *is* open) - MU6300 - Port set to 8001, `pip3 install websocket-client` must be executed, turning on works, status not working reliably, turning off is not permanent (it comes back on) - -None of the 2014 (H) and 2015 (J) model series (e.g., J5200) will work, since Samsung have used a different (encrypted) type of interface for these. -If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/media_player.samsungtv.markdown). -The first letter (U, P, L, H & K) represent the screen type, e.g., LED or Plasma. The second letter represents the region, E is Europe, N is North America and A is Asia & Australia. The two numbers following that represent the screen size. +None of the 2014 (H) and 2015 (J) model series (e.g., J5200) will work, +since Samsung have used a different (encrypted) type of interface for these. + +If your model is not on the list then give it a test, +if everything works correctly then add it to the list on +[GitHub](https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/media_player.samsungtv.markdown). +The first letter (U, P, L, H & K) represent the screen type, e.g., LED or +Plasma. The second letter represents the region, E is Europe, N is North America +and A is Asia & Australia. +The two numbers following that represent the screen size. If you add your model remember to remove these before adding them to the list. -Changing channels can be done by calling the `media_player.play_media` service with the following payload: +Changing channels can be done by calling the `media_player.play_media` service +with the following payload: ```javascript { diff --git a/source/_components/media_player.spotify.markdown b/source/_components/media_player.spotify.markdown index 0f2c27f5d05..775f1beb3d5 100644 --- a/source/_components/media_player.spotify.markdown +++ b/source/_components/media_player.spotify.markdown @@ -14,7 +14,8 @@ ha_release: 0.43 ha_iot_class: "Cloud Polling" --- -The `spotify` media player platform allows you to control [Spotify](https://www.spotify.com/) playback from Home Assistant. +The `spotify` media player platform allows you to control +[Spotify](https://www.spotify.com/) playback from Home Assistant. ## {% linkable_title Prerequisites %} @@ -32,48 +33,79 @@ To create the required Spotify Application: - Select **Create An App**. Enter any name and description. Once your application is created, view it and copy your **Client ID** and **Client Secret**, which are used in the Home Assistant configuration file. - Add a **Redirect URI** in the following forms: - No SSL: `http://:/api/spotify` + No SSL: + `http://:/api/spotify` - If using SSL: `https://:/api/spotify` + If using SSL: + `https://:/api/spotify` -The URL is whatever you use to access Home Assistant from outside your network (including port if applicable). + The URL is whatever you use to access Home Assistant from outside your network + (including port if applicable). - Click **Save** after adding the URI. You may also need to set the `base_url` attribute of the [HTTP Component](/components/http/). - ## {% linkable_title Configuration %} -To add Spotify to your installation, add the following to your `configuration.yaml` file: +To add Spotify to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry media_player: - platform: spotify - client_id: - client_secret: + client_id: YOUR_CLIENT_ID + client_secret: YOUR_CLIENT_SECRET aliases: abc123def456: 'Living Room' 9183abas000: 'Bed Room' ``` -Configuration variables: - -- **client_id** (*Required*): Client ID from your Spotify Application. -- **client_secret** (*Required*): Client Secret from your Spotify Application. -- **cache_path** (*Optional*): Path to cache authentication token (defaults to configuration directory). -- **aliases** (*Optional*): Dictionary of device ids to be aliased, handy for devices that Spotify cannot properly determine the device name of. New devices will be logged to the `info` channel for ease of aliasing. +{% configuration %} +client_id: + description: Client ID from your Spotify Application. + required: true + type: string +client_secret: + description: Client Secret from your Spotify Application. + required: true + type: string +cache_path: + description: Path to cache authentication token (defaults to configuration directory). + required: false + type: string +aliases: + description: "Dictionary of device ids to be aliased, handy for devices that Spotify cannot properly determine the device name of. New devices will be logged to the `info` channel for ease of aliasing." + required: false + type: map +{% endconfiguration %} ## {% linkable_title Setup %} -After the prerequisites and configuration are complete, restart Home Assistant. A **Spotify** configurator element will be available. Follow the instructions to authorize Home Assistant to access your Spotify account. A Spotify media player will then appear. If Spotify prompts you to download a file after completing authorization, discard the download. It is not needed. +After the prerequisites and configuration are complete, restart Home Assistant. +A **Spotify** configurator element will be available. Follow the instructions to +authorize Home Assistant to access your Spotify account. A Spotify media player +will then appear. If Spotify prompts you to download a file after completing +authorization, discard the download. It is not needed. ## {% linkable_title Sources %} -The sources are based on if you have streamed to these devices before in Spotify. If you don't have any sources, then simply stream from your phone to another device in your house, Bluetooth, echo, etc. Once you do the sources will show up in the developer console as a device to cast/stream to. Also know that the devices won't show up in the dev-console as sources unless they are powered on as well. +The sources are based on if you have streamed to these devices before in +Spotify. If you don't have any sources, then simply stream from your phone to +another device in your house, Bluetooth, echo, etc. Once you do the sources will +show up in the developer console as a device to cast/stream to. Also know that +the devices won't show up in the dev-console as sources unless they are powered +on as well. ## {% linkable_title URI Links For Playlists/Etc %} -You can send playlists to spotify via the "media_content_type": "playlist" and "media_content_id": "spotify:user:spotify:playlist:37i9dQZF1DWSkkUxEhrBdF" which are a part of the [media_player.play_media](/components/media_player/#service-media_playerplay_media) service, you can test this from the services control panel in the Home Assistant frontend. +You can send playlists to spotify via the "media_content_type": "playlist" and +"media_content_id": "spotify:user:spotify:playlist:37i9dQZF1DWSkkUxEhrBdF" +which are a part of the +[media_player.play_media](/components/media_player/#service-media_playerplay_media) +service, you can test this from the services +control panel in the Home Assistant frontend. -In this example this is a URI link to the Reggae Infusions playlist, [this support document from Spotify](https://support.spotify.com/us/using_spotify/share_music/why-do-you-have-two-different-link-formats/) explains how to get this URI value to use for playlists in the Spotify component. +In this example this is a URI link to the Reggae Infusions playlist, +[this support document from Spotify](https://support.spotify.com/us/article/sharing-music/) +explains how to get this URI value to use for playlists in the Spotify component. ## {% linkable_title Unsupported devices %} diff --git a/source/_components/media_player.webostv.markdown b/source/_components/media_player.webostv.markdown index a4afa661dad..f321a4807f9 100644 --- a/source/_components/media_player.webostv.markdown +++ b/source/_components/media_player.webostv.markdown @@ -13,20 +13,26 @@ ha_iot_class: "Local Polling" ha_release: 0.18 --- -The `webostv` platform allows you to control a [LG](http://www.lg.com/) webOS Smart TV. +The `webostv` platform allows you to control a [LG](http://www.lg.com/) webOS +Smart TV. ### {% linkable_title Setup %} -To begin with enable *LG Connect Apps* feature in *Network* settings of the TV [instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others). +To begin with enable *LG Connect Apps* feature in *Network* settings of the TV +[instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others). -Once basic configuration is added to your `configuration.yaml` *Configuration* card should prompt on your Home Assistants's states. Follow the instructions and accept pairing request on your TV. - -Pairing information will be saved to the `filename:` provided in configuration; this process is IP sensitive, in case the IP address of your TV would change in future. +Once basic configuration is added to your `configuration.yaml` *Configuration* +card should prompt on your Home Assistants's states. +Follow the instructions and accept pairing request on your TV. +Pairing information will be saved to the `filename:` provided in configuration; +this process is IP sensitive, +in case the IP address of your TV would change in future. ### {% linkable_title Configuration %} -To add a TV to your installation, add the following to your `configuration.yaml` file: +To add a TV to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -34,17 +40,41 @@ media_player: - platform: webostv ``` -Configuration variables: +{% configuration %} +host: + description: "The IP of the LG webOS Smart TV, e.g., `192.168.0.10`." + required: false + type: string +name: + description: The name you would like to give to the LG webOS Smart TV. + required: false + type: string +filename: + description: "The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. **NOTE**: When using multiple TVs each TV will need its own unique file." + required: false + type: string + default: webostv.conf +timeout: + description: The timeout for communication with the TV in seconds. + required: false + type: time +turn_on_action: + description: Defines an [action](/docs/automation/action/) to turn the TV on. + required: false + type: string +customize: + description: List of options to customize. + required: false + type: map + keys: + sources: + description: List of hardware and webOS App inputs. + required: false + type: list +{% endconfiguration %} -- **host** (*Optional*): The IP of the LG webOS Smart TV, e.g., `192.168.0.10`. -- **turn_on_action** (*Optional*): Defines an [action](/docs/automation/action/) to turn the TV on. -- **name** (*Optional*): The name you would like to give to the LG webOS Smart TV. -- **timeout** (*Optional*): The timeout for connections to the TV in seconds. -- **filename** (*Optional*): The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. It defaults to `webostv.conf`. **NOTE**: When using multiple TVs each TV will need its own unique file. -- **customize** array (*Optional*): List of options to customize. - - **sources** array (*Optional*): List of hardware and webOS App inputs. - -If you do not specify `host:`, all LG webOS Smart TVs within your network will be auto-discovered. +If you do not specify `host:`, all LG webOS Smart TVs within your network will +be auto-discovered. ### {% linkable_title Example %} @@ -56,8 +86,8 @@ media_player: - platform: webostv host: 192.168.0.10 name: Living Room TV - timeout: 5 filename: webostv.conf + timeout: 5 turn_on_action: service: persistent_notification.create data: @@ -74,10 +104,18 @@ Avoid using `[ ]` in the `name:` of your device. ### {% linkable_title Turn on action %} -Home Assistant is able to turn on a LG webOS Smart TV if you specify an action, like HDMI-CEC or WakeOnLan. +Home Assistant is able to turn on a LG webOS Smart TV if you specify an action, +like HDMI-CEC or WakeOnLan. -Common for webOS 3.0 and higher would be to use WakeOnLan feature. -To use this feature your TV should be connected to your network via Ethernet rather than Wireless and you should enable *LG Connect Apps* feature in *Network* settings of the TV [instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others) (or *Mobile App* in *General* settings for older models) (*may vary by version). On newer models (2017+), WakeOnLan may need to be enabled in the TV settings by going to Settings > General > Mobile TV On > Turn On Via WiFi [instructions](https://support.quanticapps.com/hc/en-us/articles/115005985729-How-to-turn-on-my-LG-Smart-TV-using-the-App-WebOS-). +Common for webOS 3.0 and higher would be to use WakeOnLan feature. +To use this feature your TV should be connected to your network via Ethernet rather than +Wireless and you should enable *LG Connect Apps* feature in *Network* settings of the TV +[instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others) +(or *Mobile App* in *General* settings for older models) (*may vary by version). + +On newer models (2017+), WakeOnLan may need to be enabled in the TV settings +by going to Settings > General > Mobile TV On > Turn On Via WiFi +[instructions](https://support.quanticapps.com/hc/en-us/articles/115005985729-How-to-turn-on-my-LG-Smart-TV-using-the-App-WebOS-). ```yaml # Example configuration.yaml entry @@ -93,16 +131,23 @@ media_player: mac: "B4-E6-2A-1E-11-0F" ``` -Any other [actions](/docs/automation/action/) to power on the device can be configured. +Any other [actions](/docs/automation/action/) to power on the device can be +configured. ### {% linkable_title Sources %} -To obtain complete list of available sources currently configured on the TV, once the webOS TV is configured and linked, while its powered on head to the **Developer Tools** > **States**, find your `media_player.` and use the sources listed in `source_list:` remembering to split them per line into your `sources:` configuration. +To obtain complete list of available sources currently configured on the TV, +once the webOS TV is configured and linked, while its powered on head to the +**Developer Tools** > **States**, +find your `media_player.` and use the sources listed in `source_list:` +remembering to split them per line into your `sources:` configuration. ### {% linkable_title Change channel through play_media service %} -The `play_media` service can be used in a script to switch to the specified tv channel. -It selects the best matching cannel according to the `media_content_id` parameter: +The `play_media` service can be used in a script to switch to the specified tv +channel. It selects the best matching cannel according to the `media_content_id` +parameter: + 1. Channel number *(i.e. '1' or '6')* 2. Exact channel name *(i.e. 'France 2' or 'CNN')* 3. Substring in channel name *(i.e. 'BFM' in 'BFM TV')* @@ -125,7 +170,8 @@ data: ### {% linkable_title Next/Previous buttons %} -The behaviour of the next and previsous buttons is different depending on the active source: +The behaviour of the next and previsous buttons is different depending on the +active source: - if the source is 'LiveTV' (television): next/previous buttons act as channel up/down - otherwise: next/previous buttons act as next/previous track diff --git a/source/_components/microsoft_face.markdown b/source/_components/microsoft_face.markdown index 2d9cb4318f4..1375109e276 100644 --- a/source/_components/microsoft_face.markdown +++ b/source/_components/microsoft_face.markdown @@ -12,15 +12,25 @@ ha_category: Image Processing ha_release: "0.37" --- -The `microsoft_face` component platform is the main component for Microsoft Azure Cognitive service [Face](https://www.microsoft.com/cognitive-services/en-us/face-api). All data are stored in your own private instance in the Azure cloud. +The `microsoft_face` component platform is the main component for Microsoft +Azure Cognitive service +[Face](https://azure.microsoft.com/en-us/services/cognitive-services/face/). +All data are stored in your own private instance in the Azure cloud. ## {% linkable_title Setup %} -You need an API key, which is free, but requires an [Azure registration](https://azure.microsoft.com/de-de/free/) using your Microsoft ID. The free resource (*F0*) is limited to 20 requests per minute and 30k requests in a month. If you don't want to use the Azure cloud, you can also get an API key by registering with [cognitive-services](https://www.microsoft.com/cognitive-services/en-us/subscriptions). Please note that all keys on cognitive services must be recreated every 90 days. +You need an API key, which is free, but requires an +[Azure registration](https://azure.microsoft.com/en-us/free/) using your +Microsoft ID. The free resource (*F0*) is limited to 20 requests per minute and +30k requests in a month. If you don't want to use the Azure cloud, you can also +get an API key by registering with +[cognitive-services](https://azure.microsoft.com/en-us/try/cognitive-services/). +Please note that all keys on cognitive services must be recreated every 90 days. ## {% linkable_title Configuration %} -To enable the Microsoft Face component, add the following to your `configuration.yaml`: +To enable the Microsoft Face component, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -29,17 +39,31 @@ microsoft_face: azure_region: eastus2 ``` -Configuration variables: - -- **api_key** (*Required*): The API key for your Cognitive resource. -- **azure_region** (*Optional*): The region where you instantiated your Microsoft Cognitive services endpoint -- **timeout** (*Optional)*: Set timeout for the API connection. Defaults to 10s. +{% configuration %} +api_key: + description: The API key for your Cognitive resource. + required: true + type: string +azure_region: + description: The region where you instantiated your Microsoft Cognitive services endpoint. + required: false + type: string +timeout: + description: Set timeout for the API connection. + required: false + type: time + default: 10s +{% endconfiguration %} ### {% linkable_title Person and Groups %} -For most services, you need to set up a group or a person. This limits the processing and detection to elements provided by the group. Home Assistant creates an entity for all groups and allows you to show the state, person, and IDs directly on the frontend. +For most services, you need to set up a group or a person. +This limits the processing and detection to elements provided by the group. +Home Assistant creates an entity for all groups and allows you to show the +state, person, and IDs directly on the frontend. -The following services are available for managing this feature and can be called via the Frontend, a script, or the REST API. +The following services are available for managing this feature and can be called +via the Frontend, a script, or the REST API. - *microsoft_face.create_group* - *microsoft_face.delete_group* @@ -60,7 +84,9 @@ data: name: 'Hans Maier' ``` -You need to add an image of a person. You can add multiple images for every person to make the detection better. You can take a picture from a camera or send a local image to your Azure resource. +You need to add an image of a person. You can add multiple images for every +person to make the detection better. You can take a picture from a camera or +send a local image to your Azure resource. - *microsoft_face.face_person* @@ -72,7 +98,8 @@ data: camera_entity: camera.door ``` -For the local image we need `curl`. The `{personId}` is present in group entity as attribute. +For the local image we need `curl`. +The `{personId}` is present in group entity as attribute. ```bash $ curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/persongroups/{GroupName}/persons/{personId}/persistedFaces" \ @@ -80,7 +107,8 @@ $ curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/persongr -H "Content-Type: application/octet-stream" --data-binary "@/tmp/image.jpg" ``` -After we're done with changes on a group, we need train this group to teach the AI how to handle the new data. +After we're done with changes on a group, +we need train this group to teach the AI how to handle the new data. - *microsoft_face.train_group* diff --git a/source/_components/notify.html5.markdown b/source/_components/notify.html5.markdown index 5ab7ad0d179..029f6514478 100644 --- a/source/_components/notify.html5.markdown +++ b/source/_components/notify.html5.markdown @@ -12,28 +12,42 @@ ha_category: Notifications ha_release: 0.27 --- -The `html5` notification platform enables you to receive push notifications to Chrome or Firefox, no matter where you are in the world. `html5` also supports Chrome and Firefox on Android, which enables native-app-like integrations without actually needing a native app. +The `html5` notification platform enables you to receive push notifications to +Chrome or Firefox, no matter where you are in the world. `html5` also supports +Chrome and Firefox on Android, which enables native-app-like integrations +without actually needing a native app.

HTML5 push notifications **do not** work on iOS.

-To enable this platform, add the following lines to your `configuration.yaml` file: +To enable this platform, +add the following lines to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry notify: - - name: NOTIFIER_NAME - platform: html5 + - platform: html5 + name: NOTIFIER_NAME gcm_api_key: 'gcm-server-key' gcm_sender_id: 'gcm-sender-id' ``` -Configuration variables: - -- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. -- **gcm_api_key** (*Required if pushing to Chrome*): The API Server key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. -- **gcm_sender_id** (*Required if pushing to Chrome*): The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. +{% configuration %} +name: + description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`. + required: false + type: string + default: notify +gcm_api_key: + description: The API Server key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. + required: true + type: string +gcm_sender_id: + description: The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. + required: true + type: string +{% endconfiguration %} ### {% linkable_title Getting ready for Chrome %} @@ -92,13 +106,17 @@ Assuming the previous test completed successfully and your browser was registere ### {% linkable_title Usage %} -The `html5` platform accepts a standard notify payload. However, there are also some special features built in which you can control in the payload. +The `html5` platform accepts a standard notify payload. However, there are also +some special features built in which you can control in the payload. -Any JSON examples below can be [converted to YAML](https://www.json2yaml.com/) for automations. +Any JSON examples below can be [converted to YAML](https://www.json2yaml.com/) +for automations. #### {% linkable_title Actions %} -Chrome supports notification actions, which are configurable buttons that arrive with the notification and can cause actions on Home Assistant to happen when pressed. You can send [up to 2 actions](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&sq=package:chromium&dr=CSs&l=14). +Chrome supports notification actions, +which are configurable buttons that arrive with the notification and can cause +actions on Home Assistant to happen when pressed. You can send up to 2 actions. ```json { @@ -121,7 +139,10 @@ Chrome supports notification actions, which are configurable buttons that arrive #### {% linkable_title Data %} -Any parameters that you pass in the notify payload that aren't valid for use in the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `image`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be sent back to you in the [callback events](#automating-notification-events). +Any parameters that you pass in the notify payload that aren't valid for use in +the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `image`, +`lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be +sent back to you in the [callback events](#automating-notification-events). ```json { @@ -135,7 +156,11 @@ Any parameters that you pass in the notify payload that aren't valid for use in #### {% linkable_title Tag %} -By default, every notification sent has a randomly generated UUID (v4) set as its _tag_ or unique identifier. The tag is unique to the notification, _not_ to a specific target. If you pass your own tag in the notify payload you can replace the notification by sending another notification with the same tag. You can provide a `tag` like so: +By default, every notification sent has a randomly generated UUID (v4) set as +its _tag_ or unique identifier. The tag is unique to the notification, _not_ to +a specific target. If you pass your own tag in the notify payload you can +replace the notification by sending another notification with the same tag. +You can provide a `tag` like so: ```json { @@ -147,7 +172,8 @@ By default, every notification sent has a randomly generated UUID (v4) set as it } ``` -Example of adding a tag to your notification. This won't create new notification if there already exists one with the same tag. +Example of adding a tag to your notification. This won't create new notification +if there already exists one with the same tag. ```yaml - alias: Push/update notification of sensor state with tag @@ -165,7 +191,9 @@ Example of adding a tag to your notification. This won't create new notification #### {% linkable_title Targets %} -If you do not provide a `target` parameter in the notify payload a notification will be sent to all registered targets as listed in `html5_push_registrations.conf`. You can provide a `target` parameter like so: +If you do not provide a `target` parameter in the notify payload a notification +will be sent to all registered targets as listed in +`html5_push_registrations.conf`. You can provide a `target` parameter like so: ```json { @@ -187,11 +215,16 @@ If you do not provide a `target` parameter in the notify payload a notification #### {% linkable_title Overrides %} -You can pass any of the parameters listed [here](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/showNotification#Parameters) in the `data` dictionary. Please note, [Chrome specifies](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&sq=package:chromium&dr=CSs&l=21) that the maximum size for an icon is 320px by 320px, the maximum `badge` size is 96px by 96px and the maximum icon size for an action button is 128px by 128px. +You can pass any of the parameters listed +[here](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/showNotification#Parameters) +in the `data` dictionary. Please note, Chrome specifies that the maximum size +for an icon is 320px by 320px, the maximum `badge` size is 96px by 96px and the +maximum icon size for an action button is 128px by 128px. #### {% linkable_title URL %} -You can provide a URL to open when the notification is clicked by putting `url` in the data dictionary like so: +You can provide a URL to open when the notification is clicked by putting `url` +in the data dictionary like so: ```json { @@ -203,11 +236,15 @@ You can provide a URL to open when the notification is clicked by putting `url` } ``` -If no URL or actions are provided, interacting with a notification will open your Home Assistant in the browser. You can use relative URLs to refer to Home Assistant, i.e. `/map` would turn into `https://192.168.1.2:8123/map`. +If no URL or actions are provided, interacting with a notification will open +your Home Assistant in the browser. You can use relative URLs to refer to Home +Assistant, i.e. `/map` would turn into `https://192.168.1.2:8123/map`. ### {% linkable_title Automating notification events %} -During the lifespan of a single push notification, Home Assistant will emit a few different events to the event bus which you can use to write automations against. +During the lifespan of a single push notification, +Home Assistant will emit a few different events to the event bus which you can +use to write automations against. Common event payload parameters are: @@ -219,11 +256,15 @@ Common event payload parameters are: | `target` | The target that this notification callback describes. | | `type` | The type of event callback received. Can be `received`, `clicked` or `closed`. | -You can use the `target` parameter to write automations against a single `target`. For more granularity, use `action` and `target` together to write automations which will do specific things based on what target clicked an action. +You can use the `target` parameter to write automations against a single +`target`. For more granularity, +use `action` and `target` together to write automations which will do specific +things based on what target clicked an action. #### {% linkable_title received event %} -You will receive an event named `html5_notification.received` when the notification is received on the device. +You will receive an event named `html5_notification.received` when the +notification is received on the device. ```yaml - alias: HTML5 push notification received and displayed on device @@ -234,7 +275,9 @@ You will receive an event named `html5_notification.received` when the notificat #### {% linkable_title clicked event %} -You will receive an event named `html5_notification.clicked` when the notification or a notification action button is clicked. The action button clicked is available as `action` in the `event_data`. +You will receive an event named `html5_notification.clicked` when the +notification or a notification action button is clicked. +The action button clicked is available as `action` in the `event_data`. ```yaml - alias: HTML5 push notification clicked @@ -256,7 +299,8 @@ or #### {% linkable_title closed event %} -You will receive an event named `html5_notification.closed` when the notification is closed. +You will receive an event named `html5_notification.closed` when the +notification is closed. ```yaml - alias: HTML5 push notification clicked @@ -267,7 +311,10 @@ You will receive an event named `html5_notification.closed` when the notificatio ### {% linkable_title Making notifications work with NGINX proxy %} -If you use [NGINX](/ecosystem/nginx/) as a proxy with authentication in front of your Home Assistant instance, you may have trouble with receiving events back to Home Assistant. It's because of authentication token that cannot be passed through the proxy. +If you use [NGINX](/ecosystem/nginx/) as a proxy with authentication in front of +your Home Assistant instance, +you may have trouble with receiving events back to Home Assistant. +It's because of authentication token that cannot be passed through the proxy. To solve the issue put additional location into your nginx site's configuration: @@ -281,9 +328,11 @@ location /api/notify.html5/callback { } ``` -This rule check if request have `Authorization` HTTP header and bypass the htpasswd (if you use one). +This rule check if request have `Authorization` HTTP header and bypass the +htpasswd (if you use one). If you still have the problem, even with mentioned rule, try to add this code: + ```bash proxy_set_header Authorization $http_authorization; proxy_pass_header Authorization; diff --git a/source/_components/notify.joaoapps_join.markdown b/source/_components/notify.joaoapps_join.markdown index 2143480d0e3..e5b6c76e90a 100644 --- a/source/_components/notify.joaoapps_join.markdown +++ b/source/_components/notify.joaoapps_join.markdown @@ -12,5 +12,5 @@ ha_category: Notifications ha_release: "0.24" --- -See the [Joaoapps Join component page](/components/joaoapps_join/) for information how to get the join notify platform running. - +See the [Joaoapps Join component page](/components/joaoapps_join/) for +information how to get the join notify platform running. diff --git a/source/_components/notify.webostv.markdown b/source/_components/notify.webostv.markdown index c3dbadfbe4a..41d6e633e0d 100644 --- a/source/_components/notify.webostv.markdown +++ b/source/_components/notify.webostv.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "LG WebOS TV notifications" -description: "Instructions on how to integrate a LG WebOS TV within Home Assistant." +title: "LG webOS TV notifications" +description: "Instructions on how to integrate a LG webOS TV within Home Assistant." date: 2016-04-18 23:24 sidebar: true comments: false @@ -13,11 +13,13 @@ ha_iot_class: "Local Polling" ha_release: 0.18 --- -The `webostv` platform allows you to send notifications to a LG WebOS Smart TV. +The `webostv` platform allows you to send notifications to a LG webOS Smart TV. -When the TV is first connected, you will need to accept Home Assistant on the TV to allow communication. +When the TV is first connected, +you will need to accept Home Assistant on the TV to allow communication. -To add a TV to your installation, add the following to your `configuration.yaml` file and follow the configurator instructions: +To add a TV to your installation, add the following to your `configuration.yaml` +file and follow the configurator instructions: ```yaml # Example configuration.yaml entry @@ -28,12 +30,25 @@ notify: filename: webostv.conf ``` -Configuration variables: - -- **host** (*Required*): The IP of the LG WebOS Smart TV, e.g., 192.168.0.10 -- **name** (*Required*): The name you would like to give to the LG WebOS Smart TV. -- **filename** (*Optional*): The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. It defaults to `webostv.conf`. -- **icon** (*Optional*): The path to an image file to use as the icon in notifications. +{% configuration %} +host: + description: The IP of the LG webOS Smart TV, e.g., 192.168.0.10 + required: true + type: string +name: + description: The name you would like to give to the LG webOS Smart TV. + required: true + type: string +filename: + description: "The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. **NOTE**: When using multiple TVs each TV will need its own unique file." + required: false + type: string + default: webostv.conf +icon: + description: The path to an image file to use as the icon in notifications. + required: false + type: string +{% endconfiguration %} A possible automation could be: @@ -51,7 +66,8 @@ automation: message: "You should open a window! (Livingroom Co2: {{ states.sensor.netatmo_livingroom_co2.state }}ppm)" ``` -The icon can be overridden for individual notifications by providing a path to an alternative icon image to use: +The icon can be overridden for individual notifications by providing a path to +an alternative icon image to use: ```yaml automation: diff --git a/source/_components/sensor.ihc.markdown b/source/_components/sensor.ihc.markdown index b3e91ed9823..3938d8af1d1 100644 --- a/source/_components/sensor.ihc.markdown +++ b/source/_components/sensor.ihc.markdown @@ -13,13 +13,15 @@ ha_release: 0.62 ha_iot_class: "Local Push" --- -Before you can use the IHC Sensor platform, you must setup the [IHC Component](/components/ihc/) +Before you can use the IHC Sensor platform, you must setup the +[IHC Component](/components/ihc/) -When auto setup is enabled the following products will be found in the IHC project and setup as sensors: +When auto setup is enabled the following products will be found in the IHC +project and setup as sensors: -* Dataline temperature sensor - Will insert 2 temperature sensors -* Dataline Humidity - Will insert 1 humidity and 2 temperature sensors (calculated dewpoint) -* Dataline Lux - will insert 1 light and 1 temperature sensor +- Dataline temperature sensor - Will insert 2 temperature sensors +- Dataline Humidity - Will insert 1 humidity and 2 temperature sensors (calculated dewpoint) +- Dataline Lux - will insert 1 light and 1 temperature sensor To manually configure IHC sensors insert this section: @@ -54,6 +56,5 @@ sensors: type: string {% endconfiguration %} -The resource id should be a IHC float resource. -For more information about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup) - +The resource id should be a IHC float resource. For more information about IHC +resource ids see [Manual Setup](/components/ihc/#manual-setup). diff --git a/source/_components/sensor.iota.markdown b/source/_components/sensor.iota.markdown index e907cb2795f..365796a68d6 100644 --- a/source/_components/sensor.iota.markdown +++ b/source/_components/sensor.iota.markdown @@ -13,10 +13,10 @@ ha_release: 0.62 ha_iot_class: "Cloud Polling" --- -The sensors are automatically created if the [IOTA hub](/components/iota/) is present. +The sensors are automatically created if the [IOTA hub](/components/iota/) is +present. Available sensors: - Wallet balance - Node information - diff --git a/source/_components/sensor.speedtest.markdown b/source/_components/sensor.speedtest.markdown index fb95a0cdff2..ac9e65ac30e 100644 --- a/source/_components/sensor.speedtest.markdown +++ b/source/_components/sensor.speedtest.markdown @@ -14,13 +14,18 @@ ha_release: 0.13 ha_iot_class: "Cloud Polling" --- -The `speedtest` sensor component uses the [Speedtest.net](https://speedtest.net/) web service to measure network bandwidth performance. +The `speedtest` sensor component uses the [Speedtest.net](https://speedtest.net/) +web service to measure network bandwidth performance. ## {% linkable_title Configuration %} -By default, it will run every hour. The user can change the update frequency in the configuration by defining the minute, hour, and day for a speed test to run. For the `server_id` check the list of [available servers](https://www.speedtest.net/speedtest-servers.php). +By default, it will run every hour. The user can change the update frequency in +the configuration by defining the minute, hour, and day for a speed test to run. +For the `server_id` check the list of +[available servers](https://www.speedtest.net/speedtest-servers.php). -To add a Speedtest.net sensor to your installation, add the following to your `configuration.yaml` file: +To add a Speedtest.net sensor to your installation, +add the following to your `configuration.yaml` file: Once per hour, on the hour (default): @@ -69,15 +74,24 @@ sensor: type: [int, list] default: 0 manual: - description: True or False to turn manual mode on or off. Manual mode will disable scheduled speed tests. + description: > + `true` or `false` to turn manual mode on or off. + Manual mode will disable scheduled speed tests. required: false - type: bool + type: boolean default: false {% endconfiguration %} -This component uses [speedtest-cli](https://github.com/sivel/speedtest-cli) to gather network performance data from Speedtest.net. Please be aware of the potential [inconsistencies](https://github.com/sivel/speedtest-cli#inconsistency) that this component may display. +This component uses [speedtest-cli](https://github.com/sivel/speedtest-cli) to +gather network performance data from Speedtest.net. +Please be aware of the potential +[inconsistencies](https://github.com/sivel/speedtest-cli#inconsistency) that +this component may display. -When Home Assistant first starts up, the values of the speed test will show as `Unknown`. You can use the service `sensor.update_speedtest` to run a manual speed test and populate the data or just wait for the next regularly scheduled test. You can turn on manual mode to disable the scheduled speed tests. +When Home Assistant first starts up, the values of the speed test will show as +`Unknown`. You can use the service `sensor.update_speedtest` to run a manual +speed test and populate the data or just wait for the next regularly scheduled +test. You can turn on manual mode to disable the scheduled speed tests. ## {% linkable_title Examples %} diff --git a/source/_components/sensor.systemmonitor.markdown b/source/_components/sensor.systemmonitor.markdown index 8f4ee938fea..10da7021396 100644 --- a/source/_components/sensor.systemmonitor.markdown +++ b/source/_components/sensor.systemmonitor.markdown @@ -13,9 +13,12 @@ ha_release: pre 0.7 ha_iot_class: "Local Push" --- -The `systemmonitor` sensor platform allows you to monitor disk usage, memory usage, CPU usage, and running processes. This platform has superseded the process component which is now considered deprecated. +The `systemmonitor` sensor platform allows you to monitor disk usage, +memory usage, CPU usage, and running processes. This platform has superseded the +process component which is now considered deprecated. -To add this platform to your installation, add the following to your `configuration.yaml` file: +To add this platform to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -27,13 +30,22 @@ sensor: - type: memory_free ``` -Configuration variables: +{% configuration %} +resources: + description: Contains all entries to display. + required: true + type: list + keys: + type: + description: The type of the information to display, please check the table below for details. + required: true + arg: + description: Argument to use, please check the table below for details. + required: false +{% endconfiguration %} -- **resources** array (*Required*): Contains all entries to display. - - **type** (*Required*): The type of the information to display, please check the table below for details. - - **arg** (*Optional*): Argument to use, please check the table below for details. - -The table contains types and their argument to use in your `configuration.yaml` file. +The table contains types and their argument to use in your `configuration.yaml` +file. | Type (`type:`) | Argument (`arg:`) | | :------------------ |:--------------------------| @@ -62,7 +74,8 @@ The table contains types and their argument to use in your `configuration.yaml` ## {% linkable_title Linux specific %} -To retrieve all available network interfaces on a Linux System, execute the `ifconfig` command. +To retrieve all available network interfaces on a Linux System, execute the +`ifconfig` command. ```bash $ ifconfig -a | sed 's/[ \t].*//;/^$/d' @@ -70,7 +83,9 @@ $ ifconfig -a | sed 's/[ \t].*//;/^$/d' ## {% linkable_title Windows specific %} -When running this platform on Microsoft Windows, Typically, the default interface would be called `Local Area Connection`, so your configuration might look like: +When running this platform on Microsoft Windows, Typically, +the default interface would be called `Local Area Connection`, +so your configuration might look like: ```yaml sensor: @@ -89,4 +104,4 @@ Wireless LAN adapter Wireless Network Connection: Connection-specific DNS Suffix . : ``` -Where the name is `Wireless Network Connection` +Where the name is `Wireless Network Connection`. diff --git a/source/_components/sensor.version.markdown b/source/_components/sensor.version.markdown index dda7b220fab..20e48d1fcd1 100644 --- a/source/_components/sensor.version.markdown +++ b/source/_components/sensor.version.markdown @@ -13,7 +13,6 @@ logo: home-assistant.png ha_release: 0.52 --- - The `version` sensor platform is displaying the current version of Home Assistant in the frontend. ## {% linkable_title Configuration %} @@ -36,7 +35,9 @@ name: ## {% linkable_title Alternatives %} -This sensor is an alternative to the existing solutions to achieve the same result through various platforms. Remember that you can easily get the installed version on the command line. +This sensor is an alternative to the existing solutions to achieve the same +result through various platforms. +Remember that you can easily get the installed version on the command line. ```bash $ hass --version @@ -44,7 +45,8 @@ $ hass --version Or go to the service developer tool icon **Info** section of the **Developer Tools**. -A [`command_line`](/components/sensor.command_line/) with [`hass`](/docs/tools/hass/) to display your current version. +A [`command_line`](/components/sensor.command_line/) with +[`hass`](/docs/tools/hass/) to display your current version. ```yaml sensor: @@ -53,7 +55,8 @@ sensor: command: "/home/homeassistant/bin/hass --version" ``` -It's also possible to ready a file called `.HA_VERSION` which is located in your Home Assistant [configuration](/docs/configuration/) folder. +It's also possible to ready a file called `.HA_VERSION` which is located in your +Home Assistant [configuration](/docs/configuration/) folder. ```yaml sensor: @@ -62,7 +65,9 @@ sensor: command: "cat /home/homeassistant/.homeassistant/.HA_VERSION" ``` -You might think that a [`rest` sensor](/components/sensor.rest/) could work, too, but it will not as Home Assistant is not ready when the sensor get initialized. +You might think that a [`rest` sensor](/components/sensor.rest/) could work, +too, +but it will not as Home Assistant is not ready when the sensor get initialized. {% raw %} ```yaml diff --git a/source/_components/sensor.xbox_live.markdown b/source/_components/sensor.xbox_live.markdown index ca0aa227891..3311c4f2023 100644 --- a/source/_components/sensor.xbox_live.markdown +++ b/source/_components/sensor.xbox_live.markdown @@ -15,11 +15,17 @@ ha_release: 0.28 The Xbox Live component is able to track [Xbox](http://xbox.com/) profiles. -To use this sensor you need a free API key from [XboxAPI.com](http://xboxapi.com). Please also make sure to connect your Xbox account on that site. +To use this sensor you need a free API key from +[XboxAPI.com](http://xboxapi.com). +Please also make sure to connect your Xbox account on that site. -The configuration requires you to specify XUIDs which are the unique identifiers for profiles. These can be determined on [XboxAPI.com](http://xboxapi.com) by either looking at your own profile page or using their interactive documentation to search for gamertags. +The configuration requires you to specify XUIDs which are the unique identifiers +for profiles. These can be determined on [XboxAPI.com](http://xboxapi.com) by +either looking at your own profile page or using their interactive documentation +to search for gamertags. -To use the Xbox Live sensor in your installation, add the following to your `configuration.yaml` file: +To use the Xbox Live sensor in your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -31,7 +37,13 @@ sensor: - account2 ``` -Configuration variables: - -- **api_key** (*Required*): Your API key from [XboxAPI.com](http://xboxapi.com). -- **xuid** (*Required*): Array of profile XUIDs to be tracked. +{% configuration %} +api_key: + description: Your API key from [XboxAPI.com](http://xboxapi.com). + required: true + type: string +xuid: + description: Array of profile XUIDs to be tracked. + required: true + type: list +{% endconfiguration %} diff --git a/source/_components/sensor.yr.markdown b/source/_components/sensor.yr.markdown index 772fa6560e1..8036ac714fe 100644 --- a/source/_components/sensor.yr.markdown +++ b/source/_components/sensor.yr.markdown @@ -13,11 +13,12 @@ ha_release: 0.11 ha_iot_class: "Cloud Polling" --- +The `yr` platform uses [YR.no](http://www.yr.no/) as a source for current +meteorological data for your location. The weather forecast is delivered by the +Norwegian Meteorological Institute and the NRK. -The `yr` platform uses [YR.no](http://www.yr.no/) as a source for current meteorological data for your location. The -weather forecast is delivered by the Norwegian Meteorological Institute and the NRK. - -To add YR to your installation, add the following to your `configuration.yaml` file: +To add YR to your installation, +add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -25,24 +26,49 @@ sensor: - platform: yr ``` -Configuration variables: - -- **name** (*Optional*): Additional name for the sensors. Default to platform name. -- **forecast** integer (*Optional*): If you want to get forecast data instead of the current weather data, set this to the number of hours that you want to look into the future. -- **monitored_conditions** array (*Optional*): Conditions to display in the frontend. - - **symbol**: A symbol for the current weather. - - **temperature**: The current temperature. - - **humidity**: The relative humidity. - - **fog**: Fog. - - **pressure**: The sea-level air pressure in millibars. - - **precipitation**: The precipitation. - - **dewpointTemperature**: The dew point temperature. - - **windSpeed**: The wind speed. - - **windDirection**: Where the wind is coming from in degrees, with true north at 0° and progressing clockwise. - - **cloudiness**: The cloudiness. - - **lowClouds**: Low cloud level. - - **mediumClouds**: Medium cloud level. - - **highClouds**: High cloud level. +{% configuration %} +name: + description: Additional name for the sensors. + required: false + type: string + default: yr +forecast: + description: If you want to get forecast data instead of the current weather data, set this to the number of hours that you want to look into the future. + required: false + type: int +monitored_conditions: + description: Conditions to display in the frontend. + required: false + type: list + default: symbol + keys: + symbol: + description: A symbol for the current weather. + temperature: + description: The current temperature. + humidity: + description: The relative humidity. + fog: + description: Fog. + pressure: + description: The sea-level air pressure in millibars. + precipitation: + description: The precipitation. + dewpointTemperature: + description: The dew point temperature. + windSpeed: + description: The wind speed. + windDirection: + description: Where the wind is coming from in degrees, with true north at 0° and progressing clockwise. + cloudiness: + description: The cloudiness. + lowClouds: + description: Low cloud level. + mediumClouds: + description: Medium cloud level. + highClouds: + description: High cloud level. +{% endconfiguration %} A full configuration example can be found below: diff --git a/source/_components/sun.markdown b/source/_components/sun.markdown index 2b8cf1e3313..4de53e1fba0 100644 --- a/source/_components/sun.markdown +++ b/source/_components/sun.markdown @@ -11,18 +11,21 @@ logo: home-assistant.png ha_category: Environment --- -The sun component will use your current location to track if the sun is above or below the horizon. The sun can be used within automation as [a trigger with an optional offset to simulate dawn/dusk][automation-trigger]. - -[automation-trigger]: /getting-started/automation-trigger/#sun-trigger +The sun component will use your current location to track if the sun is above or +below the horizon. The sun can be used within automation as +[a trigger with an optional offset to simulate dawn/dusk](/getting-started/automation-trigger/#sun-trigger). ```yaml # Example configuration.yaml entry sun: ``` -Configuration variables: - -- **elevation** (*Optional*): The (physical) elevation of your location, in meters above sea level. Defaults to the `elevation` in `configuration.yaml`, which is retrieved from Google Maps if not set. +{% configuration %} +elevation: + description: "The (physical) elevation of your location, in meters above sea level. Defaults to the `elevation` in `configuration.yaml`, which is retrieved from Google Maps if not set." + required: false + type: int +{% endconfiguration %}

@@ -30,9 +33,11 @@ Configuration variables: ### {% linkable_title Implementation Details %} -The sun's event listener will call the service when the sun rises or sets with an offset. +The sun's event listener will call the service when the sun rises or sets with +an offset. -The sun event need to have the type 'sun', which service to call, which event (sunset or sunrise) and the offset. +The sun event need to have the type 'sun', which service to call, +which event (sunset or sunrise) and the offset. ```json { @@ -50,8 +55,6 @@ The sun event need to have the type 'sun', which service to call, which event (s | `above_horizon` | When the sun is above the horizon. | `below_horizon` | When the sun is below the horizon. - - | State Attributes | Description | | --------- | ----------- | | `next_rising` | Date and time of the next sun rising (in UTC). diff --git a/source/_components/switch.command_line.markdown b/source/_components/switch.command_line.markdown index e2b86da84a5..5811eb9a6e4 100644 --- a/source/_components/switch.command_line.markdown +++ b/source/_components/switch.command_line.markdown @@ -13,8 +13,10 @@ ha_release: pre 0.7 ha_iot_class: "Local Polling" --- - -The `command_line` switch platform issues specific commands when it is turned on and off. This might very well become our most powerful platform as it allows anyone to integrate any type of switch into Home Assistant that can be controlled from the command line, including calling other scripts! +The `command_line` switch platform issues specific commands when it is turned on +and off. This might very well become our most powerful platform as it allows +anyone to integrate any type of switch into Home Assistant that can be +controlled from the command line, including calling other scripts! To enable it, add the following lines to your `configuration.yaml`: @@ -28,19 +30,52 @@ switch: command_off: switch_command off kitchen ``` -Configuration variables: - -- **switches** (*Required*): The array that contains all command switches. - - **identifier** (*Required*): Name of the command switch as slug. Multiple entries are possible. - - **command_on** (*Required*): The action to take for on. - - **command_off** (*Required*): The action to take for off. - - **command_state** (*Optional*): If given, this command will be run. Returning a result code `0` will indicate that the switch is on. - - **value_template** (*Optional*): If specified, `command_state` will ignore the result code of the command but the template evaluating to `true` will indicate the switch is on. - - **friendly_name** (*Optional*): The name used to display the switch in the frontend. +{% configuration %} +switches: + description: The array that contains all command switches. + required: true + type: map + keys: + identifier: + description: Name of the command switch as slug. Multiple entries are possible. + required: true + type: map + keys: + command_on: + description: The action to take for on. + required: true + type: string + command_off: + description: The action to take for off. + required: true + type: string + command_state: + description: "If given, this command will be run. Returning a result code `0` will indicate that the switch is on." + required: false + type: string + value_template: + description: "If specified, `command_state` will ignore the result code of the command but the template evaluating to `true` will indicate the switch is on." + required: false + type: string + friendly_name: + description: The name used to display the switch in the frontend. + required: false + type: string +{% endconfiguration %} A note on `friendly_name`: -When set, the `friendly_name` had been previously used for API calls and backend configuration instead of the `object_id` ("identifier"), but [this behavior is changing](https://github.com/home-assistant/home-assistant/pull/4343) to make the `friendly_name` for display purposes only. This allows users to set an `identifier` that emphasizes uniqueness and predictability for API and config purposes but have a prettier `friendly_name` still show up in the UI. As an additional benefit, if a user wanted to change the `friendly_name` / display name (e.g., from "Kitchen Lightswitch" to "Kitchen Switch" or "Living Room Light", or remove the `friendly_name` altogether), he or she could do so without needing to change existing automations or API calls. See aREST device below for an example. +When set, the `friendly_name` had been previously used for API calls and backend +configuration instead of the `object_id` ("identifier"), but +[this behavior is changing](https://github.com/home-assistant/home-assistant/pull/4343) +to make the `friendly_name` for display purposes only. This allows users to set +an `identifier` that emphasizes uniqueness and predictability for API and config +purposes but have a prettier `friendly_name` still show up in the UI. As an +additional benefit, if a user wanted to change the `friendly_name` / display +name (e.g., from "Kitchen Lightswitch" to "Kitchen Switch" or +"Living Room Light", or remove the `friendly_name` altogether), he or she could +do so without needing to change existing automations or API calls. +See aREST device below for an example. ## {% linkable_title Examples %} @@ -48,7 +83,10 @@ In this section you find some real-life examples of how to use this switch. ### {% linkable_title aREST device %} -The example below is doing the same as the [aREST switch](/components/switch.arest/). The command line tool [`curl`](http://curl.haxx.se/) is used to toggle a pin which is controllable through REST. +The example below is doing the same as the +[aREST switch](/components/switch.arest/). +The command line tool [`curl`](http://curl.haxx.se/) is used to toggle a pin +which is controllable through REST. ```yaml # Example configuration.yaml entry @@ -63,7 +101,10 @@ switch: friendly_name: Kitchen Lightswitch ``` -Given this example, in the UI one would see the `friendly_name` of "Kitchen Light". However, the `identifier` is `arest_pin_four`, making the `entity_id` `switch.arest_pin_four`, which is what one would use in [`automation`](/components/automation/) or in [API calls](/developers/). +Given this example, in the UI one would see the `friendly_name` of +"Kitchen Light". However, the `identifier` is `arest_pin_four`, making the +`entity_id` `switch.arest_pin_four`, which is what one would use in +[`automation`](/components/automation/) or in [API calls](/developers/). ### {% linkable_title Shutdown your local host %} @@ -73,7 +114,6 @@ This switch will shutdown your system that is hosting Home Assistant. This switch will shutdown your host immediately, there will be no confirmation.

- ```yaml # Example configuration.yaml entry switch: @@ -85,8 +125,8 @@ switch: ### {% linkable_title Control your VLC player %} -This switch will control a local VLC media player ([Source](https://community.home-assistant.io/t/vlc-player/106)). - +This switch will control a local VLC media player +([Source](https://community.home-assistant.io/t/vlc-player/106)). ```yaml # Example configuration.yaml entry @@ -100,7 +140,10 @@ switch: ### {% linkable_title Control Foscam Motion Sensor %} -This switch will control the motion sensor of Foscam Webcams which Support CGI Commands ([Source](http://www.ipcamcontrol.net/files/Foscam%20IPCamera%20CGI%20User%20Guide-V1.0.4.pdf)). This switch supports statecmd, which checks the current state of motion detection. +This switch will control the motion sensor of Foscam Webcams which Support CGI +Commands ([Source](http://www.ipcamcontrol.net/files/Foscam%20IPCamera%20CGI%20User%20Guide-V1.0.4.pdf)). +This switch supports statecmd, +which checks the current state of motion detection. ```yaml # Example configuration.yaml entry diff --git a/source/_components/switch.ihc.markdown b/source/_components/switch.ihc.markdown index 67abf63932f..fcdbcf3133b 100644 --- a/source/_components/switch.ihc.markdown +++ b/source/_components/switch.ihc.markdown @@ -13,14 +13,16 @@ ha_release: 0.62 ha_iot_class: "Local Push" --- -Before you can use the IHC Switch platform, you must setup the [IHC Component](/components/ihc/) +Before you can use the IHC Switch platform, you must setup the +[IHC Component](/components/ihc/) -When auto setup is enabled the following products will be found in the ihc project and setup as switch devices: +When auto setup is enabled the following products will be found in the ihc +project and setup as switch devices: -* Wireless plug outlet -* Wireless relay -* Mobile wireless relay -* Dataline plug outlet +- Wireless plug outlet +- Wireless relay +- Mobile wireless relay +- Dataline plug outlet To manually configure IHC switches insert this section in your configuration: @@ -51,6 +53,6 @@ switches: type: string {% endconfiguration %} -The resource id should be a boolean resource. (On/Off) -For more information about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup) - +The resource id should be a boolean resource (On/Off). +For more information about IHC resource ids see +[Manual Setup](/components/ihc/#manual-setup).