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

package/lib/matter-device.mjs

@@ -11,12 +11,14 @@ import { CameraAvStreamManagement } from '@matter/main/clusters/camera-av-stream
 import { WebRtcTransportRequestor } from '@matter/main/clusters/web-rtc-transport-requestor';
 import { Status, StatusResponseError, StreamUsage, VendorId, EndpointNumber } from '@matter/main/types';
 import { assertRemoteActor, hasRemoteActor, NodeSession, Invoke, DeviceCommissioner } from '@matter/main/protocol';
+import { MatterPtzStepControl, MijiaPtzStepBehavior } from './matter-ptz-cluster.mjs';
 
 const LIVE = StreamUsage.LiveView;
 const NIGHT = ['off', 'on', 'auto'];
 const reject = (status, message) => { throw new StatusResponseError(message, status); };
 const bounded = (value, fallback, min, max) => Number.isFinite(Number(value))
   ? Math.min(max, Math.max(min, Math.round(Number(value)))) : fallback;
+const streamCapacity = value => Number.isInteger(value) && value >= 1 && value <= 4 ? value : 2;
 const text = (value, fallback, max = 32) => Array.from(String(value || fallback)).slice(0, max).join('');
 const samePeer = (a, b) => a.fabricIndex === b.fabricIndex && a.nodeId === b.nodeId;
 const clone = value => structuredClone(value);
