What is an Integration, Device, Entity, Component, Platform?

Configuration
7

I’ll take a stab at it:

First, there is a Glossary available.

A device is (typically) a physical thing. It’s the real-world equipment you are attempting to control and automate.

A component is an idealized model of a device. They are the ‘virtual building-blocks’ you will use to create a virtual representation of all the devices in your home. For example:

  • Switch models a device that, minimally, can be turned on/off. This includes outlets, relays, light fixtures, etc.

  • Light models a device that, like a Switch, can be turned on/off and has other properties such as brightness and possibly color, transition, etc. This includes incandescent, (some) fluorescent, and LED lighting devices.

  • Cover models a device that can be opened/closed. This includes garage doors, awnings, shutters, blinds, etc.

  • Climate models a device that controls heating/cooling. Basically, we’re talking about a thermostat.

  • Sensor models a device that reports a value (numeric or text). This includes temperature sensors, humidity sensors, pressure sensors, weather monitors, etc.

  • Binary Sensor models a device that reports a binary state (on/off, open/closed, up/down, motion/no motion, etc). This includes a contact sensor for a door or window, a motion sensor, etc.

There are several others such as lock, fan, notification, etc. A complex device may require several components to model it completely. For example, an Ecobee thermostat is represented by a climate component (naturally) as well as sensor, binary_sensor, notification, and weather.

An integration provides the means of connecting to and controlling a device as well as modelling the device using one or more components. For example, the z-wave integration communicates with z-wave enabled devices and represents them using components such as light, fan, lock, climate, binary_sensor, etc.

An entity is an instance of a component. If you have ten physical lights (devices), where each one is modeled as a light component, then each instance is called an entity.

Finally there is platform which is a term associated with entities. If you have a light bulb that is controlled via the Zigbee integration, the entity you create to represent that light is said to use the Zigbee platform. Frankly, I feel this should probably use the word ‘integration’ but that’s the way it is.

15 Likes
8

Thanks @123, that was pretty good. It makes good sense, so maybe its the hassio ui causing me confusion.

For example I have zigbee and zwave listed as an integration in the ui. They both represent an environment consisting of a collection of devices that work and communicate with a standardized protocol. i.e. the zigbee protocol and zwave protocol.

I have Sonos listed as well. Which I guess makes sense too. Its a collection of audio equipment that uses the Sonos mesh network to communicate and share content with.

I also have Google Cast listed as an integration but have no idea what it is or why its there.

So now picking on zwave for a second. Right now Im in learning mode and only have a barebones zwave network. It consists of a huzb2 zwave/zigbee stick and a FortezZ dry contact switch to turn my fireplace on/off and a Somfy ZRTSi zwave to rts bridge to control my blinds. These are all physical devices that I can touch and hold.

Now when I go to the Devices panel on the UI, I would be expecting to see something like a list with the 1st column showing the integration and a 2nd column showing a device using that integration. i.e.:

Integration    Device
-------------- ----------
Zwave          Huzbz2 Usb Stick
Zwave          FortrezZ Dry Contact Relay
Zwave          Somfy ZRTSi rts Bridge

This shows the clear relationship between an integration and its collection of devices.

Instead of that there is an unordered list of entities all mixed together showing all my awnings and other stuff. So maybe the UI is missing a column or Panel like maybe one called Components which lists the ‘virtual devices’ available to manipulate i.e.:

Integration    Device                                      Component
-------------- ----------                                     -----------------------------
Zwave          Huzbz2 Usb Stick                     Network Controller/Hub
Zwave          FortrezZ Dry Contact Relay      On/Off Switch    
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 1
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 2
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 3

Then maybe add a 4th column that displays the Hassio ID/Usage (used in automation scripts) for the component i.e.:

Integration    Device                                      Component                                HASSio ID
-------------- ----------                                     -----------------------------                --------------------------
Zwave          Huzbz2 Usb Stick                     Network Controller/Hub             Zwave Hub
Zwave          FortrezZ Dry Contact Relay      On/Off Switch                            Bedroom Fireplace 
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 1       Bedroom Shade
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 2       Outdoor Awning
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 3       Living Room Blinds

