Shelly BluTRV Manager
Local-first control of Shelly BluTRV thermostats via RPC with automatic cloud fallback.
Repository
GitHub: INLINECODE0
Setup
Bei Erstnutzung zuerst references/setup.md lesen und Gateway-Zuordnung, Cloud-Fallback und Schreibgrenzen festlegen, bevor Befehle ausgeführt werden.
Access
Siehe references/auth-and-access.md für Credential-Handling, lokale vs. Cloud-Nutzung und Sicherheitsgrenzen.
Quick Reference
BluTRV Thermostate
| Raum | Gateway | TRV # | Device ID |
|---|
| Schlafzimmer | INLINECODE3 | 200 | INLINECODE4 |
| Wohnzimmer |
192.168.0.102 | 201 |
bad0ff1ce123 |
| Flur |
192.168.0.102 | 202 |
f00dbabecafe |
H&T Sensoren (WiFi, nur Cloud)
| Raum | Device ID | Typ |
|---|
| Schlafzimmer | INLINECODE9 | H&T (Temp + Feuchtigkeit) |
H&T Sensoren liefern: Temperatur, relative Feuchtigkeit, Batterie, RSSI
Status abfragen
BluTRV Thermostate
CODEBLOCK0
H&T Sensoren (nur Cloud)
CODEBLOCK1
H&T Output-Fields: temperature_C, humidity_percent, battery_percent, INLINECODE13
Alle Geräte auf einmal
CODEBLOCK2
Temperatur setzen
CODEBLOCK3
Wichtig: BluTRVs sind Bluetooth-Battery-Geräte — Befehle brauchen ein paar Sekunden.
Cloud API
CODEBLOCK4
Limitation: Cloud-API kann KEINE BluTRV-Status lesen — nur WiFi-Geräte (H&T, Shelly Plug, etc.). Für TRVs immer lokale Gateways nutzen.
Device-Registry
Siehe references/devices.md für vollständige Geräteliste und Gateway-Zuordnung.
Ziel-Aliase
Die Helper-Scripts akzeptieren neben gateway_ip und trv_id auch frei definierbare Ziel-Aliase aus SHELLY_TARGETS.
Ein Ziel wird intern eindeutig über gateway_key + trv_id + trv_device_id beschrieben, damit mehrere BluTrv (200) an unterschiedlichen Gateways nicht verwechselt werden.
Best Practices
- 1. Immer Helper-Scripts nutzen — nicht nacktes
curl ohne Timeout - Lokales RPC bevorzugen — Cloud hat striktes Rate-Limit
- Write verifizieren —
blutrv-control.sh prüft nach dem Setzen das resultierende INLINECODE22 - Timeout-Handling —
blutrv-status.sh hat bereits integriertes Timeout + Fallback - Fehler offen kommunizieren — Bei Timeout/Hänger: "Laufzeitprüfung fehlgeschlagen" sagen, nicht still hängen
Scope
Das veröffentlichte Paket ist bewusst auf lokale RPC-Steuerung, verifizierte Writes und Cloud-Fallback begrenzt.
Experimentelle WebSocket-Schreib- oder Debug-Helfer sind nicht Teil dieses ClawHub-Releases.
Troubleshooting
Siehe references/troubleshooting.md für typische Fehlerbilder und Recovery-Schritte.
Shelly BluTRV管理器
通过RPC对Shelly BluTRV恒温器进行本地优先控制，并自动云回退。
仓库
GitHub：https://github.com/wolf128058/openclaw-skill-shelly-blutrv-manager
设置
首次使用前，请先阅读references/setup.md，配置网关映射、云回退和写入限制，然后再执行命令。
访问
请参阅references/auth-and-access.md了解凭据处理、本地与云使用以及安全限制。
快速参考
BluTRV恒温器
| 房间 | 网关 | TRV编号 | 设备ID |
|---|
| 卧室 | 192.168.0.101 | 200 | cafebabefeed |
| 客厅 |
192.168.0.102 | 201 | bad0ff1ce123 |
| 走廊 | 192.168.0.102 | 202 | f00dbabecafe |
H&T传感器（WiFi，仅云）
| 房间 | 设备ID | 类型 |
|---|
| 卧室 | bad0ff1ce321 | H&T（温度+湿度） |
H&T传感器提供： 温度、相对湿度、电池电量、信号强度
查询状态
BluTRV恒温器
bash
通过别名
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/blutrv-status.sh 卧室
通过IP+TRV编号
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/blutrv-status.sh 192.168.0.101 200
输出字段：roomtemperatureC, currentC, targetC, battery_percent, source, rssi
H&T传感器（仅云）
bash
查询包含温度和湿度的状态
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/ht-status.sh 卧室
或通过设备ID
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/ht-status.sh decafbadf00d
原始JSON
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/shelly-cloud.sh status decafbadf00d
H&T输出字段： temperatureC, humiditypercent, battery_percent, rssi
一次性查询所有设备
bash
获取所有设备状态
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/shelly-cloud.sh list | jq .data.devices_status
设置温度
bash
通过辅助脚本（推荐）
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/blutrv-control.sh <网关IP>
<温度>
示例：卧室设置为20°C
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/blutrv-control.sh 192.168.0.101 200 20
通过别名
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/blutrv-control.sh 卧室 20
直接通过RPC（用于调试）
curl -s -X POST http://192.168.0.101/rpc \
-H Content-Type: application/json \
-d {method:BluTrv.Call,params:{id:200,method:TRV.SetTarget,params:{id:0,target_C:20}}}
重要提示： BluTRV是蓝牙电池设备——命令执行需要几秒钟。
云API
bash
列出设备
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/shelly-cloud.sh list
设备状态
~/.openclaw/workspace/skills/shelly-blutrv-manager/scripts/shelly-cloud.sh status <设备ID>
限制： 云API无法读取BluTRV状态——仅支持WiFi设备（H&T、Shelly Plug等）。对于TRV，请始终使用本地网关。
设备注册表
请参阅references/devices.md获取完整设备列表和网关映射。
目标别名
辅助脚本除了接受gatewayip和trvid外，还接受来自SHELLY_TARGETS的自由定义目标别名。
一个目标在内部通过gatewaykey + trvid + trvdeviceid唯一标识，以确保不同网关上的多个BluTrv (200)不会被混淆。
最佳实践
- 1. 始终使用辅助脚本——不要使用没有超时的裸curl
- 优先使用本地RPC——云有严格的速率限制
- 验证写入——blutrv-control.sh在设置后会检查最终的target_C
- 超时处理——blutrv-status.sh已内置超时和回退机制
- 错误公开沟通——遇到超时/卡顿时，说运行时检查失败，而不是静默卡住
范围
发布的包有意限制为本地RPC控制、验证写入和云回退。
实验性的WebSocket写入或调试辅助工具不属于此ClawHub版本。
故障排除
请参阅references/troubleshooting.md了解常见错误情况和恢复步骤。
