Developing integrations for Home Assistant OS

I have HA OS installed on a raspberry PI and I’m trying to use it to control various components of a heating system. One device I need to control is a pump that has a PWM input. Ideally I’d like to make use of the PI 3b’s hardware PWM to avoid any potential timing/alignment issues from trying to do pwm in software, but AFAICT there are no integrations for directly controlling the hardware PWM. I’m happy to write my own and it looks like it would be relatively simple, but I’m not sure how to go about debugging/testing a custom integration with a HA OS install. Ultimately I presume I have to rebuild the HA Core docker image, but is there a more practical way to test a new integration during development? Since I need access to the RPI hardware to see if things work it’s not really practical to test it on my PC. If possible I’d like to avoid having to completely reinstall my RPI HA install since it’s actually in use right now. How do people normally do this? The development docs seem primarily focused on people developing against HA core running directly on a local machine rather than in the docker-ised HA OS environment. Any guidance/pointers to other docs would be greatly appreciated. Thanks!

Having done tons of development on my past home automation system I’ve been researching this topic fairly deeply and I can agree that the documentation on writing an add-on makes it look like a daunting prospect.

Two things you might want to research, and where I’m focusing my attention as a primer before I really get too deep in the development system HA has outlined, is to use an add-on like Pyscript for your immediate needs, it’s super easy to do quite a bit with. Second take a look at “custom components”, which is sort of a lite version of full development add-ons. I haven’t worked out all the details of a custom component, but it doesn’t look too challenging.

That being said, Pyscript for one-off or “me only” needs has been perfect.

I’d like to add to this to say that, while it can’t cover everything (yet) PyScript can be use in quite a few cases where a “custom_component” would be created otherwise. However, for PWM output, we’re talking about a whole other beast. Your best bet, I think, would be to develop that separately with a simple API of its own, and then integrate that API with Home Assistant (either via the REST component, with a custom component, or via Pyscript).

Ok, sounds like I need to check out pyscript first of all, thanks for this tip. Writing the python for PWM control should be pretty simple I think; if there isn’t an API already I don’t think it’s that hard. Worst case, there’s an interface under “/sys/class” that can used just be writing to the filesystem.

A couple of clarifications; when you talk about “custom components” are you talk about what are called “integrations” in the current documentation/lovelace UI"? Looking at the source tree it seems like the “components” in there correspond to the “integrations” I see in the UI so that would make sense.

Secondly, if I did end up writing a custom component/integration, I’m still puzzled about how I develop/test this when I’m running HA OS on my target platform. Do I have to manually copy my python files into the docker volume on the raspberry pi?

a “custom_component” is just an “integration” that isn’t part of Home Assistant Core. Home Assistant uses terms that are not always clear. Like platform vs integration vs component. And entity vs entity_id vs device.

To develop a custom_component, you can do this quite a few ways. On your local workstation (windows, macos, linux) you can run VSCode and use the “.devcontainer” included in the Home Assistant Source. It uses Docker behind the scenes to set up a development environment for you. Or, what I do, is to run a separate docker instance for development. That instance has /config mounted as a volume. And in /config is a directory called custom_components. Your code goes in there, and you restart Home Assistant with every code change.

I don’t run HA OS, so I can’t speak to that specifically. But, in general, you don’t want to develop in your “production” Home Assistant for many reasons, the biggest of which is that Home Assistant needs to be restarted a lot when developing and taking your whole Automation system down over and over again to do so is annoying. Plus, if you have a lot of integrations in use already, Home Assistant can take some time to start up. By using a separate instance with almost nothing in it, startup is much quicker.

Thanks for your helpful responses. It’s becoming clear to me that installing HA OS was actually a mistake for me. Although it’s convenient it looks like it’s not practical for doing any kind of development - I need to be looking at a standard dockerised HA Core install if I want to be to hack around with it/install new dependencies like pigpio etc.

The VSCode option sounds like it’s probably going to be the quickest to get me up and running. I understand what you’re saying about not developing against the “production” instance - that does make a lot of sense and it’s what I’d normally do. The tricky bit is obviously that a big chunk of what I want to do depends on the RPI hardware/OS specifically so actually testing the output of what I’m doing on my development box is going to be tricky. Do people often run a development environment on a virtualised RPI to get round this?

Honestly, I’m not sure what other people do for that specific scenario.

For me, personally, I like having a separation between the devices I use and Home Assistant. So, anything I developed that required the RPI hardware would be in its own software package that is not TIED to Home Assistant, but exposing an interface that Home Assistant can use.

So I’d have Home Assistant running (maybe on the RPI, maybe somewhere else, it doesn’t matter). Then I’d have a service running on the RPI to interact with the hardware in the specific way you are trying to design which would expose an API. And then I’d have another Home Assistant instance to develop the component to talk to the API. And then once it was developed and working, I’d move the component into my production Home Assistant.

What worked for me was (developing on W10):

  • Installed Docker
  • Installed Visual Code
  • Cloned
  • Launched Visual Code and loaded the folder for core ( Visual Code recognized it was dockable and offered to use it in a docker environment ), same as swiftlyfalling mentioned:

That was basically enough to start developing.

I had some issues using the custom-components folder, but it turned out it is just as easy to use the components folder during development and then copy it to custom-components on production server or make it available on github (with or without hacs) :yum:

Ok, so I’m going to have a go at starting from scratch again. Before I waste massive quantities of time, what I’m thinking about doing is:

  1. Reinstalling my RPI with raspbian
  2. Installing docker on the RPI
  3. Installing pigpio on the RPI + enabling all the various modules i need (1-wire etc)
  4. Running HA as a docker container with --privileged - initially unmodified in the hope that I can get by with pyscript for what I need to do
  5. If I need to develop a custom component against it I’ll just run the docker container on my dev box and develop the custom component in the docker volume, restarting as I change things.

Does this sound plausible?

sounds good to me.