Now back to my other problem. I have a working Flirc keyboard device yet I cant find it in either the integrations or devices ui panels. So would this be a bug or does it mean its not considered a device?

I would have expected to see something like:

Integration    Device                                      Component                                HASSio ID
-------------- ----------                                     -----------------------------                --------------------------
Zwave          Huzbz2 Usb Stick                     Network Controller/Hub             Zwave Hub
Zwave          FortrezZ Dry Contact Relay      On/Off Switch                            Bedroom Fireplace 
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 1       Bedroom Shade
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 2       Outdoor Awning
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 3       Living Room Blinds
IRD              Flirc USB Ird Bridge                   Keyboard                                   Logitec Elite Remote

I have the same problem with my working Harmony Hub device. Nothing is listed anywhere, but I was expecting to see something like:

Integration    Device                                      Component                                HASSio ID
-------------- ----------                                     -----------------------------                --------------------------
Zwave          Huzbz2 Usb Stick                     Network Controller/Hub             Zwave Hub
Zwave          FortrezZ Dry Contact Relay      On/Off Switch                            Bedroom Fireplace 
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 1       Bedroom Shade
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 2       Outdoor Awning
Zwave          Somfy ZRTSi rts Bridge            Cover Controller Channel 3       Living Room Blinds
IRD              Flirc USB Ird Bridge                   Keyboard                                   Logitec Elite Remote
Harmony      Harmony Hub                            Network Controller/Hub              Harmony Hub
Harmony      Harmony Hub                            TV Device                                   Vizio TV
Harmony      Harmony Hub                            Sound Device                             Sonos 5.1 Soundbar
Harmony      Harmony Hub                            Satellite Device                           DirectTV Genie
Harmony      Harmony Hub                            Satellite Device                           DirectTV mini-Genie
Harmony      Harmony Hub                            Activity                                        Watch TV
9

Sorry about the bad formatting. Cant figure how to switch to a fixed font here.

10

Where is the logic in this?

Capture016

Bed Light is a basic LED lamp plugged in to a zwave outlet.
Guitfiddles is a RGBW zigbee LED tape
Overhead is a zwave bulb in a standard light socket kept always-on by a physical switch blocker.

Bed Light gets included in the Light category via a config entry override. Revisit the first question posed in this post.

