首页 ▸ Integrations ▸

Shelly

将 Shelly 设备集成到 Home Assistant 中。

配置

要将 Shelly 设备添加到您的 Home Assistant 实例中，请使用此 My 按钮：

Shelly 可以被 Home Assistant 自动发现。如果发现了实例，它将显示为 已发现。您可以立即进行设置。

手动配置步骤

如果没有自动发现，请不要担心！您可以设置一个手动集成条目：

浏览到您的 Home Assistant 实例。
转到 设置 > 设备与服务。
在右下角，选择 Add Integration 按钮。
从列表中选择 Shelly。
按照屏幕上的说明完成设置。

Shelly 设备代数

Shelly 设备有四代，所有代数均受此集成支持。不同代数的设备在配置方式以及实体和设备命名上存在一些差异。

Shelly BLU 系列设备（例如 Shelly BLU H&T）不受支持；请使用 BTHome 集成将此类设备配置到 Home Assistant 中。例外情况是 Shelly BLU TRV，它通过 Shelly BLU Gateway Gen3 受此集成支持。

Shelly 设备配置（第一代）

第一代设备使用 CoIoT 协议与集成通信。必须在设备设置中启用 CoIoT。导航到 Shelly 设备的本地 IP 地址，Internet & Security > ADVANCED - DEVELOPER SETTINGS 并勾选 Enable CoIoT 选项。

我们建议使用 unicast 进行通信。为启用此功能，请在 CoIoT peer 字段中输入 Home Assistant 服务器的本地 IP 地址和端口 5683，然后点击 SAVE 按钮。对于电池供电设备（即使通过 USB 连接）这是强制性的。更改 CoIoT peer 后，需要手动重启 Shelly 设备。

如果 Shelly 设备的推送更新未到达 Home Assistant 服务器，Home Assistant 将显示一个修复问题。

以下列表将帮助您诊断和解决问题：

检查您的 Shelly 设备是否正确配置了 CoIoT peer。
如果您在设备的 Web 面板中找不到 CoIoT peer 设置，可能是设备使用了非常旧的固件版本，您应该将其更新到当前版本。
如果 Shelly 设备与 Home Assistant 服务器位于不同的子网中，您应确保这些子网之间的 UDP 端口 5683 通信。
如果 Home Assistant 作为虚拟机或在非 Home Assistant OS 的操作系统上运行的服务，您应在设备的防火墙上打开 UDP 端口 5683，并/或确保从此端口的通信被重定向到 Home Assistant 服务。
推送更新丢失可能与 WiFi 网络范围有关。如果使用具有多个接入点的 WiFi 网络，请启用 Internet & Security >> WiFi Client AP Roaming 选项。考虑将 Shelly 设备移近 WiFi 接入点。考虑添加另一个 WiFi 接入点以改善设备的连接质量。
如果您认为 Shelly 设备工作正常且不想更改网络/配置，可以忽略修复问题。但您必须知道，这样会放弃第一代 Shelly 设备与 Home Assistant 的最佳使用体验。

Shelly 设备配置（第二代及以上）

第二代及以上设备使用 RPC 协议与集成通信。电池供电设备（即使通过 USB 连接）可能需要手动配置出站 WebSocket，如果 Home Assistant 无法正确确定您的实例的内部 URL 或出站 WebSocket 之前已为其他 Home Assistant 实例配置。在这种情况下，请导航到 Shelly 设备的本地 IP 地址，Settings >> Connectivity >> Outbound WebSocket 并勾选 Enable Outbound WebSocket，在服务器下输入以下地址：

ws:// + Home_Assistant_local_ip_address:Port + /api/shelly/ws（例如：ws://192.168.1.100:8123/api/shelly/ws），点击 Apply 保存设置。如果您的安装设置为使用 SSL 加密（HTTPS 带证书），则需要在 WebSocket 协议中额外添加一个 s，使其变为 wss://（例如：wss://192.168.1.100:8123/api/shelly/ws）。

Note

集成直接与设备通信；不需要云连接。

蓝牙支持

非电池供电的 Shelly 第二代及以上设备可以作为蓝牙代理，用于广告监听。可以在选项流程中启用主动或被动监听。

选项

Shelly 的选项可以通过用户界面设置，具体步骤如下：

浏览到您的 Home Assistant 实例。
转到 设置 > 设备与服务。
如果配置了多个 Shelly 实例，请选择您想配置的实例。
选择集成，然后选择配置。

范围扩展器支持

非电池供电的 Shelly 第二代及以上设备可以作为范围扩展器。同代设备可以通过这些范围扩展器配置，在配置流程中指定自定义 TCP 端口。目前，仅支持静态 IP 或 DHCP 保留 IP 用于主设备。

实体命名（第一代）

如果设备只有一个继电器或没有继电器，集成将使用 Device Name 为其实体命名。

如果设备有多个继电器，集成将使用以下策略为其实体命名：

如果设备中设置了 Device Name 或 Channel Name，集成将使用它们生成实体名称。
如果设置了通道名称，将在实体名称中使用它们。设备名称将不会被使用。
如果仅设置了设备名称，并且设备有多个通道，则通道编号将附加到实体名称后（例如：Channel 2）。
如果未设置设备名称和通道名称，实体名称将由 Device Type、Device ID 和 Channel Number 生成。

示例：

设备名称	通道名称	实体名称
`未设置`	`未设置`	shellyswitch25-ABC123 Channel 1
`未设置`	儿童房灯泡	儿童房灯泡
厨房	`未设置`	厨房 Channel 1
卧室	圆形灯泡	圆形灯泡

名称可以从设备网页中设置：

设备名称可以在 Settings >> DEVICE NAME 中设置
单通道设备的通道名称可以在 Settings >> CHANNEL NAME 中设置
多通道设备的通道名称可以在 Settings >> CHANNEL NAME 中设置，选择通道后，通过点击通道名称进行设置。

实体命名（第二代及以上）

集成使用以下策略为其实体命名：

如果设备中设置了 Channel Name，集成将使用它生成实体名称，例如 Kitchen Light
如果 Channel Name 设置为默认值，集成将使用 Device ID 和默认通道名称生成实体名称，例如 ShellyPro4PM-9808D1D8B912 Switch 0。

遮阳实体

Shelly 2PM Gen3 支持 tilt 用于 cover 实体。要启用此功能，需要配置设备：

将设备配置文件更改为 Cover（Settings > Device profile）
校准遮阳（Home > Cover > Calibration > Start）
启用并配置 Slat control（Home > Cover > Slat control）

二进制输入传感器

二进制输入传感器（第一代）

根据设备按钮类型的配置，集成将创建与这些输入相对应的二进制传感器。当按钮类型为 momentary 或 momentary_on_release 时，不会创建二进制传感器，对于这些类型，您需要使用事件进行自动化。

二进制输入传感器（第二代及以上）

对于第二代及以上硬件，可以选择设备的输入是连接到按钮还是开关。仅当输入模式设置为 switch 时，才会创建二进制传感器。当输入类型为 button 时，您需要使用事件进行自动化。

事件实体（第一代）

如果连接到设备的开关的 BUTTON TYPE 设置为 momentary 或 detached switch，集成将为此开关创建一个事件实体。您可以在自动化中使用此实体。

事件实体（第二代及以上）

如果连接到设备的开关的 Input Mode 设置为 Button，集成将为此开关创建一个事件实体。您可以在自动化中使用此实体。

每个使用 Shelly.emitEvent() 生成事件的脚本也会获得一个相应的事件实体。此实体默认禁用。更改脚本后，需要手动重新加载设备才能显示新的事件类型。

例如，以下脚本将在设备上的输入（按钮或开关）每次更改时发出一个事件。

// 示例 shelly 脚本
function eventHandler(event, userdata) {
  if (
    typeof event.component === "string" &&
    event.component.substring(0, 5) === "input"
  ) {
    let id = Number(event.component.substring(6));
    Shelly.emitEvent("input_event", { id: id });
  }
}
Shelly.addEventHandler(eventHandler);

事件

如果连接到设备的开关的 BUTTON TYPE 设置为 momentary 或 detached switch，集成在使用开关时会触发类型为 shelly.click 的事件。您可以在自动化中使用这些事件。

此外，一些设备不会为按钮/开关添加实体。例如，Shelly Button1 只有一个用于电池电量的实体。它没有用于按钮本身的实体。要基于按钮按下触发自动化，请使用 shelly.click 事件。

监听事件

您可以在开发者工具/事件中订阅 shelly.click 事件类型，以检查事件数据 JSON 以获取正确的参数用于自动化。例如，当您按下 Shelly Button1 时，shelly.click 返回类似以下的事件数据 JSON。

Event 0 fired 9:53 AM:
{
    "event_type": "shelly.click",
    "data": {
        "device_id": "e09c64a22553484d804353ef97f6fcd6",
        "device": "shellybutton1-A4C12A45174",
        "channel": 1,
        "click_type": "single",
        "generation": 1
    },
    "origin": "LOCAL",
    "time_fired": "2021-04-28T08:53:12.755729+00:00",
    "context": {
        "id": "e0f379706563aaa0c2c1fda5174b5a0e",
        "parent_id": null,
        "user_id": null
    }
}

generation 值表示事件源设备的代数。

自动化

创建自动化的最简单方法是使用 Home Assistant 自动化编辑器。例如，要设置由特定 Shelly Button1 的双击触发的自动化：

在自动化的触发器部分，将触发器类型设置为 Device。
在设备下拉菜单中，找到 Shelly Button1。
在触发器下拉菜单中，选择 Button double clicked。
设置任何条件和操作以完成您的自动化。

您还可以使用 YAML 创建自动化，例如：

- alias: "切换客厅灯"
  triggers:
    - trigger: event
      event_type: shelly.click
      event_data:
        device: shellyswitch25-AABBCC
        channel: 1
        click_type: single
  actions:
    - action: light.toggle
      target:
        entity_id: light.living_room

- alias: "切换客厅灯"
  triggers:
    - trigger: event
      event_type: shelly.click
      event_data:
        device: shellyswitch25-AABBCC
        channel: 2
        click_type: long
  actions:
    - action: light.toggle
      target:
        entity_id: light.lamp_living_room

click_type 的可能值

Shelly 输入事件	点击类型
`S`	`single`
`SS`	`double`
`SSS`	`triple`
`L`	`long`
`SL`	`single_long`
`LS`	`long_single`

第二代和第三代设备使用 btn_down、btn_up、single_push、double_push、triple_push 和 long_push 作为 click_type。

Note

并非所有设备都支持所有输入事件。您可以在 Shelly API 参考网站上查看您的设备支持哪些类型的 Shelly 输入事件。

电器类型（第一代）

Shelly 设备继电器默认作为 switch 实体添加到 Home Assistant 中。如果在设备的 WebUI 中将 Settings >> APPLIANCE TYPE 值设置为 light，则继电器可以作为 light 实体添加。

消耗类型（第二代及以上）

Shelly 设备继电器默认作为 switch 实体添加到 Home Assistant 中。如果在设备的 WebUI 中将 EXTERNAL CONSUMPTION TYPE 值设置为 light，则继电器可以作为 light 实体添加。

灯光过渡

支持灯光过渡的 Shelly 灯：

Shelly Bulb RGBW
Shelly DUO
Shelly Dimmer
Shelly Dimmer 2
Shelly RGBW2
Shelly Vintage

Note

固件将过渡时间限制为 5 秒。

设备操作

集成提供可以通过配置按钮触发的设备操作。

OTA 固件更新

触发设备 OTA 固件更新。

更新实体

固件更新
- 触发 OTA 固件更新过程到最新稳定版本
Beta 固件更新（默认禁用）
- 触发 OTA 固件更新过程到最新 Beta 版本

重启

触发设备重启。

按钮

重启
- 触发重启

Shelly 恒温阀（TRV）

Shelly TRV 生成 2 个实体，可用于控制设备行为：climate 和 number。第一个允许指定温度，第二个则允许指定阀门位置的百分比。

注意：如果您更改阀门位置，则自动温度控制将被禁用。一旦您更改温度，它将再次启用。

Shelly Gas with Valve add-on

如果您将 Valve add-on 连接到 Shelly Gas，集成将为阀门创建两个实体。valve 实体允许您控制阀门，sensor 实体显示阀门的确切状态。

CoAP 端口（第一代）

在某些情况下，可能需要自定义 Home Assistant 实例监听的 CoAP UDP 端口（默认：5683）。

要更改它，请在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 中添加以下键：

# 示例 configuration.yaml 条目
shelly:
  coap_port: 12345

虚拟组件

Shelly 第二代设备（固件 1.4.0 或更高版本的 Pro 型号）和第三代设备（固件 1.2.0 或更高版本）允许创建虚拟组件。虚拟组件是一组特殊的组件，最初不存在于设备上，由用户动态创建以与 Shelly 脚本交互。您可以在设备的 Web 面板的 Components 部分中添加虚拟组件到设备配置中。

集成支持以下虚拟组件：

boolean 在 toggle 模式下，为其创建 switch 平台实体
boolean 在 label 模式下，为其创建 binary_sensor 平台实体
enum 在 dropdown 模式下，为其创建 select 平台实体
enum 在 label 模式下，为其创建 sensor 平台实体
number 在 field 模式下，为其创建 number 平台实体（box 模式）
number 在 slider 模式下，为其创建 number 平台实体（slider 模式）
number 在 label 模式下，为其创建 sensor 平台实体
text 在 field 模式下，为其创建 text 平台实体
text 在 label 模式下，为其创建 sensor 平台实体

脚本（第二代及以上）

对于每个设备脚本，集成会创建一个 switch 实体，允许您控制脚本。这些实体默认禁用。

其他信息

Shelly 设备依赖 SNTP 进行功能如功率测量。请从设备 Web UI 检查配置的服务器是否可达。

已知问题和限制

仅支持第一代设备的固件 1.9 及更高版本
仅支持第二代设备的固件 1.0 及更高版本
以下第一代设备仅支持固件 1.11 及更高版本（由于不兼容的 API）：
- Shelly DUO
- Shelly Bulb RGBW
- Shelly Dimmer
- Shelly Dimmer 2
- Shelly RGBW2
- Shelly Vintage
第一代 “Shelly 4Pro” 和 “Shelly Sense” 不受支持（基于旧 CoAP v1 协议的设备）
设置前，必须通过按下设备上的按钮唤醒电池供电设备。
对于电池供电设备，update 平台实体仅通知固件更新的可用性，但无法触发更新过程。
使用 homeassistant.update_entity 操作更新属于电池供电设备的实体是不可能的，因为这些设备大部分时间都在睡眠（离线）。

帮助我们改进翻译

建议编辑此页面，或提供/查看此页面的反馈。

编辑提供反馈查看待处理的反馈