jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-09 18:36:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Tag 96

Browse Source
This commit is contained in:
Paulus Schoutsen 2019-07-20 09:39:19 -07:00
parent 5cb80561bf
commit 857ddd6c5e
10 changed files with 999 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
website/blog/2019-07-19-building-all-the-things.md
View File

@ -4,7 +4,6 @@ authorURL: https://twitter.com/balloob
authorImageURL: /img/profile/paulus.jpg
authorTwitter: balloob
title: Building All The Things
image: /img/en/blog/2019-07-building-all-the-things/social.png
---
_How Home Assistant is using Azure Pipelines to automate all the things._

22
website/i18n/en.json
View File

@ -1548,6 +1548,28 @@
},
"version-0.95.0/version-0.95.0-hassio_debugging": {
"title": "Debugging Hass.io"
},
"version-0.96.0/version-0.96.0-asyncio_categorizing_functions": {
"title": "Categorizing Functions"
},
"version-0.96.0/version-0.96.0-development_environment": {
"title": "Set up Development Environment"
},
"version-0.96.0/version-0.96.0-documentation_create_page": {
"title": "Create a new page"
},
"version-0.96.0/version-0.96.0-documentation_index": {
"title": "Documentation"
},
"version-0.96.0/version-0.96.0-documentation_standards": {
"title": "Standards"
},
"version-0.96.0/version-0.96.0-entity_climate": {
"title": "Climate Entity",
"sidebar_label": "Climate"
},
"version-0.96.0/version-0.96.0-hassio_addon_config": {
"title": "Add-On Configuration"
}
},
"links": {

69
website/versioned_docs/version-0.96.0/asyncio_categorizing_functions.md Normal file
View File

@ -0,0 +1,69 @@
---
title: Categorizing Functions
id: version-0.96.0-asyncio_categorizing_functions
original_id: asyncio_categorizing_functions
---
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_`.
## The coroutine function
Coroutines are special functions based on Python’s generators syntax which allows them to suspend execution while waiting on a result.
Invoking a coroutine function will return a Generator object back, but will not actually begin execution. This object will execute the task when it is either awaited (from within another coroutine) or it is scheduled on the event loop.
To declare a function a coroutine, add `async` before the `def` of the function definition.
```python
async def async_look_my_coroutine(target):
result = await entity.async_turn_on()
if result:
print("hello {}".format(target))
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 `await 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.
## 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.
To declare a function as a callback, import the callback annotation from the core package and annotate your function.
A common use case for a callback in Home Assistant is as a listener for an event or a service call. It can process the incoming information and then schedule the right calls to be made. Example from the automation component.
```python
from homeassistant.core import callback
@callback
def async_trigger_service_handler(service_call):
"""Handle automation trigger service calls."""
vars = service_call.data.get(ATTR_VARIABLES)
for entity in component.async_extract_from_service(service_call):
hass.loop.create_task(entity.async_trigger(vars, True))
```
In this example, `entity.async_trigger` is a coroutine function. Invoking the coroutine function will return a coroutine task. The passed in parameters will be used when the task gets executed.
To execute the task we have to schedule it for execution on the event loop. This is done by calling `hass.loop.create_task`.
### 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.
## 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.
## 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.
There is no special annotation necessary to be considered part of this category.

147
website/versioned_docs/version-0.96.0/development_environment.md Normal file
View File

@ -0,0 +1,147 @@
---
title: Set up Development Environment
id: version-0.96.0-development_environment
original_id: development_environment
---
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.
## Preparing your environment
### Developing on Linux
Install the core dependencies.
```bash
$ sudo apt-get install python3-pip python3-dev python3-venv
```
In order to run `script/setup` below you will need some more dependencies.
```bash
$ sudo apt-get install autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev
$ sudo apt-get install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-dev
```
> 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 python36 python36-devel mysql-devel gcc`
Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](frontend_index.md) section to learn more.
### Developing on Windows
Due to Home Assistant is mainly designed and developed on Linux distributions, on Windows 10 you can setup a [Linux subsystem](https://docs.microsoft.com/windows/wsl/install-win10).
Open Powershell as an Administrator and run
```bash
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```
From Windows Store install Ubuntu.
When the Linux subsystem is set up, perform install as for Linux.
```bash
$ sudo apt-get update
$ sudo apt-get install python3-pip python3-dev python3-venv
$ sudo apt-get install autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev
$ sudo apt-get install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-dev
```
Hint: Git is included in Linux subsytem.
When invoking your installation (see below), make sure to specify a folder for configuration which is accessible from Windows.
```bash
$ mkdir -p ../config
$ hass -c ../config
```
### Developing on macOS
Install [Homebrew](https://brew.sh/), then use that to install Python 3:
```bash
$ brew install python3 autoconf
```
Then install ffmpeg:
```bash
$ brew install ffmpeg
```
### Developing with devcontainer
The devcontainer is a preconfigured development environment with all the tools you need.
**Prerequisites**
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Docker](https://docs.docker.com/install/)
- [Visual Studio code](https://code.visualstudio.com/)
- [Remote - Containers (VSC Extension)](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
[More info about requirements and devcontainer in general](https://code.visualstudio.com/docs/remote/containers#_getting-started)
**Getting started:**
1. Fork the repository.
1. Clone the repository to your computer.
1. Open the repository using Visual Studio code.
When you open this repository with Visual Studio code you are asked to "Reopen in Container", this will start the build of the container.
_If you don't see this notification, open the command pallet and select `Remote-Containers: Reopen Folder in Container`._
The devcontainter comes with some useful tasks to help you with development, you can start these tasks by opening the command pallet and select `Tasks: Run Task` then select the task you want to run.
Running tasks like `Preview` can be restarted by opening the command pallet and selecting `Tasks: Restart Running Task`, then select the task you want to restart.
## 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
```
## 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 venv
$ source venv/bin/activate
```
Install the requirements with a provided script named `setup`.
```bash
$ script/setup
```
Invoke your installation, adjusting the [configuration](https://www.home-assistant.io/docs/configuration/) if required.
```bash
$ hass
```
## 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](https://www.home-assistant.io/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on:
```yaml
logger:
default: info
logs:
homeassistant.core: debug
nest.nest: debug
asyncio: debug
homeassistant.components.cloud.iot: debug
```

135
website/versioned_docs/version-0.96.0/documentation_create_page.md Normal file
View File

@ -0,0 +1,135 @@
---
title: Create a new page
id: version-0.96.0-documentation_create_page
original_id: documentation_create_page
---
For a platform or integration page, the fastest way is to make a copy of an existing page and edit it. The [Integration overview](https://www.home-assistant.io/components/) and the [Examples section](https://www.home-assistant.io/cookbook/) are generated automatically, so there is no need to add a link to those pages.
Please honor the [Standards](documentation_standards.md) 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
---
title: "Awesome Sensor"
description: "home-assistant.io web presence"
ha_release: "0.38"
ha_category: Sensor
ha_iot_class: "Local Polling"
ha_qa_scale: silver
ha_config_flow: true
---
Content... Written in markdown.
### Title Header
...
```
Additional keys for the file header:
- `logo`: Please check the separate section below.
- `ha_release`: The release when the integration was included, e.g., "0.38". 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`: This entry is used to group the integration on the [Integration overview](https://www.home-assistant.io/components/).
- `ha_iot_class`: [IoT class](https://www.home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things) is the classifier for the device's behavior.
- `ha_qa_scale`: [Quality scale](https://www.home-assistant.io/docs/quality_scale/) is the representation of the integration's quality.
- `ha_config_flow`: Set to `true` if the integration has a [Data Entry Flow](https://developers.home-assistant.io/docs/en/data_entry_flow_index.html), omit otherwise.
There are [pre-defined 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.
- Add screenshots to support the user where it makes sense.
- Add the type of the device(s) (incl. firmware) you have tested when you know that there are multiple out there.
### 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 `{% configuration %} ... {% endconfiguration %}` tag.
```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: map
keys:
weather:
description: A human-readable text summary.
temperature:
description: The current temperature.
{% endconfiguration %}
```
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: `boolean`, `string`, `integer`, `float`, `time`, `template`, `device_class`, `icon` or `map`/`list` (for a list of entries). For multiple possibilities use `[string, integer]`. If you use `map`/`list` then should define `keys:` (see the [`template` sensor](https://www.home-assistant.io/components/sensor.template/) for an example). If you use `boolean`, then `default:` must be defined.
- **`default:`**: The default value for the variable.
### 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 back-ticks.
When you're writing code that is to be executed on the terminal, do not prefix them with `$`, since this makes it hard to copy and paste the commands. However, an exception is made when there is a need to distinguish between typed commands and command output. In those cases, prefixing the commands with a `$` is required.
### Templates
For the [configuration templating](https://www.home-assistant.io/docs/configuration/templating/) [Jinja](http://jinja.pocoo.org/) is used. Check the [Documentation Standards](documentation_standards.md) for further details.
If you are don't escape templates then they will be rendered and appear blank on the website.
### HTML
The direct usage of HTML is supported but not recommended. The note boxes are an exception.
```html
<div class='note warning'>
You need to enable telnet on your router.
</div>
```
Please note, if you want to use Markdown inside an HTML block, it has to be surrounded by a new line.
```html
<div class='note warning'>
You need to enable [**telnet**](https://en.wikipedia.org/wiki/Telnet) on your router.
</div>
```
### 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, integration, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).
### 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 `source/_includes/asides/docs_navigation.html`.

53
website/versioned_docs/version-0.96.0/documentation_index.md Normal file
View File

@ -0,0 +1,53 @@
---
title: Documentation
id: version-0.96.0-documentation_index
original_id: documentation_index
---
The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section here is the place where we provide documentation and additional details about creating or modifying content.
The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](http://github.com/mojombo/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know 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. You work on your change and propose it via a Pull Request (PR).
Once you've created a Pull Request (PR), you can see a preview of the proposed changes by clicking *Details* against Netlify checker in the checkers section of the PR as soon as deployment is complete.
For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process of working on the website is no different from working on Home Assistant itself.
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.5.0 or higher is required.
- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler` (You might have to run this command as `sudo`).
- Fork the home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.io).
- In your home-assistant.io root directory, run `$ bundle` to install the gems you need.
- Shortcut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle`
- Shortcut for Debian/Ubuntu: `$ sudo apt-get install ruby ruby-dev ruby-bundler ruby-json g++ zlib1g-dev && bundle`
Then you can work on the documentation:
- Run `bundle exec rake generate` to generate the very first preview. This will take a minute.
- Create/edit/update a page. The integration/platforms documentation is located in `source/_components/`. `source/_docs/` contains the Home Assistant documentation itself.
- Test your changes to home-assistant.io locally: run `bundle exec rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000). While this command is working, any changes to a file are automatically detected and will update the affected pages. You will have to manually reload them in the browser though.
- Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is a new feature, platform, or integration.
- Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
The site generated by `bundle exec rake` is only available locally. If you are developing on a headless machine, use port forwarding:
```bash
$ ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine
```
## Speeding up site generation
Every release we post long changelogs to the website. This slows down generation of the website a bit. We've include some tools to temporarily exclude integrations and blog posts that you're not working on out of the way.
```bash
bundle exec rake isolate[filename-of-blogpost-or-integration]
```
When you're done working on the site, run the following command to move the pages back again:
```bash
bundle exec rake integrate
```

123
website/versioned_docs/version-0.96.0/documentation_standards.md Normal file
View File

@ -0,0 +1,123 @@
---
title: Standards
id: version-0.96.0-documentation_standards
original_id: documentation_standards
---
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.
## General Documentation
* The language of the documentation should be American-English.
* Don't put two spaces after a period and avoid the "Oxford comma".
* There is no limit for the line length. You are allowed to write in a flowing text style. This will make it easier to use the GitHub online editor in the future.
* Be objective and not gender favoring, polarizing, race related or religion inconsiderate.
* The case of brand names, services, protocols, integrations 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".
* Do not use ALL CAPITALS for emphasis - use italics instead.
## Integration and Platform Pages
* The **Configuration Variables** section must use the `{% configuration %}` tag.
* Configuration variables must document the requirement status (`false` or `true`).
* Configuration variables must document the default value, if any.
* Configuration variables must document the accepted value types (see [Configuration variables details](documentation_create_page.md#configuration)).
* 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.
* Integration and platform names should be a link to their respective documentation pages.
Example configuration block
```yaml
{% configuration %}
some_key:
description: This is a description of what this key is for.
required: false
type: string
default: Optional default value - leave out if there isn't one
{% endconfiguration %}
```
## Templates
* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the `{% raw %}` 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`
## Renaming Pages
It can happen that a integration 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 integration/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/).
## 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).
### Examples
#### Double Quotes Outside, Single Quotes Inside (Valid)
```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 %}"
```
#### Single Quotes Outside, Double Quotes Inside (Invalid)
```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 %}'
```
#### Multi-Line Template (Valid)
```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 %}
```

221
website/versioned_docs/version-0.96.0/entity_climate.md Normal file
View File

@ -0,0 +1,221 @@
---
title: Climate Entity
sidebar_label: Climate
id: version-0.96.0-entity_climate
original_id: entity_climate
---
A climate entity is a device that controls temperature, humidity, or fans, such as A/C systems and humidifiers. Derive entity platforms from [`homeassistant.components.climate.ClimateDevice`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/climate/__init__.py)
## Properties
> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
| Name | Type | Default | Description |
| ----------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| temperature_unit | string | `NotImplementedError` | The unit of temperature measurement for the system (`TEMP_CELSIUS` or `TEMP_FAHRENHEIT`). |
| precision | float | Based on `temperature_unit` | The precision of the temperature in the system. Defaults to tenths for TEMP_CELSIUS, whole number otherwise. |
| current_temperature | float | None | The current temperature. |
| current_humidity | float | None | The current humidity. |
| target_temperature | float | None | The temperature currently set to be reached. |
| target_temperature_high | float | None | The upper bound target temperature |
| target_temperature_low | float | None | The lower bound target temperature |
| target_temperature_step | float | None | The supported step size a target temperature can be increased/decreased |
| target_humidity | float | None | The target humidity the device is trying to reach. Requires `SUPPORT_TARGET_HUMIDITY`. |
| max_temp | int | `DEFAULT_MAX_TEMP` (value == 35) | Returns the maximum temperature. |
| min_temp | int | `DEFAULT_MIN_TEMP` (value == 7) | Returns the minimum temperature. |
| max_humidity | int | `DEFAULT_MAX_HUMIDITY` (value == 99) | Returns the maximum humidity. Requires `SUPPORT_TARGET_HUMIDITY`. |
| min_humidity | int | `DEFAULT_MIN_HUMIDITY` (value == 30) | Returns the minimum humidity. Requires `SUPPORT_TARGET_HUMIDITY`. |
| hvac_mode | string | `NotImplementedError()` | The current operation (e.g. heat, cool, idle). Used to determine `state`. |
| hvac_action | string | None | The current HVAC action (heating, cooling) |
| hvac_modes | list | `NotImplementedError()` | List of available operation modes. See below. |
| preset_mode | string | `NotImplementedError()` | The current active preset. Requires `SUPPORT_PRESET_MODE`. |
| preset_modes | list | `NotImplementedError()` | The available presets. Requires `SUPPORT_PRESET_MODE`. |
| fan_mode | string | `NotImplementedError()` | Returns the current fan mode. Requires `SUPPORT_FAN_MODE`. |
| fan_modes | list | `NotImplementedError()` | Returns the list of available fan modes. Requires `SUPPORT_FAN_MODE`. |
| swing_mode | string | `NotImplementedError()` | Returns the fan setting. |
| swing_modes | list | `NotImplementedError()` | Returns the list of available swing modes. |
| is_aux_heat | bool | None | Returns True if an auxiliary heater is on. Requires `SUPPORT_AUX_HEAT`. |
| supported_features | int | `NotImplementedError()` | Bitmap of supported features. See below. |
### HVAC modes
You are only allowed to use the built-in HVAC modes. If you want another mode, add a preset instead.
| Name | Description |
| --------------------- | ------------------------------------------------------------------- |
| `HVAC_MODE_OFF` | The device is turned off. |
| `HVAC_MODE_HEAT` | The device is set to heat to a target temperature. |
| `HVAC_MODE_COOL` | The device is set to cool to a target temperature. |
| `HVAC_MODE_HEAT_COOL` | The device supports heating/cooling to a range |
| `HVAC_MODE_AUTO` | The device is set to a schedule, learned behavior, AI. |
| `HVAC_MODE_DRY` | The device is set to dry/humidity mode. |
| `HVAC_MODE_FAN_ONLY` | The device only has the fan on. No heating or cooling taking place. |
### HVAC Action
The HVAC action describes the _current_ action. This is different from the mode, because if a device is set to heat, and the target temperature is already achieved, the device will not be actively heating anymore.
| Name | Description |
| ------------------- | --------------------- |
| `CURRENT_HVAC_OFF` | Device is turned off. |
| `CURRENT_HVAC_HEAT` | Device is heating. |
| `CURRENT_HVAC_COOL` | Device is cooling. |
| `CURRENT_HVAC_DRY` | Device is dring. |
| `CURRENT_HVAC_IDLE` | Device is idle. |
### Presets
A device can have different presets that it might want to show to the user. Common presets are "Away" or "Eco". There are a couple of built-in presets that will offer translations, but you're also allowed to add custom presets.
| Name | Description |
| ---------- | ------------------------------------------------------ |
| `ECO` | Device is running an energy-saving mode |
| `AWAY` | Device is in away mode |
| `BOOST` | Device turn all valve full up |
| `COMFORT` | Device is in comfort mode |
| `HOME` | Device is in home mode |
| `SLEEP` | Device is prepared for sleep |
| `ACTIVITY` | Device is reacting to activity (e.g. movement sensors) |
### Fan modes
A device's fan can have different states. There are a couple of built-in fan modes, but you're also allowed to use custom fan modes.
| Name |
| ------------- |
| `FAN_ON` |
| `FAN_OFF` |
| `FAN_AUTO` |
| `FAN_LOW` |
| `FAN_MEDIUM` |
| `FAN_HIGH` |
| `FAN_MIDDLE` |
| `FAN_FOCUS` |
| `FAN_DIFFUSE` |
### Swing modes
The device fan can have different swing modes that it wants the user to know about/control.
| Name | Description |
| ------------------ | ------------------------------------------------ |
| `SWING_OFF` | The fan is not swinging. |
| `SWING_VERTICAL` | The fan is swinging vertical. |
| `SWING_HORIZONTAL` | The fan is swinging horizontal. |
| `SWING_BOTH` | The fan is swingin both horizontal and vertical. |
### Supported features
Supported features constants are combined using the bitwise or (`|`) operator.
| Name | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| `SUPPORT_TARGET_TEMPERATURE` | The device supports a target temperature. |
| `SUPPORT_TARGET_TEMPERATURE_RANGE` | The device supports a ranged target temperature. Used for HVAC modes `heat_cool` and `auto` |
| `SUPPORT_TARGET_HUMIDITY` | The device supports a target humidity. |
| `SUPPORT_FAN_MODE` | The device supports fan modes. |
| `SUPPORT_PRESET_MODE` | The device supports presets. |
| `SUPPORT_SWING_MODE` | The device supports swing modes. |
| `SUPPORT_AUX_HEAT` | The device supports auxiliary heaters. |
## Methods
### Set hvac mode
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def set_hvac_mode(self, hvac_mode):
"""Set new target hvac mode."""
async def async_set_hvac_mode(self, hvac_mode):
"""Set new target hvac mode."""
```
### Set preset mode
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def set_preset_mode(self, preset_mode):
"""Set new target preset mode."""
async def async_set_preset_mode(self, preset_mode):
"""Set new target preset mode."""
```
### Set fan mode
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def set_fan_mode(self, fan_mode):
"""Set new target fan mode."""
async def async_set_fan_mode(self, fan_mode):
"""Set new target fan mode."""
```
### Set humidity
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def set_humidity(self, humidity):
"""Set new target humidity."""
async def async_set_humidity(self, humidity):
"""Set new target humidity."""
```
### Set swing mode
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def set_swing_mode(self, swing_mode):
"""Set new target swing operation."""
async def async_set_swing_mode(self, swing_mode):
"""Set new target swing operation."""
```
### Set temperature
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def set_temperature(self, **kwargs):
"""Set new target temperature."""
async def async_set_temperature(self, **kwargs):
"""Set new target temperature."""
```
### Control auxiliary heater
```python
class MyClimateDevice(ClimateDevice):
# Implement one of these methods.
def turn_aux_heat_on(self):
"""Turn auxiliary heater on."""
async def async_turn_aux_heat_on(self):
"""Turn auxiliary heater on."""
# Implement one of these methods.
def turn_aux_heat_off(self):
"""Turn auxiliary heater off."""
async def async_turn_aux_heat_off(self):
"""Turn auxiliary heater off."""
```

228
website/versioned_docs/version-0.96.0/hassio_addon_config.md Normal file
View File

@ -0,0 +1,228 @@
---
title: Add-On Configuration
id: version-0.96.0-hassio_addon_config
original_id: hassio_addon_config
---
Each add-on is stored in a folder. The file structure looks like this:
```text
addon_name/
apparmor.txt
build.json
CHANGELOG.md
config.json
Dockerfile
icon.png
logo.png
README.md
run.sh
```
## 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.
All our Images have also [bashio][bashio] installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons and therefore making it easier to develop and maintain add-ons.
When developing your script:
- `/data` is a volume for persistent storage.
- `/data/options.json` contains the user configuration. You can use bashio or `jq` inside your shell script to parse this data.
```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.
[bashio]: https://github.com/hassio-addons/bashio
## Add-on Docker file
All add-ons are based on latest Alpine Linux. 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`.
### 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.
## 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 | yes | List of supported arch: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`.
| machine | list | no | Default it support any machine type. You can select that this add-on run only on specific machines.
| 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.
| host_pid | bool | no | Default False. Allow to run container on host PID namespace. Work only for not protected add-ons.
| devices | list | no | Device list to map into the add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
| auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on.
| homeassistant | string | no | Pin a minimum required Home Assistant version for such Add-on. Value is a version string like `0.91.2`.
| hassio_role | str | no | Default `default`. Role based access to Hass.io API. Available: `default`, `homeassistant`, `backup`, `manager`, `admin`.
| hassio_api | bool | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
| homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://hassio/homeassistant/api`.
| docker_api | bool | no | Allow read-oly access to docker API for add-on. Work only for not protected add-ons.
| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE`, `DAC_READ_SEARCH`.
| full_access | bool | no | Give full access to hardware like the privileged mode in docker. Work only for not protected add-ons.
| apparmor | bool/string | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.
| map | list | no | List of maps for additional Hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.
| environment | dict | no | A dict of environment variable to run add-on.
| audio | bool | no | Boolean. Mark this add-on to use internal an audio system. The ALSA configuration for this add-on will be mount automatic.
| gpio | bool | no | Boolean. If this is set to True, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some library need also `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On system with AppArmor enabled, you need disable AppArmor or better for security, provide you own profile for the add-on.
| devicetree | bool | no | Boolean. If this is set to True, `/device-tree` will map into add-on.
| kernel_modules | bool | no | Map host kernel modules and config into add-on (readonly).
| stdin | bool | no | Boolean. If that is enable, you can use the STDIN with Hass.io API.
| legacy | bool | no | Boolean. If the docker image have no hass.io labels, you can enable the legacy mode to use the config data.
| options | dict | yes | Default options value of the add-on
| schema | dict | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options.
| image | string | no | For use with Docker Hub and other container registries.
| timeout | integer | no | Default 10 (second). The timeout to wait until the docker is done or will be killed.
| tmpfs | string | no | Mount a tmpfs file system in `/tmpfs`. Valide format for this option is : `size=XXXu,uid=N,rw`. Size is mandatory, valid units (`u`) are `k`, `m` and `g` and `XXX` has to be replaced by a number. `uid=N` (with `N` the uid number) and `rw` are optional.
| discovery | list | no | A list of services they this Add-on allow to provide for Home Assistant. Currently supported: `mqtt`
| services | list | no | A list of services they will be provided or consumed with this Add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly).
| auth_api | bool | no | Allow access to Home Assistent user backend.
| ingress | bool | no | Enable the ingress feature for the Add-on
| ingress_port | integer | no | Default `8099`. For Add-ons they run on host network, you can use `0` and read the port later on API.
| ingress_entry | string | no | Modify the URL entry point from `/`.
| panel_icon | string | no | Default: mdi:puzzle. MDI icon for the menu panel integration.
| panel_title | string | no | Default add-on name, but can Modify with this options.
| panel_admin | bool | no | Default True. Make menu entry only available with admin privileged.
### Options / Schema
The `options` dictionary contains all available options and their default value. Set the default value to `null` if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put `?` to the end of data type, otherwise it will be a required value.
```json
{
"message": "custom things",
"logins": [
{ "username": "beer", "password": "123456" },
{ "username": "cheep", "password": "654321" }
],
"random": ["haha", "hihi", "huhu", "hghg"],
"link": "http://example.com/",
"size": 15,
"count": 1.2
}
```
The `schema` looks like `options` but describes how we should validate the user input. For example:
```json
{
"message": "str",
"logins": [
{ "username": "str", "password": "str" }
],
"random": ["match(^\w*$)"],
"link": "url",
"size": "int(5,20)",
"count": "float",
"not_need": "str?"
}
```
We support:
- str
- bool
- int / int(min,) / int(,max) / int(min,max)
- float / float(min,) / float(,max) / float(min,max)
- email
- url
- port
- match(REGEX)
## Add-on extended build
Additional build options for an add-on is stored in `build.json`. This file will be read from our build systems.
You need this only, if you not use the default images or need additionals things.
```json
{
"build_from": {
"armhf": "mycustom/base-image:latest"
},
"squash": false,
"args": {
"my_build_arg": "xy"
}
}
```
| Key | Required | Description |
| --- | -------- | ----------- |
| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value.
| squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that!
| args | no | Allow to set additional Docker build arguments as a dictionary.
We provide a set of [Base-Images][hassio-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific Image tag, feel free to pin this requirements for you build with `build_from` option.
[hassio-base]: https://github.com/home-assistant/hassio-base

1
website/versions.json
View File

@ -1,4 +1,5 @@
[
"0.96.0",
"0.95.0",
"0.94.0",
"0.93.0",