diff --git a/docs/add_new_platform.md b/docs/add_new_platform.md index e0882296..9823bc9f 100644 --- a/docs/add_new_platform.md +++ b/docs/add_new_platform.md @@ -1,12 +1,6 @@ --- layout: page title: "Adding support for a new platform" -description: "Hints and tips for when you're adding a new platform to Home Assistant." -date: 2014-12-21 13:27 -sidebar: true -comments: false -sharing: true -footer: true --- Components that interact with devices are called "[Entity Components](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity_component.py)." They are structured in core and platform logic, which means different brands can use the same logic to handle a light. @@ -18,13 +12,13 @@ If you're planning to add support for a new type of device to an existing compon - [Example sensor platform](/developers/platform_example_sensor): hello world of platforms. - [Example light platform](/developers/platform_example_light): showing best practices. -### {% linkable_title Interfacing with devices %} +### Interfacing with devices One Home Assistant rule is that platform logic should never interface directly with devices. Instead, use a third-party Python 3 library. This way, Home Assistant can share code with the Python community and keep the project maintainable. To integrate the third-party library, create an [Entity class](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity.py) for your device. Entities are Home Assistant's representations of lights, switches, sensors, etc. and are derived from the [Entity Abstract Class](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py). This abstract class contains logic for integrating most standard features into your entities, such as visibility, entity IDs, updates, and much more. -### {% linkable_title Requirements and dependencies %} +### Requirements and dependencies Platforms can specify dependencies and requirements [the same way as components](/developers/component_deps_and_reqs): diff --git a/docs/architecture.md b/docs/architecture.md index 191ed65f..e4164f17 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,13 +1,6 @@ --- layout: page title: "Architecture" -description: "Overview of the Home Assistant architecture." -date: 2014-12-18 21:49 -sidebar: true -comments: false -sharing: true -footer: true -og_image: /images/architecture/ha_architecture.svg --- Before we dive into the Home Assistant architecture, let's get a clear overview of the home automation landscape as a whole. This way, we can show how the different parts of Home Assistant fit into the picture. diff --git a/docs/architecture_components.md b/docs/architecture_components.md index ac05c93b..39aa71a6 100644 --- a/docs/architecture_components.md +++ b/docs/architecture_components.md @@ -1,13 +1,6 @@ --- layout: page title: "Components Architecture" -description: "Overview of components within the Home Assistant architecture." -date: 2016-04-16 14:24 -07:00 -sidebar: true -comments: false -sharing: true -footer: true -og_image: /images/architecture/component_interaction.png --- Home Assistant can be extended with **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services, and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/). @@ -19,7 +12,7 @@ Diagram showing interaction between components and the Home Assistant core There are two types of components within Home Assistant: components that interact with an Internet of Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type! -#### {% linkable_title Components that interact with an Internet-of-Things domain %} +#### Components that interact with an Internet-of-Things domain These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices. @@ -27,7 +20,7 @@ For example, the built-in [`switch` component](/components/switch/) is responsib If you want to add support for a new platform, check out the [add new platform section](/developers/add_new_platform/). -#### {% linkable_title Components that respond to events that happen within Home Assistant %} +#### Components that respond to events that happen within Home Assistant These components provide small pieces of home automation logic or involve services that do common tasks within your house. @@ -53,7 +46,7 @@ In the event of the sun setting: Look [here](/python_component_automation/) for a comprehensive example of a home automation component. -### {% linkable_title The full picture %} +### The full picture When we put all the different pieces of Home Assistant together, it's a close match for the initial home automation overview sketch. The smart home AI has not been implemented yet, so it's not included in this picture. diff --git a/docs/asyncio.md b/docs/asyncio.md index 2a456794..25727532 100644 --- a/docs/asyncio.md +++ b/docs/asyncio.md @@ -1,12 +1,6 @@ --- layout: page title: "Asynchronous Programming" -description: "Introduction to the asynchronous core of Home Assistant." -date: 2016-10-17 21:49 -sidebar: true -comments: false -sharing: true -footer: true --- On September 29, 2016 we released [Home Assistant 0.29][0.29] as part of our bi-weekly release schedule. This release introduced a complete overhaul of the core spearheaded by [Ben Bangert][ben]. diff --git a/docs/asyncio_101.md b/docs/asyncio_101.md index c8826511..43076143 100644 --- a/docs/asyncio_101.md +++ b/docs/asyncio_101.md @@ -1,12 +1,6 @@ --- layout: page title: "Asyncio 101" -description: "An introduction to asyncio." -date: 2017-04-08 21:49 -sidebar: true -comments: false -sharing: true -footer: true --- If you are not familiar yet with asyncio, please watch the below video. It's a great introduction by [Robert Smallshire][rob] in how and why asyncio works the way it does. diff --git a/docs/asyncio_categorizing_functions.md b/docs/asyncio_categorizing_functions.md index 6fe74ad3..c43bffe4 100644 --- a/docs/asyncio_categorizing_functions.md +++ b/docs/asyncio_categorizing_functions.md @@ -1,19 +1,13 @@ --- layout: page title: "Categorizing Functions" -description: "A categorization of functions to work with the asynchronous core of Home Assistant." -date: 2016-10-17 21:49 -sidebar: true -comments: false -sharing: true -footer: true --- A piece of work within Home Assistant is represented by a function that will be invoked. It will either run inside our event loop or inside our thread pool, depending on if it is async safe. Home Assistant uses the convention that all functions that must be run from within the event loop are prefixed with `async_`. -## {% linkable_title The coroutine function %} +## The coroutine function Coroutines are special functions based on Python’s generators syntax which allows them to suspend execution while waiting on a result. @@ -35,7 +29,7 @@ hass.loop.create_task(async_look_my_coroutine("world")) In this example, we schedule the coroutine by calling `hass.loop.create_task`. This will add the coroutine to the queue of tasks to be run. When the event loop is running `async_look_my_coroutine` it will suspend the task when `yield from entity.async_turn_on()` is called. At that point a new task will be scheduled to execute `entity.async_turn_on()`. When that job has been executed, `async_look_my_coroutine` will resume. -## {% linkable_title The callback function %} +## The callback function This is a normal function that is considered safe to be run from within the event loop. A callback is unable to suspend itself and thus cannot do any I/O or call a coroutine. A callback is capable of scheduling a new task but it will not be able to wait for the results. @@ -58,19 +52,19 @@ In this example, `entity.async_trigger` is a coroutine function. Invoking the co To execute the task we have to schedule it for execution on the event loop. This is done by calling `hass.loop.create_task`. -### {% linkable_title Why even have callbacks? %} +### Why even have callbacks? You might wonder, if a coroutine can do everything a callback can do, why even have a callback. The reason is performance and better state consistency of the core API objects. When coroutine A waits for coroutine B, it will suspend itself and schedule a new task to run B. This means that the event loop is now running A, B and then A again. If B is a callback, A will never have to suspend itself and thus the event loop is just running A. The consistency implication is that other events queued to run on the event loop continue to wait until callbacks complete, but will be interleaved when yielding to another coroutine. -## {% linkable_title Event loop and thread safe %} +## Event loop and thread safe These are functions that are safe to run both in a thread and inside the event loop. These functions are usually performing a computation or transform data in memory. Anything that does I/O does not fall under this category. Many standard library functions fall in this category. For example generating the sum of a set of numbers using sum or merging two dictionaries. There is no special annotation to mark functions as part of this category and care should be taken when using these functions from inside the event loop. When in doubt, look at their implementation. -## {% linkable_title Other functions %} +## Other functions These are all the functions that did not fit in the previous categories. These functions are either thread-safe or not considered safe to be run within the event loop. These are functions that use sleep, or perform I/O. diff --git a/docs/asyncio_misc.md b/docs/asyncio_misc.md index 3fbc923c..7814393c 100644 --- a/docs/asyncio_misc.md +++ b/docs/asyncio_misc.md @@ -1,20 +1,14 @@ --- layout: page title: "Miscellaneous Async" -description: "A collection of miscellaneous topics about async that didn't fit on the other pages." -date: 2016-10-17 21:49 -sidebar: true -comments: false -sharing: true -footer: true --- -## {% linkable_title What about ‘async’ and ‘await’ syntax? %} +## What about ‘async’ and ‘await’ syntax? Python 3.5 introduced new syntax to formalize the asynchronous pattern. This is however not compatible with Python 3.4. The minimum required Python version for Home Assistant is based on the Python version shipped with Debian stable, which is currently 3.5.3. For more information, Brett Cannon wrote [an excellent breakdown][brett] on 'async' and 'await' syntax and how asynchronous programming works. -## {% linkable_title Acknowledgements %} +## Acknowledgements Huge thanks to [Ben Bangert][ben] for starting the conversion of the core to async, guiding other contributors while taking their first steps with async programming and peer reviewing this documentation. diff --git a/docs/asyncio_working_with_async.md b/docs/asyncio_working_with_async.md index 40fd82b2..f1eeee7e 100644 --- a/docs/asyncio_working_with_async.md +++ b/docs/asyncio_working_with_async.md @@ -1,23 +1,17 @@ --- layout: page title: "Working with Async" -description: "A breakdown of all the different ways to work with the asynchronous core of Home Assistant." -date: 2016-10-17 21:49 -sidebar: true -comments: false -sharing: true -footer: true --- Although we have a backwards compatible API, using the async core directly will be a lot faster. Most core components have already been rewritten to leverage the async core. This includes the EntityComponent helper (foundation of light, switch, etc), scripts, groups and automation. -## {% linkable_title Interacting with the core %} +## Interacting with the core [All methods in the Home Assistant core][dev-docs] are implemented in two flavors: an async version and a version to be called from other threads. The versions for other are merely wrappers that call the async version in a threadsafe manner using [the available async utilities][dev-docs-async]. So if you are making calls to the core (the hass object) from within a callback or coroutine, use the methods that start with async_. If you need to call an async_ function that is a coroutine, your task must also be a coroutine. -## {% linkable_title Implementing an async component %} +## Implementing an async component To make a component async, implement an async_setup. @@ -36,7 +30,7 @@ def async_setup(hass, config): # Setup your component inside of the event loop. ``` -## {% linkable_title Implementing an async platform %} +## Implementing an async platform For platforms we support async setup. Instead of setup_platform you need to have a coroutine async_setup_platform. @@ -58,7 +52,7 @@ def async_setup_platform(hass, config, async_add_entities, The only difference with the original parameters is that the `add_entities` function has been replaced by the async friendly callback `async_add_entities`. -## {% linkable_title Implementing an async entity %} +## Implementing an async entity You can make your entity async friendly by converting your update method to be async. This requires the dependency of your entities to also be async friendly! @@ -83,7 +77,7 @@ class MyEntity(Entity): Make sure that all properties defined on your entity do not result in I/O being done. All data has to be fetched inside the update method and cached on the entity. This is because these properties are read from within the event loop and thus doing I/O will result in the core of Home Assistant waiting until your I/O is done. -## {% linkable_title Calling async functions from threads %} +## Calling async functions from threads Sometimes it will happen that you’re in a thread and you want to call a function that is only available as async. Home Assistant includes a few async helper utilities to help with this. @@ -100,13 +94,13 @@ def async_say_hello(hass, target): return "Hello {}!".format(target) ``` -## {% linkable_title Dealing with passed in functions %} +## Dealing with passed in functions If your code takes in functions from other code, you will not know which category the function belongs to and how they should be invoked. This usually only occurs if your code supplies an event helper like `mqtt.async_subscribe` or `track_state_change_listener`. To help with this, there are two helper methods on the hass object that you can call from inside the event loop: -#### {% linkable_title hass.async_run_job %} +#### hass.async_run_job Use this method if the function should be called as soon as possible. This will call callbacks immediately, schedule coroutines for execution on the event loop and schedule other functions to be run inside the thread pool. @@ -114,7 +108,7 @@ Use this method if the function should be called as soon as possible. This will | Coroutine | Schedule for execution on the event loop. | Other functions | Schedule for execution in the thread pool. -#### {% linkable_title hass.async_add_job %} +#### hass.async_add_job Use this method if the function should be called but not get priority over already scheduled calls. diff --git a/docs/code_review_component.md b/docs/code_review_component.md index bebe3dc7..f5a2d7ce 100644 --- a/docs/code_review_component.md +++ b/docs/code_review_component.md @@ -1,12 +1,6 @@ --- layout: page title: "Checklist for creating a component" -description: "A list of things to pay attention to when code reviewing a component." -date: 2017-01-15 14:09 -0800 -sidebar: true -comments: false -sharing: true -footer: true --- A checklist of things to do when you're adding a new component. @@ -15,13 +9,13 @@ A checklist of things to do when you're adding a new component. Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them!

