Extract developer site (#5249)
* Extract developer site * Fix title in sidebar * Update dev section reference * Update edit in github link on help page
This commit is contained in:
Paulus Schoutsen
GitHub
parent
a83fd1d874
commit
80b268cd65
75 changed files with 282 additions and 4166 deletions
|
|
@ -10,32 +10,6 @@ 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
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_communication.html';
|
||||
</script>
|
||||
|
|
@ -10,198 +10,6 @@ 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: `<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.
|
||||
| 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`.
|
||||
| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`
|
||||
| apparmor | bool | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles.
|
||||
| seccomp | bool | no | Enable or disable Seccomp support. If it is enable, you can also use custom profiles.
|
||||
| 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.
|
||||
| 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.
|
||||
| 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.
|
||||
|
||||
### {% linkable_title 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)
|
||||
|
||||
## {% 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.
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_config.html';
|
||||
</script>
|
||||
|
|
@ -10,14 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/addon_development/
|
||||
---
|
||||
|
||||
Add-ons for Hass.io allow the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Hass.io panel in Home Assistant.
|
||||
|
||||
Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple references to add-ons for easy sharing with the community.
|
||||
|
||||
1. [Tutorial: Making your first add-on](/developers/hassio/addon_tutorial/)
|
||||
1. [Configuration](/developers/hassio/addon_config/)
|
||||
1. [Communication](/developers/hassio/addon_communication/)
|
||||
1. [Local Testing](/developers/hassio/addon_testing/)
|
||||
1. [Publishing](/developers/hassio/addon_publishing/)
|
||||
1. [Presentation](/developers/hassio/addon_presentation/)
|
||||
1. [Repositories](/developers/hassio/addon_repository/)
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_index.html';
|
||||
</script>
|
||||
|
|
@ -9,45 +9,6 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
If you decide to share your add-on to the public, paying attention to details is recommended. Of course, your add-on should have a proper name and description, but Hass.io also gives you some other tools to present your add-on even nicer.
|
||||
|
||||
## {% linkable_title Adding documentation %}
|
||||
|
||||
Good documentation helps the consumer of your add-on to understand its usage, explains configuration options, points users in the right direction in the case they have questions or issues, and contains the license under which the add-on was published.
|
||||
|
||||
This file containing the documentation is usually referred to as the "README", which is generally published as the `README.md` file.
|
||||
|
||||
Take a look at other projects for inspiration. For example, see the `README.md` of the [Community Hass.io Add-ons: Homebridge](https://github.com/hassio-addons/addon-homebridge/blob/master/README.md) add-on.
|
||||
|
||||
In future versions of Hass.io, the `README.md` file will be displayed in the Home Assistant frontend.
|
||||
|
||||
## {% linkable_title Add-on icon & logo %}
|
||||
|
||||
A picture is worth a thousand words. Therefore, your add-on can be improved by adding a proper image icon and logo. Those images are used when showing your add-on in the Home Assistant Hass.io panel and which will significantly improve the visual representation of your add-on.
|
||||
|
||||
Requirements for the logo of your add-on:
|
||||
|
||||
- The logo must be in the Portable Network Graphics format (`.png`).
|
||||
- The filename must be `logo.png`.
|
||||
- It is recommended to keep the logo size around 250x100px. You may choose to use a different size or aspect ratio as you seem fit for your add-on.
|
||||
|
||||
Requirements for the icon of your add-on:
|
||||
|
||||
- The icon must be in the Portable Network Graphics format (`.png`).
|
||||
- The filename must be `icon.png`.
|
||||
- The aspect ratio of the icon must be 1x1 (square).
|
||||
- It is recommended to use an icon size of 128x128px.
|
||||
|
||||
## {% linkable_title Keeping a changelog %}
|
||||
|
||||
It is likely you are going to release newer versions of your add-on in the future. In case that happens, the users of your add-on would see an upgrade notice and probably want to know what changes were made in the latest version.
|
||||
|
||||
A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of your add-on and is generally published as the `CHANGELOG.md` file.
|
||||
|
||||
If you are in need of a guide on keeping a changelog, we would recommend checking the [keep a changelog](http://keepachangelog.com) website. They have developed a standard that is used by many opensource projects around the world.
|
||||
|
||||
In future versions of Hass.io, the `CHANGELOG.md` file will be displayed in the Home Assistant frontend.
|
||||
|
||||
## {% linkable_title Extended Security %}
|
||||
|
||||
You can use own security profile for you Add-on with Seccomp or AppArmor. Default it is enabled and use the docker default profile. Put `apparmor` or `seccomp.json` file into your Add-on folder and it will load this file as primary profile.
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_presentation.html';
|
||||
</script>
|
||||
|
|
@ -10,56 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/addon_publishing/
|
||||
---
|
||||
|
||||
There are two different ways of publishing add-ons. One is to publish pre-build containers to Docker Hub and the other option is to have users build the containers locally on their Hass.io instance.
|
||||
|
||||
#### {% linkable_title Pre-build containers %}
|
||||
|
||||
With pre-build containers, the developer is responsible for building the images for each architecture on their machine and push the results out to Docker Hub. This has a lot of advantages for the user. As a user it will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and almost no chance of failure. This is the preferred method.
|
||||
|
||||
We have automated the process of building and publishing add-ons. See below for the instructions.
|
||||
|
||||
#### {% linkable_title Locally build containers %}
|
||||
|
||||
Starting Hass.io 0.26, it is possible to distribute add-ons that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your add-ons. This method includes installing and potentially compiling code. This means that installing such an add-on is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-build solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available.
|
||||
|
||||
Use this option when you are playing with add-ons and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to Docker Hub as it greatly improves the user experience. In the future we will mark locally built add-ons in the add-on store to warn users.
|
||||
|
||||
## {% linkable_title Build scripts to publish add-ons to Docker Hub %}
|
||||
|
||||
All add-ons are simple docker containers. Inside your add-on `config.json` you specify the Docker image that will be installed for your add-on:
|
||||
|
||||
```json
|
||||
{
|
||||
...
|
||||
|
||||
"image": "myhub/image-{arch}-addon-name",
|
||||
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
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` 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. 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
|
||||
$ 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
|
||||
$ docker run --rm --privileged -v ~/.docker:/root/.docker -v /my_addon:/data homeassistant/amd64-builder --all -t /data
|
||||
```
|
||||
|
||||
<p class='note'>
|
||||
If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: <code>error creating aufs mount to /var/lib/docker/aufs/mnt/<SOME_ID>-init: invalid argument</code>. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: <code>"storage-driver" : "aufs"</code>.
|
||||
</p>
|
||||
|
||||
[builder]: https://github.com/home-assistant/hassio-build/tree/master/builder
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_publishing.html';
|
||||
</script>
|
||||
|
|
@ -10,28 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/addon_repository/
|
||||
---
|
||||
|
||||
An add-on repository can contain one or more add-ons. Each add-on is stored in its own unique folder. To be indentified as a repository, the repository must contain a configuration file.
|
||||
|
||||
Check the [Example add-on repository](https://github.com/home-assistant/hassio-addons-example) for further details.
|
||||
|
||||
## {% linkable_title Installing a repository %}
|
||||
|
||||
A user can add a repository by going to the Hass.io panel in Home Assistant, clicking on the store icon in the top right, copy/paste the URL of your repostory into the repository textarea and click on **Save**.
|
||||
|
||||
## {% linkable_title Repository configuration %}
|
||||
|
||||
Each repository is required to contain `repository.json` at the root in the git repository.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Name of repository",
|
||||
"url": "http://www.example/addons",
|
||||
"maintainer": "HomeAssistant Team <info@home-assistant.io>"
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Required | Description |
|
||||
| --- | -------- | ----------- |
|
||||
| name | yes | Name of the repository
|
||||
| url | no | Homepage of the repository. Here you can explain the various add-ons.
|
||||
| maintainer | no | Contact info of the maintainer.
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_repository.html';
|
||||
</script>
|
||||
|
|
@ -10,28 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/addon_testing/
|
||||
---
|
||||
|
||||
The fastest way to develop add-ons is by adding them to your local add-on repository. To access your local add-on repository, install either the [Samba add-on] or [SSH add-on].
|
||||
|
||||
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 build %}
|
||||
|
||||
You can build and 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`
|
||||
|
||||
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 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/
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_testing.html';
|
||||
</script>
|
||||
|
|
@ -10,199 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/addon_tutorial/
|
||||
---
|
||||
|
||||
So you've got Home Assistant going and you've been enjoying the built-in add-ons but you're missing this one application. Time to make your own add-on! In Hass.io 0.24 we introduced the option to have local add-ons be build on your device. This is great for developing new add-ons locally.
|
||||
|
||||
To get started with developing add-ons, we first need access to where Hass.io looks for local add-ons. For this you can use the Samba add-on or the SSH add-on.
|
||||
|
||||
For Samba, once you have enabled and started it, your Hass.io instance will show up in your local network tab and share a folder called "addons". This is the folder to store your custom add-ons.
|
||||
|
||||
If you are on macOS and the folder is not showing up automatically, go to Finder and press CMD+K then enter 'smb://hassio.local'
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/tutorial/samba.png' />
|
||||
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.
|
||||
</p>
|
||||
|
||||
For SSH, you will have to install it. Before you can start it, you will have to have a private/public key pair and store your public key in the add-on config ([see docs for more info][ssh]). Once started, you can SSH to Hass.io and store your custom add-ons in "/addons".
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/tutorial/ssh.png' />
|
||||
Once you SSH into your Hass.io box, you have access to your add-ons in "/addons".
|
||||
</p>
|
||||
|
||||
Once you have located your add-on directory, it's time to get started!
|
||||
|
||||
[ssh]: /addons/ssh/
|
||||
|
||||
## {% linkable_title Step 1: The basics %}
|
||||
|
||||
- Create a new directory called `hello_world`
|
||||
- Inside that directory create three files.
|
||||
|
||||
`Dockerfile`:
|
||||
```
|
||||
ARG BUILD_FROM
|
||||
FROM $BUILD_FROM
|
||||
|
||||
ENV LANG C.UTF-8
|
||||
|
||||
# Copy data for add-on
|
||||
COPY run.sh /
|
||||
RUN chmod a+x /run.sh
|
||||
|
||||
CMD [ "/run.sh" ]
|
||||
```
|
||||
|
||||
`config.json`:
|
||||
```json
|
||||
{
|
||||
"name": "Hello world",
|
||||
"version": "1",
|
||||
"slug": "hello_world",
|
||||
"description": "My first real add-on!",
|
||||
"startup": "before",
|
||||
"boot": "auto",
|
||||
"options": {},
|
||||
"schema": {}
|
||||
}
|
||||
```
|
||||
|
||||
`run.sh`:
|
||||
```bash
|
||||
echo Hello world!
|
||||
```
|
||||
|
||||
## {% linkable_title Step 2: Installing and testing your add-on %}
|
||||
|
||||
Now comes the fun part, time to open the Hass.io UI and install and run your add-on.
|
||||
|
||||
- Open the Home Assistant frontend
|
||||
- Go to the Hass.io panel
|
||||
- On the top right click the shopping basket to go to the add-on store.
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/screenshots/main_panel_addon_store.png' />
|
||||
From the Hass.io main panel open the add-on store.
|
||||
</p>
|
||||
|
||||
- On the top right click the refresh button
|
||||
- You should now see a new card called "Local" that lists your add-on!
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/screenshots/local_repository.png' />
|
||||
The Hass.io add-on store will list all available local add-ons.
|
||||
</p>
|
||||
|
||||
- Click on your add-on to go to the add-on details page.
|
||||
- Install your add-on
|
||||
- Start your add-on
|
||||
- Refresh the logs of your add-on, you should now see "Hello world!" in your logs.
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/tutorial/addon_hello_world_logs.png' />
|
||||
The add-on will print Hello world to the logs and then quit.
|
||||
</p>
|
||||
|
||||
### {% linkable_title I don't see my add-on?! %}
|
||||
|
||||
Oops! You clicked refresh in the store and your add-on didn't show up. Or maybe you just updated an option, clicked refresh and saw your add-on disappear.
|
||||
|
||||
When this happens, it means that your `config.json` is invalid. It's either invalid JSON or one of the specified options is incorrect. To see what went wrong, go to the Hass.io panel and in the supervisor card click on "View logs". This should bring you to a page with the logs of the supervisor. Scroll to the bottom and you should be able to find the validation error.
|
||||
|
||||
Once you fixed the error, go to the add-on store and click refresh again.
|
||||
|
||||
## {% linkable_title Step 3: Hosting a server %}
|
||||
|
||||
Until now we've been able to do some basic stuff, but it's not very useful yet. So let's take it one step further and host a server that we expose on a port. For this we're going to use the built-in HTTP server that comes with Python 3.
|
||||
|
||||
To do this, we will need to update our files as follows:
|
||||
|
||||
- `Dockerfile`: Install Python 3
|
||||
- `config.json`: Make the port from the container available on the host
|
||||
- `run.sh`: Run the Python 3 command to start the HTTP server
|
||||
|
||||
Add to your `Dockerfile` before `RUN`:
|
||||
|
||||
```
|
||||
# Install requirements for add-on
|
||||
RUN apk add --no-cache python3
|
||||
|
||||
# Python 3 HTTP Server serves the current working dir
|
||||
# So let's set it to our add-on persistent data directory.
|
||||
WORKDIR /data
|
||||
```
|
||||
|
||||
Add "ports" to `config.json`. This will make TCP on port 8000 inside the container available on the host on port 8000.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Hello world",
|
||||
"version": "0.2",
|
||||
"slug": "hello_world",
|
||||
"description": "My first real add-on!",
|
||||
"startup": "before",
|
||||
"boot": "auto",
|
||||
"options": {},
|
||||
"schema": {},
|
||||
"ports": {
|
||||
"8000/tcp": 8000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Update `run.sh` to start the Python 3 server:
|
||||
|
||||
```
|
||||
python3 -m http.server
|
||||
```
|
||||
|
||||
## {% linkable_title Step 4: Installing the update %}
|
||||
|
||||
Since we updated the version number in our `config.json`, Home Assistant will show an update button when looking at the add-on details. You might have to refresh your browser or click the refresh button in the add-on store for it to show up. If you did not update the version number, you can also uninstall and install the add-on again. After installing the add-on again, make sure you start it.
|
||||
|
||||
Now navigate to [http://hassio.local:8000](http://hassio.local:8000) to see our server in action!
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/tutorial/python3-http-server.png' />
|
||||
The Python 3 server will allow you to browse the /data folder.
|
||||
</p>
|
||||
|
||||
## {% linkable_title Bonus: Working with add-on options %}
|
||||
|
||||
In the screenshot you've probably seen that our server only served up 1 file: `options.json`. This file contains the user configuration for this add-on. Because we specified an empty "config" and "schema" in our `config.json`, the file is currently empty.
|
||||
|
||||
Let's see if we can get some data into that file!
|
||||
|
||||
To do this, we need to specify the default options and a schema for the user to change the options.
|
||||
|
||||
Change the options and schema entries in your `config.json` with the following:
|
||||
|
||||
```json
|
||||
{
|
||||
…
|
||||
|
||||
"options": {
|
||||
"beer": true,
|
||||
"wine": true,
|
||||
"liquor": false,
|
||||
"name": "world",
|
||||
"year": 2017
|
||||
},
|
||||
"schema": {
|
||||
"beer": "bool",
|
||||
"wine": "bool",
|
||||
"liquor": "bool",
|
||||
"name": "str",
|
||||
"year": "int"
|
||||
},
|
||||
|
||||
…
|
||||
}
|
||||
```
|
||||
|
||||
Refresh the add-on store and re-install your add-on. You will now see the options available in the add-on config screen. When you now go back to our Python 3 server and download `options.json`, you'll see the options you set.
|
||||
|
||||
- [Learn more about the available schema options.](/hassio/addon_config/#options--schema)
|
||||
- [See how options.json can be used inside `run.sh`](https://github.com/home-assistant/hassio-addons/blob/master/mosquitto/run.sh#L4-L6)
|
||||
|
||||
### [Next step: Add-on config reference »](/developers/hassio/addon_config/)
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_tutorial.html';
|
||||
</script>
|
||||
|
|
@ -10,30 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/architecture/
|
||||
---
|
||||
|
||||
<p class='img'>
|
||||
<a href='/images/hassio/architecture.png'><img src='/images/hassio/architecture.png' alt='Architecture overview of Hass.io'></a>
|
||||
Architecture overview of Hass.io
|
||||
</p>
|
||||
|
||||
### {% linkable_title Host Control (HC) %}
|
||||
|
||||
This is a daemon running on the host machine that allows the supervisor to control certain aspects of the host OS:
|
||||
|
||||
- Power cycle (restart, turn off)
|
||||
- Manage network settings
|
||||
- Local updates
|
||||
|
||||
### {% linkable_title Host %}
|
||||
|
||||
Our pre-build images are based on [ResinOS]. Any Linux machine can be turned into a Hass.io host by running [the installer][linux].
|
||||
|
||||
### {% linkable_title Supervisor %}
|
||||
|
||||
The supervisor offers an API to manage the host and running the Docker containers.
|
||||
|
||||
### {% linkable_title Configuration panel %}
|
||||
|
||||
The configuration panel lives inside the supervisor but is accessible via the Home Assistant user interface. The configuration panel allows the user to manage the installation.
|
||||
|
||||
[ResinOS]: https://resinos.io/
|
||||
[linux]: /hassio/installation/#alternative-install-on-generic-linux-server
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/architecture_hassio.html';
|
||||
</script>
|
||||
|
|
@ -10,46 +10,6 @@ footer: true
|
|||
redirect_from: /hassio/debugging/
|
||||
---
|
||||
|
||||
<p class='note warning'>
|
||||
This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is for <b>developers</b> of Hass.io. Do not ask for support if you are using these options.
|
||||
</p>
|
||||
|
||||
[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`.
|
||||
|
||||
<p class='note'>
|
||||
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.
|
||||
</p>
|
||||
|
||||
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
|
||||
<script>
|
||||
window.location = 'https://developers.home-assistant.io/docs/en/hassio_debugging.html';
|
||||
</script>
|
||||
Loading…
Add table
Add a link
Reference in a new issue