Merge branch 'current' into next

_config.yml

@@ -141,10 +141,10 @@ social:
 current_major_version: 0
 current_minor_version: 57
 current_patch_version: 2
-date_released: 2017-11-05
+date_released: 2017-11-11
 
 # 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-0572--november-5"
+patch_version_notes: "#release-0573--november-11"
 # Minor release (Example #release-0431---april-25):

source/_addons/git_pull.markdown

@@ -44,4 +44,8 @@ Load and update configuration files for Home Assistant from a GIT repository.
   * **ed25519**
   * **rsa**
   
-  The protocol is typically known by the suffix of the private key --e.g., a key file named `id_rsa` will be a private key using "rsa" protocol.
+The protocol is typically known by the suffix of the private key --e.g., a key file named `id_rsa` will be a private key using "rsa" protocol.
+  
+<p class='note warning'>
+You should only use this add-on if you do not have an existing configuration or if your existing configuration is already in a git repository. If the script does not find the necessary git files in your configuration folder, it will delete anything that might be there. Please ensure that there is a `.git` folder before using this. You can verify this by listing the items in the configuration folder including hidden files. The command is `ls -a /config`.
+</p>

source/_components/device_tracker.huawei_router.markdown

@@ -13,7 +13,7 @@ ha_release: 0.51
 ---
 
 This component offers presence detection by looking at connected devices to a [Huawei router](http://m.huawei.com/enmobile/enterprise/products/network/access/pon-one/hw-371813.htm).
-Currently, this was only tested with the Huawei HG8247H (used by Vodafone Portugal).
+Currently, this was only tested with the Huawei HG8247H and HG8247Q Smart Router (used by Vodafone Portugal).
 
 To use a Huawei router in your installation, add the following to your `configuration.yaml` file:
 

source/_components/device_tracker.nmap_tracker.markdown

@@ -29,7 +29,7 @@ To use this device tracker in your installation, add the following to your `conf
 # Example configuration.yaml entry
 device_tracker:
   - platform: nmap_tracker
-    hosts: 192.168.1.1/24
+    hosts: 192.168.1.0/24
 ```
 
 Configuration variables:
@@ -47,7 +47,7 @@ A full example for the `nmap` tracker could look like the following sample:
 # One whole subnet, and skipping two specific IPs.
 device_tracker:
   - platform: nmap_tracker
-    hosts: 192.168.1.1/24
+    hosts: 192.168.1.0/24
     home_interval: 10
     exclude:
      - 192.168.1.12
@@ -60,7 +60,7 @@ device_tracker:
 device_tracker:
   - platform: nmap_tracker
     hosts:
-      - 192.168.1.1/24
+      - 192.168.1.0/24
       - 10.0.0.2
       - 10.0.0.15
 ```

source/_components/device_tracker.unifi.markdown

@@ -36,3 +36,9 @@ Configuration variables:
 - **detection_time** (*Optional*): The Unifi component will not return a device that has not been seen by the controller in the last 180 seconds. You can adjust this threshold with this variable and accepts seconds or `00:00:00` time formats.
 
 See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.
+
+<p class='note'>
+If you decide to install the Unifi Controller on the same system as your Home Assistant, be aware there may be overlap in ports if you have the MQTT component as well.
+
+[Related Issue](https://github.com/home-assistant/home-assistant/issues/10507)
+</p>

source/_components/frontend.markdown

@@ -101,8 +101,12 @@ automation:
 
 ### {% linkable_title Manual Theme Selection %}
 
-When themes are enabled in the `configuration.yaml` file, a new option will show up in the Configuration panel under `configuration.yaml` called "Set a theme." You can then choose any installed theme from the dropdown list and it will be applied immediately.
+When themes are enabled in the `configuration.yaml` file, a new option will show up in the Configuration panel under **General**  called "Set a theme." You can then choose any installed theme from the dropdown list and it will be applied immediately.
 
+<p class='img'>
+  <img src='/images/frontend/choose-theme.png' />
+  Set a theme
+</p>
 
 ## {% linkable_title Loading extra HTML %}
 
@@ -118,4 +122,13 @@ frontend:
     - /file2.html
 ```
 
-Those will be loaded via `<link rel='import' href='{{ extra_url }}' async>` on any page (states and panels)
+Those will be loaded via `<link rel='import' href='{{ extra_url }}' async>` on any page (states and panels).
+
+### {% linkable_title Manual Language Selection %}
+
+The browser language is automatically detected. To use a different language, go to **General** in the Configuration panel and select a one from "Choose a Language". It will be applied immediately.
+
+<p class='img'>
+  <img src='/images/frontend/choose-language.png' />
+  Choose a Language
+</p>

source/_components/sensor.speedtest.markdown

@@ -113,3 +113,5 @@ automation:
 
 - When running on Raspberry Pi, just note that the maximum speed is limited by its 100 Mbit/s LAN adapter.
 - Entries under `monitored_conditions` only control what entities are available under home-assistant, it does not disable the condition from running.
+- If ran frequently, this component has the capability of using a very large amount of data. Frequent updates should be avoided on bandwidth capped connections. 
+- While running, network usage is fully utilized. This may have a negative affect on other devices in use the network such as gaming consoles or streaming boxes. 

source/_components/timer.markdown

@@ -14,7 +14,7 @@ ha_release: 0.57
 
 The `timer` component aims to simplify automations based on (dynamic) durations.
 
-When a timer finishes or gets cancelled the corresponding events are fired. This allows you to diffferentiate if a timer has switched from `active` to `idle` because the given duration has elapsed or it has been cancelled. To control timers in your automations you can use the services mentioned below. When calling the `start` service on a timer that is already running, it resets the duration it will need to finish and restart the timer without triggering any events. This for example makes it easy to create timed lights that get triggered by motion.  
+When a timer finishes or gets cancelled the corresponding events are fired. This allows you to differentiate if a timer has switched from `active` to `idle` because the given duration has elapsed or it has been cancelled. To control timers in your automations you can use the services mentioned below. When calling the `start` service on a timer that is already running, it resets the duration it will need to finish and restart the timer without triggering any events. This for example makes it easy to create timed lights that get triggered by motion.  
 
 <p class='note warning'>
 With the current implementation timers don't persist over restarts. After a restart they will be idle again, together with their initial configuration.
@@ -92,3 +92,42 @@ Select <img src='/images/screenshots/developer-tool-services-icon.png' alt='serv
 }
 ```
 
+### {% linkable_title Configuration example %}
+
+```yaml
+# Example configuration.yaml entry
+
+# Set a timer called test to a duration of 30 seconds: 
+timer:
+  test:
+    duration: '00:00:30'
+```
+
+```yaml
+# Example automations.yaml entry
+- action:
+  - service: timer.start
+    entity_id: timer.test
+  alias: Timerswitch
+  id: 'Timerstart'
+
+# Timer is started when the switch pumprun is set to on. 
+  trigger: 
+    platform: state
+    entity_id: switch.pumprun
+    to: 'on'
+
+# When timer is stopped, the time run out, another message is sent
+- action:
+  - service: notify.nma
+    data:
+      message: "Timer stop"
+  alias: Timerstop
+  id: 'Timerstop'
+  trigger: 
+    platform: event
+    event_type: timer.finished
+    event_data: 
+      entity_id: timer.test
+```
+

source/_components/volvooncall.markdown

@@ -25,21 +25,21 @@ volvooncall:
   password: password
 ```
 
