It's THAT easy! Building a new Home Assistant integration in Python

Step-by-step guide to how to build support for a new Bluetooth device for Home Assistant, write a new component using Home Assistant's built in Visual Studio Code, and how to integrate a new Bluetooth Low Energy light into Home Assistant.
This is the sequel to the "How to reverse engineer a bluetooth device video".
Watch the first part here: • How To Reverse Enginee...
Home Assistant Godox Integration Code: bit.ly/3NRvjcx
Home Assistant Documentation:
"My First Integration" - Official Home Assistant Documentation: developers.home-assistant.io/...
List of existing entities: developers.home-assistant.io/...
Software:
Home Assistant: www.home-assistant.io/
Hardware:
Godox VL150: bhpho.to/3jkurjI
Raspberry Pi: bit.ly/3MvnybR

[@hml]

Errata: So after I published the video, it was brought to my attention that SUPPORT_BRIGHTNESS is deprecated, and is going to be replaced with ColorMode.BRIGHTNESS. Keep that in mind if you try to follow this tutorial. For more info, check here: developers.home-assistant.io/blog/2022/04/02/support-constants-deprecation/

[@doenyas]

can you help with setting up using the new ColorMode.BRIGHTNESS ? What need to be change in the code? also I have Godox 60TL with colors, can it used the same way ?

[@dronenb]

This series is pretty cool. Can't wait for the next part. Subscribed!

[@hml]

Thanks for subbing! Working on a few different videos in this series, as long as a bunch of other digital life hacks.

[@FreeFrag2]

​@@hml When will they come?

[@hml]

@@FreeFrag2 Unfortunately, I'm hardly ever home lately, since I travel a lot due to work... I'm gonna be back in my office in 1.5 months, and will finish the video. In the meanwhile, I will post the link to the updated code on my discord, so you won't have to wait.

[@FreeFrag2]

@@hml Thanks a lot and I understand completely. Really hard to get all you want done when travelling for work. Would appreciate a lot if the updated code would be published. 🙂

[@rogerq7369]

This is a great video - I install HomeAssisstant on the Raspberry Pi and I want to write Pyton code but I didn't know where to start. Massive help - now I can look to write my own integration to MyEnergi Eddi (in order to automatically turn it off each day between 4 and 7 so that I can export energy 🙂

[@chrislambe400]

What a cool video series. I was hacking my Specialized e-bike several years ago to make the max speed higher with the same method. I was changing the wheel size to something smaller than the bluetooth service app would allow. It was difficult as the bike and app where really chatty. I finally found where to do it, but then my bike broke under warranty and it got a new different controller. Boy was I dissapointed. Now inspired by your video I will try to integrate my Nautilus e628 eliptical trainer into HA to get my training history into HA for some Stats on a dashboard. Yeah Google Fit can do it, but Google ain't getting my health served up on a platter.

[@hml]

Nice, I'm actually planning to reverse my treadmill as well, and integrate into HA, so it should be similar. Curious to hear more about your efforts - would love to share your progress with my viewers!

[@groshert]

Hi, got anywhere with the eliptical trainer yet? Am thinking about creating an integration for my Waterrower Smartrow which sends data via BLE.

[@samsstills]

Fantastic video, so helpful, thanks man.

[@hml]

Glad you liked it!

[@pradzieda]

Great video as always. I wonder i you could film video smartyfying dumb apliences like cheap tower fans, kettles, so on. Keep up the good work

[@hml]

That's a great idea! Thank you! I was actually thinking of "smartifying" my coffee machine. I actually used to have a startup of smart coffee machines, so I know a thing or two about that :-) About tower fans - most of them come with a IR remote, and I will make a video about how to automate anything-IR.

[@CarAudioInc]

awesome! thanks for sharing

[@hml]

You are very welcome!

[@knightlautrec4311]

I'm trying to load in a custom component created from one of the Core integrations from HA, but I don't understand how to load it in YAML. Where is that usually defined and how do I load it? It's a weather integration.

[@VinceBalsamo1]

Would love a refresh of this using the new Bluetooth integration. Can't seem to get your code to work as an integration (direct on pi worked) and I think it is because of the new way these are being done.

[@hml]

Yeah, it's coming soon. I know I've been promising that forever, but the code is done, just need to record the video, will do it this week. This time I'm also showing how to work with HA in docker and how to build a config flow, so should be worth it.

[@martynbarnett2463]

