快照处理

• 摄像头快照包含敏感图像信息 —— 请勿将其存储于全局可读目录中
• 脚本会自动将快照文件权限设为 chmod 600（仅属主可读写）
• 快照文件使用完毕后，请及时清理临时文件

最佳实践

操作前务必先检查状态

调用设备相关命令前，请先确认 Hub 已就绪：

scripts/starling.sh status

请确认输出中包含 apiReady: true 和 connectedToNest: true 后再继续后续操作。

遵守速率限制

以下限制由 Nest 云服务强制执行：

• POST（设置属性）：每台设备 最多每秒一次
• Snapshot（快照）：每台摄像头 最多每 10 秒一次
• GET（读取属性/设备列表）：无云侧速率限制（数据来自本地缓存）

幂等性操作

以下操作可安全重试，不会产生副作用：

• 所有 GET 类操作（status、devices、device、get、snapshot）
• 值未变更的 SET 操作（例如当前温度已是 22°C，再次设置 targetTemperature=22）
• stream-extend（仅重置保活计时器）

非幂等操作：stream-start（每次调用均创建新流）

错误处理

脚本提供明确、可操作的错误提示：

• 401 错误：请检查 API 密钥及其权限 —— 密钥绝不会出现在错误输出中
• 404 错误：请核对设备 ID 与属性名称是否正确
• 400 错误：请检查参数值与类型是否符合要求

常用工作流

列出全部设备

scripts/starling.sh devices

读取设备属性

scripts/starling.sh device           # 获取全部属性
scripts/starling.sh get    # 获取单个属性

设置设备属性

scripts/starling.sh set  key=value [key=value...]

摄像头快照

scripts/starling.sh snapshot  --output photo.jpg --width 1280

摄像头流媒体（WebRTC）

scripts/starling.sh stream-start  
scripts/starling.sh stream-extend     # 每 60 秒调用一次
scripts/starling.sh stream-stop  

常见任务示例

将恒温器设为 22°C：

scripts/starling.sh set  targetTemperature=22

设置 HVAC 模式：

scripts/starling.sh set  hvacMode=heat

检测摄像头是否触发移动侦测：

scripts/starling.sh get  motionDetected

上锁/解锁门锁：

scripts/starling.sh set  targetState=locked

获取摄像头快照：

scripts/starling.sh snapshot  --output front-door.jpg

检查烟雾/一氧化碳报警状态：

scripts/starling.sh get  smokeDetected
scripts/starling.sh get  coDetected

设置家庭/离家模式：

scripts/starling.sh set  homeState=away

API 参考文档

完整设备属性说明、可写属性列表、错误码定义及各端点详细文档，请参阅 references/api-reference.md。