Nest SDM 技能

通过 Smart Device Management（SDM）REST API 控制和监控 Google Nest 设备。

配置

前提条件

1. Device Access Console — 在 https://console.nest.google.com/device-access 注册（一次性费用 $5）
2. GCP 项目 — 在 https://console.cloud.google.com 创建，并启用 SDM API
3. OAuth 客户端 — 类型为 Web 应用程序，重定向 URI 设为 https://www.google.com
4. SDM 权限范围（scope） — 在 OAuth 同意屏幕中添加 https://www.googleapis.com/auth/sdm.service

首次授权

1. 构建授权 URL：

https://nestservices.google.com/partnerconnections//auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=&response_type=code&scope=https://www.googleapis.com/auth/sdm.service

2. 在浏览器中打开该链接，并使用设备所有者的 Google 账户登录
3. 启用全部设备权限，点击“下一步”，然后继续完成授权流程
4. 从重定向 URL 中复制 code= 参数值
5. 换取访问令牌：

curl -s -X POST https://oauth2.googleapis.com/token 
  -d "client_id=" 
  -d "client_secret=" 
  -d "code=" 
  -d "grant_type=authorization_code" 
  -d "redirect_uri=https://www.google.com"

6. 将获取到的令牌保存至配置文件（参见下方“配置”章节）

配置

创建 ~/.openclaw/workspace/.nest-sdm-tokens.json：

{
  "client_id": "",
  "client_secret": "",
  "project_id": "",
  "refresh_token": "",
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/sdm.service"
}

设置安全权限：chmod 600 ~/.openclaw/workspace/.nest-sdm-tokens.json

CLI 使用方法

# 为方便使用，可设置别名
alias nest="/nest-sdm.sh"

设备发现

nest devices                    # 列出所有设备（JSON 格式）
nest structures                 # 列出结构/房间

恒温器（Thermostat）

nest thermostat                 # 当前状态（温度、湿度、模式、设定值）
nest set-cool <°F>              # 切换至 COOL 模式并设定目标温度
nest set-heat <°F>              # 切换至 HEAT 模式并设定目标温度
nest set-range   # 设定 HEATCOOL 模式下的温度区间
nest set-mode             # 可选：HEAT | COOL | HEATCOOL | OFF
nest set-eco              # 可选：MANUAL_ECO | OFF
nest fan-on [duration_seconds]  # 开启风扇（默认时长：900 秒 / 15 分钟）
nest fan-off                    # 关闭风扇

门铃（Doorbell）与摄像头（Cameras）

nest doorbell                   # 门铃信息及支持能力
nest display                    # 厨房显示屏信息
nest camera-stream   # 生成 WebRTC 实时视频流（返回 SDP answer）
nest camera-image     # 获取事件快照 URL

原始 API 调用

nest api GET devices                              # 原始设备列表
nest api GET devices/                  # 单个设备详情
nest api POST devices/:executeCommand '{"command":"...","params":{...}}'

支持的设备类型

SDM API 命令参考

恒温器命令

摄像头命令

Pub/Sub 实时事件

实时接收门铃触发、移动侦测、人物识别以及设备状态变更等事件通知。

CLI 工具：nest-events

nest-events setup-check         # 验证 Pub/Sub 配置是否就绪
nest-events create-topic        # 创建 GCP Pub/Sub 主题
nest-events grant-permissions   # 授予 SDM 发布者角色
nest-events create-subscription # 创建拉取订阅（pull subscription）
nest-events poll                # 一次性拉取事件
nest-events listen              # 持续轮询（守护进程模式）

配置步骤

1. 带 Pub/Sub 权限范围的 OAuth 授权 — 使用 your-email@example.com 执行 OAuth 流程，权限范围需包含 pubsub 和 cloud-platform；将令牌保存至 .nest-pubsub-tokens.json。
2. 创建主题 — 运行 nest-events create-topic（将创建 projects/YOUR_GCP_PROJECT/topics/nest-sdm-events）
3. 授予发布权限 — 运行 nest-events grant-permissions（向 sdm-publisher@googlegroups.com 授予角色）
4. 创建订阅 — 运行 nest-events create-subscription
5. 在 Device Access Console 中启用 Pub/Sub — 访问 https://console.nest.google.com/device-access → 启用 Pub/Sub → 输入主题 ID
6. 触发初始事件 — 执行一次 nest devices（任意 API 调用即可触发）
7. 启动监听器 — 运行 nest-events listen

支持的事件类型

配置

环境变量：

事件日志

原始事件将记录至 data/nest-events/events-YYYY-MM-DD.jsonl。

告警去重

相同类型的事件在 60 秒内不会重复触发告警，以避免告警疲劳。

重要注意事项

• 令牌过期：若 GCP 应用处于“测试”模式，刷新令牌（refresh token）将在 7 天后过期；请发布应用以避免重复授权。
• 温度单位：API 内部使用摄氏度（Celsius），CLI 已自动处理华氏（°F）↔ 摄氏（°C）转换。
• 设定值约束：HEATCOOL 模式下，加热与制冷设定值之间至少需保持 1.5°C（2.7°F）的温差。
• 摄像头流媒体：仅支持 WebRTC（不支持 RTSP），需完成 SDP Offer/Answer 协商流程。
• 调用频率限制：每个设备每分钟最多 10 次查询、最多 10 条命令。
• 事件通知：请使用 nest-events listen 获取实时告警；该功能依赖 Pub/Sub 配置（详见上文）。