外部组件

你可以使用外部组件功能轻松导入社区或个人组件。也可以使用此功能覆盖内置组件。

如果你想为 ESPHome 创建自己的组件/平台，请参阅我们的开发者网站。

external_components:
  # use rtttl and dfplayer from ESPHome's dev branch in GitHub
  - source:
      type: git
      url: https://github.com/esphome/esphome
      ref: dev
    components: [ rtttl, dfplayer ]

  # equivalent shorthand for GitHub
  - source: github://esphome/esphome@dev
    components: [ rtttl ]

  # equivalent shorthand for GitHub pull request
  - source: github://pr#2639
    components: [ rtttl ]

  # use all components from a local folder
  - source:
      type: local
      path: my_components

  # use a component from a local git repository
  - source:
      type: git
      url: file:///Users/user/path_to_repo
      ref: my_awesome_branch
    components: [my_awesome_component]

配置变量

source: 你想要获取的组件所在的位置。参见本地和外部组件_git。
- type (Required): 仓库类型。可为 local、git 之一。
git 选项：
- url (Required, url): Git 仓库 url。参见外部组件_git。
- ref (Optional, string): Git 引用（分支或标签）。如果未指定，则使用默认分支。
- username (Optional, string): Git 服务器的用户名（如果需要）
- password (Optional, string): Git 服务器的密码（如果需要）
- path (Optional, string): 仓库内的路径（如果不同于 components 或 esphome/components）
local 选项：
- path (Required): 使用本地组件时使用的路径。参见本地。
components (Optional, list): 要从外部源使用的组件列表。默认情况下，会使用所有可用的组件。
refresh (Optional, Time): 检查源的间隔。对 local 没有效果。更多信息参见刷新。默认为 1day。

本地

你可以指定包含外部组件的本地路径。这在开发组件或你想手动控制文件来源时最有用。

external_components:
  - source:
      path: /copied_components

# shorthand
external_components:
  - source: my_components

请注意，支持相对路径，因此你可以输入 my_components 作为源路径，然后 ESPHome 将从你的 YAML 配置文件所在文件夹中的 my_components 文件夹加载组件。

本地组件示例

以上面的 my_components 示例为例，文件夹结构必须如下所示：

<CONFIG_DIR>
├── node1.yaml
├── node2.yaml
└── my_components
    ├── my_component1
    │   ├── __init__.py
    │   ├── component1.cpp
    │   ├── component1.h
    │   └── sensor.py
    └── my_component2
        ├── __init__.py
        ├── component2.cpp
        ├── component2.h
        └── switch.py

Git

从 git 获取组件是使用 ESPHome 默认不包含的组件的最简单方式。源组件应位于 components 文件夹内或 esphome/components 文件夹内。后者使得从 ESPHome 仓库的分支共享组件变得更加容易。

仓库的 url 可以是远程的（http: 或 https: 协议）或本地的（file: 协议，需使用绝对路径）。

Git 仓库示例

对于共享一个或少数几个组件的仓库：

components
├── my_component1
│   ├── __init__.py
│   ├── component1.cpp
│   ├── component1.h
│   └── sensor.py
└── my_component2
    ├── __init__.py
    ├── component2.cpp
    ├── component2.h
    └── switch.py
example_component1.yaml        <- not required but recommended
README.md

或者，也支持以下结构，这使得从 ESPHome 仓库的分支共享组件变得很方便：

esphome
├── components
│   ├── my_component1
│   │   ├── __init__.py
│   │   ├── component1.cpp
│   │   ├── component1.h
│   │   └── sensor.py
│   ├── my_component2
│   │   ├── __init__.py
│   │   ├── component2.cpp
│   │   ├── component2.h
│   │   └── switch.py
│  ...
...

HTTP git 仓库通常通过以下配置支持：

external_components:
  source:
    type: git
    url: http://repository_url/
    ref: branch_or_tag
  source:
    type: git
    url: file:///Users/user/path_to_repo
    ref: branch_or_tag

source 字段接受 github:// 资源的简短写法：

external_components:
  # shorthand
  source: github://<user or org>/<repository name>[@<branch or tag>]

source 字段也接受来自 ESPHome 仓库的 github:// pull request 的简短写法：

external_components:
  # shorthand
  source: github://pr#<number>

在底层，验证期间，ESPHome 会将 git 仓库克隆到隐藏的 .esphome 文件夹中，然后组件将从该本地副本加载。克隆仓库的本地路径根据仓库名称和引用名称而不同，因此具有不同引用的仓库被视为不同的仓库，并会被独立更新。

如果需要，你可以提供在远程 git 服务器进行身份验证时使用的用户名和密码，使用 username 和 password 字段。这在结合 !secret 功能从 secrets.yaml 文件加载值时最有用。这不是全面的安全措施；你的用户名和密码必然会以明文形式存储在 .esphome 目录中。

刷新

组件最初被克隆到缓存目录中，然后在距离上次检查超过 refresh: 时间后，仓库会被检查更新（通过 git pull）。

你可以通过将此选项设置为 0s 让 ESPHome 每次都检查仓库，不过由于使用 dashboard 或 vscode 扩展时 ESPHome 会持续验证配置，因此不建议将此值设置为低于几分钟，以免验证变慢并造成过多的仓库检查。

同样，你可以将此设置设置为 never，ESPHome 将永远不会更新仓库，例如当 ref 指向标签（tag）时很有用。