Visual Studio Code调试Home Assistant代码(WSL版)

最近在瀚思彼岸看到M大的写插件教程帖子提及用pycharm断点调试插件,想到自己一直以来开发插件全靠logging埋点看输出、研究HA核心功能代码依靠人肉追踪,真有点内牛满面。不过M大的调试方法不是放在普通原代码上的,貌似也没法追踪HA主程序代码,用的工具也不是自己熟悉的,于是乎狠下决心去折腾实现能用VS Code对HA代码进行直接调试,发现坑真不少。


0.环境

  • Win10 LTSC 2019 + WSL(Ubuntu 18.04)
  • Visual Studio Code 1.38.0

1.问题及结论

这几天先是按官方的搭建开发环境文档去搭了(VS Code+容器)环境,结果发现压根没提到调试方面的操作。后来在官方的论坛中有搜到不少无法追踪断点的问题,不过没发现解决方法。再后来百度有人提及是目录位置问题才有了转机,瞎折腾测试一番总是解决了。

  • 问题
    • pip安装后,使用site-packages/homeassistant安装目录作为VS Code主目录,运行会跳过所有断点,显示“未验证的断点”。
    • 在其它路径放置HA代码目录homeassistant作为VS Code主目录,断点在__main__.py程序入口373行之后就不停了。
  • 结论

    • 要正常调试需要Linux环境,并且不能用pip安装目录的代码。
    • 要跟踪断点的代码需要在同一个VS Code主目录。
  • 解决方法

    • 将配置目录和程序代码放一起,这样可以调试自定义组件。
    • HA程序代码使用了不少from homeassistant import xx方式导入包,如果以HA代码目录比如d:\homeassistant作为VS Code主目录,则运行点就跑到pip的site-packages/homeassistant安装目录里的代码去,所以需要利用Python的搜索优先规则,给HA代码目录加多一层上级目录,使得导入的是VS Code主目录下的HA代码,也就能调试HA主程序代码

2.准备

  • Windows下启用Linux子系统功能,开始菜单->设置->应用和功能->程序和功能->启用或关闭Windows功能->适用于Linux的Windows子系统。 INFO:也可以PowerShell(管理员权限)运行Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
    INFO:安装完毕需要重启。
  • 下载Ubuntu 18.04安装包。下载地址

    INFO:也可以在Microsoft Store中安装,不过下载安装包安装可以选择安装路径。

  • 解压安装包至安装路径,运行ubuntu1804.exe进行注册。

    INFO:在Microsoft Store安装的安装路径是在C:\Users\ [用户名]\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc\LocalState\rootfs


3.VS Code操作

  • 安装Remote Development插件,用于远程WSL调试

    INFO:实际上用到的是Remote - WSL插件,安装Remote Development插件会打包安装。

  • 打开远程窗口连接WSL,在WSL上安装Python插件,代码调试需要

  • WSL窗口下使用终端,在WSL上安装软件包,中途会有确认步骤

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    # VS Code远程窗口的bash终端执行。PS:不嫌CMD辣眼睛也可以在CMD下敲命令安装。
    sudo su
    sed -i "s@http://\(security.ubuntu.com\|archive.ubuntu.com\)@http://mirrors.aliyun.com@g" /etc/apt/sources.list && \
    apt update && \
    apt install python3-pip && \
    mkdir -p ~/.pip/ && \
    echo "[global]" > ~/.pip/pip.conf && \
    echo "index-url = https://pypi.tuna.tsinghua.edu.cn/simple" >> ~/.pip/pip.conf && \
    echo "[install]" >> ~/.pip/pip.conf && \
    echo "trusted-host = https://pypi.tuna.tsinghua.edu.cn" >> ~/.pip/pip.conf && \
    pip3 install homeassistant

    INFO:Ctrl+Shift+`打开新的终端。


4.准备代码目录

  • 新建一个文件夹d:\workspace,作为VS Code主目录,内容如下:

    • 放入homeassistant目录,github下载指定版本HA取相应的文件夹即可。
    • 新建config目录,作为HA配置目录。
    • 新建debug.py,用于启动HA,内容如下:

      1
      2
      3
      4
      5
      from homeassistant import __main__ as hass_entry
      import sys

      if __name__ == "__main__":
      sys.exit(hass_entry.main())
    • 用CMD命令新建.vscode目录

      1
      2
      3
      rem 命令行下新建.vscode文件夹,直接右键新建会报错
      cd d:\workspace
      mkdir .vscode
    • .vscode目录下新建launch.json文件

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      //launch.json内容
      {
      // 使用 IntelliSense 了解相关属性。
      // 悬停以查看现有属性的描述。
      // 欲了解更多信息,请访问: https://go.microsoft.com/fwlink/?linkid=830387
      "version": "0.2.0",
      "configurations": [
      {
      "name": "Home Assistant Debug",
      "type": "python",
      "request": "launch",
      "program": "${workspaceRoot}/debug.py", //运行HA
      "console": "integratedTerminal",
      "args": ["-c", "config"], //指定配置文件
      }
      ]
      }

    INFO:该步骤也可以打开文件夹后,在VS Code调试页添加配置,添加完配置后会生成对应文件。

  • 最终目录结构如图

5.开始调试

  • 加载主目录,有两种方法:

    • 先打开文件夹,再点左下角弹出选项选”Reopen Folder in WSL”

    • 点左下角弹出选项选”New Window”,在新建窗口再打开文件夹(WSL中的windows文件夹路径对应为/mnt/[盘符]/[文件夹A]/[文件夹B]

    • 后续可以快速重新打开

  • 设置python解析器,一般会自动识别出来,直接选择即可。

    INFO:WSL环境自带有3.6.8版本,Windows不用安装Python。

  • 按F5即可运行调试。

    WARN:首次运行先不要设断点,待配置目录初始化完成后,再加入配置信息调试。


6.其它

  • 有时候无法正常退出调试,会占用8123端口导致无法访问网页,需要手工终止一下进程。
    1
    2
    3
    sudo su
    ps -aux | grep python3 | grep config
    kill -9 [进程号]

7.小结

  • VS Code的远程调试挺有意思的,一开始看的是容器方式的文档,看得各种懵逼,后来改看WSL方式的发现简单不少,调试果然是一门水深的学问。