Birdbuddy Homeassistant — Birdbuddy 家庭助手（Homeassistant）

Bird Buddy ↔ Home Assistant Skill 本技能将指导您完成 Bird Buddy 与 Home Assistant 的完整生产级集成：自定义组件、实时摄像头实体、Telegram 通知和专用仪表盘。 变量引用 将这些占位符替换为配置片段和参考文件中的 {{VAR}}。 变量 描述 示例 {{HA_CONFIG_DIR}} HA 配置目录 /home/mike/homeassistant (Docker) 或 /config (HA OS) {{FEEDER_ID}} Bird Buddy 鸟食器 UUID (从 HA 实体属性中获取) xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx {{TELEGRAM_BOT_TOKEN}} Telegram Bot API 令牌 123456789:AAF... {{TELEGRAM_CHAT_ID}} Telegram 聊天/群组 ID (整数，群组为负数) -1001234567890 {{TELEGRAM_THREAD_ID}} Telegram 消息线程/主题 ID 42 {{HA_URL}} Home Assistant 基础 URL http://homeassistant.local:8123 {{HA_TOKEN}} 长期 HA 访问令牌，在 HA Profile → Security 中创建 步骤 1 — 安装 ha-birdbuddy 自定义组件 选项 A：HACS (推荐) 打开 HACS → Integrations → ⋮ 菜单 → Custom repositories 添加 https://github.com/jhansche/ha-birdbuddy 作为集成 搜索 "Bird Buddy" → 下载 (测试版本 0.0.21) 重启 Home Assistant 选项 B：手动 mkdir -p {{HA_CONFIG_DIR}}/custom_components/birdbuddy # 从 https://github.com/jhansche/ha-birdbuddy 克隆或下载发行版 tarball cp -r ha-birdbuddy/custom_components/birdbuddy/* {{HA_CONFIG_DIR}}/custom_components/birdbuddy/ 安装后，前往 Settings → Devices & Services → Add Integration 并搜索 "Bird Buddy"。 输入您的 Bird Buddy 账户凭据。 账户说明：如果使用成员账户（不是饲料器所有者），则所有者必须在 Bird Buddy 应用程序中将您添加为成员，并显式授予明信片和直播访问权限。 步骤 2 — 将摄像头平台添加到组件 v0.0.21 组件默认不包括摄像头平台。 您必须： 复制 references/camera.py 到 {{HA_CONFIG_DIR}}/custom_components/birdbuddy/camera.py 编辑 {{HA_CONFIG_DIR}}/custom_components/birdbuddy/__init__.py 并将 Platform.CAMERA 添加到 PLATFORMS 列表中： from homeassistant.const import Platform PLATFORMS = [ Platform.BINARY_SENSOR, Platform.SENSOR, Platform.CAMERA, # ← 添加此行 ] 重启 Home Assistant。 将出现一个新实体 camera.bird_buddy_camera。 步骤 3 — 配置 rest_command Bird Buddy 自动化通过 rest_command 发送 Telegram 消息。 3a. 将 include 添加到 configuration.yaml # Docker：configuration.yaml 可能是 root 所有 — 使用移动技巧 cd {{HA_CONFIG_DIR}} mv configuration.yaml configuration.yaml.bak cp configuration.yaml.bak configuration.yaml # 现在以您的用户身份编辑 将以下内容添加到 configuration.yaml： rest_command: !include rest_commands.yaml 3b. 创建 rest_commands.yaml 复制 references/rest_commands.yaml 到 {{HA_CONFIG_DIR}}/rest_commands.yaml 并替换您的 Telegram 值。 最终文件应如下所示： birdbuddy_telegram_notify: url: "https://api.telegram.org/bot{{TELEGRAM_BOT_TOKEN}}/sendMessage" method: POST content_type: "application/json" payload: >- { "chat_id": {{TELEGRAM_CHAT_ID}}, "message_thread_id": {{TELEGRAM_THREAD_ID}}, "text": "{{ message }}", "parse_mode": "Markdown" } chat_id 必须是裸整数，而不是带引号的字符串。"-1001234567890" 将被 Telegram API 拒绝；使用 -1001234567890。 编辑 configuration.yaml 后重启 HA。 步骤 4 — 创建 input_boolean 通知切换 通过 Settings → Helpers → Create Helper → Toggle 或通过 HA WebSocket API 创建以下五个帮助器： 实体 ID 名称 input_boolean.bird_buddy_new_bird_detected Bird Buddy - 新鸟检测 input_boolean.bird_buddy_rare_species_alert Bird Buddy - 稀有物种警报 input_boolean.bird_buddy_low_battery_alert Bird Buddy - 低电量警报 input_boolean.bird_buddy_offline_alert Bird Buddy - 离线警报 input_boolean.bird_buddy_daily_summary Bird Buddy - 每日摘要 启用您要激活的切换。 步骤 5 — 导入自动化 将 references/automations.yaml 内容复制到您的 {{HA_CONFIG_DIR}}/automations.yaml。 如果 automations.yaml 不存在，则创建它（从空列表 [] 开始）。 HA 自动包含它，如果您在 configuration.yaml 中有 automation: !include automations.yaml（对于新安装这是默认值）。 六个自动化涵盖： ID 触发器 条件 birdbuddy_new_bird_detected birdbuddy_new_postcard_sighting 事件 切换已启用 birdbuddy_rare_species_alert 同一事件 + hasNewSpecies == true 切换已启用 birdbuddy_low_battery_alert 电池传感器 < 20% 切换已启用 birdbuddy_feeder_offline 饲料器状态 → 离线 切换已启用 birdbuddy_feeder_online 饲料器状态从离线切换已启用 birdbuddy_daily_summary 时间触发器 00:00 UTC（美国东部时间 20:00）切换已启用 每个自动化都调用 rest_command.birdbuddy_telegram_notify。 您必须在每个操作的 data: 块中提供令牌、chat_id 和 thread_id — 或通过 input_text 帮助器/ secrets.yaml 注入它们。