-### {% linkable_title 1. Requirements %} +### 1. Requirements 1. Requirement version pinned: `REQUIREMENTS = ['phue==0.8.1']` 2. We no longer want requirements hosted on GitHub. Please upload to PyPi. 3. Requirements should only be imported inside functions. This is necessary because requirements are installed on the fly. -### {% linkable_title 2. Configuration %} +### 2. Configuration 1. Voluptuous schema present for config validation 2. Default parameters specified in voluptuous schema, not in `setup(…)` @@ -30,7 +24,7 @@ Not all existing platforms follow the requirements in this checklist. This canno 5. If using a `PLATFORM_SCHEMA` to be used with `EntityComponent`, import base from `homeassistant.helpers.config_validation` 6. Never depend on users adding things to `customize` to configure behavior inside your component. -### {% linkable_title 3. Component/platform communication %} +### 3. Component/platform communication 1. If you need to share global data with platforms, use the dictionary `hass.data`. `hass.data[DATA_XY]` while `XY` is the component is preferred over `hass.data[DOMAIN]`. 2. If the component fetches data that causes its related platform entities to update, you can notify them using the dispatcher code in `homeassistant.helpers.dispatcher`. diff --git a/docs/code_review_platform.md b/docs/code_review_platform.md index 00ab599c..564ffca2 100644 --- a/docs/code_review_platform.md +++ b/docs/code_review_platform.md @@ -1,12 +1,6 @@ --- layout: page title: "Checklist for creating a platform" -description: "A list of things to pay attention to when code reviewing a platform." -date: 2017-01-15 14:09 -0800 -sidebar: true -comments: false -sharing: true -footer: true --- A checklist of things to do when you're adding a new platform. @@ -15,17 +9,17 @@ A checklist of things to do when you're adding a new platform. Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them!