@@ -28,8 +30,8 @@ function requireOwner(item, peer, kind) {
 
 /** Runtime resource accounting shared by all fabrics of one camera. Not persisted encoder state. */
 export class MatterCameraResources {
-  constructor(maxStreams = 1) {
-    this.maxStreams = maxStreams;
+  constructor(maxStreams = 2) {
+    this.maxStreams = streamCapacity(maxStreams);
     this.allocated = { video: new Map(), audio: new Map(), snapshot: new Map() };
     this.sessions = new Map();
     this.nextStream = 1;
@@ -75,7 +77,7 @@ export class MatterCameraResources {
     const id = this.nextSession;
     this.nextSession = this.nextSession % 65534 + 1;
     const item = { id, owner: { ...owner }, peerEndpointId, video, audio, state: 'connecting', pendingCandidates: [], ready: false,
-      mediaId: `${owner.fabricIndex}:${owner.nodeId}:${id}` };
+      pendingRemoteCandidates: [], mediaCreated: false, mediaId: `${owner.fabricIndex}:${owner.nodeId}:${id}` };
     this.sessions.set(id, item);
     for (const entry of [video, audio]) if (entry) entry.stream.referenceCount++;
     return item;
@@ -85,6 +87,8 @@ export class MatterCameraResources {
     if (this.sessions.get(item.id) !== item || item.ending) return false;
     item.ending = true;
     clearTimeout(item.timer);
+    item.pendingCandidates.length = 0;
+    item.pendingRemoteCandidates.length = 0;
     this.sessions.delete(item.id);
     for (const entry of [item.video, item.audio]) if (entry) entry.stream.referenceCount = Math.max(0, entry.stream.referenceCount - 1);
     return true;
@@ -136,6 +140,42 @@ export function validateMatterTransportRequest(request) {
     reject(Status.InvalidCommand, 'Requestor endpoint is required');
 }
 
+export function describeMatterSession(item) {
+  return { id: item.id, peerNodeId: item.owner.nodeId, peerEndpointId: item.peerEndpointId,
+    fabricIndex: item.owner.fabricIndex, streamUsage: LIVE, metadataEnabled: false,
+    videoStreamId: item.video?.stream.videoStreamId ?? null, audioStreamId: item.audio?.stream.audioStreamId ?? null,
+    ...(item.video ? { videoStreams: [item.video.stream.videoStreamId] } : {}),
+    ...(item.audio ? { audioStreams: [item.audio.stream.audioStreamId] } : {}) };
+}
+
+/** Keep external encoder accounting atomic with Matter's own cluster-state transaction. */
+export function enrollMatterSession({ resources, item, transaction, publish, start, afterRollback,
+  schedule = setImmediate }) {
+  let launchScheduled = false;
+  const rollback = () => { resources.detachSession(item); };
+  try {
+    transaction.addParticipants({
+      toString: () => `camera-session-create#${item.id}`,
+      rollback,
+      conclusion(outcome) {
+        if (outcome === 'committed' && !launchScheduled) {
+          launchScheduled = true;
+          schedule(() => { if (resources.sessions.get(item.id) === item && !item.ending) start(); });
+        } else if (outcome !== 'committed') {
+          rollback();
+          if (afterRollback) schedule(afterRollback);
+        }
+      },
+    });
+    publish();
+  } catch (error) {
+    rollback();
+    // The enclosing transaction also rolls back. Restore its view immediately when synchronous validation failed.
+    try { publish(); } catch {}
+    throw error;
+  }
+}
+
 /**
  * A real Matter Camera (0x0142), using the Matter 1.6.1 model in matter.js 0.18.
  * Matter carries authenticated signaling; media is encrypted WebRTC supplied by matter-media.
@@ -148,7 +188,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
   const height = bounded(config.height, 360, 120, 720) & ~1;
   const fps = bounded(config.frameRate, 12, 1, 30);
   const bitRate = bounded(config.bitRate, 800000, 64000, 2000000);
-  const maxStreams = bounded(config.maxStreams, 1, 1, 1);
+  const maxStreams = streamCapacity(config.maxStreams);
   const audioEnabled = config.enableAudio !== false;
   const speakerEnabled = config.enableTalkback === true;
   const nightEnabled = config.nightVision === true && typeof runtime?.setNightVision === 'function';
@@ -174,6 +214,9 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
   const resources = new MatterCameraResources(maxStreams), { allocated, sessions } = resources;
   let server, endpoint, closed = false, cachedCommissioned = false,
     nextControl = 1, lastError, applyingNightMode = false;
+  const ptz = new MatterPtzStepControl({ runtime, onChange: state => {
+    if (endpoint && !closed) return endpoint.set({ mijiaPtzStep: state });
+  } });
   const features = ['Video', 'Audio', 'Snapshot', ...(speakerEnabled ? ['Speaker'] : []), ...(nightEnabled ? ['NightVision'] : [])];
   const dimensions = { width, height };
   const snapshotCapabilities = [{ resolution: dimensions, maxFrameRate: 1, imageCodec: 0,
@@ -206,11 +249,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
   }
   function streamList(kind) { return [...allocated[kind].values()].map(item => clone(item.stream)); }
   function describeSession(item) {
-    return { id: item.id, peerNodeId: item.owner.nodeId, peerEndpointId: item.peerEndpointId,
-      fabricIndex: item.owner.fabricIndex, streamUsage: LIVE, metadataEnabled: false,
-      videoStreamId: item.video?.stream.videoStreamId ?? null, audioStreamId: item.audio?.stream.audioStreamId ?? null,
-      videoStreams: item.video ? [item.video.stream.videoStreamId] : [],
-      audioStreams: item.audio ? [item.audio.stream.audioStreamId] : [] };
+    return describeMatterSession(item);
   }
   async function syncState() {
     if (!endpoint || closed) return;
@@ -251,6 +290,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
     if (notify) await invokeRequestor(item, 'end', { webRtcSessionId: item.id, reason }).catch(() => {});
   }
   function fail(item, code) {
+    if (sessions.get(item.id) !== item) return;
     lastError = code;
     void end(item, code === 'matter_session_timeout' ? 1 : 0, true);
   }
@@ -262,6 +302,15 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
     // The library default writes the passcode, manual pairing code and QR to the process log.
     initiateCommissioning() {}
   }
+  class MijiaPtzStepServer extends MijiaPtzStepBehavior {
+    // The external shared guard rejects simultaneous actors instead of queueing movement
+    // behind the cluster's state lock. Attribute publications use separate transactions.
+    static lockOnInvoke = false;
+    async moveStep({ direction }) {
+      actor(this);
+      await ptz.move(direction);
+    }
+  }
   class MijiaAvServer extends CameraAvStreamManagementServer.with(...features) {
     async initialize() {
       // Allocations hold runtime encoder resources and do not survive a process restart.
@@ -352,11 +401,13 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
       if (isOffer && (typeof request.sdp !== 'string' || request.sdp.length > 65535)) reject(Status.ConstraintError, 'Invalid SDP');
       const item = resources.openSession({ owner, peerEndpointId: request.originatingEndpointId, video, audio }), { id } = item;
       lastError = undefined;
-      this.state.currentSessions = [...sessions.values()].map(describeSession);
-      // Commit the response before sending the camera-initiated Requestor commands.
-      setImmediate(() => { void (async () => {
+      const startMedia = () => {
+        item.timer = setTimeout(() => fail(item, 'matter_session_timeout'), 30000);
+        item.timer.unref?.();
+        void (async () => {
         if (closed || !sessions.has(id)) return;
         await syncState();
+        if (closed || sessions.get(id) !== item || item.ending) return;
         const v = video?.stream, a = audio?.stream;
         const result = await media.createSession({ id: item.mediaId, ...(isOffer ? { offer: request.sdp } : {}),
           video: v ? { id: v.videoStreamId, codec: 'h264', width: Math.min(width, v.maxResolution.width),
@@ -365,13 +416,15 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
           audio: a ? { id: a.audioStreamId, codec: 'opus', sampleRate: 48000, channels: 1, bitRate: a.bitRate } : undefined,
           iceServers: request.iceServers, iceTransportPolicy: request.iceTransportPolicy || 'all',
           onCandidate(candidate) {
-            if (!candidate?.candidate || closed || !sessions.has(id)) return;
+            if (!candidate?.candidate || closed || sessions.get(id) !== item) return;
             const normalized = { candidate: candidate.candidate, sdpMid: candidate.sdpMid ?? null,
               sdpmLineIndex: candidate.sdpMLineIndex ?? candidate.sdpmLineIndex ?? null };
-            if (!item.ready) item.pendingCandidates.push(normalized);
-            else void invokeRequestor(item, 'iceCandidates', { webRtcSessionId: id, iceCandidates: [normalized] }).catch(() => fail(item, 'matter_signaling_failed'));
+            if (!item.ready) {
+              if (item.pendingCandidates.length < 128) item.pendingCandidates.push(normalized);
+            } else void invokeRequestor(item, 'iceCandidates', { webRtcSessionId: id, iceCandidates: [normalized] }).catch(() => fail(item, 'matter_signaling_failed'));
           },
           onState(state) {
+            if (closed || sessions.get(id) !== item || item.ending) return;
             item.state = state;
             if (state === 'connected') {
               clearTimeout(item.timer);
@@ -379,16 +432,22 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
               item.timer.unref?.();
             } else if (state === 'failed' || state === 'closed') void end(item, state === 'failed' ? 0 : 2, true);
           } });
-        if (!sessions.has(id) || closed) { await media.closeSession(item.mediaId); return; }
+        if (sessions.get(id) !== item || closed) { await media.closeSession(item.mediaId); return; }
+        item.mediaCreated = true;
+        while (item.pendingRemoteCandidates.length) await media.addCandidates(item.mediaId, item.pendingRemoteCandidates.splice(0, 32));
         const sdp = isOffer ? result.answer : result.offer;
         if (typeof sdp !== 'string' || !sdp.length) throw new Error('matter_signaling_failed');
         await invokeRequestor(item, isOffer ? 'answer' : 'offer', { webRtcSessionId: id, sdp });
         item.ready = true;
         if (item.pendingCandidates.length) await invokeRequestor(item, 'iceCandidates', {
           webRtcSessionId: id, iceCandidates: item.pendingCandidates.splice(0) });
-      })().catch(() => fail(item, 'matter_signaling_failed')); });
-      item.timer = setTimeout(() => fail(item, 'matter_session_timeout'), 30000);
-      item.timer.unref?.();
+        })().catch(() => fail(item, 'matter_signaling_failed'));
+      };
+      enrollMatterSession({ resources, item, transaction: this.context.transaction,
+        publish: () => { this.state.currentSessions = [...sessions.values()].map(describeSession); },
+        start: startMedia, afterRollback: () => {
+          void Promise.resolve(media.closeSession(item.mediaId)).catch(() => {}).then(() => syncState()).catch(() => {});
+        } });
       const response = { webRtcSessionId: id };
       if (!isOffer) response.deferredOffer = false;
       if ('videoStreamId' in request) response.videoStreamId = video?.stream.videoStreamId ?? null;
@@ -405,8 +464,13 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
     async provideIceCandidates({ webRtcSessionId, iceCandidates }) {
       const item = sessionFor(this, webRtcSessionId);
       if (!iceCandidates.length || iceCandidates.length > 32) reject(Status.ConstraintError, 'Invalid ICE candidates');
-      try { await media.addCandidates(item.mediaId, iceCandidates.map(candidate => ({ candidate: candidate.candidate,
-        sdpMid: candidate.sdpMid ?? undefined, sdpMLineIndex: candidate.sdpmLineIndex ?? undefined }))); }
+      const normalized = iceCandidates.map(candidate => ({ candidate: candidate.candidate,
+        sdpMid: candidate.sdpMid ?? undefined, sdpMLineIndex: candidate.sdpmLineIndex ?? undefined }));
+      if (!item.mediaCreated) {
+        if (item.pendingRemoteCandidates.length + normalized.length > 128) reject(Status.ResourceExhausted, 'Too many pending ICE candidates');
+        item.pendingRemoteCandidates.push(...normalized); return;
+      }
+      try { await media.addCandidates(item.mediaId, normalized); }
       catch { reject(Status.Failure, 'Invalid ICE candidate'); }
     }
     async endSession({ webRtcSessionId, reason }) {
@@ -425,14 +489,15 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
         ...(config.listeningAddressIpv6 ? { listeningAddressIpv6: config.listeningAddressIpv6 } : {}) },
       basicInformation: { vendorName: 'linanw', vendorId: VendorId(0xfff1), productName: 'Mijia Remote Camera',
         productId: 0x8001, nodeLabel: text(name, 'Mijia Camera'), serialNumber: text(serialNumber, identifier),
-        hardwareVersion: 1, softwareVersion: 200, softwareVersionString: '0.2.0' },
+        hardwareVersion: 1, softwareVersion: 300, softwareVersionString: '0.3.0' },
     });
     const audioCapabilities = { maxNumberOfChannels: 1, supportedCodecs: [0], supportedSampleRates: [48000], supportedBitDepths: [16] };
-    endpoint = new Endpoint(CameraDevice.with(MijiaAvServer, MijiaWebRtcServer, WebRtcTransportRequestorClient), {
+    endpoint = new Endpoint(CameraDevice.with(MijiaAvServer, MijiaWebRtcServer, WebRtcTransportRequestorClient, MijiaPtzStepServer), {
       id: 'camera', number: EndpointNumber(1),
+      mijiaPtzStep: ptz.state(),
       cameraAvStreamManagement: {
-        maxContentBufferSize: 1000000, maxNetworkBandwidth: 5000000, maxConcurrentEncoders: 1,
-        maxEncodedPixelRate: width * height * fps,
+        maxContentBufferSize: 1000000, maxNetworkBandwidth: 5000000 * maxStreams, maxConcurrentEncoders: maxStreams,
+        maxEncodedPixelRate: width * height * fps * maxStreams,
         supportedStreamUsages: [LIVE], streamUsagePriorities: [LIVE],
         videoSensorParams: { sensorWidth: width, sensorHeight: height, maxFps: fps },
         minViewportResolution: { width: 160, height: 120 }, currentFrameRate: fps,
@@ -458,6 +523,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
       })().catch(() => {});
     });
   } catch (error) {
+    ptz.close();
     await server?.close().catch(() => {});
     throw error;
   }
@@ -471,6 +537,7 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
     async start() {
       if (closed) throw new Error('matter_closed');
       await server.start();
+      await ptz.refresh();
       if (nightEnabled && typeof runtime?.getNightVision === 'function') {
         const value = await runtime.getNightVision().catch(() => undefined);
         if (value) await nightChanged(value);
@@ -506,8 +573,10 @@ export async function createMatterDevice({ storagePath, name, serialNumber, netw
       await Promise.allSettled([...sessions.values()].map(item => end(item, 5, true)));
       return this.status();
     },
+    refreshPtzCapabilities(options) { return ptz.refresh(options); },
     async close() {
       if (closed) return;
+      ptz.close();
       cachedCommissioned = !!server.state.commissioning?.commissioned;
       await Promise.allSettled([...sessions.values()].map(item => end(item, 2, true)));
       closed = true;

package/lib/matter-diagnostics.mjs

@@ -19,10 +19,13 @@ export function safeMatterStatus(value = {}) {
   const source = value.media;
   if (object(source)) {
     const media = {};
-    for (const key of ['sessions', 'failures', 'videoPackets', 'audioPackets', 'talkPackets', 'talkBytes']) {
+    for (const key of ['sessions', 'failures', 'videoPackets', 'audioPackets', 'talkPackets', 'talkBytes', 'activeSessions', 'maxSessions', 'activeSources', 'videoSources', 'audioSources', 'sourceJobs', 'sourceSockets']) {
       if (count(source[key])) media[key] = source[key];
     }
-    for (const key of ['active', 'microphoneMuted', 'speakerMuted']) if (typeof source[key] === 'boolean') media[key] = source[key];
+    for (const key of ['active', 'microphoneMuted', 'speakerMuted', 'talkbackActive']) if (typeof source[key] === 'boolean') media[key] = source[key];
+    for (const [key, allowed] of Object.entries({"lastFailure": ["negotiation_failed", "media_not_offered", "webrtc_timeout", "webrtc_failed", "webrtc_disconnected", "media_unavailable", "udp_error", "ffmpeg_unavailable", "ffmpeg_exit", "video_timeout"], "lastFailureStage": ["remote_description", "replace_video_track", "replace_audio_track", "create_answer", "create_offer", "local_description", "remote_answer"], "lastFailureType": ["Error", "TypeError", "RangeError", "OperationError", "InvalidStateError", "InvalidModificationError", "InvalidAccessError", "NotSupportedError", "SyntaxError", "AbortError"]})) {
+      if (allowed.includes(source[key])) media[key] = source[key];
+    }
     if (Object.keys(media).length) result.media = media;
   }
   return result;