船舶每日检查 — Victron VRM API 监控工具

通过自动化每日报告监控您的 Victron 电源系统。从 Victron VRM API 获取实时电池荷电状态（SOC）、电压、电流、太阳能发电量及当前告警，并生成格式精美、内容完整的 HTML 邮件，汇总您所有安装点的运行状态。

概览

本技能具备以下能力：

• 📊 从 Victron VRM API 拉取实时电源系统指标
• 📧 生成专业级 HTML 邮件报告
• ⚓ 支持多个安装点（船舶、房车、住宅等）
• 🎨 美观且响应式设计的邮件模板
• 🔄 与 OpenClaw cron 任务无缝集成
• 📱 移动端友好的 HTML 输出

您将获得什么

每天清晨，您将收到一封简洁清晰的 HTML 邮件，内容包括：

• 电池状态：SOC 百分比、电压、电流、温度
• 太阳能数据：当前功率、今日发电量、最大充电功率、光伏板电压
• 逆变器/交流电信息：输入电压、运行状态（市电/岸电接入情况）
• 当前告警：系统实时触发的告警信息
• 硬件状态：网关固件版本、最后通信时间
• 仪表盘链接：直达 VRM 仪表盘的快捷链接，便于快速访问

配置说明

1. 获取 Victron VRM API Token

1. 访问 https://vrm.victronenergy.com/access-tokens
2. 创建一个新的访问令牌（access token）
3. 复制该令牌（后续配置中需要使用）

2. 查找您的安装点 ID

每个 Victron 系统在 VRM 网页 URL 中均显示其安装点 ID：

https://vrm.victronenergy.com/installation/000000/dashboard
                                         ^^^^^^
                                    安装点 ID

3. 确认 SmartShunt 实例编号

本技能通过 SmartShunt（电池监测器）获取电池数据，请确认其实例编号（instance number）：

• 可在 VRM 的诊断页面或告警接口中查看
• 默认实例编号通常为 279（如实际不同，请相应调整）

4. 配置您的安装点信息

编辑 Python 脚本并填入您的具体参数：

vim /home/jeanclaude/.openclaw/workspace/skills/boat-daily-check/scripts/boat-email-report.py

更新以下变量：

VRM_TOKEN = "your-token-here"

INSTALLATIONS = {
    "boat1": {
        "id": 000000,           # 您的安装点 ID
        "name": "Titanic",  # 显示名称
        "batteryInstance": 279,  # SmartShunt 实例编号
    },
    "boat2": {
        "id": 000001,
        "name": "Endeavour",
        "batteryInstance": 279,
    }
}

使用方法

立即生成一份报告

python3 /home/jeanclaude/.openclaw/workspace/skills/boat-daily-check/scripts/boat-email-report.py

执行后将生成以下文件：

• HTML 邮件：out/boat-daily-email.html
• JSON 数据：out/boat-status.json
• CSV 导出：out/boat-status.csv

与 OpenClaw Cron 集成

可将其加入您的晨间邮件报告（或作为独立任务运行）：

openclaw cron add -j '{
  "name": "boat-daily-check",
  "schedule": {"kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles"},
  "payload": {
    "kind": "agentTurn",
    "message": "Run boat power system check: python3 /path/to/boat-email-report.py"
  },
  "delivery": {"mode": "announce"},
  "sessionTarget": "isolated"
}'

也可嵌入现有任务中，例如将船舶状态与钓鱼预报、天气报告一并发送。

API 参考文档

本技能调用 Victron VRM API v2 接口：

接口：电池摘要（Battery Summary）

GET /v2/installations/{id}/widgets/BatterySummary/latest?instance={instance}

返回内容：SOC 百分比、电压、电流、温度、剩余续航时间、告警状态等。

接口：诊断信息（Diagnostics）

GET /v2/installations/{id}/diagnostics

返回内容：全部设备元数据，包括太阳能充电器功率、逆变器状态等。

接口：告警列表（Alarms）

GET /v2/installations/{id}/alarms?limit=10

