WTH: Why don't the developer documents cover VSCode's setup?

Archive Month of "What the heck?!" (2020)
1

The development documents only cover a small portion of the ‘setting up a development environment’. However these docs miss the most important part: Setting up the IDE (visual studio code) to properly run, with breakpoints. Simply providing an example launch.json would probably suffice.

For example: The dev container route describes all the requirements to set up ‘dev contianer’ on all 3 major operating systems. It even claims that VSCode is required. However the last set of instructions just get you a container running in docker. Additional setup is needed to get Home Assistant running with your changes.

I stumbled upon this thread with a lengthy vscode setup process for VSCode & Dev Container. I don’t know if this is correct however it worked for me. Either way, this should be included in the dev docs by someone “in the know” with proper corrections.

2

We really need this documented!
My development looks like this:
I copy/create a new integration in custom_components, do the edits, I add as many logger messages as I can, and then I start everything using hass -c config.

I have no idea how to use breakpoints while developing for HA, this is really frustrating and I lose a lot of time because I need to log everything I need.

I’m using Windows 10, I have Docker installed, when I clone the repo and open it in VS Code it is suggesting to reopen the folder in DevContainer (which is ok). But there is nothing about breakpoints and using actual hardware, in my case Raspberry Pi in development - I’d like to create a couple of integrations for specific hardware (mostly I2C). Ideally, I should be able to use a Raspberry Pi to run and debug my changes while using VS Code on my PC.
Can we use Windows and VS Code to develop and run code on Raspberry Pi with breakpoints?

3

Yep, and you can. I’m pretty sure all you need to do is:

Add the remote python debugger to configuration.yaml. It’s interesting, I didn’t know about this integration until yesterday late at night. After looking at those docs, it pretty much spells out everything you need. So in order to satisfy this WTH, the dev docs should just link to this integration.

# Enable VSCode debugging
debugpy:
  start: true
  wait: true

Then in VSCode terminal (with your dev container open) use this command:

hass -c config --debug

VSCode should then wait for attachment. Then in vscode run the following launch file:

{
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            // Example of attaching to my production server
            "name": "Python: Attach Remote",
            "type": "python",
            "request": "attach",
            "port": 5678,
            "host": "homeassistant.local",
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "/usr/src/homeassistant"
                }
            ],
        }
    ]
}

This assumes that your domain is local. If you don’t know it or just want to use the IP, change

            "host": "homeassistant.local",

to your correct IP

            "host": "1.2.3.4",

When you press run (if you have more than 1 launch config), select Python: Attach Remote.

Because python is weird with debugging, it requires libraries to attach unlike C# and other languages. I knew that but still wasn’t thinking about it being an integration (Stupid on my part). Anyways, I believe that the debugpy configuration opens the ability to attach to HA with debug via port 5678.

EDIT: This is mostly solved aside from the link to the debug integration.

1 Like
4

Yes, we need this! After spending over an hour trying to get my VS Code to launch HA “in debuggin mode” I gave up and started searching for some help in the web. I’ve found another post in this forum which helped me.
The HA dev docs are really poor and they miss a lot of things, especially reagrding how to buld integrations properly (which methods to call, how and when). All of this may be seen by analyzing code of HA built-in integrations. BUT such a fundamental thing as a documentation how to setup VS Code properly to have a fully working dev environment IS A MUST in the docs! No one will see it in any code. This is just KNOW-HOW, that you need to know by heart. Can’t be determined by deduction, at least not by a VS Code&Python newbie (like e.g. me).

By the way - seems debugpy is the only way of debugging HA. Launching the debuggin session with
/usr/bin/env /usr/local/bin/python /root/.vscode-server/extensions/ms-python.python-2022.14.0/pythonFiles/lib/python/debugpy/adapter/../../debugpy/launcher 36409 -- -m homeassistant --debug -c config
doesn’t work for me and it probablyt doesn’t work for anyone. It’s not mentioned anywhere in HA docs.

5

It’s right here. Basically just open in the dev container and you’ve got everything you need. This request has been met a while ago.

2 Likes
6

For what it’s worth, you don’t need to follow anything here when using dev container. It’s click install, debug. What I posted above works outside dev container, but it has issues on windows system due to how virtualizing works.

1 Like
7

Yep, when I created this WTH, dev container didn’t exist. It’s 1000000% easier now than it was when I made this topic.

2 Likes
8

Sure, I know this link, but it doesn’t cover the debugging part, which is essential in my opinion.
Debugging doesn’t work out of the box after setting up the dev container.
The default, most intuitive config, which I posted above raises errors while launching, just doesn’t work. The second config with debugpy also doesn’t work until you know you need to enable debugpy in HA config and launch your dev instance yourself for debugpy to be able to attach to it (by the way: I think debugpy should be enabled by default in a dev container instance without having to enable it manually). This is not covered in the docs.

