diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index fbc3baa2017..70dbdb2c322 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -113,6 +113,7 @@ article.post, article.page, article.listing { img, table { border-radius: 3px; box-shadow: rgba(0,0,0,0.06) 0 0 10px; + vertical-align: middle; } img.no-shadow { diff --git a/source/_components/alarm_control_panel.mqtt.markdown b/source/_components/alarm_control_panel.mqtt.markdown index 36c9230b87e..95967a021ed 100644 --- a/source/_components/alarm_control_panel.mqtt.markdown +++ b/source/_components/alarm_control_panel.mqtt.markdown @@ -9,6 +9,7 @@ sharing: true footer: true logo: mqtt.png ha_category: Alarm +ha_release: 0.7.4 --- The `mqtt` alarm panel platform enables the possibility to control MQTT capable alarm panels. The Alarm icon will change state after receiving a new state from `state_topic`. If these messages are published with *RETAIN* flag, the MQTT alarm panel will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state will be `unknown`. diff --git a/source/_components/alarm_control_panel.nx584.markdown b/source/_components/alarm_control_panel.nx584.markdown index 12a07029947..64bb0963997 100644 --- a/source/_components/alarm_control_panel.nx584.markdown +++ b/source/_components/alarm_control_panel.nx584.markdown @@ -9,6 +9,7 @@ sharing: true footer: true logo: networx.png ha_category: Alarm +ha_release: 0.13 --- The `nx584` platform provides integration with GE, Caddx, Interlogix (and other brands) alarm panels that support the NX584 interface module (or have it built in). Supported panels include NX4/6/8/8E. Actual integration is done through [pynx584](http://github.com/kk7ds/pynx584) which is required for this to work. diff --git a/source/_components/alexa.markdown b/source/_components/alexa.markdown index fd378d865f8..ee1fbecbcbb 100644 --- a/source/_components/alexa.markdown +++ b/source/_components/alexa.markdown @@ -45,7 +45,7 @@ Please note that you can use Haaska and the built-in Alexa component side-by-sid ### {% linkable_title I want to build custom commands to use with Echo %} -The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. There are no supported sentences out of the box as of now, you will have to define them all yourself. +The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. Home Assistant offers no built-in sentences but offers a framework for you to define your own.
@@ -113,7 +113,10 @@ Out of the box, the component will do nothing. You have to teach it about all in You can use [templates] for the values of `speech/text`, `card/title` and `card/content`. +Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent. + [templates]: /topics/templating/ +[Home Assistant Script Syntax]: /getting-started/scripts/ Configuring the Alexa component for the above intents would look like this: @@ -137,8 +140,8 @@ alexa: LocateIntent: action: service: notify.notify - data: - message: Your location has been queried via Alexa. + data_template: + message: The location of {{ User }} has been queried via Alexa. speech: type: plaintext text: > diff --git a/source/_components/binary_sensor.octoprint.markdown b/source/_components/binary_sensor.octoprint.markdown new file mode 100644 index 00000000000..7a05254c5e4 --- /dev/null +++ b/source/_components/binary_sensor.octoprint.markdown @@ -0,0 +1,34 @@ +--- +layout: page +title: "OctoPrint Binary Sensor" +description: "Instructions how to integrate OctoPrint binary sensors within Home Assistant." +date: 2016-05-05 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: octoprint.png +ha_category: Binary Sensor +ha_release: 0.19 +--- + + +The `OctoPrint` binary sensor platform let you monitor if your 3D printer is printing or if there was a printing error. + +To set it up, add the following information to your `configuration.yaml` file: + +```yaml +binary_sensor: + platform: octoprint + monitored_conditions: + - Printing + - Printing Error +``` + +Configuration variables: + +- **monitored_conditions** array (*Required*): States to monitor. + - Printing + - Printing Error + +

You must have the [OctoPrint component](/components/octoprint/) configured to use this sensor.

diff --git a/source/_components/dweet.markdown b/source/_components/dweet.markdown new file mode 100644 index 00000000000..9b57782db83 --- /dev/null +++ b/source/_components/dweet.markdown @@ -0,0 +1,44 @@ +--- +layout: page +title: "Dweet.io" +description: "Record events in InfluxDB." +date: 2016-05-07 07:08 +sidebar: true +comments: false +sharing: true +footer: true +logo: dweet.png +ha_category: "History" +featured: true +ha_release: 0.19 +--- + +The `dweet` component makes it possible to transfer details collected with Home Assistant to [Dweet.io](http://dweet.io/) and visualize them with [freeboard.io](https://freeboard.io). Keep in mind that your information will be public! + +

+ +

+ + +

+ The publishing interval is limited to 1 second. This means that it's possible to missing fast changes. +

+ +To use the `deweet` component in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +dweet: + name: HAExport + whitelist: + - input_slider.brightness + - input_boolean.notify_home + - sensor.weather_temperature + - sensor.cpu +``` + +Configuration variables: + +- **name** (*Required*): Choose must choose an unique name. +- **whitelist** (*Required*): List of entity IDs you want to publish. + diff --git a/source/_components/hvac.markdown b/source/_components/hvac.markdown new file mode 100644 index 00000000000..48bda1c43f1 --- /dev/null +++ b/source/_components/hvac.markdown @@ -0,0 +1,21 @@ +--- +layout: page +title: "HVAC" +description: "Instructions on how to integrate HVAC devices status with Home Assistant." +date: 2016-05-07 09:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.19 +--- + +The `hvac` component is built for the controlling and monitoring of HVAC (heating, ventilating, and air conditioning) devices. + +To enable this component, add the following lines to your `configuration.yaml`: + +```yaml +# Example configuration.yaml entry +hvac: +``` + diff --git a/source/_components/hvac.zwave.markdown b/source/_components/hvac.zwave.markdown new file mode 100644 index 00000000000..373256a6cc0 --- /dev/null +++ b/source/_components/hvac.zwave.markdown @@ -0,0 +1,15 @@ +--- +layout: page +title: "Z-Wave HVAC" +description: "Instructions on how to integrate HVAC Z-Wave devices status with Home Assistant." +date: 2016-05-07 09:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: z-wave.png +ha_category: HVAC +ha_release: 0.19 +--- + +To get your Z-Wave `hvac` devices working with Home Assistant, follow the instructions for the general [Z-Wave component](/components/zwave/) and the [HVAC component](/components/hvac/). diff --git a/source/_components/light.rfxtrx.markdown b/source/_components/light.rfxtrx.markdown index 7e21f273952..95dd54f172a 100644 --- a/source/_components/light.rfxtrx.markdown +++ b/source/_components/light.rfxtrx.markdown @@ -13,19 +13,42 @@ ha_release: 0.7.5 The `rfxtrx` platform support lights that communicate in the frequency range of 433.92 MHz. -To enable RFXtrx lights in your installation, add the following to your `configuration.yaml` file: +First you have to set up your [rfxtrx hub.](/components/rfxtrx/) +The easiest way to find your lights is to add this to your `configuration.yaml`: +```yaml +light: + platform: rfxtrx + automatic_add: True +``` + +Launch your homeassistant and go the website. +Push your remote and your device should be added: + +

+ +

+ +Here the name is 0b11000102ef9f210010f70 and you can verify that it works from the frontend. +Then you should update your configuration to: +```yaml +light: + platform: rfxtrx + devices: + 0b11000102ef9f210010f70: + name: device_name +``` + +Example configuration: ```yaml # Example configuration.yaml entry light: - platform: rfxtrx - signal_repetitions: 3 - devices: - living_room: - name: Living Room - packetid: XXXXX - fire_event: True - automatic_add: True + platform: rfxtrx + devices: + 0b11000f10e9e5660b010f70: + name: Light1 + 0b1100100f29e5660c010f70: + name: Light_TV ``` Configuration variables: diff --git a/source/_components/locks.zwave.markdown b/source/_components/locks.zwave.markdown new file mode 100644 index 00000000000..f5a1802fb6e --- /dev/null +++ b/source/_components/locks.zwave.markdown @@ -0,0 +1,15 @@ +--- +layout: page +title: "Z-Wave Lock" +description: "Instructions how to setup the Z-Wave Locks within Home Assistant." +date: 2016-05-07 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: z-wave.png +ha_category: Locks +ha_release: 0.19 +--- + +To get your Z-Wave locks working with Home Assistant, follow the instructions for the general [Z-Wave component](/components/zwave/). diff --git a/source/_components/media_player.pioneer.markdown b/source/_components/media_player.pioneer.markdown new file mode 100644 index 00000000000..0d05f454731 --- /dev/null +++ b/source/_components/media_player.pioneer.markdown @@ -0,0 +1,32 @@ +--- +layout: page +title: "Pioneer Network Receivers" +description: "Instructions on how to integrate a Pioneer Network Receivers into Home Assistant." +date: 2016-05-07 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: pioneer.png +ha_category: Media Player +featured: false +ha_release: 0.19 +--- + +The `pioneer` platform allows you to control Pioneer Network Receivers. + +To add a Pioneer receiver to your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +media_player: + platform: pioneer + host: 192.168.0.10 + name: Living receiver +``` + +Configuration variables: + +- **host** *Required*: The IP of the Pioneer device, eg. `192.168.0.10` +- **name** *Optional*: The name you would like to give to the receiver. + diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index 966b96ca453..df2adc25741 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -39,6 +39,8 @@ Configuration variables: - **username** (*Optional*): The username to use with your MQTT broker. - **password** (*Optional*): The corresponding password for the username to use with your MQTT broker. - **certificate** (*Optional*): Certificate to use to encrypt communication with the broker. +- **client_key** (*Optional*): Client key (example: `/home/user/owntracks/cookie.key`) +- **client_cert** (*Optional*): Client certificate (example: `/home/user/owntracks/cookie.crt`) - **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1. ## {% linkable_title Picking a broker %} diff --git a/source/_components/octoprint.markdown b/source/_components/octoprint.markdown new file mode 100644 index 00000000000..67b3846901b --- /dev/null +++ b/source/_components/octoprint.markdown @@ -0,0 +1,30 @@ +--- +layout: page +title: "OctoPrint" +description: "Instructions how to setup the OctoPrint in Home Assistant." +date: 2015-01-20 22:36 +sidebar: true +comments: false +sharing: true +footer: true +logo: octoprint.png +ha_category: Hub +featured: true +ha_release: 0.19 +--- + +[OctoPrint](http://octoprint.org/) is a web interface for your 3D printer. This is the main component to integrate OctoPrint sensors, you will have to setup sensors and binary sensors separately. + +To get started with the OctoPrint API, please follow the directions on their [site](http://docs.octoprint.org/en/master/api/general.html). Once OctoPrint is configured you will need to add your API key and host to your configuration.yaml. + + +```yaml +octoprint: + host: http://YOUR_OCTOPRINT_HOST + api_key: YOUR_API_KEY +``` + +Configuration variables: + +- **api_key** (*Required*): The retrieved api key. +- **host** (*Required*): The octoprint host. diff --git a/source/_components/rfxtrx.markdown b/source/_components/rfxtrx.markdown index 58119039920..bb4635fb6bb 100644 --- a/source/_components/rfxtrx.markdown +++ b/source/_components/rfxtrx.markdown @@ -22,33 +22,10 @@ rfxtrx: debug: True ``` + Configuration variables: - **device** (*Required*): The path to your device, e.g. `/dev/serial/by-id/usb-RFXCOM_RFXtrx433_A1Y0NJGR-if00-port0` - **debug** (*Optional*): If you want to receive debug output. -### How to find the packet_id for your devices -Make sure you have enabled all RFXtrx related platforms. Push your remote and the device will be added automatically. After that you can see you device packetid in the state developer tools in the app. - -Example for X10 and Chacon DI.O signals, if you see in state developer tools the following entities: - -``` -light.123efab1__1b2200000890efab1213f60 -light.a8__0123454041230170 -``` - -You must add the following to your `configuration.yaml`: - -```YAML -light: - platform: rfxtrx - automatic_add: True - devices: - 123efab1: - name: My DI.0 light device - packetid: 1b2200000890efab1213f60 - a8: - name: My X10 light device - packetid: 0123454041230170 -``` diff --git a/source/_components/script.markdown b/source/_components/script.markdown index d6c3be180ce..e1ddf497f02 100644 --- a/source/_components/script.markdown +++ b/source/_components/script.markdown @@ -11,15 +11,27 @@ logo: home-assistant.png ha_category: Automation --- -The script component allows users to create a sequence of service calls and delays. Scripts can be started using the service `script/turn_on` and interrupted using the service `script/turn_off`. +The script component allows users to specify a sequence of actions to be executed by Home Assistant when turned on. The script component will create an entity for each script and allow them to be controlled via services. + +The sequence of actions is specified using the [Home Assistant Script Syntax]. + +[Home Assistant Script Syntax]: /getting-started/scripts/ ```yaml # Example configuration.yaml entry script: + message_temperature: + sequence: + # This is Home Assistant Script Syntax + - service: notify.notify + data_template: + message: Current temperature is {% raw %}{{ states.sensor.temperature.state }}{% endraw %} + # Turns on the bedroom lights and then the living room lights 1 minute later wakeup: alias: Wake Up sequence: + # This is Home Assistant Script Syntax - event: LOGBOOK_ENTRY event_data: name: Paulus @@ -32,10 +44,28 @@ script: entity_id: group.bedroom brightness: 100 - delay: - # supports seconds, milliseconds, minutes, hours, etc. + # supports seconds, milliseconds, minutes, hours minutes: 1 - alias: Living room lights on service: light.turn_on data: entity_id: group.living_room ``` + +### {% linkable_title Passing parameters in service calls %} + +As part of the service, parameters can be passed in that will be made available to the script as variables within templates. + +There are two ways to activate scripts. One is using the generic `script.turn_on` service. To pass variables to the script with this service, call it using the following parameters: + +```yaml +{ + "entity_id": "script.wakeup", + "variables": { + "hello": "world", + "name": "Paulus" + } +} +``` + +If you are calling the script service directly, for example `script.wakeup`. All service data will be made available as variables. diff --git a/source/_components/sensor.fitbit.markdown b/source/_components/sensor.fitbit.markdown new file mode 100644 index 00000000000..30fdba8603b --- /dev/null +++ b/source/_components/sensor.fitbit.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Fitbit" +description: "Instructions how to integrate Fitbit devices within Home Assistant." +date: 2015-07-11 0:15 +sidebar: true +comments: false +sharing: true +footer: true +logo: +ha_category: Sensor +ha_iot_class: "Cloud Polling" +ha_release: 0.19 +--- + +```yaml +sensor: + platform: fitbit +``` diff --git a/source/_components/sensor.google_travel_time.markdown b/source/_components/sensor.google_travel_time.markdown new file mode 100644 index 00000000000..be06fb1d94b --- /dev/null +++ b/source/_components/sensor.google_travel_time.markdown @@ -0,0 +1,28 @@ +--- +layout: page +title: "Google Maps Travel Time" +description: "Instructions on how to add Google Maps travel time to Home Assistant." +date: 2016-03-28 10:19 +sidebar: true +comments: false +sharing: true +footer: true +logo: +ha_category: Sensor +ha_iot_class: "Cloud Polling" +ha_release: 0.19 +--- + +Sensor to provide travel time from Google maps api. + +Get an api key [here](https://github.com/googlemaps/google-maps-services-python#api-keys). + +```yaml +# Example entry for configuration.yaml +sensor: + platform: google_travel_time + api_key: XXXX_XXXXX_XXXXX + origin: Trondheim, Norway + destination: Paris, France + travel_mode: bicycling # can be ["driving", "walking", "bicycling", "transit"] +``` diff --git a/source/_components/sensor.octoprint.markdown b/source/_components/sensor.octoprint.markdown new file mode 100644 index 00000000000..58aaacb01b8 --- /dev/null +++ b/source/_components/sensor.octoprint.markdown @@ -0,0 +1,36 @@ +--- +layout: page +title: "OctoPrint Sensor" +description: "Instructions how to integrate OctoPrint sensors within Home Assistant." +date: 2016-05-05 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: octoprint.png +ha_category: Sensor +ha_release: 0.19 +--- + + +The `OctoPrint` sensor platform let you monitor various states of your 3D printer and its print jobs. + +To set it up, add the following information to your `configuration.yaml` file: + +```yaml +sensor: + platform: octoprint + monitored_conditions: + - Current State + - Temperatures + - Job Percentage +``` + +Configuration variables: + +- **monitored_conditions** array (*Required*): States to monitor. + - Current State (Text of current state) + - Temperatures (Temperatures of all available tools)(print head, print bed, ...) These will be displayed as tool0, tool1, ... please refer to your OctoPrint frontend to associate tool number with actual device. + - Job Percentage + +

You must have the [OctoPrint component](/components/octoprint/) configured to use this sensor.

diff --git a/source/_components/sensor.rfxtrx.markdown b/source/_components/sensor.rfxtrx.markdown index 3efb14a9919..294b1dc2369 100644 --- a/source/_components/sensor.rfxtrx.markdown +++ b/source/_components/sensor.rfxtrx.markdown @@ -12,25 +12,59 @@ ha_category: Sensor The `rfxtrx` platform support sensors that communicate in the frequency range of 433.92 MHz. -To enable RFXtrx sensors in your installation, add the following to your `configuration.yaml` file: +First you have to set up your [rfxtrx hub.](/components/rfxtrx/) +The easiest way to find your sensors is to add this to your `configuration.yaml`: +```yaml +sensor: + platform: rfxtrx + automatic_add: True +``` +Then when the sensor emits a signal it will be automatically added: + +

+ +

+ +Here the name is 0a52080000301004d240259 and you can verify that it works from the frontend. +Then you should update your configuration to: +```yaml +sensor: + platform: rfxtrx + devices: + 0a52080000301004d240259: + name: device_name +``` + +If you want to display several data types from one sensor: + +```yaml +sensor: + platform: rfxtrx + devices: + 0a520802060100ff0e0269: + name: Bath + data_type: + - Humidity + - Temperature +``` + + + +Example configuration: ```yaml # Example configuration.yaml entry sensor: platform: rfxtrx automatic_add: True devices: - sensor_0502: + 0a52080705020095220269: name: Lving - packetid: 0a52080705020095220269 - data_type: Temperature - sensor_0601: - name: Bath_Humidity - packetid: 0a520802060100ff0e0269 - data_type: Humidity - sensor_0601 2: - name: Bath - packetid: 0a520802060100ff0e0269 + 0a520802060100ff0e0269: + name: Bath + data_type: + - Humidity + - Temperature ``` Configuration variables: @@ -38,3 +72,4 @@ Configuration variables: - **devices** (*Optional*): A list of devices with their name to use in the frontend. - **automatic_add** (*Optional*): To enable the automatic addition of new lights. - **data_type** (*Optional*): Which data type the sensor should show + diff --git a/source/_components/switch.acer_projector.markdown b/source/_components/switch.acer_projector.markdown new file mode 100644 index 00000000000..fac3494da63 --- /dev/null +++ b/source/_components/switch.acer_projector.markdown @@ -0,0 +1,37 @@ +--- +layout: page +title: "Acer Projector Switch" +description: "Instructions how to integrate Acer Projector switches into Home Assistant." +date: 2016-05-07 07:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: acer.png +ha_category: Switch +ha_iot_class: "Local Polling" +ha_release: 0.19 +--- + + +The `acer_projector` switch platform allows you to control the state of RS232 connected projectors from [Acer](http://www.acer.com). + +To use your Acer Projector in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +switch: + platform: acer_projector + filename: /dev/ttyUSB0 + name: Projector + timeout: 1 + write_timeout: 1 +``` + +Configuration variables: + +- **filename** (*Required*): The pipe where the projector is connected to +- **name** (*Optional*): The name to use when displaying this switch. +- **timeout** (*Optional*): Timeout for the connection in seconds. +- **write_timeout** (*Optional*): Write timeout in seconds. + diff --git a/source/_components/switch.rfxtrx.markdown b/source/_components/switch.rfxtrx.markdown index 45908018dfc..ee66a922d78 100644 --- a/source/_components/switch.rfxtrx.markdown +++ b/source/_components/switch.rfxtrx.markdown @@ -13,19 +13,46 @@ ha_release: 0.7.5 The `rfxtrx` platform support switches that communicate in the frequency range of 433.92 MHz. -To enable RFXtrx switches in your installation, add the following to your `configuration.yaml` file: +First you have to set up your [rfxtrx hub.](/components/rfxtrx/) +The easiest way to find your switches is to add this to your `configuration.yaml`: ```yaml -# Example configuration.yaml entry switch: - platform: rfxtrx - signal_repetitions: 3 - devices: - living_room: - name: Living Room - packetid: XXXXX - fire_event: True - automatic_add: True + platform: rfxtrx + automatic_add: True +``` + +Launch your homeassistant and go the website. +Push your remote and your device should be added: + +

+ +

+ +Here the name is 0b11000102ef9f210010f70 and you can verify that it works from the frontend. +Then you should update your configuration to: +```yaml +switch: + platform: rfxtrx + devices: + 0b11000102ef9f210010f70: + name: device_name +``` + +Example configuration: +```yaml +# Example configuration.yaml entry +switch: + platform: rfxtrx + automatic_add: False + signal_repetitions: 2 + devices: + 0b1100ce3213c7f210010f70: + name: Movment1 + 0b11000a02ef2gf210010f50: + name: Movment2 + 0b1111e003af16aa10000060: + name: Door ``` Configuration variables: diff --git a/source/_components/switch.rpi_rf.markdown b/source/_components/switch.rpi_rf.markdown new file mode 100644 index 00000000000..0338a091cbc --- /dev/null +++ b/source/_components/switch.rpi_rf.markdown @@ -0,0 +1,43 @@ +--- +layout: page +title: "Raspberry PI GPIO Switch" +description: "Instructions how to integrate the GPIO of a Raspberry PI into Home Assistant as a switch." +date: 2016-05-07 09:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: raspberry-pi.png +ha_category: Switch +ha_release: 0.19 +--- + + +The `rpi_rf` switch platform allows you to control devices over 433/315MHz LPD/SRD signals with generic low-cost GPIO RF modules on a [Raspberry Pi](https://www.raspberrypi.org/). + +To use your Raspberry Pi with a 433MHz adaptor in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +switch: + platform: rpi_rf + gpio: 17 + switches: + bedroom_light: + code_on: 1234567 + code_off: 1234568 + ambilight: + pulselength: 200 + code_on: 987654 + code_off: 133742 +``` + +Configuration variables: + +- **gpio** array (*Required*): Array of used ports. +- **switches:** (*Required*): Array of switches. + - **[name]** (*Requireld*): If true, inverts the output logic to ACTIVE LOW. Default is false (ACTIVE HIGH). + - **code_on** (*Requireld*): Code to switch the device on, eg. `987654`. + - **code_off** (*Requireld*): Code to switch the device off, eg. `133742`. + - **pulselength** (*Optional*): Length of the pulse + diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index 51192cc7998..21c7496446d 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -21,7 +21,7 @@
  • {% active_link /getting-started/devices/ Setting up devices %}
  • {% active_link /getting-started/customizing-devices/ Customizing devices and services %}
  • {% active_link /getting-started/presence-detection/ Presence Detection %}
    • -
  • {% active_link /getting-started/troubleshooting-configuration/ Troubleshooting configuration.yaml %}
    • +
  • {% active_link /getting-started/troubleshooting-configuration/ Troubleshooting %}
  • @@ -31,6 +31,14 @@
  • {% active_link /getting-started/automation-trigger/ Triggers %}
  • {% active_link /getting-started/automation-condition/ Conditions %}
  • {% active_link /getting-started/automation-action/ Actions %}
    • +
  • {% active_link /getting-started/automation-templating/ Templates %}
    • + + +
  • + {% active_link /getting-started/scripts/ Scripts %} +
  • diff --git a/source/_posts/2016-05-07-empowering-scripts-and-alexa.markdown b/source/_posts/2016-05-07-empowering-scripts-and-alexa.markdown new file mode 100644 index 00000000000..0b8fd2e2b16 --- /dev/null +++ b/source/_posts/2016-05-07-empowering-scripts-and-alexa.markdown @@ -0,0 +1,159 @@ +--- +layout: post +title: "0.19: Empowering scripts and Alexa" +description: "The new release of Home Assistant includes a lot of upgrades to how we handle scripts and make them available in a wide range of new components including automation and alexa." +date: 2016-05-07 11:06:00 -0700 +date_formatted: "May 7, 2016" +author: Paulus Schoutsen +author_twitter: balloob +comments: true +categories: Talks +og_image: /images/blog/2016-05-openiot/preview-video.png +--- + +This release is big. Until now, our automations and scripts have been very static. Starting today it should all be a bit more dynamic. + +**Scripts** are now available in automations and when responding to Alexa/Amazon Echo. Both of these components will now expose data to be used in script templates (including `from_state` !). Passing data to script entities is available by passing the data to the script services. + +```yaml +automation: + trigger: + platform: mqtt + topic: some/notify/topic + action: + service: notify.notify + data_template: + message: {{ trigger.payload }} + +automation 2: + trigger: + platform: state + entity_id: light.hue + action: + service: notify.notify + data_template: + message: {{ trigger.to_state.name }} is now {{ trigger.to_state.state }} +``` + +**Entity Namespaces** allow you to influence the entity ids for a specific platform. For example you can turn `light.living_room` into `light.holiday_home_living_room` with the following config: + +```yaml +light: + platform: hue + entity_namespace: holiday_home +``` + + + + - Automation: allow [script syntax] for action ([@balloob]) + - Automation: expose [`trigger` variable][trigger-variable] to script templates ([@balloob]) + - Script: allow passing variables for script templates in the [script service calls] ([@balloob]) + - Alexa/Amazon Echo: allow [script syntax] for action ([@balloob]) + - Alexa/Amazon Echo: [expose intent variables] to script templates ([@balloob]) + - Script syntax: [conditions now supported] to interrupt execution ([@balloob]) + - Automation: use [new condition syntax] ([@balloob]) + - Script syntax: two new conditions [`and`][con-and] and [`or`][con-or] to combine conditions ([@balloob]) + - Any platform: Allow setting [entity namespace] to prefix entity_ids. ([@balloob]) + - Switch: [Raspberry Pi generic 433 Mhz GPIO adapters][rpi-rf] now supported ([@milaq]) + - Z-Wave: use more sane defaults ([@danieljkemp]) + - Media Player: [Snapcast] now supports picking a source ([@happyleavesaoc]) + - MySensors: major cleanup ([@MartinHjelmare]) + - Binary Sensor: [Command line sensor] now supports classes ([@fabaff]) + - MQTT: [allow client key authentication] ([@timharton]) + - Sensor: [Forecast.io] now supports minutely, hourly and daily summaries ([@aceat64]) + - Media Player: [Pioneer AVR] now supported ([@kylehendricks]) + - Switch: [Acer Projectors] now supported ([@deisi]) + - New [HVAC component] added with Z-Wave support ([@turbokongen]) + - Support added for [OctoPrint] ([@w1ll1am23]) + - Configuration.yaml can now refer to environment variables using `!envvar` ([@bah2830]) + - Lock: [Z-Wave][lock.zwave] now supported ([@devdelay]) + - New [Dweet component] to export data ([@fabaff]) + - Media Player now supports stop command + initial kodi support ([@hmronline]) + - Zigbee: push updates now supported ([@flyte]) + - Wink devices with battery level will now show these ([@w1ll1am23]) + - Templates: new [`as_timestamp`] method now available ([@srcLurker]) + - API: Add [`/api/discovery_info`] with basic instance info ([@robbiet480]) + - Sensor: [Google Maps travel time] added ([@Danielhiversen]) + - HTTP: Allow adding [CORS headers] ([@robbiet480]) + - Sensor: [Fitbit] support added ([@robbiet480]) + - Bug fixes and tweaks by [@turbokongen], [@danieljkemp], [@Danielhiversen], [@TheRealLink], [@persandstrom], [@sander76], [@fabaff], [@ishults], [@Bart274], [@robbiet480], [@Cinntax], [@blackdog70], [@gwendalg], [@JshWright], [@kylehendricks], [@bradsk88], [@shaftoe], [@molobrakos], [@bah2830], [@nkgilley] + +[script syntax]: /getting-started/scripts/ +[trigger-variable]: /getting-started/automation-templating/#available-trigger-data +[script service calls]: /components/script/#passing-parameters-in-service-calls +[expose intent variables]: /components/alexa/#configuring-home-assistant +[conditions now supported]: /getting-started/scripts-conditions/ +[new condition syntax]: /getting-started/scripts-conditions/ +[con-and]: /getting-started/scripts-conditions/#and-condition +[con-or]: /getting-started/scripts-conditions/#or-condition +[entity namespace]: /topics/platform_options/#entity-namespace +[rpi-rf]: /components/switch.rpi_rf/ +[Forecast.io]: /components/sensor.forecast/ +[Snapcast]: /components/media_player.snapcast/ +[Command line sensor]: /components/sensor.command_line/ +[allow client key authentication]: /components/mqtt/ +[Pioneer AVR]: /components/media_player.pioneer/ +[Acer Projectors]: /components/switch.acer_projector/ +[HVAC component]: /components/hvac/ +[OctoPrint]: /components/octoprint/ +[Z-Wave]: /components/zwave/ +[lock]: /components/lock/ +[lock.zwave]: /components/lock.zwave/ +[Dweet component]: /components/dweet/ +[`as_timestamp`]: /topics/templating/#home-assistant-template-extensions +[Google Maps travel time]: /components/sensor.google_travel_time/ +[CORS headers]: /components/http/ +[Fitbit]: /components/sensor.fitbit/ +[@balloob]: https://github.com/balloob/ +[@milaq]: https://github.com/milaq/ +[@danieljkemp]: https://github.com/danieljkemp/ +[@happyleavesaoc]: https://github.com/happyleavesaoc/ +[@MartinHjelmare]: https://github.com/MartinHjelmare/ +[@fabaff]: https://github.com/fabaff/ +[@timharton]: https://github.com/timharton/ +[@aceat64]: https://github.com/aceat64/ +[@kylehendricks]: https://github.com/kylehendricks/ +[@deisi]: https://github.com/deisi/ +[@turbokongen]: https://github.com/turbokongen/ +[@w1ll1am23]: https://github.com/w1ll1am23/ +[@bah2830]: https://github.com/bah2830/ +[@devdelay]: https://github.com/devdelay/ +[@hmronline]: https://github.com/hmronline/ +[@flyte]: https://github.com/flyte/ +[@srcLurker]: https://github.com/srcLurker/ +[@robbiet480]: https://github.com/robbiet480/ +[@Danielhiversen]: https://github.com/Danielhiversen/ +[@TheRealLink]: https://github.com/TheRealLink/ +[@persandstrom]: https://github.com/persandstrom/ +[@sander76]: https://github.com/sander76/ +[@ishults]: https://github.com/ishults/ +[@Bart274]: https://github.com/Bart274/ +[@Cinntax]: https://github.com/Cinntax/ +[@blackdog70]: https://github.com/blackdog70/ +[@gwendalg]: https://github.com/gwendalg/ +[@JshWright]: https://github.com/JshWright/ +[@bradsk88]: https://github.com/bradsk88/ +[@shaftoe]: https://github.com/shaftoe/ +[@molobrakos]: https://github.com/molobrakos/ +[@nkgilley]: https://github.com/nkgilley/ + +### Deprecations + - Conditions in automations should now specify which condition to use with `condition:` instead of `platform:`. For example `condition: state`. + - RFXtrx has a new config format. + +Old RFXtrx config format: + +```yaml + devices: + 123efab1: + name: My DI.0 light device + packetid: 1b2200000890efab1213f60 +``` + +New RFXtrx config format: + +```yaml + devices: + 1b2200000890efab1213f60: + name: My DI.0 light device +``` diff --git a/source/_cookbook/customize_polling_interval.markdown b/source/_topics/platform_options.markdown similarity index 61% rename from source/_cookbook/customize_polling_interval.markdown rename to source/_topics/platform_options.markdown index ef73095c114..eb8f1300c22 100644 --- a/source/_cookbook/customize_polling_interval.markdown +++ b/source/_topics/platform_options.markdown @@ -1,15 +1,29 @@ --- layout: page -title: "Customize polling interval for any component" +title: "Entity component platform options" description: "Shows how to customize polling interval for any component via configuration.yaml." date: 2016-02-12 23:17 -0800 sidebar: true comments: false sharing: true footer: true -ha_category: Customize Defaults --- +Any component that is based on the entity component allows various extra options to be set per platform. + +### {% linkable_title Entity namespace %} + +By setting an entity namespace, all entities will be prefixed with that namespace. That way `light.bathroom` can become `light.holiday_house_bathroom`. + +```yaml +# Example configuration.yaml entry +light: + platform: hue + entity_namespace: holiday_house +``` + +### {% linkable_title Scan Interval %} + Platforms that require polling will be polled in an interval specified by the main component. For example a light will check every 30 seconds for a changed state. It is possible to overwrite this scan interval for any platform that is being polled by specifying a `scan_interval` config key. In the example below we setup the Philips Hue lights but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds. ```yaml diff --git a/source/_topics/templating.markdown b/source/_topics/templating.markdown index 5bc4c9ea59b..5211753d2a4 100644 --- a/source/_topics/templating.markdown +++ b/source/_topics/templating.markdown @@ -69,6 +69,7 @@ Home Assistant adds extensions to allow templates to access all of the current s - Filter `round(x)` will convert the input to a number and round it to `x` decimals. - `now` will be rendered as current time in your time zone. - `utcnow` will be rendered as UTC time. + - `as_timestamp` will convert datetime object or string to UNIX timestamp - `distance()` will measure the distance in meters between home, entity, coordinates. - `closest()` will find the closest entity. diff --git a/source/developers/credits.markdown b/source/developers/credits.markdown index 0d985f8c549..5e9b44d4553 100644 --- a/source/developers/credits.markdown +++ b/source/developers/credits.markdown @@ -23,14 +23,17 @@ This page contains a list of people who have contributed in one way or another t - [Alex Harvey](https://github.com/infamy) - [Allan Glen](https://github.com/allanglen) - [Andrew](https://github.com/aoakeson) +- [Andrew LeCody](https://github.com/aceat64) - [Andy Loughran](https://github.com/andylockran) - [andythigpen](https://github.com/andythigpen) - [Arthur Leonard Andersen](https://github.com/leoc) - [Austin](https://github.com/trainman419) - [Azelphur](https://github.com/Azelphur) - [Bart274](https://github.com/Bart274) +- [blackdog70](https://github.com/blackdog70) - [Brad Buran](https://github.com/bburan) - [Brad Johnson](https://github.com/bradsk88) +- [Brent](https://github.com/bah2830) - [Bruno Adele](https://github.com/badele) - [Carlo Costanzo](https://github.com/CCOSTAN) - [Charles Spirakis](https://github.com/srcLurker) @@ -44,6 +47,7 @@ This page contains a list of people who have contributed in one way or another t - [Daren Lord](https://github.com/Xorso) - [Dean Galvin](https://github.com/FreekingDean) - [Dennis Karpienski](https://github.com/TheRealLink) +- [devdelay](https://github.com/devdelay) - [Edwin Smulders](https://github.com/Dutchy-) - [Ellis Percival](https://github.com/flyte) - [Eric Rolf](https://github.com/xrolfex) @@ -58,9 +62,12 @@ This page contains a list of people who have contributed in one way or another t - [Greg Dowling](https://github.com/pavoni) - [Guillem Barba](https://github.com/gbarba) - [Gustav Ahlberg](https://github.com/Gyran) +- [gwendalg](https://github.com/gwendalg) - [happyleavesaoc](https://github.com/happyleavesaoc) - [Heathbar](https://github.com/heathbar) +- [Hernán](https://github.com/hmronline) - [Hydreliox](https://github.com/HydrelioxGitHub) +- [Igor Shults](https://github.com/ishults) - [Issac Kelly](https://github.com/issackelly) - [James Cole](https://github.com/jamespcole) - [Jan Harkes](https://github.com/jaharkes) @@ -84,6 +91,7 @@ This page contains a list of people who have contributed in one way or another t - [Karen Goode](https://github.com/kfgoode) - [kennedyshead](https://github.com/kennedyshead) - [kixam](https://github.com/kixam) +- [Kyle Hendricks](https://github.com/kylehendricks) - [Luca Soldi](https://github.com/LucaSoldi) - [Lukas Hetzenecker](https://github.com/lukas-hetzenecker) - [Magnus Knutas](https://github.com/MagnusKnutas) @@ -97,6 +105,7 @@ This page contains a list of people who have contributed in one way or another t - [Michael Auchter](https://github.com/auchter) - [Michael Gilbert](https://github.com/Zyell) - [Michael Kuty](https://github.com/michaelkuty) +- [Micha LaQua](https://github.com/milaq) - [miniconfig](https://github.com/miniconfig) - [molobrakos](https://github.com/molobrakos) - [Moon Shot](https://github.com/moonshot) @@ -127,6 +136,7 @@ This page contains a list of people who have contributed in one way or another t - [Theb-1](https://github.com/Theb-1) - [Theodor Lindquist](https://github.com/theolind) - [tilutza](https://github.com/tilutza) +- [Tim Harton](https://github.com/timharton) - [toddeye](https://github.com/toddeye) - [Tom Duijf](https://github.com/tomduijf) - [trollkarlen](https://github.com/trollkarlen) diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index 197c1d0648e..8e4463a9e0b 100644 --- a/source/developers/rest_api.markdown +++ b/source/developers/rest_api.markdown @@ -273,6 +273,25 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api/error_log ``` +#### {% linkable_title GET /api/discovery_info %} +Retrieve about the discovery feature. + +```json +{ + "base_url": "http://192.168.1.2:8123", + "location_name": "My home", + "requires_api_password": true, + "version": "0.19.0" +} +``` + +Sample `curl` command: + +```bash +$ curl -X GET -H "x-ha-access: mypass" \ + http://localhost:8123/api/discovery_info +``` + #### {% linkable_title POST /api/states/<entity_id> %} Updates or creates the current state of an entity. diff --git a/source/getting-started/automation-action.markdown b/source/getting-started/automation-action.markdown index fc6f10fea82..b08c9678a93 100644 --- a/source/getting-started/automation-action.markdown +++ b/source/getting-started/automation-action.markdown @@ -9,11 +9,19 @@ sharing: true footer: true --- -When an automation rule fires, it calls a service. For this service you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness). +The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax] which can be used to interact with anything via services or events. For services you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness). + +You can also call the service to activate [a scene] which will allow you to define how you want your devices to be and have Home Assistant call the right services. + +[script syntax]: /getting-started/scripts/ +[a scene]: /components/scene/ ```yaml automation: # Change the light in the kitchen and living room to 150 brightness and color red. + trigger: + platform: sun + event: sunset action: service: homeassistant.turn_on entity_id: @@ -22,15 +30,20 @@ automation: data: brightness: 150 rgb_color: [255, 0, 0] -``` -```yaml -automation: +automation 2: # Notify me on my mobile phone of an event + trigger: + platform: sun + event: sunset + offset: -00:30 action: - service: notify.notify - data: - message: Something just happened, better take a look! + # Actions are scripts so can also be a list of actions + - service: notify.notify + data: + message: Beautiful sunset! + - delay: 0:35 + - service: notify.notify + data: + message: Oh wow you really missed something great. ``` - -If you want to specify multiple services to be called, or to include a delay, have a look at the [script component](/components/script/). If you want to describe the desired state of certain entities, check out the [scene component](/components/scene/). diff --git a/source/getting-started/automation-condition.markdown b/source/getting-started/automation-condition.markdown index 5930840c101..8a712153168 100644 --- a/source/getting-started/automation-condition.markdown +++ b/source/getting-started/automation-condition.markdown @@ -11,18 +11,6 @@ footer: true Conditions are an optional part of an automation rule and be used to prevent an action from happening when triggered. Conditions look very similar to triggers but are very different. A trigger will look at events happening in the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is currently on or off. -An automation rule can have multiple conditions. By default the action will only fire if all conditions pass. An optional key `condition_type: 'or'` can be set on the automation rule to fire action if any condition matches. In the example below, the automation would trigger if the time is before 05:00 _OR_ after 20:00. - -```yaml -automation: - condition_type: or - condition: - - platform: time - before: '05:00' - - platform: time - after: '20:00' -``` - If your triggers and conditions are exactly the same, you can use a shortcut to specify conditions. In this case, triggers that are not valid conditions will be ignored. ```yaml @@ -30,92 +18,6 @@ automation: condition: use_trigger_values ``` -#### {% linkable_title Numeric state condition %} +The available conditions for an automation are the same as for the script syntax. So see that page for a [full list of available conditions][script-condition]. -This type of condition attempts to parse the state of specified entity as a number and triggers if the value matches all of the above or below thresholds. -Either `above` or `below`, or both need to be specified. If both are used, the condition is true when the value is >= `before` *and** < `after`. -You can optionally use a `value_template` to make the value of the entity the same type of value as the condition. - -```yaml -automation: - condition: - platform: numeric_state - entity_id: sensor.temperature - above: 17 - below: 25 -``` - -#### {% linkable_title State condition %} - -Tests if an entity is a specified state. - -```yaml -automation: - condition: - platform: state - entity_id: device_tracker.paulus - state: not_home - # optional: trigger only if state was this for last X time. - for: - hours: 1 - minutes: 10 - seconds: 5 -``` - -#### {% linkable_title Sun condition %} - -The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger](#sun-trigger). - -```yaml -automation: - condition: - platform: sun - after: sunset - # Optional offset value - after_offset: "-1:00:00" -``` - -#### {% linkable_title Template condition %} - -The template condition will test if the [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'. - - -```yaml -automation: - condition: - platform: template - value_template: '{% raw %}{{ state.attributes.battery > 50 }}{% endraw %}' - # Or value_template could be: - # {% raw %}{% if state.attributes.battery > 50 %}true{% else %}false{% endif %}{% endraw %} -``` - -#### {% linkable_title Time condition %} - -The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week - -```yaml -automation: - condition: - platform: time - # At least one of the following is required. - after: '15:00:00' - before: '23:00:00' - weekday: - - mon - - wed - - fri -``` - -Valid values for `weekday` are (`sun`, `mon`, `tue`, `wed`, `thu`, `fri` & `sat`) - -#### {% linkable_title Zone condition %} - -Zone conditions test if an entity is in a certain zone. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently this is limited to the [OwnTracks platform](/components/device_tracker.owntracks/) and the [iCloud platform](/components/device_tracker.icloud/). - -```yaml -automation: - condition: - platform: zone - entity_id: device_tracker.paulus - zone: zone.home -``` +[script-condition]: /getting-started/scripts-conditions/ diff --git a/source/getting-started/automation-create-first.markdown b/source/getting-started/automation-create-first.markdown index 0d123608a46..e128a94ce1e 100644 --- a/source/getting-started/automation-create-first.markdown +++ b/source/getting-started/automation-create-first.markdown @@ -74,7 +74,7 @@ automation: Christmas is coming along and you decide to buy a remote switch to control the Christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turning on your Christmas lights! -We hook the switch up to Home Assistant and grab the entity ID0 from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. +We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. ```yaml # Example configuration.yaml entry @@ -98,3 +98,15 @@ automation: service: homeassistant.turn_on entity_id: group.living_room ``` + +### {% linkable_title Learn more %} + + - [Triggers] + - [Conditions] + - [Actions] + - [Templating] (advanced) + +[Triggers]: /getting-started/automation-trigger/ +[Conditions]: /getting-started/automation-condition/ +[Actions]: /getting-started/automation-action/ +[Templating]: /getting-started/automation-templating/ diff --git a/source/getting-started/automation-templating.markdown b/source/getting-started/automation-templating.markdown new file mode 100644 index 00000000000..e80b973d3ce --- /dev/null +++ b/source/getting-started/automation-templating.markdown @@ -0,0 +1,98 @@ +--- +layout: page +title: "Automation Templating" +description: "Advanced automation documentation using templating." +date: 2016-04-24 08:30 +0100 +sidebar: true +comments: false +sharing: true +footer: true +--- + +In Home Assistant 0.19 we introduced a new powerful feature: variables in scripts and automations. This makes it possible to adjust your condition and action based on the information of the trigger. + +The trigger data made is available during template rendering as the `trigger` variable. + +```yaml +# Example configuration.yaml entries +automation: + trigger: + platform: state + entity_id: device_tracker.paulus + action: + service: notify.notify + data_template: + message: >{% raw %} + Paulus just changed from {{ trigger.from_state.state }} + to {{ trigger.to_state.state }}{% endraw %} + +automation 2: + trigger: + platform: mqtt + topic: /notify/+ + action: + service_template: >{% raw %} + notify.{{ trigger.topic.split('/')[-1] }} + data_template: + message: {% raw %}{{ trigger.payload }}{% endraw %} +``` + +### {% linkable_title Available Trigger Data %} + +The following tables show the available trigger data per platform. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `event`. +| `trigger.event` | Event object that matched. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `mqtt`. +| `trigger.topic` | Topic that received payload. +| `trigger.payload` | Payload. +| `trigger.qos` | QOS of payload. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `numeric_state` +| `trigger.entity_id` | Entity ID that we observe. +| `trigger.below` | The below treshold, if any. +| `trigger.above` | The above treshold, if any. +| `trigger.from_state` | The previous state of the entity. +| `trigger.to_state` | The new state that triggered trigger. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `state` +| `trigger.entity_id` | Entity ID that we observe. +| `trigger.from_state` | The previous state of the entity. +| `trigger.to_state` | The new state that triggered trigger. +| `trigger.for` | Timedelta object how long state has been to state, if any. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `sun` +| `trigger.event` | The event that just happened: `sunset` or `sunrise`. +| `trigger.offset` | Timedelta object with offset to the event, if any. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `template` +| `trigger.entity_id` | Entity ID that caused change. +| `trigger.from_state` | Previous state of entity that caused change. +| `trigger.to_state` | New state of entity that caused template to change. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `time` +| `trigger.now` | DateTime object that triggered the time trigger. + +| Template variable | Data | +| ---- | ---- | +| `trigger.platform` | Hardcoded: `zone` +| `trigger.entity_id` | Entity ID that we are observing. +| `trigger.from_state` | Previous state of the entity. +| `trigger.to_state` | New state of the entity. +| `trigger.zone` | State object of zone +| `trigger.event` | Event that trigger observed: `enter` or `leave`. diff --git a/source/getting-started/automation-trigger.markdown b/source/getting-started/automation-trigger.markdown index f471c68d12f..3fc7462c14d 100644 --- a/source/getting-started/automation-trigger.markdown +++ b/source/getting-started/automation-trigger.markdown @@ -53,13 +53,13 @@ automation: #### {% linkable_title State trigger %} -Triggers when the state of an entity changes. If only entity_id given will match all state changes. +Triggers when the state of tracked entities change. If only entity_id given will match all state changes. ```yaml automation: trigger: platform: state - entity_id: device_tracker.paulus + entity_id: device_tracker.paulus, device_tracker.anne_therese # Optional from: 'not_home' to: 'home' diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown index c40ab99c08b..2de0f5c7db7 100644 --- a/source/getting-started/automation.markdown +++ b/source/getting-started/automation.markdown @@ -11,23 +11,35 @@ footer: true When all your devices are set up it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) but mainly you'll be using the automation component to set up your own rules. +Home Assistant offers a wide range of automations. In the next few pages we'll try to guide you through all the different possibilities and options. Besides this documentation there are also a couple of people who have made their automation configurations [publicly available][cookbook-config]. + +[cookbook-config]: /cookbook/#example-configurationyaml + ### {% linkable_title The basics of automation %} -Every automation rule consists of triggers, an action to be performed and optional conditions. +Before you can go ahead and create your own automations, it's important to learn the basics. To explore the basics, let's have a look at the following example home automation rule: -Triggers can be anything observed in Home Assistant. For example, it can be a certain point in time or a person coming home, which can be observed by the state changing from `not_home` to `home`. +```text +(trigger) When Paulus arrives home +(condition) and it is after sunset: +(action) Turn the lights in the living room on +``` -Actions will call services within Home Assistant. For example, turn a light on, set the temperature on your thermostat or activate a scene. +The example consists of three different parts: a trigger, a condition and an action. -Conditions are used to prevent actions from firing unless certain conditions are met. For example, it is possible to only turn on the light if someone comes home and it is after a certain point in time. +The first line is the trigger of the automation rule. Triggers describe events that should trigger the automation rule. In this case it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'. -The difference between a condition and a trigger can be confusing. The difference is that the trigger looks at the event that is happening, e.g., a car engine turning on. Conditions looks at the current state of the system, e.g., is the car engine on. +The second line is the condition part of the automation rule. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case we only want to act when the sun has set. + +The third part is the action which will be performed when a rule is triggered and all conditions are met.For example, it can turn a light on, set the temperature on your thermostat or activate a scene. + +

    +The difference between a condition and a trigger can be confusing as they are very similar. Triggers are looking at the actions while conditions look at the result: turning a light on vs a light being on. +

    ### {% linkable_title Exploring the internal state %} -Automation rules are based on the internal state of Home Assistant. This is available for exploring in the app using the developer tools. The first icon will show you the available services and the second icon will show you the current devices. - -Each device is represented in Home Assistant as an entity consisting of the following parts: +Automation rules interact directly with the internal state of Home Assistant so you'll need to familiarize yourself with it. Home Assistant exposes it's current state via the developer tools which are available at the bottom of the sidebar in the frontend. The icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts: | Name | Description | Example | | ---- | ----- | ---- | @@ -35,22 +47,8 @@ Each device is represented in Home Assistant as an entity consisting of the foll | State | The current state of the device. | `home` | Attributes | Extra data related to the device and/or current state. | `brightness` -A service can be called to have Home Assistant perform an action. Turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light device in your system. Services can be passed parameters to for example tell which device to turn on or what color to use. +State changes can be used as the source of triggers and the current state can be used in conditions. +Actions are all about calling services. To explore the available services open the Services developer tool. Services allow to change anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use. - -### {% linkable_title Further reading %} - - - Learn how to make your [first automation rule](/getting-started/automation-create-first/) - - Learn about the available [automation triggers](/getting-started/automation-trigger/) - - Learn about the available [automation conditions](/getting-started/automation-condition/) - - Learn about [scripts](/components/script/) to help you trigger multiple actions and delays - - Learn about [scenes](/components/scene/) to help you set many entities at once to your liking - - Setup a [notification platform](/components/#notifications) to sent yourself messages - - For more advanced automation using Python, write your own [custom component](/developers/creating_components/). - - Check out the [slides](http://events.linuxfoundation.org/sites/events/files/slides/OpenIoT%202016%20-%20Automating%20your%20Home%20with%20Home%20Assistant.pdf) from [OpenIoT 2016 summit](http://events.linuxfoundation.org/events/openiot-summit) - -

    - Whenever you write the value on or off, surround it with quotes to avoid - the YAML parser interpreting the values as booleans. -

    +### [Next step: Your First Automation »](/getting-started/automation-create-first/) diff --git a/source/getting-started/scripts-conditions.markdown b/source/getting-started/scripts-conditions.markdown new file mode 100644 index 00000000000..3ee0d281bd2 --- /dev/null +++ b/source/getting-started/scripts-conditions.markdown @@ -0,0 +1,125 @@ +--- +layout: page +title: "Conditions" +description: "Documentation about all available conditions." +date: 2016-04-24 08:30 +0100 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Conditions can be used within a script or automation to prevent further execution. A condition will look at the system right now. For example a condition can test if a switch is currently turned on or off. + +#### {% linkable_title AND condition %} + +Test multiple conditions in 1 condition statement. Passes if all embedded conditions are valid. + +```yaml +condition: and +conditions: + - condition: state + entity_id: 'device_tracker.paulus' + state: 'home' + - condition: numeric_state + entity_id: 'sensor.temperature' + below: '20' +``` + +#### {% linkable_title Numeric state condition %} + +This type of condition attempts to parse the state of specified entity as a number and triggers if the value matches all of the above or below thresholds. + +For above, the condition passes if `value >= above`. For below, the condition passes if `value <= below`. If both `below` and `above` are specified, both tests have to pass. + +You can optionally use a `value_template` to process the value of the state before testing it. + +```yaml +condition: numeric_state +entity_id: sensor.temperature +above: 17 +below: 25 +# If your sensor value needs to be adjusted +value_template: {{ float(state.state) + 2 }} +``` + +#### {% linkable_title OR condition %} + +Test multiple conditions in 1 condition statement. Passes if any embedded conditions is valid. + +```yaml +condition: or +conditions: + - condition: state + entity_id: 'device_tracker.paulus' + state: 'home' + - condition: numeric_state + entity_id: 'sensor.temperature' + below: '20' +``` + +#### {% linkable_title State condition %} + +Tests if an entity is a specified state. + +```yaml +condition: state +entity_id: device_tracker.paulus +state: not_home +# optional: trigger only if state was this for last X time. +for: + hours: 1 + minutes: 10 + seconds: 5 +``` + +#### {% linkable_title Sun condition %} + +The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger](#sun-trigger). + +```yaml +condition: sun +after: sunset +# Optional offset value +after_offset: "-1:00:00" +``` + +#### {% linkable_title Template condition %} + +The template condition will test if the [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'. + +```yaml +condition: template +value_template: '{% raw %}{{ state.attributes.battery > 50 }}{% endraw %}' +``` + +Within an automation, template conditions also have access to the `trigger` variable as [described here][automation-templating]. + +[automation-templating]: /getting-started/automation-templating/ + +#### {% linkable_title Time condition %} + +The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week + +```yaml +condition: time +# At least one of the following is required. +after: '15:00:00' +before: '23:00:00' +weekday: + - mon + - wed + - fri +``` + +Valid values for `weekday` are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. + +#### {% linkable_title Zone condition %} + +Zone conditions test if an entity is in a certain zone. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently this is limited to the [OwnTracks platform](/components/device_tracker.owntracks/) and the [iCloud platform](/components/device_tracker.icloud/). + +```yaml +condition: zone +entity_id: device_tracker.paulus +zone: zone.home +``` diff --git a/source/_topics/service_calls.markdown b/source/getting-started/scripts-service-calls.markdown similarity index 58% rename from source/_topics/service_calls.markdown rename to source/getting-started/scripts-service-calls.markdown index fb30a38d0d1..1090dc741ed 100644 --- a/source/_topics/service_calls.markdown +++ b/source/getting-started/scripts-service-calls.markdown @@ -3,7 +3,7 @@ layout: page title: "Service Calls" description: "Instructions how to call services in Home Assistant." date: 2016-03-12 12:00 -0800 -sidebar: false +sidebar: true comments: false sharing: true footer: true @@ -16,7 +16,7 @@ The configuration options to call a config are the same between all components a Examples on this page will be given as part of an automation component configuration but different approaches can be used for other components too.

    -Use the service developer tool in the frontend to discover available services. +Use the service developer tool in the frontend to discover available services.

    ### {% linkable_title The basics %} @@ -24,13 +24,8 @@ Use the service developer tool in the frontend to discover available services. Call the service `homeassistant.turn_on` on the entity `group.living_room`. This will turn all members of `group.living_room` on. You can also omit `entity_id` and it will turn on all possible entities. ```yaml -automation: -- trigger: - platform: sun - event: sunset - action: - service: homeassistant.turn_on - entity_id: group.living_room +service: homeassistant.turn_on +entity_id: group.living_room ``` ### {% linkable_title Passing data to the service call %} @@ -38,16 +33,11 @@ automation: You can also specify other parameters beside the entity to target. For example, the light turn on service allows specifying the brightness. ```yaml -automation: -- trigger: - platform: sun - event: sunset - action: - service: light.turn_on - entity_id: group.living_room - data: - brightness: 120 - rgb_color: [255, 0, 0] +service: light.turn_on +entity_id: group.living_room +data: + brightness: 120 + rgb_color: [255, 0, 0] ``` ### {% linkable_title Use templates to decide which service to call %} @@ -55,18 +45,13 @@ automation: You can use [templating] support to dynamically choose which service to call. For example, you can call a certain service based on if a light is on. ```yaml -automation: -- trigger: - platform: sun - event: sunset - action: - service_template: > - {% raw %}{% if states.sensor.temperature | float > 15 %} - switch.turn_on - {% else %} - switch.turn_off - {% endif %}{% endraw %} - entity_id: switch.ac +service_template: > + {% raw %}{% if states.sensor.temperature | float > 15 %} + switch.turn_on + {% else %} + switch.turn_off + {% endif %}{% endraw %} +entity_id: switch.ac ``` ### {% linkable_title Use templates to determine the attributes %} @@ -74,20 +59,15 @@ automation: Templates can also be used for the data that you pass to the service call. ```yaml -automation: -- trigger: - platform: sun - event: sunset - action: - service_template: thermostat.set_temperature - data_template: - entity_id: > - {% raw %}{% if is_state('device_tracker.paulus', 'home') %} - thermostat.upstairs - {% else %} - thermostat.downstairs - {% endif %}{% endraw %} - temperature: {% raw %}{{ 22 - distance(states.device_tracker.paulus) }}{% endraw %} +service: thermostat.set_temperature +data_template: + entity_id: > + {% raw %}{% if is_state('device_tracker.paulus', 'home') %} + thermostat.upstairs + {% else %} + thermostat.downstairs + {% endif %}{% endraw %} + temperature: {% raw %}{{ 22 - distance(states.device_tracker.paulus) }}{% endraw %} ``` [templating]: /topics/templating/ diff --git a/source/getting-started/scripts.markdown b/source/getting-started/scripts.markdown new file mode 100644 index 00000000000..e0413a421da --- /dev/null +++ b/source/getting-started/scripts.markdown @@ -0,0 +1,89 @@ +--- +layout: page +title: "Script Syntax" +description: "Documention for the Home Assistant Script Syntax." +date: 2016-04-24 08:30 +0100 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Scripts are a sequence of actions that Home Assistant will execute. Scripts are available as an entity through the standalone [Script component] but can also be embedded in [automations] and [Alexa/Amazon Echo] configurations. + +The script syntax basic structure is a list of key/value maps that contain actions. If a script contains only 1 action, the wrapping list can be omitted. + +```yaml +# Example script component containing script syntax +script: + example_script: + sequence: + # This is written using the Script Syntax + - service: light.turn_on + entity_id: light.ceiling + - service: notify.notify + data: + message: 'Turned on the ceiling light!' +``` + +#### {% linkable_title Call a Service %} + +The most important one is the action to call a service. This can be done in various ways. For all the different possibilities, have a look at the [service calls page]. + +```yaml +alias: Bedroom lights on +service: light.turn_on +data: + entity_id: group.bedroom + brightness: 100 +``` + +#### {% linkable_title Test a Condition %} + +While executing a script you can add a condition to stop further execution. When a condition does not return `true`, the script will finish. There are many different conditions which are documented at the [conditions page]. + +```yaml +condition: state +entity_id: device_tracker.paulus +state: 'home' +``` + +#### {% linkable_title Delay %} + +Delays are useful for temporarily suspending your script and start it at a later moment. We support different syntaxes for a delay as shown below. + +```yaml +# Waits 1 hour +delay: 01:00 +``` + +```yaml +# Waits 1 minute, 30 seconds +delay: 00:01:30 +``` + +```yaml +# Waits 1 minute +delay: + # supports seconds, minutes, hours, days + minutes: 1 +``` + +#### {% linkable_title Fire an Event %} + +This action allows you to fire an event. Events can be used for many things. It could trigger an automation or indicate to another component that something is happening. For instance, in the below example it is used to create an entry in the logbook. + +```yaml +event: LOGBOOK_ENTRY +event_data: + name: Paulus + message: is waking up + entity_id: device_tracker.paulus + domain: light +``` + +[Script component]: /components/script/ +[automations]: /getting-started/automation-action/ +[Alexa/Amazon Echo]: /components/alexa/ +[service calls page]: /getting-started/scripts-service-calls/ +[conditions page]: /getting-started/scripts-conditions/ diff --git a/source/images/components/rfxtrx/sensor.png b/source/images/components/rfxtrx/sensor.png new file mode 100644 index 00000000000..e8d7ce3d1da Binary files /dev/null and b/source/images/components/rfxtrx/sensor.png differ diff --git a/source/images/components/rfxtrx/switch.png b/source/images/components/rfxtrx/switch.png new file mode 100644 index 00000000000..660b9288e6e Binary files /dev/null and b/source/images/components/rfxtrx/switch.png differ diff --git a/source/images/screenshots/developer-tool-about-icon.png b/source/images/screenshots/developer-tool-about-icon.png new file mode 100644 index 00000000000..0796b67b510 Binary files /dev/null and b/source/images/screenshots/developer-tool-about-icon.png differ diff --git a/source/images/screenshots/developer-tool-events-icon.png b/source/images/screenshots/developer-tool-events-icon.png new file mode 100644 index 00000000000..b3cd955fb72 Binary files /dev/null and b/source/images/screenshots/developer-tool-events-icon.png differ diff --git a/source/images/screenshots/developer-tool-services-icon.png b/source/images/screenshots/developer-tool-services-icon.png new file mode 100644 index 00000000000..0e9eafcdb76 Binary files /dev/null and b/source/images/screenshots/developer-tool-services-icon.png differ diff --git a/source/images/screenshots/developer-tool-states-icon.png b/source/images/screenshots/developer-tool-states-icon.png new file mode 100644 index 00000000000..22cf085c709 Binary files /dev/null and b/source/images/screenshots/developer-tool-states-icon.png differ diff --git a/source/images/screenshots/developer-tool-templates-icon.png b/source/images/screenshots/developer-tool-templates-icon.png new file mode 100644 index 00000000000..4e90e910cf1 Binary files /dev/null and b/source/images/screenshots/developer-tool-templates-icon.png differ diff --git a/source/images/screenshots/dweet-freeboard.png b/source/images/screenshots/dweet-freeboard.png new file mode 100644 index 00000000000..d9fd8a1aade Binary files /dev/null and b/source/images/screenshots/dweet-freeboard.png differ diff --git a/source/images/supported_brands/acer.png b/source/images/supported_brands/acer.png new file mode 100644 index 00000000000..9178908c129 Binary files /dev/null and b/source/images/supported_brands/acer.png differ diff --git a/source/images/supported_brands/octoprint.png b/source/images/supported_brands/octoprint.png new file mode 100644 index 00000000000..bf5286f423d Binary files /dev/null and b/source/images/supported_brands/octoprint.png differ diff --git a/source/images/supported_brands/pioneer.png b/source/images/supported_brands/pioneer.png new file mode 100644 index 00000000000..50574207a82 Binary files /dev/null and b/source/images/supported_brands/pioneer.png differ