Update Hass.io docs
This commit is contained in:
Paulus Schoutsen
parent
419540348d
commit
ca80944d74
31 changed files with 248 additions and 74 deletions
|
|
@ -1,148 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Add-On Configuration"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Each add-on is stored in a folder. The file structure looks like this:
|
||||
|
||||
```
|
||||
addon_name/
|
||||
Dockerfile
|
||||
config.json
|
||||
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.
|
||||
|
||||
```bash
|
||||
echo '{ "target": "beer" }' | jq -r ".target"
|
||||
```
|
||||
|
||||
## {% 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.
|
||||
|
||||
```
|
||||
FROM %%BASE_IMAGE%%
|
||||
|
||||
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 follow schema:
|
||||
```
|
||||
#amd64:FROM...
|
||||
#i386:FROM...
|
||||
#armhf:FROM...
|
||||
#aarch64:FROM...
|
||||
```
|
||||
|
||||
## {% 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 descripton",
|
||||
"arch": ["amd64"],
|
||||
"url": "website with more information about add-on (ie a forum thread for support)",
|
||||
"startup": "before",
|
||||
"boot": "auto",
|
||||
"ports": {
|
||||
"123/tcp": 123
|
||||
},
|
||||
"map": ["config:rw", "ssl"],
|
||||
"options": {},
|
||||
"schema": {},
|
||||
"image": "repo/{arch}-my-custom-addon"
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Required | Description |
|
||||
| --- | -------- | ----------- |
|
||||
| name | yes | Name of the add-on
|
||||
| version | yes | Version of the add-on
|
||||
| slug | yes | Slug of the add-on
|
||||
| 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.
|
||||
| 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`
|
||||
| privileged | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`
|
||||
| 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.
|
||||
| environment | no | A dict of environment variable to run add-on.
|
||||
| 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.
|
||||
| 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.
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "custom things",
|
||||
"logins": [
|
||||
{ "username": "beer", "password": "123456" },
|
||||
{ "username": "cheep", "password": "654321" }
|
||||
],
|
||||
"random": ["haha", "hihi", "huhu", "hghg"],
|
||||
"link": "http://blebla.com/"
|
||||
}
|
||||
```
|
||||
|
||||
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": ["str"],
|
||||
"link": "url"
|
||||
}
|
||||
```
|
||||
|
||||
We support:
|
||||
- str
|
||||
- bool
|
||||
- int
|
||||
- float
|
||||
- email
|
||||
- url
|
||||
- port
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Developing an add-on"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Add-ons for Hass.io allows 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,71 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Publishing your add-on"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## {% 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.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
[builder]: https://github.com/home-assistant/hassio-build/tree/master/build-scripts/addons
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Create an add-on repository"
|
||||
description: "Add-ons repositories."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Add-ons repository can contain one or more add-ons. Each add-on is stored in it's own unique folder. For it to be indentified as a repository, a repository contains a configuration file.
|
||||
|
||||
[Example add-on repository](https://github.com/home-assistant/hassio-addons-example).
|
||||
|
||||
## 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".
|
||||
|
||||
## Repository configuration
|
||||
|
||||
Each repository is required to contain `repository.json` at the root of 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.
|
||||
|
|
@ -1,35 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Local add-on testing"
|
||||
description: "Instructions how to test your add-on locally."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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 run %}
|
||||
|
||||
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:
|
||||
|
||||
- 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 .`
|
||||
|
||||
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.
|
||||
|
||||
[Samba add-on]: /addons/samba/
|
||||
[SSH add-on]: /addons/ssh/
|
||||
|
|
@ -1,206 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Tutorial: Making your first add-on"
|
||||
description: "Easy tutorial to get started making your first add-on."
|
||||
date: 2017-05-12 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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`:
|
||||
```
|
||||
FROM %%BASE_IMAGE%%
|
||||
|
||||
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_store_icon.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 »](/hassio/addon_config/)
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Hass.io Architecture"
|
||||
description: "The architecture of Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
<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
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Debugging Hass.io"
|
||||
description: "Tips and tricks for when things go wrong."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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 in the root of your SD card with your public key. 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, copy your public key file to the root of your SD card.
|
||||
|
||||
<p class='note'>
|
||||
Make sure when you are copying the public key to the root of the SD card that you rename the file correctly with no `.pub` file extension.
|
||||
</p>
|
||||
|
||||
## {% 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 hassio_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
|
||||
|
|
@ -9,4 +9,33 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
Hass.io turns your Raspberry Pi (or other device) into the ultimate Home Automation hub. It takes away all the hassle of installing Home Assistant and related applications and keeping them up to date. Updates to the operating system, Home Assistant, and any add-ons can be done via the Home Assistant UI with a single click.
|
||||
Hass.io turns your Raspberry Pi (or other device) into the ultimate home automation hub powered by Home Assistant. With Hass.io you can focus on integrating your devices and writing automations.
|
||||
|
||||
[Go to the installation instructions »][install]
|
||||
|
||||
The advantages of using Hass.io:
|
||||
|
||||
- Free and open source
|
||||
- Optimized for the Raspberry Pi
|
||||
- 100% local home automation
|
||||
- Easy installation and updates (powered by [ResinOS] and [Docker])
|
||||
- Management user interface integrated into Home Assistant
|
||||
- Easily create and restore full backups of your whole configuration.
|
||||
- One click install of many popular add-ons including voice assistant via [Snips.ai], encryption via [Let's Encrypt] and dynamic DNS via [Duck DNS].<br><br>[Browse available add-ons »][all]
|
||||
- Active community that is helpful and sharing add-ons including AppDaemon, Homebridge and InfluxDB.<br><br>[Browse the forums »][forums]<br>[Join the Hass.io chat »][chat]<br>[Browse community add-on repositories »][comm-add-ons]
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/hassio/screenshots/dashboard.png'>
|
||||
Hass.io dashboard
|
||||
</p>
|
||||
|
||||
[Snips.ai]: /addons/snips/
|
||||
[Let's Encrypt]: /addons/lets_encrypt/
|
||||
[Duck DNS]: /addons/duckdns/
|
||||
[forums]: https://community.home-assistant.io/c/hass-io
|
||||
[comm-add-ons]: https://community.home-assistant.io/tags/hassio-repository
|
||||
[all]: /addons/
|
||||
[chat]: https://discord.gg/K3UVxJd
|
||||
[ResinOS]: https://resinos.io/
|
||||
[Docker]: https://www.docker.com/
|
||||
[install]: /hassio/installation/
|
||||
|
|
|
|||
|
|
@ -9,26 +9,29 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
Hass.io images are available for all available Raspberry Pi and intel nuc platforms.
|
||||
Hass.io images are available for all available Raspberry Pi and Intel NUC platforms.
|
||||
|
||||
- Download the appropriate image for your Raspberry Pi / intel nuc:
|
||||
- [Raspberry Pi / Zero][pi1]
|
||||
- [Raspberry Pi 2][pi2]
|
||||
- [Raspberry Pi 3][pi3]
|
||||
- [Intel Nuc][nuc]
|
||||
- [Intel NUC][nuc]
|
||||
- Flash the downloaded image to an SD card using [Etcher].
|
||||
- Optional - Setup the WiFi or static ip: On the SD-card, edit the `system-connections/resin-sample` file and follow the [ResinOS howto][resinos-network].
|
||||
- Insert SD card to Raspberry Pi and turn it on. On first boot, it downloads the latest version of Home Assistant which takes ~20 minutes (slower/faster depending on the platform).
|
||||
- You will be able to reach your installation at [http://hassio.local:8123][local].
|
||||
- Enable either the [Samba add-on][samba] or the [SSH add-on][ssh] to manage your configuration.
|
||||
|
||||
<p class='note'>
|
||||
If you copy over your existing Home Assistant configuration, make sure to enable the Hass.io panel by adding either `discovery:` or `hassio:` to your configuration.
|
||||
</p>
|
||||
|
||||
### {% linkable_title Alternative: install on generic Linux server %}
|
||||
## {% linkable_title Alternative: install on generic Linux server %}
|
||||
|
||||
For advanced users, it is also possible to try Hass.io on your Linux server or inside a VM. To do so, [follow these instructions][linux].
|
||||
|
||||
<p class='note'>When you use this installation method, some add-ons will not be available and the documentation might not work for your installation.</p>
|
||||
|
||||
[Etcher]: https://etcher.io/
|
||||
[resinos-network]: https://docs.resin.io/deployment/network/2.0.0/
|
||||
[pi1]: https://github.com/home-assistant/hassio-build/releases/download/0.8/resinos-hassio-0.8-raspberrypi.img.bz2
|
||||
|
|
@ -37,3 +40,5 @@ For advanced users, it is also possible to try Hass.io on your Linux server or i
|
|||
[nuc]: https://github.com/home-assistant/hassio-build/releases/download/0.8/resinos-hassio-0.8-intel-nuc.img.bz2
|
||||
[linux]: https://github.com/home-assistant/hassio-build/tree/master/install#install-hassio
|
||||
[local]: http://hassio.local:8123
|
||||
[samba]: /addons/samba/
|
||||
[ssh]: /addons/ssh/
|
||||
|
|
|
|||
|
|
@ -9,7 +9,11 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
Hass.io allows anyone to create add-on repositories to easily share their add-ons for Hass.io. To try this locally, you can use our example add-on repository at `https://github.com/home-assistant/hassio-addons-example`.
|
||||
Hass.io allows anyone to create add-on repositories to easily share their add-ons for Hass.io. To try this locally, you can use our example add-on repository at
|
||||
|
||||
```text
|
||||
https://github.com/home-assistant/hassio-addons-example
|
||||
```
|
||||
|
||||
<p class='note warning'>
|
||||
Home Assistant cannot guarantee the quality or security of third party add-ons. Use at your own risk.
|
||||
|
|
@ -27,4 +31,4 @@ Add the urls of repositories (one per line) and then press "Save". A new card fo
|
|||
|
||||
### {% linkable_title Help: Repository is not showing up %}
|
||||
|
||||
If you have added a repository but it's not showing up, it means that the repository contains invalid configuration. Go to the Hass.io panel -> Supervisor card -> View logs and scroll to the bottom. It should tell you what went wrong. Report this information to the repository author.
|
||||
If you have added a repository but it's not showing up, it means that the repository contains invalid configuration. Go to the Hass.io panel -> Three dot menu -> Advanced Settings -> Supervisor card -> View logs and scroll to the bottom. It should tell you what went wrong. Report this information to the repository author.
|
||||
|
|
|
|||
|
|
@ -9,15 +9,19 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
On a normal Home Assistant installation you have access to the base machine and can install or add scripts that you can call with a `command_line` sensor/switch. Since Hass.IO uses Docker, you can not use this old way to perform local stuff. On its face, it looks quite restrictive, but it makes the whole system stable.
|
||||
Hass.io is a managed environment. This means that you're unable to install applications that you can embed into Home Assistant using the `command_line` sensor/switch.
|
||||
|
||||
However, if you need to run a script to read data for a sensor or send commands to other devices on Hass.IO, you can do that with a add-on or on inside the Home Assistant container with a custom component. Here is one way to accomplish that using an add-on. For custom component, look at the [devoloper site][custom-component] and also read the [add-ons tutorial][addons-tutorial]. Now you can get started with your custom component in the right way.
|
||||
There are two options if you need to run a script to read data from a sensor or send commands to other devices on Hass.IO.
|
||||
|
||||
First you need install a MQTT broker. You can use our [MQTT broker add-on][mqtt-addon]. Make sure you use logins and disable anonymous access if you want to secure the system. We provide no Hass.IO way to exchange data, that will be not realy good for security and is also to slow to exchange data between containers or stop and go stuff. That is the reason why we use a mqtt broker for it.
|
||||
First option is to write a custom component for Home Assistant. Using Python you can communicate with your device. For custom component, look at the [devoloper site][custom-component].
|
||||
|
||||
The second option is to make a local add-on for Hass.io that sends the data to Home Assistant via MQTT. Before we dive into this, read up on [Hass.io add-on development][addons-tutorial].
|
||||
|
||||
For security and speed, Hass.io does not provide a way for containers to communicate directly. So the first step is to set up a communication channel. We're going to use MQTT for this using the [MQTT broker add-on][mqtt-addon].
|
||||
|
||||
### {% linkable_title Sensors %}
|
||||
|
||||
Short story of that caption: We loop in our script to fetch data and push it to MQTT and wait until next process is ready. Here is a basic example and structure for that process.
|
||||
We loop in our script to fetch data and push it to MQTT and wait until next process is ready. Here is a basic example and structure for that process.
|
||||
|
||||
Our Dockerfile need to install:
|
||||
|
||||
|
|
@ -26,6 +30,7 @@ RUN apk --no-cache add jq mosquitto-clients
|
|||
```
|
||||
|
||||
Now we can process it with `run.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
|
@ -52,11 +57,11 @@ do
|
|||
|
||||
sleep "$WAIT_TIME"
|
||||
done
|
||||
|
||||
```
|
||||
|
||||
### {% linkable_title Commands %}
|
||||
Short story of that caption: We wait for incoming data from MQTT broker. We can also use an `input_boolean` that triggers an automation to publish a custom command to MQTT topic that can process multiple things in one add-on.
|
||||
|
||||
We wait for incoming data from MQTT broker. We can also use an `input_boolean` that triggers an automation to publish a custom command to MQTT topic that can process multiple things in one add-on.
|
||||
|
||||
Our Dockerfile need to install:
|
||||
|
||||
|
|
@ -88,10 +93,9 @@ do
|
|||
fi
|
||||
|
||||
done < <(mosquitto_sub -h "$MQTT_SERVER" -p "$MQTT_PORT" -u "$USER" -P "$PASSWORD" -t "$TOPIC" -q 1)
|
||||
|
||||
```
|
||||
|
||||
|
||||
[MQTT-addon]: /addons/mosquitto/
|
||||
[custom-component]: /developers/component_loading/
|
||||
[addons-tutorial]: /hassio/addon_tutorial/
|
||||
[addons-tutorial]: /developers/hassio/addon_tutorial/
|
||||
|
|
|
|||
17
source/hassio/zwave.markdown
Normal file
17
source/hassio/zwave.markdown
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Z-Wave"
|
||||
description: "Instructions on how-to use Z-Wave with Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
To enable Z-Wave, plug your Z-Wave USB stick into your Raspberry Pi 3 and add the following to your `configuration.yaml`:
|
||||
|
||||
```yaml
|
||||
zwave:
|
||||
usb_path: /dev/ttyACM0
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue