Nest Device Access

Control Nest devices via Google's Smart Device Management API.

Setup

1. Google Cloud & Device Access

1. Create a Google Cloud project at console.cloud.google.com
2. Pay the $5 fee and create a Device Access project at console.nest.google.com/device-access
3. Create OAuth 2.0 credentials (Web application type)
4. Add https://www.google.com as an authorized redirect URI
5. Link your Nest account to the Device Access project

2. Get Refresh Token

Run the OAuth flow to get a refresh token:

bash
# 1. Open this URL in browser (replace CLIENT_ID and 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. Authorize and copy the 'code' parameter from the redirect URL

# 3. Exchange code for tokens:
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. Store Credentials

Store in 1Password or environment variables:

1Password (recommended): Create an item with fields: project_id, client_id, client_secret, refresh_token

Environment variables:

bash
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"

Usage

List devices

bash
python3 scripts/nest.py list

Thermostat

bash
# Get status
python3 scripts/nest.py get <device_id>

# Set temperature (Celsius)
python3 scripts/nest.py set-temp <device_id> 21 --unit c --type heat

# Set temperature (Fahrenheit)
python3 scripts/nest.py set-temp <device_id> 70 --unit f --type heat

# Change mode (HEAT, COOL, HEATCOOL, OFF)
python3 scripts/nest.py set-mode <device_id> HEAT

# Eco mode
python3 scripts/nest.py set-eco <device_id> MANUAL_ECO

Cameras

bash
# Generate live stream URL (RTSP, valid ~5 min)
python3 scripts/nest.py stream <device_id>

Python API

python
from nest import NestClient

client = NestClient()

# List devices
devices = client.list_devices()

# Thermostat control
client.set_heat_temperature(device_id, 21.0)  # Celsius
client.set_thermostat_mode(device_id, 'HEAT')
client.set_eco_mode(device_id, 'MANUAL_ECO')

# Camera stream
result = client.generate_stream(device_id)
rtsp_url = result['results']['streamUrls']['rtspUrl']

Configuration

The script checks for credentials in this order:

1. 1Password: Set NEST_OP_VAULT and NEST_OP_ITEM (or use defaults: vault "Alfred", item "Nest Device Access API")
2. Environment variables: NEST_PROJECT_ID, NEST_CLIENT_ID, NEST_CLIENT_SECRET, NEST_REFRESH_TOKEN

Temperature Reference

| Setting | Celsius | Fahrenheit | |---------|---------|------------| | Eco (away) | 15-17°C | 59-63°F | | Comfortable | 19-21°C | 66-70°F | | Warm | 22-23°C | 72-73°F | | Night | 17-18°C | 63-65°F |

Real-Time Events (Doorbell, Motion, etc.)

For instant alerts when someone rings the doorbell or motion is detected, you need to set up Google Cloud Pub/Sub with a webhook.

Prerequisites

• Google Cloud CLI (gcloud) installed and authenticated
• Cloudflare account (free tier works) for the tunnel
• Clawdbot hooks enabled in config

1. Enable Clawdbot Hooks

Add to your clawdbot.json:

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

Generate a token: openssl rand -hex 24

2. Create Pub/Sub Topic

bash
gcloud config set project YOUR_GCP_PROJECT_ID

# Create topic
gcloud pubsub topics create nest-events

# Grant SDM permission to publish (both the service account and publisher group)
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. Link Topic to Device Access

Go to console.nest.google.com/device-access → Your Project → Edit → Set Pub/Sub topic to:

projects/YOUR_GCP_PROJECT_ID/topics/nest-events

4. Set Up Cloudflare Tunnel

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

# Authenticate (opens browser)
~/.local/bin/cloudflared tunnel login

# Create named tunnel
~/.local/bin/cloudflared tunnel create nest-webhook

# Note the Tunnel ID (UUID) from output

Create ~/.cloudflared/config.yml:

yaml
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

Create DNS route:

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

5. Create Systemd Services

Webhook server (/etc/systemd/system/nest-webhook.service):

ini
[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):

ini
[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

Enable and start:

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

6. Create Pub/Sub Push Subscription

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

7. Test

bash
# Test webhook endpoint
curl https://nest.yourdomain.com/health

# Simulate doorbell event
curl -X POST http://localhost:8420/nest/events \
  -H "Content-Type: application/json" \
  -d '{"message":{"data":"eyJyZXNvdXJjZVVwZGF0ZSI6eyJuYW1lIjoiZW50ZXJwcmlzZXMvdGVzdC9kZXZpY2VzL0RPT1JCRUxMLTAxIiwiZXZlbnRzIjp7InNkbS5kZXZpY2VzLmV2ZW50cy5Eb29yYmVsbENoaW1lLkNoaW1lIjp7ImV2ZW50SWQiOiJ0ZXN0In19fX0="}}'

Supported Events

| Event | Behaviour | |-------|-----------| | DoorbellChime.Chime | 🔔 Alerts — sends photo to Telegram | | CameraPerson.Person | 🚶 Alerts — sends photo to Telegram | | CameraMotion.Motion | 📹 Logged only (no alert) | | CameraSound.Sound | 🔊 Logged only (no alert) | | CameraClipPreview.ClipPreview | 🎬 Logged only (no alert) |

> Staleness filter: Events older than 5 minutes are logged but never alerted. This prevents notification floods if queued Pub/Sub messages are delivered late.

Image Capture

When a doorbell or person event triggers an alert:

1. Primary: SDM GenerateImage API — fast, event-specific snapshot
2. Fallback: RTSP live stream frame capture via ffmpeg (requires ffmpeg installed)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CLAWDBOT_GATEWAY_URL | No | Gateway URL (default: http://localhost:18789) | | CLAWDBOT_HOOKS_TOKEN | Yes | Gateway hooks token for awareness notifications | | OP_SVC_ACCT_TOKEN | Yes | 1Password service account token for Nest API credentials | | TELEGRAM_BOT_TOKEN | Yes | Telegram bot token for sending alerts | | TELEGRAM_CHAT_ID | Yes | Telegram chat ID to receive alerts | | PORT | No | Webhook server port (default: 8420) |

Important Setup Notes

• Verify the full Pub/Sub topic path in Device Access Console matches your GCP project exactly: projects/YOUR_GCP_PROJECT_ID/topics/nest-events
• Use a push subscription, not pull — the webhook expects HTTP POST delivery
• Test end-to-end after setup: ring the doorbell and confirm a photo arrives. Don't rely on simulated POST requests alone.

Limitations

• Camera event images expire after ~5 minutes (RTSP fallback captures current frame instead)
• Real-time events require Pub/Sub setup (see above)
• Quick tunnels (without Cloudflare account) have no uptime guarantee
• Some older Nest devices may not support all features
• Motion and sound events are intentionally not alerted to avoid notification fatigue