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-19 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/current' into next

Browse Source
This commit is contained in:
Paulus Schoutsen 2016-11-04 23:24:11 -07:00
commit c1148f8ec4
89 changed files with 1460 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
README.markdown
View File

@ -13,24 +13,3 @@ In order to make the preview available on [http://127.0.0.1:4000](http://127.0.0
```bash
$ rake preview
```
### Setup on Fedora and CentOS
On Fedora 22 and later or CentOS 7.1.1503, Ruby is not available by default. Please take the notes here as a little guide for the Ruby installation process.
```bash
$ curl -sSL https://rvm.io/mpapis.asc | gpg2 --import -
$ curl -L get.rvm.io | bash -s stable
$ source ~/.profile
$ rvm requirements
$ rvm install ruby-2.2.3
$ rvm use ruby-2.2.3 --default
$ ruby -v
```
The last command will give you something like this: `ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-linux]`. Then install `bundler`.
```bash
$ gem install bundler
```
Now you can follow the [setup instructions](https://home-assistant.io/developers/website/).

4
_config.yml
View File

@ -72,6 +72,10 @@ collections:
output: true
cookbook:
output: true
ecosystem:
output: true
details:
output: true
topics:
output: true

13
source/_components/alexa.markdown
View File

@ -337,19 +337,24 @@ Please refer to the [Amazon documentation][flash-briefing-api-docs] for more inf
### {% linkable_title Configuring your Flash Briefing skill %}
- Log in to [Amazon developer console][amazon-dev-console]
- Click the Alexa button at the top of the console
- Click the Alexa navigation tab at the top of the console
- Click on the "Get Started >" button under "Alexa Skills Kit"
- Click the yellow "Add a new skill" button in the top right
- Skill Information
- For Skill Type select Flash Briefing Skill API
- For Skill Type select "Flash Briefing Skill API"
- You can enter whatever name you want
- Hit next
- Hit "Next"
- Interaction Model
- Nothing to do here
- Configuration
- Add new feed
- For URL, enter `https://YOUR_HOST/api/alexa/flash_briefings/BRIEFING_ID?api_password=YOUR_API_PASSWORD` where `BRIEFING_ID` is the key you entered in your configuration (such as `whoishome` in the above example)
- For URL, enter `https://YOUR_HOST/api/alexa/flash_briefings/BRIEFING_ID?api_password=YOUR_API_PASSWORD` where `BRIEFING_ID` is the key you entered in your configuration (such as `whoishome` in the above example). **NOTE:** Do not use a non-standard http or https port, AWS will not connect to it.
- You can use this [specially sized Home Assistant logo][large-icon] as the Feed Icon
- All other settings are up to you
- Hit "Next"
- Test
- Having passed all validations to reach this screen you can now click on "< Back to All Skills" as your flash briefing is now available as in "Development" service.
- To invoke your flash briefing, open the Alexa app on your phone or go to [Alexa|http://alexa.amazon.com/], open the "Skills" configuration section, select "Your Skills", scroll to the bottom, tap on the Flash Briefing Skill you just created, enable it, then manage Flash Briefing and adjust ordering as necessary. Finally ask your Echo for your "news","flash briefing", or "briefing".
[amazon-dev-console]: https://developer.amazon.com
[flash-briefing-api]: https://developer.amazon.com/alexa-skills-kit/flash-briefing

2
source/_components/binary_sensor.concord232.markdown
View File

@ -8,7 +8,7 @@ comments: false
sharing: true
footer: true
logo: interlogix.png
ha_category: Binary sensor
ha_category: Binary Sensor
ha_release: 0.31
---

35
source/_components/binary_sensor.rest.markdown
View File

@ -56,9 +56,13 @@ Configuration variables:
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value.
- **payload** (*Optional*): The payload to send with a POST request. Usualy formed as a dictionary.
- **verify_ssl** (*Optional*): Verify the certification of the endpoint. Default to True.
- **authentication** (*Optional*): Type of the HTTP authentication. `basic` or `digest`.
- **username** (*Optional*): The username for accessing the REST endpoint.
- **password** (*Optional*): The password for accessing the REST endpoint.
- **headers** (*Optional*): The headers for the requests.
<p class='note warning'>
Make sure that the URL matches exactly your endpoint or resource.
Make sure that the URL exactly matches your endpoint or resource.
</p>
@ -68,7 +72,7 @@ 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 could the value of a device supporting aREST directly retrieved 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:
@ -77,6 +81,31 @@ binary_sensor:
method: GET
name: Light
sensor_class: light
value_template: '{{ value_json.return_value }}'
value_template: {% raw %}'{{ value_json.return_value }}'{% endraw %}
```
### {% linkable_title Accessing an HTTP authentication protected endpoint %}
The REST sensor supports HTTP authentication and customized headers.
```yaml
binary_sensor:
- platform: rest
resource: http://IP_ADDRESS:5000/binary_sensor
username: ha1
password: test1
authentication: basic
headers:
User-Agent: Home Assistant
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.
```bash
Content-Length: 1024
Host: IP_ADDRESS1:5000
Authorization: Basic aGExOnRlc3Qx
Accept-Encoding: identity
Content-Type: application/json
User-Agent: Home Assistant

13
source/_components/device_tracker.icloud.markdown
View File

@ -25,12 +25,14 @@ device_tracker:
- platform: icloud
username: USERNAME
password: PASSWORD
account_name: accountname
```
Configuration variables:
- **username** (*Required*): The username for the iCloud account.
- **password** (*Required*): The password for your given username.
- **account_name** (*Optional*): The friendly name for the account_name. If this isn't given, it will use the account_name of the username (so the part before the `@` in the email address).
<p class='note warning'>
This may cause battery drainage as it wakes up your device to get the current location.
@ -40,7 +42,12 @@ This may cause battery drainage as it wakes up your device to get the current lo
You may receive an email from Apple stating that someone has logged into your account.
</p>
<p class='note warning'>
If you have two-factor authentication enabled on your iCloud account you will not be able to use this presence detection in HA, even with an app-specific password.
</p>
To disable the drainage of the battery, a dynamic interval is being used for each individual device instead of a fixed interval for all devices linked to one account. The dynamic interval is based on the current zone of a device, the distance towards home and the battery level of the device.
2 Factor Authentication is enabled for iCloud. The component will ask which device you want to use as Trusted Device and then you can enter the code that has been sent to that device. The duration of this authentication is determined by Apple, but is now at 2 months, so you will only need to verify your account each two months, even after restarting Home Assistant.
4 services are available for this component:
- **icloud_update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional.
- **icloud_lost_iphone**: This service will play the Lost iPhone sound on a certain iDevice. The `account_name` and `device_name` are optional.
- **icloud_set_interval**: This service will change the dynamic interval of an iDevice. The `account_name` and `device_name` are optional. If `interval` is used in the service_data, the iDevice will be updated with that new interval. That interval will be fixed until the iDevice changes zone or if this service is called again. If `interval` isn't used in the service_data, the interval for that iDevice will revert back to it's default dynamic interval based on it's current zone, it's distance towards home and it's battery level.
- **icloud_reset_account**: This service can be used to reset an iCloud account. This is helpful when not all devices are being found by the component or if you have added a new iDevice to your account. The `account_name` is optional.

2
source/_components/device_tracker.markdown
View File

@ -73,7 +73,7 @@ devicename:
| `name` | Host name or "Unnamed Device" | The friendly name of the device |
| `mac` | None | The MAC address of the device. Add this if you are using a network device tracker like Nmap or SNMP |
| `icon` | None | A name of an MDI Icon. |
| `picture` | None | A picture that you can use to easily identify the person or device, if provided, will override 'icon' |
| `picture` | None | A picture that you can use to easily identify the person or device. You can also save the image file in a folder "www" in the same location (can be obtained from developer tools) where you have your configuration.yaml file and just use `picture: /local/favicon-192x192.png`. |
| `gravatar` | None | An email address for the device's owner. If provided, it will override `picture` |
| `track` | False | If `yes`/`on`/`true` then the device will be tracked. Otherwise its location and state will not update |
| `hide_if_away` | False | If `yes`/`on`/`true` then the device will be hidden if it is not at home |

2
source/_components/device_tracker.tomato.markdown
View File

@ -15,6 +15,8 @@ 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.
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:
```yaml

12
source/_components/discovery.markdown
View File

@ -18,7 +18,13 @@ Home Assistant can discover and automatically configure zeroconf/mDNS and uPnP d
* Belkin WeMo switches
* Philips Hue
* Netgear routers
* Plex Media Server
* Plex media server
* Panasonic Viera
* Roku media player
* Sono Speaker
* Yamaha media player
* Logitech media server (Squeezebox)
* DirecTV
It will be able to add Google Chromecasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user.
@ -30,8 +36,8 @@ discovery:
```
<p class='note'>
The home-assistant server must be on the same network as the devices for uPnP discovery to work.
If running home-assistant in a docker container use switch `--net=host` to put it on the host's network.
Home Assistant must be on the same network as the devices for uPnP discovery to work.
If running Home Assistant in a Docker container use switch `--net=host` to put it on the host's network.
</p>
If you are developing a new platform, please read [how to make your platform discoverable]({{site_root}}/developers/add_new_platform/#discovery).

7
source/_components/emulated_hue.markdown
View File

@ -84,6 +84,13 @@ The following are attributes that can be applied in the `customize` section:
- **emulated_hue** (*Optional*): Whether or not the entity should be exposed by the emulated Hue bridge. The default value for this attribute is controlled by the `expose_by_default` option.
- **emulated_hue_name** (*Optional*): The name that the emulated Hue will use. The default for this is the entity's friendly name.
### {% linkable_title Troubleshooting %}
You can verify that the `emulated_hue` component has been loaded and is responding by pointing a local browser to the following URL:
http://`<HA IP Address>`:8300/description.xml - This URL should return a descriptor file in the form of an XML file.
http://`<HA IP Address>`:8300/api/pi/lights - This will return a list of devices, lights, scenes, groups, etc.. that `emulated_hue` is exposing to Alexa.
### {% linkable_title License %}
Much of this code is based on work done by Bruce Locke on his [ha-local-echo](https://github.com/blocke/ha-local-echo) project, originally released under the MIT License. The license is located [here](https://github.com/blocke/ha-local-echo/blob/b9bf5dcaae6d8e305e2283179ffba64bde9ed29e/LICENSE).

18
source/_components/fan.mqtt.markdown
View File

@ -32,15 +32,27 @@ fan:
Configuration variables:
- **name** (*Optional*): The name of the lock. Default is 'MQTT Lock'.
- **command_topic** (*Required*): The MQTT topic to publish commands to change the fan state.
- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
- **command_topic** (*Required*): The MQTT topic to publish commands to change the lock state.
- **name** (*Optional*): The name of the fan. Default is 'MQTT Fan'.
- **payload_on** (*Optional*): The payload that represents the running state. Default is "ON".
- **payload_off** (*Optional*): The payload that represents the stop state. Default is "OFF".
- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no state topic defined, else `false`.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
- **retain** (*Optional*): If the published message should have the retain flag on or not.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the state.
- **speed_state_topic** (*Optional*): The MQTT topic subscribed to receive speed updates.
- **speed_command_topic** (*Optional*): The MQTT topic to publish commands to change the fan speed.
- **speed_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the speed.
- **oscillation_state_topic** (*Optional*): The MQTT topic subscribed to receive oscillation updates.
- **oscillation_command_topic** (*Optional*): The MQTT topic to publish commands to change the fan oscillation.
- **oscillation_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the oscillation.
- **payload_oscillation_on** (*Optional*): The payload that represents the oscillation state. Default is "ON".
- **payload_oscillation_off** (*Optional*): The payload that represents the oscillation state. Default is "OFF".
- **payload_low_speed** (*Optional*): The payload that represents the low speed state. Default is "low".
- **payload_medium_speed** (*Optional*): The payload that represents the low speed state. Default is "med".
- **payload_high_speed** (*Optional*): The payload that represents the low speed state. Default is "high".
- **speeds** array (*Optional*): Valid entries for the list are `off`, `low`, `med`, and `high`.
<p class='note warning'>
Make sure that your topic match exact. `some-topic/` and `some-topic` are different topics.

4
source/_components/ifttt.markdown
View File

@ -71,7 +71,11 @@ automation:
To be able to receive events from IFTTT, your Home Assistant instance needs to be accessible from the web. This can be achieved by forwarding port 8123 from your router to the device running Home Assistant. If your ISP is giving you a new IP address from time to time, consider using [DuckDNS][duck-dns].
In the URL field, you can then put an [API URL][rest-api]. You probably want to use a POST action, so select `POST` as method. After your request line, you need to add your Home Assistant password, which you defined in the [http section of your config][http-configuration], in the form off `?api_password=<your_password>`. For the message body, refer to the API page linked above.
[duck-dns]: https://duckdns.org
[rest-api]: https://home-assistant.io/developers/rest_api/
[http-configuration]: https://home-assistant.io/getting-started/basic/#password-protecting-the-web-interface
<p class='img'>
<img src='/images/components/ifttt/IFTTT_to_HA.png' />

2
source/_components/influxdb.markdown
View File

@ -8,7 +8,7 @@ comments: false
sharing: true
footer: true
logo: influxdb.png
ha_category: "History"
ha_category: History
ha_release: 0.9
---

1
source/_components/media_player.webostv.markdown
View File

@ -23,7 +23,6 @@ To add a TV to your installation, add the following to your `configuration.yaml`
# Example configuration.yaml entry
media_player:
- platform: webostv
host: 192.168.0.10
```
Configuration variables:

2
source/_components/media_player.yamaha.markdown
View File

@ -43,7 +43,7 @@ A few notes:
- For receivers that support more than one zone, Home Assistant will add one media player per zone supported by the player, named "$name Zone 2" and "$name Zone 3".
- In some cases, autodiscovery fails due to a known bug in the receiver's firmware. It is possible to manually specify the reveiver's IP address or via it's hostname (if it is discoverably by your DNS) then.
- Please note: If adding the IP address or hostname manually, you **must** enable network standby on your receiver, or else startup of Home Assistant will hang if you have your receiver switched off.
- Currently, this component supports powering on/off, mute, volume control and source selection.
- Currently, this component supports powering on/off, mute, volume control and source selection. Playback controls, for instance play and stop are available for sources that supports it.
A full configuration example will look like the sample below:
```yaml

2
source/_components/notify.xmpp.markdown
View File

@ -15,6 +15,8 @@ ha_release: pre 0.7
The `xmpp` platform allows you to deliver notifications from Home Assistant to a [Jabber (XMPP)](http://xmpp.org) account.
To enable Jabber notifications in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:

4
source/_components/rfxtrx.markdown
View File

@ -27,3 +27,7 @@ Configuration variables:
- **device** (*Required*): The path to your device, e.g. `/dev/serial/by-id/usb-RFXCOM_RFXtrx433_A1Y0NJGR-if00-port0`
- **debug** (*Optional*): If you want to receive debug output.
- **dummy** (*Optional*): Then you have need a connected drive to test your settings. Can be usefull for debugging and testing.
Supported protocols
Not all protocols as advertised are enabled on inital setup of your transceiver. Enabling all protocols is not recommmended either. Your 433.92 product not showing in the logs? Visit the RFXtrx website to [download RFXmgmr](http://www.rfxcom.com/epages/78165469.sf/nl_NL/?ObjectPath=/Shops/78165469/Categories/Downloads) and enable the required protocol.

10
source/_components/sensor.efergy.markdown
View File

@ -14,7 +14,15 @@ ha_iot_class: "Cloud Polling"
---
Integrate your [Efergy](https://efergy.com) meter information into Home Assistant. To get an app token, log in to your efergy account, go to the Settings page, click on App tokens, and click "Add token".
Integrate your [Efergy](https://efergy.com) meter information into Home Assistant. To get an app token:
1. Log in to your efergy account
2. Go to the Settings page
3. Click on App tokens
4. Click "Add token"
```yaml
# Example configuration.yaml entry

2
source/_components/sensor.fixer.markdown
View File

@ -16,7 +16,7 @@ ha_release: 0.23
The `fixer` sensor will show you the current exchange rate from [Fixer.io](http://fixer.io/) which is using data from the [European Central Bank (ECB)](https://www.ecb.europa.eu).
To get an owerview about the available [currencies](http://api.fixer.io/latest).
To get an overview about the available [currencies](http://api.fixer.io/latest).
To enable this sensor, add the following lines to your `configuration.yaml` file:

12
source/_components/sensor.plex.markdown
View File

@ -21,20 +21,14 @@ If you want to enable the plex sensor, add the following lines to your `configur
```yaml
# Example configuration.yaml entry
sensor:
platform: plex
name: Plex Spy
host: 192.168.1.100
port: 32400
username: plexuser
password: plexpw
server: MyPlexServer
- platform: plex
```
Configuration variables:
- **host** (*Optional*): The IP address of your Plex server. Defaults to `localhost`.
- **port** (*Optional*): The port of your Plex Server. Defaults to 32400.
- **name** (*Optional*): Name of the Plex server. Defaults to Plex.
- **port** (*Optional*): The port of your Plex Server. Defaults to `32400`.
- **name** (*Optional*): Name of the Plex server. Defaults to "Plex".
- **username** (*Optional*): The username for the remote Plex server.
- **password** (*Optional*): The password for your given account on the remote Plex server.
- **server** (*Optional*): The name of your remote Plex server.

15
source/_components/sensor.rest.markdown
View File

@ -50,10 +50,10 @@ Configuration variables:
- **headers** (*Optional*): The headers for the requests.
<p class='note warning'>
Make sure that the URL matches exactly your endpoint or resource.
Make sure that the URL exactly matches your endpoint or resource.
</p>
`curl` could help you with the identification of the variable you want to display in your Home Assistant frontend. The example below show the JSON response of a device that is running with [aREST](http://arest.io/).
`curl` can help you identify the variable you want to display in your Home Assistant frontend. The example below shows the JSON response of a device that is running with [aREST](http://arest.io/).
```bash
$ curl -X GET http://192.168.1.31/temperature/
@ -97,6 +97,8 @@ sensor:
The Home Assistant [API](/developers/rest_api/) exposes the data from your attached sensors. If you are running multiple Home Assistant instances which are not [connected](/developers/architecture/#multiple-connected-instances) you can still get information from them.
If the Home Assistant instance in the resource variable is protected by an API password, you can append `?api_password=YOUR_PASSWORD` to the resource URL to authenticate or use `headers:`.
```yaml
sensor:
- platform: rest
@ -105,6 +107,7 @@ sensor:
value_template: {% raw %}'{{ value_json.state }}'{% endraw %}
unit_of_measurement: "°C"
```
### {% linkable_title Accessing a HTTP authentication protected endpoint %}
The REST sensor supports HTTP authentication and customized headers.
@ -117,14 +120,14 @@ sensor:
password: test1
authentication: basic
headers:
User-agent: Home Assistant
User-Agent: Home Assistant
Content-Type: application/json
```
The header will contains all relevant details. This will give you the flexibility to access also endpoints wich 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:
Content-Length: 1024
Host: IP_ADDRESS1:5000
Authorization: Basic aGExOnRlc3Qx
Accept-Encoding: identity
@ -134,7 +137,7 @@ User-Agent: Home Assistant
### {% linkable_title Use GitHub to get the latest release of Home Assistant %}
This sample is very similar to the [`updater`](/components/updater/) component but the information are recieved from GitHub.
This sample is very similar to the [`updater`](/components/updater/) component but the information is recieved from GitHub.
```yaml
sensor:

2
source/_components/sensor.systemmonitor.markdown
View File

@ -13,7 +13,7 @@ ha_release: pre 0.7
ha_iot_class: "Local Push"
---
The `systemmonitor` sensor platform to allow 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:

1
source/_components/switch.arduino.markdown
View File

@ -27,7 +27,6 @@ switch:
name: Fan Office
12:
name: Light Desk
type: digital
initial: true
negate: true
```

94
source/_components/switch.rfxtrx.markdown
View File

@ -43,7 +43,30 @@ switch:
name: device_name
```
Example configuration:
Configuration variables:
- **devices** (*Required*): A list of devices with their name to use in the frontend.
- **automatic_add** (*Optional*): To enable the automatic addition of new switches.
- **signal_repetitions** (*Optional*): Because the rxftrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the switch to try to send each signal repeatedly.
- **fire_event** (*Optional*): Fires an event even if the state is the same as before, for example a doorbell switch. Can also be used for automations.
Generate codes:
If you need to generate codes for switches you can use a template (usefull for example COCO switches).
- Go to home-assistant-IP:8123/dev-template
- Use this code to generate a code:
```yaml
0b11000{{ range(0,700) | random | int }}bc0cfe0{{ range(0,10) | random | int }}010f70
```
- Use this code to add a new switch in your configuration.yaml
- Launch your homeassistant and go the website.
- Enable learning mode on your switch (i.e. push learn button or plug it in a wall socket)
- Toggle your new switch in the homeassisant interface
## {% linkable_title Examples %}
Basic configuration with 3 devices:
```yaml
# Example configuration.yaml entry
@ -61,9 +84,68 @@ switch:
fire_event: True
```
Configuration variables:
Doorbell configuration:
- **devices** (*Required*): A list of devices with their name to use in the frontend.
- **automatic_add** (*Optional*): To enable the automatic addition of new switches.
- **signal_repetitions** (*Optional*): Because the rxftrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the switch to try to send each signal repeatedly.
- **fire_event** (*Optional*): Fires an event even if the state is the same as before. Can be used for automations.
```yaml
# Example configuration.yaml entry
switch:
platform: rfxtrx
automatic_add: False
devices:
0710014c440f0160:
name: Hall
0710010244080780:
name: Door
fire_event: true
automation:
- alias: Switch light on when door bell rings if sun is below horizon and light was off
trigger:
platform: event
event_type: button_pressed
event_data: {"entity_id": "switch.door"}
condition:
condition: and
conditions:
- condition: state
entity_id: sun.sun
state: "below_horizon"
- condition: state
entity_id: switch.hall
state: 'off'
action:
- service: switch.turn_on
entity_id: switch.hall
```
Use remote to enable scene:
```yaml
# Example configuration.yaml entry
switch:
platform: rfxtrx
automatic_add: False
devices:
0b1100ce3213c7f210010f70:
name: Light1
0b11000a02ef2gf210010f50:
name: Light2
0b1111e003af16aa10000060:
name: Keychain remote
fire_event: true
scene:
name: Livingroom
entities:
switch.light1: on
switch.light2: on
automation:
- alias: Use remote to enable scene
trigger:
platform: event
event_type: button_pressed
event_data: {"state": "on", "entity_id": "switch.keychain_remote"}
action:
service: scene.turn_on
entity_id: scene.livingroom
```

6
source/_cookbook/automation_for_rainy_days.markdown
View File

@ -10,7 +10,7 @@ footer: true
ha_category: Automation Examples
---
This requires a [forecast.io](/components/sensor.forecast/) sensor with the condition `weather_precip` that tells if it's raining or not.
This requires a [Dark Sky](/components/sensor.darksky/) sensor with the condition `precip_intensity` that tells if it's raining or not. You could also experiment with other attributes such as `cloud_cover`.
Turn on a light in the living room when it starts raining, someone is home, and it's afternoon or later.
@ -20,7 +20,7 @@ automation:
trigger:
- platform: state
entity_id: sensor.weather_precip
entity_id: sensor.precip_intensity
state: 'rain'
- platform: state
entity_id: group.all_devices
@ -43,7 +43,7 @@ automation 2:
alias: 'Rain is over'
trigger:
- platform: state
entity_id: sensor.weather_precip
entity_id: sensor.precip_intensity
state: 'None'
- platform: sun
event: 'sunset'

12
source/_cookbook/configuration_yaml_by_alok_saboo.markdown Normal file
View File

@ -0,0 +1,12 @@
---
layout: page
title: "Configuration.yaml by Alok Saboo"
description: ""
date: 2016-10-25 10:45
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Example configuration.yaml
ha_external_link: https://github.com/arsaboo/homeassistant-config
---

12
source/_cookbook/configuration_yaml_by_daniel_hoyer_iversen.markdown Normal file
View File

@ -0,0 +1,12 @@
---
layout: page
title: "Configuration.yaml by Daniel Høyer Iversen"
description: ""
date: 2016-10-11 11:45
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Example configuration.yaml
ha_external_link: https://github.com/Danielhiversen/home-assistant_config
---

0
source/configuration_yaml_by_mertenats.markdown → source/_cookbook/configuration_yaml_by_mertenats.markdown
View File

4
source/_cookbook/tor_configuration.markdown
View File

@ -37,7 +37,7 @@ Onion sites are websites that run on a Tor Hidden Service node. "dot onion" site
#### {% linkable_title Setting up Tor on your Home Assistant %}
First, install Tor. On a Debain-based system, you can install the package easily:
First, install Tor. On a Debian-based system, you can install the package easily:
```bash
$ sudo apt-get install tor
@ -104,7 +104,7 @@ On iOS, we have not fully tested this yet, but you should be able to add custom
With this configuration, only you can access your Home Assistant instance Onion site through Tor, and no one else. You can share the authentication cookie with multiple devices and users, or you can generate a unique one for each - up to you! If you have multiple, say for an industrial, business or corporate configuration, this would provide an easy way to revoke access to a specific user or device.
If you always access your Home Assistant instance via Tor, you can easily run this on an isolated "IoT" network segment at your install site, keeping your internal home network traffic seperate from any potentially compromised devices (like cheap "smart" lightbulbs with backdoors!).
If you always access your Home Assistant instance via Tor, you can easily run this on an isolated "IoT" network segment at your install site, keeping your internal home network traffic separate from any potentially compromised devices (like cheap "smart" lightbulbs with backdoors!).
You could also use Tor as a means to connect your Home Assistant instance to a remote device, sensor or other service that you do not want to or connect provide a direct, open IP connection to. Again, Tor provides authenticated and confidential routing (aka "privacy and encryption") by default, without having to setup TLS/SSL or VPN. It is just important to secure IoT nodes within your network, as it is to secure remote access!

4
source/_topics/database.markdown → source/_details/database.markdown
View File

@ -1,9 +1,9 @@
---
layout: page
title: "Home Assistant Database"
title: "Database"
description: "Details about the database which Home Assistant is using."
date: 2016-10-10 10:00
sidebar: true
sidebar: false
comments: false
sharing: true
footer: true

3
source/_topics/updater_details.markdown → source/_details/updater.markdown
View File

@ -1,13 +1,12 @@
---
layout: page
title: "Details about the updater"
title: "Updater"
description: "Details what the updater component is reporting about your Home Assistant instance."
date: 2016-10-22 08:00
sidebar: false
comments: false
sharing: true
footer: true
ha_category: Infrastructure
---
Starting with 0.31 the [updater component](/components/updater/) sends an optional report about Home Assistant instance.

3
source/_topics/webserver_details.markdown → source/_details/webserver.markdown
View File

@ -1,13 +1,12 @@
---
layout: page
title: "Details about the web server"
title: "Web server"
description: "Use nmap to scan your Home Assistant instance."
date: 2016-10-06 08:00
sidebar: false
comments: false
sharing: true
footer: true
ha_category: Infrastructure
---
It was only a matter of time till the first queries for tools like [https://www.shodan.io](https://www.shodan.io/search?query=Home+Assistant) to search for Home Assistant instances showed up.

68
source/_ecosystem/ios.markdown Normal file
View File

@ -0,0 +1,68 @@
---
layout: page
title: "iOS"
description: "Documentation about the Home Assistant iOS app."
release_date: 2016-10-24 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
regenerate: true
hide_github_edit: true
---
The Home Assistant for iOS app offers a companion app for iOS which is deeply integrated into both Home Assistant and iOS. Its basic features include:
* Advanced push notifications
* Location tracking
* Basic control of all Home Assistant entities
* Integration with third party apps
<p class='note warning'>
Currently, the app is only available via a closed beta. It will be on the App Store within the next few weeks.
</p>
<p class='img'>
<img src='/images/ios/control1.png' width='310' height='552' />
An example of a Home Assistant group as seen in the iOS app.
</p>
## Basic requirements
* iOS device running at least iOS 9, but iOS 10 is greatly preferred.
* Home Assistant 0.31.1 or higher for push notification support.
* SSL is strongly recommended. Self-signed SSL certificates will not work due to Apple's limitations.
The `ios` component is the companion component for the Home Assistant iOS app. While not required, adding the `ios` component to your setup will greatly enhance the iOS app with new notification, location and sensor functions not possible with a standalone app.
Loading the `ios` component will also load the [`device_tracker`][device-tracker] and [`zeroconf`][zeroconf] components. It also provides functionality required for the iOS notify platform but will not automatically load the `notify` component or platform as of 0.31.1. You must manually load it. See the [iOS notify platform][ios-notify] for more information.
## {% linkable_title Setup %}
### Automated Setup
The `ios` component will automatically be loaded under the following circumstances:
1. The [`discovery`][discovery] component is enabled.
2. You have just installed the app and are at the getting started screen.
Automated discovery and component loaded can only happen at first install of the app. You may need to wait a few minutes for the iOS component to load as the `discovery` component only scans the network every 5 minutes.
### Manual Setup
You may also manually load the `ios` component by adding the following to your configuration:
```yaml
# Example configuration.yaml entry
ios:
```
Configuration variables:
- **push** (*Optional*): Push notification configuration. See the [iOS `notify` platform][ios-notify] for more information.
[discovery]: /components/discovery
[device-tracker]: /components/device_tracker
[zeroconf]: /components/zeroconf
[notify]: /components/notify
[ios-notify]: /ecosystem/ios/notifications/

12
source/_ecosystem/ios/devices_file.markdown Normal file
View File

@ -0,0 +1,12 @@
---
layout: page
title: "ios.conf"
description: "Describes the contents and purpose of ios.conf"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
The `ios.conf` file contains the most recent state of all registered iOS devices. Deleting this file will not disable the devices and the file will be recreated the next time a new device is connected or an existing one reconnects.

12
source/_ecosystem/ios/features.markdown Normal file
View File

@ -0,0 +1,12 @@
---
layout: page
title: "Features"
description: "Describes the features of Home Assistant for iOS"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Coming soon

25
source/_ecosystem/ios/integration.markdown Normal file
View File

@ -0,0 +1,25 @@
---
layout: page
title: "Integration"
description: "Examples of how Home Assistant for iOS can be integrated with other apps"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant for iOS supports opening from other apps via URL.
Query parameters are passed as a dictionary in the call.
## Call service
Example: `homeassistant://call_service/device_tracker.see?entity_id=device_tracker.entity`
## Fire event
Example `homeassistant://fire_event/custom_event?entity_id=device_tracker.entity`
## Send one shot location
Example: `homeassistant://send_location/`

36
source/_ecosystem/ios/location.markdown Normal file
View File

@ -0,0 +1,36 @@
---
layout: page
title: "Location"
description: "Documentation about the location tracking abilities in Home Assistant for iOS"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
## {% linkable_title Location tracking when outside a Home Assistant zone %}
Home Assistant for iOS receives _significant location updates_ from iOS. Whenever an update is received, it is sent to Home Assistant. Roughly, an update is received everytime that your device transfers to a new cellular tower, a significant amount of time has passed (usually a couple hours) or a connection state changes and the system notices your location recently changed.
Apple [defines][apple-location-programming-guide] significant significant-change location updates as:
> The significant-change location service delivers updates only when there has been a significant change in the device’s location, such as 500 meters or more.
They also say in the [Energy Efficiency Guide][apple-energy-guide]:
> Significant-change location updates wake the system and your app once every 15 minutes, at minimum, even if no location changes have occurred.
Finally, I think this answer from [Stack Overflow][stackoverflow] says it best:
> The significant location change is the least accurate of all the location monitoring types. It only gets its updates when there is a cell tower transition or change. This can mean a varying level of accuracy and updates based on where the user is. City area, more updates with more towers. Out of town, interstate, fewer towers and changes.
What's the real story on significant-change location updates? Who knows, because Apple keeps it private.
## {% linkable_title Location tracking in Home Assistant zones %}
At launch, Home Assistant for iOS sets up geofences for all zones in your Home Assistant configuration. Enter and exit notifications are sent to Home Assistant.
[apple-energy-guide]: https://developer.apple.com/library/content/documentation/Performance/Conceptual/EnergyGuide-iOS/LocationBestPractices.html#//apple_ref/doc/uid/TP40015243-CH24-SW4
[apple-location-programming-guide]: https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/LocationAwarenessPG/CoreLocation/CoreLocation.html#//apple_ref/doc/uid/TP40009497-CH2-SW9
[stackoverflow]: http://stackoverflow.com/a/13331625/486182

24
source/_ecosystem/ios/notifications.markdown Normal file
View File

@ -0,0 +1,24 @@
---
layout: page
title: "Notifications Introduction"
description: "Getting started with iOS notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
The `ios` notify platform enables sending push notifications to the Home Assistant iOS app.
## {% linkable_title Setup %}
```yaml
# Example configuration.yaml entry
notify:
- platform: ios
```
Configuration variables:
- **name** (*Optional*): The name of the service.

142
source/_ecosystem/ios/notifications/actions.markdown Normal file
View File

@ -0,0 +1,142 @@
---
layout: page
title: "Actionable notifications"
description: "Making push notifications a two way system"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Actionable notifications allow you to attach 1-4 custom buttons to a notification. When one of the actions is selected Home Assistant will be notified which action was chosen. This allows you to build complex automations.
Examples of actionable notifications:
- A notification is sent whenever motion is detected in your home while you are away or asleep. You can add an action to Sound Alarm. When tapped, Home Assistant is notified that the `sound_alarm` action was selected. You can add an automation to sound the burglar alarm whenever this event is seen.
- Someone rings your front door bell. You can send an action to lock or unlock your front door. When tapped, a notification is sent back to Home Assistant upon which you can build automations.
- Send a notification whenever your garage door opens with actions to open and close the garage.
<p class='img'>
<img src='/images/ios/actions.png' />
Actionable notifications allow the user to send a command back to Home Assistant.
</p>
## Overview of how actionable notifications work
In advance of sending a notification:
1. Define a notification category in your Home Assistant configuration which contain 1-4 actions.
2. At launch iOS app requests notification categories from Home Assistant (can also be done manually in notification settings).
When sending a notification:
1. Send a notification with `data.push.category` set to a pre-defined notification category identifer.
2. Push notification delivered to device
3. User opens notification.
3. Action tapped
4. Identifier of action sent back to HA as the `actionName` property of the event `ios.notification_action_fired`, along with other metadata such as the device and category name.
<p class='img'>
<img src='/images/ios/NotificationActionFlow.png' />
How the iOS device and Home Assistant work together to enable actionable notifications.
</p>
## Definitions
- Category - A category represents a type of notification that the app might receive. Think of it as a unique group of actions. A categories parameters include:
- Action - An action consists of a button title and the information that iOS needs to notify the app when the action is selected. You create separate action objects for distinct action your app supports. An actions parameters include:
## {% linkable_title Category parameters %}
- **name** (*Required*): A friendly name for this category.
- **identifier** (*Required*): A unique identifier for the category. Must be uppercase and have no special characters or spaces.
- **action** (*Required*): A list of actions.
## {% linkable_title Action parameters %}
- **identifier** (*Required*): A unique identifier for this action. Must be uppercase and have no special characters or spaces. Only needs to be unique to the category, not unique globally.
- **title** (*Required*): The text to display on the button. Keep it short.
- **activationMode** (*Optional*): The mode in which to run the app when the action is performed. Setting this to `foreground` will make the app open after selecting. Default value is `background`.
- **authenticationRequired** (*Optional*): If a truthy value (`true`, `True`, `yes`, etc.) the user must unlock the device before the action is performed.
- **destructive** (*Optional*): When the value of this property is a truthy value, the system displays the corresponding button differently to indicate that the action is destructive (text color is red).
- **behavior** (*Optional*): When `textInput` the system provides a way for the user to enter a text response to be included with the notification. The entered text will be sent back to Home Assistant. Default value is `default`.
- **textInputButtonTitle** (*Optional*): The button label. *Required* if `behavior` is `textInput`.
- **textInputPlaceholder** (*Optional*): The placeholder text to show in the text input field. Only used if `behavior` is `textInput` and the device runs iOS 10.
Here's a fully built example configuration:
```yaml
ios:
push:
categories:
- name: Alarm
identifier: 'ALARM'
actions:
- identifier: 'SOUND_ALARM'
title: 'Sound Alarm'
activationMode: 'background'
authenticationRequired: yes
destructive: yes
behavior: 'default'
- identifier: 'SILENCE_ALARM'
title: 'Silence Alarm'
activationMode: 'background'
authenticationRequired: yes
destructive: no
behavior: 'textInput'
textInputButtonTitle: 'Silencio!'
textInputPlaceholder: 'Placeholder'
```
## {% linkable_title Building automations for notification actions %}
Here is an example automation to send a notification with a category in the payload:
```yaml
automation:
- alias: Notify iOS app
trigger:
...
action:
service: notify.ios_robbies_iphone_7_plus
data:
message: "Something happened at home!"
data:
push:
badge: 5
sound: <SOUND FILE HERE>
category: "ALARM" # Needs to match the top level identifier you used in the ios configuration
action_data: # Anything passed in action_data will get echoed back to Home Assistant.
entity_id: light.test
my_custom_data: foo_bar
```
When an action is selected an event named `ios.notification_action_fired` will be emitted on the Home Assistant event bus. Below is an example payload.
```json
{
"sourceDeviceName": "Robbie's iPhone 7 Plus",
"sourceDeviceID": "robbies_iphone_7_plus",
"actionName": "SOUND_ALARM",
"sourceDevicePushId": "ab9f02fe-6ac6-47b8-adeb-5dd87b489156",
"textInput": "",
"actionData": {}
}
```
Here's an example automation for the given payload:
```yaml
automation:
- alias: Sound the alarm
trigger:
platform: event
event_type: ios.notification_action_fired
event_data:
actionName: SOUND_ALARM
action:
...
```
Notes:
* `textInput` will only exist if `behavior` was set to `textInput`.
* `actionData` is a dictionary with parameters passed in the `action_data` dictionary of the `push` dictionary in the original notification.

15
source/_ecosystem/ios/notifications/architecture.markdown Normal file
View File

@ -0,0 +1,15 @@
---
layout: page
title: "Architecture"
description: "The push notification system layout"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
<p class='img'>
<img src='/images/ios/PushNotificationLayout.png' />
The push notification infrastructure layout
</p>

76
source/_ecosystem/ios/notifications/attachments.markdown Normal file
View File

@ -0,0 +1,76 @@
---
layout: page
title: "Notification attachments"
description: "Adding attachments to iOS push notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
iOS 10 adds _attachments_ to notifications. An attachment is an image, video, or audio file which is downloaded to the device when a notification is received and shown alongside the notification. A thumbnail is shown when the notification is not expanded. The full size attachment is shown when the notification is expanded.
<p class="note">
To expand a notification on 3D Touch devices simply force touch any notification. On non-3D Touch devices swipe and tap the "View" button.
</p>
```yaml
- alias: Notify iOS app
trigger:
...
action:
service: notify.ios_robbies_iphone_7_plus
data:
message: "Something happened at home!""
data:
attachment:
url: https://67.media.tumblr.com/ab04c028a5244377a0ab96e73915e584/tumblr_nfn3ztLjxk1tq4of6o1_400.gif
content-type: gif
hide-thumbnail: false
```
Notes:
* The thumbnail of the notification will be the media at the `url`.
* The notification content is the media at the `url`.
* Attachment can be used with custom push notification categories.
## Example
<p class='img'>
<img src='/images/ios/attachment.png' />
An unexpanded push notification with an attachment.
</p>
<p class='img'>
<img src='/images/ios/expanded_attachment.png' />
The same notification but expanded to show the full size attachment
</p>
## Supported media types
If the attachment does not appear please ensure it is in one of the following formats:
### Audio attachments
Maximum file size: 5 MB
Allowed Formats: AIFF, WAV, MP3, MPEG4 Audio
### Image attachments
Maximum file size: 10 MB
Allowed Formats: JPEG, GIF, PNG
### Video attachments
Maximum file size: 50 MB
Allowed Formats: MPEG, MPEG2, MPEG4, AVI
## Configuration
- **url** (*Required*): The URL of content to use as the attachment. This URL _must_ be accessible from the Internet, or the receiving device must be on the same network as the hosted content.
- **content-type** (*Optional*): By default, the extension of the URL will be checked to determine the filetype. If there is no extension/it can't be determined you can manually provide a file extension.
- **hide-thumbnail** (*Optional*): If set to `true` the thumbnail will not show on the notification. The content will only be viewable by expanding.

58
source/_ecosystem/ios/notifications/basic.markdown Normal file
View File

@ -0,0 +1,58 @@
---
layout: page
title: "Basic Notifications"
description: "Basic notes about iOS notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
The iOS notify platform accepts the standard `title`, `message` and `target` parameters. The iOS notify platform supports targets as services. Assuming that you did not set a `name` when configuring the platform you should find all your registered and notification-enabled iOS devices available as notify targets as services with names prefixed "notify.ios_" and then the device name you entered at setup.
Notes:
* `title` only displays on Apple Watch and iOS 10 devices.
* `target` can be used to specific a single device using its PushID, found in `ios.conf`. The preferred way of providing a target is through a target specific notify service.
<p class='img'>
<img src='/images/ios/example.png' />
A push notification showing all of the basic options `title` and `message` as well as `subtitle` and [actions](/ecosystem/ios/notifications/actions/).
</p>
### {% linkable_title Enhancing basic notifications %}
#### Badge
You can set the icon badge in the payload:
```yaml
automation:
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: "Something happened at home!"
data:
push:
badge: 5
```
#### Subtitle
iOS 10 supports a subtitle in addition to the title:
```yaml
automation
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: "Something happened at home!"
data:
subtitle: "Subtitle goes here"
```

61
source/_ecosystem/ios/notifications/content_extensions.markdown Normal file
View File

@ -0,0 +1,61 @@
---
layout: page
title: "Dynamic content"
description: "Extend your notifications with dynamic content"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
With the new Content Extension feature found in iOS 10, dynamic content can now be displayed as part of a notification without opening an app.
# Map
Will show a map with a red tipped pin at the coordinates given.
The map will be centered at the coordinates given.
```yaml
service: notify.iOSApp
data:
message: Something happened at home!
data:
push:
category: map
action_data:
latitude: 40.785091
longitude: -73.968285
```
<p class='img'>
<img src='/images/ios/map.png' />
An example of the map dynamic content.
</p>
# Camera Stream
The notification thumbnail will be a still image from the camera.
The notification content is a real time MJPEG stream of a camera (assuming the camera supports it).
You can use the attachment parameters `content-type` and `hide-thumbnail` with camera.
You can view an example [here](https://www.youtube.com/watch?v=LmYwpxPKW0g).
```yaml
service: notify.iOSApp
data:
message: Motion detected in the Living Room
data:
push:
category: camera
entity_id: camera.demo_camera
```
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/LmYwpxPKW0g" frameborder="0" allowfullscreen></iframe>
</div>
# Combining with actionable notifications
As you can see the `category` key is used to tell the device what kind of content extension to use. You can use the same category identifiers in your own custom [actions](/ecosystem/ios/notifications/actions/) to add actions to the content extension.

0
source/_ecosystem/ios/notifications/examples.markdown Normal file
View File

22
source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown Normal file
View File

@ -0,0 +1,22 @@
---
layout: page
title: "Privacy, rate limiting and security"
description: "Notes about important topics relating to push notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
## {% linkable_title Privacy %}
No notification content is stored on remote servers. Only the required push registration data and a simple counter of the total number of push notifications sent per day per device (for rate limiting purposes) is kept.
## {% linkable_title Rate limiting %}
Currently, you are allowed to send a maximum of 150 push notifications per day per device. This is to ensure that the service remains cheap to maintain. In the future we may add support for upgrading to allow more notifications. The rate limit resets at midnight UTC daily. When a notification is sent your current rate limits (including sent notifications and notifications remaining for the day) will be output to your Home Assistant logs. If an error occurs while sending a notification your rate limit will not be affected.
## {% linkable_title Security %}
All traffic between your Home Assistant instance, the push infrastructure, and Apple, is encrypted with SSL.

30
source/_ecosystem/ios/notifications/requesting_location_updates.markdown Normal file
View File

@ -0,0 +1,30 @@
---
layout: page
title: "Requesting location updates"
description: "Ask the device to send a location update remotely"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
<p class="note warning">
**Do not rely on this functionality due to the time limits mentioned below.**
</p>
You can force a device to attempt to report its location by sending a special notification.
```yaml
automation
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: "request_location_updates"
```
Assuming the device receives the notification, it will attempt to get a location update within 5 seconds and report it to Home Assistant. This is a little bit hit or miss since Apple imposes a maximum time allowed for the app to work with the notification and location updates sometimes take longer than usual due to factors such as waiting for GPS acquisition.

184
source/_ecosystem/ios/notifications/sounds.markdown Normal file
View File

@ -0,0 +1,184 @@
---
layout: page
title: "Notification Sounds"
description: "Adding sounds to notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Adding a custom sound to a notification allows you to easily identify the notification without even looking at your device. Home Assistant for iOS comes with some notification sounds pre-installed but you can also upload your own.
Here is an example notification that uses one of the pre-installed sounds.
```yaml
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: “Something happened at home!”
data:
push:
sound: "US-EN-Morgan-Freeman-Roommate-Is-Arriving.wav"
```
Notes:
* You must use the full filename in the payload (including extension).
## {% linkable_title Custom push notification sounds %}
The app allows you to use your own custom sounds in push notifications. The sounds must be formatted following [Apple's requirements][sound-requirements]. You set the filename of the sound in the notification payload. To add sounds:
1. Connect the device to a PC or Mac running the latest version of iTunes.
2. Go to the device in iTunes.
3. Select "Apps" on the left sidebar.
4. Scroll down until you see the section labeled "File Sharing".
5. Select HomeAssistant.
6. Drag and drop properly formatted sounds.
7. Click Sync in the lower right.
8. Once sync is complete, disconnect the device from the computer.
9. On your iOS device, open the Home Assistant app.
10. Go to Settings -> Notification Settings.
11. Select "Import sounds from iTunes".
Assuming that you correctly formatted the sounds they are now available to use in push notifications.
Notes:
* **Please note that due to a bug in iOS 10 you may need to restart your entire device before notification sounds can be played. This should hopefully be fixed by Apple soon.**
* Uploading a file with the same name as an existing one will overwrite the original.
* You can view what sounds are installed on each device by inspecting the `ios.conf` file in your configuration directory. They are listed in the `pushSounds` array.
### {% linkable_title Preinstalled notification sounds %}
```
US-EN-Alexa-Back-Door-Opened.wav
US-EN-Alexa-Back-Door-Unlocked.wav
US-EN-Alexa-Basement-Door-Opened.wav
US-EN-Alexa-Basement-Door-Unlocked.wav
US-EN-Alexa-Boyfriend-Is-Arriving.wav
US-EN-Alexa-Daughter-Is-Arriving.wav
US-EN-Alexa-Front-Door-Opened.wav
US-EN-Alexa-Front-Door-Unlocked.wav
US-EN-Alexa-Garage-Door-Opened.wav
US-EN-Alexa-Girlfriend-Is-Arriving.wav
US-EN-Alexa-Good-Morning.wav
US-EN-Alexa-Good-Night.wav
US-EN-Alexa-Husband-Is-Arriving.wav
US-EN-Alexa-Mail-Has-Arrived.wav
US-EN-Alexa-Motion-At-Back-Door.wav
US-EN-Alexa-Motion-At-Front-Door.wav
US-EN-Alexa-Motion-Detected-Generic.wav
US-EN-Alexa-Motion-In-Back-Yard.wav
US-EN-Alexa-Motion-In-Basement.wav
US-EN-Alexa-Motion-In-Front-Yard.wav
US-EN-Alexa-Motion-In-Garage.wav
US-EN-Alexa-Patio-Door-Opened.wav
US-EN-Alexa-Patio-Door-Unlocked.wav
US-EN-Alexa-Smoke-Detected-Generic.wav
US-EN-Alexa-Smoke-Detected-In-Basement.wav
US-EN-Alexa-Smoke-Detected-In-Garage.wav
US-EN-Alexa-Smoke-Detected-In-Kitchen.wav
US-EN-Alexa-Son-Is-Arriving.wav
US-EN-Alexa-Water-Detected-Generic.wav
US-EN-Alexa-Water-Detected-In-Basement.wav
US-EN-Alexa-Water-Detected-In-Garage.wav
US-EN-Alexa-Water-Detected-In-Kitchen.wav
US-EN-Alexa-Welcome-Home.wav
US-EN-Alexa-Wife-Is-Arriving.wav
US-EN-Daisy-Back-Door-Motion.wav
US-EN-Daisy-Back-Door-Open.wav
US-EN-Daisy-Front-Door-Motion.wav
US-EN-Daisy-Front-Door-Open.wav
US-EN-Daisy-Front-Window-Open.wav
US-EN-Daisy-Garage-Door-Open.wav
US-EN-Daisy-Guest-Bath-Leak.wav
US-EN-Daisy-Kitchen-Sink-Leak.wav
US-EN-Daisy-Kitchen-Window-Open.wav
US-EN-Daisy-Laundry-Room-Leak.wav
US-EN-Daisy-Master-Bath-Leak.wav
US-EN-Daisy-Master-Bedroom-Window-Open.wav
US-EN-Daisy-Office-Window-Open.wav
US-EN-Daisy-Refrigerator-Leak.wav
US-EN-Daisy-Water-Heater-Leak.wav
US-EN-Morgan-Freeman-Back-Door-Closed.wav
US-EN-Morgan-Freeman-Back-Door-Locked.wav
US-EN-Morgan-Freeman-Back-Door-Opened.wav
US-EN-Morgan-Freeman-Back-Door-Unlocked.wav
US-EN-Morgan-Freeman-Basement-Door-Closed.wav
US-EN-Morgan-Freeman-Basement-Door-Locked.wav
US-EN-Morgan-Freeman-Basement-Door-Opened.wav
US-EN-Morgan-Freeman-Basement-Door-Unlocked.wav
US-EN-Morgan-Freeman-Boss-Is-Arriving.wav
US-EN-Morgan-Freeman-Boyfriend-Is-Arriving.wav
US-EN-Morgan-Freeman-Cleaning-Supplies-Closet-Opened.wav
US-EN-Morgan-Freeman-Coworker-Is-Arriving.wav
US-EN-Morgan-Freeman-Daughter-Is-Arriving.wav
US-EN-Morgan-Freeman-Friend-Is-Arriving.wav
US-EN-Morgan-Freeman-Front-Door-Closed.wav
US-EN-Morgan-Freeman-Front-Door-Locked.wav
US-EN-Morgan-Freeman-Front-Door-Opened.wav
US-EN-Morgan-Freeman-Front-Door-Unlocked.wav
US-EN-Morgan-Freeman-Garage-Door-Closed.wav
US-EN-Morgan-Freeman-Garage-Door-Opened.wav
US-EN-Morgan-Freeman-Girlfriend-Is-Arriving.wav
US-EN-Morgan-Freeman-Good-Morning.wav
US-EN-Morgan-Freeman-Good-Night.wav
US-EN-Morgan-Freeman-Liquor-Cabinet-Opened.wav
US-EN-Morgan-Freeman-Motion-Detected.wav
US-EN-Morgan-Freeman-Motion-In-Basement.wav
US-EN-Morgan-Freeman-Motion-In-Bedroom.wav
US-EN-Morgan-Freeman-Motion-In-Game-Room.wav
US-EN-Morgan-Freeman-Motion-In-Garage.wav
US-EN-Morgan-Freeman-Motion-In-Kitchen.wav
US-EN-Morgan-Freeman-Motion-In-Living-Room.wav
US-EN-Morgan-Freeman-Motion-In-Theater.wav
US-EN-Morgan-Freeman-Motion-In-Wine-Cellar.wav
US-EN-Morgan-Freeman-Patio-Door-Closed.wav
US-EN-Morgan-Freeman-Patio-Door-Locked.wav
US-EN-Morgan-Freeman-Patio-Door-Opened.wav
US-EN-Morgan-Freeman-Patio-Door-Unlocked.wav
US-EN-Morgan-Freeman-Roommate-Is-Arriving.wav
US-EN-Morgan-Freeman-Searching-For-Car-Keys.wav
US-EN-Morgan-Freeman-Setting-The-Mood.wav
US-EN-Morgan-Freeman-Smartthings-Detected-A-Flood.wav
US-EN-Morgan-Freeman-Smartthings-Detected-Carbon-Monoxide.wav
US-EN-Morgan-Freeman-Smartthings-Detected-Smoke.wav
US-EN-Morgan-Freeman-Smoke-Detected-In-Basement.wav
US-EN-Morgan-Freeman-Smoke-Detected-In-Garage.wav
US-EN-Morgan-Freeman-Smoke-Detected-In-Kitchen.wav
US-EN-Morgan-Freeman-Someone-Is-Arriving.wav
US-EN-Morgan-Freeman-Son-Is-Arriving.wav
US-EN-Morgan-Freeman-Starting-Movie-Mode.wav
US-EN-Morgan-Freeman-Starting-Party-Mode.wav
US-EN-Morgan-Freeman-Starting-Romance-Mode.wav
US-EN-Morgan-Freeman-Turning-Off-All-The-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Air-Conditioner.wav
US-EN-Morgan-Freeman-Turning-Off-The-Bar-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Chandelier.wav
US-EN-Morgan-Freeman-Turning-Off-The-Family-Room-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Hallway-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Kitchen-Light.wav
US-EN-Morgan-Freeman-Turning-Off-The-Light.wav
US-EN-Morgan-Freeman-Turning-Off-The-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Mood-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-TV.wav
US-EN-Morgan-Freeman-Turning-On-The-Air-Conditioner.wav
US-EN-Morgan-Freeman-Turning-On-The-Bar-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Chandelier.wav
US-EN-Morgan-Freeman-Turning-On-The-Family-Room-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Hallway-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Kitchen-Light.wav
US-EN-Morgan-Freeman-Turning-On-The-Light.wav
US-EN-Morgan-Freeman-Turning-On-The-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Mood-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-TV.wav
US-EN-Morgan-Freeman-Vacate-The-Premises.wav
US-EN-Morgan-Freeman-Water-Detected-In-Basement.wav
US-EN-Morgan-Freeman-Water-Detected-In-Garage.wav
US-EN-Morgan-Freeman-Water-Detected-In-Kitchen.wav
US-EN-Morgan-Freeman-Welcome-Home.wav
US-EN-Morgan-Freeman-Wife-Is-Arriving.wav
```

14
source/_ecosystem/ios/requirements.markdown Normal file
View File

@ -0,0 +1,14 @@
---
layout: page
title: "Requirements"
description: "Basic requirements to use Home Assistant for iOS"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
* iOS device running at least iOS 9, but iOS 10 is greatly preferred.
* Home Assistant 0.31.1 or higher for push notification support.
* SSL is strongly recommended. Self-signed SSL certificates will not work due to Apple's limitations.

184
source/_ecosystem/scenegen.markdown Executable file
View File

@ -0,0 +1,184 @@
---
layout: page
title: "SceneGen"
description: "Scenegen is a scene generation tool for Home Assistant"
release_date: 2016-10-30 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
regenerate: true
hide_github_edit: true
---
Scenegen is a scene generation tool for [Home Assistant](https://home-assistant.io/) home automation software. It creates scenes by example, by reading the current states of devices and outputting a corresponding scene. Scenegen is written in python using Home Assistant's RESTFul API so can be run from anywhere. It currently supports lights and switches only.
## Installation
### Clone the Repository
Clone the **scenegen** repository to the current local directory on your machine.
``` bash
$ git clone https://github.com/home-assistant/scenegen.git
```
Change your working directory to the repository root. Moving forward, we will be working from this directory.
``` bash
$ cd scenegen
```
## Install Prereqs
Before running `SceneGen` you will need to add some python prerequisites:
```bash
$ sudo pip3 install configparser
```
You should now be ready to run `scenegen`
## Basic Operation
```
usage: scenegen [-h] [-k KEY] [-s SCENENAME] [-m MAPFILE] [-f FILTER]
[-c {xy_color,rgb_color,color_temp,color_name}] [-t TYPES]
url
positional arguments:
url url for Home Assistant instance
optional arguments:
-h, --help show this help message and exit
-k KEY, --key KEY API Key of Home Assistant instance
-s SCENENAME, --scenename SCENENAME
Name of scene to generate
-m MAPFILE, --mapfile MAPFILE
Name of mapfile to enable device filtering
-f FILTER, --filter FILTER
Comma separated list of device collections as defined
in mapfile
-c {xy_color,rgb_color,color_temp,color_name}, --colortype {xy_color,rgb_color,color_temp,color_name}
color type to use
-t TYPES, --types TYPES
list of device types to include
```
For basic operation just supply the url and optionally the api key (using the --key option) on the command line and scenegen will output a list of all lights and switches with their attributes. Optionally use the `--scenename` flag to explicitly set the scenename.
```
$ ./scenegen.py https://<some url> -k <some api key>
name: My New Scene
entities:
light.bedroom:
state: on
brightness: 28
light.kitchen:
state: off
light.living_room:
state: off
light.bedside:
state: on
brightness: 125
color_temp: 412
light.office_level_29:
state: on
brightness: 28
```
This output can be cut and pasted into your configuration.yaml file as required (ensuring correct indentatation of course).
Scenegen supports all documented effects for lights including transitions and flash effects, however generally it is easier to run scenegen to get the basic setup and add any effects manually later.
Note that depending on the type of light there may be a delay in actually setting up its parameters and Home Assistant actually recieving that state. For instance, if you set a scene up with the Hue App, Home Assistant won't see those changes for up to 10 seconds. Turning on a ZWave light might not be seen for an entire poll interval. For this reason, its good practice to wait for a while after the scene is setup before running scenegen. Alternatively, perform all setup using the Home Assistant frontend and it will instantly have the required state for capture.
## Advanced Usage
For a more advanced way to use the output try the following. In configuration.yaml add the following line:
```
scene: !include_dir_list scenes
```
This will tell home assistant to look in the subdirectory `scenes` for yaml files containing scene information. Each file will be named for the scene it will create and should contain information formatted as above. Then simply run Scenegen and redirect its output to the scenes subdirectory:
```
$ ./scenegen.py https://<some url> -k <some api key> > scenes/my_new_scene.yaml
```
This will create a new scene called `my_new_scene` which will automatically be picked up by Home Assistant on the next restart.
## Colors
Scenegen allows colors to be captured, and in fact Home Assistant light entities store up to 4 different ways of specifying the colors. This is redundant for creating scenes so Scenegen picks 1 and goes with it. The default is `color_temp` but you can change this with the `--colortype` flag, supported options are `xy_color`, `rgb_color`, `color_temp` and `color_name`.
## Types
By default, Scenegen will list all lights and switches. To restrict the device type use the `--types` option and supply a comma separated list (no spaces) of types to output. e.g.:
```
./scenegen.py https://<some url> -k <some api key> --types light,switch
```
or:
```
./scenegen.py https://<some url> -k <some api key> --types light
```
This will make more sense as and when more types are added.
## Maps and Filters
Maps allow you to specify and label various subsets of devices that you want to work on together. A mapfile is specified using the `--mapfile` option and is a `.ini` style file consisting of section headers and entries. The section headers specify a region or zone or otherwise organized selection of entities you want to filter on, and it is mandatory to have at least one. If you create a map file like this:
```
[entities]
light.living_room:
light.dining_room:
```
The trailing colons are necessary to prevent parsing errors for including just keys, as opposed to key=value so just go with it - it reminds us of YAML ;)
If you run scenegen with the `--mapfile` argument pointing to that file you will only get output for the listed entities (the name of the section is irrelevant if not using the `--filter` option). A more complex mapfile might look like this:
```
[Outside]
light.porch:
switch.path_lights:
[Living Room]
light.living_room_front:
light.living_room_back:
[Bedroom]
light.bedside:
```
Again, if you run with that map file it will output all of the entities listed, however you now have the possibility of restricting output devices based on the sections they are in, using the `--filter` option and supplying a comma separated list of sections you want to include, for instance:
```
./scenegen.py https://<some url> -k <some api key> --mapfile map.cfg --filter "Outside,Living Room"
```
The intended use of the mapfile and filter is that you create a map of all your devices and organize them into zones that you are interested in creating scenes for and use the filter to limit output to that zone. For instance you might want to create 3 or 4 scenes for your living room, and once the map is set up you can easily do so without the addition of unwanted devices.
## Updating SceneGen
To update SceneGen after a new version is released, just run the following command to update your copy:
```bash
$ git pull
```
## Release Notes
***Version 1.2***
- Add installation instructions
***Version 1.1***
- Add better error checking for Home Assistant errors
***Version 1.0***
Initial Release

39
source/_includes/asides/ecosystem_ios_navigation.html Normal file
View File

@ -0,0 +1,39 @@
<section class="aside-module grid__item one-whole lap-one-half">
<div class="section">
<h1 class="title delta">iOS Guide</h1>
<ul class="divided sidebar-menu">
<li>
{% active_link /ecosystem/ios/ General %}
{% comment %}
<ul>
<li>{% active_link /ecosystem/ios/requirements/ Requirements %}</li>
<li>{% active_link /ecosystem/ios/getting_started/ Getting Started %}</li>
<li>{% active_link /ecosystem/ios/features/ Features %}</li>
<li>{% active_link /ecosystem/ios/devices_file/ ios.conf %}</li>
</ul>
{% endcomment %}
</li>
<li>
{% active_link /ecosystem/ios/notifications/ Push Notifications %}
<ul>
<li>{% active_link /ecosystem/ios/notifications/basic/ Basic notifications %}</li>
<li>Advanced notifications</li>
<ul>
<li>{% active_link /ecosystem/ios/notifications/attachments/ Attachments %}</li>
<li>{% active_link /ecosystem/ios/notifications/content_extensions/ Dynamic content %}</li>
<li>{% active_link /ecosystem/ios/notifications/actions/ Actionable notifications %}</li>
<li>{% active_link /ecosystem/ios/notifications/requesting_location_updates/ Requesting location updates %}</li>
</ul>
<li>{% active_link /ecosystem/ios/notifications/examples/ Examples %}</li>
<li>{% active_link /ecosystem/ios/notifications/sounds/ Sounds %}</li>
<li>{% active_link /ecosystem/ios/notifications/architecture/ Architecture %}</li>
<li>{% active_link /ecosystem/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}</li>
</ul>
</li>
<li>{% active_link /ecosystem/ios/location/ Location Tracking %}</li>
{% comment %}<li>{% active_link /ecosystem/ios/sensor/ Battery Sensors %}</li>{% endcomment %}
<li>{% active_link /ecosystem/ios/integration/ Integration with other apps %}</li>
</ul>
</div>
</section>

25
source/_includes/asides/ecosystem_navigation.html Normal file
View File

@ -0,0 +1,25 @@
{% assign url_parts = page.url | split: "/" %}
{% if url_parts[2] == "ios" %}
{% include asides/ecosystem_ios_navigation.html | compact_newlines %}
{% comment %}
{% elsif url_parts[2] == "cookbook" %}
{% include asides/cookbook_navigation.html | compact_newlines %}
{% endcomment %}
{% else %}
<section class="aside-module grid__item one-whole lap-one-half">
{% include edit_github.html %}
{% assign ecosystem = site.ecosystem | sort: "title" %}
<div class="section">
<h1 class="title delta">Ecosystem</h1>
<ul class="divided">
{% for tool in ecosystem %}
{% assign filename = tool.path | split: "/" %}
{% if filename.size == 2 %}
<li><a href="{{tool.url}}">{{tool.title}}</a></li>
{% endif %}
{% endfor %}
</ul>
</div>
</section>
{% endif %}

1
source/_includes/asides/getting_started_navigation.html
View File

@ -65,6 +65,7 @@
</ul>
</li>
<li>{% active_link {{site_root}}/topics/ Advanced Topics %}</li>
<li>{% active_link {{site_root}}/details/ Details %}</li>
<li>{% active_link /getting-started/android/ Add to Android Homescreen %}</li>
<li>{% active_link /getting-started/browsers/ Browser Compatibility List %}</li>
</ul>

11
source/_includes/custom/navigation.html
View File

@ -4,14 +4,15 @@
<li>
<a>Getting started <i class="icon icon-caret-down"></i></a>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration Basics</a></li>
<li><a href="/getting-started/">Installing Home Assistant</a></li>
<li><a href="/getting-started/configuration/">Configuration Basics</a></li>
</ul>
</li>
{% endcomment %}
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/ecosystem/">Ecosystem</a></li>
<li><a href="/cookbook/">Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>

2
source/_includes/site/sidebar.html
View File

@ -6,6 +6,8 @@
{% include asides/cookbook_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'developers' %}
{% include asides/developers_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'ecosystem' %}
{% include asides/ecosystem_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'getting-started' %}
{% include asides/getting_started_navigation.html | compact_newlines %}
{% else %}

4
source/_posts/2016-10-22-flash-briefing-updater-hacktoberfest.markdown
View File

@ -203,7 +203,8 @@ This is super annoying, I know, especially since we had said in [0.12][zero-one-
## {% linkable_title Breaking changes %}
- The [HTTP] component now takes a different format for authenticating IPs
- Config format has changed for [Proximity]
- Configuration format has changed for [Proximity]
- The [Arduino] platform are now covered by the configuration check. Please check the documentation to see how.
- The Z-Wave entity ID change mentioned above
## {% linkable_title If you need help... %}
@ -263,6 +264,7 @@ Thanks for reading all of the above, especially since this week was a pretty lon
[@vittoriom]: https://github.com/vittoriom
[@wokar]: https://github.com/wokar
[Arduino]: https://home-assistant.io/components/arduino/
[APNS]: https://home-assistant.io/components/notify.apns/
[ARWN]: https://home-assistant.io/components/sensor.arwn/
[Concord232]: https://home-assistant.io/components/alarm_control_panel.concord232/

1
source/_topics/state_object.markdown
View File

@ -17,6 +17,7 @@ All states will always have an entity id, a state and a timestamp when last upda
Field | Description
----- | -----------
`state.state` | String representation of the current state of the entity. Example `off`
`state.entity_id` | Entity ID. Format: `<domain>.<object_id>`. Example: `light.kitchen`.
`state.domain` | Domain of the entity. Example: `light`.
`state.object_id` | Object ID of entity. Example: `kitchen`.

8
source/_topics/templating.markdown
View File

@ -85,7 +85,7 @@ Home Assistant adds extensions to allow templates to access all of the current s
## {% linkable_title Examples %}
### {% linkable_title States %}
Next two statements result in same value if state exists. Second one will result in an error if state does not exist.
The next two statements result in same value if state exists. The second one will result in an error if state does not exist.
```text
{% raw %}{{ states('device_tracker.paulus') }}
@ -134,7 +134,7 @@ Print out a list of all the sensor states.
### {% linkable_title Distance examples %}
If only 1 location is passed in will measure the distance from home.
If only 1 location is passed in, Home Assistant will measure the distance from home.
```text
{% raw %}Using Lat Lng coordinates: {{ distance(123.45, 123.45) }}
@ -166,7 +166,7 @@ Closest to an entity: {{ closest(states.zone.school, 'group.children') }}{% endr
```
### {% linkable_title Combined %}
Since closest returns a state, we can combine it with distance too
Since closest returns a state, we can combine it with distance too.
```text
{% raw %}{{ closest(states).name }} is {{ distance(closest(states)) }} meters away.{% endraw %}
@ -176,7 +176,7 @@ Since closest returns a state, we can combine it with distance too
The other part of templating is processing incoming data. It will allow you to modify incoming data and extract only the data you care about. This will work only for platforms and components that mentioned support for this in their documentation.
It depends per component or platform but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions:
It depends per component or platform, but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions:
| Variable | Description |
| ------------ | -------------------------------------- |

20
source/details/index.markdown Normal file
View File

@ -0,0 +1,20 @@
---
layout: page
title: "Details Topics"
description: "Details about Home Assistant."
date: 2016-10-20 12:00 -0800
sidebar: false
comments: false
sharing: true
footer: true
regenerate: true
hide_github_edit: true
---
This page is a collection of further details about Home Assistant.
{% assign details = site.details | sort: 'title' %}
{% for detail in details %}
* [{{detail.title}}]({{detail.url}})
{% endfor %}

4
source/developers/architecture.markdown
View File

@ -14,7 +14,7 @@ Before we dive into the Home Assistant architecture, let's get a clear overview
For more information about each part in this overview, <a href='/blog/2014/12/26/home-control-home-automation-and-the-smart-home/'>check out our blog</a>. Here's the tl;dr version of the blog:
* Home Control is responsible for collecting information and controlling devices.
* Home Automation triggers command based on user configurations.
* Home Automation triggers commands based on user configurations.
* Smart Home triggers commands based on previous behaviour.
<p class='img'>
@ -25,7 +25,7 @@ For more information about each part in this overview, <a href='/blog/2014/12/26
Overview of the home automation landscape
</p>
The Home Assistant core is responsible for Home Control. Home Assistant has four parts to make this possible:
The Home Assistant core is responsible for Home Control. Home Assistant contains four parts which make this possible:
* **Event Bus**: facilitates the firing and listening of events -- the beating heart of Home Assistant.
* **State Machine**: keeps track of the states of things and fires a `state_changed` event when a state has been changed.

12
source/developers/architecture_components.markdown
View File

@ -16,19 +16,19 @@ Home Assistant can be extended with **components**. Each component is responsibl
Diagram showing interaction between components and the Home Assistant core
</p>
There are two types of components within Home Assistant: components that interact with an Internet-of-Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type!
There are two types of components within Home Assistant: components that interact with an Internet of Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type!
#### {% linkable_title Components that interact with an Internet-of-Things domain %}
These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices.
For example, the built-in [`switch` component](/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform.
For example, the built-in [`switch` component](/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
If you want to add support for a new platform, check out the [add new platform section](/developers/add_new_platform/).
#### {% linkable_title Components that respond to events that happen within Home Assistant %}
These components provide small pieces of home automation logic or services that do common tasks within your house.
These components provide small pieces of home automation logic or involve services that do common tasks within your house.
For example, the [`device_sun_light_trigger` component](/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:
@ -50,11 +50,11 @@ For example, the [`device_sun_light_trigger` component](/components/device_sun_l
Turn on the lights
```
Look [here](https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py) for an extended example of a home automation component.
Look [here](https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py) for a comprehensive example of a home automation component.
### {% linkable_title The full picture %}
When we put all the different pieces of Home Assistant together, it's a close match for the initial home automation overview sketch. The smart home AI is not implemented yet, so it's not included in this picture.
When we put all the different pieces of Home Assistant together, it's a close match for the initial home automation overview sketch. The smart home AI has not been implemented yet, so it's not included in this picture.
<p class='img'>
<a href='/images/architecture/ha_full_architecture.png'>
@ -63,4 +63,4 @@ When we put all the different pieces of Home Assistant together, it's a close ma
Overview of the full Home Assistant architecture with a couple of loaded components and platforms
</p>
The platform logic for components uses third-party Python libraries to communicate with the devices so we can leverage the great device libraries in the Python community.
The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.

1
source/developers/development_testing.markdown
View File

@ -38,6 +38,7 @@ During development on a specific file, speed up your workflow by running tests a
```bash
$ flake8 homeassistant/core.py
$ pylint homeassistant/core.py
$ pydocstyle homeassistant/core.py
$ py.test tests/test_core.py
```

3
source/developers/helpers.markdown
View File

@ -9,11 +9,10 @@ sharing: true
footer: true
---
There are a bunch of online services which can help you if you are developing for Home Assistant or maintaining platforms/components. Some are directly connected to Pull Requests and the repositories itself, others are only publishing details and updates in our [gitter.im](https://gitter.im/home-assistant/home-assistant/devs) chatroom.
There are a bunch of online services which can help you if you are developing for Home Assistant or maintaining components. Some of these are directly connected to Pull Requests and the repositories, while others publish details and updates in our [Gitter.im](https://gitter.im/home-assistant/home-assistant/devs) chatroom.
- [Coveralls](https://coveralls.io/github/home-assistant/home-assistant)
- [Travis CI](https://travis-ci.org/home-assistant/home-assistant)
- [gemnasium](https://gemnasium.com/github.com/home-assistant/home-assistant)
- [Requires.io](https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev)
- [Pivotal Tracker](https://www.pivotaltracker.com/n/projects/1250084)

10
source/developers/rest_api.markdown
View File

@ -205,7 +205,7 @@ Returns an array of state changes in the past. Each object contains further deta
},
"entity_id": "sensor.weather_temperature",
"last_changed": "2016-02-06T22:15:00+00:00",
"last_updated": "2016-02-06T22:15:00+00:00"",
"last_updated": "2016-02-06T22:15:00+00:00",
"state": "-3.9"
},
{
@ -343,7 +343,7 @@ The return code is 200 if the entity existed, 201 if the state of a new entity w
},
"entity_id": "sun.sun",
"last_changed": "2016-05-30T21:43:29.204838+00:00",
"last_updated": "2016-05-30T21:47:30.533530+00:00"
"last_updated": "2016-05-30T21:47:30.533530+00:00",
"state": "below_horizon"
}
```
@ -364,7 +364,7 @@ You can pass an optional JSON object to be used as `event_data`.
```json
{
next_rising":"2016-05-31T03:39:14+00:00",
"next_rising":"2016-05-31T03:39:14+00:00",
}
```
@ -447,7 +447,7 @@ Set up event forwarding to another Home Assistant instance.
Requires a JSON object that represents the API to forward to.
```json
```javascript
{
"host": "machine",
"api_password": "my_super_secret_password",
@ -468,7 +468,7 @@ Cancel event forwarding to another Home Assistant instance.<br>
Requires a JSON object that represents the API to cancel forwarding to.
```json
```javascript
{
"host": "machine",
"api_password": "my_super_secret_password",

8
source/developers/website.markdown
View File

@ -17,11 +17,13 @@ You can use the "**Edit this page on GitHub**" link to edit pages without creati
For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a pull request.
To test your changes locally, you need to install the **Ruby** dependencies (gems):
To test your changes locally, you need to install **Ruby** and its dependencies (gems):
- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already.
- Install `bundler`, a dependency manager for Ruby: `gem install bundler`
- In your home-assistant.github.io root directory, run `bundle` to install the gems you need.
- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler`
- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need.
Short cut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler && bundle`
Then you can work on the documentation:

13
source/ecosystem/index.markdown Normal file
View File

@ -0,0 +1,13 @@
---
layout: page
title: "Ecosystem"
description: "External tools for Home Assistant"
date: 2016-10-26 00:46
sidebar: true
comments: false
sharing: true
footer: true
hide_github_edit: true
---
Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems. Use the sidebar to discover documentation for projects.

14
source/getting-started/android.markdown
View File

@ -9,15 +9,15 @@ sharing: true
footer: true
---
Home Assistant is not available on the Play Store or App Store. Instead, Home Assistant leverages the new [manifest.json support](https://w3c.github.io/manifest/) to allow Mobile devices to add the web application to your homescreen as if it was a native application.
Home Assistant is not available on the Play Store or App Store. Instead, Home Assistant leverages the new W3C [manifest.json](https://w3c.github.io/manifest/) support, allowing mobile devices to add the "web app" to your homescreen as if it was native.
On Android:
1. Open Chrome
2. Navigate to your Home Assistant instance
3. Click on the menu icon (three vertical dots)
4. Click on Add to Homescreen
5. A dialog will popup, click on Add
3. Tap on the Menu icon (three vertical bars)
4. Tap on Add to Homescreen
5. A dialog will popup; tap on Add
<p class='img' style='width:500px; margin-left: auto; margin-right: auto;'>
<img src='/images/screenshots/android-homescreen-guide.gif' />
@ -27,6 +27,6 @@ On iOS:
1. Open Safari
2. Navigate to your Home Assistant instance
3. Click on the share icon in the middle of the toolbar (on the bottom)
4. Click on Add to Home Screen
5. A dialog will popup, click on Add
3. Tap on the Share icon in the middle of the bottom toolbar
4. Tap on "Add to Home Screen"
5. A dialog will popup; tap on Add

4
source/getting-started/automation-create-first.markdown
View File

@ -26,9 +26,9 @@ automation:
service: light.turn_on
```
Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's is very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when HASS starts set `initial_state:` to `False`.
Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when HASS starts set `initial_state:` to `False`.
After a few days of running this automation rule you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home.
After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home.
```yaml
# Example configuration.yaml entry

2
source/getting-started/automation-trigger.markdown
View File

@ -141,5 +141,5 @@ automation:
entity_id: device_tracker.paulus
zone: zone.home
# Event is either enter or leave
event: enter
event: enter # or "leave"
```

16
source/getting-started/automation.markdown
View File

@ -9,15 +9,15 @@ sharing: true
footer: true
---
When all your devices are set up it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) but mainly you'll be using the automation component to set up your own rules.
When all your devices are set up, it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) – but you'll be using the automation component to set up your own rules, for the most part.
Home Assistant offers a wide range of automations. In the next few pages we'll try to guide you through all the different possibilities and options. Besides this documentation there are also a couple of people who have made their automation configurations [publicly available][cookbook-config].
Home Assistant offers a wide range of automation configurations. In the next few pages,, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available][cookbook-config].
[cookbook-config]: /cookbook/#example-configurationyaml
### {% linkable_title Automation basics %}
Before you can go ahead and create your own automations, it's important to learn the basics. To explore the basics, let's have a look at the following example home automation rule:
Before you can go ahead and create your own automations, it's important to learn the basics. To explore these, let's have a look at the following example home automation rule:
```text
(trigger) When Paulus arrives home
@ -27,19 +27,19 @@ Before you can go ahead and create your own automations, it's important to learn
The example consists of three different parts: a trigger, a condition and an action.
The first line is the trigger of the automation rule. Triggers describe events that should trigger the automation rule. In this case it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'.
The first line is the **trigger** of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'.
The second line is the condition part of the automation rule. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case we only want to act when the sun has set.
The second line is the **condition**. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set.
The third part is the action which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
The third part is the **action**, which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
<p class='note'>
The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on vs a light being on.
The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on versus a light being on.
</p>
### {% linkable_title Exploring the internal state %}
Automation rules interact directly with the internal state of Home Assistant so you'll need to familiarize yourself with it. Home Assistant exposes it's current state via the developer tools which are available at the bottom of the sidebar in the frontend. The <img src='/images/screenshots/developer-tool-states-icon.png' class='no-shadow' height='38' /> icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts:
Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. The <img src='/images/screenshots/developer-tool-states-icon.png' class='no-shadow' height='38' /> icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts:
| Name | Description | Example |
| ---- | ----- | ---- |

6
source/getting-started/autostart-macos.markdown
View File

@ -1,7 +1,7 @@
---
layout: page
title: "Autostart on OS X"
description: "Instructions how to setup Home Assistant to launch on OS X."
title: "Autostart on macOS"
description: "Instructions how to setup Home Assistant to launch on Apple macOS."
date: 2015-9-1 22:57
sidebar: true
comments: false
@ -9,7 +9,7 @@ sharing: true
footer: true
---
Setting up Home Assistant to run as a background service is simple. OS X will start it on boot and make sure it's always running.
Setting up Home Assistant to run as a background service is simple; macOS will start Home Assistant on boot and make sure it's always running.
To get Home Assistant installed as a background service, run:

17
source/getting-started/autostart-systemd.markdown
View File

@ -35,6 +35,23 @@ WantedBy=multi-user.target
EOF'
```
If you've setup Home Assistant in virtualenv following the guide the following template should work for you.
```
[Unit]
Description=Home Assistant
After=network.target
[Service]
Type=simple
User=hass
ExecStartPre=source /srv/hass/bin/activate
ExecStart=/srv/hass/bin/hass -c "/home/hass/.homeassistant"
[Install]
WantedBy=multi-user.target
```
There is also another [sample service file](https://raw.githubusercontent.com/home-assistant/home-assistant/master/script/home-assistant%40.service) available. To use this one, just download it.
```bash

20
source/getting-started/basic.markdown
View File

@ -9,7 +9,7 @@ sharing: true
footer: true
---
By default Home Assistant will try to detect your location and will automatically select a temperature unit and time zone based on your location. You can overwrite this by adding the following information to your `configuration.yaml`:
By default, Home Assistant will try to detect your location from IP address geolocation. Home Assistant will automatically select a temperature unit and time zone based on this location. You can overwrite this by adding the following information to your `configuration.yaml`:
```yaml
homeassistant:
@ -35,7 +35,7 @@ homeassistant:
### {% linkable_title Password protecting the web interface %}
The first thing you will want to add is a password for the web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section:
First, you'll want to add a password for the Home Assistant web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section:
```yaml
http:
@ -43,26 +43,24 @@ http:
```
<p class='note warning'>
If you are planning to expose your Home Assistant instance to the internet and don't set a password then your installation could be accessed by everybody.
If you decide to expose your Home Assistant instance to the internet and forget to set a password, your installation could be accessed by everybody.
</p>
See the [HTTP component documentation](/components/http/) for more options like HTTPS encryption.
See the [HTTP component documentation](/components/http/) for more options, such as the use of HTTPS encryption.
### {% linkable_title Setting up your phone or tablet %}
Home Assistant runs as a self-hosted web application and contains support to be added to your home screen. If you're on Android you can follow [the visual guide]({{site_root}}/getting-started/android/). For other devices, open Home Assistant on your mobile browser and tap the add to home screen option.
Home Assistant runs as a self-hosted web application and can be pinned to your home screen (with the new W3C standard). If you're on Android, follow [the visual guide]({{site_root}}/getting-started/android/). For other devices, open Home Assistant on your mobile browser and tap the "Add to Home Screen" (or similar) option.
### {% linkable_title Remote access %}
To make Home Assistant accessible while away from home, you will have to make it accessible.
If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible.
The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. Instructions on how to do this can be found by searching `<Router model> port forwarding instructions`.
The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching `<router model> port forwarding instructions`.
The problem with making a port accessible is that some Internet service providers will only offer dynamic IPs. This can cause you to be unable to access Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/).
A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/).
Just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post.
Remember: just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post.
If you want the very best security, check out [the instructions how to use Tor to access your home](/cookbook/tor_configuration/).
### [Next step: Setting up devices &raquo;](/getting-started/devices/)

6
source/getting-started/browsers.markdown
View File

@ -25,7 +25,7 @@ We would appreciate if you help to keep this page up-to-date and add feedback.
| [Firefox] | 43.0.1 | works | |
| [Iridium] | 48.2 | works | |
## {% linkable_title MacOS %}
## {% linkable_title macOS %}
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
@ -35,9 +35,9 @@ We would appreciate if you help to keep this page up-to-date and add feedback.
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Firefox] | 47.0 | works | |
| [Firefox] | 49.0 | works | |
| [Midori] | 0.5.11 | works | |
| [Chromium] | 50.0.2661.102 | works | |
| [Chromium] | 53.0.2785.143 | works | |
| [Conkeror] | 1.0.2 | works | |
| [Konqueror] | | unknown | |
| [Uzbl] | 0.9.0 | works | |

4
source/getting-started/configuration.markdown
View File

@ -9,7 +9,7 @@ sharing: true
footer: true
---
When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the user interface.
When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and appear in the user interface.
The location of the folder differs between operating systems:
@ -21,7 +21,7 @@ The location of the folder differs between operating systems:
If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`.
Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is. Throughout the documentation you will find snippets that you can add to your configuration file to enable that functionality.
Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains components to be loaded with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable functionality.
<p class='note'>
You will have to restart Home Assistant for changes to `configuration.yaml` to take effect.

8
source/getting-started/index.markdown
View File

@ -25,7 +25,7 @@ Running these commands will:
- Install Home Assistant
- Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123)
If you prefer to watch a video tutorial, [tktino](https://github.com/tktino) has made some great ones.
If you prefer to watch a video tutorial, [tktino](https://github.com/tktino) has made some great ones:
- [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY)
- [Mac OS X](https://www.youtube.com/watch?v=hej6ipN86ls)
@ -41,9 +41,9 @@ If you run into any issues, please see [the troubleshooting page](/getting-start
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting
### {% linkable_title What's next? %}

66
source/getting-started/installation-raspberry-pi-image.markdown
View File

@ -46,30 +46,38 @@ To login to your Raspberry Pi running HASSbian your going to be using a ssh clie
Connect to the Raspberry Pi over ssh. Default user name is `pi` and password is `raspberry`.
Linux and Mac OS users execute the following command in a terminal.
```bash
$ ssh pi@ip-address-of-pi
```
Windows users start [Putty][ssh-putty], enter the IP address of the Raspberry Pi in the *Host name* field and port 22 in the *Port* field. Then click *Open* and a terminal window will open. Enter the credentials. Default user name is `pi` and password is `raspberry`.
#### {% linkable_title Start/Stop/Restart Home Assistant on HaSSbian %}
Log in as the `pi` account account and execute the following commands:
```bash
sudo systemctl stop home-assistant@homeassistant.service
$ sudo systemctl stop home-assistant@homeassistant.service
```
Replace `stop` with `start` or `restart` to get the desired functionality.
To get the current state of the `homeassistant.service` replace `stop` with `status`.
#### {% linkable_title Update Home Assistant on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo systemctl stop home-assistant@homeassistant.service
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
pip3 install --upgrade homeassistant
exit
sudo systemctl start home-assistant@homeassistant.service
$ sudo systemctl stop home-assistant@homeassistant.service
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ pip3 install --upgrade homeassistant
$ exit
$ sudo systemctl start home-assistant@homeassistant.service
```
This will in order do the following:
- Stop the Home Assistant service running on HASSbian
- Open a shell as the `homeassistant` user running the Homeassistant service and that has ownership over the Home Assistant installation.
- Change into the virtual Python environment at `/src/homeassistant/` containing the Home Assistant installation.
@ -79,60 +87,74 @@ This will in order do the following:
#### {% linkable_title Manually launch Home Assistant on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
hass
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ hass
```
This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first.
#### {% linkable_title Check your configuration on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
hass --script check_config
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ hass --script check_config
```
This will output any errors in your configuration files to console.
#### {% linkable_title Read the Home Assistant log file on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
cd /home/homeassistant/.homeassistant
nano homeassistant.log
$ sudo su -s /bin/bash homeassistant
$ cd /home/homeassistant/.homeassistant
$ nano homeassistant.log
```
This will in order do the following:
- Open a shell as the `homeassistant` user.
- Change directory to the Home Assistant configuration directory.
- Open the log file in the nano editor.
Optionaly, you can also view the log with `journalctl`.
Log in as the `pi` account and execute the following commands:
```bash
sudo journalctl -fu home-assistant@homeassistant.service
$ sudo journalctl -fu home-assistant@homeassistant.service
```
#### {% linkable_title Edit the Home Assistant configuration on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
cd /home/homeassistant/.homeassistant
nano configuration.yaml
$ sudo su -s /bin/bash homeassistant
$ cd /home/homeassistant/.homeassistant
$ nano configuration.yaml
```
This will in order do the following:
- Open a shell as the `homeassistant` user.
- Change directory to the Home Assistant configuration directory.
- Open the configuration file in the nano editor.
It's generally recommended that you read the [Getting started][configuring-homeassistant] guide for how to configure Home Assistant.
#### {% linkable_title Upgrade and update HASSbian %}
HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following.
Log in as the `pi` account and execute the following commands:
```bash
sudo apt-get update
sudo apt-get upgrade
$ sudo apt-get update
$ sudo apt-get upgrade
```
Press `Y` to confirm that you would like to continue.
### {% linkable_title Troubleshooting %}

2
source/getting-started/installation-synology.markdown
View File

@ -46,7 +46,7 @@ $ ./python3 -m ensurepip
Use PIP to install Homeassistant package
```bash
$ ./python3 pip install homeassistant
$ ./python3 -m pip install homeassistant
```
Create homeassistant config directory & switch to it

11
source/getting-started/securing.markdown
View File

@ -9,20 +9,21 @@ sharing: true
footer: true
---
One of the reasons to use Home Assistant is that it's not depending on cloud services. Even if you are only using Home Assistant in your local network, you should consider securing your instance.
One major advantage of Home Assistant is that it's not dependent on cloud services. Even if you're only using Home Assistant on a local network, you should take steps to secure your instance.
### {% linkable_title Checklist %}
- [Protect your web interface with a password](https://home-assistant.io/getting-started/basic/#password-protecting-the-web-interface)
- Secure your host. Sources could be [Red Hat Enterprise Linux 7 Security Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/pdf/Security_Guide/Red_Hat_Enterprise_Linux-7-Security_Guide-en-US.pdf), [CIS Red Hat Enterprise Linux 7 Benchmark](https://benchmarks.cisecurity.org/tools2/linux/CIS_Red_Hat_Enterprise_Linux_7_Benchmark_v1.0.0.pdf), or the [Securing Debian Manual](https://www.debian.org/doc/manuals/securing-debian-howto/index.en.html).
- Restrict network access to your device. Set `PermitRootLogin no` in your sshd config (usually `/etc/ssh/sshd_config`) and to use keys for authentication instead of passwords.
- Don't run Home Assistant as root.
- Restrict network access to your devices. Set `PermitRootLogin no` in your sshd config (usually `/etc/ssh/sshd_config`) and to use SSH keys for authentication instead of passwords.
- Don't run Home Assistant as root – consider the Principle of Least Privilege.
- Keep your [secrets](/topics/secrets/) safe.
Additional points if you want to allow remote access:
If you want to allow remote access, consider these additional points:
- Protect your communication with [TLS](blog/2015/12/13/setup-encryption-using-lets-encrypt/)
- Protect your communication with [TLS](/blog/2015/12/13/setup-encryption-using-lets-encrypt/)
- Protect your communication with [Tor](/cookbook/tor_configuration/)
- Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/)
- Use a [proxy](/cookbook/apache_configuration/)

10
source/getting-started/updating.markdown
View File

@ -18,18 +18,18 @@ $ pip3 install --upgrade homeassistant
Different installation methods as [HASSbian](/getting-started/installation-raspberry-pi-image/#update-home-assistant-on-hassbian), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/#upgrading), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv/#upgrading-home-assistant) may have an alternative way for updating Home Assistant.
After updating, restart Home Assistant for the changes to take effect. This means that you have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon if you use any.
After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon (if applicable)
<p class='note note'>
The upgrade needs to be run as the same user as the installation was done to avoid permission errors.
To avoid permission errors, the upgrade must be run as the same user as the installation was completed.
</p>
[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant.
#### {% linkable_title Run a specific version %}
It can happen that a version doesn't play well with your hardware setup. If that's the case you can downgrade to a previous release.
In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release:
```bash
$ pip3 install homeassistant==0.XX.X
@ -37,10 +37,10 @@ $ pip3 install homeassistant==0.XX.X
#### {% linkable_title Run the development version %}
If you want to stay on top of the development of Home Assistant then you can upgrade to the `dev` branch.
If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to `dev`.
<p class='note warning'>
This can result in an unstable system, loss of data, etc. etc.
The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption.
</p>
```bash

7
source/getting-started/z-wave.markdown
View File

@ -23,10 +23,10 @@ Make sure you have the correct dependencies installed before running the script:
$ sudo apt-get install cython3 libudev-dev python3-sphinx python3-setuptools
```
Make sure you have at least version 0.23 of cython.
Make sure you have at least version 0.23 and at the most 0.24.1 of cython.
```bash
$ sudo pip3 install --upgrade cython
$ sudo pip3 install --upgrade cython==0.24.1
```
Then get the OpenZWave files and switch to the `python3` branch:
@ -43,14 +43,13 @@ $ sudo PYTHON_EXEC=$(which python3) make install
<p class='note'>
Instead of `make install`, you can alternatively build your own python-openzwave package which can be easily uninstalled:
</p>
```bash
$ sudo apt-get install -y checkinstall
$ sudo PYTHON_EXEC=$(which python3) checkinstall --pkgname python-openzwave --pkgversion 1.0 --provides python-openzwave
```
</p>
With this installation, your `config_path` needed below will resemble:
```bash

BIN
source/images/ios/NotificationActionFlow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

BIN
source/images/ios/PushNotificationLayout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB

BIN
source/images/ios/actions.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 222 KiB

BIN
source/images/ios/attachment.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 132 KiB

BIN
source/images/ios/control1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 422 KiB

BIN
source/images/ios/control2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 342 KiB

BIN
source/images/ios/example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 203 KiB

BIN
source/images/ios/expanded_attachment.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.5 MiB

BIN
source/images/ios/map.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.8 MiB