外部组件

您可以使用外部组件功能轻松导入社区或个人组件。 可以使用此功能覆盖捆绑的组件。

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

external_components:
  # 使用 GitHub 上 ESPHome dev 分支的 rtttl 和 dfplayer
  - source:
      type: git
      url: https://github.com/esphome/esphome
      ref: dev
    components: [ rtttl, dfplayer ]

  # GitHub 的等效简写
  - source: github://esphome/esphome@dev
    components: [ rtttl ]

  # GitHub 拉取请求的等效简写
  - source: github://pr#2639
    components: [ rtttl ]

  # 使用本地文件夹中的所有组件
  - source:
      type: local
      path: my_components

  # 使用本地 git 仓库中的组件
  - source:
      type: git
      url: file:///Users/user/path_to_repo
      ref: my_awesome_branch
    components: [my_awesome_component]

配置变量

• source: 要检索的组件的位置。请参阅 本地 和 external-components_git。

  • type (Required): 仓库类型。local 或 git 之一。

  git 选项：

  • url (Required, url): Git 仓库 url。请参阅 external-components_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

# 简写
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        <- 不是必需的，但推荐
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:
  # 简写
  source: github://<user or org>/<repository name>[@<branch or tag>]

source 字段还接受来自 ESPHome 仓库的简写 github:// 拉取请求：

external_components:
  # 简写
  source: github://pr#<number>

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

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

刷新

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

您可以通过将此选项设置为 0s 使 ESPHome 每次都检查仓库，但是，由于 ESPHome 在使用仪表板或 vscode 扩展时会持续验证配置，不建议将此值设置为少于几分钟，以避免验证变慢和过多的仓库检查。

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