Shellies Discovery 安装与使用指南

Shellies Discovery 安装与使用指南

ha-shellies-discoveryScript that adds MQTT discovery support for Shellies devices项目地址:https://gitcode.com/gh_mirrors/ha/ha-shellies-discovery

本指南将带你深入了解 Shellies Discovery 开源项目，这是一个旨在为Home Assistant添加Shelly设备（第二代和第三代）MQTT发现支持的脚本。本文档分为三个主要部分：项目目录结构及介绍、启动文件介绍、以及配置文件介绍。

1. 项目目录结构及介绍

Shellies Discovery 的项目结构简洁明了，下面是其主要组成部分：

• .gitignore: Git使用的忽略文件列表，定义了哪些文件或目录不应被版本控制系统跟踪。
• pre-commit-config.yaml: 配置代码风格检查工具，保证提交的代码质量。
• LICENSE: 许可证文件，说明了该项目遵循的Apache-2.0许可协议。
• README.md: 项目的主要说明文档，包含了快速入门指导和重要信息。
• hacs.json: 用于HACS（Home Assistant Community Store）的配置文件，便于在Home Assistant中安装和管理此插件。
• python_scripts目录: 包含Python脚本，主要是实现MQTT发现逻辑的核心代码。
  • shellies_discovery.py: 主要脚本，负责发现并配置Shelly设备。
  • shellies_discovery_gen2.py: 专为第二代Shelly设备设计的脚本，可能包含了针对新特性的适配。
• 其他配置文件如requirements-dev.txt, requirements-test.txt, ruff.toml等: 分别用于开发环境依赖、测试依赖和代码规范检查。

2. 启动文件介绍

虽然这个项目没有一个传统意义上的“启动”脚本，它的运行主要依托于Home Assistant的自动化配置。关键在于创建自动化任务来触发脚本执行，例如通过MQTT消息或Home Assistant启动时。

示例自动化配置:

# 在automations.yaml中的示例
- id: shellies_announce
  alias: 'Shellies Announce'
  trigger:
    - platform: homeassistant
      event: start
    - platform: time_pattern
      hours: "/1"
  action:
    service: mqtt.publish
    data:
      topic: shellies/command
      payload: announce
      
- id: shellies_discovery
  alias: 'Shellies Discovery'
  mode: queued
  max: 999
  trigger:
    platform: mqtt
    topic: shellies_discovery/rpc
  action:
    service: python_script.shellies_discovery
    data_template: # 注意这里使用data_template而非data，以支持模板渲染
      id: '{{ trigger.payload_json.id }}'
      mac: '{{ trigger.payload_json.mac }}'
      ...

这些自动化确保了当条件满足（如系统启动或周期性触发）时，执行MQTT发现命令，进而调用Python脚本来识别并配置Shelly设备。

3. 配置文件介绍

配置主要分布在两个方面：Home Assistant的自动化配置 和 潜在的Python脚本内参数。

自动化配置(yaml)

• automations.yaml: 如上所述，自动化的示例展示了如何设置触发器来启动Shellies Discovery过程。

Python脚本配置

虽然直接的配置不在单独的文件中，而是在调用Python脚本的服务数据中完成，比如通过python_script.shellies_discovery服务调用传递必要参数。对于更复杂的配置需求，可能会涉及到编辑Python脚本本身，或者通过自动化配置中的变量来间接设定。

# 示例数据模板
data:
  id: '{{ trigger.payload_json.id }}'
  mac: '{{ trigger.payload_json.mac }}'
  # 其他可能的配置项根据实际脚本要求添加

请注意，实际部署前务必查看最新版的项目文档和脚本注释，以获取最新的配置指示和任何必要的更新。

ha-shellies-discoveryScript that adds MQTT discovery support for Shellies devices项目地址:https://gitcode.com/gh_mirrors/ha/ha-shellies-discovery