@linanw/homebridge-mijia-remote-camera 0.2.0 → 0.3.0

package/lib/ptz-control.mjs

@@ -0,0 +1,59 @@
+import { request as httpRequest } from 'node:http';
+
+const DIRECTIONS = ['up', 'down', 'left', 'right'];
+// This exact model's four directions and self-stopping single-step behavior were physically verified.
+const VERIFIED_MODELS = new Set(['chuangmi.camera.061a01']);
+const REASONS = new Set(['invalid_request', 'ptz_unsupported', 'ptz_unavailable', 'ptz_rejected', 'ptz_timeout', 'ptz_busy', 'query_cancelled']);
+const failure = reason => Object.assign(new Error(REASONS.has(reason) ? reason : 'ptz_unavailable'), {
+  reason: REASONS.has(reason) ? reason : 'ptz_unavailable',
+});
+export const validPtzDirection = value => DIRECTIONS.includes(value);
+export const ptzModelSupported = model => VERIFIED_MODELS.has(model);
+export function ptzCapabilities(model, available = false, supports = ptzModelSupported) {
+  const supported = supports(model) === true;
+  return { supported, available: available === true, directions: supported ? [...DIRECTIONS] : [],
+    relativeStep: supported, zoom: false, absolutePosition: false };
+}
+
+/** Authenticated loopback only. Public callers cannot provide endpoints, operation IDs, speed or duration. */
+export function requestPtzStep(control, direction, { signal, timeoutMs = 2600, request = httpRequest } = {}) {
+  if (!validPtzDirection(direction) || !Number.isInteger(control?.port) || control.port < 1024 || control.port > 65535
+    || typeof control?.token !== 'string' || !/^[a-f0-9]{64}$/.test(control.token)) return Promise.reject(failure('invalid_request'));
+  return new Promise((resolve, reject) => {
+    let child, response, timer, done = false, size = 0;
+    const chunks = [];
+    const finish = (error, value) => {
+      if (done) return; done = true; clearTimeout(timer); signal?.removeEventListener('abort', cancelled);
+      for (const chunk of chunks) chunk.fill(0);
+      error ? reject(error) : resolve(value);
+    };
+    const cancel = reason => { child?.destroy(); response?.destroy(); finish(failure(reason)); };
+    const cancelled = () => cancel('query_cancelled');
+    if (signal?.aborted) { finish(failure('query_cancelled')); return; }
+    try {
+      const body = JSON.stringify({ direction });
+      child = request({ hostname: '127.0.0.1', port: control.port, path: '/ptz/move', method: 'POST',
+        headers: { Authorization: `Bearer ${control.token}`, 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } }, incoming => {
+        response = incoming;
+        incoming.on('data', chunk => {
+          if (done) return;
+          size += chunk.length;
+          if (size > 2048) { cancel('ptz_unavailable'); return; }
+          chunks.push(chunk);
+        });
+        incoming.once('error', () => finish(failure('ptz_unavailable')));
+        incoming.once('end', () => {
+          let value;
+          try { value = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { finish(failure('ptz_unavailable')); return; }
+          if (incoming.statusCode !== 200) { finish(failure(value?.reason)); return; }
+          if (value?.accepted !== true || value.direction !== direction || value.movement !== 'step') { finish(failure('ptz_unavailable')); return; }
+          finish(null, { accepted: true, direction, movement: 'step' });
+        });
+      });
+      child.once('error', () => finish(failure('ptz_unavailable')));
+      signal?.addEventListener('abort', cancelled, { once: true });
+      timer = setTimeout(() => cancel('ptz_timeout'), Math.max(1, Math.min(3000, timeoutMs)));
+      child.end(body);
+    } catch { cancel('ptz_unavailable'); }
+  });
+}

package/lib/ptz.mjs

@@ -0,0 +1,56 @@
+const DIRECTIONS = ['up', 'down', 'left', 'right'];
+const LABELS = { up: '云台向上', down: '云台向下', left: '云台向左', right: '云台向右' };
+const SAFE_REASONS = new Set(['ptz_unsupported', 'ptz_unavailable', 'ptz_rejected', 'ptz_timeout', 'ptz_busy']);
+
+/** Optional Home app controls for a verified, finite camera direction step. */
+export async function configurePtz({ api, accessory, runtime, selection, log } = {}) {
+  let capabilities;
+  try { capabilities = await runtime.getPtzCapabilities(); } catch { return null; }
+  if (capabilities?.supported !== true || capabilities.relativeStep !== true
+    || !Array.isArray(capabilities.directions) || !DIRECTIONS.every(d => capabilities.directions.includes(d))) return null;
+  const expected = selection && { deviceId: selection.deviceId, homeId: selection.homeId, homeOwner: selection.homeOwner };
+  let closed = false, busy = false, lastFailure;
+  const services = [];
+  const hapError = reason => new api.hap.HapStatusError(reason === 'ptz_busy'
+    ? api.hap.HAPStatus.RESOURCE_BUSY : api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+  for (const direction of DIRECTIONS) {
+    const subtype = `mijia-ptz-${direction}`;
+    const service = accessory.getServiceById?.(api.hap.Service.Switch, subtype)
+      || accessory.addService(api.hap.Service.Switch, LABELS[direction], subtype);
+    services.push(service);
+    const on = service.getCharacteristic(api.hap.Characteristic.On);
+    service.updateCharacteristic(api.hap.Characteristic.On, false);
+    on.onGet(() => false);
+    on.onSet(async value => {
+      if (value === false || value === 0) return;
+      if (value !== true && value !== 1) throw hapError('ptz_rejected');
+      if (closed) throw hapError('ptz_unavailable');
+      if (busy) throw hapError('ptz_busy');
+      busy = true;
+      try {
+        if (expected) {
+          const current = await runtime.selected();
+          if (closed || !current || Object.keys(expected).some(k => expected[k] !== current[k]))
+            throw Object.assign(new Error('ptz_unavailable'), { reason: 'ptz_unavailable' });
+        }
+        if (closed) throw Object.assign(new Error('ptz_unavailable'), { reason: 'ptz_unavailable' });
+        const result = await runtime.movePtz(direction);
+        if (result?.accepted !== true || result.direction !== direction)
+          throw Object.assign(new Error('ptz_rejected'), { reason: 'ptz_rejected' });
+        lastFailure = undefined;
+      } catch (error) {
+        const reason = SAFE_REASONS.has(error?.reason) ? error.reason : 'ptz_unavailable';
+        if (!closed && lastFailure !== reason) { lastFailure = reason; log?.warn?.(`云台控制未完成（${reason}）。`); }
+        throw hapError(reason);
+      } finally {
+        busy = false;
+        setImmediate(() => { if (!closed) service.updateCharacteristic(api.hap.Characteristic.On, false); });
+      }
+    });
+  }
+  return { shutdown() {
+    if (closed) return;
+    closed = true;
+    for (const service of services) service.updateCharacteristic(api.hap.Characteristic.On, false);
+  } };
+}

package/lib/rpc.mjs

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 
-const METHODS = new Set(['status', 'homes', 'devices', 'select', 'pause', 'resume', 'auth.start', 'auth.status', 'auth.cancel', 'night.get', 'night.set', 'matter.pairing', 'matter.openWindow', 'matter.closeWindow']);
+const METHODS = new Set(['status', 'homes', 'devices', 'select', 'pause', 'resume', 'auth.start', 'auth.status', 'auth.cancel', 'night.get', 'night.set', 'ptz.capabilities', 'ptz.move', 'matter.pairing', 'matter.openWindow', 'matter.closeWindow']);
 const MAX_REQUEST = 32768;
 const MAX_RESPONSE = 1048576;
 const REASONS = new Set(['operation_failed', 'invalid_request', 'response_too_large', 'invalid_response', 'plugin_not_running',
@@ -17,6 +17,7 @@ const REASONS = new Set(['operation_failed', 'invalid_request', 'response_too_la
   'invalid_region', 'unsafe_url', 'network_error', 'request_timeout', 'unexpected_response', 'login_expired', 'login_cancelled',
   'login_not_approved', 'incomplete_session', 'credentials_write_failed', 'unknown_login',
   'night_vision_unsupported', 'night_vision_unavailable', 'night_vision_rejected', 'night_vision_not_applied', 'night_vision_timeout',
+  'ptz_unsupported', 'ptz_unavailable', 'ptz_rejected', 'ptz_timeout', 'ptz_busy',
   'matter_disabled', 'matter_not_ready', 'matter_start_failed', 'matter_port_in_use', 'matter_configuration_invalid',
   'matter_pairing_unavailable', 'matter_window_failed', 'matter_closed']);
 

package/lib/runtime-factory.mjs

@@ -56,7 +56,9 @@ export async function attachServices(runtime, auth, storagePath) {
       if (method === 'matter.pairing') return runtime.matterPairing?.() ?? Promise.reject(failure('matter_not_ready'));
       if (method === 'matter.openWindow') return runtime.matterOpenWindow?.() ?? Promise.reject(failure('matter_not_ready'));
       if (method === 'matter.closeWindow') return runtime.matterCloseWindow?.() ?? Promise.reject(failure('matter_not_ready'));
-      if (authorizing && ['homes', 'devices', 'select', 'resume', 'night.get', 'night.set'].includes(method)) throw failure('auth_in_progress');
+      if (authorizing && ['homes', 'devices', 'select', 'resume', 'night.get', 'night.set', 'ptz.capabilities', 'ptz.move'].includes(method)) throw failure('auth_in_progress');
+      if (method === 'ptz.capabilities') return runtime.getPtzCapabilities();
+      if (method === 'ptz.move') return runtime.movePtz(payload.direction);
       if (method === 'night.get') return runtime.getNightVision();
       if (method === 'night.set') return runtime.setNightVision(payload.mode);
       if (method === 'homes') return runtime.discoverHomes();

package/lib/runtime.mjs

@@ -6,6 +6,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { acquireRuntimeLock } from './process-lock.mjs';
+import { ptzCapabilities, ptzModelSupported, validPtzDirection, requestPtzStep } from './ptz-control.mjs';
 
 const REGIONS = new Set(['cn', 'ru', 'de', 'sg', 'us', 'i2']);
 const REASONS = new Set(['not_selected', 'starting', 'ready', 'stopped', 'retrying', 'connect_timeout',
@@ -14,7 +15,8 @@ const REASONS = new Set(['not_selected', 'starting', 'ready', 'stopped', 'retryi
   'device_pagination_incomplete', 'home_request_failed', 'home_request_rejected', 'discovery_failed',
   'backend_failed', 'connection_failed', 'no_video', 'port_in_use', 'runtime_in_use', 'runtime_closed',
   'runtime_unavailable', 'query_timeout', 'query_cancelled', 'invalid_backend_response', 'storage_failed',
-  'night_vision_unsupported', 'night_vision_unavailable', 'night_vision_rejected', 'night_vision_not_applied', 'night_vision_timeout']);
+  'night_vision_unsupported', 'night_vision_unavailable', 'night_vision_rejected', 'night_vision_not_applied', 'night_vision_timeout',
+  'ptz_unsupported', 'ptz_unavailable', 'ptz_rejected', 'ptz_timeout', 'ptz_busy']);
 REASONS.add('auth_in_progress');
 const TRANSIENT_CODES = new Set([0, 3, 4, 5, 6]);
 const STAGES = ['device_lookup', 'provisioning', 'relay_connect', 'authentication', 'waiting_video'];
@@ -82,7 +84,7 @@ async function terminate(child) {
 export class RuntimeManager extends EventEmitter {
   constructor({ storagePath, javaPath, jarPath, bridgePath, log, region = 'cn', quality = 1, enableAudio = true, enableTalkback = true, cloudControl,
     spawn = spawnProcess, choosePort = freePort, terminateProcess = terminate, retryDelays = [15000, 30000, 60000],
-    connectTimeoutMs = 180000, queryTimeoutMs = 90000 } = {}) {
+    connectTimeoutMs = 180000, queryTimeoutMs = 90000, ptzRequest = requestPtzStep, ptzSupported = ptzModelSupported } = {}) {
     super();
     if (![storagePath, javaPath, jarPath, bridgePath].every(value => typeof value === 'string' && value.length)) {
       throw new RuntimeError('runtime_unavailable');
@@ -101,6 +103,7 @@ export class RuntimeManager extends EventEmitter {
     this.audioInfo = null;
     this.audioSeenAt = null;
     this.cloudControl = cloudControl; this.controlRequests = new Set();
+    this.ptzRequest = ptzRequest; this.ptzSupported = ptzSupported; this.ptzControl = null; this.ptzBusy = false; this.lastPtzAt = null;
     this.spawn = spawn; this.choosePort = choosePort; this.terminateProcess = terminateProcess;
     this.retryDelays = retryDelays; this.connectTimeoutMs = connectTimeoutMs; this.queryTimeoutMs = queryTimeoutMs;
     this.state = 'idle'; this.reason = 'stopped'; this.ready = false; this.videoReceived = false;
@@ -176,7 +179,7 @@ export class RuntimeManager extends EventEmitter {
     if (state === 'retrying' || state === 'blocked') {
       this.lastFailure = this.reason; this.lastFailureAt = Date.now();
     }
-    if (extra.ready === false) { this.audioInfo = null; this.audioSeenAt = null; }
+    if (extra.ready === false) { this.audioInfo = null; this.audioSeenAt = null; this.ptzControl = null; }
     Object.assign(this, extra); this.emit('status', this.status());
   }
   audioSource() {
@@ -233,6 +236,48 @@ export class RuntimeManager extends EventEmitter {
     });
   }
   getNightVision() { return this._nightVision(); }
+  async getPtzCapabilities() {
+    if (this.closed) throw new RuntimeError('runtime_closed');
+    if (this.paused) throw new RuntimeError('auth_in_progress');
+    const selected = this.selected();
+    return ptzCapabilities(selected?.model, Boolean(selected && this.ready && this.child && this.ptzControl), this.ptzSupported);
+  }
+  async movePtz(direction) {
+    if (!validPtzDirection(direction)) throw new RuntimeError('invalid_request');
+    if (this.closed) throw new RuntimeError('runtime_closed');
+    if (this.paused) throw new RuntimeError('auth_in_progress');
+    const selected = this.selected();
+    if (!selected) throw new RuntimeError('not_selected');
+    if (!this.ptzSupported(selected.model)) throw new RuntimeError('ptz_unsupported');
+    if (!this.ready || !this.child || !this.ptzControl) throw new RuntimeError('ptz_unavailable');
+    if (this.ptzBusy || this.lastPtzAt !== null && Date.now() - this.lastPtzAt < 1800) throw new RuntimeError('ptz_busy');
+    const generation = this.generation, region = this.region, control = this.ptzControl, controller = new AbortController();
+    const valid = () => !this.closed && !this.paused && !controller.signal.aborted && this.generation === generation
+      && this.region === region && this.ptzControl === control
+      && ['homeId', 'homeOwner', 'deviceId', 'model', 'region'].every(key => this.selected()?.[key] === selected[key]);
+    let timer; this.ptzBusy = true; this.controlRequests.add(controller);
+    try {
+      const task = async () => {
+        if (!this.cloudControl?.context) throw new RuntimeError('ptz_unavailable');
+        await this.cloudControl.context(selected, region);
+        if (!valid()) throw new RuntimeError('query_cancelled');
+        this.lastPtzAt = Date.now();
+        return this.ptzRequest(control, direction, { signal: controller.signal });
+      };
+      const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => { controller.abort(); reject(new RuntimeError('ptz_timeout')); }, 3000);
+      });
+      const reply = await Promise.race([task(), timeout]);
+      if (!valid()) throw new RuntimeError('query_cancelled');
+      if (reply?.accepted !== true || reply.direction !== direction || reply.movement !== 'step') throw new RuntimeError('ptz_unavailable');
+      return { accepted: true, direction, movement: 'step' };
+    } catch (error) {
+      if (error?.reason === 'session_expired') this._renewControlSession();
+      if (error?.capabilityRequired === true && this.ready) this._refreshControlCapability(selected, region);
+      const reason = error?.reason?.startsWith('night_vision_') ? 'ptz_unavailable' : error?.reason;
+      throw new RuntimeError(REASONS.has(reason) ? reason : 'ptz_unavailable');
+    } finally { clearTimeout(timer); controller.abort(); this.controlRequests.delete(controller); this.ptzBusy = false; }
+  }
   setNightVision(mode) {
     if (!['on', 'off', 'auto'].includes(mode)) return Promise.reject(new RuntimeError('invalid_request'));
     return this._nightVision(mode);
@@ -407,6 +452,12 @@ export class RuntimeManager extends EventEmitter {
           if (value?.success === false) {
             eventFailure = REASONS.has(value.reason) ? value.reason : 'backend_failed';
             if (Number.isInteger(value.vendor) && value.vendor >= 0 && value.vendor <= 100) this.vendor = value.vendor;
+          } else if (value?.event === 'control_ready' && value.success === true
+            && Number.isInteger(value.controlPort) && value.controlPort >= 1024 && value.controlPort <= 65535
+            && typeof value.controlToken === 'string' && /^[a-f0-9]{64}$/.test(value.controlToken)) {
+            this.ptzControl = { port: value.controlPort, token: value.controlToken };
+          } else if (value?.event === 'control_unavailable' && value.success === true) {
+            this.ptzControl = null;
           } else if (value?.event === 'audio_ready' && value.success === true && this.enableAudio
             && Number.isInteger(value.audioPort) && value.audioPort >= 1024 && value.audioPort <= 65535
             && ['PCMA', 'OPUS'].includes(value.audioCodec) && [8000, 16000, 48000].includes(value.sampleRate)
@@ -490,6 +541,7 @@ export class RuntimeManager extends EventEmitter {
   }
   async stop() {
     this.wantRunning = false; this.generation++;
+    this.ptzControl = null;
     for (const controller of this.controlRequests) controller.abort();
     this.controlRequests.clear();
     clearTimeout(this.retryTimer); clearTimeout(this.bootTimer); this.retryTimer = null; this.bootTimer = null;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@linanw/homebridge-mijia-remote-camera",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@linanw/homebridge-mijia-remote-camera",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "cpu": [
         "x64"
       ],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linanw/homebridge-mijia-remote-camera",
   "displayName": "米家远程摄像头",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone Xiaomi remote camera plugin with HomeKit and experimental Matter camera streaming",
   "license": "MIT",
   "author": "linanw",