Merge pull request #1312 from robbiet480/ios-component

WIP: iOS Component Documentation

_config.yml

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

source/_ecosystem/ios.markdown

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

source/_ecosystem/ios/devices_file.markdown

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

source/_ecosystem/ios/features.markdown

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

source/_ecosystem/ios/integration.markdown

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

source/_ecosystem/ios/location.markdown

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

source/_ecosystem/ios/notifications.markdown

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

source/_ecosystem/ios/notifications/actions.markdown

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

source/_ecosystem/ios/notifications/architecture.markdown

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

source/_ecosystem/ios/notifications/attachments.markdown

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

source/_ecosystem/ios/notifications/basic.markdown

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

source/_ecosystem/ios/notifications/content_extensions.markdown

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

source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown

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

source/_ecosystem/ios/notifications/requesting_location_updates.markdown

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

source/_ecosystem/ios/notifications/sounds.markdown

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

source/_ecosystem/ios/requirements.markdown

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

source/_includes/asides/ecosystem_ios_navigation.html

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

source/_includes/asides/ecosystem_navigation.html

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

source/_includes/custom/navigation.html

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

source/_includes/site/sidebar.html

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

source/ecosystem/index.markdown

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