jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Merge branch 'current' into next

Browse source
This commit is contained in:
Fabian Affolter 2017-09-30 13:30:14 +02:00
commit c8ec8391f4
No known key found for this signature in database
GPG key ID: DDF3D6F44AAB1336
190 changed files with 787 additions and 379 deletions
Download patch file Download diff file Expand all files Collapse all files

2
source/developers/development_environment.markdown
View file

@ -29,7 +29,7 @@ $ sudo apt-get install libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-de
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`
</p>
Additional dependencies exist if you you plan to perform Frontend Development, please read the [Frontend](https://home-assistant.io/developers/frontend/) section to learn more.
Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](https://home-assistant.io/developers/frontend/) section to learn more.
#### {% linkable_title Developing on Windows %}

80
source/developers/hassio/addon_config.markdown
View file

@ -26,26 +26,27 @@ As with every Docker container, you will need a script to run when the container
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).
- `/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)
TARGET="$(jq --raw-output '.target' $CONFIG_PATH)"
```
So if your `options`contain
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.
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 correct timezone, but that is already add in our base images.
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.
```
FROM %%BASE_IMAGE%%
ARG BUILD_FROM
FROM $BUILD_FROM
ENV LANG C.UTF-8
@ -64,15 +65,17 @@ If you don't use local build on device or our build script, make sure that the D
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 follow schema:
```
#amd64:FROM...
#i386:FROM...
#armhf:FROM...
#aarch64:FROM...
```
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`.
Or if you not want to do a multi arch build/support you can also use a simle 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 %}
@ -106,26 +109,27 @@ The config for an add-on is stored in `config.json`.
| description | yes | Description of the add-on
| arch | no | List of supported arch: `armhf`, `aarch64`, `amd64`, `i386`. Default all.
| url | no | Homepage of the addon. Here you can explain the add-ons and options.
| startup | yes | `initialize` will start addon on setup of hassio. `system` is for things like database and base not on other things. `services` will start before homeassistant. `application` is after homeassistant will start or `once` for application they don't run as deamon.
| webui | no | A URL for webinterface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port need the internal port, we replace it later with the effective port.
| startup | 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 | 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.
| boot | yes | `auto` by system and manual or only `manual`
| ports | no | Network ports to expose from the container. Format is `"container-port/type": host-port`.
| host_network | no | If that is True, the add-on run on host network.
| devices | no | Device list to map into add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
| hassio_api | no | This add-on can access to hass.io REST API. It set the host alias `hassio`.
| devices | 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`
| hassio_api | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
| privileged | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`
| map | no | List of maps for additional hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Default it map it `ro`, you can change that if you add a ":rw" at the end of name.
| map | 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 | no | A dict of environment variable to run add-on.
| audio | no | Mark this add-on to use internal audio system. Environment is `ALSA_INPUT` and `ALSA_OUTPUT` to access the internal information for alsa.
| audio | no | Boolean. Mark this add-on to use internal an audio system. The available environment variables are `ALSA_INPUT` and `ALSA_OUTPUT` which provide internal information to access alsa.
| gpio | 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.
| options | yes | Default options value of the add-on
| schema | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options.
| image | no | For use dockerhub.
| image | no | For use with Docker Hub.
| timeout | no | Default 10 (second). The timeout to wait until the docker is done or will be killed.
| tmpfs | 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.
### {% linkable_title Options / Schema %}
The `options` dict 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. Only non-nested arrays and dictorys are supported.
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. Only non-nested arrays and dictionaries are supported.
```json
{
@ -135,7 +139,9 @@ The `options` dict contains all available options and their default value. Set t
{ "username": "cheep", "password": "654321" }
],
"random": ["haha", "hihi", "huhu", "hghg"],
"link": "http://blebla.com/"
"link": "http://example.com/",
"size": 15,
"count": 1.2
}
```
@ -147,8 +153,10 @@ The `schema` looks like `options` but describes how we should validate the user
"logins": [
{ "username": "str", "password": "str" }
],
"random": ["str"],
"link": "url"
"random": ["match(^\w*$)"],
"link": "url",
"size": "int(5,20)",
"count": "float"
}
```
@ -161,3 +169,25 @@ We support:
- url
- port
- match(REGEX)
## {% linkable_title 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.
```json
{
"build_from": {
"armhf": "homeassistant/armhf-base: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.

23
source/developers/hassio/addon_publishing.markdown
View file

@ -38,35 +38,24 @@ All add-ons are simple docker containers. Inside your add-on `config.json` you s
}
```
You can use `{arch}` inside the image name to support multiple architectures with 1 configuration file. It will be replaced with the architecture of the user when we load the image.
You can use `{arch}` inside the image name to support multiple architectures with 1 configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.json` to overwrite our default args.
Hass.io assumes that the `master` branch of your add-on repository matches the latest tag on Docker Hub. When you're building a new version, it's suggested that you use another branch, ie `build`. After you push the add-on to [Docker Hub](https://hub.docker.com/), you can merge this branch to master.
Hass.io assumes that the `master` branch of your add-on repository matches the latest tag on Docker Hub. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the add-on to [Docker Hub](https://hub.docker.com/), you can merge this branch to master.
## {% linkable_title Custom Add-ons %}
You need a Docker Hub account to make your own add-ons. Download our [build script][builder] and run one of the following commands.
You need a Docker Hub account to make your own add-ons. You can build your docker images with docker `build` command or use our script that make it simple. Pull our [builder docker engine][builder] and run one of the following commands.
For a git repository:
```bash
# Test only:
./create_hassio_addon.sh -a amd64 -s addon-slug -r https://github.com/xy/addons -b branchname
# push to docker hub:
./create_hassio_addon.sh -a amd64 -s addon-slug -r https://github.com/xy/addons -b branchname -p
# create for all supported arch:
./create_addon_all.sh -s addon-slug -r https://github.com/xy/addons -b branchname -p
docker run --rm --privileged -v ~/.docker:/root/.docker homeassistant/amd64-builder --all -t addon-folder -r https://github.com/xy/addons -b branchname
```
For a local repository:
```bash
# Test only:
./create_hassio_addon.sh -a amd64 -s addon-slug -l /home/xy/my_local_repo
# push to docker hub:
./create_hassio_addon.sh -a amd64 -s addon-slug -l /home/xy/my_local_repo -p
docker run --rm --privileged -v ~/.docker:/root/.docker -v /my_addon:/data homeassistant/amd64-builder --all -t /data
```
[builder]: https://github.com/home-assistant/hassio-build/tree/master/build-scripts/addons
[builder]: https://github.com/home-assistant/hassio-build/tree/master/builder

13
source/developers/hassio/addon_testing.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Local add-on testing"
description: "Instructions how to test your add-on locally."
description: "Instructions on how to test your add-on locally."
date: 2017-04-30 13:28
sidebar: true
comments: false
@ -14,23 +14,24 @@ The fastest way to develop add-ons is by adding them to your local add-on reposi
Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). Without `image` inside local add-ons repository it to be built on the device.
## {% linkable_title Local run %}
## {% linkable_title Local build %}
You can build an try the addon on your developer machine also. Move all addon stuff into a temp folder. Replace in the Dockerfile `%%BASE_IMAGE%%` with:
You can build an try the addon on your developer machine also. Move all addon stuff into a temp folder. If you use `FROM $BUILD_FROM` you need set a base image with build args. Normally you can use follow base images:
- armhf: `homeassistant/armhf-base:latest`
- aarch64: `homeassistant/aarch64-base:latest`
- amd64: `homeassistant/amd64-base:latest`
- i386: `homeassistant/i386-base:latest`
Add also a `LABEL io.hass.version="xy"` into your dockerfile.
Use `docker` to build the test addon: `docker build -t local/my-test-addon .`
Use `docker` to build the test addon: `docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" -t local/my-test-addon .`
## {% linkable_title Local run %}
Create a new folder for data and add a test _options.json_ file. After that you can run your add-on with: `docker run --rm -v /tmp/my_test_data:/data -p PORT_STUFF_IF_NEEDED local/my-test-addon`
## {% linkable_title Logs %}
All stdout and stderr is redirected to the Docker logs. The logs can be fetched from the add-on page inside the Hass.io panel in Home Assistant.
All stdout and stderr are redirected to the Docker logs. The logs can be fetched from the add-on page inside the Hass.io panel in Home Assistant.
[Samba add-on]: /addons/samba/
[SSH add-on]: /addons/ssh/