(This isn’t just about switches and outlets and lights… just a basic example of what I could rephrase with forum structure in the face of so many parallel platforms (referring to hassos, hassio, hassbian, plain-hass.)

1 Like
11

I guess I would be slightly happier if my Flirc and Harmony Hub were at least listed somewhere as something

12

@MithrasPan,

I’m now thinking that part of the problem is that the meaning of “device” is not well defined.

I’m seeing lots of zwave products with built-in mutli purposes.

For example my Husb2 usb stick is not a zwave stick, its a zwave/zigbee controller.

So maybe another term is needed, like maybe “physical device” and “virtual device” where a “physical device” always contains on one or more “virtual devices”.

And if you could say hassio only uses “virtual devices” then each “virtual device” could be assigned a unique “hass entity id (or maybe virtual device id)” which would be similar to a mac address or a celluar imei number.

Then you could describe physical things with better clarity. i.e. my husb2 stick would look something like:

Physical Device      Virtual Device                   HASS ID          Integration/Platform?    
----------------------     -----------------------------      ----------------      ------------------------ 
Huzbz2 Usb Stick   Z-Wave Controller            Entity #235       Zwave
Huzbz2 Usb Stick   Zigbee Controller              Entity #122      Zwave

Then something like this for a zwave light:

Physical Device      Virtual Device                   HASS ID          Integration/Platform?    
----------------------     -----------------------------      ----------------      ------------------------ 
Hue Z-Wave Light   Switch                              Entity #324       Zwave
Hue Z-Wave Light   Light Bulb                         Entity #866       Zwave

Then hassio would have to access Entity #324 to switch the light on/off and Entity #866 to adjust the light bulbs brightness and color.

p.s. I’m retired now but one of my hats way back when was Data Administrator for C&H Sugar. So I get my rocks off talking about this stuff.

13

An even better name…
Use “Product” instead of “Physical Device”
Use “Device” instead of “Virtual Device”

Product                   Device              HASS ID           Integration Platform?    
----------------------     ----------------      ----------------      ------------------------ 
Hue Z-Wave Light   Switch              Entity #324       Zwave
Hue Z-Wave Light   Light Bulb         Entity #866       Zwave

p.s anyway to change font here?

14

How/where are you doing that?

1 Like
15

via an entry in configuration.yaml

light:
  - platform: switch
    name: Bed Light
    entity_id: switch.zooz_zen06_switch_2
1 Like
16

Then that doesn’t seem to be a HA issue.

You actually created the light. HA automatically created the switch from your device as it’s supposed to do.

At this point you have the choice of which entity you display on the frontend.

17

I agree, but think this is where having solid scope and definition are key. When it comes to things like zigbee and zwave interfaces… I lean towards ‘controller’ or maybe ‘bridge’ if the category was being built to include… is a broadlink RMmini3 a controller? …is it an interface? …or is it simply a device?

18

Have you been keeping up with the thread or did you just decide to jump in with an out of context opinion?

That is a legitimate question.

19

Yes, I’ve been following but the screenshot you provided stated that it made no logical sense that the two entities you showed were the same device.

in that context what you were saying that made no logical sense was a self-inflicted injury. You created the light from an existing switch. HA has no way of knowing what you have plugged in to the zwave outlet (it could be a light, a heater, an AC unit, or any number of different types of loads) and the default platform for a zwave outlet is a “switch”. And besides that, you are the one who has control over the naming of your entities. You could have easily named the “switch.zooz_zen06_switch_2” something more logical like “Bed Light Outlet”

I will grant that there is enough confusion over the thread topic but in the context of the post you made that isn’t a part of that confusion. If you create multiple entities in different platforms based on the same device then that’s on you.

I’m willing to listen and try to understand what you are saying and why it might be related but there’s no need to get all snarky about my reply.

And that’s a legitimate answer. :wink:

As far as the real topic of the thread I’ve been trying to figure out where the “device panel” is located that the OP was referring to. I don’t use Hassio so I thought maybe it was a hassio thing. So I’ve been in the process of setting up a test hassio container (and failing so far). I didn’t want to comment on that until I figured out (or not) what the OP was talking about.

20

Go to the Configuration Panel where there is a sub panel with “Integrations”, “Devices” and “Users”. Im not positive but dont think its a hassio thing. I can provide screen shots if needed.

21

My listed devices:

 Device	 Manufacturer	 Model	 Area	 Integration	 Battery
Aeotec Limited Unknown: type=0103, id=00a4	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (2)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (3)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (4)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (5)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (6)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (7)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (8)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Aeotec Limited Unknown: type=0103, id=00a4 (9)	Aeotec Limited	Unknown: type=0103, id=00a4	No area	Z-Wave	-
Bathroom	Sonos	Play:5	No area	Sonos	-
FortrezZ MIMOlite	FortrezZ	MIMOlite	No area	Z-Wave	-
Master Bedroom	Sonos	Playbar	No area	Sonos	-
Somfy Unknown: type=5a52, id=5400	Somfy	Unknown: type=5a52, id=5400	No area	Z-Wave	-
Somfy Unknown: type=5a52, id=5401	Somfy	Unknown: type=5a52, id=5401	No area	Z-Wave	-
Somfy Unknown: type=5a52, id=5402	Somfy	Unknown: type=5a52, id=5402	No area	Z-Wave	-
VIZIO Backup	Vizio	D32f-F1	No area	Google Cast	-
VIZIO Master Bedroom	Vizio	V436-G1	No area	Google Cast	-
Z-Wave (Sigma Designs) UZB Z-Wave USB Adapter	Z-Wave (Sigma Designs)	UZB Z-Wave USB Adapter	No area	Z-Wave	-
Zigbee Coordinator	ZHA	EZSP	No area	ZHA

My flirc keyboard or harmony hub are not shown

22

From my configuation.yaml file:

# Controllers
zwave:
  usb_path: /dev/ttyUSB0
  device_config:
    cover.my_cover:
      invert_openclose_buttons: true
      
zha:
  usb_path: /dev/ttyUSB1
  database_path: /config/zigbee.db

# Flirc USB IRC  
keyboard_remote:
#- device_descriptor: '/dev/input/event3'
  device_name: 'flirc.tv flirc Keyboard'
  type: 'key_down'

# Harmony Hub Control  
remote:
- platform: harmony
  name: HUB@3911 Master Bedroom
  host: 192.168.0.182
23

Why, yes, there it is. I’ve never looked in there before.

I would assume from looking at my list that the only devices that are listed are only the ones associated with an integration that is listed in the integrations page.

The only integrations listed in the integrations page are ones that are supported by a GUI configuration. Not all integrations are supported by a GUI configuration. And not all platforms/devices are supported by GUI configurable integrations. Some platforms/devices still need to be manually configured. I don’t think those will necessarily show up in the devices list (tho some might).

As far as the confusion as to the terminology I agree it’s a problem. But part of the problem may lie in the fact that some devices don’t fit neatly into a pre-defined slot. And then there is the issue that not all integrations actually have physical devices. And entities are nothing more than a low level representation in the state machine of all the aspects needed to represent a device/platform based on the features that it offers.

there has been some progress made to reclassify things but TBH ultimately I’m not really sure it’s that important to how HA functions in the backend or even at the user level.

What real benefit will you gain by having a complete list of devices and the associated integration? Like I said I’ve been using HA for over two years now and have never looked at that page.

Maybe it might help to understand if you give an example of something you are trying to accomplish and not being successful because of some information you think you are missing.

You mentioned that you can’t see your remotes or keyboard in the device listing. How would having that information listed there help you?

1 Like
24

Not sure how to answer that.

Guess from my perspective as a user, I’m expecting to see a complete list of Integrations and devices that “I’ve installed”, whether they are Gui configurable or not to confirm my setup is “configured” properly. Plus I would like to see the devices sorted by their associated integration plus maybe a column indicating if the device is running ok or failed to load. The sorting would just make it easier to find what im looking for and their relationship.

I mean when I install a device manually, how do I even know the system even recognizes my configuration and is available to use when I cant see it listed anywhere?

For example this works fine but how would I know short of running some sort of test:

# Flirc USB IRC  
keyboard_remote:
  device_name: 'flirc.tv flirc Keyboard'
  type: 'key_down'

And how would I know that the following doesn’t work short of combing thru log files (maybe):

# Flirc USB IRC  
keyboard_remotes:
  device_name: 'flirc.tv flirc Keyboard'
  type: 'key_down'

Hope that makes sense.

25

On further thought, I just realized I’m describing the exact functionality of the Windows Device Manager.
Maybe Im just spoiled? hehehe :slight_smile:

1 Like
26

well, if you do a config check and it doesn’t return any errors you can at least be reasonably confident that the configuration is in the correct syntax.

then if the device shows up in the entity listing in the “states” page under the correct platform for whatever the device is then you can be fairly confident that the device should generally be recognized by HA using the configuration that you entered.

there are some things that there is no way for the system to know whether it is configured correctly and working because it relies on a user inputting the correct information. there’s no way to know if that info is correct. The best HA can do is check that the config syntax is correct and has all of the required information and nothing extraneous.

So, the bottom line lessons are that too make sure you always do a config check and fix any errors before you restart HA, make sure you have at least a basic understanding of what the correct expected entity_id should be (which includes the platform or “domain”) and that there isn’t really any way to know 100% that the device is working as expected until and unless you test it first (unless the device has error checking as part of its integration).

I think once you start using HA the things you are concerned about in this thread will seem less confusing and/or important. But then, of course, there will be lots of other things to be confused about. :wink:

1 Like