jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-22 16:56:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

🔨 Restructure platform pages (#9541)

Browse Source
This commit is contained in:
Klaas Schoute 2019-06-01 01:46:57 +02:00 committed by GitHub
parent 4812b311aa
commit 2d752bcab0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 72 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
source/_components/alarm_control_panel.markdown
View File

@ -7,12 +7,9 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Alarm
ha_release: 0.7.3
---
Home Assistant can give you an interface with is similar to a classic alarm system. There are several panels supported:
- [Alarm.com](/components/alarm_control_panel.alarmdotcom/)
- [Manual](/components/alarm_control_panel.manual/)
- [MQTT](/components/alarm_control_panel.mqtt/)
- [Verisure](/components/verisure/)
Home Assistant can give you an interface with is similar to a classic alarm system.

34
source/_components/binary_sensor.markdown
View File

@ -7,43 +7,13 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Binary Sensor
ha_release: 0.9
---
Binary sensors gather information about the state of devices which have a "digital" return value (either 1 or 0). These can be switches, contacts, pins, etc. These sensors only have two states: **0/off/low/closed/false** and **1/on/high/open/true**. Knowing that there are only two states allows Home Assistant to represent these sensors in a better way in the frontend according to their functionality.
### {% linkable_title Device Class %}
The way these sensors are displayed in the frontend can be modified in the [customize section](/getting-started/customizing-devices/). The following device classes are supported for binary sensors:
- **None**: Generic on/off. This is the default and doesn't need to be set.
- **battery**: `On` means low, `Off` means normal
- **cold**: `On` means cold, `Off` means normal
- **connectivity**: `On` means connected, `Off` means disconnected
- **door**: `On` means open, `Off` means closed
- **garage_door**: `On` means open, `Off` means closed
- **gas**: `On` means gas detected, `Off` means no gas (clear)
- **heat**: `On` means hot, `Off` means normal
- **light**: `On` means light detected, `Off` means no light
- **lock**: `On` means open (unlocked), `Off` means closed (locked)
- **moisture**: `On` means moisture detected (wet), `Off` means no moisture (dry)
- **motion**: `On` means motion detected, `Off` means no motion (clear)
- **moving**: `On` means moving, `Off` means not moving (stopped)
- **occupancy**: `On` means occupied, `Off` means not occupied (clear)
- **opening**: `On` means open, `Off` means closed
- **plug**: `On` means device is plugged in, `Off` means device is unplugged
- **power**: `On` means power detected, `Off` means no power
- **presence**: `On` means home, `Off` means away
- **problem**: `On` means problem detected, `Off` means no problem (OK)
- **safety**: `On` means unsafe, `Off` means safe
- **smoke**: `On` means smoke detected, `Off` means no smoke (clear)
- **sound**: `On` means sound detected, `Off` means no sound (clear)
- **vibration**: `On` means vibration detected, `Off` means no vibration (clear)
- **window**: `On` means open, `Off` means closed
For analog sensors please check the [component overview](/components/#sensor).
<p class='img'>
<img src='/images/screenshots/binary_sensor_classes_icons.png' />
Example of various device classes icons in `On` and `Off` state.
</p>

67
source/_components/camera.markdown
View File

@ -7,10 +7,24 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Camera
ha_release: 0.7
---
The camera component allows you to use IP cameras with Home Assistant. With a little additional work you could use [USB cameras](/blog/2016/06/23/usb-webcams-and-home-assistant/) as well.
The camera component allows you to use IP cameras with Home Assistant.
### {% linkable_title Streaming Video %}
If your camera supports it, and the [`stream`](/components/stream) component is setup, you will be able to stream your cameras in the frontend and on supported media players.
This option will keep the stream alive, and preload the feed on Home Assistant startup. This will result in reduced latency when opening the stream in the frontend, as well as when using the `play_stream` service or Google Assistant integration. It does, however, utilize more resources on your machine, so it is recommended to check CPU usage if you plan to use this feature.
<p class='img'>
<img src='/images/components/camera/preload-stream.png' alt='Screenshot showing Preload Stream option in Home Assistant front end.'>
Example showing the Preload Stream option in the camera dialog.
</p>
### {% linkable_title Services %}
@ -18,6 +32,26 @@ Once loaded, the `camera` platform will expose services that can be called to pe
Available services: `turn_on`, `turn_off`, `enable_motion_detection`, `disable_motion_detection`, `snapshot`, and `play_stream`.
#### {% linkable_title Service `play_stream` %}
Play a live stream from a camera to selected media player(s). Requires [`stream`](/components/stream) component to be set up.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Name of entity to fetch stream from, e.g., `camera.living_room_camera`. |
| `media_player` | no | Name of media player to play stream on, e.g., `media_player.living_room_tv`. |
| `format` | yes | Stream format supported by `stream` component and selected `media_player`. Default: `hls` |
For example, the following action in an automation would send an `hls` live stream to your chromecast.
```yaml
action:
service: camera.play_stream
data:
entity_id: camera.yourcamera
media_player: media_player.chromecast
```
#### {% linkable_title Service `turn_on` %}
Turn on camera. Not all camera models support this service, please consult individual camera page.
@ -100,26 +134,6 @@ action:
```
{% endraw %}
#### {% linkable_title Service `play_stream` %}
Play a live stream from a camera to selected media player(s). Requires [`stream`](/components/stream) component to be set up.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Name of entity to fetch stream from, e.g., `camera.living_room_camera`. |
| `media_player` | no | Name of media player to play stream on, e.g., `media_player.living_room_tv`. |
| `format` | yes | Stream format supported by `stream` component and selected `media_player`. Default: `hls` |
For example, the following action in an automation would send an `hls` live stream to your chromecast.
```yaml
action:
service: camera.play_stream
data:
entity_id: camera.yourcamera
media_player: media_player.chromecast
```
### {% linkable_title Test if it works %}
A simple way to test if you have set up your `camera` platform correctly, is to use <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> **Services** from the **Developer Tools**. Choose your service from the dropdown menu **Service**, enter something like the sample below into the **Service Data** field, and hit **CALL SERVICE**.
@ -128,13 +142,4 @@ A simple way to test if you have set up your `camera` platform correctly, is to
{
"entity_id": "camera.living_room_camera"
}
```
### {% linkable_title Preload Stream %}
If your camera supports it, and the [`stream`](/components/stream) component is setup, You will notice a "Preload Stream" option in the top right of the dialog when clicking to view the camera stream. This option will keep the stream alive, and preload the feed on Home Assistant startup. This will result in reduced latency when opening the stream in the frontend, as well as when using the `play_stream` service or Google Assistant integration. It does, however, utilize more resources on your machine, so it is recommended to check CPU usage if you plan to use this feature.
<p class='img'>
<img src='/images/components/camera/preload-stream.png' alt='Screenshot showing Preload Stream option in Home Assistant front end.'>
Example showing the Preload Stream option in the camera dialog.
</p>
```

21
source/_components/climate.markdown
View File

@ -7,19 +7,12 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Climate
ha_release: 0.19
---
The `climate` component is built for the controlling and monitoring of HVAC (heating, ventilating, and air conditioning) and thermostat devices.
To enable this component, pick one of the platforms, and add it to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
climate:
platform: demo
```
## {% linkable_title Services %}
@ -238,13 +231,3 @@ Turn climate device off
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Targets all when omitted.
#### {% linkable_title Customization %}
The step for the setpoint can be adjusted (default to 0,5 increments) by adding the following line into configuration
```yaml
customize:
- entity_id
target_temp_step: 1
```

24
source/_components/cover.markdown
View File

@ -7,33 +7,13 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Cover
ha_release: 0.27
---
Home Assistant can give you an interface to control covers such as rollershutters, blinds, and garage doors.
The display style of each entity can be modified in the [customize section](/getting-started/customizing-devices/). Besides the basic ones like `friendly_name` or `hidden`, the following attributes are supported for covers:
| Attribute | Default | Description |
| --------- | ------- | ----------- |
| `device_class` | | see below
| `assumed_state` | `false` | If set to `true`, cover buttons will always be enabled
### {% linkable_title Device Class %}
The way these sensors are displayed in the frontend can be modified in the [customize section](/docs/configuration/customizing-devices/). The following device classes are supported for covers:
- **None**: Generic cover. This is the default and doesn't need to be set.
- **awning**: Control of an awning, such as an exterior retractable window, door, or patio cover.
- **blind**: Control of blinds, which are linked slats that expand or collapse to cover an opening or may be tilted to partially covering an opening, such as window blinds.
- **curtain**: Control of curtains or drapes, which is often fabric hung above a window or door that can be drawn open.
- **damper**: Control of a mechanical damper that reduces airflow, sound, or light.
- **door**: Control of a door or gate that provides access to an area.
- **garage**: Control of a garage door that provides access to a garage.
- **shade**: Control of shades, which are a continuous plane of material or connected cells that expanded or collapsed over an opening, such as window shades.
- **shutter**: Control of shutters, which are linked slats that swing out/in to covering an opening or may be tilted to partially cover an opening, such as indoor or exterior window shutters.
- **window**: Control of a physical window that opens and closes or may tilt.
## {% linkable_title Services %}
### {% linkable_title Cover control services %}

34
source/_components/device_tracker.markdown
View File

@ -7,14 +7,12 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Presence Detection
ha_release: 0.7
---
Home Assistant can get information from your wireless router or third party services like iCloud or OwnTracks to track which devices are connected and considered "in home". Please check the sidebar for a list of brands of supported wireless routers and services.
There are also trackers available which use different technologies like [MQTT](/components/mqtt/) or [Nmap](/components/nmap_tracker/) to scan the network for devices.
An [event](/getting-started/automation-trigger/#event-trigger) (`device_tracker_new_device`) will be fired when a device is discovered for the first time.
The device tracker allows you to track devices in Home Assistant. This can happen by querying your wireless router or by having applications push location info.
## {% linkable_title Configuring a `device_tracker` platform %}
@ -24,8 +22,8 @@ To get started add the following lines to your `configuration.yaml` (example for
# Example configuration.yaml entry for Netgear device
device_tracker:
- platform: netgear
host: 192.168.1.1
username: admin
host: IP_ADDRESS
username: YOUR_USERNAME
password: YOUR_PASSWORD
new_device_defaults:
track_new_devices: true
@ -54,8 +52,8 @@ The extended example from above would look like the following sample:
# Example configuration.yaml entry for Netgear device
device_tracker:
- platform: netgear
host: 192.168.1.1
username: admin
host: IP_ADDRESS
username: YOUR_USERNAME
interval_seconds: 10
consider_home: 180
new_device_defaults:
@ -94,24 +92,6 @@ devicename:
| `hide_if_away` | false | If `yes`/`on`/`true` then the device will be hidden if it is not at home. |
| `consider_home` | [uses platform setting] | Seconds to wait till marking someone as not home after not being seen. Allows you to override the global `consider_home` setting from the platform configuration on a per device level. |
## {% linkable_title Using GPS device trackers with local network device trackers %}
GPS based device trackers (like [OwnTracks](/components/owntracks/), [GPSLogger](/components/gpslogger) and others) can also be used with local network device trackers, such as [Nmap](/components/nmap_tracker/) or [Netgear](/components/netgear/). To do this, fill in the `mac` field to the entry in `known_devices.yaml` with the MAC address of the device you want to track. This way the state of the device will be determined by *the source that reported last*. The naming convention for known device list is `<username>_<device-id>` and could be set in the app configuration.
An example showing the inclusion of the `mac` field for multiple platform tracking. The `mac` field was added to the GPS based device tracker entry and will enable tracking by all platforms that track via the `mac` address.
```yaml
USERNAME_DEVICE_ID:
name: Friendly Name
mac: EA:AA:55:E7:C6:94
picture: https://www.home-assistant.io/images/favicon-192x192.png
gravatar: test@example.com
track: true
hide_if_away: false
```
If you want to track whether either your GPS based tracker or your local network tracker, identify you as being at home, use [a group](/components/group/) instead.
## {% linkable_title Device states %}
The state of your tracked device will be `'home'` if it is in the [home zone](/components/zone#home-zone), detected by your network or Bluetooth based presence detection. If you're using a presence detection method that includes coordinates then when it's in a zone the state will be the name of the zone (case sensitive). When a device isn't at home and isn't in any zone, the state will be `'not_home'`.

14
source/_components/fan.markdown
View File

@ -7,17 +7,9 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Fan
ha_release: 0.27
---
The `fan` component is built for the controlling of fan devices. It can be called the little brother of the [climate](/components/climate/) component.
To enable this component, pick one of the platforms, and add it to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
climate:
platform: fan
```
The `fan` component is built for the controlling of fan devices.

10
source/_components/light.markdown
View File

@ -7,14 +7,12 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Light
ha_release: pre 0.7
---
This component allows you to track and control various light bulbs. Read the platform documentation for your particular light hardware to learn how to enable it.
<p class='note'>
The light component supports multiple entries in <code>configuration.yaml</code> by appending a sequential number to the section: <code>light 2:</code>, <code>light 3:</code> etc.
</p>
This component allows you to track and control various light bulbs. Read the integration documentation for your particular light hardware to learn how to enable it.
### {% linkable_title Default turn-on values %}
@ -26,7 +24,7 @@ The `.default` suffix should be added to the entity identifier of each light to
Turns one light on or multiple lights on using [groups]({{site_root}}/components/group/).
Most lights do not support all attributes. You can check the platform documentation of your particular light for hints, but in general, you will have to try things out and see what works.
Most lights do not support all attributes. You can check the integration documentation of your particular light for hints, but in general, you will have to try things out and see what works.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |

2
source/_components/lock.markdown
View File

@ -7,6 +7,8 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Lock
ha_release: 0.9
---

4
source/_components/media_player.markdown
View File

@ -7,10 +7,12 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Media Player
ha_release: 0.7
---
Interacts with media players on your network. Please check the right sidebar for a full list of supported devices.
Interacts with media players on your network.
## {% linkable_title Services %}

16
source/_components/notify.markdown
View File

@ -7,6 +7,8 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Notifications
ha_release: 0.7
---
@ -14,19 +16,7 @@ The `notify` component makes it possible to send notifications to a wide variety
If you want to send notifications to the Home Assistant Web Interface you may use the [Persistent Notification Component](/components/persistent_notification/).
## {% linkable_title Configuration %}
```yaml
# Example configuration.yaml entry
notify:
- platform: pushbullet
name: NOTIFY_NAME
api_key: YOUR_API_KEY
```
The **name** parameter is optional but needed if you want to use multiple platforms. The platform will be exposed as service `notify.<name>`. The name will default to `notify` if not supplied.
### {% linkable_title Service %}
## {% linkable_title Service %}
Once loaded, the `notify` platform will expose a service that can be called to send notifications.

19
source/_components/sensor.markdown
View File

@ -7,28 +7,15 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Sensor
ha_release: 0.7
---
Sensors are gathering information about states and conditions.
Home Assistant currently supports a wide range of sensors. They are able to display information which are provides by Home Assistant directly, are gathered from web services, and, of course, physical devices. Please check the sidebar for a full list of supported sensor platforms.
## {% linkable_title Device Class %}
The way these sensors are displayed in the frontend can be modified in the [customize section](/docs/configuration/customizing-devices/). The following device classes are supported for sensors:
- **None**: Generic sensor. This is the default and doesn't need to be set.
- **battery**: Percentage of battery that is left.
- **humidity**: Percentage of humidity in the air.
- **illuminance**: The current light level in lx or lm.
- **signal_strength**: Signal strength in dB or dBm.
- **temperature**: Temperature in °C or °F.
- **power**: Power in W or kW.
- **pressure**: Pressure in hPa or mbar.
- **timestamp**: Datetime object or timestamp string.
Home Assistant currently supports a wide range of sensors. They are able to display information which are provides by Home Assistant directly, are gathered from web services, and, of course, physical devices.
<p class='img'>
<img src='/images/screenshots/sensor_device_classes_icons.png' />
Example of various device class icons for sensors.
</p>

2
source/_components/switch.markdown
View File

@ -7,6 +7,8 @@ sidebar: true
comments: false
sharing: true
footer: true
ha_category:
- Switch
ha_release: 0.7
---