3
source/developers/hassio/addon_tutorial.markdown
View file

@ -41,7 +41,8 @@ Once you have located your add-on directory, it's time to get started!
`Dockerfile`:
```
FROM %%BASE_IMAGE%%
ARG BUILD_FROM
FROM $BUILD_FROM
ENV LANG C.UTF-8

48
source/developers/website.markdown
View file

@ -23,7 +23,7 @@ To test your changes locally, you need to install **Ruby** and its dependencies
- 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 && bundle`
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:
@ -73,20 +73,42 @@ 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.
- Keep the configuration sample minimal by only adding the `Required` options. Full configuration details with further explanations should go into a seperate section.
- The description of all the configuration variables should contains information about the used defaults.
- If you're adding a new component, for the `ha_release` part of the header, just increment off the current release. If the current release is 0.37, make `ha_release` 0.38.
- 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 `" "`.
### {% linkable_title Configuration variables %}
The ***Configuration Variables*** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag.
```text
{% raw %}
{% 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
type: string
{% endconfiguration %}
{% endraw %}
```
- **`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` 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).
### {% linkable_title Embedding Code %}
You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in \`. For multi-line, syntax wrap your code as shown below.
```text
{% raw %} ```yaml
sensor:
platform: template
```{% endraw %}
```
Note that you can replace `yaml` next to \`\`\` with the language that is within the block.
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 `$`.
@ -109,7 +131,7 @@ The direct usage of HTML is supported but not recommended. The note boxes are an
### {% linkable_title Redirects %}
If you rename or move an existing platform or component, create the redirect. Add the old location of the page to the header of the new one.
```test
```text
---
...
redirect_from: /getting-started/android/