homebridge-firstalert

Homebridge dynamic-platform plugin for the First Alert VX1 HD Video Doorbell (CAMW-WDB), using the supported Honeywell Home API with First Alert OAuth.

Current status

• HomeKit doorbell, camera streaming, snapshots, and motion service
• First Alert OAuth refresh and automatic VX1 discovery
• Polled camera notifications for doorbell and motion events
• Optional RTSP and snapshot URL overrides for local or diagnostic use

Development

Requires Node.js 20+, Homebridge, and FFmpeg.

Debug logging

Enable Debug Logging in the plugin settings and start Homebridge with debug logging enabled to inspect sanitized API responses. Debug output includes OAuth lifecycle, discovery counts, camera detail fields, notification counts, stream lookup, and FFmpeg lifecycle information.

Sensitive fields are redacted, URL query strings are removed, long responses are truncated, and arrays are sampled. Normal logging remains limited to discovery results, important stream findings, warnings, and errors. Do not post logs publicly without reviewing them first.

npm install
npm run build
npm link
homebridge -D -U ~/.homebridge-dev

Publishing and Homebridge installation

GitHub Actions validates Node.js 20, 22, and 24 on every pull request and push to main. Homebridge discovers installable plugins through npm, not directly from GitHub.

To publish a release:

1. Create the homebridge-firstalert package under your npm account on the first publish, or confirm the name is available.
2. Add an npm automation token as the repository secret NPM_TOKEN.
3. Create an npm GitHub environment, optionally with required reviewers.
4. Update the version in package.json and package-lock.json, then merge it.
5. Publish a GitHub release whose tag matches that version, for example v0.1.0.

The release workflow validates the package and publishes it to npm with provenance. After publication, users can find and install it from the Homebridge UI because the package includes the homebridge-plugin keyword.

Configuration

Recommended: Homebridge UI

Open Plugins → First Alert Doorbell → Settings, enter the API key and secret from your Honeywell Home developer application, and click Sign in with First Alert. After approval, paste the final callback URL into the assistant. It exchanges the code, discovers your locations, and saves the refresh token automatically—no terminal commands are needed.

Register https://localhost/callback as the developer application's redirect URI, or enter your registered URI in the assistant.

New to the Resideo developer portal? Follow the complete developer account and application setup guide. It explains the two separate accounts, every setup step, security considerations, and common OAuth errors.

Manual configuration

{
  "platform": "FirstAlertDoorbell",
  "name": "First Alert",
  "apiKey": "YOUR-DEVELOPER-API-KEY",
  "apiSecret": "YOUR-DEVELOPER-API-SECRET",
  "refreshToken": "YOUR-FIRST-ALERT-REFRESH-TOKEN",
  "locationId": "YOUR-FIRST-ALERT-LOCATION-ID",
  "ffmpegPath": "ffmpeg",
  "pollInterval": 300
}

Optional stream overrides can be matched by serial number:

"doorbells": [{
    "name": "Front Door",
    "serialNumber": "YOUR-SERIAL",
    "rtspUrl": "rtsp://user:password@doorbell/stream",
    "snapshotUrl": "http://doorbell/snapshot.jpg"
}]

Create an application at the Honeywell Home developer portal. Authorize it using https://api.honeywellhome.com/oauth2/authorize?response_type=code&client_id=API_KEY&redirect_uri=REDIRECT_URI&subSystemId=5, exchange the returned code for a refresh token, and place that token in the configuration.

The supported camera API provides discovery, configuration, and notification history, but it does not publish a live stream or snapshot resource. HomeKit video therefore requires rtspUrl and snapshotUrl overrides obtained from a supported local gateway or another authorized source. Keep API credentials and camera URLs private.