Tutorial for creating a custom component

Development
8

Finally wrapped up this series of posts (only took nearly a year :smile:):

6 Likes
9

Hi. Thanks for this. How up to date is this tutorial? I just upgraded HA by pulling latest and a custom_component broke because HA seems now to want to look for setup.py and not init.py?

10

Still working on the latest, 2021.11.5, on my install. Could you provide some more information about what you are seeing in regards to setup.py? As far as I know that isn’t something used in custom components.

1 Like
11

All good, on traceback the problem was the custom component updates required a “version” parameter and the component I was using was behind in that requirement. I added the “version” parameter to the config and everything sorted itself out. The setup.py function just failed with an uninformative error report, the setup.py function likely was baulking at the missing “version” parameter.

12

Thank you so much for this wonderful tutorial. It fills quite a few gaps from the official documentation and adds some context where I was lost as a beginner.

Looking at the code of quite a few integrations, I noticed many integrations using a coordinator but I have to admit that I don’t fully understand how that works. Could you maybe point me in the direction of some explanation or - even better - add another chapter to your wonderful tutorial?

All the best and happy new year!

13

I think the official developer documentation has a pretty good description and example: Fetching Data | Home Assistant Developer Docs

Here’s a snippet from a somewhat related blog post that describes when you would use it (Use CoordinatorEntity when using the DataUpdateCoordinator - Automate The Things) :

Home Assistant’s DataUpdateCoordinator which drastically reduces network calls by fetching all of the data needed by the entities just once. The entities then use the data stored by the coordinator to update their state. The other way to do this is to have each entity (think 10 games on your wish list) and each one individually hits the api to see if it’s on sale. Since all the data comes from the same endpoint we only need to make that call once and the DataUpdateCoordinator helps us manage that.

Thanks for the suggestion, I think it would be a good idea to write up a little post about it since it’s a little bit buried in the documentation.

14

Thanks for considering. I had found your blog post and that helped me quite a bit. However, while the documentation is great for looking up stuff, your tutorials take this to another level for a beginner like me.

There are also other things that at least to me weren’t obvious, like how to list several entities as part of one device. In the documentation, the terms of devices and entities seem to be mixed at teams - or I just didn’t get it.

I guess a lot of stuff is obvious for the seasoned Python dev and wide-spread convention, but not so obvious if you move over from another language and try to get your head around HA.

15

Devices vs entities can be confusing at first, but is an HA concept and not anything related to python. Consider a device to be a physical thing (like a sonos speaker) or an api. Each device can have entities, so the Sonos speaker has a media_player entity and a few switches. In order to let HA know each device you must define a unique_id when setting it up in your component. This will ensure all entities related to that device are grouped together.

It gets a little tricky when there is no physical device, like the github tutorial example component. I don’t actually define a device and I’m not entirely sure what should be considered a device (each repository added?). One day I wouldn’t mind revisiting this to see if I can make improvements there for this tutorial.

It’s helpful to browse the core code and checkout how core platinum integrations handle this for one that uses an API and not a physical device. I learned most of what I know by browsing existing code, but I still don’t consider myself to be an expert.

16

Thank you so much. I browsed your code and quite some other integrations and just finished my first custom integration. It still lacks good tests and probably is not very robust if something goes wrong on the way, but it works and even uses devices.

Your tutorials definitely helped a lot.

1 Like
17

Awesome, glad to hear it!

18

Thanks for the tutorial. I started with your tutorial before I even found the official documentation - I probably would have been pretty confused without it! And I’m so glad to see the devcontainer thing, I was dying before I read that, as every time I made a little change I would copy it to Home Assistant and wait 1-2 mins for it to restart!

Anyway, I may be totally missing it in the documentation, but I can’t find anything that talks about how to create a device. Can you give an example of this?

19

You can find the documentation for devices here:

Essentially, you define a device by setting a number of properties in entities. All entities with the same properties will be bundled as a device. There is no separate class for devices.

20

Thanks, I guess I had trouble navigating the docs! :smiley: Looks like it’s much easier than I thought!

21

Once I add config flow to my integration, I can rename entities through the GUI. However the names reset when I restart Home Assistant. How can I prevent this?

22

Oh I see, problem was that I was just restarting the Home Assistant Dev Container, and so I guess Home Assistant just didn’t have time to save my updates. I chose Stop Server in the UI before restarting the Dev Container and it worked. :smiley:

1 Like
24

Thanks for the article. Glad something to gude to get started. I have HA green device. I am assuming that I login to terminal (not Docker home assistant) and change folder to custom_components and run pip to install cookie cutter template. Please let me know otherwise.

25

It would be much easier developing your custom component by running the devcontainer in vs-code from the core repository. Then creating a config/custom_components directory in that checked-out repository. It will be much faster to spin up and restart as you make changes.

To create the initial structure, I’d just create a virtualenv on your local machine, activate it, pip install cookiecutter, then use cookiecutter to create your project template.

1 Like
26

Do you manually copy custom component into the devcontainer? Is there a way to sync the custom component repo to the devcontainer?

27

The config directory will be mounted into the devcontainer so you shouldn’t need to sync anything.

So, if you have the core repo checked out and create a config directory at the root and a custom_components directory within the config directory then you can edit files there and HA will see the custom component. Note you will have to restart the devcontainer when making changes to the python files.

example: /path/to/core/config/custom_components/tutorial if your custom component is named tutorial and exists in a directory at this location.

28

Got it, thanks.