@camstack/addon-provider-hikvision 0.1.1

package/README.md

@@ -0,0 +1,38 @@
+# @camstack/addon-provider-hikvision
+
+Hikvision ISAPI camera/NVR provider for CamStack. Speaks HTTP(S) ISAPI with HTTP Digest auth and hands RTSP URLs to the camstack stream-broker for video pull (no in-process video work).
+
+## v0.1 surface
+
+- **Connection**: ISAPI over HTTP or HTTPS, digest auth (RFC 7616, MD5+qop=auth). HTTPS uses `rejectUnauthorized: false` because Hikvision ships self-signed certs by default.
+- **Probe**: `/ISAPI/System/deviceInfo` — used by the Add-Device modal's Test button + by `onCreateDevice` to confirm the camera responds and persist the model/serial cache.
+- **Snapshot**: `/ISAPI/Streaming/channels/{id}/picture?snapShotImageType=JPEG` (registered as the `snapshot` native cap; the system snapshot wrapper handles caching + sleep gating on top).
+- **Reboot**: `/ISAPI/System/reboot` (registered as the `reboot` native cap).
+- **Stream discovery**: `/ISAPI/Streaming/channels` enumerates every (camera, slot) pair on single-camera devices and NVRs. Each enabled entry is published to the stream-broker as a `pull-rtsp` source (`rtsp://user:pass@host:554/Streaming/Channels/{id}?transportmode=unicast`).
+- **Alarm stream**: subscribes to `/ISAPI/Event/notification/alertStream`; the multipart parser emits `EventCategory.Motion` (with hysteresis: motion → inactive after 3s of silence) and `EventCategory.NativeDetection` (smart events: line-cross, region-entrance/exit, field-detection — class names normalised via `HIKVISION_AI_CLASS_MAP`).
+
+## v0.2 surface (added)
+
+- **PTZ** — `ptz` cap registered when `/PTZCtrl/channels/{id}/capabilities` reports any of pan / tilt / zoom. Methods: `move` (one-shot 500ms burst then auto-stop), `continuousMove`, `stop`, `getPresets` (`/presets`), `goToPreset` (`/presets/{id}/goto`), `goHome` (alias for preset id `1`). Speed range -100..+100 per axis as Hikvision documents; clamped on send.
+- **Supplemental light** — `switch` + `brightness` caps registered when `/Image/channels/{id}/supplementLight/capabilities` advertises any non-`close` mode. The "on" mode is picked deterministically: `colorVuWhiteLight` when present (newer ColorVu firmwares), else the first non-`close` mode. Brightness 0..100 — when the light is off, brightness writes are stashed and applied on the next `setState({on:true})`.
+- **Siren / alarm output** — `switch` cap registered when `/System/IO/inputs` lists at least one alarm input port. Defaults to port `1` (the typical built-in-siren GPIO). Note: the camera-side **Linkage Method** (Configuration → Event → Linkage Method) must be configured to fire the siren tone / strobe when the input flips — the API only toggles the input state. v0.2 limitation: when both supplemental light and siren are present, the supplemental light owns the `switch` cap; the siren registration logs and skips. Child accessory devices (one per cap) land in v0.3 to fix the collision.
+
+The probe runs once per camera lifetime (after the first successful `publishToBroker`); results are cached into `deviceCache.{hasPtz,hasSupplementalLight,hasAlarmIo}` so the next boot can short-circuit without re-probing. Cap registration itself is always re-done at runtime.
+
+## Deferred to v0.3+
+
+- **Child accessory devices** — model siren / supplemental light as separate child `IDevice` rows (parentDeviceId = camera) so the two switches don't have to share the parent's `switch` cap. Mirrors Reolink's `ReolinkAccessory` pattern.
+- **Two-way audio (intercom)** — `/ISAPI/System/TwoWayAudio/...` plus RTP relay; out of scope until camstack adds an intercom cap that other providers can also implement.
+- **AI thumbnail forwarding** — the alarm-stream parser sees `image/jpeg` parts that follow smart-detection events but discards them. Hook lands cleanly in `pumpAlarmStream` when consumers ask for it.
+- **PTZ position read-back** — `/PTZCtrl/channels/{id}/status` is firmware-dependent; today we return a stub `{0,0,0}` for `getPosition`.
+
+## Notes
+
+- **Channel id encoding**: Hikvision uses `{cameraNumber}{streamSlot}` — `101` = camera 1 / main, `102` = camera 1 / sub, `201` = camera 2 / main. Single-camera devices yield `native:main` / `native:sub` cam-stream ids; multi-channel NVRs yield `ch{N}-main` / `ch{N}-sub`.
+- **Old NVR fallback**: pre-2018 NVRs (DS-7600 series and similar) lack `/ISAPI/Streaming/channels`. The provider falls back to a synthetic `[101, 102]` channel set so video still publishes.
+- **Motion debounce**: Hikvision fires VMD events every ~1s while motion is active. The driver flips the `motion` cap to `detected: true` on the first event of a burst and waits 3s of silence before flipping back to `detected: false` — emitting both the activated and deactivated transitions on the event bus.
+
+## References
+
+- ISAPI Service v2 & v3 specs (Hikvision ISAPI doc package — vendor download).
+- Scrypted Hikvision plugin — `/Users/gianlucaruocco/Documents/Git/scrypted/plugins/hikvision/src/` (port reference for endpoint patterns + alarm-stream parsing).

package/assets/icon.svg

@@ -0,0 +1,6 @@
+<!-- Hikvision official wordmark — source: dashboard-icons (Bjorn Lammers, 2023, CC-BY).
+     Original viewBox is 0 0 1544 536 (very wide). Expanded vertically to 1544x1544
+     so the logo centers nicely inside the addon-icon square frame. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -504 1544 1544" baseProfile="tiny-ps" version="1.2">
+  <path fill-rule="evenodd" d="M614.42 535.16 810.93 2.95h159.61L774.47 535.16zM472.15 207.65 547.73 2.5h159.61L523.28 502.23s0 .45-.44.45c-7.56 18.69-25.35 31.59-46.69 32.04H351.23l93.8-254.54H255.19l-93.8 254.54H1.78L197.84 2.5h159.61l-75.58 205.15zM1424.02 2.5h119.15l-266.31 204.7 168.94 327.52h-135.6c.45 0 .89 0 1.34-.45-20.9 1.34-40.02-10.68-48.91-28.48 0 0 0-.44-.44-.44v.44l-105.81-205.58-40.02 30.7-75.13 204.25H881.62L1077.68 2.95h159.61l-73.8 199.8z" style="fill:#d71820"/>
+</svg>