-### {% linkable_title 1. Requirements %} +### 1. Requirements 1. Requirement version should be pinned: `REQUIREMENTS = ['phue==0.8.1']` 2. We no longer want requirements hosted on GitHub. Please upload to PyPi. 3. Requirements should only be imported inside functions. This is necessary because requirements are installed on the fly. -### {% linkable_title 2. Dependencies %} +### 2. Dependencies 1. If you depend on a component for the connection, add it to your dependencies: `DEPENDENCIES = ['nest']` -### {% linkable_title 3. Configuration %} +### 3. Configuration 1. Voluptuous schema present for config validation 2. Voluptuous schema extends schema from component
(e.g., `light.hue.PLATFORM_SCHEMA` extends `light.PLATFORM_SCHEMA`) @@ -50,20 +44,20 @@ Not all existing platforms follow the requirements in this checklist. This canno ``` 5. Never depend on users adding things to `customize` to configure behavior inside your platform. -### {% linkable_title 4. Setup Platform %} +### 4. Setup Platform 1. Test if passed in info (user/pass/host etc.) works. 2. Group your calls to `add_devices` if possible. 3. If platform adds extra services, format should be `._`. -### {% linkable_title 5. Entity %} +### 5. Entity 1. Extend entity from component, e.g., `class HueLight(Light)` 2. Do not call `update()` in constructor, use `add_devices(devices, True)` instead. 3. Do not do any I/O inside properties. Cache values inside `update()` instead. 4. The state and/or attributes should not contain relative time since something happened. Instead it should store UTC timestamps. -### {% linkable_title 6. Communication with devices/services %} +### 6. Communication with devices/services 1. All API specific code has to be part of a third party library hosted on PyPi. Home Assistant should only interact with objects and not make direct calls to the API. diff --git a/docs/component_deps_and_reqs.md b/docs/component_deps_and_reqs.md index 2a6ae27d..b9049f71 100644 --- a/docs/component_deps_and_reqs.md +++ b/docs/component_deps_and_reqs.md @@ -1,17 +1,11 @@ --- layout: page title: "Requirements & Dependencies" -description: "Instructions on how to define requirements and dependencies." -date: 2016-04-16 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant allows components and platforms to specify their dependencies and requirements using the variables `DEPENDENCIES` and `REQUIREMENTS`. Both are lists that contain strings. -## {% linkable_title Dependencies %} +## Dependencies Dependencies are other Home Assistant components that should be setup before the platform is loaded. An example is the MQTT sensor component, which requires an active connection to an MQTT broker. If Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor component. @@ -19,7 +13,7 @@ Dependencies are other Home Assistant components that should be setup before the DEPENDENCIES = ['mqtt'] ``` -## {% linkable_title Requirements %} +## Requirements Requirements are Python libraries or modules that you would normally install using `pip` for your component. Home Assistant will try to install the requirements into the `deps` subdirectory of the Home Assistant [configuration directory](/docs/configuration/) if you are not using a `venv` or in something like `path/to/venv/lib/python3.6/site-packages` if you running in a virtual environment. This will make sure that all requirements are present at startup. If steps fails like missing packages for the compilation of a module or other install errors, the component will fail to load. diff --git a/docs/component_discovery.md b/docs/component_discovery.md index 2911adaa..631fc223 100644 --- a/docs/component_discovery.md +++ b/docs/component_discovery.md @@ -1,12 +1,6 @@ --- layout: page title: "Component Discovery" -description: "How to make component discovery work." -date: 2017-11-23 07:27 +02:00 -sidebar: true -comments: false -sharing: true -footer: true ---