-Users registered with Volvo in North America or China will need to specify a service URL:
+Users registered with Volvo in North America or China will need to specify a region:
 
 ```yaml
 # North America 
 volvooncall:
   username: username
   password: password
-  service_url: 'https://vocapi-na.wirelesscar.net/customerapi/rest/v3.0/'
+  region: na
 ```
 ```yaml
 # China
 volvooncall:
   username: username
   password: password
-  service_url: 'https://vocapi-cn.wirelesscar.net/customerapi/rest/v3.0/'
+  region: cn
 ```
 
 A more advanced example for setting the vehicle name and selecting what resources to display:
@@ -61,7 +61,8 @@ Configuration variables:
 
 - **username** (*Required*): The username associated with your Volvo On Call account.
 - **password** (*Required*): The password for your given Volvo On Call account.
-- **service_url** (*Optional*): The service URL to use for Volvo On Call (defaults to https://vocapi.wirelesscar.net/customerapi/rest/v3.0/).
+- **region** (*Optional*): The region where the Volvo is registered. Needs to be set for users in North America or China.
+- **service_url** (*Optional*): The service URL to use for Volvo On Call. Normally not neccessary to specify.
 - **name** (*Optional*): Make it possible to provide a name for the vehicles.
 - **resources** (*Optional*): A list of resources to display (defaults to all available).
 

source/_components/xiaomi_aqara.markdown

@@ -9,7 +9,7 @@ sharing: true
 footer: true
 logo: xiaomi.png
 ha_category: Hub
-ha_release: "0.50"
+ha_release: "0.57"
 ha_iot_class: "Local Push"
 redirect_from: /components/xiaomi/
 ---
@@ -49,7 +49,7 @@ The `xiaomi_aqara` component allows you to integrate [Xiaomi](http://www.mi.com/
 
 ## {% linkable_title Setup %}
 
-Follow the setup process using your phone and Mi-Home app. From here you will be able to retrieve the key from within the app following [this tutorial](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832).
+Follow the setup process using your phone and Mi-Home app. From here you will be able to retrieve the key (password) from within the app following [this tutorial](https://www.domoticz.com/wiki/Xiaomi_Gateway_(Aqara)#Adding_the_Xiaomi_Gateway_to_Domoticz).
 
 To enable {{ page.title }} in your installation, add the following to your `configuration.yaml` file:
 
@@ -236,7 +236,7 @@ If you run into trouble initializing the gateway with your app, try another smar
 ```
 
 That means that Home Assistant is not getting any response from your Xiaomi gateway. Might be a local network problem or your firewall.
-- Make sure you have [enabled LAN access](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832).
+- Make sure you have [enabled LAN access](https://www.domoticz.com/wiki/Xiaomi_Gateway_(Aqara)#Adding_the_Xiaomi_Gateway_to_Domoticz).
 - Turn off the firewall on the system where Home Assistant is running.
 - Ensure your router supports multicast as this is a requirement of the Xiaomi GW
 - Try to leave the MAC address `mac:` blank.

source/_docs/installation/docker.markdown

@@ -54,9 +54,10 @@ The steps would be:
 * Set "Enable auto-restart" if you like
 * Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount point" has to be "/config", so that Home Assistant will use it for the configs and logs.
 * Within "Network" select "Use same network as Docker Host"
+* To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
 * Confirm the "Advanced Settings"
 * Click on "Next" and then "Apply"
-* Your Home Assistant within Docker should now run
+* Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`)
 
 Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following:
 * Go to the Docker-app and move to "Image"-section
@@ -64,9 +65,13 @@ Remark: to update your Home Assistant on your Docker within Synology NAS, you ju
 * wait until the system-message/-notification comes up, that the download is finished (there is no progress bar)
 * Move to "Container"-section
 * Stop your container if it's running
-* Right-click on it and select "Action"->"Clear". You won't loose any data, as all files are stored in your config-directory
+* Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your config-directory
 * Start the container again - it will then boot up with the new Home Assistant image
 
+Remark: to restart your Home Assistant within Synology NAS, you just have to do the following:
+* Go to the Docker-app and move to "Container"-section
+* Right-click on it and select "Action"->"Restart".
+
 ### {% linkable_title Restart %}
 
 This will launch Home Assistant and serve the web interface from port 8123 on your Docker host.
@@ -74,4 +79,4 @@ This will launch Home Assistant and serve the web interface from port 8123 on yo
 If you change the configuration you have to restart the server. To do that you have 2 options.
 
  1. You can go to the <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> service developer tools, select the service `homeassistant/restart` and click "Call Service".
- 2. Or you can restart it from an terminal by running `docker restart home-assistant`
+ 2. Or you can restart it from a terminal by running `docker restart homeassistant`

source/_docs/z-wave/adding.markdown

@@ -2,7 +2,7 @@
 layout: page
 title: "Z-Wave Devices - Adding and Removing"
 description: "How to add and remove Z-Wave devices."
-date: 2016-02-27 19:59
+date: 2017-11-08 19:06
 sidebar: true
 comments: false
 sharing: true
@@ -11,17 +11,29 @@ footer: true
 
 ## {% linkable_title Adding Non-Secure Devices %}
 
-To add (include) a non-secure Z-Wave [device](/docs/z-wave/devices/) to your system, go to the [Z-Wave control panel](/docs/z-wave/control-panel/) in the Home Assistant frontend and click the **Add Node** button in the *Z-Wave Network Management* card. This will place the controller in inclusion mode, after which you should activate your device to be included by following the instructions provided with the device. Don't use this for secure devices, since this is likely to limit the features the device supports.
+To add (include) a non-secure Z-Wave [device](/docs/z-wave/devices/) to your system:
+
+1. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/) in the Home Assistant frontend
+2. Click the **Add Node** button in the *Z-Wave Network Management* card - this will place the controller in inclusion mode
+3. Activate your device to be included by following the instructions provided with the device
+
+Don't use this for [secure devices](https://home-assistant.io/docs/z-wave/adding/#adding-secure-devices), since this is likely to limit the features the device supports.
 
 <p class='note warning'>
-Don't use the OpenZWave control panel (OZWCP), or the physical button on a controller, to add or remove devices. Many devices will only send the information about their capabilities at the time you include them. If you use the OpenZWave control panel, or the button on a device, then Home Assistant won't have that information. Using the physical button on a controller will also result in a non-security inclusion being performed, which may limit the features the device supports.
+Don't use the OpenZWave control panel (OZWCP), **or the physical button on a controller**, to add or remove devices. Many devices will only send the information about their capabilities at the time you include them. If you use the OpenZWave control panel, or the button on a device, then Home Assistant won't have that information. Using the physical button on a controller will also result in a non-security inclusion being performed, which may limit the features the device supports.
 </p>
 
 When you add a device, it may initially appear without a specific entity ID (eg `zwave.__`) and without other identifying information. Running a *Heal* should help speed this process up, and you'll need to run a *Heal* anyway so that all the devices in your Z-Wave network learn about the new device. You *might* need to restart Home Assistant (not reboot the system) to have the entity ID fully visible.
 
 ## {% linkable_title Adding Secure Devices %}
 
-Security Z-Wave devices require a network key before being added to the network using the **Add Secure Node** button in the Z-Wave Network Management card. You must set the *network_key* configuration variable to use a network key before adding these devices. Some devices only expose their full capabilities when included this way, you should always read the manual for your device to find out the recommended inclusion method.
+Security Z-Wave devices require a network key - you must set the *network_key* configuration variable to use a network key before adding these devices. Some devices only expose their full capabilities when included this way, you should always read the manual for your device to find out the recommended inclusion method. To add (include) a secure Z-Wave device:
+
+1. Go to the [Z-Wave control panel](/docs/z-wave/control-panel/) in the Home Assistant frontend
+2. Click the **Add Node Secure** button in the *Z-Wave Network Management* card - this will place the controller in inclusion mode
+3. Activate your device to be included by following the instructions provided with the device
+
+### {% linkable_title Network Key %}
 
 An easy script to generate a random key:
 ```bash
@@ -39,5 +51,8 @@ Ensure you keep a backup of this key. If you have to rebuild your system and don
 
 ## {% linkable_title Removing Devices %}
 
-To remove (exclude) a Z-Wave device from your system, go to the Z-Wave control panel in the Home Assistant frontend and click the **Remove Node** button in the *Z-Wave Network Management* card. This will place the controller in exclusion mode, after which you should activate your device to be excluded by following the instructions provided with the device.
+To remove (exclude) a Z-Wave device from your system:
 
+1. Go to the Z-Wave control panel in the Home Assistant frontend
+2. Click the **Remove Node** button in the *Z-Wave Network Management* card - this will place the controller in exclusion mode
+3. Activate your device to be excluded by following the instructions provided with the device

source/_docs/z-wave/control-panel.markdown

@@ -36,7 +36,8 @@ Here is where you [include and exclude](/docs/z-wave/adding/) Z-Wave devices fro
 * **Remove Failed Node** will remove a failed node from the network. The node needs to be on the controller's Failed Node List (marked as `is_failed: true`), otherwise this command will fail.
 * **Replace Failed Node** will replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail.
 * **Print Node** prints all state of Z-Wave node to the console log
-* **Rename Node** sets a node's name
+
+* **Rename Node** sets a node's name - this won't happen immediately, and requires you to restart Home Assistant (not reboot) to set the new name
 
 * **Heal Node** starts healing of the node.(Update neighbour list and update return routes)
 

source/_docs/z-wave/device-specific.markdown

@@ -156,3 +156,54 @@ Triple tap on|1|4
 Triple tap off|2|4
 Tap and hold on|1|2
 Tap and hold off|2|2
+
+### {% linkable_title Fibaro Button FGPB-101-6 v3.2 %}
+
+<!-- from https://hastebin.com/esodiweduq.cs -->
+
+For the Button, you may need to update the `COMMAND_CLASS_CENTRAL_SCENE` for each node in your `zwcfg` file with the following:
+
+```xml
+      <CommandClass id="91" name="COMMAND_CLASS_CENTRAL_SCENE" version="1" request_flags="4" innif="true" scenecount="0">
+        <Instance index="1" />
+          <Value type="int" genre="system" instance="1" index="0" label="Scene Count" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+          <Value type="int" genre="system" instance="1" index="1" label="Scene Count" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="3" />
+      </CommandClass>
+```
+
+Below is a table of the action/scenes for the Button (as a reference for other similar devices):
+
+**Action**|**scene\_id**|**scene\_data**
+:-----:|:-----:|:-----:
+Single tap on|1|0
+Double tap on|1|3
+Triple tap on|1|4
+
+Tap and hold wakes up the Button.
+
+### {% linkable_title Aeotec Wallmote %}
+
+<!-- from https://hastebin.com/esodiweduq.cs -->
+
+For the Aeotec Wallmote, you may need to update the `COMMAND_CLASS_CENTRAL_SCENE` for each node in your `zwcfg` file with the following:
+
+```xml
+      <CommandClass id="91" name="COMMAND_CLASS_CENTRAL_SCENE" version="1" request_flags="5" innif="true" scenecount="0">
+        <Instance index="1" />
+          <Value type="int" genre="system" instance="1" index="0" label="Scene Count" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+          <Value type="int" genre="system" instance="1" index="1" label="Button One" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+          <Value type="int" genre="system" instance="1" index="2" label="Button Two" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+          <Value type="int" genre="system" instance="1" index="3" label="Button Three" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+          <Value type="int" genre="system" instance="1" index="4" label="Button Four" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+          <Value type="int" genre="system" instance="1" index="5" label="Other" units="" read_only="true" write_only="false" verify_changes="false" poll_intensity="0" min="-2147483648" max="2147483647" value="0" />
+      </CommandClass>
+```
+
+Below is a table of the action/scenes for the Wallmote (as a reference for other similar devices):
+
+**Action**|**scene\_id**|**scene\_data**
+:-----:|:-----:|:-----:
+Button one single tap|1|TBC
+Button two single tap|2|TBC
+Button three single tap|3|TBC
+Button four single tap|4|TBC

source/_docs/z-wave/installation.markdown

@@ -25,7 +25,7 @@ $ sudo /Applications/Python\ x.x/Install\ Certificates.command
 ```
 
 <p class='note'>
-The installation of python-openzwave can take half an hour or more on a Raspbery Pi.
+The installation of python-openzwave happens when you first enable the Z-Wave component, and can take half an hour or more on a Raspbery Pi.
 </p>
 
 ## {% linkable_title Configuration %}
@@ -183,7 +183,9 @@ Ensure you keep a backup of this key. If you have to rebuild your system and don
 
 ## {% linkable_title First Run %}
 
-Upon first run, the `zwave` component will take time to initialize entities and entities may appear with incomplete names. Running a network heal may speed up this process.
+The (compilation and) installation of python-openzwave happens when you first enable the Z-Wave component, and can take half an hour or more on a Raspbery Pi. When you upgrade Home Assistant and python-openzwave is also upgraded, this will also result in a delay while the new version is compiled and installed.
+
+The first run after adding a device is when the `zwave` component will take time to initialize the entities, some entities may appear with incomplete names. Running a network heal may speed up this process.
 
 ## {% linkable_title Troubleshooting %}
 

source/_posts/2017-11-04-release-57.markdown

@@ -92,6 +92,11 @@ Okay, one more highlight before we'll let you check out the changelog. Contribut
 - Update frontend with fixes for setting temperature on climate card ([@balloob])
 - Fix setting max brightness for TRADFRI ([@ggravlingen] - [#10359])
 
+## {% linkable_title release 0.57.3 - november 11 %}
+
+- Tellstick Duo acync callback fix ([@stefan-jonasson] - [#10384]) ([tellstick docs])
+- Fixed update() method and removed `ding` feature from stickupcams/floodlight ([@tchellomello] - [#10428]) ([binary_sensor.ring docs]) ([camera.ring docs]) ([sensor.ring 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.
@@ -643,4 +648,12 @@ Experiencing issues introduced by this release? Please report them in our [issue
 [wink docs]: https://home-assistant.io/components/wink/
 [xiaomi_aqara docs]: https://home-assistant.io/components/xiaomi_aqara/
 [ikea email]: https://twitter.com/home_assistant/status/925373865802502144
-[wink-auth]: https://home-assistant.io/components/wink/#authenticate-using-developerwinkcomhttpsdeveloperwinkcom
+[wink-auth]: https://home-assistant.io/components/wink/#authenticate-using-developerwinkcomhttpsdeveloperwinkcom
+[#10384]: https://github.com/home-assistant/home-assistant/pull/10384
+[#10428]: https://github.com/home-assistant/home-assistant/pull/10428
+[@stefan-jonasson]: https://github.com/stefan-jonasson
+[@tchellomello]: https://github.com/tchellomello
+[binary_sensor.ring docs]: https://home-assistant.io/components/binary_sensor.ring/
+[camera.ring docs]: https://home-assistant.io/components/camera.ring/
+[sensor.ring docs]: https://home-assistant.io/components/sensor.ring/
+[tellstick docs]: https://home-assistant.io/components/tellstick/

source/_posts/2017-11-10-ttn-with-mqtt.markdown

@@ -0,0 +1,198 @@
+---
+layout: post
+title: "Home Assistant and The Things Network (TTN)"
+description: "How to use transfer MQTT messages from The Things Network (TTN) to a local broker."
+date: 2017-11-10 14:00:00 +0200
+date_formatted: "November 10, 2017"
+author: Fabian Affolter
+author_twitter: fabaff
+comments: true
+categories: How-To
+og_image: /images/blog/2017-11-mqtt-ttn/social-ha-ttn.png
+---
+
+The Home Assistant integration for [The Things Network (TTN)](https://www.thethingsnetwork.org/) uses their [Storage](https://www.thethingsnetwork.org/docs/applications/storage/) feature to get the sensor data. The easiest way to observe TTN sensors would be [MQTT](https://www.thethingsnetwork.org/docs/applications/mqtt/) as it doesn't requires any additional configuration.
+
+At the moment Home Assistant only supports one [MQTT broker](/docs/mqtt/). This means that you can't subscribe to topics which are located on different brokers.
+
+<!--more-->
+
+## {% linkable_title Subscribe to the TTN Broker %}
+
+To check what your devices are sending, subscribe to the topic `+/devices/+/up` with a command-line tool like `mosquitto_sub`. The `<Region>` is the postfix of the **Handler** entry in your **Application overview**. `<AppID>` is the **Application ID** and `<AppKey>` is your access key. 
+
+```bash
+$ mosquitto_sub -v -h <Region>.thethings.network -t '+/devices/+/up' -u '<AppID>' -P '<AppKey>'
+{
+	"app_id": "ha-demo",
+	"dev_id": "device01",
+	"hardware_serial": "AJDJENDNHRBFBBT",
+	"port": 1,
+    [...]
+```
+
+The payload contains details about the device itself and the sensor data. The sensor data is stored in `payload_fields`. Depending on the device configuration it may contain a single value or multiple values. 
+
+## {% linkable_title The relay %}
+
+To be able to work locally with the MQTT data that is received from the devices connected to TTN, we need to transfer it to the local broker. With this simple script below all messages from a given device are re-published on your local MQTT broker after they are received. Modify the script with your details as outlined in the previous section.
+
+```python
+"""Relay MQTT messages from The Things Network to a local MQTT broker."""
+import paho.mqtt.client as mqtt
+import paho.mqtt.publish as publish
+
+DEVICE_NAME = '<DeviceID>'
+
+TTN_BROKER = '<Region>.thethings.network'
+TTN_USERNAME = '<AppID>'
+TTN_PASSWORD = '<AppKey>'
+TTN_TOPIC = '+/devices/{}/up'.format(DEVICE_NAME)
+
+LOCAL_BROKER = '192.168.0.2'
+LOCAL_TOPIC = 'home/ttn/garden_temp'
+
+
+def on_connect(client, userdata, flags, rc):
+    """Subscribe to topic after connection to broker is made."""
+    print("Connected with result code", str(rc))
+    client.subscribe(TTN_TOPIC)
+
+
+def on_message(client, userdata, msg):
+    """Relay message to a different broker."""
+    publish.single(
+        LOCAL_TOPIC, payload=msg.payload, qos=0, retain=False,
+        hostname=LOCAL_BROKER, port=1883, client_id='ttn-local',
+        keepalive=60, will=None, auth=None, tls=None, protocol=mqtt.MQTTv311)
+
+
+client = mqtt.Client()
+client.username_pw_set(TTN_USERNAME, password=TTN_PASSWORD)
+client.on_connect = on_connect
+client.on_message = on_message
+client.connect(TTN_BROKER, 1883, 60)
+
+client.loop_forever()
+```
+
+Save it and run it. As soon as a MQTT message is received from your device you should see it on your local broker (here 192.168.0.2) if you subscribe to `#` or the topic given in the script above `home/ttn/garden_temp`.
+
+```bash
+$ mosquitto_sub -h 192.168.0.2 -t "#" -d
+```
+
+## {% linkable_title The sensor %}
+
+All we would need now, is a [`mqtt` sensor](/components/sensor.mqtt/) with a `value_template`. With a sophisticated custom sensor it would be possible to displaying a little more than just the state. The device is only sending the temperature `{"temperature": 7.5}` but there are other details available which the sensor should show.
+
+```python
+"""Support for The Things Network MQTT sensors."""
+import asyncio
+from datetime import timedelta
+import json
+import logging
+
+import voluptuous as vol
+
+import homeassistant.components.mqtt as mqtt
+from homeassistant.components.mqtt import CONF_STATE_TOPIC
+from homeassistant.const import CONF_NAME, CONF_UNIT_OF_MEASUREMENT
+from homeassistant.core import callback
+import homeassistant.helpers.config_validation as cv
+from homeassistant.helpers.entity import Entity
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_NAME = 'MQTT TTN Sensor'
+DEFAULT_FORCE_UPDATE = False
+DEPENDENCIES = ['mqtt']
+
+PLATFORM_SCHEMA = mqtt.MQTT_RO_PLATFORM_SCHEMA.extend({
+    vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,
+    vol.Optional(CONF_UNIT_OF_MEASUREMENT): cv.string,
+
+})
+
+
+@asyncio.coroutine
+def async_setup_platform(hass, config, async_add_devices, discovery_info=None):
+    """Set up the TTN MQTT Sensor."""
+    async_add_devices([MqttTtnSensor(
+        config.get(CONF_NAME), config.get(CONF_STATE_TOPIC),
+        config.get(CONF_UNIT_OF_MEASUREMENT))
+    ])
+
+
+class MqttTtnSensor(Entity):
+    """Representation of a sensor."""
+
+    def __init__(self, name, state_topic, unit_of_measurement):
+        """Initialize the sensor."""
+        self._state = None
+        self._name = name
+        self._unit_of_measurement = unit_of_measurement
+        self._attributes = {}
+        self._state_topic = state_topic
+
+    def async_added_to_hass(self):
+        """Subscribe to MQTT events."""
+        @callback
+        def message_received(topic, payload, qos):
+            """Handle new MQTT messages."""
+
+            try:
+                data = json.loads(payload)
+            except json.JSONDecodeError:
+                _LOGGER.error("Invalid JSON data received: %s", data)
+
+            self._state = data['payload_fields'][next(
+                iter(data['payload_fields']))]
+            self._attributes = data
+            del self._attributes['payload_fields']
+            del self._attributes['metadata']
+            self.async_schedule_update_ha_state()
+
+        return mqtt.async_subscribe(
+            self.hass, self._state_topic, message_received, 0)
+
+    @property
+    def should_poll(self):
+        """No polling needed."""
+        return False
+
+    @property
+    def name(self):
+        """Return the name of the sensor."""
+        return self._name
+
+    @property
+    def unit_of_measurement(self):
+        """Return the unit this state is expressed in."""
+        return self._unit_of_measurement
+
+    @property
+    def state_attributes(self):
+        """Return the attributes of the entity."""
+        return self._attributes
+
+    @property
+    def state(self):
+        """Return the state of the entity."""
+        return self._state
+```
+
+Store it in `<config_dir>/custom_components/sensor/mqtt_ttn.py` and it will handle the messages.
+
+## {% linkable_title The configuration %}
+
+Now create the [`mqtt_ttn` sensor](/components/sensor.mqtt/) entry for your device.
+
+```
+sensor:
+  - platform: mqtt_ttn
+    name: TTN Sensor
+    state_topic: "home/ttn/garden_temp"
+```
+
+This solution is not production-ready, scalable or stable but it could fill the gape till Home Assistant is able to connect to multiple MQTT brokers. If you have multiple devices relay all messages to your local broker and add an configuration variable to `mqtt_ttn` sensor which allows you to select the device.

source/developers/documentation/create_page.markdown

@@ -86,7 +86,7 @@ required: inclusive       #=> Inclusive
 required: exclusive       #=> Exclusive
 required: any string here #=> Any string here
 ```
-- **`type:`**: The type of the variable. Allowed entries: `string`, `int` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example).
+- **`type:`**: The type of the variable. Allowed entries: `string`, `int`, `time`, `template` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example).
 - **`default:`**: The default value for the variable.
 
 ### {% linkable_title Embedding Code %}

source/developers/frontend_creating_custom_ui.markdown

@@ -40,7 +40,7 @@ frontend:
     - /local/custom_ui/state-card-my-custom-light.html
 ```
 
-`www\custom_ui\state-card-my-custom-light.html`:
+`www/custom_ui/state-card-my-custom-light.html`:
 
 ```javascript
 <dom-module id='state-card-my-custom-light'>

source/developers/frontend_translation.markdown

@@ -23,6 +23,7 @@ The translation of the Home Assistant frontend is still a work in progress. More
 1. Only native speakers should submit translations.
 2. Stick to [Material Design guidelines](https://material.io/guidelines/style/writing.html).
 3. Don't translate or change proper nouns like `Home Assistant`, `Hass.io` or `Hue`.
+4. For a region specific translation, keys that will be the same as the base translation should be filled with `[VOID]`. These will be replaced during our translation build process.
 
 ## {% linkable_title Adding a new language %}
 If your language is not listed you can request it at [GitHub](https://github.com/home-assistant/home-assistant-polymer/issues/new). Please provide both the English name and the native name for your language. For example:

source/hassio/zwave.markdown

@@ -16,7 +16,9 @@ zwave:
   usb_path: /dev/ttyACM0
 ```
 
-If you need GPIO on Raspberry Pi 3 for your Z-Wave module, add the following line into `config.txt`:
+### RAZBERRY BOARD
+
+If you need GPIO on Raspberry Pi 3 for your Z-Wave module, add the following line into `config.txt` (you have to access that on the SD card directly; simply plug it into your PC and edit it there):
 
 ```
 dtoverlay=pi3-miniuart-bt
@@ -28,7 +30,12 @@ For some devices the `/dev/ttyAMA0` device is not detected by udev and is theref
 $ curl -d '{"devices": ["ttyAMA0"]}' http://hassio/homeassistant/options
 ```
 
-After that, you need to change `usb_path` to `/dev/ttyAMA0`.
+After that, you need to change `usb_path` to `/dev/ttyAMA0` in your `configuration.yaml`.
+
+```yaml
+zwave:
+  usb_path: /dev/ttyAMA0
+```
 
 ### HUSBZB-1: