@homebridge-plugins/homebridge-eufy-security 4.7.2 → 5.0.0-beta.0

package/.claude/docs/debug-recording-lessons.md

@@ -1,91 +0,0 @@
-# Debug Recording Pipeline — Lessons Learned (PRs #888–#894, 2026-03-26)
-
-Six PRs in one day to fix a feature that should have landed in one or two. Root causes were not understanding the FFmpeg process architecture, fixing symptoms instead of root causes, and not testing against real hardware before merging.
-
-## 1. Understand the P2P FFmpeg process architecture BEFORE touching it
-
-P2P cameras use SEPARATE FFmpeg processes for video and audio. The video process has only one input (raw H264 via TCP). There is no `input 1` for audio. Any `-map 1:a` on the video process will fail silently or crash.
-
-**Rule**: Before adding FFmpeg arguments, trace the FULL command that gets spawned. Check `ffmpeg-<serial>.log` in diagnostics. Verify what each input index maps to.
-
-**Why**: PRs #888, #890, #891 all tried to add audio to the video process file tee — impossible by architecture. Three PRs wasted.
-
-**How to apply**: When modifying `getCombinedArguments()` or `buildRawMuxArgs()`, always log or mentally construct the full FFmpeg command and verify each `-i` and `-map` index.
-
-## 2. Homebridge plugin UI runs in an iframe with strict CSP
-
-Homebridge enforces `frame-src 'self' data: https://developers.homebridge.io`. This means:
-- `data:` URIs work for downloads
-- `blob:` URLs are BLOCKED
-
-**Rule**: Never use `URL.createObjectURL()` / `blob:` for downloads in the plugin UI. Use the same `btoa()` + `data:` URI pattern as diagnostics download.
-
-**Why**: PR #893 switched to Blob URLs for "memory efficiency", immediately broke downloads. Had to revert.
-
-**How to apply**: When writing download logic in `homebridge-ui/`, copy the pattern from `diagnostics.js` `_downloadDiagnostics()`. Check CSP before changing.
-
-## 3. Destroy PassThrough forks when their consumer dies
-
-When piping a source stream to multiple PassThrough forks via `.pipe()`, if ANY fork's consumer dies (e.g., FFmpeg crashes) and the fork is not destroyed, it fills its internal buffer (16KB default) and applies permanent backpressure on the source — starving ALL other consumers.
-
-**Rule**: Always destroy PassThrough forks when their downstream consumer exits. Store references and destroy in cleanup handlers.
-
-**Why**: PR #888 created forks without cleanup. The bug was masked by 4MB highWaterMark in #890, exposed when removed in #891, finally fixed in #893.
-
-**How to apply**: Any time you create a `new PassThrough()` and pipe a shared source into it, ensure the fork is destroyed when its consumer (FFmpeg, socket, etc.) exits. Use both socket `close` handler AND session cleanup as belt-and-suspenders.
-
-## 4. FFmpeg ignores stdin when reading from TCP
-
-When FFmpeg reads input from a TCP socket (`-i tcp://...`), it is blocked in the socket read loop and does NOT monitor stdin. Writing `'q'` or `'q\n'` to stdin has no effect. The process will never exit gracefully via stdin.
-
-**Rule**: To stop FFmpeg reading from TCP, destroy the TCP socket. FFmpeg detects EOF and exits cleanly, finalizing the container.
-
-**Why**: PR #888 used `stdin.write('q')`, #893 added newline, neither worked. FFmpeg was always SIGKILL'd after timeout. PR #894 fixed it by destroying the socket.
-
-**How to apply**: In `stopSessionBySerial()`, destroy `session.videoSocket` and `session.audioSocket` instead of writing to stdin.
-
-## 5. P2P data is inherently bursty — never use wallclock timestamps
-
-`-use_wallclock_as_timestamps 1` assigns PTS based on when FFmpeg receives each frame. P2P delivers data in bursts at every level: initial buffer dump, ongoing video chunks (~1.3s gaps between bursts), and audio (entire ADTS batch arrives in one TCP write). Wallclock faithfully records these arrival times, producing choppy video and crushed audio (25s of audio crammed into 2ms of timestamps).
-
-Deferred piping (PR #891) only prevents the initial buffer dump. It does NOT make ongoing P2P delivery real-time.
-
-**Rule**: Never use `-use_wallclock_as_timestamps` for P2P recordings. Use `-fflags +genpts -r <fps>` for video (generates smooth PTS from declared framerate) and `-fflags +genpts` for audio (generates PTS from sample rate). The FPS comes from `metadata.videoFPS`.
-
-**Why**: PR #888 used wallclock -> burst -> 0.07s. PR #894 used wallclock + deferred piping -> choppy video (1.3s frame gaps) and silent audio (all timestamps within 2ms). PR #897 uses genpts + fps from metadata.
-
-**How to apply**: In `buildRawMuxArgs()`, use `-fflags +genpts -r <fps>` before each input. Deferred piping in `LocalLivestreamManager.onStationLivestreamStart` is still needed to prevent the initial buffer burst from skewing the generated PTS.
-
-## 6. The processed file tee copies raw INPUT, not encoded OUTPUT
-
-In FFmpeg multi-output, `-map 0:v -c:v copy` on a second output copies from INPUT 0 (raw P2P), not the encoded output of the first output. To capture the encoded stream, you'd need the `tee` muxer (blocked by SRTP params) or double encoding (wasteful).
-
-**Rule**: Don't use the file tee to capture "what HomeKit sees". It captures the raw P2P feed. For P2P cameras, use DebugRecordingManager instead (captures both video+audio). Keep the file tee only for RTSP cameras where DebugRecordingManager doesn't apply.
-
-**Why**: PRs #888-#891 assumed the file tee captured the encoded stream. It never did.
-
-## 7. HomeKit probes streams with a stop/restart cycle
-
-HomeKit sends startStream -> runs for 2-3s -> sends stopStream -> waits -> sends startStream again. This is normal probe behavior. If the file recording uses the P2P sessionId (which persists across HomeKit sessions), the second start overwrites the first file.
-
-**Rule**: For any per-HomeKit-session file recording, use `request.sessionID` (HomeKit's session ID), not the P2P livestream sessionId.
-
-**How to apply**: Relevant if the RTSP file tee is ever extended. Currently moot for P2P since the file tee was removed.
-
-## 8. Test against real hardware before merging
-
-Every PR #888-#893 was merged and found broken on the next beta. A single 15-second test (enable debug livestream -> stream camera -> check recording) would have caught most issues immediately.
-
-**Rule**: Before merging debug recording changes, the test plan MUST actually be executed. At minimum: enable feature, stream for 15s, ffprobe the output, check eufy-security.log for errors.
-
-**Why**: The ADTS crash (FFmpeg exit 255) was visible in the very first test. The 0.07s duration was visible in the first ffprobe. Six PRs could have been two.
-
-## 9. Fragmented MP4 breaks VLC and QuickTime
-
-`-movflags frag_keyframe+empty_moov` writes fragmented MP4 (fMP4) — designed for live streaming, not file playback. VLC shows ~1s of content then stops. QuickTime can't play it at all.
-
-**Rule**: Use `-movflags +faststart` for debug recordings written to disk. Standard MP4 with moov relocated to the start is universally playable.
-
-**Why**: PR #897 used fMP4 for crash resilience (already-written fragments survive SIGKILL). But graceful shutdown via socket destroy (lesson #4) makes this unnecessary. PR #898 switched to faststart.
-
-**How to apply**: Only use `frag_keyframe+empty_moov` when streaming to a non-seekable output (e.g., HTTP). For file output, always use `+faststart`.

package/.claude/docs/hksv-recording-fix.md

@@ -1,160 +0,0 @@
-# HKSV Recording Reliability Fix
-
-**PR:** [#878](https://github.com/homebridge-plugins/homebridge-eufy-security/pull/878)
-**Branch:** `fix/hksv-recording-reliability`
-**Affects:** All cameras with HomeKit Secure Video enabled
-
----
-
-## Problem
-
-HKSV recordings never appeared in the Apple Home timeline. Users could enable HKSV in Apple Home settings, but no recordings were captured on motion events. Two independent issues combined to make HKSV completely non-functional.
-
-## Root Cause 1: HKSV state lost on every restart
-
-### How HKSV state persistence works
-
-When a user enables HKSV for a camera in Apple Home:
-
-1. HomeKit sets the `Active` characteristic to `true` on the `CameraRecordingManagement` service
-2. HAP-NodeJS stores this in two places:
-   - The `cachedAccessories` JSON (service characteristic values)
-   - The `ControllerStorage` file (controller-specific state)
-3. On next boot, `CameraController._initWithServices()` restores services from cache
-4. `ControllerStorage.restoreController()` calls `deserialize()` to restore `recordingActive`
-
-### What was broken
-
-`CameraAccessory.configureVideoStream()` removed two controller-managed services (`CameraOperatingMode` and `DataStreamTransportManagement`) from the cached accessory before calling `configureController()`. This was added to prevent a "duplicate UUID error".
-
-However, this broke the restoration flow:
-
-```
-HAP-NodeJS CameraController._initWithServices():
-
-  IF all 3 services found in cache:
-    → Reuse cached services (preserves Active state) ✓
-
-  ELSE (any service missing):
-    → Create NEW services with Active=false ✗
-```
-
-By removing 2 of the 3 services, every restart forced the `ELSE` path, resetting `recordingActive` to `false`. HomeKit set `Active=true` once, but it was lost on every boot.
-
-### The fix
-
-Removed the stale service removal code entirely. HAP-NodeJS's `_initWithServices()` already handles service reuse through its `serializedControllers` path — the "duplicate UUID error" it was designed to prevent doesn't occur when services are properly managed by the controller.
-
-## Root Cause 2: P2P cold-start delay
-
-### The timing problem
-
-When HomeKit requests an HKSV recording after motion detection, the recording delegate must:
-
-1. Establish a P2P connection to the camera (`getLocalLiveStream()`)
-2. Start FFmpeg to transcode the stream
-3. Begin yielding fMP4 fragments to HomeKit
-
-Step 1 takes **~4.8 seconds** (observed in diagnostics). HomeKit has an approximate **5-second timeout** for the first data. This means recordings frequently failed to start in time.
-
-### How reference implementations solve this
-
-| Plugin | Approach | Prebuffer Duration |
-|--------|----------|--------------------|
-| homebridge-unifi-protect | Always-on RTSP timeshift buffer | Configurable |
-| Scrypted | Ring buffer, 2.5x HomeKit's prebufferLength | 10s default |
-| homebridge-camera-ui | Always-on prebuffer | 4s |
-
-All use prebuffering. For battery-powered Eufy cameras, always-on prebuffering is not viable.
-
-### The fix: motion-triggered P2P pre-warming
-
-When the plugin detects motion (before HomeKit even requests a recording), it proactively starts the P2P connection:
-
-```
-Motion Detected → Plugin sets MotionDetected=true on characteristic
-                → Plugin calls preWarmStream() (P2P starts in background)
-                → HomeKit receives motion notification
-                → HomeKit sends DATA_SEND OPEN → handleRecordingStreamRequest()
-                → getLocalLiveStream() returns instantly (P2P already warm)
-```
-
-A new `preWarmStream()` method on `LocalLivestreamManager` starts the P2P connection without creating a consumer fork. The stream auto-cleans up after the `STOP_GRACE_MS` (5 seconds) grace period if HomeKit doesn't request a recording.
-
-RTSP cameras are excluded from pre-warming since their stream URL is immediately available.
-
-## Additional fix: updateRecordingActive log bug
-
-`recordingDelegate.ts` line 282 had swapped log arguments:
-
-```typescript
-// Before (wrong — message as camera name, camera name as message):
-log.debug(`Recording: ${active}`, this.accessory.displayName);
-
-// After (correct):
-log.info(this.camera.getName(), `HKSV recording enabled/disabled by HomeKit.`);
-```
-
-This made HKSV state changes invisible in logs, making the root cause much harder to diagnose. Promoted to INFO level since this is a critical diagnostic signal.
-
-## HKSV Recording Flow (Architecture Reference)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     eufy-security-client                     │
-│  Device emits 'motion detected' / 'person detected' / etc.  │
-└──────────────────────────┬──────────────────────────────────┘
-                           │
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                    CameraAccessory.ts                         │
-│  1. characteristic.updateValue(true)  → HomeKit notified     │
-│  2. preWarmStream()                   → P2P starts warming   │
-└──────────────────────────┬───────────────────────────────────┘
-                           │
-              ┌────────────┴────────────┐
-              │                         │
-              ▼                         ▼
-┌──────────────────────┐   ┌─────────────────────────────────┐
-│  LocalLivestream     │   │  HAP-NodeJS RecordingManagement  │
-│  Manager.ts          │   │                                   │
-│  P2P connecting...   │   │  HomeKit receives MotionDetected  │
-│  Stream warming...   │   │  HomeKit decides to record        │
-│  ✓ Stream ready     │   │  DATA_SEND OPEN →                 │
-└──────────┬───────────┘   └───────────────┬───────────────────┘
-           │                               │
-           │                               ▼
-           │               ┌───────────────────────────────────┐
-           │               │  recordingDelegate.ts              │
-           │               │  handleRecordingStreamRequest()    │
-           └──────────────►│  configureInputSource()            │
-             P2P already   │    → getLocalLiveStream() instant  │
-             warm!         │  FFmpeg starts                     │
-                           │  yield fMP4 fragments → HomeKit    │
-                           └───────────────────────────────────┘
-```
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `src/accessories/CameraAccessory.ts` | Removed stale service removal; added motion-triggered pre-warming |
-| `src/controller/LocalLivestreamManager.ts` | Added `preWarmStream()` method; updated `isStreamActive()` |
-| `src/controller/recordingDelegate.ts` | Fixed `updateRecordingActive` log arguments |
-
-## User Impact
-
-### After upgrading
-
-Users who had HKSV enabled but never saw recordings should see them start working. Some users may need to:
-
-1. Restart Homebridge after the upgrade
-2. If recordings still don't appear, toggle HKSV off and on in Apple Home:
-   - Open Home app → Camera settings → Recording Options → Disable → Re-enable
-
-### Battery considerations
-
-The P2P pre-warming starts a livestream connection on every motion event. For battery-powered cameras:
-- The stream only runs for 5 seconds if HomeKit doesn't request a recording
-- This is similar to what already happens for snapshot fetching on motion
-- Impact on battery life should be minimal but is worth monitoring

package/.claude/skills/architect/SKILL.md

@@ -1,76 +0,0 @@
----
-name: architect
-description: Answer quick architectural questions, debug mini-issues, explore the codebase, and help improve skills and workflows. Use this skill when the user asks "how does X work", "where is Y", "why does Z happen", wants to understand code flow, trace a bug through the system, or asks about the relationship between components. Also use when the user wants to improve an existing skill or refine development workflows. This is the lightweight, exploratory counterpart to the planner -- use it for questions and small fixes, not multi-file changes.
----
-
-# Architect
-
-You are an architectural advisor for homebridge-eufy-security. You answer questions quickly, trace code paths, debug small issues, and help refine the development workflow. You are the "thinking" mode -- fast, focused, and precise.
-
-Refer to CLAUDE.md for the full architecture and project conventions.
-
-## What you do
-
-### Codebase exploration
-
-When the user asks "how does X work" or "where is Y":
-
-1. Search the codebase (Glob, Grep) to find the relevant code
-2. Read the key files
-3. Explain the flow concisely with file:line references
-4. Draw the path through the system if it crosses multiple files
-
-Quick-reference starting points:
-
-| Question | Start here |
-|---|---|
-| Device discovery? | `src/platform.ts` -- `onStationAdded`, `onDeviceAdded`, `register_device` |
-| Streaming? | `src/controller/streamingDelegate.ts` -> `LocalLivestreamManager.ts` |
-| HKSV recording? | `src/controller/recordingDelegate.ts` |
-| Snapshots? | `src/controller/snapshotDelegate.ts` |
-| UI <-> plugin? | `src/utils/accessoriesStore.ts` -> `homebridge-ui/server.js` |
-| Arm/disarm? | `src/accessories/StationAccessory.ts` |
-| Two-way audio? | `src/utils/Talkback.ts` |
-
-### Mini-bug debugging
-
-For small, contained bugs:
-
-1. Reproduce the understanding -- what's expected vs what happens?
-2. Trace the code path from trigger to symptom
-3. Identify the root cause with file:line reference
-4. If it's a one-line fix, suggest it directly
-5. If it's bigger, recommend using the planner skill
-
-### Skill and workflow improvement
-
-When the user wants to refine skills or workflows:
-
-1. Read the current skill/workflow file
-2. Identify what's working and what's not based on user feedback
-3. Suggest specific, minimal changes
-4. Apply changes after user approval
-
-### Quick code review
-
-When asked to review code or a diff:
-
-1. Focus on correctness, not style
-2. Check the architectural boundaries (plugin vs eufy-security-client)
-3. Flag potential issues with file:line references
-4. Don't nitpick -- only flag things that could break or confuse
-
-## How to respond
-
-- Be concise. Use file:line references.
-- Show the relevant code snippet when it helps understanding.
-- If the answer requires reading more than 3-4 files, use subagents for parallel exploration.
-- If the question turns into a multi-file change request, suggest switching to the planner skill.
-- If you're unsure, say so. Don't speculate about code you haven't read.
-
-## What you don't do
-
-- Don't make multi-file code changes (use planner -> developer)
-- Don't run builds or lint (use QA skill)
-- Don't create PRs or push code (use the git workflow directly)
-- Don't write lengthy essays -- keep answers tight and actionable

package/.claude/skills/developer/SKILL.md

@@ -1,59 +0,0 @@
----
-name: developer
-description: Execute code changes following an approved plan or direct user instructions. Use this skill when the user says "implement", "code it", "go ahead", "execute the plan", or when transitioning from the planner skill after approval. Also use for direct coding tasks where the user provides clear, specific instructions. This skill writes clean, correct code respecting all project conventions.
----
-
-# Developer
-
-You are a code execution agent for homebridge-eufy-security. You write code that is clean, correct, and follows every project convention. You either execute an approved plan from the planner skill, or implement direct user instructions.
-
-Follow all conventions in CLAUDE.md (ESM imports, lint, architecture patterns, code style, git workflow).
-
-## Before writing any code
-
-1. **Read first**: Read every file you intend to modify. Understand existing patterns before touching them.
-2. **Check the plan**: If a plan was approved, follow it exactly. If you spot an issue with the plan during implementation, stop and flag it -- don't silently deviate.
-3. **Branch check**: Verify you're on the correct branch per CLAUDE.md git workflow.
-
-## Implementation workflow
-
-### Step 1 -- Write the code
-
-Make changes file by file, following the plan order. For each file:
-- Use the Edit tool for modifications (not Bash with sed/awk)
-- Use Write only for new files
-- Keep changes minimal and focused
-- Don't add features beyond what was requested
-- Don't refactor surrounding code while fixing a bug
-
-### Step 2 -- Self-review
-
-After all changes are made, re-read each modified file to verify:
-- No syntax errors
-- Imports use `.js` extensions
-- No accidental duplicate code
-- Changes match the plan
-
-### Step 3 -- Verify
-
-```bash
-npm run lint
-npm run build
-```
-
-If either fails, fix the issue immediately. Do not commit code that doesn't lint or build.
-
-### Step 4 -- Commit
-
-Follow the git workflow from CLAUDE.md. Stage each logical change individually.
-
-## Chaining
-
-After committing, automatically invoke the **qa** skill to verify the changes before pushing. Do not wait for the user to ask -- QA is part of the development flow.
-
-## When things go wrong
-
-- **Lint failure**: Fix the warning. Don't disable the rule.
-- **Build failure**: Read the error. If it's a type error, trace it back. If it's an import error, check `.js` extensions.
-- **Plan doesn't work**: Stop. Explain what you found. Don't improvise a workaround without user approval.
-- **Unclear requirement**: Ask. Don't guess.

package/.claude/skills/new-device-support/SKILL.md

@@ -1,212 +0,0 @@
----
-name: new-device-support
-description: Full workflow to add support for a new Eufy Security device type (cameras, locks, sensors, and other devices) across eufy-security-client and homebridge-eufy-security. Covers exploration, implementation, build verification, and git/PR creation.
----
-
-# Add New Eufy Security Device Support
-
-You are adding support for a new device type to the eufy-security ecosystem. The user will provide a GitHub issue URL or device details (model name, model number like T86P2, device type number like 111). They may also provide raw device properties JSON.
-
-Use `$ARGUMENTS` for the issue URL or device details.
-
-## Phase 1 — Gather Information
-
-1. **Fetch the GitHub issue** (if URL provided) to extract: device name, model number (e.g. T86P2), device type number, raw properties JSON, firmware version, and any reference PRs. Note: users on recent eufy-security-client versions see a structured "unknown device" debug message that includes raw properties in a format directly usable with the mapping script.
-2. **Check for existing upstream work** — before starting, search for PRs that already add this device:
-   ```bash
-   gh pr list --repo bropat/eufy-security-client --state all --search "<model> OR <device-type-number>" --limit 10
-   ```
-   If a PR exists: review its diff to see what's already implemented, what's missing (e.g. missing GenericTypeProperty label, incomplete DeviceCommands), and whether it's merged, open, or stale. If merged, the device may only need homebridge-eufy-security side changes. If open but incomplete, coordinate with the PR author or build on their work. If the PR has review comments, check for flagged issues.
-3. **Pre-flight checks** — before proceeding, confirm you have:
-   - Device type number (required — cannot proceed without it)
-   - Raw device properties JSON (required for accurate property mapping — if missing, ask the user to enable debug logging and re-export diagnostics)
-   - Model number / display name (needed for enum naming and documentation)
-   - If the device type number is completely unknown (not in any existing code), investigate: check the model number prefix pattern, look at raw properties to infer capabilities (camera properties? lock properties? sensor properties?), and check Eufy's product pages for the model.
-4. **Run the pre-implementation audit**: Before writing any code, run the audit script to see what already exists:
-   ```bash
-   node homebridge-eufy-security/.claude/skills/new-device-support/check-device.mjs <type-number> [--pr-search <model>]
-   ```
-   This checks all 6 registration points in types.ts, classification methods in device.ts, device-images.js, finds the closest existing devices by property overlap, and searches upstream PRs. Use its output to understand the starting point.
-5. **Run the property mapping script**: Save the raw properties JSON to a temp file and run:
-   ```bash
-   node homebridge-eufy-security/.claude/skills/new-device-support/map-properties.mjs /tmp/<device>-raw-props.json --closest
-   ```
-   This maps each raw `param_type` to its `CommandType`/`ParamType` enum name, matching property constants, and which existing device types use them. It also outputs a suggested DeviceProperties block. The `--closest` flag ranks existing devices by property overlap to identify the best base device.
-6. **Ask the user** two questions:
-   - Image naming convention (check if images already exist or need renaming)
-   - Enum name for the DeviceType (e.g. `CAMERA_4G_S330`)
-
-## Phase 2 — Plan (use EnterPlanMode)
-
-Create a detailed plan covering all files that need changes. The plan must be based on the actual raw device properties — never guess which properties a device supports.
-
-### Determine device category
-
-Before planning file changes, identify the device category — this determines which classification methods and accessory classes apply:
-
-- **Camera** (including doorbells, floodlights, indoor cameras, solo cameras, 4G cameras): uses `CameraAccessory` in the plugin. Classification methods: `isCamera()`, and optionally `isDoorbell()`, `isFloodLight()`, `isIndoorCamera()`, `isPanAndTiltCamera()`, `isOutdoorPanAndTiltCamera()`, `isSoloCameras()`, etc. Note: `isSoloCameras()` is a composite method that includes outdoor PTZ, wall light cams, and other standalone camera types.
-- **WallLightCam**: uses `CameraAccessory`. Classification: `isWallLightCam()`. This category is heavily referenced in `station.ts` (50+ references) for livestream, talkback, property handling, and command routing — expect substantial `station.ts` changes.
-- **GarageCamera**: uses `CameraAccessory`. Classification: `isGarageCamera()`. Has dedicated property variants (e.g. `DeviceWatermarkGarageCameraProperty`, `DeviceMotionDetectionSensitivityGarageCameraProperty`). Also has `isGarageCameraBySn()` for serial number matching.
-- **Lock** (BLE, WiFi, WiFi Video variants): uses `LockAccessory`. Classification methods: `isLock()`, `isLockWifi()`, `isLockBle()`, `isLockWifiVideo()`, etc. Locks have many specialized type guard methods (e.g. `isLockWifiT8531()`, `isLockWifiR10()`) — check existing patterns carefully. Locks may require changes in **three additional layers** beyond this skill's primary scope — flag these to the user:
-  - `src/mqtt/` — MQTT protocol for lock communication
-  - `src/p2p/session.ts` — P2P session initialization uses `Device.isLockWifi()` and `Device.isLockWifiNoFinger()` for lock sequence generation
-  - `src/http/station.ts` — lock-specific routing at station level
-- **Sensor** (entry sensor, motion sensor, PIR sensor): uses `EntrySensorAccessory` or `MotionSensorAccessory`. Classification: `isSensor()`, `isEntrySensor()`, `isMotionSensor()`. Note: `isSensor()` is static-only — no public instance method exists.
-- **SmartDrop**: uses `SmartDropAccessory`. Classification: `isSmartDrop()`. Also has `isSmartDropBySn()` for serial number matching.
-- **SmartSafe**: no HomeKit accessory currently. Classification: `isSmartSafe()`.
-- **Tracker/SmartTrack**: no HomeKit accessory currently. Classification: `isSmartTrack()`.
-- **Keypad**: no HomeKit accessory currently. Classification: `isKeyPad()`.
-- **WaterFreezeSensor**: no HomeKit accessory currently. Classification: check for `WATER_FREEZE_SENSOR_*` in DeviceType enum.
-- **Siren**: no HomeKit accessory currently. Classification: check for `SIREN_SENSOR_*` in DeviceType enum.
-- **New category**: if the device doesn't fit any existing category, a new accessory class is needed in `src/accessories/`, a new classification method, and a new `if` block in `register_device()`. Flag this to the user — it's a significantly larger task.
-
-### Files to modify in eufy-security-client
-
-#### `src/http/types.ts` — 6 locations:
-
-1. **DeviceType enum**: Add `ENUM_NAME = <number>, //<model>` in numeric order
-2. **GenericTypeProperty `states` field**: Add `<number>: "<Display Name> (<Model>)"` inside the `states` object in numeric order. **WARNING**: This is one of the most commonly forgotten steps. Missing this label causes the device to display as a raw number in downstream UIs (see upstream PR #828 where 5 device types had missing labels).
-3. **DeviceProperties**: Add `[DeviceType.ENUM_NAME]` block. Always starts with `...GenericDeviceProperties`. Map each raw param_type to its corresponding `PropertyName.*` property constant. Base on the closest existing device but only include properties that match the raw data.
-4. **StationProperties**: Add `[DeviceType.ENUM_NAME]` block if device can act as its own station (solo cameras, integrated devices). Use `...BaseStationProperties` plus station-specific properties.
-5. **DeviceCommands**: Add `[DeviceType.ENUM_NAME]` array. Commands depend on device capabilities (livestream, talkback, pan/tilt, download, snooze, preset positions, calibrate, alarm).
-6. **StationCommands**: Add `[DeviceType.ENUM_NAME]` array if device has station properties. Typically `[CommandName.StationReboot, CommandName.StationTriggerAlarmSound]`.
-
-#### `src/http/device.ts` — Classification methods:
-
-Add the new device type to all applicable static classification methods. There are two kinds:
-
-**Broad classification methods** (add device to these as applicable):
-- `isCamera()` — if it's a camera/doorbell/floodlight
-- `hasBattery()` — if battery-powered (critical — omitting this means no battery service in HomeKit)
-- `isPanAndTiltCamera()` — if has PTZ
-- `isOutdoorPanAndTiltCamera()` — if outdoor PTZ (included by `isSoloCameras()`)
-- `isSoloCameras()` — composite method aggregating solo/standalone camera types
-- `isFloodLight()`, `isIndoorCamera()`, `isDoorbell()`, `isWallLightCam()`, `isGarageCamera()` — as applicable
-- `isLock()`, `isLockWifi()`, `isLockBle()`, `isLockWifiNoFinger()` — if it's a lock variant
-- `isSensor()`, `isEntrySensor()`, `isMotionSensor()` — if it's a sensor
-- `isSmartDrop()`, `isSmartSafe()`, `isSmartTrack()`, `isKeyPad()` — as applicable
-
-Note: Not all broad methods have public instance counterparts (e.g. `isSensor()` is static-only). Don't create instance methods where none exist for the pattern.
-
-**`isSupported()` check**: After adding to `DeviceProperties` map, `Device.isSupported(type)` automatically returns `true` (it checks `DeviceProperties[type] !== undefined`). This is the foundation of device registration — if `DeviceProperties` entry is missing, the device is silently unsupported regardless of all other registrations.
-
-Add a **new dedicated type guard method** (static + instance pair):
-```typescript
-static isNewDevice(type: number): boolean {
-  //<Model>
-  return DeviceType.ENUM_NAME == type;
-}
-
-public isNewDevice(): boolean {
-  return Device.isNewDevice(this.rawDevice.device_type);
-}
-```
-
-Update serial number checks if applicable (all are static-only, no instance methods):
-- `isIntegratedDeviceBySn()` — add `sn.startsWith("<model>")` if the device is integrated/standalone
-- `isSoloCameraBySn()` — add `sn.startsWith("<model>")` if it's a solo camera
-- `isSmartDropBySn()` — add if it's a SmartDrop variant
-- `isGarageCameraBySn()` — add if it's a garage camera variant
-- `isFloodlightBySn()` — add if it's a floodlight variant
-
-#### `src/http/station.ts`:
-
-- `isIntegratedDevice()` — if the device is standalone or can pair as its own station, it may already be covered by `isSoloCameras()`, `isFloodLight()`, etc. Only add explicit check if needed.
-
-#### `src/push/service.ts`:
-
-- If the device is 4G LTE or needs special push notification handling, expand the normalization block (line 768) to include the new type guard.
-
-#### `docs/supported_devices.md`:
-
-Add an entry in the correct table section:
-```markdown
-| ![<Model> image](_media/<image_small>.png) | <Display Name> (<Model>) | :wrench: | Firmware: <version> |
-```
-Use `:wrench:` for initial support.
-
-### Files to modify in homebridge-eufy-security
-
-#### `src/platform.ts` — `register_device()`:
-
-Verify the new device type is handled by `register_device()`. This method uses independent `if` blocks (not `else if`) to map device types to accessory classes. If the device is a camera, it falls through to the camera path. If it's a lock, sensor, or SmartDrop, it hits those specific checks. If it's a new category that doesn't match any existing check, the device won't get an accessory — flag this to the user.
-
-#### `homebridge-ui/public/utils/device-images.js`:
-
-Add a case in the `getImage()` switch:
-```javascript
-case <type_number>: return '<image_large>.png';
-```
-
-#### Image assets:
-
-- Rename or add images in `eufy-security-client/docs/_media/` (small + large)
-- Rename or add image in `homebridge-eufy-security/homebridge-ui/public/assets/devices/` (large only)
-
-## Phase 3 — Implement
-
-Execute the plan. Key implementation notes:
-
-- **Property mapping**: Use the output from `map-properties.mjs` (Phase 1) as the primary guide. Many property constants have large variant families (e.g. `DeviceMotionDetection*` has 40+ variants, `DeviceFloodlightLight*` has 12+, `DeviceVideoRecordingQuality*` has 11+). When multiple constants match the same `param_type`, pick the variant used by the closest existing device — check the "Used by DeviceTypes" column in the script output and the `--closest` flag results.
-- **Companion custom properties**: Some properties have required companions with `custom_*` keys that never appear in raw device data (they're populated at runtime). The script detects these and marks them with `⚠ companion`. Always include them — omitting a companion breaks functionality silently. Key pairs: `DeviceRTSPStream` → `DeviceRTSPStreamUrl`, `DeviceWifiRSSI` → `DeviceWifiSignalLevel`, `DeviceCellularRSSI` → `DeviceCellularSignalLevel`.
-- **Insert in order**: When adding to enums, switch statements, or `if` chains, maintain numeric ordering by device type number.
-- **Audio recording property**: Different device families use different audio recording property constants (e.g. `DeviceAudioRecordingProperty`, `DeviceAudioRecordingStarlight4gLTEProperty`). Match the closest existing device.
-
-### Registration verification checklist
-
-After implementing all changes, run the post-implementation verification script:
-```bash
-node homebridge-eufy-security/.claude/skills/new-device-support/verify-device.mjs <ENUM_NAME>
-```
-This automatically checks all required registration points and reports PASS/FAIL:
-
-1. `DeviceType` enum definition
-2. `GenericTypeProperty` states
-3. `DeviceProperties` map
-4. `DeviceCommands` map
-5. `StationProperties` map (if device acts as its own station — reported as WARN if missing)
-6. `StationCommands` map (if device has station properties — reported as WARN if missing)
-7. Dedicated type guard method (static + instance) in device.ts
-8. Broad classification methods (isCamera, isLock, etc.) in device.ts
-9. `docs/supported_devices.md` entry (reported as WARN if missing)
-10. `*BySn` serial number methods (reported as WARN if missing — not all devices need these)
-11. device-images.js case in homebridge-eufy-security
-
-The script exits with code 1 if any required checks fail. A device type that is defined in the enum but missing from DeviceProperties will silently fall back to GenericDeviceProperties with only ~3 basic properties (name, model, serial). This is the most common implementation error — see upstream issue #853 where LOCK_85V0 was added to the enum but never registered in the lookup maps.
-
-## Phase 4 — Build & Lint Verification
-
-Run build and lint for both repos. Note: eufy-security-client lint may fail due to a pre-existing `jiti` library issue unrelated to our changes — the TypeScript build succeeding is sufficient validation.
-
-## Phase 5 — Git & PR
-
-Follow CLAUDE.md Git Workflow for commit messages, branch naming, and PR body format. This skill creates **two PRs** across repos:
-
-### eufy-security-client (cross-fork)
-
-1. Discard unrelated changes (e.g. `package-lock.json`)
-2. Sync develop: `git fetch upstream && git checkout develop && git merge upstream/develop`
-3. Branch: `git checkout -b feat/<device-slug>`
-4. Stage only: images, `src/http/types.ts`, `src/http/device.ts`, `src/push/service.ts`, `docs/supported_devices.md`
-5. Cross-fork PR:
-   ```bash
-   gh pr create --repo bropat/eufy-security-client --base develop \
-     --head lenoxys:feat/<device-slug> \
-     --title "feat: add <Device Name> (<Model>, type <number>) support" \
-     --body-file /tmp/pr-body-<branch>.md
-   ```
-
-### homebridge-eufy-security
-
-1. Branch from current beta: `git checkout -b feat/<device-slug>`
-2. Stage: `homebridge-ui/public/utils/device-images.js` + any added image
-3. PR to current beta branch:
-   ```bash
-   gh pr create --base beta-<current-version> \
-     --title "feat: add <Device Name> (<Model>) image" \
-     --body-file /tmp/pr-body-<branch>.md
-   ```
-
-### Cross-referencing
-
-After both PRs are created, update both bodies so they reference each other.