@@ -15,13 +9,13 @@ This option is only available for built-in components. Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, a `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event. -### {% linkable_title Add discovery instructions %} +### Add discovery instructions Device discovery for Home Assistant has been extracted into an external library called [NetDisco](https://github.com/home-assistant/netdisco). This library is integrated using [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py) and scans the network in intervals for uPnP and zeroconf/mDNS services. To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. [See the repository for examples of existing discoverable.](https://github.com/home-assistant/netdisco/tree/master/netdisco/discoverables) -### {% linkable_title Listening to `SERVICE_DISCOVERED` events %} +### Listening to `SERVICE_DISCOVERED` events From your component, you will have to set up the listening for specific services. Given below is an example how one would listen for a discovered AwesomeDevice: @@ -46,7 +40,7 @@ def setup(hass, config): return True ``` -### {% linkable_title Auto-loading your component upon discovery %} +### Auto-loading your component upon discovery The `discovery` component is capable of setting up your components before firing the `EVENT_PLATFORM_DISCOVERED` event. To do this you will have to update the [`SERVICE_HANDLERS`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L40) constant in [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py): diff --git a/docs/component_events.md b/docs/component_events.md index ee2e281b..ce07a9de 100644 --- a/docs/component_events.md +++ b/docs/component_events.md @@ -1,12 +1,6 @@ --- layout: page title: "Handling events" -description: "Instructions on how to handle events with your component." -date: 2016-04-16 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in [helper methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/event.py). Examples are `track_state_change`, `track_point_in_time`, `track_time_change`. diff --git a/docs/component_generic_discovery.md b/docs/component_generic_discovery.md index 8eacc22f..bba6039d 100644 --- a/docs/component_generic_discovery.md +++ b/docs/component_generic_discovery.md @@ -1,12 +1,6 @@ --- layout: page title: "Generic Platform Discovery" -description: "Using generic platform discovery." -date: 2016-05-12 22:00 -02:00 -sidebar: true -comments: false -sharing: true -footer: true --- New controller or hub components often need to add platforms in sub-components (i.e. Lights & Switches) without additional configuration. @@ -18,7 +12,7 @@ def load_platform(hass, component, platform, discovered=None, hass_config=None) From more info on how this works, refer to the [load_platform](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/discovery.py#L136) method. -### {% linkable_title Example %} +### Example Say you need to implement your new MyFlashyHub that controls both Switches & Lights, you can follow these steps: @@ -59,7 +53,7 @@ Add your custom device specific code to the `setup_platform` method in `light/my ```python import custom_components.myflashyhub as myflashyhub -# 'switch' will receive discovery_info={'optional': 'arguments'} +# 'switch' will receive discovery_info={'optional': 'arguments'} # as passed in above. 'light' will receive discovery_info=None def setup_platform(hass, config, add_devices, discovery_info=None): """Your switch/light specific code.""" diff --git a/docs/component_loading.md b/docs/component_loading.md index b817fadf..6cb20107 100644 --- a/docs/component_loading.md +++ b/docs/component_loading.md @@ -1,12 +1,6 @@ --- layout: page title: "Loading your components" -description: "Instructions on how to get your component loaded by Home Assistant." -date: 2016-04-16 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- A component will be loaded on start if a section (ie. `light:`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths: diff --git a/docs/component_states.md b/docs/component_states.md index f8980369..375d2588 100644 --- a/docs/component_states.md +++ b/docs/component_states.md @@ -1,12 +1,6 @@ --- layout: page title: "Handling states" -description: "Instructions on how to handle states with your component." -date: 2016-07-01 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- It is the responsibility of the component to maintain the states of the devices in your domain. Each device should be a single state and, if possible, a group should be provided that tracks the combined state of the devices. diff --git a/docs/creating_components.md b/docs/creating_components.md index f52629db..c6e556fb 100644 --- a/docs/creating_components.md +++ b/docs/creating_components.md @@ -1,17 +1,11 @@ --- layout: page title: "Creating components" -description: "Guidelines to get you create your first component for Home Assistant." -date: 2014-12-21 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- Alright, you're ready to make your first component. AWESOME. Don't worry, we've tried hard to keep it as easy as possible. -### {% linkable_title Example component %} +### Example component Add `hello_state:` to your `configuration.yaml` file and create a file `/custom_components/hello_state.py` with the below code to test it locally. diff --git a/docs/development.md b/docs/development.md index 8bc61429..505732b4 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,12 +1,6 @@ --- layout: page title: "Starting with Development" -description: "Everything to get you started developing for Home Assistant." -date: 2014-12-21 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant is built from the ground up to be easily extensible using components. Home Assistant uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend. @@ -16,7 +10,7 @@ Home Assistant is open-source and licensed under [Apache 2.0](http://www.apache. - [home-assistant](https://github.com/home-assistant/home-assistant): Python server backend. - [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer): Polymer UI. -For those new to contributing to open source software, make sure you are familiar with all of the tools and concepts used in Home Assistant before you start. +For those new to contributing to open source software, make sure you are familiar with all of the tools and concepts used in Home Assistant before you start. When contributing Home Assistant code: - [Github](https://guides.github.com/activities/hello-world/) diff --git a/docs/development_101.md b/docs/development_101.md index 5db0cdf1..d30799df 100644 --- a/docs/development_101.md +++ b/docs/development_101.md @@ -1,12 +1,6 @@ --- layout: page title: "Development 101" -description: "Introduction to the basics of Home Assistant." -date: 2017-05-13 05:40:00 +0000 -sidebar: true -comments: false -sharing: true -footer: true --- The goal of development 101 is to get you familiar with the basics of developing for Home Assistant. Before we start, please make sure you familiarize yourself with the [architecture]. diff --git a/docs/development_catching_up.md b/docs/development_catching_up.md index 88f4b73e..44bb32cc 100644 --- a/docs/development_catching_up.md +++ b/docs/development_catching_up.md @@ -1,12 +1,6 @@ --- layout: page title: "Catching up with Reality" -description: "Update your fork with the latest commit." -date: 2016-07-01 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- If it's taking a while to develop your feature, and you want to catch up with what's in the current Home Assistant `dev` branch, you can use `git rebase`. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant, and replay all of your commits on top. diff --git a/docs/development_checklist.md b/docs/development_checklist.md index 3fe199b8..07957cc5 100644 --- a/docs/development_checklist.md +++ b/docs/development_checklist.md @@ -1,12 +1,6 @@ --- layout: page title: "Development Checklist" -description: "Overview of the requirements for an improvement for Home Assistant." -date: 2016-07-01 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- diff --git a/docs/development_config.md b/docs/development_config.md index 56382ecb..0c1e6338 100644 --- a/docs/development_config.md +++ b/docs/development_config.md @@ -1,21 +1,15 @@ --- layout: page title: "Using Config" -description: "Introduction to the Config object in Home Assistant." -date: 2017-05-13 05:40:00 +0000 -sidebar: true -comments: false -sharing: true -footer: true --- Based on where you are in the code, `config` can mean various things. -### {% linkable_title On the hass object %} +### On the hass object On the hass object is an instance of the Config class. The Config class contains the users preferred units, the path to the config directory and which components are loaded. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.Config) -### {% linkable_title Config passed into component setup %} +### Config passed into component setup The `config` parameter passed to a component setup is a dictionary containing all of the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration. @@ -30,6 +24,6 @@ example: Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`. -### {% linkable_title Passed into platform setup %} +### Passed into platform setup The `config` parameter passed to a platform setup function is only the config for that specific platform. diff --git a/docs/development_environment.md b/docs/development_environment.md index b198bebb..2600220c 100644 --- a/docs/development_environment.md +++ b/docs/development_environment.md @@ -1,19 +1,13 @@ --- layout: page title: "Set up Development Environment" -description: "Set up your environment to start developing for Home Assistant." -date: 2014-12-21 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up. -### {% linkable_title Preparing your environment %} +### Preparing your environment -#### {% linkable_title Developing on Linux %} +#### Developing on Linux Install the core dependencies. @@ -33,7 +27,7 @@ Different distributions have different package installation mechanisms and somet Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](/developers/frontend/) section to learn more. -#### {% linkable_title Developing on Windows %} +#### Developing on Windows If you are using Windows as a development platform, make sure that you have the correct Microsoft [Visual C++ build tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) installed. The installation of the most requirements and validation using `tox` will fail if this is not done correctly. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. @@ -64,7 +58,7 @@ Also, make sure to install or upgrade the `setuptools` Python package. It contai $ pip install --upgrade setuptools ``` -#### {% linkable_title Developing on OS X %} +#### Developing on OS X Install [Homebrew](https://brew.sh/), then use that to install Python 3: @@ -72,7 +66,7 @@ Install [Homebrew](https://brew.sh/), then use that to install Python 3: $ brew install python3 ``` -### {% linkable_title Setup Local Repository %} +### Setup Local Repository Visit the [Home Assistant repository](https://github.com/home-assistant/home-assistant) and click **Fork**. Once forked, setup your local copy of the source using the commands: @@ -83,7 +77,7 @@ $ cd home-assistant $ git remote add upstream https://github.com/home-assistant/home-assistant.git ``` -### {% linkable_title Setting up virtual environment %} +### Setting up virtual environment To isolate your environment from the rest of the system, set up a [`venv`](https://docs.python.org/3/library/venv.html). Within the `home-assistant` directory, create and activate your virtual environment. @@ -103,7 +97,7 @@ Invoke your installation. $ hass ``` -### {% linkable_title Logging %} +### Logging By default logging in home-assistant is tuned for operating in production (set to INFO by default, with some modules set to even less verbose logging levels). diff --git a/docs/development_events.md b/docs/development_events.md index e078396f..95cce1f5 100644 --- a/docs/development_events.md +++ b/docs/development_events.md @@ -1,12 +1,6 @@ --- layout: page title: "Using Events" -description: "Introduction to using events in Home Assistant." -date: 2017-05-13 05:40:00 +0000 -sidebar: true -comments: false -sharing: true -footer: true --- The core of Home Assistant is driven by events. That means that if you want to respond to something happening, you'll have to respond to events. Most of the times you won't interact directly with the event system but use one of the [event listener helpers][helpers]. @@ -15,7 +9,7 @@ The event system is very flexible. There are no limitations on the event type, a [List of events that Home Assistant fires.][object] -### {% linkable_title Firing events %} +### Firing events To fire an event, you have to interact with the event bus. The event bus is available on the Home Assistant instance as `hass.bus`. @@ -33,7 +27,7 @@ def setup(hass, config): }) ``` -### {% linkable_title Listening to events %} +### Listening to events Most of the times you'll not be firing events but instead listen to events. For example, the state change of an entity is broadcasted as an event. @@ -54,7 +48,7 @@ def setup(hass, config): hass.bus.listen('my_cool_event', handle_event) ``` -#### {% linkable_title Helpers %} +#### Helpers Home Assistant comes with a lot of bundled helpers to listen to specific types of event. There are helpers to track a point in time, to track a time interval, a state change or the sun set. [See available methods.][helpers] diff --git a/docs/development_guidelines.md b/docs/development_guidelines.md index 7e408824..2ace2dca 100644 --- a/docs/development_guidelines.md +++ b/docs/development_guidelines.md @@ -1,12 +1,6 @@ --- layout: page title: "Style guidelines" -description: "Details about styling your code." -date: 2017-04-28 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant enforces strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/) compliance on all code submitted. We automatically test every pull request as part of the linting process with [Coveralls](https://coveralls.io/github/home-assistant/home-assistant) and [Travis CI](https://travis-ci.org/home-assistant/home-assistant). @@ -25,11 +19,11 @@ The maximum line length comes directly from the [PEP8 style guide](https://www.p Those points may require that you adjust your IDE or editor settings. -## {% linkable_title Our recommendations %} +## Our recommendations For some cases [PEPs](https://www.python.org/dev/peps/) don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code unified. -### {% linkable_title Quotes %} +### Quotes Use single quotes `'` for single word and `"` for multiple words or sentences. @@ -41,7 +35,7 @@ SENSOR_TYPES = { } ``` -### {% linkable_title File headers %} +### File headers The docstring in the file header should contain a link to the documentation to make it easy to find further information, especially about the configuration or details which are not mentioned in the code. @@ -54,7 +48,7 @@ https://home-assistant.io/components/light.mqtt/ """ ``` -### {% linkable_title Requirements %} +### Requirements Please place [Platform requirements](/developers/code_review_platform/#1-requirements) right after the imports. @@ -65,7 +59,7 @@ from homeassistant.helpers.entity import Entity REQUIREMENTS = ['xmltodict==0.11.0'] ``` -### {% linkable_title Log messages %} +### Log messages There is no need to add the platform or component name to the log messages. This will be added automatically. Like `syslog` messages there shouldn't be any period at the end. Try to avoid brackets and additional quotes around the output to make it easier for users to parse the log. A widely style is shown below but you are free to compose the messages as you like. diff --git a/docs/development_hass_object.md b/docs/development_hass_object.md index d4a5926d..a4d4994e 100644 --- a/docs/development_hass_object.md +++ b/docs/development_hass_object.md @@ -1,18 +1,11 @@ --- layout: page title: "Hass object" -description: "Introduction to developing with the hass object." -date: 2016-04-16 13:32 -sidebar: true -comments: false -sharing: true -footer: true -redirect_from: /developers/component_initialization/ --- While developing Home Assistant you will see a variable that is everywhere: `hass`. This is the Home Assistant instance that will give you access to all the various parts of the system. -### {% linkable_title The `hass` object %} +### The `hass` object The Home Assistant instance contains four objects to help you interact with the system. @@ -24,7 +17,7 @@ The Home Assistant instance contains four objects to help you interact with the | `hass.bus` | This is the EventBus. It allows you to trigger and listen for events. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.EventBus). | | `hass.services` | This is the ServiceRegistry. It allows you to register services. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.ServiceRegistry). | -### {% linkable_title Where to find `hass` %} +### Where to find `hass` Depending on what you're writing, there are different ways the `hass` object is made available. diff --git a/docs/development_services.md b/docs/development_services.md index 1aa11397..e9c504c6 100644 --- a/docs/development_services.md +++ b/docs/development_services.md @@ -1,12 +1,6 @@ --- layout: page title: "Using Services" -description: "Introduction to services in Home Assistant." -date: 2017-05-13 05:40:00 +0000 -sidebar: true -comments: false -sharing: true -footer: true --- This is a simple "hello world" example to show the basics of registering a service. To use this example, create the file `/custom_components/hello_service.py` and copy the below example code. diff --git a/docs/development_states.md b/docs/development_states.md index e1161ffc..81b6bdd5 100644 --- a/docs/development_states.md +++ b/docs/development_states.md @@ -1,12 +1,6 @@ --- layout: page title: "Using States" -description: "Introduction to states in Home Assistant." -date: 2017-05-13 05:40:00 +0000 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant keeps track of the states of entities in a state machine. The state machine has very few requirements: @@ -17,7 +11,7 @@ Home Assistant keeps track of the states of entities in a state machine. The sta [Description of the state object.](/docs/configuration/state_object/) -### {% linkable_title Using states in your component %} +### Using states in your component This is a simple tutorial/example on how to create and set states. We will do our work in a component called "hello_state". The purpose of this component is to display a given text in the frontend. diff --git a/docs/development_submitting.md b/docs/development_submitting.md index b1439e45..599d9a95 100644 --- a/docs/development_submitting.md +++ b/docs/development_submitting.md @@ -1,47 +1,41 @@ --- layout: page title: "Submit your work" -description: "Submit your work as Pull Request for Home Assistant." -date: 2016-07-01 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://help.github.com/articles/using-pull-requests). Here are the steps: 1. From your fork's dev branch, create a new branch to hold your changes: - + `git checkout -b some-feature` - + 2. Make your changes, create a [new platform](/developers/add_new_platform/), develop a [new component](/developers/creating_components/), or fix [issues](https://github.com/home-assistant/home-assistant/issues). - + 3. [Test your changes](/developers/development_testing/) and check for style violations. - + 4. If everything looks good according to these [musts](/developers/development_checklist/), commit your changes: - + `git add .` - + `git commit -m "Added some-feature"` * Write a meaningful commit message and not only `Update` or `Fix`. * Use a capital letter to start with your commit message. * Don't prefix your commit message with `[bla.bla]` or `platform:`. * Consider adding tests to ensure that your code works. - + 5. Push your committed changes back to your fork on GitHub: - + `git push origin HEAD` - + 6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request. - + * On GitHub, navigate to the main page of the Home Assistant repository. * In the "Branch" menu, choose the branch that contains your commits (from your fork). * To the right of the Branch menu, click **New pull request**. * Use the base branch dropdown menu to select the branch you'd like to merge your changes into, then use the compare branch drop-down menu to choose the topic branch you made your changes in. Make sure the Home Assistant branch matches with your forked branch (`dev`) else you will propose ALL commits between branches. - * Type a title and complete the provided description for your pull request. + * Type a title and complete the provided description for your pull request. * Click **Create pull request**. - + 7. Check for comments and suggestions on your pull request and keep an eye on the [CI output](https://travis-ci.org/home-assistant/home-assistant/). diff --git a/docs/development_testing.md b/docs/development_testing.md index a4f46269..2e68cf51 100644 --- a/docs/development_testing.md +++ b/docs/development_testing.md @@ -1,12 +1,6 @@ --- layout: page title: "Testing your code" -description: "Make sure that your code passes the checks" -date: 2016-07-01 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- As states in the [Style guidelines section](/developers/development_guidelines/) all code is checked to verify all unit tests pass and that the code passes the linting tools. Local testing is done using Tox, which has been installed as part of running `script/setup`. To start the tests, simply run it: @@ -22,7 +16,7 @@ Tox uses virtual environments under the hood to create isolated testing environm If you are working on tests for a component or platform and you need the dependencies available inside the Tox environment, update the list inside `script/gen_requirements_all.py`. Then run the script and then run `tox -r` to recreate the virtual environments. -### {% linkable_title Running single tests using Tox %} +### Running single tests using Tox You can pass arguments via Tox to py.test to be able to run single test suites or test files. Replace `py36` with the Python version that you use. @@ -37,7 +31,7 @@ $ tox -e py36 -- tests/test_core.py --timeout 2 $ tox -e py36 -- tests/test_core.py --duration=10 ``` -### {% linkable_title Testing outside of Tox %} +### Testing outside of Tox Running tox will invoke the full test suite. Even if you specify which tox target to run, you still run all tests inside that target. That's not very convenient to quickly iterate on your code! To be able to run the specific test suites without Tox, you'll need to install the test dependencies into your Python environment: @@ -60,7 +54,7 @@ You can also run linting tests against all changed files, as reported by `git di $ script/lint ``` -### {% linkable_title Preventing Linter Errors %} +### Preventing Linter Errors Save yourself the hassle of extra commits just to fix style errors by enabling the Flake8 git commit hook. Flake8 will check your code when you try to commit to the repository and block the commit if there are any style errors, which gives you a chance to fix them! @@ -71,6 +65,6 @@ $ flake8 --install-hook=git The `flake8-docstrings` extension will check docstrings according to [PEP257](https://www.python.org/dev/peps/pep-0257/) when running Flake8. -### {% linkable_title Notes on PyLint and PEP8 validation %} +### Notes on PyLint and PEP8 validation If you can't avoid a PyLint warning, add a comment to disable the PyLint check for that line with `# pylint: disable=YOUR-ERROR-NAME`. Example of an unavoidable one is if PyLint incorrectly reports that a certain object doesn't have a certain member. diff --git a/docs/development_validation.md b/docs/development_validation.md index 30b3dc77..46c463d0 100644 --- a/docs/development_validation.md +++ b/docs/development_validation.md @@ -1,12 +1,6 @@ --- layout: page title: "Validate the input" -description: "Validation of entries in configuration.yaml" -date: 2016-08-11 20:00 -sidebar: true -comments: false -sharing: true -footer: true --- The `configuration.yaml` file contains the configuration options for components and platforms. We use [voluptuous](https://pypi.python.org/pypi/voluptuous) to make sure that the configuration provided by the user is valid. Some entries are optional or could be required to set up a platform or a component. Others must be a defined type or from an already-defined list. @@ -20,7 +14,7 @@ Besides [voluptuous](https://pypi.python.org/pypi/voluptuous) default types, man - Numbers: `small_float` and `positive_int` - Time: `time`, `time_zone` - Misc: `template`, `slug`, `temperature_unit`, `latitude`, `longitude`, `isfile`, `sun_event`, `ensure_list`, `port`, `url`, and `icon` - + To validate platforms using [MQTT](/components/mqtt/), `valid_subscribe_topic` and `valid_publish_topic` are available. Some things to keep in mind: @@ -30,11 +24,11 @@ Some things to keep in mind: - Preferred order is `required` first and `optional` second - Starting with Home Assistant 0.64 `voluptuous` requires default values for optional configuration keys to be valid values. Don't use a default which is `None` like `vol.Optional(CONF_SOMETHING, default=None): cv.string`, set the default to `default=""` if required. -### {% linkable_title Snippets %} +### Snippets This section contains snippets for the validation we use. -#### {% linkable_title Default name %} +#### Default name It's common to set a default for a sensor if the user doesn't provide a name to use. @@ -46,7 +40,7 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string, ``` -#### {% linkable_title Limit the values %} +#### Limit the values You might want to limit the user's input to a couple of options. @@ -58,9 +52,9 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(['POST', 'GET']), ``` -#### {% linkable_title Port %} +#### Port -All port numbers are from a range of 1 to 65535. +All port numbers are from a range of 1 to 65535. ```python DEFAULT_PORT = 993 @@ -70,7 +64,7 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port, ``` -#### {% linkable_title Lists %} +#### Lists If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list. diff --git a/docs/documentation_create_page.md b/docs/documentation_create_page.md index cb0c4125..0970d529 100644 --- a/docs/documentation_create_page.md +++ b/docs/documentation_create_page.md @@ -1,12 +1,6 @@ --- layout: page title: "Create a new page" -description: "Create a new page for the documentation" -date: 2015-06-17 08:00 -sidebar: true -comments: false -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. @@ -19,19 +13,19 @@ If you start from scratch with a page, you need to add a header. Different secti --- 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. +Content...Written in markdown. -{% raw %}### {% linkable_title Linkable Header %}{% endraw %} +{% raw %}### Linkable Header %}{% endraw ... ``` @@ -43,7 +37,7 @@ A couple of points to remember: - 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 %} +### 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. @@ -53,23 +47,23 @@ The **Configuration Variables** section must use the {% raw %}`{% configuration ```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 %} ``` @@ -89,29 +83,29 @@ 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 %} +### 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 %}. +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 %} +### 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 %} +### 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. + You need to enable telnet on your router.

