diff --git a/_config.yml b/_config.yml index e658ece8fe8..081fb5711d5 100644 --- a/_config.yml +++ b/_config.yml @@ -140,13 +140,13 @@ social: # Home Assistant release details current_major_version: 0 current_minor_version: 64 -current_patch_version: 0 -date_released: 2018-02-26 +current_patch_version: 3 +date_released: 2018-03-02 # Either # or the anchor link to latest release notes in the blog post. # Must be prefixed with a # and have double quotes around it. # Major release: -patch_version_notes: "#release-0641---february-27" +patch_version_notes: "#release-0643---march-2" # Minor release (Example #release-0431---april-25): # Date we moved to Discourse for comments diff --git a/source/_addons/lets_encrypt.markdown b/source/_addons/lets_encrypt.markdown index fe3894e6f89..c0cbf10bbea 100644 --- a/source/_addons/lets_encrypt.markdown +++ b/source/_addons/lets_encrypt.markdown @@ -14,7 +14,7 @@ featured: false You should not use this if you are also using the [DuckDNS add-on]. The DuckDNS add-on has integrated Let's Encrypt support.

-Setup and manage a [Let's Encrypt](https://letsencrypt.org/) certificate. This addon will create a certificate on the first run and will auto-renew if the certificate is within 30 days of expiration. +Setup and manage a [Let's Encrypt](https://letsencrypt.org/) certificate. This addon will create a certificate on the first run and will auto-renew if the certificate is within 30 days of expiration. This add-on uses port 80 to verify the certificate request. You will need to stop all other add-ons that also use this port. ```json { diff --git a/source/_addons/nginx_proxy.markdown b/source/_addons/nginx_proxy.markdown index 8fd22956e72..f306fccbe5e 100644 --- a/source/_addons/nginx_proxy.markdown +++ b/source/_addons/nginx_proxy.markdown @@ -15,13 +15,23 @@ In the `http` section of the `configuration.yaml` file remove `ssl_certificate` ```json { - "domain": "home.example.com" + "domain": "home.example.com", + "certfile": "fullchain.pem", + "keyfile": "privkey.pem", + "customize": { + "active": false, + "default": "nginx_proxy_default*.conf", + "servers": "nginx_proxy/*.conf" + } } ``` Configuration variables: - **domain** (*Required*): Domain they will proxy run with it. +- **certfile** (*Required*): Certificate file to use in the /ssl dir. +- **keyfile** (*Required*): Private key file to use in the /ssl dir. +- **customize** (*Optional*): If true, additional NGINX configuration files for the default server and additional servers are read from files in the /share dir specified by the `default` and `servers` variables.

It is possible to deactivate port 80 if you need this for things like `emulate_hue`. Remove the host port from Network option of this add-on. diff --git a/source/_components/binary_sensor.hikvision.markdown b/source/_components/binary_sensor.hikvision.markdown index ae37f2e9797..803e8b40a2a 100644 --- a/source/_components/binary_sensor.hikvision.markdown +++ b/source/_components/binary_sensor.hikvision.markdown @@ -17,6 +17,10 @@ The Hikvision Binary Sensor is a platform that parses the event stream of a [Hik The platform will automatically add all sensors to Home Assistant that are configured within the camera/nvr interface to "Notify the surveillance center" as a trigger. If you would like to hide a sensor type you can do so by either unchecking "Notify the surveillance center" in the camera configuration or by using the "ignored" customize option detailed below. +

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

+ For example, if you configure a camera with the name "Front Porch" that has motion detection and line crossing events enabled to notify the surveillance center the following binary sensors will be added to Home Assistant: ``` diff --git a/source/_components/bmw_connected_drive.markdown b/source/_components/bmw_connected_drive.markdown index 92bd4723cdf..21e7e04ecf5 100644 --- a/source/_components/bmw_connected_drive.markdown +++ b/source/_components/bmw_connected_drive.markdown @@ -22,8 +22,7 @@ To enable this component in your installation, add the following to your ```yaml # Example configuration.yaml entry bmw_connected_drive: - mycar: - name: Car 1 + name: username: USERNAME_BMW_CONNECTED_DRIVE password: PASSWORD_BMW_CONNECTED_DRIVE country: COUNTRY_BMW_CONNECTED_DRIVE diff --git a/source/_components/climate.zwave.markdown b/source/_components/climate.zwave.markdown index 3c5f96f7247..0669e0dfc69 100644 --- a/source/_components/climate.zwave.markdown +++ b/source/_components/climate.zwave.markdown @@ -46,12 +46,12 @@ automation: at: "20:00:00" action: - service: climate.set_operation_mode - entity_id: climate.remotec_zxt120_heating_1_id data: + entity_id: climate.remotec_zxt120_heating_1_id operation_mode: Heat - service: climate.set_temperature - entity_id: climate.remotec_zxt120_heating_1_39 data: + entity_id: climate.remotec_zxt120_heating_1_39 temperature: 24 ``` @@ -65,8 +65,8 @@ automation: at: "21:00:00" action: - service: climate.set_operation_mode - entity_id: climate.remotec_zxt120_heating_1_id data: + entity_id: climate.remotec_zxt120_heating_1_id operation_mode: 'Off' ``` diff --git a/source/_components/device_tracker.gpslogger.markdown b/source/_components/device_tracker.gpslogger.markdown index 1f1437dca27..3b1bbb33201 100644 --- a/source/_components/device_tracker.gpslogger.markdown +++ b/source/_components/device_tracker.gpslogger.markdown @@ -39,7 +39,7 @@ After the launch, go to **General Options**. Enable **Start on bootup** and **St GPSLogger Settings

-Go to **Logging details** and disable **Log to GPX**. **Log to KML**, and **Log to NMEA**. Enable **Log to custom URL**. +Go to **Logging details** and disable **Log to GPX**, **Log to KML** and **Log to NMEA**. Enable **Log to custom URL**.

diff --git a/source/_components/google_assistant.markdown b/source/_components/google_assistant.markdown index 50c311a624e..afd653b7dc2 100644 --- a/source/_components/google_assistant.markdown +++ b/source/_components/google_assistant.markdown @@ -68,7 +68,7 @@ agent_user_id: required: false type: string api_key: - description: An API Key generated for the project from [Google Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) which allows you to update devices without unlinking and relinking an account (see setup below). If not provided then the request_sync service is not exposed. + description: An API Key generated for the project from [Google Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) which allows you to update devices without unlinking and relinking an account (see step 9 below). If not provided then the `google_assistant.request_sync` service is not exposed. It is recommended to set up this configuration key as it also allows the usage of the following command, "Ok Google, sync my devices". Once you have setup this componenet you will need to call this service (or command) each time you add a new device that you wish to control via the Google Assistant integration. required: false type: string expose_by_default: diff --git a/source/_components/image_processing.dlib_face_identify.markdown b/source/_components/image_processing.dlib_face_identify.markdown index 1e47bf13e40..4f3d267f534 100644 --- a/source/_components/image_processing.dlib_face_identify.markdown +++ b/source/_components/image_processing.dlib_face_identify.markdown @@ -36,3 +36,7 @@ Configuration variables: - **entity_id** (*Required*): A camera entity id to get picture from. - **name** (*Optional*): This parameter allows you to override the name of your `image_processing` entity. - **faces** array (*Required*): List of faces sources. + +

+If the platform fails to load because it could not install its requirement, install cmake: `sudo apt-get install cmake`. +

diff --git a/source/_components/influxdb.markdown b/source/_components/influxdb.markdown index 2e13714e90f..3f606caf030 100644 --- a/source/_components/influxdb.markdown +++ b/source/_components/influxdb.markdown @@ -23,7 +23,7 @@ The default InfluxDB configuration doesn't enforce authentication. If you have i influxdb: ``` -You will still need to create a database named `home_assistant` via InfluxDB's web interface or command line. For instructions how to create a database check the [InfluxDB documentation](https://docs.influxdata.com/influxdb/latest/introduction/getting_started/#creating-a-database) relevant to the version you have installed. +You will still need to create a database named `home_assistant` via InfluxDB's command line interface. For instructions on how to create a database check the [InfluxDB documentation](https://docs.influxdata.com/influxdb/latest/introduction/getting_started/#creating-a-database) relevant to the version you have installed. Configuration variables: diff --git a/source/_components/light.decora_wifi.markdown b/source/_components/light.decora_wifi.markdown index 48ce82aa3aa..cf2c5556266 100644 --- a/source/_components/light.decora_wifi.markdown +++ b/source/_components/light.decora_wifi.markdown @@ -8,12 +8,12 @@ comments: false sharing: true footer: true ha_category: Light -ha_iot_class: "Local Polling" +ha_iot_class: "Cloud Polling" logo: leviton.png ha_release: 0.51 --- -Support for [Leviton Decora Wi-Fi](http://www.leviton.com/en/products/lighting-controls/decora-smart-with-wifi) dimmers/switches. +Support for [Leviton Decora Wi-Fi](http://www.leviton.com/en/products/lighting-controls/decora-smart-with-wifi) dimmers/switches via the MyLeviton API. Supported devices (tested): diff --git a/source/_components/media_player.markdown b/source/_components/media_player.markdown index 62c1af3a4cc..90507d40e5d 100644 --- a/source/_components/media_player.markdown +++ b/source/_components/media_player.markdown @@ -20,7 +20,7 @@ Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, | ---------------------- | -------- | ------------------------------------------------ | | `entity_id` | yes | Target a specific media player. Defaults to all. | -#### {% linkable_title Service `media_player/volume_mute` %} +#### {% linkable_title Service `media_player.volume_mute` %} | Service data attribute | Optional | Description | |------------------------|----------|--------------------------------------------------| @@ -34,14 +34,14 @@ Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, | `entity_id` | yes | Target a specific media player. Defaults to all. | | `volume_level` | no | Float for volume level | -#### {% linkable_title Service `media_player/media_seek` %} +#### {% linkable_title Service `media_player.media_seek` %} | Service data attribute | Optional | Description | |------------------------|----------|--------------------------------------------------------| | `entity_id` | yes | Target a specific media player. Defaults to all. | | `seek_position` | no | Position to seek to. The format is platform dependent. | -#### {% linkable_title Service `media_player/play_media` %} +#### {% linkable_title Service `media_player.play_media` %} | Service data attribute | Optional | Description | | -----------------------| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -49,14 +49,14 @@ Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, | `media_content_id` | no | A media identifier. The format of this is component dependent. For example, you can provide URLs to Sonos and Cast but only a playlist ID to iTunes. | | `media_content_type` | no | A media type. Must be one of `music`, `tvshow`, `video`, `episode`, `channel` or `playlist`. For example, to play music you would set `media_content_type` to `music`. | -#### {% linkable_title Service `media_player/select_source` %} +#### {% linkable_title Service `media_player.select_source` %} | Service data attribute | Optional | Description | | ---------------------- | -------- | ---------------------------------------------------- | | `entity_id` | yes | Target a specific media player. Defaults to all. | | `source` | no | Name of the source to switch to. Platform dependent. | -#### {% linkable_title Service `media_player/shuffle_set` %} +#### {% linkable_title Service `media_player.shuffle_set` %} Currently only supported on [Spotify](/components/media_player.spotify/), [MPD](/components/media_player.mpd/), [Kodi](/components/media_player.kodi/), [Squeezebox](/components/media_player.squeezebox/) and [Universal](/components/media_player.universal/). diff --git a/source/_components/media_player.samsungtv.markdown b/source/_components/media_player.samsungtv.markdown index 10201bfbb93..3cabb0f43d6 100644 --- a/source/_components/media_player.samsungtv.markdown +++ b/source/_components/media_player.samsungtv.markdown @@ -57,6 +57,7 @@ Currently known supported models: - K5579 (port must be set to 8001, On/Off, Forward/Backward, Volume control, but no Play button) - K6500AF (port must be set to 8001) - KS8005 (port must be set to 8001, and `pip3 install websocket-client` must be executed) +- KU6020 (port must be set to 8001, and `pip3 install websocket-client` must be executed) - KU6290 (port must be set to 8001) - KU7000 (port must be set to 8001) - MU6170UXZG (port must be set to 8001, and `pip3 install websocket-client` must be executed) diff --git a/source/_components/recorder.markdown b/source/_components/recorder.markdown index c52520baa4d..6e51c653824 100644 --- a/source/_components/recorder.markdown +++ b/source/_components/recorder.markdown @@ -156,14 +156,29 @@ If the `recorder` component is activated then some components support `restore_s | PostgreSQL | `postgresql://scott:tiger@SERVER_IP/DB_NAME` | | MS SQL Server | `mssql+pymssql://user:pass@SERVER_IP/DB_NAME?charset=utf8` | -+

-+If you are running a database server instance on the same server as Home Assistant then you must ensure that this service starts before Home Assistant. For a Linux instance running Systemd (Raspberry Pi, Debian, Ubuntu and others) then you should edit the file /etc/systemd/system/home-assistant@homeassistant.service as root (e.g. sudo nano /etc/systemd/system/home-assistant@homeassistant.service) and add the service - for PostgreSQL: -+``` -+[Unit] -+Description=Home Assistant -+After=network.target postgresql.service -+``` -+

+

+If you use MariaDB 10 you need to add port 3307 to the SERVER_IP, e.g., `mysql://user:password@SERVER_IP:3307/DB_NAME?charset=utf8`. + ++If you are running a database server instance on the same server as Home Assistant then you must ensure that this service starts before Home Assistant. For a Linux instance running Systemd (Raspberry Pi, Debian, Ubuntu and others) then you should edit the service file. + +```bash +$ sudo nano /etc/systemd/system/home-assistant@homeassistant.service +``` + +and add the service for PostgreSQL: + +``` +[Unit] +Description=Home Assistant +After=network.target postgresql.service +``` + +Save the file then reload `systemctl`: + +```bash +$ sudo systemctl daemon-reload +``` +

## {% linkable_title Installation notes %} diff --git a/source/_components/sensor.filesize.markdown b/source/_components/sensor.filesize.markdown index 91eb16037ce..8c46e8c1b29 100644 --- a/source/_components/sensor.filesize.markdown +++ b/source/_components/sensor.filesize.markdown @@ -13,7 +13,7 @@ ha_iot_class: "Local Polling" ha_release: 0.64 --- -Component for displaying the size of a file. Note that paths must be added to [whitelist_external_dirs](https://home-assistant.io/docs/configuration/basic/). +Component for displaying the size in MB of a file. Note that paths must be added to [whitelist_external_dirs](https://home-assistant.io/docs/configuration/basic/). Add to your config: ```yaml diff --git a/source/_components/sensor.mqtt.markdown b/source/_components/sensor.mqtt.markdown index e6b96b3bc1d..aebe44beb99 100644 --- a/source/_components/sensor.mqtt.markdown +++ b/source/_components/sensor.mqtt.markdown @@ -82,6 +82,32 @@ json_attributes: In this section you find some real life examples of how to use this sensor. +### {% linkable_title JSON attributes configuration %} + +The example sensor below shows a configuration example which uses JSON in the state topic to add extra attributes. It also makes use of the availability topic. Attributes can then be extracted in [Templates](configuration/templating/#attributes); Example to extract data from the sensor below {% raw %}'{{ states.sensor.bs_client_name.attributes.ClientName }}'{% endraw %}. + +{% raw %} +```yaml +# Example configuration.yml entry +sensor: + - platform: mqtt + state_topic: "HUISHS/BunnyShed/NodeHealthJSON" + name: "BS RSSI" + unit_of_measurement: "dBm" + value_template: '{{ value_json.RSSI }}' + availability_topic: "HUISHS/BunnyShed/status" + payload_available: "online" + payload_not_available: "offline" + json_attributes: + - ClientName + - IP + - MAC + - RSSI + - HostName + - ConnectedSSID +``` +{% endraw %} + ### {% linkable_title Get battery level %} If you are using the [Owntracks](/components/device_tracker.owntracks/) and enable the reporting of the battery level then you can use a MQTT sensor to keep track of your battery. A regular MQTT message from Owntracks looks like this: diff --git a/source/_components/sensor.pollen.markdown b/source/_components/sensor.pollen.markdown index 9a9ddc05ec6..8c613882242 100644 --- a/source/_components/sensor.pollen.markdown +++ b/source/_components/sensor.pollen.markdown @@ -30,7 +30,7 @@ liking): ```yaml sensor: platform: pollen - zip_code: ZIP_CODE + zip_code: "00544" monitored_conditions: - allergy_average_forecasted - allergy_average_historical @@ -42,15 +42,20 @@ sensor: {% configuration %} zip_code: - description: the U.S. ZIP code to gather data for + description: the U.S. ZIP code to gather data for (as a quoted string) required: true - type: int + type: string monitored_conditions: description: the metric types to monitor; valid values are specified below required: true type: list {% endconfiguration %} +

+It is important to ensure the ZIP code is quoted if it starts with a 0. Unquoted +ZIP codes that start with 0 will cause errors. +

+ ## {% linkable_title Available Metrics %} The following metrics can be monitored: diff --git a/source/_components/sensor.scrape.markdown b/source/_components/sensor.scrape.markdown index 06d1cd80424..cbbaf5553e0 100644 --- a/source/_components/sensor.scrape.markdown +++ b/source/_components/sensor.scrape.markdown @@ -126,7 +126,7 @@ sensor: resource: https://elen.nu/timpriser-pa-el-for-elomrade-se3-stockholm/ name: Electricity price select: ".elspot-content" - value_template: '{{ value.split(" ")[0] }}' + value_template: '{{ ((value.split(" ")[0]) | replace (",", ".")) }}' unit_of_measurement: "öre/kWh" ``` {% endraw %} diff --git a/source/_components/sensor.statistics.markdown b/source/_components/sensor.statistics.markdown index 01abb92ca24..a5b126fac4a 100644 --- a/source/_components/sensor.statistics.markdown +++ b/source/_components/sensor.statistics.markdown @@ -16,7 +16,7 @@ ha_release: "0.30" The `statistics` sensor platform consumes the state from other sensors. Besides the maximum and the minimum values, the total, mean, median, variance and the standard deviation are also available as attributes. If it's a binary sensor then only state changes are counted. -If you are running the [recorder](/components/recorder/) component, on startup the data is read from the database. So after a restart of the platform, you will immediately have data available. If you're using the [history](/components/history/) component, this will automatically also start the recoder component on startup. +If you are running the [recorder](/components/recorder/) component, on startup the data is read from the database. So after a restart of the platform, you will immediately have data available. If you're using the [history](/components/history/) component, this will automatically also start the `recorder` component on startup. If you are *not* running the `recorder` component, it can take time till the sensor starts to work because a couple of attributes need more than one value to do the calculation. To enable the statistics sensor, add the following lines to your `configuration.yaml`: diff --git a/source/_components/sensor.worldclock.markdown b/source/_components/sensor.worldclock.markdown index c195fe37ce9..e9f4ac8f9bf 100644 --- a/source/_components/sensor.worldclock.markdown +++ b/source/_components/sensor.worldclock.markdown @@ -14,7 +14,7 @@ ha_release: pre 0.7 --- -The `worldclock` sensor platform simple displays the current time in a different time zone +The `worldclock` sensor platform simply displays the current time in a different time zone To enable this sensor in your installation, add the following to your `configuration.yaml` file: diff --git a/source/_components/vacuum.xiaomi_miio.markdown b/source/_components/vacuum.xiaomi_miio.markdown index c8aafb0de9a..3d6a7908b81 100644 --- a/source/_components/vacuum.xiaomi_miio.markdown +++ b/source/_components/vacuum.xiaomi_miio.markdown @@ -13,8 +13,7 @@ ha_release: 0.51 ha_iot_class: "Local Polling" --- -The `xiaomi miio` vacuum platform allows you to control the state of your -[Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/). +The `xiaomi miio` vacuum platform allows you to control the state of your [Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/). Currently supported features are: @@ -50,10 +49,7 @@ Configuration variables: ## {% linkable_title Platform Services %} -In addition to [all of the services provided by the `vacuum` component] -]) (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`, -`set_fan_speed` and `send_command`), the `xiaomi` platform introduces specific -services to access the remote control mode of the robot. These are: +In addition to all of the services provided by the `vacuum` component (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`, `set_fan_speed` and `send_command`), the `xiaomi` platform introduces specific services to access the remote control mode of the robot. These are: - `xiaomi_remote_control_start` - `xiaomi_remote_control_stop` @@ -62,8 +58,7 @@ services to access the remote control mode of the robot. These are: ### {% linkable_title Service `vacuum.xiaomi_remote_control_start` %} -Start the remote control mode of the robot. You can then move it with -`remote_control_move`; when done, call `remote_control_stop`. +Start the remote control mode of the robot. You can then move it with `remote_control_move`; when done, call `remote_control_stop`. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| @@ -79,8 +74,7 @@ Exit the remote control mode of the robot. ### {% linkable_title Service `vacuum.xiaomi_remote_control_move` %} -Remote control the robot. Please ensure you first set it in remote control -mode with `remote_control_start`. +Remote control the robot. Please ensure you first set it in remote control mode with `remote_control_start`. | Service data attribute | Optional | Description | |---------------------------|----------|-------------------------------------------------------| @@ -102,9 +96,8 @@ Enter remote control mode, make one move, stop, and exit remote control mode. ## {% linkable_title Attributes %} -In addition to [all of the attributes provided by the `vacuum` component](https://home-assistant.io/components/vacuum/#attributes), -(`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, and -`params`), the `xiaomi` platform introduces specific attributes. These are: +In addition to [all of the attributes provided by the `vacuum` component](/components/vacuum/#attributes), +(`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, and `params`), the `xiaomi` platform introduces specific attributes. These are: - `cleaning_time` - `do_not_disturb` @@ -132,12 +125,45 @@ The following table shows the units of measurement for each attribute: ## {% linkable_title Retrieving the Access Token %}

-This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot -Vacuum, Xiaomi Philips Lights and Xiaomi IR Remote. The Xiaomi Gateway uses another security -method and requires a `key` (16 alphanumeric chars), which can be obtained -easily via a hidden menu item at the Mi-Home app. +As per [python-miio issue 185](https://github.com/rytilahti/python-miio/issues/185) the Mi-Home app no longer stores the token within the database (it's retrieved from Xiaomi servers from version 5.0.31+). Currently the only known fix is to uninstall, then install a downgraded version of the apk. Apkmirror is a trusted source for older versions of the app. [Mi-Home version 5.0.0](https://www.apkmirror.com/apk/xiaomi-inc/mihome/mihome-5-0-0-release/) is confirmed as working for the following Android methods. + +This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot Vacuum, Xiaomi Philips Lights and Xiaomi IR Remote. The Xiaomi Gateway uses another security method and requires a `key` (16 alphanumeric chars), which can be obtained +easily via a hidden menu item at the Mi-Home app or using the `miio` command line tool.

+#### {% linkable_title Miio command line tool %} + +You can install the command line tool with: + +```bash +$ npm install -g miio +``` + +Discovering devices on current network + +```bash +$ miio discover +``` + +This will list devices that are connected to the same network as your computer. Let it run for a while so it has a chance to reach all devices, as it might take a minute or two for all devices to answer. + +The commands outputs each device on this format: + +```text +Device ID: 48765421 +Model info: zhimi.airpurifier.m1 +Address: 192.168.100.9 +Token: token-as-hex-here via auto-token +Support: At least basic +``` + +The information output is: + +* __Device ID__ - the unique identifier of the device, does not change if the device is reset. +* __Model ID__ - the model id if it could be determined, this indicates what type of device it is +* __Address__ - the IP that the device has on the network +* __Token__ - the token of the device or ??? if it could not be automatically determined + #### {% linkable_title Windows and Android %} To fetch the token follow these instructions depending on your mobile phone platform. @@ -204,7 +230,7 @@ To fetch the token follow these instructions depending on your mobile phone plat 3. Get ADB f.e. `apt-get install android-tools-adb` 4. `adb devices` should list your device 5. `adb root` (does work for development builds only: ones with `ro.debuggable=1`) -6. `adb shell` +6. `adb shell` (for those using Magisk based root the previous command won't work. After entering a shell, type `su` to enter the root shell) 7. `echo "select name,localIP,token from devicerecord;" | sqlite3 /data/data/com.xiaomi.smarthome/databases/miio2.db` returns a list of all registered devices including IP address and token. #### {% linkable_title iOS %} diff --git a/source/_cookbook/configuration_yaml_by_greenturtwig.markdown b/source/_cookbook/configuration_yaml_by_greenturtwig.markdown index dcb11f84540..a5bc7c5b184 100644 --- a/source/_cookbook/configuration_yaml_by_greenturtwig.markdown +++ b/source/_cookbook/configuration_yaml_by_greenturtwig.markdown @@ -8,6 +8,6 @@ comments: false sharing: true footer: true ha_category: Example configuration.yaml -ha_external_link: https://github.com/GreenTurtwig/personal-home-automation/tree/master/Home%20Assistant +ha_external_link: https://github.com/GreenTurtwig/personal-home-automation/blob/master/configuration.yaml --- diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown index 77e8359eba1..3ac38b00a2f 100644 --- a/source/_docs/configuration/basic.markdown +++ b/source/_docs/configuration/basic.markdown @@ -28,7 +28,7 @@ Configuration variables: - **longitude** (*Optional*): Longitude of your location required to calculate the time the sun rises and sets. - **elevation** (*Optional*): Altitude above sea level in meters. Impacts weather/sunrise data. - **unit_system** (*Optional*): `metric` for Metric, `imperial` for Imperial. -- **time_zone** (*Optional*): Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones +- **time_zone** (*Optional*): Pick yours from here: [http://en.wikipedia.org/wiki/List_of_tz_database_time_zones](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - **name** (*Optional*): Name of the location where Home Assistant is running. - **customize** (*Optional*): [Customize](/docs/configuration/customizing-devices/) entities. - **customize_domain** (*Optional*): [Customize](/docs/configuration/customizing-devices/) all entities in a domain. diff --git a/source/_docs/configuration/events.markdown b/source/_docs/configuration/events.markdown index 7d4be04c87f..ff0bcd35140 100644 --- a/source/_docs/configuration/events.markdown +++ b/source/_docs/configuration/events.markdown @@ -18,7 +18,7 @@ Home Assistant contains a few built-in events that are used to coordinate betwee Event `homeassistant_start` is fired when all components from the configuration have been intitialized. This is the event that will start the timer firing off `time_changed` events.

- Starting 0.42, it is no longer possible to listen for event `homeassistant_start`. Use the 'homeassistant' [platform](docs/automation/trigger) instead. + Starting 0.42, it is no longer possible to listen for event `homeassistant_start`. Use the 'homeassistant' [platform](/docs/automation/trigger) instead.

### {% linkable_title Event `homeassistant_stop` %} diff --git a/source/_docs/ecosystem/appdaemon/tutorial.markdown b/source/_docs/ecosystem/appdaemon/tutorial.markdown index 6a9998bced3..962be8ea9f1 100755 --- a/source/_docs/ecosystem/appdaemon/tutorial.markdown +++ b/source/_docs/ecosystem/appdaemon/tutorial.markdown @@ -43,22 +43,38 @@ The best way to show what AppDaemon does is through a few simple examples. ### {% linkable_title Sunrise/Sunset Lighting %} -Lets start with a simple App to turn a light on every night at sunset and off every morning at sunrise. Every App when first started will have its `initialize()` function called which gives it a chance to register a callback for AppDaemons's scheduler for a specific time. In this case we are using `run_at_sunrise()` and `run_at_sunset()` to register 2 separate callbacks. The argument `0` is the number of seconds offset from sunrise or sunset and can be negative or positive. For complex intervals it can be convenient to use Python's `datetime.timedelta` class for calculations. When sunrise or sunset occurs, the appropriate callback function, `sunrise_cb()` or `sunset_cb()` is called which then makes a call to Home Assistant to turn the porch light on or off by activating a scene. The variables `args["on_scene"]` and `args["off_scene"]` are passed through from the configuration of this particular App, and the same code could be reused to activate completely different scenes in a different version of the App. +Lets start with a simple App to turn a light on every night fifteen +minutes (900 seconds) before sunset and off every morning at sunrise. +Every App when first started will have its ``initialize()`` function +called which gives it a chance to register a callback for AppDaemons's +scheduler for a specific time. In this case we are using +`run_at_sunrise()` and `run_at_sunset()` to register 2 separate +callbacks. The named argument `offset` is the number of seconds offset +from sunrise or sunset and can be negative or positive (it defaults to +zero). For complex intervals it can be convenient to use Python's +`datetime.timedelta` class for calculations. In the example below, +when sunrise or just before sunset occurs, the appropriate callback +function, `sunrise_cb()` or `before_sunset_cb()` is called which +then makes a call to Home Assistant to turn the porch light on or off by +activating a scene. The variables `args["on_scene"]` and +`args["off_scene"]` are passed through from the configuration of this +particular App, and the same code could be reused to activate completely +different scenes in a different version of the App. ```python -import homeassistant.appapi as appapi + import appdaemon.plugins.hass.hassapi as hass -class OutsideLights(appapi.AppDaemon): + class OutsideLights(hass.Hass): - def initialize(self): - self.run_at_sunrise(self.sunrise_cb, 0) - self.run_at_sunset(self.sunset_cb, 0) - - def sunrise_cb(self, kwargs): - self.turn_on(self.args["off_scene"]) + def initialize(self): + self.run_at_sunrise(self.sunrise_cb) + self.run_at_sunset(self.before_sunset_cb, offset=-900) + + def sunrise_cb(self, kwargs): + self.turn_on(self.args["off_scene"]) - def sunset_cb(self, kwargs): - self.turn_on(self.args["on_scene"]) + def before_sunset_cb(self, kwargs): + self.turn_on(self.args["on_scene"]) ``` diff --git a/source/_docs/ecosystem/nginx.markdown b/source/_docs/ecosystem/nginx.markdown index 24e4c7e0849..46ae6152d1c 100644 --- a/source/_docs/ecosystem/nginx.markdown +++ b/source/_docs/ecosystem/nginx.markdown @@ -14,13 +14,17 @@ Using NGINX as a proxy for Home Assistant allows you to serve Home Assistant sec ### {% linkable_title 1. Get a domain name forwarded to your IP %} -Chances are, you have a dynamic IP Address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later. +Chances are, you have a dynamic IP address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later. ### {% linkable_title 2 Install nginx on your server %} This will vary depending on your OS. Check out Google for this. After installing, ensure that NGINX is not running. +

+You will at least need nginx >= 1.3.13, as WebSocket support is required for the reverse proxy. +

+ ### {% linkable_title 3. Obtain an SSL certificate %} There are two ways of obtaining an SSL certificate. @@ -28,7 +32,7 @@ There are two ways of obtaining an SSL certificate. #### {% linkable_title Using Let's Encrypt %} If you purchased your own domain, you can use https://letsencrypt.org/ to obtain a free, publicly trusted SSL certificate. This will allow you to work with services like IFTTT. Download and install per the instructions online and get a certificate using the following command. -``` +```bash $ sudo ./letsencrypt-auto certonly --standalone -d example.com -d www.example.com ``` @@ -75,14 +79,13 @@ $ sudo ln ../sites-available/hass default Double check this configuration to ensure all settings are correct and start nginx. - ### {% linkable_title 8. Port forwarding. %} Forward ports 443 and 80 to your server on your router. Do not forward port 8123. ### {% linkable_title NGINX Config %} -``` +```text map $http_upgrade $connection_upgrade { default upgrade; '' close; diff --git a/source/_docs/installation/docker.markdown b/source/_docs/installation/docker.markdown index 310be8c0282..bc7b0998cb4 100644 --- a/source/_docs/installation/docker.markdown +++ b/source/_docs/installation/docker.markdown @@ -20,14 +20,16 @@ $ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/ ### {% linkable_title macOS %} -When using `boot2docker` on macOS you are unable to map the local time to your Docker container. Use `-e "TZ=America/Los_Angeles"` instead of `-v /etc/localtime:/etc/localtime:ro`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). +When using `docker-ce` (or `boot2docker`) on macOS, you are unable to map the local timezone to your Docker container (see Docker issue https://github.com/docker/for-mac/issues/44). Instead of `-v /etc/localtime:/etc/localtime:ro`, just pass in the timezone environment variable when you launch the container, ex: `-e "TZ=America/Los_Angeles"`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). -Additionally, if your expectation is that you will be able to browse directly to `http://localhost:8123` on your macOS host, then you will also need to replace the `--net=host` switch with `-p 8123:8123`. This is currently the only way to forward ports on to your actual host (macOS) machine instead of the virtual machine inside `xhyve`. More detail on this can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10). +If you wish to browse directly to `http://localhost:8123` from your macOS host, meaning forward ports directly to the container, replace the `--net=host` switch with `-p 8123:8123`. More detail can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10). ```bash $ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant ``` +Alternatively, `docker-compose` works with any recent release of `docker-ce` on macOS. Note that (further down this page) we provide an example `docker-compose.yml` however it differs from the `docker run` example above. To make the .yml directives match, you would need to make _two_ changes: first add the equivalent `ports:` directive, then _remove_ the `network_mode: host` section. This is because `Port mapping is incompatible with network_mode: host:`. More details can be found at [Docker networking docs] (https://docs.docker.com/engine/userguide/networking/#default-networks). Note also the `/dev/tty*` device name used by your Arduino etc. devices will differ from the Linux example, so the compose `mount:` may require updates. + ### {% linkable_title Windows %} When running Home Assistant in Docker on Windows, you may have some difficulty getting ports to map for routing (since the `--net=host` switch actually applies to the hypervisor's network interface). To get around this, you will need to add port proxy ipv4 rules to your local Windows machine, like so (Replacing '192.168.1.10' with whatever your Windows IP is, and '10.0.50.2' with whatever your Docker container's IP is): @@ -160,7 +162,8 @@ As the docker command becomes more complex, switching to `docker-compose` can be ```yaml version: '3' services: - web: + homeassistant: + container_name: home-assistant image: homeassistant/home-assistant volumes: - /path/to/your/config:/config @@ -188,7 +191,8 @@ or in a `docker-compose.yml` file: ```yaml version: '3' services: - web: + homeassistant: + container_name: home-assistant image: homeassistant/home-assistant volumes: - /path/to/your/config:/config diff --git a/source/_docs/installation/hassbian/common-tasks.markdown b/source/_docs/installation/hassbian/common-tasks.markdown index 6fddcd360b6..73e96a07876 100644 --- a/source/_docs/installation/hassbian/common-tasks.markdown +++ b/source/_docs/installation/hassbian/common-tasks.markdown @@ -37,7 +37,7 @@ To get the current state of the `homeassistant.service` replace `stop` with `sta ### {% linkable_title Update Home Assistant %}

-You can also use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade home-assistant` +You can also use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade homeassistant`

Log in as the `pi` account and execute the following commands: diff --git a/source/_docs/installation/raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown index 178ad0abdf4..d7f3c231ef7 100644 --- a/source/_docs/installation/raspberry-pi.markdown +++ b/source/_docs/installation/raspberry-pi.markdown @@ -12,6 +12,14 @@ redirect_from: /getting-started/installation-raspberry-pi/ This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/). The installation will be installed in a [Virtual Environment](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite. +

+Although these installation steps specifically mention a Raspberry Pi, you can go ahead and proceed on any Linux install as well. This guide is also referred to as the "Advanced Guide" for a virtual environment install. +

+ +

+Please remember to ensure you're using an [appropriate power supply](https://www.raspberrypi.org/help/faqs/#powerReqs) with your Pi. Mobile chargers may not be suitable, since some are designed to only provide the full power with that manufacturer's handsets. USB ports on your computer also will not supply enough power and must not be used. +

+ Connect to the Raspberry Pi over SSH. Default password is `raspberry`. You will need to enable SSH access. The Raspberry Pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/). @@ -61,7 +69,13 @@ $ cd /srv/homeassistant $ python3 -m venv . $ source bin/activate ``` -Once you have activated the virtual environment you will notice the prompt change and then you can install Home Assistant. +Once you have activated the virtual environment (notice the prompt change) you will need to run the following command to install a required python package. + +```bash +(homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ python3 -m pip install wheel +``` + +Once you have installed the required python package it is now time to install Home Assistant! ```bash (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ pip3 install homeassistant @@ -79,3 +93,15 @@ When you run the `hass` command for the first time, it will download, install an

If you want setup `hass` as a daemon and autostart it on boot please refer to [Autostart Home Assistant](/docs/autostart/). + +### {% linkable_title Updating %} + +To update to the latest version of Home Assistant follow these simple steps: + +```bash +$ sudo su -s /bin/bash homeassistant +$ source /srv/homeassistant/bin/activate +$ pip3 install --upgrade homeassistant +``` + +Once the last command executes restart the Home Assistant service to apply the latest updates. Please keep in mind that some updates may take longer to boot up than others. If Home Assistant fails to start make sure you check the **Breaking Changes** from the [Release Notes](https://github.com/home-assistant/home-assistant/releases). diff --git a/source/_docs/installation/synology.markdown b/source/_docs/installation/synology.markdown index 9edf9fbb001..8885d8e868b 100644 --- a/source/_docs/installation/synology.markdown +++ b/source/_docs/installation/synology.markdown @@ -61,7 +61,7 @@ Create homeassistant config directory & switch to it ```bash # mkdir /volume1/homeassistant -# chown /volume1/homeassistant homeassistant +# chown homeassistant /volume1/homeassistant # chmod 755 /volume1/homeassistant # cd /volume1/homeassistant ``` diff --git a/source/_docs/installation/virtualenv.markdown b/source/_docs/installation/virtualenv.markdown index 51ab71aa141..54af7e09d85 100644 --- a/source/_docs/installation/virtualenv.markdown +++ b/source/_docs/installation/virtualenv.markdown @@ -16,6 +16,10 @@ It's recommended when installing Python packages that you use a [virtual environ _(If you're on a Debian based system, you will need to install Python virtual environment support using `apt-get install python3-pip python3-venv`.)_ +

+It is recommended to use the [advanced guide](/docs/installation/raspberry-pi/) which allows for the installation to run as a `homeassistant` user. The steps below may be shorter but some users find difficulty when applying updates and may run into issues. +

+ ### {% linkable_title Install %} 1. Create a virtual environment in your current directory: diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index a0f3737cbce..51eae400c43 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -44,7 +44,7 @@ The discovery topic need to follow a specific format: - ``: One of the supported components, eg. `binary_sensor`. - ``: (*Optional*) id of the node providing the topic. -- ``: The ID of the device. This will become the `entity_id` in Home Assistant. +- ``: "The ID of the device. This is only to allow for separate topics for each device and is not used for the `entity_id`." - `<>`: The topic `config` or `state` which defines the current action. The payload will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. All configuration variables which are *required* must be present in the initial payload send to `/config`. diff --git a/source/_docs/z-wave/devices.markdown b/source/_docs/z-wave/devices.markdown index 13d2966b4f4..92d43f00948 100644 --- a/source/_docs/z-wave/devices.markdown +++ b/source/_docs/z-wave/devices.markdown @@ -39,7 +39,7 @@ The key improvements are: ### {% linkable_title Z-Wave Security 2 %} -From 2 April 2017 all newly approved Z-Wave devices will have to support the Security 2 (S2) framework. At the time of writing this (September 2017) OpenZWave does not support the S2 framework. +From 2 April 2017 all newly approved Z-Wave devices will have to support the Security 2 (S2) framework. At the time of writing this (March 2018) OpenZWave does not support the S2 framework. ## {% linkable_title Device power %} diff --git a/source/_docs/z-wave/installation.markdown b/source/_docs/z-wave/installation.markdown index 03195547071..5974c16a201 100644 --- a/source/_docs/z-wave/installation.markdown +++ b/source/_docs/z-wave/installation.markdown @@ -43,7 +43,7 @@ On Raspberry Pi you will need to enable the serial interface in the `raspi-confi ```yaml # Example configuration.yaml entry zwave: - usb_path: /dev/ttyUSB0 + usb_path: /dev/ttyACM0 ``` {% configuration zwave %} diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html index 0f42206817a..2d770cb7a14 100644 --- a/source/_includes/asides/developers_navigation.html +++ b/source/_includes/asides/developers_navigation.html @@ -78,7 +78,14 @@
  • {% active_link /developers/frontend_add_more_info/ Add More Info Dialog %}
  • {% active_link /developers/frontend_creating_custom_panels/ Add Custom Panels %}
  • {% active_link /developers/frontend_creating_custom_ui/ Add Custom UI %}
    • -
  • {% active_link /developers/frontend_translation/ Translation %}
    • + + +
  • + {% active_link /developers/internationalization/ Internationalization %} +
      +
    • {% active_link /developers/internationalization/backend_localization/ Backend Localization %}
      • +
    • {% active_link /developers/internationalization/custom_component_localization/ Custom Component Localization %}
      • +
    • {% active_link /developers/internationalization/translation/ Translation %}
  • diff --git a/source/_posts/2018-02-26-release-64.markdown b/source/_posts/2018-02-26-release-64.markdown index 32185857ce8..c745d771fd5 100644 --- a/source/_posts/2018-02-26-release-64.markdown +++ b/source/_posts/2018-02-26-release-64.markdown @@ -82,6 +82,25 @@ Major new integration by [@snjoetw]: August locks and door bells! Lock and unloc - MQTT: Fix doing async inside sync context ([@OttoWinter]) - Fix DarSky humidity precision ([@PhilRW]) +## {% linkable_title Release 0.64.2 - March 1 %} + +- updated to bimmer_connected 0.4.1 ([@ChristianKuehnel] - [#12759]) ([bmw_connected_drive docs]) +- Revert optimized logbook SQL ([@amelchio] - [#12762]) ([logbook docs]) +- bump fedex version ([@happyleavesaoc] - [#12764]) ([sensor.fedex docs]) +- Silence harmless sonos data structure warnings ([@amelchio] - [#12767]) ([media_player.sonos docs]) +- Update samsungctl library to latest version ([@uchagani] - [#12769]) ([media_player.samsungtv docs]) +- Fixed missing optional keyerror data_bits ([@basschipper] - [#12789]) ([binary_sensor.rfxtrx docs]) +- Fixed Pollen.com bugs with ZIP codes and invalid API responses ([@bachya] - [#12790]) ([sensor.pollen docs]) +- Fix dead Sonos web interface with some music sources ([@amelchio] - [#12796]) ([media_player.sonos docs]) +- Unique IDs for Plex Clients ([@ryanm101] - [#12799]) ([media_player.plex docs]) + +## {% linkable_title Release 0.64.3 - March 2 %} + +- is_allowed_path: Also test folder #12788 #12807 ([@kellerza] - [#12810]) +- Fix sensibo default IDs to be according to schema ([@andrey-git] - [#12837]) ([climate.sensibo docs]) +- Cloud: handle unauth better ([@balloob] - [#12840]) ([cloud docs]) +- Handle Hue errors better ([@balloob] - [#12845]) ([hue docs]) + ## {% linkable_title If you need help... %} ...don't hesitate to use our very active [forums](https://community.home-assistant.io/) or join us for a little [chat](https://discord.gg/c5DvZ4e). The release notes have comments enabled but it's preferred if you use the former communication channels. Thanks. @@ -606,3 +625,37 @@ Experiencing issues introduced by this release? Please report them in our [issue [tahoma docs]: https://home-assistant.io/components/tahoma/ [vacuum.roomba docs]: https://home-assistant.io/components/vacuum.roomba/ [zha docs]: https://home-assistant.io/components/zha/ +[#12759]: https://github.com/home-assistant/home-assistant/pull/12759 +[#12762]: https://github.com/home-assistant/home-assistant/pull/12762 +[#12764]: https://github.com/home-assistant/home-assistant/pull/12764 +[#12767]: https://github.com/home-assistant/home-assistant/pull/12767 +[#12769]: https://github.com/home-assistant/home-assistant/pull/12769 +[#12789]: https://github.com/home-assistant/home-assistant/pull/12789 +[#12790]: https://github.com/home-assistant/home-assistant/pull/12790 +[#12796]: https://github.com/home-assistant/home-assistant/pull/12796 +[#12799]: https://github.com/home-assistant/home-assistant/pull/12799 +[@ChristianKuehnel]: https://github.com/ChristianKuehnel +[@amelchio]: https://github.com/amelchio +[@bachya]: https://github.com/bachya +[@basschipper]: https://github.com/basschipper +[@happyleavesaoc]: https://github.com/happyleavesaoc +[@ryanm101]: https://github.com/ryanm101 +[@uchagani]: https://github.com/uchagani +[binary_sensor.rfxtrx docs]: https://home-assistant.io/components/binary_sensor.rfxtrx/ +[bmw_connected_drive docs]: https://home-assistant.io/components/bmw_connected_drive/ +[logbook docs]: https://home-assistant.io/components/logbook/ +[media_player.plex docs]: https://home-assistant.io/components/media_player.plex/ +[media_player.samsungtv docs]: https://home-assistant.io/components/media_player.samsungtv/ +[media_player.sonos docs]: https://home-assistant.io/components/media_player.sonos/ +[sensor.fedex docs]: https://home-assistant.io/components/sensor.fedex/ +[sensor.pollen docs]: https://home-assistant.io/components/sensor.pollen/ +[#12810]: https://github.com/home-assistant/home-assistant/pull/12810 +[#12837]: https://github.com/home-assistant/home-assistant/pull/12837 +[#12840]: https://github.com/home-assistant/home-assistant/pull/12840 +[#12845]: https://github.com/home-assistant/home-assistant/pull/12845 +[@andrey-git]: https://github.com/andrey-git +[@balloob]: https://github.com/balloob +[@kellerza]: https://github.com/kellerza +[climate.sensibo docs]: https://home-assistant.io/components/climate.sensibo/ +[cloud docs]: https://home-assistant.io/components/cloud/ +[hue docs]: https://home-assistant.io/components/hue/ \ No newline at end of file diff --git a/source/cloud/google_assistant.markdown b/source/cloud/google_assistant.markdown index f76dd80d481..155b2356a73 100644 --- a/source/cloud/google_assistant.markdown +++ b/source/cloud/google_assistant.markdown @@ -16,7 +16,7 @@ To use this integration, you need to have: - The cloud component set up. [Learn more](/components/cloud/) - A Google Assistant enabled device like the Google Home - - Activated the Home Assistant Smart Home skill for Google Assistant + - Activated the [Home Assistant Smart Home skill for Google Assistant](https://assistant.google.com/services/a/uid/00000091fd5fb875) You can use `configuration.yaml` to configure the entities that are being shown to Google Assistant and how they are exposed. diff --git a/source/developers/architecture.markdown b/source/developers/architecture.markdown index c92361a4fc2..afe8a21ef9c 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -35,7 +35,7 @@ The Home Assistant core is responsible for Home Control. Home Assistant contains

    - + Overview of the Home Assistant core architecture

    diff --git a/source/developers/development_states.markdown b/source/developers/development_states.markdown index 369f87ea54b..6da9e5fbc97 100644 --- a/source/developers/development_states.markdown +++ b/source/developers/development_states.markdown @@ -137,4 +137,4 @@ def device_state_attributes(self): Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead.

    -To get your component included in the Home Assistant releases, follow the steps described in the [Submitting improvements](https://home-assistant.io/developers/#submitting-improvements) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request. +To get your component included in the Home Assistant releases, follow the steps described in the [Submit your work](https://home-assistant.io/developers/development_submitting/) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request. diff --git a/source/developers/development_testing.markdown b/source/developers/development_testing.markdown index b1bc38d0c29..9884120e0ba 100644 --- a/source/developers/development_testing.markdown +++ b/source/developers/development_testing.markdown @@ -54,10 +54,10 @@ $ pydocstyle homeassistant/core.py $ py.test tests/test_core.py ``` -You can also run linting tests against all changed files, as reported by `git diff upstream/dev --name-only`, using the `lint` script: +You can also run linting tests against all changed files, as reported by `git diff upstream/dev... --name-only`, using the `lint` script: ```bash -$ script/lint --changed +$ script/lint ``` ### {% linkable_title Preventing Linter Errors %} diff --git a/source/developers/documentation/create_page.markdown b/source/developers/documentation/create_page.markdown index f2bf29dcef1..cb0c4125198 100644 --- a/source/developers/documentation/create_page.markdown +++ b/source/developers/documentation/create_page.markdown @@ -122,3 +122,6 @@ The images which are displayed on the pages are stored in various directories ac | screenshots | source/images/components | Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). + +### {% linkable_title Linking From The Sidebar %} +If you are adding a new page that requires linking from the sidebar you need to edit the `docs_navigation.html` file in `home-assistant.github.io/source/_includes/asides/docs_navigation.html`. diff --git a/source/developers/frontend_creating_custom_ui.markdown b/source/developers/frontend_creating_custom_ui.markdown index 7a4b8eeb418..c9da0cf1e22 100644 --- a/source/developers/frontend_creating_custom_ui.markdown +++ b/source/developers/frontend_creating_custom_ui.markdown @@ -48,7 +48,7 @@ frontend: - + diff --git a/source/developers/internationalization/backend_localization.markdown b/source/developers/internationalization/backend_localization.markdown new file mode 100644 index 00000000000..6d395352b4f --- /dev/null +++ b/source/developers/internationalization/backend_localization.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Backend Localization" +description: "Translating platforms in Home Assistant" +date: 2018-03-01 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.64 +--- + +## {% linkable_title Translation Strings %} +Platform translation strings are stored as JSON in the [home-assistant](https://github.com/home-assistant/home-assistant) repository. These files must be located adjacent to the component/platform they belong to. They are named `strings..json`, unless the component being translated exists in its own directory, in which case the file is simply named `strings.json` in that directory. This file will contain the different strings that will be translatable. Currently only states are supported by the frontend. + +After the pull request with the strings file is merged into the `dev` branch, the strings will be automatically uploaded to Lokalise, where contributors can submit translations. The translated strings in Lokalise will be periodically pulled in to the home-assistant repository. + +## {% linkable_title States Localization %} +The first step when localizing platform states is to ensure that the states defined in the actual platform code are defined in `snake_case`. The states should not contain capital letters or spaces. Next, the strings file needs to be created. The states should exist under the `state` key, and map the backend state keys to their English translations. [The season sensor localization](https://github.com/home-assistant/home-assistant/pull/12453/commits/bb2f328ce10c3867990e34a88da64e2f8dc7a5c4) is a good example. diff --git a/source/developers/internationalization/custom_component_localization.markdown b/source/developers/internationalization/custom_component_localization.markdown new file mode 100644 index 00000000000..b7d12664d4d --- /dev/null +++ b/source/developers/internationalization/custom_component_localization.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "Custom Component Localization" +description: "Translating custom components in Home Assistant" +date: 2018-03-01 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.64 +--- + +## {% linkable_title Translation Strings %} +Unlike localized strings merged in the home-assistant repository, custom components cannot take advantage of Lokalise for user submitted translations. However, custom component authors can still include translation with their components. These will be read from the `.translations` directory, adjacent to the component source file. They are named `..json`, unless the custom component exists in its own directory, in which case the file is simply named `.json` in the `.translations` directory. + +These files follow the same formatting as [backend translation string files](/developers/internationalization/backend_localization/), but a copy will exist for each translated language. + +The language codes follow the [BCP47](https://tools.ietf.org/html/bcp47) format. The [frontend translation files](https://github.com/home-assistant/home-assistant-polymer/tree/master/translations) can also be referred to if you are unsure of the correct language code to use. + +The frontend will serve these files after Home Assistant is restarted. diff --git a/source/developers/internationalization/index.markdown b/source/developers/internationalization/index.markdown new file mode 100644 index 00000000000..109502fe458 --- /dev/null +++ b/source/developers/internationalization/index.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Internationalization" +description: "Home Assistant internationalization summary" +date: 2018-03-01 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.64 +--- + +The Home Assistant internationalization project includes preparing platforms and the frontend for localization, as well as the actual translation of localized strings. + +Some compmonents and platforms will have strings that need to be localized specifically for that platform. These strings are managed in the core [home-assistant](https://github.com/home-assistant/home-assistant) repository. The Home Assistant backend will serve strings to the clients based on the loaded components in the running instance. + +There are also localizable strings that exist only on the frontend. These strings are managed in the [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) repository. These strings are stored with the frontend and don’t depend on the backend configuration. + +Our strings are translated by the community using the online translation tool [Lokalise](https://lokalise.co/). diff --git a/source/developers/frontend_translation.markdown b/source/developers/internationalization/translation.markdown similarity index 79% rename from source/developers/frontend_translation.markdown rename to source/developers/internationalization/translation.markdown index 99a231941f0..334a68e6aa3 100644 --- a/source/developers/frontend_translation.markdown +++ b/source/developers/internationalization/translation.markdown @@ -1,19 +1,23 @@ --- layout: page -title: "Frontend Translation" -description: "How to translate the frontend for Home Assistant." +title: "Translation" +description: "How to translate Home Assistant." date: 2017-10-27 13:00 sidebar: true comments: false sharing: true footer: true ha_release: 0.57 +redirect_from: /developers/frontend_translation/ --- ## {% linkable_title How to start %} -[Join the translation team](https://lokalise.co/signup/3420425759f6d6d241f598.13594006/all/) and choose your language. Even if your language is completely translated, extra proofreading is a big help! Please feel free to review the existing translations, and vote for alternatives that might be more appropriate. +Translations for Home Assistant are managed through Lokalise, an online translation management tool. Our translations are split between two projects, a backend project for platform-specific translations, and a frontend project for UI translations. Click the links below to join both projects! Even if your language is completely translated, extra proofreading is a big help! Please feel free to review the existing translations, and vote for alternatives that might be more appropriate. -First time users may find it helpful to switch between multilanguage and single language view using the Multilanguage view button. For more information about the translation workflow, please see the [Lokalise translation workflow documents](https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators). +- [Join the frontend translation team](https://lokalise.co/signup/3420425759f6d6d241f598.13594006/all/) +- [Join the backend translation team](https://lokalise.co/signup/130246255a974bd3b5e8a1.51616605/all/) + +For more information about the translation workflow, please see the [Lokalise translation workflow documents](https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators).

    The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon. diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index abb8cf7e72c..429c6b4cb8a 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -17,7 +17,7 @@ Follow this guide if you want to easily get started with Home Assistant, or if y We will need a few things to get started with installing Home Assistant. Links below are linking to Amazon US. If you're not in the US, you should be able to find these items in web stores in your country. -- [Raspberry Pi 3 model B](http://a.co/gEfMqL4) + [Power Supply](http://a.co/cgKUgkt) (at least 2.5A) +- [Raspberry Pi 3 model B](http://a.co/gEfMqL4) + [Power Supply](https://www.raspberrypi.org/help/faqs/#powerReqs) (at least 2.5A) - [Micro SD Card](http://a.co/gslOydD). Get one that is Class 10 as they are more reliable. Size 32GB or bigger recommended. - SD Card reader. Part of most laptops, and also available as [standalone USB sticks](http://a.co/5FCyb0N) (the brand doesn't matter, just pick the cheapest) - Ethernet cable (optional, Hass.io can work with WiFi too) diff --git a/source/hassio/index.markdown b/source/hassio/index.markdown index fdddad8dd39..d53336e89ca 100644 --- a/source/hassio/index.markdown +++ b/source/hassio/index.markdown @@ -57,7 +57,7 @@ Hass.io upgrade process from the SSH command line ## {% linkable_title hassio command %} -On the SSH command line tyou can use the `hassio` command to retrieve logs, check the details of connected hardware, and more. +On the SSH command line you can use the `hassio` command to retrieve logs, check the details of connected hardware, and more. HomeAssistant: ``` $ hassio homeassistant logs diff --git a/source/hassio/installation.markdown b/source/hassio/installation.markdown index 1a3113dffce..2a26994493a 100644 --- a/source/hassio/installation.markdown +++ b/source/hassio/installation.markdown @@ -17,20 +17,19 @@ Hass.io images are available for all available Raspberry Pi and Intel NUC platfo - [Raspberry Pi 3][pi3] - [Intel NUC][nuc] -- Unpack the .bz2 File - Flash the downloaded image to an SD card using [Etcher]. - Optional - Setup the WiFi or static IP: On the SD-card, edit the `system-connections/resin-sample` file and follow the [ResinOS howto][resinos-network]. - Insert SD card to Raspberry Pi and turn it on. On first boot, it downloads the latest version of Home Assistant which takes ~20 minutes (slower/faster depending on the platform). -

    -Please remember to ensure you're using an [appropriate power supply](https://www.raspberrypi.org/help/faqs/#powerReqs) with your Pi. Mobile chargers may not be suitable since some are designed to only provide the full power with that manufacturer's handsets. -

    - - You will be able to reach your installation at [http://hassio.local:8123][local]. - Enable either the [Samba add-on][samba] or the [SSH add-on][ssh] to manage your configuration in `/config/` (From the UI choose **Hass.io** which is located in the sidebar). +

    +Please remember to ensure you're using an [appropriate power supply](https://www.raspberrypi.org/help/faqs/#powerReqs) with your Pi. Mobile chargers may not be suitable since some are designed to only provide the full power with that manufacturer's handsets. +

    +

    If you copy over your existing Home Assistant configuration, make sure to enable the Hass.io panel by adding either `discovery:` or `hassio:` to your configuration.

    @@ -51,10 +50,10 @@ A detailed guide about running Hass.io as a virtual machine is available in the [Etcher]: https://etcher.io/ [resinos-network]: https://docs.resin.io/deployment/network/2.0.0/ -[pi1]: https://github.com/home-assistant/hassio-build/releases/download/1.1/resinos-hassio-1.1-raspberrypi.img.bz2 -[pi2]: https://github.com/home-assistant/hassio-build/releases/download/1.1/resinos-hassio-1.1-raspberrypi2.img.bz2 -[pi3]: https://github.com/home-assistant/hassio-build/releases/download/1.1/resinos-hassio-1.1-raspberrypi3.img.bz2 -[nuc]: https://github.com/home-assistant/hassio-build/releases/download/1.1/resinos-hassio-1.1-intel-nuc.img.bz2 +[pi1]: https://github.com/home-assistant/hassio-build/releases/download/1.3/resinos-hassio-1.3-raspberrypi.img.bz2 +[pi2]: https://github.com/home-assistant/hassio-build/releases/download/1.3/resinos-hassio-1.3-raspberrypi2.img.bz2 +[pi3]: https://github.com/home-assistant/hassio-build/releases/download/1.3/resinos-hassio-1.3-raspberrypi3.img.bz2 +[nuc]: https://github.com/home-assistant/hassio-build/releases/download/1.3/resinos-hassio-1.3-intel-nuc.img.bz2 [linux]: https://github.com/home-assistant/hassio-build/tree/master/install#install-hassio [local]: http://hassio.local:8123 [samba]: /addons/samba/ diff --git a/source/hassio/installing_third_party_addons.markdown b/source/hassio/installing_third_party_addons.markdown index 1d320586fa2..828ed90e590 100644 --- a/source/hassio/installing_third_party_addons.markdown +++ b/source/hassio/installing_third_party_addons.markdown @@ -20,15 +20,15 @@ Home Assistant cannot guarantee the quality or security of third-party add-ons.

    - + From the Hass.io main panel open the add-on store.

    - -Add the URLs of repositories (one per line) and then press "Save". A new card for the repository will appear. + +Add the URL of the repository and then press "Add". A new card for the repository will appear.

    ### {% linkable_title Help: Repository is not showing up %} -If you have added a repository, but it's not showing up, it means that the repository contains invalid configuration. Go to the Hass.io panel -> Three dot menu -> Advanced Settings -> Supervisor card -> View logs and scroll to the bottom. It should tell you what went wrong. Report this information to the repository author. +If you have added a repository, but it's not showing up, it means that the repository contains invalid configuration. Go to the Hass.io panel and then the System tab to find the System log. It should tell you what went wrong. Report this information to the repository author. diff --git a/source/images/architecture/ha_architecture.svg b/source/images/architecture/ha_architecture.svg new file mode 100644 index 00000000000..dbe41b93bc9 --- /dev/null +++ b/source/images/architecture/ha_architecture.svg @@ -0,0 +1,856 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + Home AssistantCore Architecture + + Timer + + Event Bus + + StateMachine + listen for events/fire event + + ServiceRegistry + + + + Light + + + + Many more... + Device Tracker + Switch + Components + set state + + + + + + + + call event listeners + publishservice + callservice + + + call_serviceevents + + service_calledevents + time_changedevents + state_changedevents + + diff --git a/source/images/frontend/lokalise-multilanguage-view-button.png b/source/images/frontend/lokalise-multilanguage-view-button.png deleted file mode 100644 index 26872d47266..00000000000 Binary files a/source/images/frontend/lokalise-multilanguage-view-button.png and /dev/null differ diff --git a/source/images/hassio/screenshots/adding_repositories.png b/source/images/hassio/screenshots/adding_repositories.png new file mode 100644 index 00000000000..ef3edc88f5d Binary files /dev/null and b/source/images/hassio/screenshots/adding_repositories.png differ diff --git a/source/images/hassio/screenshots/main_panel_addon_store.png b/source/images/hassio/screenshots/main_panel_addon_store.png new file mode 100644 index 00000000000..deffb7db03a Binary files /dev/null and b/source/images/hassio/screenshots/main_panel_addon_store.png differ