Nest 设备访问

通过 Google 的智能设备管理（Smart Device Management）API 控制 Nest 设备。

配置步骤

1. Google Cloud 与 Device Access

1. 在 console.cloud.google.com 创建一个 Google Cloud 项目
2. 支付 5 美元费用，并在 console.nest.google.com/device-access 创建一个 Device Access 项目
3. 创建 OAuth 2.0 凭据（类型为 Web 应用）
4. 将 https://www.google.com 添加为已授权的重定向 URI
5. 将您的 Nest 账户关联至该 Device Access 项目

2. 获取 Refresh Token

运行 OAuth 流程以获取 refresh token：

# 1. 在浏览器中打开以下 URL（请替换 CLIENT_ID 和 PROJECT_ID）：
https://nestservices.google.com/partnerconnections/PROJECT_ID/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=CLIENT_ID&response_type=code&scope=https://www.googleapis.com/auth/sdm.service

# 2. 授权后，从重定向 URL 中复制 'code' 参数值

# 3. 使用 code 换取 access token 与 refresh token：
curl -X POST https://oauth2.googleapis.com/token 
  -d "client_id=CLIENT_ID" 
  -d "client_secret=CLIENT_SECRET" 
  -d "code=AUTH_CODE" 
  -d "grant_type=authorization_code" 
  -d "redirect_uri=https://www.google.com"

3. 存储凭据

建议存储于 1Password 或环境变量中：

1Password（推荐）： 创建一个条目，包含以下字段：project_id、client_id、client_secret、refresh_token

环境变量：

export NEST_PROJECT_ID="your-project-id"
export NEST_CLIENT_ID="your-client-id"
export NEST_CLIENT_SECRET="your-client-secret"
export NEST_REFRESH_TOKEN="your-refresh-token"

使用方法

列出设备

python3 scripts/nest.py list

恒温器（Thermostat）

# 获取当前状态
python3 scripts/nest.py get 

# 设置温度（摄氏度）
python3 scripts/nest.py set-temp  21 --unit c --type heat

# 设置温度（华氏度）
python3 scripts/nest.py set-temp  70 --unit f --type heat

# 切换模式（HEAT、COOL、HEATCOOL、OFF）
python3 scripts/nest.py set-mode  HEAT

# 启用节能模式（Eco mode）
python3 scripts/nest.py set-eco  MANUAL_ECO

摄像头（Cameras）

# 生成实时视频流 URL（RTSP 协议，有效期约 5 分钟）
python3 scripts/nest.py stream 

Python API

from nest import NestClient

client = NestClient()

# 列出所有设备
devices = client.list_devices()

# 恒温器控制
client.set_heat_temperature(device_id, 21.0)  # 单位：摄氏度
client.set_thermostat_mode(device_id, 'HEAT')
client.set_eco_mode(device_id, 'MANUAL_ECO')

# 摄像头视频流
result = client.generate_stream(device_id)
rtsp_url = result['results']['streamUrls']['rtspUrl']

配置说明

脚本按以下顺序查找凭据：

1. 1Password：设置 NEST_OP_VAULT 和 NEST_OP_ITEM（或使用默认值：vault 名为 "Alfred"，item 名为 "Nest Device Access API"）
2. 环境变量：NEST_PROJECT_ID、NEST_CLIENT_ID、NEST_CLIENT_SECRET、NEST_REFRESH_TOKEN

温度参考值

实时事件（门铃、移动侦测等）

如需在有人按门铃或检测到移动时即时收到通知，需配置 Google Cloud Pub/Sub 并接入 webhook。

前置条件

• 已安装并完成身份验证的 Google Cloud CLI（gcloud）
• Cloudflare 账户（免费版即可支持隧道功能）
• 已在配置中启用 Clawdbot hooks

1. 启用 Clawdbot Hooks

在您的 clawdbot.json 中添加以下内容：

{
  "hooks": {
    "enabled": true,
    "token": "your-secret-token-here"
  }
}

生成 token 命令：openssl rand -hex 24

2. 创建 Pub/Sub Topic

gcloud config set project YOUR_GCP_PROJECT_ID

# 创建 topic
gcloud pubsub topics create nest-events

# 授予 SDM 服务账号发布权限（包括服务账号和发布者组）
gcloud pubsub topics add-iam-policy-binding nest-events 
  --member="serviceAccount:sdm-prod@sdm-prod.iam.gserviceaccount.com" 
  --role="roles/pubsub.publisher"

