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

Small fixes for Hass.io/HA (#405)

Browse Source 
* Small fixes for Hass.io/HA

* Update docs/hassio_addon_communication.md

Co-Authored-By: Franck Nijhof <git@frenck.dev>

* Update docs/hassio_addon_communication.md

Co-Authored-By: Franck Nijhof <git@frenck.dev>

* Update docs/hassio_addon_communication.md

Co-Authored-By: Franck Nijhof <git@frenck.dev>

* Update docs/hassio_addon_config.md

Co-Authored-By: Franck Nijhof <git@frenck.dev>

* Update docs/hassio_addon_config.md

Co-Authored-By: Franck Nijhof <git@frenck.dev>

* Update docs/hassio_addon_communication.md

Co-Authored-By: Franck Nijhof <git@frenck.dev>

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
Pascal Vizeli 2020-02-10 17:02:46 +01:00 committed by GitHub
parent 1649c2d4d7
commit d92362b693
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 61 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/hassio_addon_communication.md
View File

@ -2,37 +2,37 @@
title: "Add-On Communication" title: "Add-On Communication"
--- ---
There are different ways for communication between add-ons inside Hass.io. There are different ways for communication between add-ons inside Home Assistant.
## Network ## Network
We use an internal network that's allowed to communicate with every add-on, including to/from Home Assistant, by using its name or alias. Only add-ons that run on the host network are limited in that they can talk with all internal add-ons by their name, but all other add-ons can't address these add-ons by name. However, using an alias works for both! We use an internal network that's allowed to communicate with every add-on, including to/from Home Assistant, by using its name or alias. Only add-ons that run on the host network are limited in that they can talk with all internal add-ons by their name, but all other add-ons can't address these add-ons by name. However, using an alias works for both!
Names/aliases are used for communication inside Hass.io. Names/aliases 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-on's `config.json` file. You can use this name as the DNS name also, but you need replace any `_` 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. 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-on's `config.json` file. You can use this name as the DNS name also, but you need replace any `_` 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 [Supervisor add-on API][supervisor-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. Use `supervisor` for communication with the internal API.
## Home Assistant ## Home Assistant Core
An add-on can talk to the [Home Assistant API][hass-api] using the internal proxy. This makes it very easy to communicate with the API without knowing the password, port or any other information about the Home Assistant instance. Using this URL: `http://hassio/homeassistant/api` ensures that internal communication is redirected to the right place. The next step is to add `homeassistant_api: true` to the `config.json` file and read the environment variable `HASSIO_TOKEN`. Use this as the Home Assistant [bearer token](https://developers.home-assistant.io/docs/en/auth_api.html#making-authenticated-requests) when making requests. An add-on can talk to the [Home Assistant Core API][core-api] using the internal proxy. This makes it very easy to communicate with the API without knowing the password, port or any other information about the Home Assistant instance. Using this URL: `http://supervisor/core/api` ensures that internal communication is redirected to the right place. The next step is to add `homeassistant_api: true` to the `config.json` file and read the environment variable `SUPERVISOR_TOKEN`. Use this as the Home Assistant Core [bearer token](https://developers.home-assistant.io/docs/en/auth_api.html#making-authenticated-requests) when making requests.
For example `curl -X GET -H "Authorization: Bearer ${HASSIO_TOKEN}" -H "Content-Type: application/json" http://hassio/homeassistant/api/discovery_info` For example `curl -X GET -H "Authorization: Bearer ${SUPERVISOR_TOKEN}" -H "Content-Type: application/json" http://supervisor/core/api/discovery_info`
There is also a proxy for the [Home Assistant Websocket API][hass-websocket] that works like the API proxy above and requires `HASSIO_TOKEN` as the password. Use this URL: `http://hassio/homeassistant/websocket`. There is also a proxy for the [Home Assistant Websocket API][core-websocket] that works like the API proxy above and requires `SUPERVISOR_TOKEN` as the password. Use this URL: `http://supervisor/core/websocket`.
It is also possible to talk directly to the Home Assistant instance, which is named `homeassistant`, over the internal network. However, you'll need to know the configuration that is used by the running instance. It is also possible to talk directly to the Home Assistant instance, which is named `homeassistant`, over the internal network. However, you'll need to know the configuration that is used by the running instance.
We have several services for Hass.io inside Home Assistant to run tasks. Send data over STDIN to an add-on to use the `hassio.addon_stdin` service. We have several services for Hass.io inside Home Assistant to run tasks. Send data over STDIN to an add-on to use the `hassio.addon_stdin` service.
## Hass.io API ## Supervisor API
To enable calls to the [Hass.io API][hassio-api], add `hassio_api: true` to the `config.json` file 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`. You may also need to change the Hass.io API role to `hassio_role: default`. To enable calls to the [Supervisor API][supervisor-api], add `hassio_api: true` to the `config.json` file and read the environment variable `SUPERVISOR_TOKEN`. Now you can use the API over the URL: `http://supervisor/`. Use the `SUPERVISOR_TOKEN` with header `Authorization: Bearer`. You may also need to change the Supervisor API role to `hassio_role: default`.
Add-ons can call some API commands without needing to set `hassio_api: true`: Add-ons can call some API commands without needing to set `hassio_api: true`:
- `/homeassistant/api` - `/core/api`
- `/homeassistant/api/stream` - `/core/api/stream`
- `/homeassistant/websocket` - `/core/websocket`
- `/addons/self/*` - `/addons/self/*`
- `/services*` - `/services*`
- `/discovery*` - `/discovery*`
@ -40,7 +40,7 @@ Add-ons can call some API commands without needing to set `hassio_api: true`:
***Note:*** For Home Assistant API access requirements, see above. ***Note:*** For Home Assistant API access requirements, see above.
[hass-api]: https://www.home-assistant.io/developers/rest_api/ [core-api]: https://www.home-assistant.io/developers/rest_api/
[hass-websocket]: https://www.home-assistant.io/developers/websocket_api/ [core-websocket]: https://www.home-assistant.io/developers/websocket_api/
[hassio-api]: https://github.com/home-assistant/hassio/blob/master/API.md [supervisor-api]: https://github.com/home-assistant/supervisor/blob/master/API.md
[hassio-addon-api]: https://github.com/home-assistant/hassio/blob/dev/API.md#restful-for-api-addons [supervisor-addon-api]: https://github.com/home-assistant/supervisor/blob/dev/API.md#restful-for-api-addons

10
docs/hassio_addon_config.md
View File

@ -125,10 +125,10 @@ The config for an add-on is stored in `config.json`.
| 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` | 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`
| udev | bool | no | Default False. Set this True, if your container runs a udev process of its own. | udev | bool | no | Default False. Set this True, if your container runs a udev process of its own.
| auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on. | auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on.
| homeassistant | string | no | Pin a minimum required Home Assistant version for such Add-on. Value is a version string like `0.91.2`. | homeassistant | string | no | Pin a minimum required Home Assistant Core version for such Add-on. Value is a version string like `0.91.2`.
| hassio_role | str | no | Default `default`. Role based access to Hass.io API. Available: `default`, `homeassistant`, `backup`, `manager`, `admin`. | hassio_role | str | no | Default `default`. Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager`, `admin`.
| hassio_api | bool | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`. | 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`. | homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://supervisor/core/api`.
| docker_api | bool | no | Allow read-oly access to docker API for add-on. Work only for not protected add-ons. | docker_api | bool | no | Allow read-oly access to docker API for add-on. Work only for not protected add-ons.
| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE`, `DAC_READ_SEARCH`. | privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE`, `DAC_READ_SEARCH`.
| full_access | bool | no | Give full access to hardware like the privileged mode in docker. Work only for not protected add-ons. | full_access | bool | no | Give full access to hardware like the privileged mode in docker. Work only for not protected add-ons.
@ -230,6 +230,6 @@ You need this only, if you not use the default images or need additionals things
| squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that! | 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. | args | no | Allow to set additional Docker build arguments as a dictionary.
We provide a set of [Base-Images][hassio-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific Image tag, feel free to pin this requirements for you build with `build_from` option. We provide a set of [Base-Images][docker-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific Image tag, feel free to pin this requirements for you build with `build_from` option.
[hassio-base]: https://github.com/home-assistant/hassio-base [docker-base]: https://github.com/home-assistant/docker-base

14
docs/hassio_addon_index.md
View File

@ -19,11 +19,11 @@ Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.
Useful links: Useful links:
* [Hass.io Supervisor](https://github.com/home-assistant/hassio) * [Supervisor](https://github.com/home-assistant/supervisor)
* [Hass.io Core Add-ons](https://github.com/home-assistant/hassio-addons) * [Core Add-ons](https://github.com/home-assistant/hassio-addons)
* [Hass.io Build environment](https://github.com/home-assistant/hassio-build) * [Build environment](https://github.com/home-assistant/hassio-build)
* [Hass.io base images](https://github.com/home-assistant/hassio-base) * [base images](https://github.com/home-assistant/docker-base)
* [Hass.io Builder](https://github.com/home-assistant/hassio-builder) * [Builder](https://github.com/home-assistant/hassio-builder)
* [Hass.io community Add-ons](https://github.com/hassio-addons) * [Home Assistant community Add-ons](https://github.com/hassio-addons)
* [HassOS embedded Linux](https://github.com/home-assistant/hassos) * [HassOS embedded Linux](https://github.com/home-assistant/hassos)
* [Home Assistant Dockerfile](https://github.com/home-assistant/hassio-homeassistant) * [Home Assistant Dockerfile](https://github.com/home-assistant/docker)

6
docs/hassio_addon_presentation.md
View File

@ -2,7 +2,7 @@
title: "Presenting your addon" title: "Presenting your addon"
--- ---
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. 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 Home Assistant also gives you some other tools to present your add-on even nicer.
## Adding intro ## Adding intro
@ -18,7 +18,7 @@ This file containing the documentation is usually referred to as the "DOC", whic
## Add-on icon & logo ## 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. 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 Supervisor panel and which will significantly improve the visual representation of your add-on.
Requirements for the logo of your add-on: Requirements for the logo of your add-on:
@ -41,8 +41,6 @@ A changelog is a file which contains a curated, chronologically ordered list of
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. 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.
## AppArmor ## AppArmor
You can use own security profile for you Add-on with AppArmor. Default it is enabled and use the Docker default profile. Put `apparmor.txt` file into your Add-on folder and it will load this file as primary profile. Use the config options to set the name of that profile. You can use own security profile for you Add-on with AppArmor. Default it is enabled and use the Docker default profile. Put `apparmor.txt` file into your Add-on folder and it will load this file as primary profile. Use the config options to set the name of that profile.

6
docs/hassio_addon_publishing.md
View File

@ -2,7 +2,7 @@
title: "Publishing your add-on" title: "Publishing your add-on"
--- ---
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. 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 Home Assistant instance.
#### Pre-build containers #### Pre-build containers
@ -12,7 +12,7 @@ We have automated the process of building and publishing add-ons. See below for
#### Locally build containers #### 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. Starting Supervisor 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. 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.
@ -30,7 +30,7 @@ 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 one (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. You can use `{arch}` inside the image name to support multiple architectures with one (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. Home Assistant 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.
## Custom Add-ons ## Custom Add-ons

4
docs/hassio_addon_repository.md
View File

@ -4,11 +4,11 @@ title: "Create an add-on 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. 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. Check the [Example add-on repository](https://github.com/home-assistant/addons-example) for further details.
## Installing a repository ## 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**. A user can add a repository by going to the Supervisor 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 ## Repository configuration

9
docs/hassio_addon_security.md
View File

@ -2,11 +2,11 @@
title: "Add-on security" title: "Add-on security"
--- ---
Hass.io rates every add-on based on the wanted rights. An add-on with a rating of 6 is very secure. If an add-on has a rating of 1, you shouldn't run this add-on unless you are 100% sure that you can trust the source. Home Assistant rates every add-on based on the wanted rights. An add-on with a rating of 6 is very secure. If an add-on has a rating of 1, you shouldn't run this add-on unless you are 100% sure that you can trust the source.
## API Role ## API Role
For access to Hass.io API you need define a role or you run in default mode. This is only required for Hass.io API not Home Assistant proxy. Any of the roles already have access to the default API calls, and do not require any additional settings. For access to Supervisor API you need define a role or you run in default mode. This is only required for Supervisor API not Home Assistant proxy. Any of the roles already have access to the default API calls, and do not require any additional settings.
### Available Roles ### Available Roles
@ -35,7 +35,4 @@ As a developer, follow the following best practices to make your add-on secure:
Instead of allowing users to set new login credential in plain text config, use the Home Assistant [Auth backend][hassio-api-auth]. You can enable the access to API with `auth_api: true`. Now you are able to send the login credential to auth backend and validate it again Home Assistant. Instead of allowing users to set new login credential in plain text config, use the Home Assistant [Auth backend][hassio-api-auth]. You can enable the access to API with `auth_api: true`. Now you are able to send the login credential to auth backend and validate it again Home Assistant.
We have some sample and helpers around that system collected in a [GitHub repository][hassio-auth]. Feel free to copy and paste it or provide your own scripts. [supervisor-api-auth]: https://github.com/home-assistant/supervisor/blob/dev/API.md#auth--sso-api
[hassio-auth]: https://github.com/home-assistant/hassio-auth
[hassio-api-auth]: https://github.com/home-assistant/hassio/blob/dev/API.md#auth--sso-api

2
docs/hassio_addon_testing.md
View File

@ -6,7 +6,7 @@ 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. 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.
The [Community Add-on][hassio-vagrant] repository create a vagrant based development system. This Vagrant virtual machine allows you to test and play with Hass.io and Home Assistant, and is a great environment for add-on developers The [Community Add-on][hassio-vagrant] repository create a vagrant based development system. This Vagrant virtual machine allows you to test and play with Supervisor and Home Assistant, and is a great environment for add-on developers
[Samba add-on]: https://www.home-assistant.io/addons/samba/ [Samba add-on]: https://www.home-assistant.io/addons/samba/
[SSH add-on]: https://www.home-assistant.io/addons/ssh/ [SSH add-on]: https://www.home-assistant.io/addons/ssh/

20
docs/hassio_addon_tutorial.md
View File

@ -2,19 +2,19 @@
title: "Tutorial: Making your first add-on" title: "Tutorial: Making your first add-on"
--- ---
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. 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 Supervisor 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. To get started with developing add-ons, we first need access to where Home Assistant 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. For Samba, once you have enabled and started it, your Home Assistant 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' 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'
![Screenshot of Windows Explorer showing a folder on the Hass.io server](/img/en/hass.io/tutorial/samba.png) ![Screenshot of Windows Explorer showing a folder on the Home Assistant server](/img/en/hass.io/tutorial/samba.png)
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". 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 Home Assistant and store your custom add-ons in "/addons".
![Screenshot of Putty connected to Hass.io](/img/en/hass.io/tutorial/ssh.png) ![Screenshot of Putty connected to Home Assistant](/img/en/hass.io/tutorial/ssh.png)
Once you have located your add-on directory, it's time to get started! Once you have located your add-on directory, it's time to get started!
@ -62,13 +62,13 @@ Make sure your editor is using UNIX-like line breaks (LF), not Dos/Windows (CRLF
## Step 2: Installing and testing your add-on ## 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. Now comes the fun part, time to open the Home Assistant UI and install and run your add-on.
- Open the Home Assistant frontend - Open the Home Assistant frontend
- Go to the Hass.io panel - Go to the Supervisor panel
- On the top right click the shopping basket to go to the add-on store. - On the top right click the shopping basket to go to the add-on store.
![Screenshot of the Hass.io main panel](/img/en/hass.io/screenshots/main_panel_addon_store.png) ![Screenshot of the Home Assistant Supervisor main panel](/img/en/hass.io/screenshots/main_panel_addon_store.png)
- On the top right click the refresh button - On the top right click the refresh button
- You should now see a new card called "Local" that lists your add-on! - You should now see a new card called "Local" that lists your add-on!
@ -86,7 +86,7 @@ Now comes the fun part, time to open the Hass.io UI and install and run your add
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. 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. 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 Supervisor 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. Once you fixed the error, go to the add-on store and click refresh again.

27
docs/hassio_debugging.md
View File

@ -1,12 +1,12 @@
--- ---
title: "Debugging Hass.io" title: "Debugging Home Assistant"
--- ---
> This section is not for end users. End users should 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. > This section is not for end users. End users should use the [SSH add-on] to SSH into Home Assistant. This is for <b>developers</b> of Home Assistant. Do not ask for support if you are using these options.
[SSH add-on]: https://www.home-assistant.io/addons/ssh/ [SSH add-on]: https://www.home-assistant.io/addons/ssh/
The following debug tips and tricks are for developers 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. The following debug tips and tricks are for developers who are running the Home Assistant 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.
## Debug Supervisor ## Debug Supervisor
@ -16,7 +16,7 @@ Visual Studio Code config:
"version": "0.2.0", "version": "0.2.0",
"configurations": [ "configurations": [
{ {
"name": "Hass.io remote debug", "name": "Supervisor remote debug",
"type": "python", "type": "python",
"request": "attach", "request": "attach",
"port": 33333, "port": 33333,
@ -37,25 +37,22 @@ You need set the dev mode on supervisor and enable debug with options. You need
## SSH access to the host ## SSH access to the host
> SSH access through the [SSH add-on] (which will give you SSH access through port 22) will not provide you with all the necessary privileges, and you will be asked for a username and password when typing the 'login' command. You need to follow the steps below, which will setup a separate SSH access through port 22222 with all necessary privileges. > SSH access through the [SSH add-on] (which will give you SSH access through port 22) will not provide you with all the necessary privileges, and you will be asked for a username and password when typing the 'login' command. You need to follow the steps below, which will setup a separate SSH access through port 22222 with all necessary privileges.
### resinOS based Hass.io (deprecated) ### Home Assistant OS
Create an `authorized_keys` file containing your public key, and place it in the root of the boot partition of your SD card. See [Generating SSH Keys](#generating-ssh-keys) section below if you need help generating keys. Once the device is booted, you can access your device as root over SSH on port 22222. Use a USB drive formatted with FAT, ext4, or NTFS and name it CONFIG (case sensitive). Create an `authorized_keys` file (no extension) containing your public key, and place it in the root of the USB drive. File needs to be ANSI encoded (not UTF-8) and must have Unix line ends (LF), not Windows (CR LF). See [Generating SSH Keys](#generating-ssh-keys) section below if you need help generating keys. From the UI, navigate to the Supervisor system page and choose "Import from USB". You can now access your device as root over SSH on port 22222. Alternatively, the file will be imported from the USB when the Home Assistant OS device is rebooted.
### HassOS based Hass.io
Use a USB drive formatted with FAT, ext4, or NTFS and name it CONFIG (case sensitive). Create an `authorized_keys` file (no extension) containing your public key, and place it in the root of the USB drive. File needs to be ANSI encoded (not UTF-8) and must have Unix line ends (LF), not Windows (CR LF). See [Generating SSH Keys](#generating-ssh-keys) section below if you need help generating keys. From the UI, navigate to the hass.io system page and choose "Import from USB". You can now access your device as root over SSH on port 22222. Alternatively, the file will be imported from the USB when the hass.io device is rebooted.
> Make sure when you are copying the public key to the root of the USB drive that you rename the file correctly to `authorized_keys` with no `.pub` file extension. > Make sure when you are copying the public key to the root of the USB drive that you rename the file correctly to `authorized_keys` with no `.pub` file extension.
You should then be able to SSH into your Hass.io device. On Mac/Linux, use: You should then be able to SSH into your Home Assistant device. On Mac/Linux, use:
```shell ```shell
ssh root@hassio.local -p 22222 ssh root@hassio.local -p 22222
``` ```
You will initially be logged in to Hass.io CLI for HassOS where you can perform normal [CLI functions]. If you need access to the host system use the 'login' command. [Hass.io OS] is a hypervisor for Docker. See the [Hass.io Architecture] documentation for information regarding the Hass.io supervisor. The supervisor offers an API to manage the host and running the Docker containers. Home Assistant itself and all installed addon's run in separate Docker containers. You will initially be logged in to Home Assistant CLI for HassOS where you can perform normal [CLI functions]. If you need access to the host system use the 'login' command. [Home Assistant OS] is a hypervisor for Docker. See the [Supervisor Architecture] documentation for information regarding the supervisor. The supervisor offers an API to manage the host and running the Docker containers. Home Assistant itself and all installed addon's run in separate Docker containers.
[CLI functions]: https://www.home-assistant.io/hassio/commandline/ [CLI functions]: https://www.home-assistant.io/hassio/commandline/
[Hass.io OS]: https://github.com/home-assistant/hassos [Home Assistant OS]: https://github.com/home-assistant/hassos
[Hass.io Architecture]: https://developers.home-assistant.io/docs/en/architecture_hassio.html [Supervisor Architecture]: https://developers.home-assistant.io/docs/en/architecture_hassio.html
## Checking the logs ## Checking the logs
@ -63,7 +60,7 @@ You will initially be logged in to Hass.io CLI for HassOS where you can perform
# Logs from the supervisor service on the Host OS # Logs from the supervisor service on the Host OS
journalctl -f -u hassos-supervisor.service journalctl -f -u hassos-supervisor.service
# Hass.io supervisor logs # Supervisor logs
docker logs hassos_supervisor docker logs hassos_supervisor
# Home Assistant logs # Home Assistant logs
@ -84,6 +81,6 @@ Windows instructions for how to generate and use private/public keys with Putty
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). 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.) Follow steps 1-4 under 'Generating a new SSH key' (The other sections are not applicable to Home Assistant 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 the authorized_keys file" and save it to the root of your USB drive as `authorized_keys`. 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 the authorized_keys file" and save it to the root of your USB drive as `authorized_keys`.