homebridge-ring-hksv 14.3.1 → 14.3.3

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# homebridge-ring-hksv
+
+## Unreleased
+
+### Minor Changes
+
+- Add `homeKitAccessoryTag` to append a custom tag to Ring accessory names and generated HomeKit identities. This helps expose the same physical camera/accessory as a distinct HomeKit device for debugging or multi-home testing.
+
+## 14.3.2
+
+### Main Changes
+
+- [`b9dbe7e`](https://github.com/dgreif/ring/commit/b9dbe7e) Thanks [@dgreif](https://github.com/dgreif)! - This is the first version of homebridge-ring-hksv, which is a fork of homebridge-ring with support for HomeKit Secure Video (HKSV). 
+
 # homebridge-ring
 
 ## 14.3.0

package/README.md

@@ -10,7 +10,6 @@
 [![certified-hoobs-plugin](https://badgen.net/badge/HOOBS/Uncertified/yellow)](https://plugins.hoobs.org/plugin/homebridge-ring-hksv)
 [![Donate](https://badgen.net/badge/Donate/BuyMeACoffee/FFDD00)](https://buymeacoffee.com/trinityhades)
 
-# homebridge-ring-hksv
 
 `homebridge-ring-hksv` is a Homebridge platform plugin for Ring devices, with HomeKit Secure Video (HKSV) support.
 
@@ -18,40 +17,27 @@
 
 This project is based on Dustin Greif's original Ring Homebridge ecosystem:
 
-- Upstream plugin: `dgreif/homebridge-ring`
-- Upstream API library: `dgreif/ring-client-api`
+- Upstream plugin: [dgreif/homebridge-ring](https://github.com/dgreif/homebridge-ring)
+- Upstream API library: [dgreif/ring-client-api](https://github.com/dgreif/ring-client-api)
 
 Big thanks to Dustin and all upstream contributors. This fork reuses and extends that foundation.
 
-## What This Plugin Does
-
-This plugin integrates Ring locations and devices into HomeKit via Homebridge, including:
-
-- Ring cameras and doorbells
-- Ring Alarm devices and sensors
-- Ring chimes and intercoms
-- Ring Smart Lighting and supported alarm-connected devices
-- Thermostats, locks, outlets/switches, valves, and other supported accessory types
-
-It also introduces HKSV-focused controls such as:
-
-- `enableHksv`
-- `disableHksvOnBattery`
-- `hksvPrebufferLengthMs`
-- `hksvFragmentLengthMs`
-- `hksvMaxRecordingSeconds`
-
-## How This Fork Differs From Upstream
+## Important Plugin Options
 
-This fork is intended as a standalone package/repository with your own plugin identity and HKSV-focused iteration.
-
-In short:
-
-- Standalone plugin packaging
-- Custom branding/repository ownership
-- Additional HKSV recording controls exposed in config
-
-Core Ring platform behavior still relies on `ring-client-api`, so many upstream troubleshooting guides remain relevant.
+| Option | Purpose |
+| --- | --- |
+| `enableHksv` | Enables experimental HKSV support for eligible cameras |
+| `disableHksvOnBattery` | Disables HKSV on battery cameras to reduce battery/network usage |
+| `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
+| `hksvFragmentLengthMs` | HKSV fragment duration target |
+| `hksvMaxRecordingSeconds` | Optional safety cap for a recording session |
+| `homeKitAccessoryTag` | Appends a tag to accessory names and HomeKit IDs so the same Ring device can be exposed as a distinct HomeKit accessory for debugging/testing |
+| `cameraVideoCodec` | Preferred H.264 encoder (`h264_videotoolbox` or `libx264`) |
+| `hideDoorbellSwitch` / `hideCameraMotionSensor` / `hideCameraSirenSwitch` | Hides specific HomeKit-exposed services |
+| `showPanicButtons` | Adds panic switches (use with caution) |
+| `ffmpegPath` | Override FFmpeg binary path |
+| `debug` | Enables additional logging |
+| `disableLogs` | Disables plugin logging |
 
 ## Installation
 
@@ -76,36 +62,39 @@ Add a platform block with your Ring refresh token:
 
 ```json
 {
-  "platform": "RingHKSV",
+  "platform": "Homebridge Ring HKSV",
   "refreshToken": "your-refresh-token"
 }
 ```
 
-## Important Options
+If you need Home app to treat the same physical Ring device as a different HomeKit accessory, add a `homeKitAccessoryTag`:
 
-| Option | Purpose |
-| --- | --- |
-| `enableHksv` | Enables experimental HKSV support for eligible cameras |
-| `disableHksvOnBattery` | Disables HKSV on battery cameras to reduce battery/network usage |
-| `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
-| `hksvFragmentLengthMs` | HKSV fragment duration target |
-| `hksvMaxRecordingSeconds` | Optional safety cap for a recording session |
-| `cameraVideoCodec` | Preferred H.264 encoder (`h264_videotoolbox` or `libx264`) |
-| `hideDoorbellSwitch` / `hideCameraMotionSensor` / `hideCameraSirenSwitch` | Hides specific HomeKit-exposed services |
-| `showPanicButtons` | Adds panic switches (use with caution) |
-| `ffmpegPath` | Override FFmpeg binary path |
-| `debug` | Enables additional logging |
-| `disableLogs` | Disables plugin logging |
+```json
+{
+  "platform": "Homebridge Ring HKSV",
+  "refreshToken": "your-refresh-token",
+  "homeKitAccessoryTag": "Debug Home A"
+}
+```
+
+Changing `homeKitAccessoryTag` updates both the exposed accessory name and the generated HomeKit identity, which changes the advertised MAC-style identifier shown during manual camera pairing.
 
 ## HKSV Status
 
 HKSV support is experimental and actively evolving. Behavior may vary by camera model, wired vs battery power, Ring API changes, and FFmpeg environment.
 
+I currently am able to run 3 cameras with HKSV enabled on a Homebridge instance ran on a M4 Mac Mini 32GB of RAM.
+Please report your experience and setup details to help improve support.
+
+### Minimum specifications for HKSV: 
+[TBD - will be added as more users test and report their setups]
+
 ## Troubleshooting
 
 For support and debugging:
 
 - This repository issues: <https://github.com/trinityhades/homebridge-ring-hksv/issues>
+
 - Upstream Ring wiki (token/auth/camera references): <https://github.com/dgreif/ring/wiki>
 
 ## Disclaimer

package/config.schema.json

@@ -53,6 +53,11 @@
         "maximum": 300,
         "description": "Optional safety cap for a single HKSV recording stream duration."
       },
+      "homeKitAccessoryTag": {
+        "title": "HomeKit Accessory Tag",
+        "type": "string",
+        "description": "Optional tag appended to Ring accessory names and HomeKit identities. Change this to expose the same Ring devices as distinct accessories in Home app for debugging or multi-home testing."
+      },
       "cameraVideoCodec": {
         "title": "Camera Video Codec",
         "type": "string",
@@ -210,6 +215,7 @@
         "hksvPrebufferLengthMs",
         "hksvFragmentLengthMs",
         "hksvMaxRecordingSeconds",
+        "homeKitAccessoryTag",
         "cameraVideoCodec",
         "hideLightGroups",
         "hideDoorbellSwitch",

package/lib/ring-platform.js

@@ -155,7 +155,11 @@ export class RingPlatform {
         this.homebridgeAccessories[accessory.UUID] = accessory;
     }
     async connectToApi() {
-        const { api, config } = this, systemId = getSystemId(api.user.storagePath()), ringApi = new RingApi({
+        const { api, config } = this, systemId = getSystemId(api.user.storagePath()), configuredHomeKitAccessoryTag = config.homeKitAccessoryTag?.trim(), accessoryIdSuffix = configuredHomeKitAccessoryTag
+            ? `-${configuredHomeKitAccessoryTag}`
+            : '', accessoryNameSuffix = configuredHomeKitAccessoryTag
+            ? ` (${configuredHomeKitAccessoryTag})`
+            : '', ringApi = new RingApi({
             controlCenterDisplayName,
             ...config,
             systemId,
@@ -182,8 +186,9 @@ export class RingPlatform {
                     isCamera,
                     id: device.id.toString() +
                         cameraIdDifferentiator +
-                        cameraIdentitySalt,
-                    name: device.name,
+                        cameraIdentitySalt +
+                        accessoryIdSuffix,
+                    name: device.name + accessoryNameSuffix,
                     AccessoryClass,
                 };
             }), hideDeviceIds = config.hideDeviceIds || [], onlyDeviceTypes = config.onlyDeviceTypes?.length
@@ -194,8 +199,8 @@ export class RingPlatform {
                     deviceType: securityPanel.deviceType,
                     device: securityPanel,
                     isCamera: false,
-                    id: securityPanel.id.toString() + 'panic',
-                    name: 'Panic Buttons',
+                    id: securityPanel.id.toString() + 'panic' + accessoryIdSuffix,
+                    name: 'Panic Buttons' + accessoryNameSuffix,
                     AccessoryClass: PanicButtons,
                 });
             }
@@ -205,8 +210,8 @@ export class RingPlatform {
                     deviceType: 'location.mode',
                     device: location,
                     isCamera: false,
-                    id: location.id + 'mode',
-                    name: location.name + ' Mode',
+                    id: location.id + 'mode' + accessoryIdSuffix,
+                    name: location.name + ' Mode' + accessoryNameSuffix,
                     AccessoryClass: LocationModeSwitch,
                 });
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ring-hksv",
   "displayName": "Homebridge Ring HKSV",
-  "version": "14.3.1",
+  "version": "14.3.3",
   "description": "Homebridge plugin for Ring devices with HomeKit Secure Video support",
   "type": "module",
   "main": "lib/index.js",