@linanw/homebridge-mijia-remote-camera 0.2.1 → 0.4.0

package/backend/PtzControlServer.java

@@ -0,0 +1,223 @@
+package mijia.bridge;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import micam.miss.MissClient;
+import micam.miss.MissCrypto;
+
+import java.io.IOException;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.attribute.PosixFilePermissions;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.time.Duration;
+import java.util.Arrays;
+import java.util.HexFormat;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ThreadPoolExecutor;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/** Bounded single-step motor control on the existing encrypted MISS session. No startup movement. */
+final class PtzControlServer implements AutoCloseable {
+    private static final ObjectMapper JSON = new ObjectMapper()
+            .enable(com.fasterxml.jackson.core.JsonParser.Feature.STRICT_DUPLICATE_DETECTION)
+            .enable(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_TRAILING_TOKENS);
+    private static final int MOTOR_REQUEST = 0x112, MOTOR_RESPONSE = 0x113;
+    private static final Set<String> PROBE_MODELS = Set.of("chuangmi.camera.061a01");
+    // Physically verified on this exact model. One command is a finite step; no precise angle is implied.
+    private static final Map<String, Map<String, Integer>> PROFILES = Map.of("chuangmi.camera.061a01",
+            Map.of("left", 1, "right", 2, "up", 3, "down", 4));
+    private static final long COOLDOWN_NANOS = TimeUnit.MILLISECONDS.toNanos(1800);
+    interface Session {
+        void send(int command, String body);
+        MissClient.Response receive(Duration timeout);
+    }
+    private final Session session;
+    private final byte[] key;
+    private final String model, token;
+    private final Path descriptor;
+    private final HttpServer server;
+    private final ThreadPoolExecutor executor = new ThreadPoolExecutor(2, 2, 0, TimeUnit.SECONDS,
+            new ArrayBlockingQueue<>(2), runnable -> { Thread thread = new Thread(runnable, "mijia-ptz-http"); thread.setDaemon(true); return thread; });
+    private final ScheduledExecutorService deadlines = Executors.newSingleThreadScheduledExecutor(runnable -> {
+        Thread thread = new Thread(runnable, "mijia-ptz-deadlines"); thread.setDaemon(true); return thread;
+    });
+    private final AtomicBoolean busy = new AtomicBoolean();
+    private volatile boolean closed;
+    private volatile CompletableFuture<Map<String, Object>> pending;
+    private long lastCommand = Long.MIN_VALUE;
+    private Thread reader;
+
+    PtzControlServer(MissClient camera, byte[] key, String model, Path descriptor) throws IOException {
+        this(new Session() {
+            public void send(int command, String body) { camera.sendEncrypted(command, body); }
+            public MissClient.Response receive(Duration timeout) { return camera.awaitResponse(timeout); }
+        }, key, model, descriptor);
+    }
+    PtzControlServer(Session session, byte[] key, String model, Path descriptor) throws IOException {
+        if (session == null || key == null || key.length != 32 || model == null) throw new IOException("ptz_unavailable");
+        this.session = session; this.key = Arrays.copyOf(key, key.length); this.model = model; this.descriptor = descriptor;
+        byte[] random = new byte[32]; new SecureRandom().nextBytes(random); token = HexFormat.of().formatHex(random); Arrays.fill(random, (byte) 0);
+        server = HttpServer.create(new InetSocketAddress(InetAddress.getByName("127.0.0.1"), 0), 4);
+        server.setExecutor(executor); server.createContext("/", this::handle);
+    }
+    int port() { return server.getAddress().getPort(); }
+    String token() { return token; }
+    static boolean supported(String model) { return PROFILES.containsKey(model); }
+    void start() throws IOException {
+        reader = new Thread(this::readLoop, "mijia-ptz-commands"); reader.setDaemon(true); reader.start();
+        try { writeDescriptor(); server.start(); } catch (IOException | RuntimeException error) { close(); throw error; }
+    }
+    private void writeDescriptor() throws IOException {
+        if (descriptor == null) return;
+        Files.createDirectories(descriptor.getParent());
+        Files.setPosixFilePermissions(descriptor.getParent(), PosixFilePermissions.fromString("rwx------"));
+        Path temporary = descriptor.resolveSibling(".ptz-control-" + UUID.randomUUID() + ".tmp");
+        try {
+            Files.createFile(temporary, PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rw-------")));
+            JSON.writeValue(temporary.toFile(), Map.of("version", 1, "port", port(), "token", token, "model", model,
+                    "pid", ProcessHandle.current().pid(), "createdAt", System.currentTimeMillis()));
+            Files.move(temporary, descriptor, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);
+        } finally { Files.deleteIfExists(temporary); }
+    }
+    private void handle(HttpExchange exchange) throws IOException {
+        String host = exchange.getRequestHeaders().getFirst("Host"), authorization = exchange.getRequestHeaders().getFirst("Authorization");
+        if (closed || !exchange.getRemoteAddress().getAddress().isLoopbackAddress() || !("127.0.0.1:" + port()).equals(host)
+                || exchange.getRequestURI().getRawQuery() != null || exchange.getRequestHeaders().containsKey("Origin")
+                || authorization == null || !MessageDigest.isEqual(("Bearer " + token).getBytes(StandardCharsets.US_ASCII), authorization.getBytes(StandardCharsets.UTF_8))) {
+            respond(exchange, 403, Map.of("reason", "ptz_unavailable")); return;
+        }
+        String route = exchange.getRequestURI().getRawPath();
+        if (!exchange.getRequestMethod().equals("POST") || !(route.equals("/ptz/probe") || route.equals("/ptz/move"))) {
+            respond(exchange, 404, Map.of("reason", "invalid_request")); return;
+        }
+        int length;
+        try { length = Integer.parseInt(exchange.getRequestHeaders().getFirst("Content-Length")); }
+        catch (Exception error) { respond(exchange, 400, Map.of("reason", "invalid_request")); return; }
+        if (length < 2 || length > 128 || !"application/json".equals(exchange.getRequestHeaders().getFirst("Content-Type"))) {
+            respond(exchange, 400, Map.of("reason", "invalid_request")); return;
+        }
+        var timeout = deadlines.schedule(exchange::close, 3, TimeUnit.SECONDS);
+        try {
+            byte[] bytes = exchange.getRequestBody().readNBytes(length);
+            JsonNode payload;
+            try { payload = bytes.length == length ? JSON.readTree(bytes) : null; } finally { Arrays.fill(bytes, (byte) 0); }
+            if (payload == null || !payload.isObject() || payload.size() != 1) { respond(exchange, 400, Map.of("reason", "invalid_request")); return; }
+            int operation;
+            if (route.equals("/ptz/probe")) {
+                if (!PROBE_MODELS.contains(model) || !payload.path("operation").isIntegralNumber() || !payload.path("operation").canConvertToInt()) {
+                    respond(exchange, 400, Map.of("reason", "ptz_unsupported")); return;
+                }
+                operation = payload.path("operation").intValue();
+            } else {
+                String direction = payload.path("direction").asText("");
+                Map<String, Integer> profile = PROFILES.get(model);
+                if (profile == null) { respond(exchange, 409, Map.of("reason", "ptz_unsupported")); return; }
+                operation = profile.getOrDefault(direction, 0);
+            }
+            if (operation < 1 || operation > 4) { respond(exchange, 400, Map.of("reason", "invalid_request")); return; }
+            Map<String, Object> result = probeStep(operation);
+            if (route.equals("/ptz/move")) {
+                if (!Integer.valueOf(0).equals(result.get("ret"))) throw new ControlFailure("ptz_rejected");
+                result = Map.of("accepted", true, "direction", payload.path("direction").asText(), "movement", "step");
+            }
+            respond(exchange, 200, result);
+        } catch (ControlFailure error) { respond(exchange, error.reason.equals("ptz_busy") ? 429 : 503, Map.of("reason", error.reason)); }
+        catch (Exception error) { respond(exchange, 503, Map.of("reason", "ptz_unavailable")); }
+        finally { timeout.cancel(false); exchange.close(); }
+    }
+    Map<String, Object> probeStep(int operation) {
+        if (operation < 1 || operation > 4) throw new ControlFailure("invalid_request");
+        if (closed) throw new ControlFailure("ptz_unavailable");
+        if (!busy.compareAndSet(false, true)) throw new ControlFailure("ptz_busy");
+        CompletableFuture<Map<String, Object>> response = new CompletableFuture<>();
+        try {
+            synchronized (this) {
+                if (closed) throw new ControlFailure("ptz_unavailable");
+                long now = System.nanoTime();
+                if (lastCommand != Long.MIN_VALUE && now - lastCommand < COOLDOWN_NANOS) throw new ControlFailure("ptz_busy");
+                lastCommand = now; pending = response;
+                session.send(MOTOR_REQUEST, "{\"operation\":" + operation + "}");
+            }
+            try {
+                Map<String, Object> result = new LinkedHashMap<>(response.get(2, TimeUnit.SECONDS));
+                if (closed) throw new ControlFailure("ptz_unavailable");
+                result.put("sent", true); result.put("responded", true); result.put("operation", operation);
+                return result;
+            } catch (java.util.concurrent.TimeoutException timeout) { lastCommand = System.nanoTime(); throw new ControlFailure("ptz_timeout"); }
+            catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); throw new ControlFailure("ptz_unavailable"); }
+            catch (java.util.concurrent.ExecutionException error) { throw new ControlFailure("ptz_unavailable"); }
+        } finally { if (pending == response) pending = null; busy.set(false); }
+    }
+    private void readLoop() {
+        while (!closed) {
+            try {
+                MissClient.Response response = session.receive(Duration.ofMillis(100));
+                if (response == null) continue;
+                Map<String, Object> safe = motorResponse(response, key);
+                CompletableFuture<Map<String, Object>> waiter = pending;
+                if (safe != null && waiter != null) waiter.complete(safe);
+            } catch (RuntimeException ignored) {
+                try { Thread.sleep(20); } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return; }
+            }
+        }
+    }
+    static Map<String, Object> motorResponse(MissClient.Response response, byte[] key) {
+        if (response == null || response.command() != MissClient.CMD_ENCODED || response.body() == null || response.body().length > 4108) return null;
+        byte[] plain = null;
+        try {
+            int command = response.command();
+            if (command == MissClient.CMD_ENCODED) {
+                if (response.body().length < 12) return null;
+                plain = MissCrypto.decrypt(key, response.body());
+                if (plain.length < 4) return null;
+                command = ByteBuffer.wrap(plain).order(ByteOrder.BIG_ENDIAN).getInt();
+            } else plain = Arrays.copyOf(response.body(), response.body().length);
+            if (command != MOTOR_RESPONSE) return null;
+            int offset = response.command() == MissClient.CMD_ENCODED ? 4 : 0, length = plain.length - offset;
+            while (length > 0 && plain[offset + length - 1] == 0) --length;
+            JsonNode value = JSON.readTree(Arrays.copyOfRange(plain, offset, offset + length));
+            if (value == null || !value.isObject()) return null;
+            Map<String, Object> result = new LinkedHashMap<>();
+            for (String name : Set.of("ret", "angle", "elevation", "xAngle", "yAngle", "xStep", "yStep")) {
+                JsonNode number = value.get(name);
+                if (number != null && number.isIntegralNumber() && number.canConvertToInt() && Math.abs((long) number.intValue()) <= 36000)
+                    result.put(name, number.intValue());
+            }
+            return result.isEmpty() ? null : result;
+        } catch (Exception ignored) { return null; }
+        finally { if (plain != null) Arrays.fill(plain, (byte) 0); }
+    }
+    private static void respond(HttpExchange exchange, int status, Map<String, Object> value) throws IOException {
+        byte[] body = JSON.writeValueAsBytes(value);
+        exchange.getResponseHeaders().set("Content-Type", "application/json"); exchange.getResponseHeaders().set("Cache-Control", "no-store");
+        exchange.sendResponseHeaders(status, body.length);
+        try (var output = exchange.getResponseBody()) { output.write(body); } finally { Arrays.fill(body, (byte) 0); }
+    }
+    static final class ControlFailure extends RuntimeException { final String reason; ControlFailure(String reason) { super(reason); this.reason = reason; } }
+    @Override public synchronized void close() {
+        if (closed) return; closed = true;
+        CompletableFuture<Map<String, Object>> waiter = pending; if (waiter != null) waiter.completeExceptionally(new ControlFailure("ptz_unavailable"));
+        server.stop(0); executor.shutdownNow(); deadlines.shutdownNow(); if (reader != null) reader.interrupt(); Arrays.fill(key, (byte) 0);
+        if (descriptor != null) try {
+            JsonNode value = JSON.readTree(descriptor.toFile()); if (token.equals(value.path("token").asText())) Files.deleteIfExists(descriptor);
+        } catch (Exception ignored) { }
+    }
+}

