@homebridge-plugins/homebridge-firstalert 0.0.1-beta.1 → 0.0.1-beta.3

package/API/README.md

@@ -0,0 +1,310 @@
+# First Alert by Resideo - Home Assistant Integration
+
+A custom Home Assistant integration for First Alert Safe & Sound smoke/CO detectors connected via the Resideo platform.
+
+## Supported Devices
+
+- First Alert Safe & Sound Smart Smoke/CO Alarm (SMCO600NVACA)
+- Other Resideo-connected First Alert devices may also work
+
+## Features
+
+- **Easy Setup** - Login with your Resideo email and password directly
+- **Smoke Alarm Detection** - Binary sensor that triggers when smoke is detected
+- **CO Alarm Detection** - Binary sensor that triggers when carbon monoxide is detected
+- **Battery Monitoring** - Track battery status and get low battery alerts
+- **Power Source** - See if device is on AC or battery power
+- **Connectivity Status** - Know if your detector is online
+- **Malfunction Detection** - Get alerts if the device has issues
+- **Test Mode & Silence Status** - Monitor when detectors are in test mode or silenced
+- **Early Warning** - Track early warning feature status
+- **End of Life Alerts** - Know when your detector needs replacement
+- **Comprehensive Fault Detection** - Monitor various fault conditions
+- **Configurable Polling** - Adjust update interval from 5 seconds to 1 hour
+
+## Installation
+
+### HACS (Recommended)
+
+1. Open HACS in Home Assistant
+2. Click the three dots menu → Custom repositories
+3. Add `https://github.com/aidenmitchell/ha-resideo-firstalert` with category "Integration"
+4. Search for "First Alert by Resideo" and install
+5. Restart Home Assistant
+
+### Manual Installation
+
+1. Copy the `custom_components/resideo_firstalert` folder to your Home Assistant `config/custom_components/` directory
+2. Restart Home Assistant
+
+## Configuration
+
+### Authentication
+
+When adding the integration, you have two options:
+
+#### Option 1: Login with Email & Password (Recommended)
+
+1. Go to **Settings** → **Devices & Services** → **Add Integration**
+2. Search for "First Alert by Resideo"
+3. Select **"Login with email and password"**
+4. Enter your Resideo account credentials (same as the First Alert app)
+5. Your devices will be automatically discovered
+
+#### Option 2: Manual Token Entry
+
+If you prefer, you can manually obtain and enter a refresh token:
+
+1. **Install a network proxy** like [Proxyman](https://proxyman.io/) (macOS/iOS) or [mitmproxy](https://mitmproxy.org/)
+
+2. **Configure SSL interception** for `login.resideo.com`
+
+3. **Log into the First Alert app** on your phone while capturing traffic
+
+4. **Look for the request** to `POST https://login.resideo.com/oauth/token`
+
+5. **Find the `refresh_token`** in the response JSON:
+   ```json
+   {
+     "access_token": "...",
+     "refresh_token": "THIS_IS_YOUR_TOKEN",
+     "expires_in": 3600,
+     "token_type": "Bearer"
+   }
+   ```
+
+6. In Home Assistant, select **"Enter refresh token manually"** and paste your token
+
+### Options
+
+After setup, you can configure the integration via **Settings** → **Devices & Services** → **First Alert by Resideo** → **Configure**:
+
+- **Settings** - Adjust the polling interval (5-3600 seconds, default: 60)
+- **Update refresh token** - Enter a new token if needed without recreating the integration
+
+## Entities Created
+
+For each smoke detector, the following entities are created:
+
+### Binary Sensors
+
+| Entity | Description | Device Class | Default |
+|--------|-------------|--------------|---------|
+| Smoke Alarm | On when smoke is detected | `smoke` | Enabled |
+| CO Alarm | On when CO is detected | `co` | Enabled |
+| Malfunction | On when device has a problem | `problem` | Enabled |
+| Connectivity | On when device is online | `connectivity` | Enabled |
+| Battery Low | On when battery is low | `battery` | Enabled |
+| Test Mode | On when device is in test mode | `running` | Enabled |
+| Silenced | On when alarm is silenced | `running` | Enabled |
+| End of Life | On when device needs replacement | `problem` | Enabled |
+| Early Warning | On when early warning is enabled | - | Enabled |
+| Supervision Healthy | On when supervision is healthy | - | Disabled |
+| General Fault | On when general fault detected | `problem` | Disabled |
+| E2 Fault | On when E2 fault detected | `problem` | Disabled |
+| Photo Sensor Fault | On when photo sensor fault detected | `problem` | Disabled |
+| Drift Malfunction | On when drift malfunction detected | `problem` | Disabled |
+| CO Sensor Fault | On when CO sensor fault detected | `problem` | Disabled |
+| Temperature Sensor Fault | On when temp sensor fault detected | `problem` | Disabled |
+| Voice Module Fault | On when voice module fault detected | `problem` | Disabled |
+| Radio Fault | On when radio fault detected | `problem` | Disabled |
+
+### Sensors
+
+| Entity | Description | Default |
+|--------|-------------|---------|
+| Battery Status | `good` or `low` | Enabled |
+| Power Source | `ac` or `battery` | Enabled |
+| Smoke Status | `idle` or `alarm` | Enabled |
+| CO Status | `idle` or `alarm` | Enabled |
+| Test Status | `idle` or `testing` | Enabled |
+| Silence Status | `not_silenced` or `silenced` | Enabled |
+| End of Life Status | `no` or `yes` | Enabled |
+| Language | Device language setting | Enabled |
+| Room | Room number setting | Disabled |
+| WiFi Signal Strength | Signal strength in dBm | Disabled |
+| WiFi Network | Connected SSID | Disabled |
+| Last Seen | Timestamp of last communication | Disabled |
+| Firmware Version | Device firmware | Disabled |
+| Firmware (Exec Core) | Exec core firmware version | Disabled |
+| Firmware (Sensor Core) | Sensor core firmware version | Disabled |
+| Hardware Version (E2C) | E2C hardware version | Disabled |
+| Hardware Version (Exec Core) | Exec core hardware version | Disabled |
+| Hardware Version (Sensor Core) | Sensor core hardware version | Disabled |
+| Voice File Version | Voice file version | Disabled |
+| Running Hours | Total running hours | Disabled |
+| Registration Date | When device was registered | Disabled |
+| Last Firmware Update | Last firmware update timestamp | Disabled |
+
+## Example Automations
+
+### Alert on Smoke Detection
+```yaml
+automation:
+  - alias: "Smoke Alarm Alert"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.living_room_detector_smoke_alarm
+        to: "on"
+    action:
+      - service: notify.mobile_app
+        data:
+          title: "SMOKE DETECTED!"
+          message: "Smoke alarm triggered in Living Room"
+          data:
+            priority: high
+            ttl: 0
+```
+
+### Alert on CO Detection
+```yaml
+automation:
+  - alias: "CO Alarm Alert"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.living_room_detector_co_alarm
+        to: "on"
+    action:
+      - service: notify.mobile_app
+        data:
+          title: "CARBON MONOXIDE DETECTED!"
+          message: "CO alarm triggered - evacuate immediately!"
+          data:
+            priority: high
+            ttl: 0
+```
+
+### Low Battery Alert
+```yaml
+automation:
+  - alias: "Smoke Detector Low Battery"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.living_room_detector_battery_low
+        to: "on"
+    action:
+      - service: notify.mobile_app
+        data:
+          title: "Low Battery"
+          message: "Living Room smoke detector battery is low"
+```
+
+### End of Life Alert
+```yaml
+automation:
+  - alias: "Smoke Detector End of Life"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.living_room_detector_end_of_life
+        to: "on"
+    action:
+      - service: notify.mobile_app
+        data:
+          title: "Detector Replacement Needed"
+          message: "Living Room smoke detector has reached end of life and should be replaced"
+```
+
+## Troubleshooting
+
+### "Invalid email or password" error
+Double-check your credentials. These are the same as your First Alert / Resideo app login.
+
+### "Authentication failed" error
+Your refresh token may have expired. Use the **Configure** option to update your token, or re-authenticate with email/password.
+
+### "Unable to connect" error
+Check your internet connection and verify the Resideo API is accessible.
+
+### Devices not showing
+Make sure your devices are properly set up in the First Alert app and are online.
+
+### Token Expiration
+- **Access tokens** expire hourly and are automatically refreshed
+- **Refresh tokens** expire after ~30 days. When this happens, Home Assistant will prompt you to re-authenticate
+
+## Removing the Integration
+
+To remove the First Alert by Resideo integration:
+
+1. Go to **Settings** → **Devices & Services**
+2. Find "First Alert by Resideo" and click on it
+3. Click the three-dot menu → **Delete**
+4. Confirm the deletion
+
+All entities and device data will be removed. No additional cleanup is required.
+
+## Technical Details
+
+- **Polling Interval**: 60 seconds (configurable from 5-3600 seconds)
+- **API Base URL**: `https://api.resideo.com`
+- **Authentication**: OAuth 2.0 with PKCE via Auth0
+
+## Privacy Note
+
+This integration communicates with Resideo's cloud servers. Your device data passes through their infrastructure. The integration stores only the refresh token locally - your email and password are not stored.
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Local Development
+
+### Prerequisites
+
+- Docker and Docker Compose
+- A Resideo account with First Alert devices
+
+### Quick Start
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/aidenmitchell/ha-resideo-firstalert.git
+   cd ha-resideo-firstalert
+   ```
+
+2. Create the config file:
+   ```bash
+   cp config/configuration.yaml.example config/configuration.yaml
+   ```
+
+3. Start Home Assistant:
+   ```bash
+   docker compose up -d
+   ```
+
+4. Open http://localhost:8123 in your browser
+
+5. Complete the Home Assistant onboarding, then add the integration:
+   - Settings → Devices & Services → Add Integration
+   - Search "First Alert by Resideo"
+   - Login with your email and password
+
+### Development Workflow
+
+The `custom_components` folder is mounted directly into the container, so changes to the integration code take effect after restarting Home Assistant:
+
+```bash
+# Restart to pick up code changes
+docker compose restart
+
+# View logs
+docker compose logs -f homeassistant
+
+# Stop
+docker compose down
+```
+
+### Debug Logging
+
+The example configuration enables debug logging for the integration. View logs with:
+```bash
+docker compose logs -f homeassistant 2>&1 | grep resideo_firstalert
+```
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on GitHub.
+
+## Disclaimer
+
+This is an unofficial integration and is not affiliated with, endorsed by, or supported by First Alert or Resideo. Use at your own risk.

package/API/RESIDEO_API.md

@@ -0,0 +1,377 @@
+# First Alert by Resideo API Documentation
+
+This document describes the API used by the First Alert by Resideo mobile app to communicate with smoke/CO detectors.
+
+## Authentication
+
+The API uses **OAuth 2.0 with PKCE** via **Auth0**.
+
+### OAuth Configuration
+
+| Parameter | Value |
+|-----------|-------|
+| Auth Domain | `login.resideo.com` |
+| Client ID | `SRmiA7CaYi1JgivDZdzzoZu4X5VBogGt` |
+| Audience | `https://resideo-prod.auth0.com/api/v2/` |
+| Scopes | `openid profile email offline_access` |
+
+### Token Refresh
+
+Access tokens expire after 1 hour. Use the refresh token to get new access tokens:
+
+```http
+POST https://login.resideo.com/oauth/token
+Content-Type: application/json
+
+{
+  "grant_type": "refresh_token",
+  "refresh_token": "<refresh_token>",
+  "client_id": "SRmiA7CaYi1JgivDZdzzoZu4X5VBogGt"
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "eyJ...",
+  "id_token": "eyJ...",
+  "scope": "openid profile email offline_access",
+  "expires_in": 3600,
+  "token_type": "Bearer"
+}
+```
+
+---
+
+## API Endpoints
+
+Base URL: `https://api.resideo.com`
+
+All requests require:
+```http
+Authorization: Bearer <access_token>
+Content-Type: application/json
+Accept: application/json
+```
+
+### Get Account Information
+
+```http
+GET /ris-public-api/api/v1/accounts
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "id": "VXNlcjow...",
+    "firstName": "John",
+    "lastName": "Doe",
+    "contactEmail": "user@example.com",
+    "countryCode": "US",
+    "locale": "en_US",
+    "consumerUsers": [
+      {
+        "id": "Q29uc3VtZXJVc2VyOj...",
+        "role": "ADMIN",
+        "consumerAccount": {
+          "id": "Q29uc3VtZXJBY2NvdW50Oj...",
+          "locations": [
+            {
+              "id": "Q29uc3VtZXJEZXZpY2VMb2NhdGlvbjo...",
+              "name": "Home",
+              "address": {
+                "addressLine1": "123 Main St",
+                "city": "Anytown",
+                "stateProvinceRegionCode": "CA",
+                "zipPostalCode": "90210",
+                "countryCode": "US"
+              },
+              "geoCoordinate": {
+                "latitude": 34.0901,
+                "longitude": -118.4065
+              },
+              "consumerDevices": [
+                {
+                  "id": "Q29uc3VtZXJEZXZpY2U6...",
+                  "name": "Living Room Detector",
+                  "device": {
+                    "id": "THlyaWNUaGVybW9zdGF0RGV2aWNlOj...",
+                    "deviceId": "XXXXXXXXXXXX",
+                    "globalDeviceType": "Citadel_SC5"
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "errors": []
+}
+```
+
+### Get Device State
+
+```http
+GET /ris-public-api/api/v2/devices/smokeDetectors/{deviceId}/state
+```
+
+**Example:** `GET /ris-public-api/api/v2/devices/smokeDetectors/XXXXXXXXXXXX/state`
+
+**Response:**
+```json
+{
+  "name": "XXXXXXXXXXXX",
+  "deviceType": "SmokeDetector",
+  "sku": "SMCO600NVACA",
+  "registrationStatus": "Registered",
+  "isOnline": true,
+  "isSupervisionHealthy": true,
+  "isOnlineComputed": true,
+  "dataSyncState": "Completed",
+  "registrationDate": "2025-12-18T03:22:17.457+00:00",
+  "lastMessageReceivedTime": "2025-12-20T17:02:30.861+00:00",
+  "deviceState": {
+    "desired": { ... },
+    "reported": {
+      "alarmState": {
+        "co": {
+          "eventSource": "self",
+          "tStampEpoch": 1766247701,
+          "deviceState": "idle"
+        },
+        "smoke": {
+          "eventSource": "self",
+          "tStampEpoch": 1766247701,
+          "deviceState": "idle"
+        },
+        "test": {
+          "eventSource": "self",
+          "tStampEpoch": 1766034736,
+          "deviceState": "idle"
+        },
+        "malfunction": {
+          "eventSource": "self",
+          "tStampEpoch": 1766247701,
+          "deviceState": "none"
+        },
+        "battery": {
+          "eventSource": "self",
+          "tStampEpoch": 1766247701,
+          "deviceState": "good"
+        },
+        "eol": {
+          "eventSource": "self",
+          "tStampEpoch": 1766247704,
+          "deviceState": "no"
+        },
+        "power": {
+          "eventSource": "self",
+          "tStampEpoch": 1766029736,
+          "deviceState": "ac"
+        },
+        "silence": {
+          "eventSource": "self",
+          "tStampEpoch": 1766247701,
+          "deviceState": "not_silenced"
+        }
+      },
+      "deviceConfig": {
+        "language": "en_US",
+        "room": 14,
+        "debugLevel": "error",
+        "earlyWarning": true
+      },
+      "deviceInfo": {
+        "hwVerE2C": "1.0.0",
+        "hwVerExecCore": "1.0.0",
+        "hwVerSensorCore": "1.0.0",
+        "fwVerE2C": "00.07.72.00",
+        "fwVerExecCore": "01.06.38",
+        "fwVerSensorCore": "11.00",
+        "voiceFileVer": "1.0.0",
+        "runningHrs": 0
+      },
+      "deviceStatus": {
+        "rssi": -30,
+        "ssid": "WiFiNetwork"
+      },
+      "deviceStatusFlags": {
+        "fault": false,
+        "e2Fault": false,
+        "photoFault": false,
+        "driftMalfunction": false,
+        "coFault": false,
+        "temperatureFault": false,
+        "voiceFault": false,
+        "radioFault": false
+      }
+    }
+  },
+  "lastFirmwareUpdateTime": "2025-12-18T03:22:45.412+00:00"
+}
+```
+
+---
+
+## Alarm State Values
+
+### `alarmState.smoke.deviceState`
+| Value | Description |
+|-------|-------------|
+| `idle` | Normal - no smoke detected |
+| `alarm` | Smoke alarm active |
+
+### `alarmState.co.deviceState`
+| Value | Description |
+|-------|-------------|
+| `idle` | Normal - no CO detected |
+| `alarm` | CO alarm active |
+
+### `alarmState.battery.deviceState`
+| Value | Description |
+|-------|-------------|
+| `good` | Battery healthy |
+| `low` | Battery low (assumed) |
+
+### `alarmState.power.deviceState`
+| Value | Description |
+|-------|-------------|
+| `ac` | Running on AC power |
+| `battery` | Running on battery (assumed) |
+
+### `alarmState.malfunction.deviceState`
+| Value | Description |
+|-------|-------------|
+| `none` | No malfunction |
+| (other) | Device malfunction |
+
+### `alarmState.silence.deviceState`
+| Value | Description |
+|-------|-------------|
+| `not_silenced` | Alarm not silenced |
+| `silenced` | Alarm temporarily silenced (assumed) |
+
+### `alarmState.eol.deviceState`
+| Value | Description |
+|-------|-------------|
+| `no` | Not at end of life |
+| `yes` | End of life - replace device (assumed) |
+
+### `alarmState.test.deviceState`
+| Value | Description |
+|-------|-------------|
+| `idle` | Not in test mode |
+| `testing` | Test in progress (assumed) |
+
+---
+
+## Other Endpoints (Discovered)
+
+```http
+GET /ris-public-api/api/v1/geofence
+POST /ds-activity-feed-api/api/v1/app/events
+```
+
+---
+
+## Device Types
+
+| `globalDeviceType` | Description |
+|-------------------|-------------|
+| `Citadel_SC5` | First Alert Safe & Sound Smart Smoke/CO Alarm (SMCO600NVACA) |
+
+---
+
+## Home Assistant Integration Notes
+
+### Sensors to Expose
+
+1. **Binary Sensors:**
+   - Smoke Alarm (`alarmState.smoke.deviceState` != "idle")
+   - CO Alarm (`alarmState.co.deviceState` != "idle")
+   - Malfunction (`alarmState.malfunction.deviceState` != "none")
+   - Online Status (`isOnline`)
+
+2. **Sensors:**
+   - Battery Status (`alarmState.battery.deviceState`)
+   - Power Source (`alarmState.power.deviceState`)
+   - WiFi Signal Strength (`deviceStatus.rssi`)
+   - Last Message Time (`lastMessageReceivedTime`)
+
+3. **Diagnostic Sensors:**
+   - Firmware versions
+   - End of Life status
+   - Various fault flags
+
+### Polling Interval
+
+Recommend polling every 30-60 seconds. The device reports timestamps in `tStampEpoch` format.
+
+### OAuth Flow for Home Assistant
+
+For Home Assistant, you'll need to implement the full OAuth PKCE flow:
+1. Generate code_verifier and code_challenge
+2. Open browser to authorization URL
+3. Handle callback with authorization code
+4. Exchange code for tokens
+5. Store and refresh tokens as needed
+
+---
+
+## Example Python Client
+
+```python
+import requests
+
+class ResideoClient:
+    def __init__(self, refresh_token: str):
+        self.client_id = "SRmiA7CaYi1JgivDZdzzoZu4X5VBogGt"
+        self.refresh_token = refresh_token
+        self.access_token = None
+
+    def _refresh_access_token(self):
+        resp = requests.post(
+            "https://login.resideo.com/oauth/token",
+            json={
+                "grant_type": "refresh_token",
+                "refresh_token": self.refresh_token,
+                "client_id": self.client_id
+            }
+        )
+        data = resp.json()
+        self.access_token = data["access_token"]
+        return self.access_token
+
+    def _headers(self):
+        if not self.access_token:
+            self._refresh_access_token()
+        return {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json"
+        }
+
+    def get_accounts(self):
+        resp = requests.get(
+            "https://api.resideo.com/ris-public-api/api/v1/accounts",
+            headers=self._headers()
+        )
+        return resp.json()
+
+    def get_device_state(self, device_id: str):
+        resp = requests.get(
+            f"https://api.resideo.com/ris-public-api/api/v2/devices/smokeDetectors/{device_id}/state",
+            headers=self._headers()
+        )
+        return resp.json()
+
+# Usage
+client = ResideoClient(refresh_token="your_refresh_token")
+accounts = client.get_accounts()
+state = client.get_device_state("YOUR_DEVICE_ID")
+print(f"Smoke: {state['deviceState']['reported']['alarmState']['smoke']['deviceState']}")
+print(f"CO: {state['deviceState']['reported']['alarmState']['co']['deviceState']}")
+print(f"Battery: {state['deviceState']['reported']['alarmState']['battery']['deviceState']}")
+```