But I thought I’m gonna add this info, so people didn’t have to search for it throughout the community forum.

1 Like
9

Huh, I guess that is true. I had that in my configuration.yaml within the devcontainer so I guess I forgot about it. Well you don’t have to leave the info here. You can click the edit button at the bottom of that page and add it.

10

You’re another person saying that, but as I set up my dev container 3 days ago and was unable to debug just like that - I thought I need to follow some extra steps to debug my dev container instance running locally.
The only thing that works for me is the debugpy solution. The docs say nothing about debugging, so one may think that debugging doesn’t work by default, especially when one sets up the dev container, hits F5 and it won’t work as in my case.

I don’t know why it’s not “click install, debug” in my case.

1 Like
11

Well, you need to understand how debugging in python works. It’s not like other IDEs. It’s a library that does it. If you’ve ever debugged into a python lib, you’d know that you need to import the library into the code you plan to debug. I guess it’s implied that if you know how to debug python that you’d know to add the integration. My post here is 100% about setting up vscode to debug. Which the dev container does for you. So in my eyes, my WTH is solved because it never used to have those setting and you had to create them yourself though furious googling.

12

You’re correct, your WTH is solved.
And my point is that the dev container doesn’t provide a hussle-free debugging for everyone. It’s probably not the devcontainer, but VS Code that has some bugs.
I’m not alone in this. Another user who wrote this post Developing Home Assistant Core in a VSCode Devcontainer - #12 by dave_t_uk did have the same problem and we both setup the devcontainer in the last days using the newest HA build. Coincidence?

But luckly after doing some more furious googling I’ve found a solution/workaround that worked for me and him and now we can both enjoy the “default” debugging function without having to enable the debugpy integration in HA configuration.
He’s gonna post my solution in his guide, so whoever encounters the same issue (I’m pretty sure someone will sooner or later) will have the solution on the table after doing some furious googling leading him to this or the other post :wink:

13

Those errors look like he didn’t wait for the setup script to complete and fully install all the dependencies.

Also, if you followed that guide, there’s alot of old information in it that’s no longer needed. The directions in the dev docs are watered down so that you don’t need to learn vscode. You can do everything from vscode by just opening the command pallet, opening a remote repository, selecting your fork. When the container is set up. You should be able to run home assistant. If it errors, then it’s missing dependencies and you can just install the requirements through pip or use the setup script.

14

I think we’re on the same page here. The wth is solved because devcontainer and corresponding doc updates have made the process of getting a dev environment set up much easier.

That being said, there’s still extra steps to get a debugger attached which aren’t currently covered and could be made easier. Including your note here in the doc is one option.

Another (that I would prefer personally) is to update the devcontainer so the configuration.yaml used by the launch task includes debugpy. Or add a cli param that adds the debugpy integration even if it’s not in configuration.yaml and have the launch task use it. Something along those lines seems good.

15

I waited until the script told me that it had finished, with something like “do xxx to close this terminal”

Then I tried rebuilding it two more times, and restarting HA and vscode multiple times. I don’t think it was a time/waiting issue.

Ok, so might be a silly question, but I don’t get this. If there are some dependencies missing immediately after the devcontainer is built, then doesn’t that mean that everyone will have exactly the same problems? So there’s no ‘if’? Don’t we all have identical systems at that point? Or have I misunderstood?

I get that the dev container won’t pre-install every python library for every integration. But it would be great if it could auto install the ones needed by the base system.

My experience is that it doesn’t work seamlessly and I have to fight it each time. My sledgehammer option (rip up everything and rebuild from scratch) doesn’t make any difference.

And I really don’t get why. I thought that once I’m inside the fresh docker container, it ‘looks’ the same for everyone (like the inside of the
original developer’s docker container).

Is my understanding wrong?

16

HA installs dependencies when they are configured and needed in the system. I would assume this is the case when running debug. This usually takes time, I’m impatient and just install everything right after I create the container so I don’t have to wait when I press play the first time.

17

I did the same thing, I’m pretty sure and still ended up with errors while launching the ‘Run task’ for the first time after rebuilding finished. As I said, I rebuilt my dev container multiple times and never experienced this before.

Wouldn’t that mean that HA won’t finish launching itself until it installed all the dependencies and that theoretically prevents any runtime errors related to missing dependencies? Or this is some parallel process and HA can still end up with errors for the first or second time until everything is installed?

18

Solved in the end. For me it was a cached docker image that had a different python 3.9 bundle than the current one.

Details here.

1 Like