返回内容：最多 10 条当前激活的告警及其详细信息和关联设备。

认证方式：所有请求均使用 X-Authorization: Token {your-token} 头部进行身份验证。

速率限制：VRM API 设有合理限流（约 10 次请求/秒），本脚本已严格遵循该限制。

文件结构

boat-daily-check/
├── SKILL.md （本文档）
├── scripts/
│   └── boat-email-report.py       # 主程序：数据采集 + HTML 生成
├── references/
│   ├── victron_attributes.md      # Victron 属性代码对照表
│   └── vrm_api_guide.md           # VRM API 快速参考指南
├── out/
│   ├── boat-daily-email.html      # 生成的邮件（最近一次运行结果）
│   ├── boat-status.json           # JSON 格式数据导出
│   └── boat-status.csv            # CSV 格式导出
└── templates/ （可选）
    └── boat-email-template.html   # 邮件模板（支持自定义）

自定义选项

修改收件人邮箱

编辑 boat-email-report.py 文件，修改邮件发送逻辑：

# 修改收件人邮箱地址
recipients = ["your-email@example.com"]

自定义 HTML 模板

邮件模板采用 Handlebars 风格占位符。可直接编辑 Python 脚本中的 HTML 字符串段落：

html = html.replace("{{pitterPatter.battery.soc}}", f"{value}%")

也可新建自定义模板文件，并修改脚本以加载该文件。

添加更多安装点

向 INSTALLATIONS 字典中新增条目：

"boat3": {
    "id": 999999,
    "name": "My Third Boat",
    "batteryInstance": 279,
}

随后更新报告生成逻辑，确保包含新安装点的数据。

调整指标采集项

可根据 Victron 小部件响应结果选取其他指标。修改电池数据提取函数：

def fetch_battery_data(installation_id, instance):
    # 返回字段：soc, voltage, current, temp
    # 可扩展添加：time_to_go, mid_voltage 等字段

故障排查

“子组件 ‘BatterySummary’ 未找到”

• 请确认安装点 ID 正确无误
• 请核实 SmartShunt 实例编号是否准确

缺失太阳能/逆变器数据

• 手动运行 python3 boat-email-report.py 进行调试
• 检查 JSON 输出中是否存在对应字段缺失
• 确认相关设备在 VRM 平台中处于在线状态

邮件未成功发送

• 请确保 OpenClaw cron 任务已启用
• 检查投递模式设置："delivery": {"mode": "announce"}
• 确认收件人邮箱地址填写正确

邮件中数据显示为空

• 请检查 VRM API Token 是否有效
• 确认安装点 ID 填写无误
• 再次核对 SmartShunt 实例编号

性能表现

• 数据拉取耗时：约 5–10 秒（每个安装点发起 3 次 API 请求）
• HTML 生成耗时：约 1 秒
• 邮件投递：由 OpenClaw 异步处理
• 整体执行耗时：2 个安装点下小于 30 秒

运行依赖

• Python 3.7 或更高版本
• requests 库（可通过 pip install requests 安装）
• 具备只读权限的 Victron VRM API Token
• OpenClaw cron 任务支持（用于定时调度）

已知限制

• VRM API 存在约 10 次请求/秒的速率限制
• 仅提供最新值，不支持历史数据查询
• 部分小部件类型暂未支持（可通过自定义实现扩展）
• 邮件投递功能依赖 OpenClaw 的邮件基础设施

下一步操作

1. ✅ 获取您的 VRM API Token
2. ✅ 查找各安装点 ID 和电池监测器实例编号
3. ✅ 使用您的信息更新 Python 脚本
4. ✅ 执行测试命令：python3 boat-email-report.py
5. ✅ 配置 cron 任务实现每日自动报告

技术支持与贡献

• VRM API 文档：https://vrm-api-docs.victronenergy.com/
• Victron 社区论坛：https://community.victronenergy.com/
• GitHub 仓库（参考实现）：https://github.com/dirkjanfaber/victron-vrm-api

许可证

本技能为开源项目，欢迎自由 Fork、修改与分享！