``` -### {% linkable_title Images, icons, and logos %} +### 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. @@ -123,5 +117,5 @@ The images which are displayed on the pages are stored in various directories ac 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 %} +### 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/docs/documentation_index.md b/docs/documentation_index.md index 50370c78..e5016990 100644 --- a/docs/documentation_index.md +++ b/docs/documentation_index.md @@ -1,13 +1,6 @@ --- layout: page title: "Documentation Home Assistant" -description: "home-assistant.io web presence for the documentation" -date: 2015-06-17 08:00 -sidebar: true -comments: false -sharing: true -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. diff --git a/docs/documentation_standards.md b/docs/documentation_standards.md index 05b1223c..7f9c3d74 100644 --- a/docs/documentation_standards.md +++ b/docs/documentation_standards.md @@ -1,25 +1,19 @@ --- layout: page title: "Documentation Standards" -description: "Standards for the creation and maintenance of documentation for Home Assistant." -date: 2017-09-16 03:51 -sidebar: true -comments: false -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 %} +## 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. +* All headings should use the {% raw %}`%}`{% endraw tag. -## {% linkable_title Component and Platform Pages %} +## Component and Platform Pages * The **Configuration Variables** section must use the {% raw %}`{% configuration %}`{% endraw %} tag. * Configuration variables must document the requirement status. @@ -32,7 +26,7 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo * 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 %} +## 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()`. @@ -57,26 +51,26 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo * `condition` * `service` -## {% linkable_title Renaming Pages %} +## 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 %} +## 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 %} +### Examples -#### {% linkable_title Double Quotes Outside, Single Quotes Inside (Valid) %} +#### Double Quotes Outside, Single Quotes Inside (Valid) {% raw %} ```yaml @@ -89,7 +83,7 @@ automation: ``` {% endraw %} -#### {% linkable_title Single Quotes Outside, Double Quotes Inside (Invalid) %} +#### Single Quotes Outside, Double Quotes Inside (Invalid) {% raw %} ```yaml @@ -102,7 +96,7 @@ automation: ``` {% endraw %} -#### {% linkable_title Multi-Line Template (Valid) %} +#### Multi-Line Template (Valid) {% raw %} ```yaml diff --git a/docs/external_api_python.md b/docs/external_api_python.md index 818bb8d0..96847625 100644 --- a/docs/external_api_python.md +++ b/docs/external_api_python.md @@ -1,19 +1,13 @@ --- layout: page title: "Python Remote API" -description: "Home Assistant Python Remote API documentation" -date: 2015-05-11 12:00 -sidebar: true -comments: false -sharing: true -footer: true --- See the [developer documentation][devdocs] for a full overview of the documentation. The rest of this page will contain examples on how to use it. [devdocs]: https://dev-docs.home-assistant.io/en/master/api/homeassistant.html#module-homeassistant.remote -In the package [`homeassistant.remote`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found. If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file to use the Python Remote API. +In the package [`homeassistant.remote`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found. If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file to use the Python Remote API. A simple way to get all current entities is to visit the "Set State" page in the "Developer Tools". For the examples below just choose one from the available entries. Here the sensor `sensor.office_temperature` and the switch `switch.livingroom_pin_2` are used. @@ -26,7 +20,7 @@ api = remote.API('127.0.0.1', 'password') print(remote.validate_api(api)) ``` -### {% linkable_title Get configuration %} +### Get configuration Get the current configuration of a Home Assistant instance: @@ -38,7 +32,7 @@ api = remote.API('127.0.0.1', 'password') print(remote.get_config(api)) ``` -### {% linkable_title Get details about services, events, and entitites %} +### Get details about services, events, and entitites The output from this is similar to the output you'd find via the frontend, using the [Developer Tools](/docs/tools/dev-tools/). @@ -63,9 +57,9 @@ for entity in entities: print(entity) ``` -### {% linkable_title Get the state of an entity %} +### Get the state of an entity -To get the details of a single entity, use `get_state`: +To get the details of a single entity, use `get_state`: ```python import homeassistant.remote as remote @@ -96,7 +90,7 @@ print('{} is {}.'.format( ) ``` -### {% linkable_title Set the state of an entity %} +### Set the state of an entity Of course, it's possible to set the state as well: @@ -111,7 +105,7 @@ remote.set_state(api, 'switch.livingroom_pin_2', new_state=STATE_ON) The state will be set to the new values until the next update occurs. -### {% linkable_title Blinking all entities of a domain %} +### Blinking all entities of a domain If you want to turn on all entities of a domain, retrieve the service via `get_services` and act on that: @@ -128,7 +122,7 @@ time.sleep(10) remote.call_service(api, domain, 'turn_off') ``` -### {% linkable_title Control a single entity %} +### Control a single entity To turn on or off a single switch, pass the ID of the entity: @@ -145,7 +139,7 @@ time.sleep(5) remote.call_service(api, domain, 'turn_off', {'entity_id': '{}'.format(switch_name)}) ``` -### {% linkable_title Specify a timeout %} +### Specify a timeout The default timeout for an API call with `call_service` is 5 seconds. Services taking longer than this to return will raise @@ -169,9 +163,9 @@ remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name}, timeout=11) ``` -### {% linkable_title Send a notification %} +### Send a notification -The example uses the Jabber notification platform to send a single message to the given recipient in the `configuration.yaml` file: +The example uses the Jabber notification platform to send a single message to the given recipient in the `configuration.yaml` file: ```python import homeassistant.remote as remote @@ -183,13 +177,13 @@ data = {"title":"Test", "message":"A simple test message from HA."} remote.call_service(api, domain, 'jabber', data) ``` -## {% linkable_title Examples %} +## Examples This section contains a couple of sample scripts. -### {% linkable_title List all sensors and their value %} +### List all sensors and their value -If you want to see, export or list all sensor states then an easy way to do it, is to get all entities and filter for the one you are looking for. +If you want to see, export or list all sensor states then an easy way to do it, is to get all entities and filter for the one you are looking for. ```python import homeassistant.remote as remote @@ -202,10 +196,10 @@ for entity in entities: print('{}: {}'.format(data.attributes['friendly_name'], data.state)) ``` -### {% linkable_title Show difference between `last_changed` and `last_updated` %} +### Show difference between `last_changed` and `last_updated` -The documentation about the [State Objects](/docs/configuration/state_object/) describes the -`last_changed` and `last_updated` fields. This example shows how it works in practice. +The documentation about the [State Objects](/docs/configuration/state_object/) describes the +`last_changed` and `last_updated` fields. This example shows how it works in practice. ```python import time diff --git a/docs/external_api_rest.md b/docs/external_api_rest.md index ec232cac..2eaef3d0 100644 --- a/docs/external_api_rest.md +++ b/docs/external_api_rest.md @@ -1,12 +1,6 @@ --- layout: page title: "RESTful API" -description: "Home Assistant RESTful API documentation" -date: 2014-12-21 13:27 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant runs a web server accessible on port 8123. @@ -16,7 +10,7 @@ Home Assistant runs a web server accessible on port 8123. The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](/components/http/)). -If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file. +If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file. There are multiple ways to consume the Home Assistant Rest API. One is with `curl`: @@ -51,11 +45,11 @@ Successful calls will return status code 200 or 201. Other status codes that can - 404 (Not Found) - 405 (Method not allowed) -### {% linkable_title Actions %} +### Actions The API supports the following actions: -#### {% linkable_title GET /api/ %} +#### GET /api/ Returns a message if the API is up and running. @@ -72,7 +66,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/ ``` -#### {% linkable_title GET /api/config %} +#### GET /api/config Returns the current configuration as JSON. @@ -103,7 +97,7 @@ Returns the current configuration as JSON. "location_name":"Home", "longitude":8.458853651, "time_zone":"Europe/Zurich", - "unit_system":{ + "unit_system":{ "length":"km", "mass":"g", "temperature":"\u00b0C", @@ -124,7 +118,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/config ``` -#### {% linkable_title GET /api/discovery_info %} +#### GET /api/discovery_info Returns basic information about the Home Assistant instance as JSON. @@ -144,7 +138,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/discovery_info ``` -#### {% linkable_title GET /api/events %} +#### GET /api/events Returns an array of event objects. Each event object contains event name and listener count. @@ -168,7 +162,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/events ``` -#### {% linkable_title GET /api/services %} +#### GET /api/services Returns an array of service objects. Each object contains the domain and which services it contains. @@ -197,7 +191,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/services ``` -#### {% linkable_title GET /api/history/period/<timestamp> %} +#### GET /api/history/period/<timestamp> Returns an array of state changes in the past. Each object contains further details for the entities. @@ -255,7 +249,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?end_time=2016-12-31T00%3A00%3A00%2B02%3A00 ``` -#### {% linkable_title GET /api/states %} +#### GET /api/states Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes. @@ -283,7 +277,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ -H "Content-Type: application/json" http://localhost:8123/api/states ``` -#### {% linkable_title GET /api/states/<entity_id> %} +#### GET /api/states/<entity_id> Returns a state object for specified entity_id. Returns 404 if not found. @@ -311,7 +305,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api/states/sensor.kitchen_temperature ``` -#### {% linkable_title GET /api/error_log %} +#### GET /api/error_log Retrieve all errors logged during the current session of Home Assistant as a plaintext response. @@ -329,7 +323,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api/error_log ``` -#### {% linkable_title GET /api/camera_proxy/camera.<entity_id> %} +#### GET /api/camera_proxy/camera.<entity_id> Returns the data (image) from the specified camera entity_id. @@ -341,7 +335,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg ``` -#### {% linkable_title POST /api/states/<entity_id> %} +#### POST /api/states/<entity_id> Updates or creates the current state of an entity. @@ -381,7 +375,7 @@ $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ http://localhost:8123/api/states/sensor.kitchen_temperature ``` -#### {% linkable_title POST /api/events/<event_type> %} +#### POST /api/events/<event_type> Fires an event with event_type @@ -401,7 +395,7 @@ Returns a message if successful. } ``` -#### {% linkable_title POST /api/services/<domain>/<service> %} +#### POST /api/services/<domain>/<service> Calls a service within a specific domain. Will return when the service has been executed or after 10 seconds, whichever comes first. @@ -457,7 +451,7 @@ $ curl -X POST \ The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system.