Hi... great video... but a critical question please... the Home Assistant Documentation seems to "strongly" suggest we should not be putting integration API code (python that actually talks to devices (such as your godox) into the home Assistant code, and we should instead be importing from the PyPl Library. In your video I think you are showing us that you put your device specific godox code into godox.py and did not import from a library... is this right? and what do you think about that? Many thanks...

[@hml]

Thank you! You are indeed correct, that the proper way to implement a HA integration, is by creting a PyPI library and then calling it from the integration. The main reason for this is ease of maintenance, and to allow others to contribute to your integration, even if they don't use Home Assistant. However, if it's a local integration that only you use - it's much easier and faster to do the full integration locally. Especially with the new Bluetooth native recently introduced. Also, I intentionally separated the code interacting with the light into a separate module - that way it's easy to extract it to a PyPI integration, and that definitely would be the next step.

[@fasthowto]

Is this still correct for current versions of Home Assistant? I have several Amaran lights that I use for my channel, and I'd LOVE to be able to control them via HA. I was going to use your first video to reverse engineer the protocol. Thanks!!

[@hml]

This still works, but quite a bit outdated at this point. I keep planning to make an updated version, but unfortunately life and other interests are in the way...

[@RazuEazu]

I was looking for a video on whether it is possible to run a python program with its libraries in HA. But it's also been interesting to see this.

[@hml]

It's definitely possible, either as an integration, or as an addon, what are you trying to run?

[@RazuEazu]

@@hml It is a Chat Bot for Telegram entirely in python with libraries such as pyTelegramAPI, pymongo, nltk, setuptools... It would be to run it independently and make it functional without having to use other Raspberry exclusively for it.

[@hml]

@@RazuEazu sure, you can easily wrap it as a Docker container, and then use that as an addon in HA. Alternatively, just install the Portainer add-on and run the Docker container through that.

[@EngineerK]

Any chance you could do a tutorial on setting up a home assistant development environment in docker? . I want to be able to debug my code

[@hml]

Absolutely. Was planning to do a Docker tutorial in general soon, and I could use HA as an example.

[@russellehrnsberger6591]

How would I go about creating an integration for homeless assistant for a online platform. I'm looking at a light controller that has its own online platform and can offer an api for integrations

[@hml]

Exactly same process, just instead of using Bluetooth to connect to the device, you use the devices API. So async_setup to connect to it, async_update_data to update the data from the end point. As far as Home Assistant is concerned - it doesn't care how you control the device, in a way.

[@TomTheDutchy]

i already have a folder called custom components and its filled with hacs and pyscript folders, how to continue?

[@hml]

You just create in custom_components a new folder that is named after the component you want to create. Don't touch the other components in there.

[@TheJCDFilms]

I am trying to setup a button and not a light and having a difficult time determining what headers to use instead. Where did you find the light example you are copy and pasting from? Is there an example to for setting up a button? For context, the device I am trying to control is an adjustable bedframe and does not report back its state to the native app. So I want to be able to control it from HA using Bluetooth and emulate the Bluetooth commands.

[@hml]

The code I copy paste is from code I wrote myself (you can see it in the linked repo in the description), however it's heavily based on the examples from here: github.com/home-assistant/example-custom-config/tree/master/custom_components, specifically "example_light". You can take a look at the example for "detailed_hello_world_push", which implements window blinds, that I imagine would be similar to the bed frame you're trying to implement. The light in the video doesn't report back it's state either, so you just need to implement it with "assumed_state", and in your case, I would imagine you would based it on either "SwitchEntity" or "CoverEntity" (developers.home-assistant.io/docs/core/entity/cover), instead of the "LightEntity" that I based it on in my example.

[@TheJCDFilms]

@@hml thank you very much!

[@hml]

@@TheJCDFilms sure thing! Let me know how it goes, I'd love to feature your solution on the channel!

[@duuuuus]

I am trying to do the exact same thing at the moment, please let us know if you make it!

[@neekster28]

HomeAssistant released their native Bluetooth support. Could you do a follow-up video explaining how that is different and possibly editing your integration to work with that?

[@hml]

Definitely, working on an update to this tutorial for the new native Bluetooth integration right now

[@TheJCDFilms]

@@hml any updates on this update? Curious if the Bluetooth update simplified the process at all

[@hml]

It definitely made the configuration and discovery of Bluetooth devices easier. The code is ready for a while, need to find some time this week to record the video. The video will include working on HA in Docker, and building a config flow as well, so a bit more advanced than the previous one.

[@TheJCDFilms]

@@hml great! Do you have a GitHub where the code is? Or are you waiting to release that with the video?

[@duuuuus]

@@hml Any news on the video? Can't wait :)

[@pete.n.]

I do not get a simple example to work. Is there a github repo with the final solution?

[@hml]

Sure, click on the "Home Assistant Godox Integration Code" link, and it has the final version of the integration. But also, feel free to ask here, and I'll try to help!

[@user-ne3yz6gc5u]

Hello. Many thanks for this tutorial. It is pretty clear. I was looking for a way to create my own integration. To be honest, for the moment, I don't need to control a bluetooth light but I was interested in how to create an integration that manages a hardware through python script. Anyway, I have created the files in my "custom_components" folder and edited my configuration.yaml. Unfortunately, I can't see any new device neither in the dashboard nor in Settings->Devices->Integrations nor in Settings->Devices->Devices. I don't know what I missed! Is it because I don't have the bluetooth device? If you could help me it would appreciate. Thanks.

[@user-ne3yz6gc5u]

I could have found a problem. The configuration checker in Developer Tools raises this error : "Platform error light.godox - Requirements for godox not found: ['bleak==0.14.1']." How to fix it?

[@hml]

Hey Matthieu! Hopefully you already found the problem, but first - make sure that the manifest.json includes "bleak" in the requirements. Also, if you'll check the code repository (github.com/hml-yt/ha-godox) there's a new branch there called "ha-native-ble" which is an updated version of the code for the latest HA version (which I prepared for a future video, but didn't get the chance to do the video yet) so it might be a better starting point. Lastly, our Discord might be a better place to ask questions, and I'll try to figure out the issue you're having together with you over there.

[@user-ne3yz6gc5u]

@@hml Hi! 2 months later, I finally found some time to work on my project. Unfortunately, the GitHub link you sent seems to be out of date. Is there a new link? I just joined your Discord channel. I will continue this discussion there. Thanks

[@isniphsi7843]

Does folder have to be called godox or should that be the name of the script?

[@hml]

The folder doesn't have to be Godox, it should be the name of the integration you're creating. In my case, it was for a Godox light, so I called it "Godox".

[@isniphsi7843]

Thx@@hml

[@johnreese7986]

I actually want to try and build some custom components, in your video you kind of skipped the explanation of building an homeassistant component, and showed how to create a specific script for a specific purpose. Can you by any chance give me a place where I can find a good tutorial or a documentation to the custom components building from scratch? I have knowledge in python, so O just need the basics of how an homeassistant component should be built. Thanks in advance :)

[@hml]

Sure, the documentation is here - developers.home-assistant.io/docs/creating_component_index/, but generally you have a number of entities (like I show in the video) that you use as the starting blocks. In this example, I used the Light entity as the basic block to create a light integration. It's not a script, but a full integration - it supports scenes, brightness, on/off and so on. Good luck! What are you trying to build?

[@talissonjorge1989]

TOP

[@TheMixflow]

didnt know dji made microphones :O and good quality too aparently

[@hml]

Yeah, it's the new DJI Mic, released about a month ago and it's really awesome. Should I make a review of it? www.dji.com/mobile/mic

[@artfulbodger2k]

@@hml a review of the DJI mobile mic would be helpful, maybe compare it to some of your previous Mics too?

[@nagarava]

How to 8ntegrate raspberry Pi pico?

[@hml]

How do you integrate it to what? You want to run Home Assistant on the Pi Pico, or use it to update something inside a different home assistant instance?

[@nagarava]

How to integrate as esp8266

[@hml]

@@nagarava so you want to use Pico to control another device, similar to the ESP8266?

[@nagarava]

@@hml yes

[@hml]

@@nagarava Interesting idea, I will definitely make a video on this in the future!

[@pedrohenriquepeixoto3964]

Feedback as a developer: This is hardly an overview on how to build an integration. You didn't even touch on the config flow, which has been the recommended patter in HA for quite some time now. You also didn't touch on stuff like interfacing with actual devices and/or external APIs. Nothing agains the video or content itself, but I think you should name it accordingly.

[@hml]

The actual interface with the device was converted in the first part (Reverse engineering Bluetooth devices), and when that video was made it was before the new config flow or native Bluetooth was introduced... I keep planning to do an update with config flow and native Bluetooth, but I'm never enough in my office lately to actually work on it...

[@mikekornikh]

@@hml +1 on that video. Can't wait for the release!

[@DmitriyKhazansky]

I’d to see one you actually write from scratch and not copy and paste blocks you’ve pre written

[@hml]

You sure? I thought it would be pretty boring to watch me type for half an hour :-) But I guess in the future I could share more of the thinking process.

[@DmitriyKhazansky]

@@hml I know almost zero about python so it’s the why that’s important. t hardest part for me is understanding why you’re including the blocks you did and where you got the “base” of each block. And other items like what documentation are you referencing as you’re making this (dev docs, previous things you’ve done, others integrations?)

[@duuuuus]

@@hml I would much rather have 30 minutes of typing that I can scroll and skip through than 10 minutes that I do not understand without knowing Python and the libraries used. We are here to learn, not to be entertained :) Would also make it a lot easier to adapt the methods you are using to other types of BLE receivers that do not have any integrations written yet, like adjustable beds, relays, power outlets etc.

[@Electronieks]

Add a python code from start