+The new picture elements card.
++If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
+ Binary sensors have only two states - "on" and "off". Many door or window opening sensors will send a signal each time the door/window is open or closed. However, depending on their hardware or on their purpose, some sensors are only able to signal their "on" state: - Most motion sensors send a signal each time they detect motion. They stay "on" for a few seconds and go back to sleep, ready to signal other motion events. Usually, they do not send a signal when they go back to sleep. @@ -55,7 +60,6 @@ Binary sensors have only two states - "on" and "off". Many door or window openin For those devices, use the *off_delay* parameter. It defines a delay after which a device will go back to an "Off" state. That "Off" state will be fired internally by Home Assistant, just as if the device fired it by itself. If a motion sensor can only send signals once every 5 seconds, sets the *off_delay* parameter to *seconds: 5*. - Example configuration: ```yaml @@ -83,7 +87,7 @@ Let's try to add a new PT-2262 sensor using the "automatic_add" option and have Have your sensor trigger the "On" state for the first time. Some messages will appear: -``` +```text INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 0913000022670e013970 (Device_id: 22670e Class: LightingDevice Sub: 0) ``` @@ -91,7 +95,7 @@ Here the sensor has the id *22670e*. Now have your sensor trigger the "Off" state and look for the following message in the Home Assistant log. You should see that your device has been detected as a *new* device when triggering its "Off" state: -``` +```text INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 09130000226707013d70 (Device_id: 226707 Class: LightingDevice Sub: 0) ``` @@ -115,7 +119,7 @@ devices: The *automatic_add* option makes the rfxtrx binary sensor component calculate and display the configuration options for you in the Home Assistant logs: -``` +```text INFO (Thread-6) [homeassistant.components.rfxtrx] rfxtrx: found possible device 226707 for 22670e with the following configuration: data_bits=4 command_on=0xe diff --git a/source/_components/calendar.google.markdown b/source/_components/calendar.google.markdown index 9825c5f9cc6..73860367c8c 100644 --- a/source/_components/calendar.google.markdown +++ b/source/_components/calendar.google.markdown @@ -46,7 +46,7 @@ client_id: description: Use the value you generated in the Prerequisites stage. required: true type: string -minimum: +client_secret: description: Use the value you generated in the Prerequisites stage. required: true type: string @@ -95,7 +95,7 @@ Variables: - **track**: (*Required*): Should we create a sensor `True` or ignore it `False`? - **search**: (*Optional*): If set will only trigger for matched events. - **offset**: (*Optional*): A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. (Default: `!!`) - - **ignore_availablilty**: (*Optional*): Should we respect `free`/`busy` flags? (Defaults to `true`) + - **ignore_availability**: (*Optional*): Should we respect `free`/`busy` flags? (Defaults to `true`) From this we will end up with the binary sensors `calendar.test_unimportant` and `calendar.test_important` which will toggle themselves on/off based on events on the same calendar that match the search value set for each. You'll also have a sensor `calendar.test_everything` that will not filter events out and always show the next event available. diff --git a/source/_components/camera.xiaomi.markdown b/source/_components/camera.xiaomi.markdown index 2285e405a41..6e1c279da40 100644 --- a/source/_components/camera.xiaomi.markdown +++ b/source/_components/camera.xiaomi.markdown @@ -19,8 +19,6 @@ To successfully implement this platform, the Home Assistant host should be capab ## {% linkable_title Preparing the Device %} -### {% linkable_title Installing Alternative Firmware %} - In order to integrate the camera with Home Assistant, it is necessary to install a custom firmware on the device. Instructions for doing so can be found for each models. * [Yi 720p](https://github.com/fritz-smh/yi-hack) @@ -29,16 +27,16 @@ In order to integrate the camera with Home Assistant, it is necessary to install Once installed, please ensure that you have enabled FTP. -+
Currently, version 0.1.4-beta2 of the custom firmware is the highest supported. Firmwares higher than this version use [Pure-FTPd](https://www.pureftpd.org/project/pure-ftpd), which has a bug that prevents FFmpeg from correctly rendering video files.
-Hassbian users: don't forget to install ffmpeg support on your platform, otherwise, you'll not see video. +Hassbian users: Don't forget to install `ffmpeg` support on your platform, otherwise, you'll not see video.
-The live stream writing by the camera is not an supported format when the hass reads through FTP for Yi 720p and Xiaofang Cameras, so this component retrives the video which was saved 1 minute earlier. +The live stream writing by the camera is not an supported format when the hass reads through FTP for Yi 720p and Xiaofang Cameras, so this platform retrives the video which was saved 1 minute earlier.
@@ -68,6 +66,10 @@ Configuration variables: - **username** (*Optional*): The user that can access the FTP server. Defaults to `root`. - **ffmpeg_arguments** (*Optional*): Extra options to pass to `ffmpeg` (e.g., image quality or video filter options). +
+The default for `path:` will not work with all cameras. It may be needed that you add that key with the exact path for your device. +
+ ## {% linkable_title Image quality %} Any option supported by [`ffmpeg` camera](/components/camera.ffmpeg/) can be utilized via the `ffmpeg_arguments` configuration parameter. diff --git a/source/_components/cover.rfxtrx.markdown b/source/_components/cover.rfxtrx.markdown index dd31090f864..342677cb5ae 100644 --- a/source/_components/cover.rfxtrx.markdown +++ b/source/_components/cover.rfxtrx.markdown @@ -67,3 +67,8 @@ Configuration variables: - **automatic_add** (*Optional*): To enable the automatic addition of new covers (Siemens/LightwaveRF only). - **signal_repetitions** (*Optional*): Because the rxftrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the roller shutter to try to send each signal repeatedly. - **fire_event** (*Optional*): Fires an event even if the state is the same as before. Can be used for automations. + ++If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
diff --git a/source/_components/device_tracker.mqtt.markdown b/source/_components/device_tracker.mqtt.markdown index 3640b8ad5a4..cf8f006de1f 100644 --- a/source/_components/device_tracker.mqtt.markdown +++ b/source/_components/device_tracker.mqtt.markdown @@ -36,7 +36,7 @@ Example JSON you can publish to the topic (e.g., via mqtt.publish service): ```json { - "topic": "/location/paulus", + "topic": "location/paulus", "payload": "home" } ``` diff --git a/source/_components/device_tracker.snmp.markdown b/source/_components/device_tracker.snmp.markdown index 8193abfee85..9b3805e30ce 100644 --- a/source/_components/device_tracker.snmp.markdown +++ b/source/_components/device_tracker.snmp.markdown @@ -34,6 +34,8 @@ The following OID examples pull the current MAC Address table from a router. Thi | EdgeRouter | Lite v1.9.0 | `1.3.6.1.2.1.4.22.1.2` | | Ruckus | ZoneDirector 9.13.3 | `1.3.6.1.4.1.25053.1.2.2.1.1.3.1.1.1.6` | | DD-WRT | unknown RouterOS version/model | `1.3.6.1.2.1.4.22.1.2` | +| Apple Airport Express (2nd gen.) | 7.6.9 | `1.3.6.1.2.1.3.1.1.2` +`1.3.6.1.2.1.4.22.1.2.16`| To use the SNMP version 1 platform in your installation, add the following to your `configuration.yaml` file: diff --git a/source/_components/light.rfxtrx.markdown b/source/_components/light.rfxtrx.markdown index b6a1b707cf5..c83d9f71fc7 100644 --- a/source/_components/light.rfxtrx.markdown +++ b/source/_components/light.rfxtrx.markdown @@ -60,3 +60,8 @@ Configuration variables: - **automatic_add** (*Optional*): To enable the automatic addition of new lights. - **signal_repetitions** (*Optional*): Because the RFXtrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the switch to try to send each signal repeatedly. - **fire_event** (*Optional*): Fires an event even if the state is the same as before. Can be used for automations. + ++If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
diff --git a/source/_components/sensor.dsmr.markdown b/source/_components/sensor.dsmr.markdown index 6cd6befc3ab..8ead92afc41 100644 --- a/source/_components/sensor.dsmr.markdown +++ b/source/_components/sensor.dsmr.markdown @@ -32,6 +32,7 @@ This component is known to work for: - Landis+Gyr ZCF110 / ZM F110 (DSMR 4.2) - Kaifa E0026 - Kamstrup 382JxC (DSMR 2.2) +- Sagemcom XS210 ESMR5 USB serial converters: diff --git a/source/_components/sensor.rfxtrx.markdown b/source/_components/sensor.rfxtrx.markdown index 91a2dd5cf13..3378d7b03f9 100644 --- a/source/_components/sensor.rfxtrx.markdown +++ b/source/_components/sensor.rfxtrx.markdown @@ -55,7 +55,9 @@ sensor: - Humidity - Temperature ``` + Only these data_type are valid : + - *Temperature* - *Humidity* - *Barometer* @@ -93,4 +95,7 @@ Configuration variables: - **data_type** (*Optional*): Which data type the sensor should show - **fire_event** (*Optional*): Fires an event even if the state is the same as before. Can be used for automations. - ++If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
diff --git a/source/_components/switch.broadlink.markdown b/source/_components/switch.broadlink.markdown index ad5f0214dc4..040a06c726b 100644 --- a/source/_components/switch.broadlink.markdown +++ b/source/_components/switch.broadlink.markdown @@ -31,7 +31,7 @@ Configuration variables: - **mac** (*Required*): Device MAC address. - **timeout** (*Optional*): Timeout in seconds for the connection to the device. - **friendly_name** (*Optional*): The name used to display the switch in the frontend. -- **type** (*Required for some models*): Switch type. Choose one from: `rm`, `rm2`, `rm_mini`, `rm_pro_phicomm`, `rm2_home_plus`, `rm2_home_plus_gdt`, `rm2_pro_plus`, `rm2_pro_plus2`, `rm2_pro_plus_bl`, `rm_mini_shate`, `sp1`, `sp2`, `honeywell_sp2`, `sp3`, `spmini2`, `spminiplus` or `mp1`. +- **type** (*Required for some models*): Switch type. Choose one from: `rm`, `rm2`, `rm_mini`, `rm_pro_phicomm`, `rm2_home_plus`, `rm2_home_plus_gdt`, `rm2_pro_plus`, `rm2_pro_plus2`, `rm2_pro_plus_bl`, `rm_mini_shate`, `sp1`, `sp2`, `honeywell_sp2`, `sp3`, `spmini2`, `spminiplus` or `mp1`. `SC1` devices can be registered as `sp2`. - **switches** (*Optional*): The array that contains all switches. - **identifier** (*Required*): Name of the command switch as slug. Multiple entries are possible. - **friendly_name** (*Optional*): The name used to display the switch in the frontend. diff --git a/source/_components/switch.rfxtrx.markdown b/source/_components/switch.rfxtrx.markdown index 52b58ab4a66..b1ef272d1a0 100644 --- a/source/_components/switch.rfxtrx.markdown +++ b/source/_components/switch.rfxtrx.markdown @@ -54,6 +54,10 @@ Configuration variables: This component and the [rfxtrx binary sensor](/components/binary_sensor.rfxtrx/) can steal each other's devices when setting the `automatic_add` configuration parameter to `true`. Set `automatic_add` only when you have some devices to add to your installation, otherwise leave it to `False`. ++If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
Generate codes: @@ -101,10 +105,10 @@ switch: devices: 0710014c440f0160: name: Hall - 0710010244080780: + "0710010244080780": name: Door fire_event: true - + automation: - alias: Switch light on when door bell rings if sun is below horizon and light was off trigger: @@ -145,7 +149,7 @@ scene: entities: switch.light1: on switch.light2: on - + automation: - alias: Use remote to enable scene trigger: diff --git a/source/_docs/installation/raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown index d021e7041a0..0ee8868207c 100644 --- a/source/_docs/installation/raspberry-pi.markdown +++ b/source/_docs/installation/raspberry-pi.markdown @@ -49,10 +49,10 @@ $ sudo apt-get install python3 python3-venv python3-pip ``` Add an account for Home Assistant called `homeassistant`. -Since this account is only for running Home Assistant the extra arguments of `-rm` is added to create a system account and create a home directory. The arguments `-G dialout` adds the user to the `dialout` group. This is required for using Z-Wave and Zigbee controllers. +Since this account is only for running Home Assistant the extra arguments of `-rm` is added to create a system account and create a home directory. The arguments `-G dialout,gpio` adds the user to the `dialout` and the `gpio` group. The first is required for using Z-Wave and Zigbee controllers, while the second is required to communicate with Raspberry's GPIO. ```bash -$ sudo useradd -rm homeassistant -G dialout +$ sudo useradd -rm homeassistant -G dialout,gpio ``` Next we will create a directory for the installation of Home Assistant and change the owner to the `homeassistant` account. diff --git a/source/_docs/installation/windows.markdown b/source/_docs/installation/windows.markdown index 7a6017c9ae1..3efe0581137 100644 --- a/source/_docs/installation/windows.markdown +++ b/source/_docs/installation/windows.markdown @@ -15,6 +15,8 @@ To run Home Assistant on Microsoft Windows installation you need to install Pyth There may be alpha or beta releases of Python listed on that download page (marked by the letters `a` or `b` in the version number. Do not use these versions. +If you use your machine for something other than Home Assistant, you should install it in a [Python virtual environment](#Installing_in_a_Python_virtual_environment). + Start ```bash @@ -39,3 +41,27 @@ C:\...\> pip3 install --upgrade homeassistant ``` Then start Home Assistant. + +## {% linkable_title Installing in a Python virtual environment %} + +Open `cmd.exe` and paste the following commands (one at the time): + +```bash +C:\...\> py -m venv homeassistant +C:\...\> cd homeassistant +C:\...\> Scripts\activate.bat +C:\...\> py -m pip install wheel setuptools pip +C:\...\> py -m pip install homeassistant +C:\...\> hass +``` + +## {% linkable_title Upgrading in a Python virtual environment %} + +To update Home Assistant, stop it and then open `cmd.exe` and paste the following commands (one at the time): + +```bash +C:\...\> cd homeassistant +C:\...\> Scripts\activate.bat +C:\...\> py -m pip install --upgrade homeassistant +``` +Then start Home Assistant. diff --git a/source/_includes/asides/lovelace_navigation.html b/source/_includes/asides/lovelace_navigation.html new file mode 100644 index 00000000000..fd19a6462df --- /dev/null +++ b/source/_includes/asides/lovelace_navigation.html @@ -0,0 +1,22 @@ +
+
+The new picture elements card.
+
The minimum supported version of Home Assistant is 0.65.6.
@@ -19,8 +18,10 @@ The Google Assistant integration allows users to control the entities via the Ho To use this integration, you need to have: - The cloud component set up. [Learn more](/components/cloud/) - - A Google Assistant enabled device like the Google Home - - Activated the Home Assistant Smart Home skill for Google Assistant by using the Google Home app, select *Home control*, and then add *hass.io* using the *Add devices* option. + - A Google Assistant enabled device like the Google Home or a mobile phone running Google Assistant. + - Activated the Home Assistant Smart Home skill for Google Assistant. + - If you have a Google Home device, use the Google Home app, select *Home control*, and then add *hass.io* using the *Add devices* option. + - If you only have a mobile phone, launch Google Assistant, select the three dots menu. Under *Settings* you'll find *Home Control*. There you can add *hass.io* using the *Add devices* option. You can use `configuration.yaml` to configure the entities that are being shown to Google Assistant and how they are exposed. @@ -73,7 +74,7 @@ google_actions: required: false type: list entity_config: - description: Entity specific configuration for Google Assistant + description: Entity specific configuration for Google Assistant. required: false type: map keys: @@ -83,11 +84,11 @@ google_actions: type: map keys: name: - description: Name of entity to show in Google Assistant + description: Name of entity to show in Google Assistant. required: false type: string aliases: - description: Aliases that can also be used to refer to this entity + description: Aliases that can also be used to refer to this entity. required: false type: list room: diff --git a/source/developers/documentation/create_page.markdown b/source/developers/documentation/create_page.markdown index cb0c4125198..a21303179c8 100644 --- a/source/developers/documentation/create_page.markdown +++ b/source/developers/documentation/create_page.markdown @@ -9,119 +9,6 @@ sharing: true footer: true --- -For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](/components/) and the [Examples section](/cookbook/) are generated automatically, so there is no need to add a link to those pages. - -Please honor the [Standards](/developers/documentation/standards/) we have for the documentation. - -If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers. - -```text ---- -layout: page -title: "Awesome Sensor" -description: "home-assistant.io web presence" -date: 2015-06-17 08:00 -sidebar: true -comments: false -sharing: true -footer: true -ha_release: "0.38" -ha_category: Sensor ---- - -Content...Written in markdown. - -{% raw %}### {% linkable_title Linkable Header %}{% endraw %} -... -``` - -There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation. - -A couple of points to remember: - -- Document the needed steps to retrieve API keys or access token for the third party service or device if needed. -- If you're adding a new component, for the `ha_release` part of the header, just increment of the current release. If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`. -- `ha_category:` is needed to list the platform or component in the appropriate category on the website. - -### {% linkable_title Configuration %} - -Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file. - -The **Configuration Variables** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag. - -{% raw %} -```text -{% configuration %} -api_key: - description: The API key to access the service. - required: true - type: string -name: - description: Name to use in the frontend. - required: false - default: The default name to use in the frontend. - type: string -monitored_conditions: - description: Conditions to display in the frontend. - required: true - type: list - keys: - weather: - description: A human-readable text summary. - temperature: - description: The current temperature. -{% endconfiguration %} - -``` -{% endraw %} - -Available keys: - -- **`description:`**: That the variable is about. -- **`required:`**: If the variable is required. -```text -required: true #=> Required -required: false #=> Optional -required: inclusive #=> Inclusive -required: exclusive #=> Exclusive -required: any string here #=> Any string here -``` -- **`type:`**: The type of the variable. Allowed entries: `string`, `int`, `time`, `template` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example). -- **`default:`**: The default value for the variable. - -### {% linkable_title Embedding Code %} - -You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in {% raw %}`{% endraw %}. - -When you're writing code that is to be executed on the terminal, prefix it with `$`. - -### {% linkable_title Templates %} - -For the [configuration templating](/topics/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](/developers/documentation/standards/) for further details. - -If you are don't escape templates then they will be rendered and appear blank on the website. - -### {% linkable_title HTML %} - -The direct usage of HTML is supported but not recommended. The note boxes are an exception. - -```html -- You need to enable telnet on your router. -
-``` - -### {% linkable_title Images, icons, and logos %} - -The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent. - -| Type | Location | -| :----------- |:----------------------------------------------| -| logos | source/images/supported_brands | -| blog | source/images/blog | -| screenshots | source/images/components | - -Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). - -### {% linkable_title Linking From The Sidebar %} -If you are adding a new page that requires linking from the sidebar you need to edit the `docs_navigation.html` file in `home-assistant.github.io/source/_includes/asides/docs_navigation.html`. + diff --git a/source/developers/documentation/index.markdown b/source/developers/documentation/index.markdown index c6b1ee6fb4f..aed589d8a3e 100644 --- a/source/developers/documentation/index.markdown +++ b/source/developers/documentation/index.markdown @@ -10,35 +10,6 @@ footer: true redirect_from: /developers/website/ --- -The website you are reading now is the home of Home Assistant: [https://www.home-assistant.io](/). This is the place where we provide documentation and additional details about Home Assistant for end users and developers. - -The [home-assistant.io](/) website is built using [Jekyll](http://github.com/mojombo/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know about HTML. - -You can use the "**Edit this page on GitHub**" link to edit pages without creating a fork. Keep in mind that you can't upload images while working this way. - -For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a Pull Request (PR). - -To test your changes locally, you need to install **Ruby** and its dependencies (gems): - -- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. Ruby version 2.3.0 or higher is required. -- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler` -- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need. - -Shortcut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle` - -Then you can work on the documentation: - -- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.github.io). -- Create/edit/update a page in the directory `source/_components/` for your platform/component. -- Test your changes to home-assistant.io locally: run `rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000) -- Create a Pull Request (PR) against the **next** branch of home-assistant.github.io if your documentation is a new feature, platform, or component. -- Create a Pull Request (PR) against the **current** branch of home-assistant.github.io if you fix stuff, create Cookbook entries, or expand existing documentation. - --It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview. -
--Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding: -`ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine` -
- + diff --git a/source/developers/documentation/standards.markdown b/source/developers/documentation/standards.markdown index 05b1223cc61..5ef543344ac 100644 --- a/source/developers/documentation/standards.markdown +++ b/source/developers/documentation/standards.markdown @@ -9,113 +9,6 @@ sharing: true footer: true --- -To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation. - -## {% linkable_title General Documentation %} - -* The language of the documentation should be American-English. -* Don't put two spaces after a period and avoid the "Oxford comma". -* Be objective and not gender favoring, polarizing, race related or religion inconsiderate. -* The case of brand names, services, protocols, components, and platforms must match its respective counterpart. e.g., "Z-Wave" **not** "Zwave", "Z-wave", "Z Wave" or "ZWave". Also, "Input Select" **not** "input select" or "Input select". -* All headings should use the {% raw %}`{% linkable_title %}`{% endraw %} tag. - -## {% linkable_title Component and Platform Pages %} - -* The **Configuration Variables** section must use the {% raw %}`{% configuration %}`{% endraw %} tag. -* Configuration variables must document the requirement status. -* Configuration variables must document the default value, if any. -* Configuration variables must document the accepted value types. - * For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, int`). -* Use YAML sequence syntax in the sample code if it is supported. -* All examples should be formatted to be included in `configuration.yaml` unless explicitly stated. - * Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`. - * If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note. -* Component and platform names should be a link to their respective documentation pages. - -## {% linkable_title Templates %} - -* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the {% raw %}`{% raw %}`{% endraw %} tag. -* Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`. -* Use double quotes (`"`) for ([more information](#single-vs-double-quotation-marks)): - * `friendly_name` - * Single-line templates: - * `value_template` - * `level_template` - * `icon_template` - * Children of `data_template` -* Use single quotes (`'`) for ([more information](#single-vs-double-quotation-marks): - * Strings inside of templates: - * States - * Entity IDs - * `unit_of_measurement` -* No whitespace around pipe character (`|`) for Jinja2 filters. -* Single whitespace after Jinja2 opening delimiters ({% raw %}`{{`{% endraw %}). -* Single whitespace before Jinja2 closing delimiters ({% raw %}`}}`{% endraw %}). -* Do not quote values for: - * `device_class` - * `platform` - * `condition` - * `service` - -## {% linkable_title Renaming Pages %} - -It can happen that a component or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add `redirect_from:` to the file header and let it point to the old location/name of the page. Please consider to add details, like release number or old component/platform name, to the page in a [note](/developers/documentation/create_page/#html). - -```text ---- -... -redirect_from: /getting-started/android/ ---- -``` - -Adding a redirect also applies if you move content around in the [documentation](/docs/). - -## {% linkable_title Single vs. Double Quotation Marks %} - -Use single quotes (`'`) for strings inside of a template. It is more obvious to escape a single quote when necessary (i.e. `name` is a possessive noun), because the single quotes that wrap the string are closer in position to the apostrophe inside the string. Use double quotes (`"`) outside of a template (unless it is a multi-line template, in which case outside quotes are not required). - -### {% linkable_title Examples %} - -#### {% linkable_title Double Quotes Outside, Single Quotes Inside (Valid) %} - -{% raw %} -```yaml -automation: - ... - action: - - service: notify.notify - data_template: - message: "{% if trigger.to_state.name == 'Dale\'s Bedroom' %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}" -``` -{% endraw %} - -#### {% linkable_title Single Quotes Outside, Double Quotes Inside (Invalid) %} - -{% raw %} -```yaml -automation: - ... - action: - - service: notify.notify - data_template: - message: '{% if trigger.to_state.name == "Dale's Bedroom" %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}' -``` -{% endraw %} - -#### {% linkable_title Multi-Line Template (Valid) %} - -{% raw %} -```yaml -automation: - ... - action: - - service: notify.notify - data_template: - message: >- - {% if trigger.to_state.name == 'Dale\'s Bedroom' %} - Someone's in your base, killing your noobs! - {% else %} - It's just another door. - {% endif %} -``` -{% endraw %} + diff --git a/source/images/blog/2018-07-0.73/lovelace-elements.png b/source/images/blog/2018-07-0.73/lovelace-elements.png new file mode 100644 index 00000000000..64d18b6c323 Binary files /dev/null and b/source/images/blog/2018-07-0.73/lovelace-elements.png differ diff --git a/source/images/lovelace/lovelace-ui-comparison.png b/source/images/lovelace/lovelace-ui-comparison.png new file mode 100644 index 00000000000..1d79d98716b Binary files /dev/null and b/source/images/lovelace/lovelace-ui-comparison.png differ diff --git a/source/lovelace/index.markdown b/source/lovelace/index.markdown new file mode 100644 index 00000000000..f2b626a3dc3 --- /dev/null +++ b/source/lovelace/index.markdown @@ -0,0 +1,107 @@ +--- +layout: page +title: "Lovelace UI" +description: "The Lovelace UI is a powerful and configurable interface for Home Assistant." +date: 2018-07-01 10:28 +00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + ++This is an experimental feature. Configuration might change in future versions. +
+ +Starting with Home Assistant 0.72, we're experimenting with a new way of defining your interface. We're calling it the Lovelace UI. + +The Lovelace UI is: + + - **Extremely fast**. We create the user interface when the UI configuration changes. When a state changes, we just make the UI represent the current state. + - **Extremely customizable**. We have a new file for just configuration. In the past, we declined UI specific options because they did not fit in the state machine. They will fit in a configuration file for a user interface. + - **Extremely extensible**. It's based on the web standard [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Don't like the built-in cards? Make your own! Custom cards are treated the same as built-in cards and are configured the same way. [Check the docs.](lovelace_custom_card.md) + - **Making the backend faster**. With Lovelace, the backend will no longer need to maintain entities like groups for the sole purpose of showing them on the frontend. + +## How it works + +The old user interface relied solely on the state machine. This caused trouble as it meant that the state machine was now not only the source for device states, but also for user interface configuration. With Lovelace, we're taking a completely different approach. All user interface configuration will live in a seperate file, controlled by the user. + +
+
+Visual comparison of old configuration versus new configuration
+