package/config.schema.json

@@ -84,6 +84,11 @@
         "title": "在家庭中显示夜视开关",
         "default": true
       },
+      "enablePtzSwitches": {
+        "type": "boolean",
+        "title": "在家庭中显示四个云台方向开关",
+        "default": false
+      },
       "enableMatter": {
         "type": "boolean",
         "title": "启用 Matter 摄像头（开发设备）",
@@ -103,6 +108,14 @@
         "minLength": 1,
         "maxLength": 40,
         "pattern": "^[A-Za-z0-9_.:-]+$"
+      },
+      "matterMaxStreams": {
+        "type": "integer",
+        "title": "Matter 同时播放窗口数",
+        "description": "默认两个窗口可同时播放；相同画质共享转码，关闭一个窗口不会中断另一个。最多四路；不同画质会增加 CPU 用量。",
+        "default": 2,
+        "minimum": 1,
+        "maximum": 4
       }
     }
   }

package/docs/verification.md

@@ -0,0 +1,72 @@
+# Homebridge verification preparation
+
+Reviewed against the [current official criteria](https://github.com/homebridge/plugins/wiki/Verified-Plugins) on 2026-10-24. **This plugin has not been verified by the Homebridge team.** This document records preparation and remaining review points; it is not an approval or a guarantee that the request will be accepted.
+
+## Compatibility and distribution
+
+| Area | Declared scope |
+| --- | --- |
+| npm name | `@linanw/homebridge-mijia-remote-camera` |
+| Platform | Dynamic platform `MijiaRemoteCamera`; external native HAP camera; optional independently registered Matter camera |
+| Target release | 0.4.0; public npm and the GitHub release must match before requesting review |
+| Node.js | `^22.13.1 || ^24.0.0` |
+| Homebridge | `^1.11.4 || ^2.0.0`; current development dependency 2.4.0 |
+| OS / CPU | Linux x64 only; pinned local runtime contains glibc and musl variants |
+| Current device validation | One Xiaomi Smart Camera 3 Pro PTZ, CS2/vendor 4; other models are not promised |
+| Initial configuration | Homebridge Plugin Settings GUI; asynchronous local component import, official Xiaomi login, home and camera selection |
+| Runtime components | Existing, matching user-owned local components; no acquisition service, bundled vendor runtime, or automatic download |
+
+The current criteria specify the supported Node LTS lines, currently 22 and 24. They do not state a universal OS/CPU support requirement. **Linux x64 remains a material limitation for the reviewers to assess**, especially for Raspberry Pi and other ARM users. A successful npm installation without the local components does not provide working video.
+
+## Criteria and evidence to present
+
+| Official requirement | Implementation / review evidence |
+| --- | --- |
+| Dynamic platform and a distinct purpose | Registered platform with a single selected external camera; the comparison below explains the remote Xiaomi transport use case |
+| Public npm and GitHub source with Issues enabled | Public npm package and GitHub repository exist; the matching 0.4.0 source, npm release and GitHub release notes still need publication before submission |
+| Supported Node LTS, clean installation and no unconfigured startup | Node 22/24 public-source CI matrix; no platform instance or camera is created without configuration; clean tarball installation still needs final release verification |
+| No system-changing postinstall or TTY setup | No plugin lifecycle install scripts; local import and account setup are in Homebridge UI; CLI tools are optional |
+| Settings GUI | Schema plus protected custom settings page |
+| No analytics or tracking | No author-operated analytics service; Xiaomi account, cloud metadata and remote-camera services are necessary network dependencies |
+| Files confined to Homebridge storage | Private credentials, selection, local runtime and Matter identity under the instance storage directory; inspect clean-runtime writes during final review |
+| Errors handled by the plugin | Bounded public errors, caught background work and shutdown failures; source tests cover safe failure paths |
+
+The official [checker implementation](https://github.com/homebridge/plugins/blob/latest/src/plugin-checks/workspace/index.ts) also checks package metadata, dependency placement, configuration, repository/release availability and runtime behavior. `homebridge` is a development dependency; HAP is obtained from the host. HTTPS homepage/issues and both `supports-hap` and `supports-matter` describe the actual transports. A production `npm audit --omit=dev --json` on 2026-10-24 reported **0 vulnerabilities**. This local audit does not replace the Homebridge team's checks.
+
+## Distinction from related verified plugins
+
+The comparison uses the [official verified list](https://github.com/homebridge/plugins/blob/latest/verified-plugins.json) and the projects' own documentation. It explains a separate use case and does not claim broader feature coverage than those projects.
+
+| Project | Published capability and difference |
+| --- | --- |
+| [Camera FFmpeg](https://github.com/homebridge-plugins/homebridge-camera-ffmpeg) | Its configuration requires an FFmpeg input source, usually an existing camera URL. This plugin obtains the selected supported Xiaomi camera's remote P2P source through account/home selection instead of requiring the user to supply that URL. |
+| [camera.ui](https://github.com/SeydX/homebridge-camera-ui) | Its documentation targets cameras exposing RTSP and includes recording, HSV and motion features. This plugin targets the Xiaomi remote transport and does not implement HSV or recording. |
+| [homebridge-miot](https://github.com/merdok/homebridge-miot) | A broad Xiaomi MIOT device-control platform that explicitly lists a camera category. Its current [CameraAccessory](https://github.com/merdok/homebridge-miot/blob/main/lib/modules/camera/CameraAccessory.js) builds a power switch, while [CameraDevice](https://github.com/merdok/homebridge-miot/blob/main/lib/modules/camera/CameraDevice.js) monitors MIOT power/indicator/storage properties; those classes do not implement a HomeKit streaming delegate. Our request specifically adds the tested remote camera video/audio/talkback transport and scoped metadata, rather than claiming that homebridge-miot has no camera support. |
+
+A related [homebridge-xiaomi-go2rtc project](https://github.com/moguennouni/homebridge-xiaomi-go2rtc) now documents local Xiaomi camera streaming and controls, automatic go2rtc provisioning and broader server architectures. It was not present in the official verified list checked for this preparation. Its overlapping functionality must still be disclosed; acceptance of a distinct use case is the Homebridge team's decision.
+
+## Scope that must remain explicit
+
+- The npm package excludes micam, its native components, JRE and FFmpeg. The known local backend repository has no license, and the known FFmpeg build enables `nonfree`. No redistribution rights are asserted. See [third-party notices](../THIRD_PARTY_NOTICES.md).
+- The GUI importer accepts only already-held matching files inside Homebridge storage, verifies fixed hashes and preserves legal files. It solves terminal-free import; it does not solve lawful acquisition for a new user without components. Reviewers may regard that remaining setup limitation as blocking.
+- Mi Home metadata polls every 60 seconds. Confirmed owner-only edits cover the device name and moves to existing rooms of the same home; cloud-side name normalization can reject exact confirmation even for locally valid Unicode; the runtime must expose the validated write capability before editing is enabled. Shared homes are read-only. There is no room rename/create or cross-home move.
+- Apple Home's own name and room edits are not written back to Mi Home. Matter metadata uses a vendor interface and a 160-byte UTF-8 bound; controllers must explicitly support it. Neither of these features is a universal HomeKit/Matter room sync promise.
+- Matter remains an experimental development device using SDK test attestation. Homebridge verification, if granted, would not confer Matter product certification.
+
+## Validation and release checklist
+
+The CI workflow tests public-source behavior with Node 22.13.1, the current 22.x and 24.x releases against Homebridge 1.11.4 and 2.4.0. It runs `npm test` without proprietary runtime assets; codec-dependent HomeKit media and the full-runtime UI IPC fixture explicitly report skipped tests when their required components are absent. Java/vendor protocol fixtures and real AAC-ELD/media checks require the separately held components; execute those locally and report their results separately. The workflow must actually pass on the public repository before describing CI as passed.
+
+The final local full suite, with the held runtime and an independent Matter controller integration, passed on **Node 22.22.1 and Node 24.19.0 / Homebridge 2.4.0: 325 tests, 324 passed, 1 root-only ownership test skipped, 0 failed on each Node version**. Real-account validation changed a Chinese camera name and restored it, moved the camera between two existing rooms of its owned home and restored the original room, and independently read back each result. The original name/room and credentials were preserved at completion. An emoji-containing target was normalized by the cloud, correctly returned `metadata_not_applied`, and was restored; the plugin does not promise arbitrary cloud name characters or automatic rollback.
+
+A local isolated source copy with no `assets/`, using Node 22.22.1 and Homebridge 2.4.0, ran the unfiltered `npm test`: **325 tests, 295 passed, 30 explicitly skipped, 0 failed**. It reused installed public dependencies, so it is not evidence of a fresh registry installation or of all six CI combinations. The four affected native-media/UI test files also ran with the held runtime: **40 passed, 0 skipped**; without assets the same subset reported **35 passed, 5 skipped**. No real account writes were performed by these tests.
+
+- [ ] Publish the reviewed source to the intended public GitHub repository, enable Issues, and verify all package URLs resolve.
+- [x] Complete changed-value Chinese rename/restore and existing-room round-trip validation with independent reads, original values restored and credentials unchanged. Confirm exact readback rejects a cloud-normalized emoji result; run the final local suite on Node 22 and 24.
+- [ ] Run the public-source CI matrix and a clean packed-package install; inspect startup without configuration, stop/restart and network failure behavior.
+- [ ] Inspect the exact npm tarball and Git tree for credentials, imported assets, APK/DEX/decompiled code and third-party binaries. Only the project's own Java adapter JAR is intended for distribution.
+- [ ] Publish npm 0.4.0 and a matching GitHub release with release notes; ensure the default branch package version matches npm latest.
+- [ ] Refresh the production audit and official criteria/checker findings, then provide the limitations and comparison to the reviewers.
+- [ ] Submit the official verification request and address review feedback. Add a Verified badge only after the Homebridge team grants verification.
+
+The [official request form](https://github.com/homebridge/plugins/issues/new?template=1_verification-request.yml) requires the npm name, public repository and six Yes/No declarations. A roughly 100×100 PNG icon is optional and must respect licensing/trademarks. Include setup restrictions and test evidence in More Information. Use the [current template](https://github.com/homebridge/plugins/blob/latest/.github/ISSUE_TEMPLATE/1_verification-request.yml); repository transfer or a package scope change is not required for this request. The project team performs the review described in the [program documentation](https://github.com/homebridge/plugins#plugin-verification).