gcloud pubsub topics add-iam-policy-binding nest-events 
  --member="group:sdm-publisher@googlegroups.com" 
  --role="roles/pubsub.publisher"

3. 将 Topic 关联至 Device Access

访问 console.nest.google.com/device-access → 您的项目 → 编辑 → 设置 Pub/Sub topic 为：

projects/YOUR_GCP_PROJECT_ID/topics/nest-events

4. 配置 Cloudflare Tunnel

# 安装 cloudflared
curl -L -o ~/.local/bin/cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x ~/.local/bin/cloudflared

# 认证（将自动打开浏览器）
~/.local/bin/cloudflared tunnel login

# 创建具名隧道
~/.local/bin/cloudflared tunnel create nest-webhook

# 记录输出中的 Tunnel ID（UUID）

创建 ~/.cloudflared/config.yml：

tunnel: nest-webhook
credentials-file: /home/YOUR_USER/.cloudflared/TUNNEL_ID.json

ingress:
  - hostname: nest.yourdomain.com
    service: http://localhost:8420
  - service: http_status:404

创建 DNS 解析记录：

~/.local/bin/cloudflared tunnel route dns nest-webhook nest.yourdomain.com

5. 创建 Systemd 服务

Webhook 服务端（/etc/systemd/system/nest-webhook.service）：

[Unit]
Description=Nest Pub/Sub Webhook Server
After=network.target

[Service]
Type=simple
User=YOUR_USER
Environment=CLAWDBOT_GATEWAY_URL=http://localhost:18789
Environment=CLAWDBOT_HOOKS_TOKEN=your-hooks-token-here
ExecStart=/usr/bin/python3 /path/to/skills/nest-devices/scripts/nest-webhook.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Cloudflare Tunnel 服务（/etc/systemd/system/cloudflared-nest.service）：

[Unit]
Description=Cloudflare Tunnel for Nest Webhook
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_USER
ExecStart=/home/YOUR_USER/.local/bin/cloudflared tunnel run nest-webhook
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable --now nest-webhook cloudflared-nest

6. 创建 Pub/Sub Push 订阅

gcloud pubsub subscriptions create nest-events-sub 
  --topic=nest-events 
  --push-endpoint="https://nest.yourdomain.com/nest/events" 
  --ack-deadline=30

7. 测试

# 测试 webhook 健康状态
curl https://nest.yourdomain.com/health

# 模拟门铃事件
curl -X POST http://localhost:8420/nest/events 
  -H "Content-Type: application/json" 
  -d '{"message":{"data":"eyJyZXNvdXJjZVVwZGF0ZSI6eyJuYW1lIjoiZW50ZXJwcmlzZXMvdGVzdC9kZXZpY2VzL0RPT1JCRUxMLTAxIiwiZXZlbnRzIjp7InNkbS5kZXZpY2VzLmV2ZW50cy5Eb29yYmVsbENoaW1lLkNoaW1lIjp7ImV2ZW50SWQiOiJ0ZXN0In19fX0="}}'

支持的事件类型

陈旧性过滤（Staleness filter）：超过 5 分钟的事件仅记录日志，不会触发告警。此举可避免因 Pub/Sub 消息延迟投递而引发大量重复通知。

图像捕获机制

当门铃或人物事件触发告警时：

1. 首选方式：调用 SDM GenerateImage API —— 快速、事件精准的快照
2. 备用方式：通过 ffmpeg 截取 RTSP 实时流当前帧（需系统已安装 ffmpeg）

环境变量说明

重要配置提示

• 请严格核对 Device Access 控制台中填写的完整 Pub/Sub topic 路径，必须与您的 GCP 项目完全一致：projects/YOUR_GCP_PROJECT_ID/topics/nest-events
• 务必使用 push 订阅（而非 pull 订阅） —— Webhook 服务仅接受 HTTP POST 方式推送的消息
• 配置完成后请进行端到端测试：实际按压门铃，确认照片成功送达。切勿仅依赖模拟的 POST 请求测试结果。

限制说明

• 摄像头事件图像有效期约为 5 分钟（RTSP 备用方案会截取当前帧）
• 实时事件依赖 Pub/Sub 配置（详见上文）
• 未绑定 Cloudflare 账户的快速隧道（Quick tunnels）不保证持续可用性
• 部分较老款 Nest 设备可能不支持全部功能
• 为避免通知疲劳，移动侦测（Motion）与声音事件（Sound）默认不触发告警