Integrations and components and platforms, oh my!

Configuration
1

I admit I’ve been challenged by some of Home Assistant’s terminology, especially by “integration, component, and platform”. In most other home automation software I’ve used, one or two terms describe the connection between the device and the software. Home Assistant has three and one of them can have two meanings.

I can’t claim I understand the terminology perfectly. After revising my interpretation of their definitions several times, the following is just my latest version. I invite the community to provide corrections.

Integration
This term is used when discussing the overall integration of a device (or service) into the Home Assistant ecosystem. Go to Configuration > Integrations and you see Hue, Sonos, Google Cast, MQTT, Z-Wave, etc. It’s easy enough to understand that if you have a device from Acme and there’s no existing integration for Acme then you can’t currently use Acme devices with Home Assistant.

Component
Home Assistant has many idealized versions of common devices (and services) like switch, light, notify, cover, lock, media-player, device_tracker, etc. These are the building blocks of your home automation system and are aptly called components (as in the components of your home automation system).

It seems one can also use the word ‘component’ to refer to an integration. For example, there’s a KNX integration but the piece that helps to bind the KNX system to Home Assistant is called the KNX component. Look at the documentation page for KNX. It states:

The KNX integration for Home Assistant allows you to connect to a KNX/IP devices.
The component requires a local KNX/IP interface like …

The KNX documentation page is one of the few that even uses the word integration (Z-Wave is another). Many simply use component: Nest, Insteon, Lutron, Xiaomi

The usage of ‘component’ is also found in Home Assistant’s directory structure (components, not integrations):

homeassistant/components/hue
homeassistant/components/sonos
homeassistant/components/mqtt

So it seems the word component can be used to refer to hue, sonos, mqtt, etc and light, switch, lock, cover, etc.

Unless I’m mistaken, this use of the word component is actually a contraction of ‘Entity Component’ (see Entity Architecture).

Platform
It’s my understanding that a platform is how an integration implements a component. For example, the KNX integration has a KNX component with platforms for binary_sensor, climate, light, switch, etc. Here’s where I often find myself mixing up the terms and saying “KNX light component” when I ought to be saying “KNX light platform”.

Sources of confusion:

If KNX has platforms for binary_sensor, climate, cover, etc then why doesn’t the right-hand side of its documentation page indicate ‘Related Platforms’ instead of ‘Related Components’ (other integrations do this as well). Why the reversion from platform to component? For that matter, why do many integrations describe the right-hand list as “Categories”? IKEA Tradfri, Ecobee

I’ve seen documentation refer to light, switch, cover, etc as ‘device types’: Insteon, Wink, Zigbee. Tuya uses all three: device type, platform, and category.

2

And to add one more layer of confusion you forgot to mention the other main term - “Domain”.

The Domain is the basic “device type” that is configured by platform to use the different available components.

The “entity_id” is comprised of two parts - the domain (light, switch, binary_sensor, etc.) and the device_id.

My understanding is that an “integration” refers to devices that are either discovered automatically or manually forced to be “found” by built in components (those components that are available but not specifically configured in your configuration.yaml file) that will then need very little if any configuration.

3

Ah yes, how did manage to overlook “domain”! Seems to me this term is context based and applies when you have an instance of a component. Whereas light is a component, light.kitchen is an instance of a light component, namely an entity. Now the light in light.kitchen represents the entity’s domain. No shortage of terms!

My impression of ‘integration’ is that it encompasses everything required to integrate the device with Home Assistant. The quality of the integration has a rating scale:

4

I’m not sure that the link you posted above is related to the term “integration” as you were using it above. It looks like it’s trying to describe how well a component is integrated into the HA ecosystem.

the difference (I think) is that the first one is a noun (an integration). The second one in the link is being used as an adjective (how well integrated something is).

Isn’t the English language fun?! :slightly_smiling_face:

5

Nah, it’s the same. The scale “scores each integration”, meaning the quality of the integration’s code and the user-experience it provides . It was introduced a few versions ago but hasn’t been widely adopted. For example, the documentation for Time & Date has “Quality Scale” (right-hand side of page) indicating it is ‘internal’ and the doc page for Philips Hue indicates its quality scale is ‘platinum’.

6

These were mostly spot on definitions, I’d be happy to accept a pull request to the documentation with them. Maybe as a new page at the end of Getting Started?

1 Like
7

Home Assistant is growing and the old terms are no longer sufficient so new ones appear. Most of those terms really only make sense to developers these days.

There is a move to only use “integration” in user-facing texts but that is a lot of work and not a lot of people are volunteering for these boring tasks. Actually, most people did not even get that memo yet so the confusion continues.

8

Hello guys!

This is the part Frenk and Paulus answer my question about component/addons/integrations:

9

Not much of an answer.

F: “People are mixing it up, a lot!”
Yes, because the definitions for components and integrations overlap.

F: “Integrations and components are almost the same now.”
OK, but were they ever very different?

P: “Component is gone.”
Except from all of the documentation …

F: “It’s still everywhere.”
Uh-huh.

P: “Yeah, I know.”
So, not really gone.

F: “In Home-Assistant terms, components are not a thing anymore, its integrations.”
Components were just a passing fad but integrations are the new black?

P: “I understand where the confusion is coming from but I don’t know what the solution is.”
Honest and commendable; first step to fix a problem is to recognize it exists.

One solution would be to define the terms in clear, precise language (perhaps even discarding one or two terms) then revising all of the documentation to reflect it. Despite statements like “components is gone”, the term is used everywhere, including the source-code, so we can’t just pretend it’s “gone”.

2 Likes
10

Well, I stumbled across as I had my first meet with the need to understand and identify components. Though I get stuck already, as my File Editor doesn’t show any components directory?
Yes, this is new to me, but sure I’d love to learn. Any link to a RTFM for HA newbies like me very welcome!