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 }}'
# 其他可能的配置项根据实际脚本要求添加
请注意,实际部署前务必查看最新版的项目文档和脚本注释,以获取最新的配置指示和任何必要的更新。