+
+ Overview of the home automation landscape
+
+
+
+
+ Overview of the home automation landscape
+
+
+ 
+
+ Overview of the Home Assistant core architecture
+
+
+Diagram showing interaction between components and the Home Assistant core
+
+
+ 
+
+ Overview of the full Home Assistant architecture with a couple of loaded components and platforms
+
+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. 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 %} + + 1. Voluptuous schema present for config validation + 2. Default parameters specified in voluptuous schema, not in `setup(…)` + 3. Schema using as many generic config keys as possible from `homeassistant.const` + 4. If your component has platforms, define a `PLATFORM_SCHEMA` instead of a `CONFIG_SCHEMA`. + 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 %} + + 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 new file mode 100644 index 00000000000..00ab599c1b3 --- /dev/null +++ b/docs/code_review_platform.md @@ -0,0 +1,78 @@ +--- +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. + ++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. 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 %} + + 1. If you depend on a component for the connection, add it to your dependencies: `DEPENDENCIES = ['nest']` + +### {% linkable_title 3. Configuration %} + + 1. Voluptuous schema present for config validation + 2. Voluptuous schema extends schema from component+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 %} + +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 %} + +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: + +```python +from homeassistant.components.discovery import SERVICE_AWESOMEDEVICE +from homeassistant.helpers import discovery + +DOMAIN = 'awesomedevice' + +DEPENDENCIES = ['http'] + +def setup(hass, config): + cfg = config.get(DOMAIN) + + def device_discovered(service, info): + """ Called when a Awesome device has been discovered. """ + print("Discovered a new Awesome device: {}".format(info)) + + discovery.listen( + hass, SERVICE_AWESOMEDEVICE, device_discovered) + + return True +``` + +### {% linkable_title 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): + +```python +SERVICE_AWESOMEDEVICE = 'awesomedevice' + +SERVICE_HANDLERS = { + ... + SERVICE_AWESOMEDEVICE: ('awesomedevice', None), +} +``` diff --git a/docs/component_events.md b/docs/component_events.md new file mode 100644 index 00000000000..ee2e281b1f3 --- /dev/null +++ b/docs/component_events.md @@ -0,0 +1,12 @@ +--- +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 new file mode 100644 index 00000000000..8eacc22ff4a --- /dev/null +++ b/docs/component_generic_discovery.md @@ -0,0 +1,77 @@ +--- +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. +This can be achieved using the `load_platform` or `async_load_platform` methods from `homeassistant.helpers.discovery`: + +```python +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 %} + +Say you need to implement your new MyFlashyHub that controls both Switches & Lights, you can follow these steps: + +Configuration required for your new hub component: + +```yaml +myflashyhub: + example: setting +``` + +The source for your component can be located in your configuration directory for now: + +```bash +~/.homeassistant/custom_components/myflashyhub.py +~/.homeassistant/custom_components/light/myflashyhub.py +~/.homeassistant/custom_components/switch/myflashyhub.py +``` + +In the hub component `myflashyhub.py` you can call your light and switch components. To pass any non-serializable information to the platforms in the sub-component, you can use a global variable. + +```python +from homeassistant.helpers.discovery import load_platform +DOMAIN = 'myflashyhub' + +DATA_MFH = 'MFH' + +def setup(hass, config): + """Your controller/hub specific code.""" + hass.data[DATA_MFH] = SomeObjectToInitialiseGlobal() + + #--- snip --- + load_platform(hass, 'light', DOMAIN) + load_platform(hass, 'switch', DOMAIN, {'optional': 'arguments'}) +``` + +Add your custom device specific code to the `setup_platform` method in `light/myflashyhub.py` and `switch/myflashyhub`. + +```python +import custom_components.myflashyhub as myflashyhub + +# '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.""" + # You can now use hass.data[myflashyhub.DATA_MFH] +``` + + +The `load_platform` method allows the platforms to be loaded without the need for any additional platform entries in your `configuration.yaml` file, which normally would have been: + +```yaml +#light: +# platform: myflashyhub +#switch: +# platform: myflashyhub +``` diff --git a/docs/component_loading.md b/docs/component_loading.md new file mode 100644 index 00000000000..b817fadf382 --- /dev/null +++ b/docs/component_loading.md @@ -0,0 +1,25 @@ +--- +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: + + * `
+You can override a built-in component by having a component with the same name in your config/custom_components folder. If the built-in component is inside a subfolder, take care to place your customization in a folder with the same name in config/custom_components/*folder*. Note that overriding built-in components is not recommended and will probably break things!
+
+Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/.
+
. It's the path after the text "Path to configuration.yaml".
+
+Inside your configuration directory create a new folder called `custom_components`. It might be that one already exists, that's fine too. This is the folder that Home Assistant will look at when looking for custom code.
+
++The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version. +
+ +To verify that everything is working correctly, let's create a small Hello World component. To do so, create a file called `hello_world.py` in your custom components folder. Copy paste the following content to it: + +```python +# The domain of your component. Equal to the filename of your component. +DOMAIN = "hello_world" + + +def setup(hass, config): + """Setup the hello_world component.""" + # States are in the format DOMAIN.OBJECT_ID. + hass.states.set('hello_world.Hello_World', 'Works!') + + # Return boolean to indicate that initialization was successfully. + return True +``` + +Last step is to add `hello_world:` entry to your `configuration.yaml` file. + +```yaml +# Hello World component +hello_world: +``` + +After running `hass`, we should see log entries stating that `hello_world` component was loaded. What is more, additional state card shall appear within main panel. + +```log +2018-04-03 21:44:20 INFO (MainThread) [homeassistant.loader] Loaded hello_world from custom_components.hello_world +2018-04-03 21:44:20 INFO (MainThread) [homeassistant.setup] Setting up hello_world +``` + +
+
+State card showing that Hello World component is working as intended.
+
+Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: `sudo yum install epel-release && sudo yum install python34 python34-devel mysql-devel` +
+ +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 %} + +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. + +Due to Home Assistant is mainly designed and developed on Linux distributions it is not recommended to develop on Windows machines. However on Windows 10 machines you should decide to set up a [Linux subsystem](https://docs.microsoft.com/de-de/windows/wsl/install-win10). + +Setup Linux subsystem. + +```bash +$ apt-get update +$ apt-get upgrade +$ echo 'export DISPLAY=:0' >> ~/.bashrc && . ~/.bashrc +$ sudo apt-get install xubuntu-desktop -y +``` + +It is recommended using [PyCharm](https://www.jetbrains.com/pycharm/download/) as debugger. Download and start PyCharm. + +```bash +$ wget https://download.jetbrains.com/python/pycharm-community-20XX.X.tar.gz +$ tar -xzf pycharm-community-20XX.X +$ ./pycharm.sh +``` + +In order to display the PyCharm GUI on Windows you need to run a X-Server like [VcXserv](https://sourceforge.net/projects/vcxsrv/). + +Also, make sure to install or upgrade the `setuptools` Python package. It contains compatibility improvements and adds automatic use of compilers: + +```bash +$ pip install --upgrade setuptools +``` + +#### {% linkable_title Developing on OS X %} + +Install [Homebrew](https://brew.sh/), then use that to install Python 3: + +```bash +$ brew install python3 +``` + +### {% linkable_title 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: + +```bash +$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git +$ cd home-assistant +$ git remote add upstream https://github.com/home-assistant/home-assistant.git +``` + +### {% linkable_title 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. + +```bash +$ python3 -m venv . +$ source bin/activate +``` +Install the requirements with a provided script named `setup`. + +```bash +$ script/setup +``` + +Invoke your installation. + +```bash +$ hass +``` + +### {% linkable_title 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). + +You can use the [logger](/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on. diff --git a/docs/development_events.md b/docs/development_events.md new file mode 100644 index 00000000000..e078396fd05 --- /dev/null +++ b/docs/development_events.md @@ -0,0 +1,62 @@ +--- +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]. + +The event system is very flexible. There are no limitations on the event type, as long as it's a string. Each event can contain data. The data is a dictionary that can contain any data as long as it's JSON serializable. This means that you can use number, string, dictionary and list. + +[List of events that Home Assistant fires.][object] + +### {% linkable_title 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`. + +Example component that will fire an event when loaded. + +```python +DOMAIN = 'hello_event' + +def setup(hass, config): + """Set up is called when Home Assistant is loading our component.""" + + # Fire event my_cool_event with event data answer=42 + hass.bus.fire('my_cool_event', { + 'answer': 42 + }) +``` + +### {% linkable_title 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. + +```python +DOMAIN = 'hello_event' + +def setup(hass, config): + """Set up is called when Home Assistant is loading our component.""" + count = 0 + + # Listener to handle fired events + def handle_event(event): + nonlocal count + count += 1 + print('Total events received:', count) + + # Listen for when my_cool_event is fired + hass.bus.listen('my_cool_event', handle_event) +``` + +#### {% linkable_title 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] + +[helpers]: https://dev-docs.home-assistant.io/en/master/api/helpers.html#module-homeassistant.helpers.event +[object]: /docs/configuration/events/ diff --git a/docs/development_guidelines.md b/docs/development_guidelines.md new file mode 100644 index 00000000000..7e4088249ce --- /dev/null +++ b/docs/development_guidelines.md @@ -0,0 +1,81 @@ +--- +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). + +Summary of the most relevant points: + +- Line length is limited to 79 characters (see below). +- Use 4 spaces per indentation level. We don't use tabs. +- Comments should be full sentences and end with a period. +- [Imports](https://www.python.org/dev/peps/pep-0008/#imports) should be ordered. +- Constants and the content of lists and dictionaries should be in alphabetical order. +- Avoid trailing whitespace but surround binary operators with a single space. +- Line separator should be set to `LF`. + +The maximum line length comes directly from the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/#maximum-line-length), and is also used by the Python standard library. All code must pass these linting checks, and no exceptions will be made. There have already been numerous requests to increase the maximum line length, but after evaluating the options, the Home Assistant maintainers have decided to stay at 79 characters. This decision is final. + +Those points may require that you adjust your IDE or editor settings. + +## {% linkable_title 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 %} + +Use single quotes `'` for single word and `"` for multiple words or sentences. + +```python +ATTR_WATERLEVEL = 'level' +CONF_ATTRIBUTION = "Data provided by the WUnderground weather service" +SENSOR_TYPES = { + 'alerts': ['Alerts', None], +} +``` + +### {% linkable_title 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. + +```python +""" +Support for MQTT lights. + +For more details about this platform, please refer to the documentation at +https://home-assistant.io/components/light.mqtt/ +""" +``` + +### {% linkable_title Requirements %} + +Please place [Platform requirements](/developers/code_review_platform/#1-requirements) right after the imports. + +```python +[...] +from homeassistant.helpers.entity import Entity + +REQUIREMENTS = ['xmltodict==0.11.0'] +``` + +### {% linkable_title 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. + +```python +_LOGGER.error("No route to device: %s", self._resource) +``` + +```bash +2017-05-01 14:28:07 ERROR [homeassistant.components.sensor.arest] No route to device: 192.168.0.18 +``` + +Don't print out wrong API keys, tokens, usernames, or passwords. +Also note that `_LOGGER.info` is reserved for the core, use `_LOGGER.debug` in anything else. diff --git a/docs/development_hass_object.md b/docs/development_hass_object.md new file mode 100644 index 00000000000..d4a5926d2ec --- /dev/null +++ b/docs/development_hass_object.md @@ -0,0 +1,38 @@ +--- +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 Home Assistant instance contains four objects to help you interact with the system. + +| Object | Description | +| ------ | ----------- | +| `hass` | This is the instance of Home Assistant. Allows starting, stopping and enqueing new jobs. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.HomeAssistant) +| `hass.config` | This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.Config) +| `hass.states` | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.StateMachine). | +| `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` %} + +Depending on what you're writing, there are different ways the `hass` object is made available. + +**Component**
+
+
+Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead. +
+ +To get your component included in the Home Assistant releases, follow the steps described in the [Submit your work](/developers/development_submitting/) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request. diff --git a/docs/development_submitting.md b/docs/development_submitting.md new file mode 100644 index 00000000000..b1439e4551e --- /dev/null +++ b/docs/development_submitting.md @@ -0,0 +1,47 @@ +--- +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. + * 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 new file mode 100644 index 00000000000..a4f462690dd --- /dev/null +++ b/docs/development_testing.md @@ -0,0 +1,76 @@ +--- +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: + +```bash +$ tox +``` +**Important:** Run `tox` before you create your pull request to avoid annoying fixes. + +Running Tox will run unit tests against the locally available Pythons, as well as validate the code and document style using `pycodestyle`, `pydocstyle` and `pylint`. You can run tests on only one tox target -- just use `-e` to select an environment. For example, `tox -e lint` runs the linters only, and `tox -e py36` runs unit tests only on Python 3.6. + +Tox uses virtual environments under the hood to create isolated testing environments. The tox virtual environments will get out-of-date when requirements change, causing test errors. Run `tox -r` to tell Tox to recreate the virtual environments. + +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 %} + +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. + +```bash +# Stop after the first test fails +$ tox -e py36 -- tests/test_core.py -x +# Run test with specified name +$ tox -e py36 -- tests/test_core.py -k test_split_entity_id +# Fail a test after it runs for 2 seconds +$ tox -e py36 -- tests/test_core.py --timeout 2 +# Show the 10 slowest tests +$ tox -e py36 -- tests/test_core.py --duration=10 +``` + +### {% linkable_title 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: + +```bash +$ pip3 install -r requirements_test_all.txt +``` + +Now that you have all test dependencies installed, you can run tests on individual files: + +```bash +$ flake8 homeassistant/core.py +$ pylint homeassistant/core.py +$ pydocstyle homeassistant/core.py +$ py.test tests/test_core.py +``` + +You can also run linting tests against all changed files, as reported by `git diff upstream/dev... --diff-filter=d --name-only`, using the `lint` script: + +```bash +$ script/lint +``` + +### {% linkable_title 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! + +```bash +$ pip3 install flake8 flake8-docstrings +$ 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 %} + +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 new file mode 100644 index 00000000000..30b3dc77a86 --- /dev/null +++ b/docs/development_validation.md @@ -0,0 +1,87 @@ +--- +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. + +We test the configuration to ensure that users have a great experience and minimize notifications if something is wrong with a platform or component setup before Home Assistant runs. + +Besides [voluptuous](https://pypi.python.org/pypi/voluptuous) default types, many custom types are available. For an overview, take a look at the [config_validation.py](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/config_validation.py) helper. + +- Types: `string`, `byte`, and `boolean` +- Entity ID: `entity_id` and `entity_ids` +- 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: + +- Use the constants defined in `const.py` +- Import `PLATFORM_SCHEMA` from the parent component and extend it +- 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 %} + +This section contains snippets for the validation we use. + +#### {% linkable_title Default name %} + +It's common to set a default for a sensor if the user doesn't provide a name to use. + +```python +DEFAULT_NAME = 'Sensor name' + +PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ + ... + vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string, +``` + +#### {% linkable_title Limit the values %} + +You might want to limit the user's input to a couple of options. + +```python +DEFAULT_METHOD = 'GET' + +PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ + ... + vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(['POST', 'GET']), +``` + +#### {% linkable_title Port %} + +All port numbers are from a range of 1 to 65535. + +```python +DEFAULT_PORT = 993 + +PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ + ... + vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port, +``` + +#### {% linkable_title Lists %} + +If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list. + +```python +SENSOR_TYPES = { + 'article_cache': ('Article Cache', 'MB'), + 'average_download_rate': ('Average Speed', 'MB/s'), +} + +PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({ + ... + vol.Optional(CONF_MONITORED_VARIABLES, default=[]): + vol.All(cv.ensure_list, [vol.In(SENSOR_TYPES)]), +``` diff --git a/docs/documentation_create_page.md b/docs/documentation_create_page.md new file mode 100644 index 00000000000..cb0c4125198 --- /dev/null +++ b/docs/documentation_create_page.md @@ -0,0 +1,127 @@ +--- +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. + +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/docs/documentation_index.md b/docs/documentation_index.md new file mode 100644 index 00000000000..50370c7802a --- /dev/null +++ b/docs/documentation_index.md @@ -0,0 +1,44 @@ +--- +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. + +home-assistant.io is built using [Jekyll](http://github.com/mojombo/jekyll) and [these available 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. + +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. + +Short cut 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/docs/documentation_standards.md b/docs/documentation_standards.md new file mode 100644 index 00000000000..05b1223cc61 --- /dev/null +++ b/docs/documentation_standards.md @@ -0,0 +1,121 @@ +--- +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 %} + +* 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/docs/external_api_python.md b/docs/external_api_python.md new file mode 100644 index 00000000000..818bb8d0771 --- /dev/null +++ b/docs/external_api_python.md @@ -0,0 +1,236 @@ +--- +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. + +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. + +First import the module and setup the basics: + +```python +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'password') +print(remote.validate_api(api)) +``` + +### {% linkable_title Get configuration %} + +Get the current configuration of a Home Assistant instance: + +```python +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'password') + +print(remote.get_config(api)) +``` + +### {% linkable_title 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/). + +```python +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') + +print('-- Available services:') +services = remote.get_services(api) +for service in services: + print(service['services']) + +print('\n-- Available events:') +events = remote.get_event_listeners(api) +for event in events: + print(event) + +print('\n-- Available entities:') +entities = remote.get_states(api) +for entity in entities: + print(entity) +``` + +### {% linkable_title Get the state of an entity %} + +To get the details of a single entity, use `get_state`: + +```python +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +office_temp = remote.get_state(api, 'sensor.office_temperature') +print('{} is {} {}.'.format( + office_temp.name, office_temp.state, + office_temp.attributes['unit_of_measurement']) +) +``` + +This outputs the details which are stored for this entity, ie: + +```bash +Office Temperature is 19 °C. +``` + +Switches work the same way. The only difference is that both entities have different attributes. + +```python +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +switch_livingroom = remote.get_state(api, 'switch.livingroom_pin_2') +print('{} is {}.'.format( + switch_livingroom.name, switch_livingroom.state) +) +``` + +### {% linkable_title Set the state of an entity %} + +Of course, it's possible to set the state as well: + +```python +import homeassistant.remote as remote +from homeassistant.const import STATE_ON + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +remote.set_state(api, 'sensor.office_temperature', new_state=123) +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 %} + +If you want to turn on all entities of a domain, retrieve the service via `get_services` and act on that: + + +```python +import time +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +domain = 'switch' + +remote.call_service(api, domain, 'turn_on') +time.sleep(10) +remote.call_service(api, domain, 'turn_off') +``` + +### {% linkable_title Control a single entity %} + +To turn on or off a single switch, pass the ID of the entity: + +```python +import time +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +domain = 'switch' +switch_name = 'switch.livingroom_pin_2' + +remote.call_service(api, domain, 'turn_on', {'entity_id': '{}'.format(switch_name)}) +time.sleep(5) +remote.call_service(api, domain, 'turn_off', {'entity_id': '{}'.format(switch_name)}) +``` + +### {% linkable_title 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 +`homeassistant.exceptions.HomeAssistantError: Timeout`, unless provided with a +longer timeout. + +```python +import homeassistant.remote as remote + +api = remote.API('host', 'password') +domain = 'switch' + +# Assuming switch.timeout_switch takes 10 seconds to return +switch_name = 'switch.timeout_switch' + +# Raises homeassistant.exceptions.HomeAssistantError: Timeout when talking to +remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name}) + +# Runs withous exception +remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name}, + timeout=11) +``` + +### {% linkable_title Send a notification %} + +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 + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +domain = 'notify' +data = {"title":"Test", "message":"A simple test message from HA."} + +remote.call_service(api, domain, 'jabber', data) +``` + +## {% linkable_title Examples %} + +This section contains a couple of sample scripts. + +### {% linkable_title 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. + +```python +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') +entities = remote.get_states(api) +for entity in entities: + if entity.entity_id.startswith('sensor'): + data = remote.get_state(api, entity.entity_id) + print('{}: {}'.format(data.attributes['friendly_name'], data.state)) +``` + +### {% linkable_title 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. + +```python +import time + +from prettytable import PrettyTable +import homeassistant.remote as remote + +api = remote.API('127.0.0.1', 'YOUR_PASSWORD') + +ACTIONS = { + 'Create sensor': [21, 'Test'], + 'No new sensor value': [21, 'Test'], + 'New sensor value': [22, 'Test'], + 'Update attribute': [22, 'Test1'], +} + +output = PrettyTable(['Action', 'Last changed', 'Last updated']) + +for key, value in ACTIONS.items(): + remote.set_state(api, 'sensor.test', new_state=value[0], + attributes={'friendly_name': value[1]}) + data = remote.get_state(api, 'sensor.test') + output.add_row([key, data.last_changed, data.last_updated]) + time.sleep(2) + +print(output) +``` + diff --git a/docs/external_api_rest.md b/docs/external_api_rest.md new file mode 100644 index 00000000000..ec232cac97f --- /dev/null +++ b/docs/external_api_rest.md @@ -0,0 +1,530 @@ +--- +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. + +* http://IP_ADDRESS:8123/ is an interface to control Home Assistant. +* http://IP_ADDRESS:8123/api/ is a Rest API. + +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. + +There are multiple ways to consume the Home Assistant Rest API. One is with `curl`: + +```bash +curl -X GET \ + -H "x-ha-access: YOUR_PASSWORD" \ + -H "Content-Type: application/json" \ + http://IP_ADDRESS:8123/ENDPOINT +``` + +Another option is to use Python and the [Requests](http://docs.python-requests.org/en/latest/) module. = + +```python +from requests import get + +url = 'http://localhost:8123/ENDPOINT' +headers = {'x-ha-access': 'YOUR_PASSWORD', + 'content-type': 'application/json'} + +response = get(url, headers=headers) +print(response.text) +``` + ++You can append `?api_password=YOUR_PASSWORD` to any URL to log in automatically. +
+ +Successful calls will return status code 200 or 201. Other status codes that can return are: + +- 400 (Bad Request) +- 401 (Unauthorized) +- 404 (Not Found) +- 405 (Method not allowed) + +### {% linkable_title Actions %} + +The API supports the following actions: + +#### {% linkable_title GET /api/ %} + +Returns a message if the API is up and running. + +```json +{ + "message": "API running." +} +``` + +Sample `curl` command: + +```bash +$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ + -H "Content-Type: application/json" http://localhost:8123/api/ +``` + +#### {% linkable_title GET /api/config %} + +Returns the current configuration as JSON. + +```json +{ + "components":[ + "sensor.cpuspeed", + "frontend", + "config.core", + "http", + "map", + "api", + "sun", + "config", + "discovery", + "conversation", + "recorder", + "group", + "sensor", + "websocket_api", + "automation", + "config.automation", + "config.customize" + ], + "config_dir":"/home/ha/.homeassistant", + "elevation":510, + "latitude":45.8781529, + "location_name":"Home", + "longitude":8.458853651, + "time_zone":"Europe/Zurich", + "unit_system":{ + "length":"km", + "mass":"g", + "temperature":"\u00b0C", + "volume":"L" + }, + "version":"0.56.2", + "whitelist_external_dirs":[ + "/home/ha/.homeassistant/www", + "/home/ha/.homeassistant/" + ] +} +``` + +Sample `curl` command: + +```bash +$ 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 %} + +Returns basic information about the Home Assistant instance as JSON. + +```json +{ + "base_url": "http://192.168.0.2:8123", + "location_name": "Home", + "requires_api_password": true, + "version": "0.56.2" +} +``` + +Sample `curl` command: + +```bash +$ 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 %} + +Returns an array of event objects. Each event object contains event name and listener count. + +```json +[ + { + "event": "state_changed", + "listener_count": 5 + }, + { + "event": "time_changed", + "listener_count": 2 + } +] +``` + +Sample `curl` command: + +```bash +$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ + -H "Content-Type: application/json" http://localhost:8123/api/events +``` + +#### {% linkable_title GET /api/services %} + +Returns an array of service objects. Each object contains the domain and which services it contains. + +```json +[ + { + "domain": "browser", + "services": [ + "browse_url" + ] + }, + { + "domain": "keyboard", + "services": [ + "volume_up", + "volume_down" + ] + } +] +``` + +Sample `curl` command: + +```bash +$ 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> %} + +Returns an array of state changes in the past. Each object contains further details for the entities. + +The `+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 %} + +Render a Home Assistant template. [See template docs for more information.](/topics/templating/) + +```json +{ + "template": "Paulus is at {% raw %}{{ states('device_tracker.paulus') }}{% endraw %}!" +} +``` + +Returns the rendered template in plain text. + +```text +Paulus is at work! +``` + +Sample `curl` command: + +```bash +$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ + -H "Content-Type: application/json" \ + -d '{"template": "It is {{ now }}!"}' http://localhost:8123/api/template +``` + +#### {% linkable_title POST /api/event_forwarding %} + +Set up event forwarding to another Home Assistant instance. + +Requires a JSON object that represents the API to forward to. + +```javascript +{ + "host": "machine", + "api_password": "my_super_secret_password", + "port": 8880 // optional +} +``` + +It will return a message if event forwarding was set up successfully. + +```json +{ + "message": "Event forwarding setup." +} +``` + +#### {% linkable_title DELETE /api/event_forwarding %} + +Cancel event forwarding to another Home Assistant instance.
+If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE.
+
+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 %} + ++All commands below need to be run from inside the home-assistant-polymer repository. +
+ +Home Assistant will by default serve the compiled version of the frontend from the hass_frontend Python package. For development you want to work with the unbundled source files which are in the home-assistant-polymer repository. + +First step is to configure Home Assistant to use the development mode for the frontend. Do this by updating the frontend config in your `configuration.yaml` and set the path to the polymer repo: + +```yaml +frontend: + development_repo:
+ 
+ The more info dialog for a light allows the user to control the color and the brightness.
+
Hello {% raw %}{{who}}{% endraw %}. Greetings from Home Assistant.
+ ++Some browsers don't support latest ECMAScript standards, these require a separate ES5 compatible file (`extra_html_url_es5`). +
+ +For more possibilities, see the [Custom UI section](/cookbook/#user-interface) on our Examples page. diff --git a/docs/hassio_addon_communication.md b/docs/hassio_addon_communication.md new file mode 100644 index 00000000000..3a4f57fb8b0 --- /dev/null +++ b/docs/hassio_addon_communication.md @@ -0,0 +1,41 @@ +--- +layout: page +title: "Add-On Communication" +description: "Description of the internal communication of Hass.io." +date: 2017-04-30 13:28 +sidebar: true +comments: false +sharing: true +footer: true +redirect_from: /hassio/addon_config/ +--- + +There are different ways for communication between add-ons inside Hass.io. + +## {% linkable_title Network %} + +We use an internal network that allows to communicate with every add-on, even to/from Home Assistant, by using its name or alias. Only the add-ons which run on the host network are a bit limited. These can talk with all internal add-ons by their name but all other add-on can't address these add-on by name - using an alias works for both! + +Name/alias are used for communication inside Hass.io. +The name is generated using the following format: `{REPO}_{SLUG}`, e.g., `local_xy` or `3283fh_myaddon`. In this example, `{SLUG}` is defined in an add-ons `config.json`. You can use this name also as DNS name but you need replace the `_` with `-` to have a valid hostname. If an add-on is installed locally, `{REPO}` will be `local`. If the add-on is installed from a Github repository, `{REPO}` is a hashed identifier generated from the GitHub repository's URL (ex: https://github.com/xy/my_hassio_addons). See [here](https://github.com/home-assistant/hassio/blob/587047f9d648b8491dc8eef17dc6777f81938bfd/hassio/addons/utils.py#L17) to understand how this identifier is generated. Note that this identifier is required in certain service calls that use the [Hass.io add-on API](hassio-addon-api). You can view the repository identifiers for all currently installed add-ons via a GET request to the hassio API `addons` endpoint. + +Use `hassio` for communication with the internal API. + +## {% linkable_title Home Assistant %} + +An add-on can talk to the [Home Assistant API][hass-api] using the internal proxy. That makes it very easy to communicate with the API without knowing the password, port or any other information of the Home Assistant instance. Use this URL: `http://hassio/homeassistant/api` and internal communication is redirected to the right place. The next stept is to add `homeassistant_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN` and use this as Home-Assistant password. + +There is also a proxy for the [Home Assistant Websocket API][hass-websocket]. It works like the API proxy above and requires `HASSIO_TOKEN` as password. Use this URL: `http://hassio/homeassistant/websocket`. + +It is also possible to talk direct to the Home Assistant instance which is named `homeassistant` over the internal network. But you need to know the configuration that is used by the running instance. + +We have severals services for Hass.io inside Home Assistant to run tasks. To send data over STDIN to an add-on use the `hassio.addon_stdin` service. + +## {% linkable_title Hass.io API %} + +To enables calls to the [Hass.io API][hassio-api], add `hassio_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN`. Now you can use the API over the URL: `http://hassio/`. Use the `HASSIO_TOKEN` with header `X-HASSIO-KEY`. + +[hass-api]: /developers/rest_api/ +[hass-websocket]: /developers/websocket_api/ +[hassio-api]: https://github.com/home-assistant/hassio/blob/master/API.md +[hassio-addon-api]: https://github.com/home-assistant/hassio/blob/dev/API.md#restful-for-api-addons diff --git a/docs/hassio_addon_config.md b/docs/hassio_addon_config.md new file mode 100644 index 00000000000..bc4870f8621 --- /dev/null +++ b/docs/hassio_addon_config.md @@ -0,0 +1,207 @@ +--- +layout: page +title: "Add-On Configuration" +description: "Steps on how-to create an add-on for Hass.io." +date: 2017-04-30 13:28 +sidebar: true +comments: false +sharing: true +footer: true +redirect_from: /hassio/addon_config/ +--- + +Each add-on is stored in a folder. The file structure looks like this: + +```text +addon_name/ + build.json + CHANGELOG.md + config.json + Dockerfile + icon.png + logo.png + README.md + run.sh +``` + +## {% linkable_title Add-on script %} + +As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things. + +When developing your script: + + - `/data` is a volume for persistent storage. + - `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data. However, you might have to install `jq` as a separate package in your container (see `Dockerfile` below). + +```bash +CONFIG_PATH=/data/options.json + +TARGET="$(jq --raw-output '.target' $CONFIG_PATH)" +``` + +So if your `options` contain +```json +{ "target": "beer" } +``` +then there will be a variable `TARGET` containing `beer` in the environment of your bash file afterwards. + +## {% linkable_title Add-on Docker file %} + +All add-ons are based on Alpine Linux 3.6. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images. + +``` +ARG BUILD_FROM +FROM $BUILD_FROM + +ENV LANG C.UTF-8 + +# Install requirements for add-on +RUN apk add --no-cache jq + +# Copy data for add-on +COPY run.sh / +RUN chmod a+x /run.sh + +CMD [ "/run.sh" ] +``` + +If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include: +``` +LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64|i386|amd64" +``` + +It is possible to use own base image with `build.json` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`. + +### {% linkable_title Build Args %} + +We support the following build arguments by default: + +| ARG | Description | +|-----|-------------| +| BUILD_FROM | Hold image for dynamic builds or buildings over our systems. +| BUILD_VERSION | Add-on version (read from `config.json`). +| BUILD_ARCH | Hold current build arch inside. + +## {% linkable_title Add-on config %} + +The config for an add-on is stored in `config.json`. + +```json +{ + "name": "xy", + "version": "1.2", + "slug": "folder", + "description": "long description", + "arch": ["amd64"], + "url": "website with more information about add-on (ie a forum thread for support)", + "startup": "application", + "boot": "auto", + "ports": { + "123/tcp": 123 + }, + "map": ["config:rw", "ssl"], + "options": {}, + "schema": {}, + "image": "repo/{arch}-my-custom-addon" +} +``` + +| Key | Type | Required | Description | +| --- | ---- | -------- | ----------- | +| name | string | yes | Name of the add-on +| version | string | yes | Version of the add-on +| slug | string | yes | Slug of the add-on +| description | string | yes | Description of the add-on +| arch | list | no | List of supported arch: `armhf`, `aarch64`, `amd64`, `i386`. Default all. +| url | url | no | Homepage of the addon. Here you can explain the add-ons and options. +| startup | bool | yes | `initialize` will start addon on setup of Hass.io. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon. +| webui | string | no | A URL for web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the proto part to a config options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and he lookup if they is True and going to `https`. +| boot | string | yes | `auto` by system and manual or only `manual` +| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`. +| host_network | bool | no | If that is True, the add-on run on host network. +| host_ipc | bool | no | Default False. Allow to share the IPC namespace with others. +| host_dbus | bool | no | Default False. Map Host dbus service into add-on. +| devices | list | no | Device list to map into the add-on. Format is: `
+If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: error creating aufs mount to /var/lib/docker/aufs/mnt/. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: "storage-driver" : "aufs".
+
+
+With Samba add-on enabled, you can browse to your Hass.io server over the local network. It will contain an addons folder to store your local add-ons.
+
+
+Once you SSH into your Hass.io box, you have access to your add-ons in "/addons".
+
+
+From the Hass.io main panel open the add-on store.
+
+
+The Hass.io add-on store will list all available local add-ons.
+
+
+The add-on will print Hello world to the logs and then quit.
+
+
+The Python 3 server will allow you to browse the /data folder.
+
+ 
+ Architecture overview of Hass.io
+
+This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is for developers of Hass.io. Do not ask for support if you are using these options. +
+ +[SSH add-on]: /addons/ssh/ + +The following debug tips and tricks are for people who are running the Hass.io image and are working on the base image. If you use the generic Linux installer script, you should be able to access your host and logs as per your host. + +## {% linkable_title SSH access to the host %} + +Create an `authorized_keys` file containing your public key, and place it in the root of the boot partition of your SD card. Once the device is booted, you can access your device as root over SSH on port 22222. + +Windows instructions how to generate and use private/public keys with Putty are [here][windows-keys]. Instead of the droplet instructions, add the public key as per above instructions. + +Alternative instructions, for Mac, Windows and Linux can be found [here](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#platform-mac). + +Follow steps 1-4 under 'Generating a new SSH key' (The other sections are not applicable to Hass.io and can be ignored.) + +Step 3 in the link above, shows the path to the private key file `id_rsa` for your chosen operating system. Your public key, `id_rsa.pub`, is saved in the same folder. Next, select all text from text box "Public key for pasting into OpenSSH authorized_keys file" and save it to the root of your SD card as `authorized_keys`. + ++Make sure when you are copying the public key to the root of the /resin-boot partition of the SD card that you rename the file correctly to `authorized_keys` with no `.pub` file extension. +
+ +You should then be able to SSH into your Hass.io device. On mac/linux, use: +``` +ssh root@hassio.local -p 22222 +``` + +## {% linkable_title Checking the logs %} + +```bash +# Logs from the supervisor service on the Host OS +journalctl -f -u resin-supervisor.service + +# Hass.io supervisor logs +docker logs resin_supervisor + +# Home Assistant logs +docker logs homeassistant +``` + +[windows-keys]: https://www.digitalocean.com/community/tutorials/how-to-use-ssh-keys-with-putty-on-digitalocean-droplets-windows-users diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000000..c801866e6aa --- /dev/null +++ b/docs/index.md @@ -0,0 +1,26 @@ +--- +layout: page +title: "Developers" +description: "Everything you need to know to get started with Home Assistant development." +date: 2016-04-16 10:28 +07:00 +sidebar: true +comments: false +sharing: true +footer: true +og_image: /images/architecture/component_interaction.png +--- + +Welcome to the Home Assistant development documentation. This is the place to learn all about how Home Assistant works and how you can extend it with support for your devices and services! + +
+
+Diagram showing interaction between components and the Home Assistant core.
+
+
+Architectural overview of intents in Home Assistant
+
+The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon. +
+ +## {% linkable_title Translation placeholders %} + +Some translation strings will contain special placeholders that will be replaced later. Placeholders shown in square brackets `[]` are [Lokalise key references](https://docs.lokalise.co/article/KO5SZWLLsy-key-referencing). These are primarily used to link translation strings that will be duplicated. Different languages may not have the same duplicates as English, and are welcome to link duplicate translations that are not linked in English. Placeholders shown in curly brackets `{}` are [translation arguments](https://formatjs.io/guides/message-syntax/) that will be replaced with a live value when Home Assistant is running. Any translation argument placeholders present in the original string must be included in the translated string. These may include special syntax for defining plurals or other replacement rules. The linked format.js guide explains the syntax for adding plural definitions and other rules. + +## {% linkable_title Rules %} +1. Only native speakers should submit translations. +2. Stick to [Material Design guidelines](https://material.io/guidelines/style/writing.html). +3. Don't translate or change proper nouns like `Home Assistant`, `Hass.io` or `Hue`. +4. For a region specific translation, keys that will be the same as the base translation should be filled with `[VOID]`. These will be replaced during our translation build process. +5. Translations under the `state_badge` keys will be used for the notification badge display. These translations should be short enough to fit in the badge label without overflowing. This can be tested in the Home Assistant UI either by editing the label text with your browsers development tools, or by using the States
developer tool in the Home Assistant UI. In the UI, enter a new entity ID (`device_tracker.test`), and enter the text you want to test in state.
+6. If text will be duplicated across different translation keys, make use of the Lokalise key reference feature where possible. The base translation provides examples of this underneath the `states` translations. Please see the [Lokalise key referencing](https://docs.lokalise.co/article/KO5SZWLLsy-key-referencing) documentation for more details.
+
+## {% linkable_title Adding a new language %}
+If your language is not listed you can request it at [GitHub](https://github.com/home-assistant/home-assistant-polymer/issues/new). Please provide both the English name and the native name for your language. For example:
+```
+English Name: German
+Native Name: Deutsch
+```
+
++Region specific translations (`en-US`, `fr-CA`) will only be included if translations for that region need to differ from the base language translation. +
+ +### {% linkable_title Maintainer steps to add a new language %} +1. Language tags have to follow [BCP 47](https://tools.ietf.org/html/bcp47). A list of most language tags can be found here: [IANA sutbtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). Examples: `fr`, `fr-CA`, `zh-Hans`. Only include the country code if country specific overrides are being included, and the base language is already translated. +2. Add the language tag and native name in `src/translations/translationMetadata.json`. Examples: "Français", "Français (CA)" +3. Add the new language in Lokalize. +Note: Sometimes you have to change the tag in Lokalise (Language -> Language settings -> custom ISO code). diff --git a/docs/maintenance.md b/docs/maintenance.md new file mode 100644 index 00000000000..4995e7de51c --- /dev/null +++ b/docs/maintenance.md @@ -0,0 +1,52 @@ +--- +layout: page +title: "Maintenance" +description: "Steps involved to maintain the current state of Home Assistant." +date: 2016-09-13 17:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +This page documents a couple of points for maintaining the Home Assistant code. Most of the tasks don't need to be performed on a regular base thus the steps, used tools, or details are preserved here. + +## {% linkable_title Source code %} + +### {% linkable_title Line separator %} + +People are using various operating systems to develop components and platforms for Home Assistant. This could lead to different line endings on file. We prefer `LN`. Especially Microsoft Windows tools tend to use `CRLF`. + +```bash +$ find homeassistant -name "*.py" -exec file {} \; | grep BOM +$ find homeassistant -name "*.py" -exec file {} \; | grep CRLF +``` + +To fix the line separator, use `dos2unix` or `sed`. + +```bash +$ dos2unix homeassistant/components/notify/kodi.py +``` + +### {% linkable_title File permissions %} + +Most files don't need to the be executable. `0644` is fine. + +### {% linkable_title Dependencies %} + +A lot of components and platforms depends on third-party Python modules. The dependencies which are stored in the `requirements_*.txt` files are tracked by [gemnasium](https://gemnasium.com/github.com/home-assistant/home-assistant) and [Requires.io](https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev). + +If you update the requirements of a component/platform through the `REQUIREMENTS = ['modules-xyz==0.3']` entry, run the provided script to update the `requirements_*.txt` file(s). + +```bash +$ script/gen_requirements_all.py +``` + +Start a test run of Home Assistant. If that was successful, include all files in a Pull Request. Add a short summary of the changes, a sample configuration entry, details about the tests you performed to ensure the update works, and other useful information to the description. + + +## {% linkable_title Documentation %} + +- Merge `current` into `next` on a regular base. +- Optimize the images. + diff --git a/docs/platform_example_light.md b/docs/platform_example_light.md new file mode 100644 index 00000000000..8a11eec73f5 --- /dev/null +++ b/docs/platform_example_light.md @@ -0,0 +1,124 @@ +--- +layout: page +title: "Example light platform" +description: "Minimum implementation of a Home Assistant platform." +date: 2016-04-16 14:24 -07:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +This example is for adding support for the imaginary Awesome Lights. It shows the different best practices for developing a platform. + +Similar to Example Sensor Platform, copy the code below, and create it as a file in `This project is maintained by a dedicated group of people.
+This project is used by all these people
+This project is used by many folks
+Are you using this project?
+ + Add your company + +