Hi everybody,
One of the things that confuses me - as a HA newbie - is the concept of helpers.
Via another discussion I found a link to the helper documentation, but that is quite empty. So I want to create a pull request to extend that documentation, but first I need to make sure I understand it correctly. And when searching for helpers, most of the info I found is quite advanced…
From this nice video I understand that a helper is a variable in which you can store data, to use it afterwards in different parts of HA (automations, scripts, dashboards, …).
That is very clear, but I have some HA beginner questions about this definition:
- That video is 4 years old and HA is changing continiously, so not sure whether that definition is still correct? Because when I look at the available helper types I see e.g. “change device type of a switch”, which doesn’t look like a data type to me at first sight…
- The list of helpers (see link in point 1) is available under “integrations”. What is the relation between integrations and helpers?
- It looks to me that the helpers list contains a mix of variable data types (text, switch, number, …) and tools (change device type of a switch, …). Which might explain the title “Tools and helpers” in the documentation perhaps. Am I correct?
Thanks a lot for illuminating me, so I can try to update the documentation to help other beginners!!
Bart
I’d avoid this rabbit-hole if I were you. Down there madness lies. 
Documentation and terminology in HA have improved immensely in the last year or two, but there are still plenty of fuzzy bits. There’s a glossary which is quite useful (although it doesn’t include helpers).
I’ve always defined a helper as “a module which does useful stuff” and left it at that. They’re UI-based (although some have yaml options) and I think that may have been the point originally - they make “useful stuff” available through the UI. All of them are documented individually. They’ve recently been included in the integrations search page as part of a move to make documentation more accessible, but you’re right, they’re not the same thing - as the glossary says, an integration usually connects with devices and services. Helpers don’t appear on the integrations page in the app.
I believe there are moves to revamp the documentation generally, but that’s a monumental job.
Don’t watch any video older than six months. Many were very good originally, but they can’t be updated, so they become misleading.
1 Like
Conceptually, I think of Helpers as a user-created entities defined in the GUI.
User-created entities from outside the GUI are generally not called Helpers, but entities that can be defined by the user in the GUI have generally been put into the Helpers section.
Helpers started out with mostly “data type”-like entities, but gradually added features like “change device type…” which simply creates a new user-defined entity based on another entity, similar to how a template light creates a user-defined light based on jinja code. Over time a lot of YAML-only template entities have been added to Helpers because they can now be defined in the GUI. Template entities that are still YAML-only are not considered Helpers, which may sound a little inconsistent but consider that the end-goal is likely to make all template entities into (GUI-defined) Helpers some day, we’re just still in transition.
2 Likes
This is my understanding/approach to helpers/integrations.
An integration provides a bunch of functionality out of the box, sometimes to interact with a specific physical device, but it can also just be something more “virtual” (eg. a weather integration which pulls weather info from some provider). These are all “standard”, in the sense that whatever you get there is entirely defined by the integration and there’s not much you can do there, other than configuring the integration.
If you need to have other, more custom entities, you can use helpers. These are not linked to integrations, but can be basically whatever you need. These can then be used in whatever custom logic you need, eg. I have:
- A helper toggle to enable guest mode, which disables certain automations
- Garbage collection schedules for organic/waste, which is used to show notifications on my dashboard
- Toggles to select which rooms should be vacuumed
- Whether we are sleeping or not, so certain lights are not turned on when motion is detected
These are all not related to any one integration which provides them by default, but are created by me for whatever purposes I need. They can of course use other integration entities (eg. the change switch type changes some light switches I have integrated via the Zigbee2MQTT integration to be shown as lights instead of just raw switches), but they can be created ad-hoc and separately.
1 Like
@jackjourneyman, @peterxian, @gutifarra
Thanks for taking the time to write down your ideas about what helpers are all about. Really appreciated!!!
If I understand correctly, I can summarize it a bit like this (to support my visual oriented brain):
Hopefully - one day in the future - the helpers are refactored to make the distinction between the variables (or custom entities) and the helper functions a bit more clear in the UI. Imho that would really be helpful for beginners…
I am not sure whether the fog in my head has cleared enough to write a “clear” documentation page about this. But hopefully others can get some insights at least from this discussion.
What you are categorizing as “helper functions” don’t “manage how other entities behave or are represented”, they create new entities… The original entities still exist and have the same utility they had previously.
1 Like
Ah yes indeed, you are right.
That was indeed another thing that confused me this week, but with your feedback it makes a bit more sense now. I had a Shelly switch, which had (obviously) default type switch. But I wanted it to be type light, because I use that Shelly to turn off/on a light.
To do that indeed I found that I needed to use a helper “change device type of switch”. I thought first that this helper would change my entity type from switch to light, but instead it created a new entity light next to the existing entity type switch:
To be honest I was first rather confused about that, but with your help it makes more sense. I assume the original entity is created and managed by the (Shelly) integration, so I need to consider those entities immutable perhaps? So that I cannot update/delete these entities, so I only can create new entities myself. The “delete” button in my entities dialog window is disabled, perhaps because of that?
Is it better to look at helper like this then (?):
So if you need to create a custom entity, you always need to use a helper: you can create an entity yourself (with a specified data type) or you ask a helper function to create an entity for you (based on one or more other existing entities). Is that definition a bit correct?
Forgive me the avalanche of questions!
Correct, they are created by the Shelly integration. You cannot delete them without deleting their unit instance of the integration, but you can disable or hide them.
Not if you define Helpers as being created in the GUI. You can create many, but not all, of the same custom entities (and some other ones) directly in the YAML configuration, not in the GUI.
2 Likes