-#### {% linkable_title POST /api/template %} +#### POST /api/template Render a Home Assistant template. [See template docs for more information.](/topics/templating/) @@ -481,7 +475,7 @@ $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ -d '{"template": "It is {{ now }}!"}' http://localhost:8123/api/template ``` -#### {% linkable_title POST /api/event_forwarding %} +#### POST /api/event_forwarding Set up event forwarding to another Home Assistant instance. @@ -503,7 +497,7 @@ It will return a message if event forwarding was set up successfully. } ``` -#### {% linkable_title DELETE /api/event_forwarding %} +#### DELETE /api/event_forwarding Cancel event forwarding to another Home Assistant instance.
diff --git a/docs/external_api_server_sent_events.md b/docs/external_api_server_sent_events.md index fc54b168..e6930f44 100644 --- a/docs/external_api_server_sent_events.md +++ b/docs/external_api_server_sent_events.md @@ -1,12 +1,6 @@ --- layout: page title: "Server-sent events" -description: "Home Assistant Server-sent events documentation" -date: 2016-04-08 07:00 -sidebar: true -comments: false -sharing: true -footer: true --- The [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) feature is a one-way channel from your Home Assistant server to a client which is acting as a consumer. For bi-directional communication check the [RESTful API](/developers/rest_api/) and [Python API](/developers/python_api/). @@ -42,7 +36,7 @@ You can create a convenient view for this by creating an HTML file (`sse.html`) Visit [http://localhost:8123/local/sse.html](http://localhost:8123/local/sse.html) to see the stream of events. -## {% linkable_title Examples %} +## Examples A simple way to consume server-sent events is to use a command-line http client like [httpie](https://httpie.org/). Installation info is on the site (if you use Homebrew, it's `brew install httpie`). Once installed, run this snippet from your terminal: @@ -50,11 +44,11 @@ A simple way to consume server-sent events is to use a command-line http client $ http --stream http://localhost:8123/api/stream x-ha-access:YOUR_PASSWORD content-type:application/json ``` -### {% linkable_title Website %} +### Website The [home-assistant-sse](https://github.com/fabaff/home-assistant-sse) repository contains a more advanced example. -### {% linkable_title Python %} +### Python If you want to test the server-sent events without creating a website, the Python module [`sseclient` ](https://pypi.python.org/pypi/sseclient/) can help. To install (assuming Python and pip3 are already installed): diff --git a/docs/external_api_websocket.md b/docs/external_api_websocket.md index 76f7f0b0..579f5e5b 100644 --- a/docs/external_api_websocket.md +++ b/docs/external_api_websocket.md @@ -1,25 +1,19 @@ --- layout: page title: "WebSocket API" -description: "Home Assistant WebSocket API documentation" -date: 2016-11-26 13:27 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages: - [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend - [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/) -- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser +- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser Connect your websocket implementation to `ws://localhost:8123/api/websocket`. -If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`websocket_api` component](/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API. +If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`websocket_api` component](/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API. -## {% linkable_title Server states %} +## Server states 1. Client connects. 1. Authentication phase starts. @@ -37,7 +31,7 @@ If you are not using the [`frontend`](/components/frontend/) in your setup then During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to its origin. -## {% linkable_title Message format %} +## Message format Each API message is a JSON serialized object containing a `type` key. After the authentication phase messages also must contain an `id`, an integer that contains the number of interactions. @@ -63,7 +57,7 @@ Example of an auth message: } ``` -## {% linkable_title Authentication phase %} +## Authentication phase When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header). @@ -109,7 +103,7 @@ If the data is incorrect, the server will reply with `auth_invalid` message and } ``` -## {% linkable_title Command phase %} +## Command phase During this phase the client can give commands to the server. The server will respond to each command with a `result` message indicating when the command is done and if it was successful. @@ -123,7 +117,7 @@ During this phase the client can give commands to the server. The server will re } ``` -## {% linkable_title Subscribe to events %} +## Subscribe to events The command `subscribe_events` will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple `subscribe_events` commands. @@ -196,7 +190,7 @@ For each event that matches, the server will send a message of type `event`. The } ``` -### {% linkable_title Unsubscribing from events %} +### Unsubscribing from events You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field. @@ -219,7 +213,7 @@ The server will respond with a result message to indicate that unsubscribing was } ``` -### {% linkable_title Calling a service %} +### Calling a service This will call a service in Home Assistant. Right now there is no return value. The client can listen to `state_changed` events if it is interested in changed entities as a result of a service call. @@ -247,7 +241,7 @@ The server will indicate with a message indicating that the service is done exec } ``` -### {% linkable_title Fetching states %} +### Fetching states This will get a dump of all the current states in Home Assistant. @@ -269,7 +263,7 @@ The server will respond with a result message containing the states. } ``` -### {% linkable_title Fetching config %} +### Fetching config This will get a dump of the current config in Home Assistant. @@ -291,7 +285,7 @@ The server will respond with a result message containing the config. } ``` -### {% linkable_title Fetching services %} +### Fetching services This will get a dump of the current services in Home Assistant. @@ -313,7 +307,7 @@ The server will respond with a result message containing the services. } ``` -### {% linkable_title Fetching panels %} +### Fetching panels This will get a dump of the current registered panels in Home Assistant. @@ -335,7 +329,7 @@ The server will respond with a result message containing the current registered } ``` -## {% linkable_title Error handling %} +## Error handling If an error occurs, the `success` key in the `result` message will be set to `false`. It will contain an `error` key containing an object with two keys: `code` and `message`. diff --git a/docs/frontend.md b/docs/frontend.md index 0fb71208..a052be66 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -1,12 +1,6 @@ --- layout: page title: "Frontend development" -description: "Tips and hints if you are starting on Home Assistant frontend development" -date: 2014-12-21 13:32 -sidebar: true -comments: false -sharing: true -footer: true --- Home Assistant is built on top of the [Polymer](https://www.polymer-project.org/) webcomponents framework. Polymer allows building encapsulated custom HTML elements. [Home-Assistant-Polymer source code on GitHub.][hass-polymer] @@ -15,7 +9,7 @@ Home Assistant is built on top of the [Polymer](https://www.polymer-project.org/ Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.

-## {% linkable_title Setting up the environment %} +## Setting up the environment

All commands below need to be run from inside the home-assistant-polymer repository. @@ -61,7 +55,7 @@ $ script/bootstrap This script will use yarn and bower to install all the necessary dependencies necessary for development and do an initial build. -### {% linkable_title Creating pull requests %} +### Creating pull requests If you're planning on issuing a PR back to the Home Assistant codebase you need to fork the polymer project and add your fork as a remote to the Home Assistant Polymer repo. @@ -77,7 +71,7 @@ $ git commit -m "Added new feature X" $ git push -u HEAD ``` -## {% linkable_title Development %} +## Development If you are changing `html` files under `/src` or `/panels` - just reload the page in your browser to see changes. If you are changing javascript files under `/js` you need to have gulp running to watch the source files for changes and build when necessary. @@ -92,7 +86,7 @@ The source code for the frontend can be found in different directories: - Panels: `/home-assistant-polymer/panels/` - Javascript code: `/home-assistant-polymer/js/` -# {% linkable_title Building the Polymer frontend %} +# Building the Polymer frontend Building a new version of the frontend is as simple as running `script/build_frontend`. To use a built version package it: `python setup.py sdist` diff --git a/docs/frontend_add_card.md b/docs/frontend_add_card.md index 2deba80d..5e0284ac 100644 --- a/docs/frontend_add_card.md +++ b/docs/frontend_add_card.md @@ -1,12 +1,6 @@ --- layout: page title: "Adding state card" -description: "Adding a state card to the frontend" -date: 2016-04-16 14:40 -07:00 -sidebar: true -comments: false -sharing: true -footer: true --- The main interface of Home Assistant is a list of the current entities and their states. For each entity in the system, a state card will be rendered. State cards will show an icon, the name of the entity, when the state has last changed and the current state or a control to interact with it. diff --git a/docs/frontend_add_more_info.md b/docs/frontend_add_more_info.md index 2364c5b3..f8451e69 100644 --- a/docs/frontend_add_more_info.md +++ b/docs/frontend_add_more_info.md @@ -1,12 +1,6 @@ --- layout: page title: "Adding more info dialogs" -description: "Adding a more info dialog to the frontend" -date: 2016-04-16 14:40 -07:00 -sidebar: true -comments: false -sharing: true -footer: true --- Whenever the user taps or clicks on one of the cards, a more info dialog will show. The header of this dialog will be the state card, followed by the history of this entity for the last 24 hours. Below this the more info component is rendered for that entity. The more info component can show more information or allow more ways of control. diff --git a/docs/frontend_creating_custom_panels.md b/docs/frontend_creating_custom_panels.md index 4066e606..24307d8e 100644 --- a/docs/frontend_creating_custom_panels.md +++ b/docs/frontend_creating_custom_panels.md @@ -1,19 +1,13 @@ --- layout: page title: "Creating custom panels" -description: "Introduction to create custom panels for Home Assistant." -date: 2016-07-29 13:00 -sidebar: true -comments: false -sharing: true -footer: true --- Panels are pages within Home Assistant that show information within Home Assistant and can allow controlling it. Panels are linked from the sidebar and rendered full screen. The have have real-time access to the Home Assistant object via JavaScript. Examples of panels in the app are map, logbook and history. Besides components registering panels, users can also register panels using the `panel_custom` component. This allows users to quickly build their own custom interfaces for Home Assistant. -### {% linkable_title Before you get started %} +### Before you get started The Home Assistant user interface is currently served to browsers in modern JavaScript and older JavaScript (ES5). The older version has a wider browser support but that comes at a cost of size, performance and more difficult to get started building panels for authors. @@ -24,7 +18,7 @@ frontend: javascript_version: latest ``` -### {% linkable_title Building your first panel %} +### Building your first panel Create a file called `hello.html` in your /panels/. @@ -45,7 +39,7 @@ The `hello.html` contains the needed building blocks to create the elements insi