RFC: Hass.io add-ons <> Home Assistant components

[balloob]

I think that it would be great if we could add awareness to our components that supporting Hass.io add-ons exist and vice versa. Main component when I"m thinking about this is MQTT. It's the backbone of DIY IoT and if we can help make setup easier, we can unlock a lot of potential things.

Use case 1:

1. MQTT add-on starts up, triggers Hass.io to load MQTT component.
2. MQTT component checks during setup if MQTT server add-on is installed and connects to it if no config given (instead of embedded broker)

Requirements:

1. Add-ons can trigger components to be loaded
2. Components can read if add-ons are installed and wait till add-ons are loaded
3. Components should be made Hass.io add-on aware, but generic. So not aware of core/mosquitto add-on but instead mqtt-server.
4. The MQTT component in HASS should connect to an MQTT server add-on if installed and running instead of spinning up the embedded MQTT server.

Problems:

1. Race conditions. During startup, if user has MQTT platforms configured, Home Assistant will setup the MQTT component. At that point in time the MQTT add-on should already have been started or the MQTT component will wait for that.

Use case 2:

1. Snips add-on starts up
2. Triggers the Snips component to be loaded in Home Assistant automatically and wait for "response"
3. Snips component starts up and sets response for Snips add-on with MQTT broker to connect to
4. Snips add-on unblocks, uses returned info to configure MQTT broker.

I had this as another use case but I think a better solution would be for the snips add-on to directly communicate with the mosquitto add-on to see if it exists (via the network layer) and make a connection like that.

[pvizeli]

I think we can that solve very simple and high powerful (based on idea of paulus):

API for Add-ons / homeassistant config:
GET /homeassistant/config/_component_ in example: /homeassistant/config/mqtt

In example of snips. The add-on (is tagged as application and run after startup of home-assistant) can read the home-assistant configuration for mqtt and connect the snips to this mqtt or setup a own mqtt server. Now it send the own mqtt server config or/and request the snips component setup with next API.

API for Add-ons / discovery:
POST /homeassistant/discovery

In example of mqtt. The add-on (is tagged as system and startup on stage 2 before home-assistant) can push the config they is needed to setup the component on home-assistant. I.e. the core-mqtt add-on will setup a hass user if the user config is enable or if they is open it push the data for connection.

API for Home-Assistant hassio component:
GET /homeassistant/discovery

It can read the wanted setups for add-ons and setup it in home-assistant with the given config.

---

There are other add-ons they use mqtt and they can read the actual given mqtt settings from home-assistant and connect to this server. He don't need know if there is a add-on setup or somethings else.

There need also no blocking APIs or any knowlage or other APIs inside home-assistant.

[balloob]

So it would then look like this:

Startup of MQTT add-on (system stage):

• MQTT add-on starts up
• MQTT add-on posts MQTT connection info for component.mqtt to /homeassistant/discovery
• Home Assistant starts up
• Hass.io subscribes to discovery content components.*. It will right away receive all discoveries that have already been posted and will then be notified of extras as soon as they arrive.
• Hass.io component sees discovery for component.mqtt and triggers loading of the MQTT component.
• MQTT component loads. During set up will read Hass.io discovery info and connect to the provided credentials (if no broker config is available in the config)

This will still work If Home Assistant contains a platform that depends on MQTT because MQTT will check Hass.io during setup of the component.

Start of Snips add-on (application stage):

• Home Assistant starts up
• Hass.io is listening for discovery component.*
• Snips add-on at start of setup posts to discovery component.snips
• Snips add-on blocks further setup waiting for a discovery for addon.snips
• Hass.io is triggered by discovery and loads Snips component
• MQTT is loaded as a dependency of Snips. Follows normal setup.
• Snips component during setup will call a new method hass.components.mqtt.get_credentials() and pushes that info to /homeassistant/discovery for addon.snips
• Snips add-on will unblock now that discovery has been posted and will connect to given MQTT server.

[frenck]

We have to take into account, that there are (and will be) multiple add-ons providing the "same" service. E.g. don't lock onto build-in/known add-ons. (Which is cover fairly in the above).

Nevertheless, what if 2 active add-ons provide the same services? E.g. 2 MySQL add-ons?

[pvizeli]

Correct:

Start of Snips add-on (application stage):

• Home Assistant starts up
• Hass.io is listening for discovery `component.*
• Snips add-on at start look for exists mqtt server (/homeassistant/config/mqtt)
• Snips add-on connect to exists mqtt server or attach home-assistant to his internal
• Snips add-on at start of setup posts to discovery component.snips

@frenck That will be a mission of the add-on. He can provide stuff to home-assistant but he don't need it. I think also the add-on should be expose this handling as a option like auto_config.

[frenck]

@pvizeli I agree, I was just exposing/questioning a potential "bad path" in the case where 2 add-ons where conflicting. Adding this to the design in the first place will definitely reduce headaches later on.

[pvizeli]

Add-on config

{
  "homeassistant_config": ["mqtt", "component_xy"],
  "homeassistant_discovery": ["mqtt", "component/platform", "recorder"],
}

Config API

GET - /homeassistant/config/_component_

return the hass config or provided configs from a other add-ons.

Discovery send API

POST - /homeassistant/discovery

{
  "component": "",
  "platform": "",
  "config": {}
}

Discovery read API

GET - /homeassistant/discovery

{
  "requested": "addon-slug",
  "component": "",
  "platform": "",
  "config": {}
}

[ciotlosm]

Quick question about config format:

What do you think of getting configs more aligned? For example using yaml for addon config, and maybe allowing addon config to be part of the /config folder for home assistant (something like !include packages, but !include addons)?

[balloob]

@ciotlosm please open a new issue for this.

For conflicts: if an add-on says which config they might potentially provide, we can do conflict checking and show a picker in the UI.

Which add-on should provide config for the recorder component?

 - (  ) MySQL
 - (  ) PostgresQL

[pvizeli]

Add-on config

{
  "services": ["mqtt:rw"],
  "homeassistant_discovery": ["mqtt", "component/platform"],
}

Publish a service inside hass.io

First service is mqtt. A add-on can write data into this node and other can read it, some services i.e. mqtt can also set by home-assistant (user). If a add-on write the service, he can also trigger a discovery on home-assistant.

Read service settings

GET - /services/_service_

return the service setting from this hass.io system. Return value is service specific.

Write service settings

POST - /services/_service_

Discovery

Allow to trigger a discovery inside home-assistant to install and setup a component automatic by add-on.

Discovery send API

POST - /homeassistant/discovery

{
  "component": "",
  "platform": "",
  "config": {}
}

Discovery read API

GET - /homeassistant/discovery

{
  "requested": "addon-slug",
  "component": "",
  "platform": "",
  "config": {}
}

[balloob]

So now that we're going to get config entries, I think that we should change this slightly. It's no longer going to be based on 'discovery' on the Home Assistant side but instead about config entries.

Read more about config entries here (docs are inside the source)

[pvizeli]

I think the discovery on hassio is not bounded to discovery on home-assistant. It give only a hint to home-assistant with the configs for setup this component/platform with whatever.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[balloob]

This has been implemented, see MQTT add-on as an example.