@rhizomatics/signalk-einklabel-plugin 1.3.0-beta1 → 1.3.0-beta10

package/dist/devices/bleBackend.d.ts

@@ -12,10 +12,38 @@ export interface BleBackend {
     connectGatt(address: string, timeoutMs: number): Promise<GattConnection>;
     waitForManufacturerData(address: string, manufacturerId: number, timeoutMs: number): Promise<Buffer | undefined>;
 }
+/**
+ * Wraps a connected `GattConnection` so the session as a whole - not just the connect step - can't
+ * hang forever. Starts a single timer when the connection opens; if `disconnect()` hasn't been
+ * called (i.e. the caller's `paint()` hasn't finished, successfully or not) by the time it fires,
+ * treats the session as stuck: calls `forceClose` (which must tear down the connection and, for a
+ * shared backend, release any claim on it) and fails every call still outstanding or made afterwards.
+ * `Promise.race`ing each call against that same failure - rather than just refusing new calls once
+ * killed - is what actually unblocks a caller `await`ing a hung `write()`/`discoverServices()`:
+ * forcing the underlying connection closed doesn't guarantee the hung call's own promise ever
+ * settles, so the caller needs a second, independent way to move on.
+ */
+export declare function withSessionWatchdog(conn: GattConnection, timeoutMs: number, forceClose: () => Promise<void>): GattConnection;
 export declare function nodeBleBackend(): BleBackend;
+/**
+ * Waits for the BLE Manager to know about `address` before a GATT connect is attempted against it -
+ * mirrors `getOrDiscoverDevice` in `bleDiscovery.ts`, which gives `nodeBleBackend` the same guarantee
+ * against BlueZ directly. Without this, a specifically-addressed device that the manager hasn't seen
+ * yet (e.g. this plugin's own `scanOnStart` is off and no other BLE plugin happens to be scanning)
+ * would sit on `bleApi.connectGATT()` until that call's own `timeoutMs` gives up, rather than the
+ * plugin quietly rediscovering it the way the direct-BlueZ backend already does.
+ */
+export declare function ensureDeviceVisible(bleApi: BLEApi, pluginId: string, address: string, timeoutMs: number): Promise<void>;
+/**
+ * Runs `fn` only once every earlier caller has finished, so paints to different devices never hold
+ * BLE Manager GATT slots at the same time. The server's local provider defaults to just a couple of
+ * slots shared with every other BLE plugin (e.g. Bluetti), so two concurrent connects can leave the
+ * second with none free - which the server reports as the misleading "No provider with GATT support
+ * can see <mac>".
+ */
+export declare function exclusiveBleManagerAccess<T>(fn: () => Promise<T>): Promise<T>;
 /**
  * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
- * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs` and disconnects in the
- * background if it eventually resolves after the caller has already given up.
+ * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
  */
 export declare function bleApiBackend(bleApi: BLEApi, pluginId: string): BleBackend;

package/dist/devices/bleBackend.js

@@ -1,10 +1,82 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSessionWatchdog = withSessionWatchdog;
 exports.nodeBleBackend = nodeBleBackend;
+exports.ensureDeviceVisible = ensureDeviceVisible;
+exports.exclusiveBleManagerAccess = exclusiveBleManagerAccess;
 exports.bleApiBackend = bleApiBackend;
+const pluginVersion_1 = require("../pluginVersion");
 const bleDiscovery_1 = require("./bleDiscovery");
 /** How long to wait for BlueZ to have (or acquire) a `Device` object for the target address before giving up - a separate budget from the connect step itself, matching both drivers' previous hardcoded constant. */
 const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+/**
+ * Bounds the whole post-connect GATT session (service discovery, every read/write/notification a
+ * driver's `paint()` makes until it calls `disconnect()`), not just the connect step above - unlike
+ * `connectWithTimeout`/`bleApiBackend`'s connect race, neither backend's underlying `write()` or
+ * `discoverServices()` has any timeout of its own, so a hang there (plausible against a flaky real
+ * device) would otherwise sit forever with the connection, and any BLE Manager GATT claim, held open
+ * - see `withSessionWatchdog`. Generous relative to any single driver operation's own timeout (e.g.
+ * gicisky's 15s per-chunk ack) since it has to cover a whole multi-chunk image transfer, not one step
+ * of it; it's a last-resort backstop, not a normal-path budget.
+ */
+const GATT_SESSION_WATCHDOG_MS = 5 * 60000;
+/**
+ * Wraps a connected `GattConnection` so the session as a whole - not just the connect step - can't
+ * hang forever. Starts a single timer when the connection opens; if `disconnect()` hasn't been
+ * called (i.e. the caller's `paint()` hasn't finished, successfully or not) by the time it fires,
+ * treats the session as stuck: calls `forceClose` (which must tear down the connection and, for a
+ * shared backend, release any claim on it) and fails every call still outstanding or made afterwards.
+ * `Promise.race`ing each call against that same failure - rather than just refusing new calls once
+ * killed - is what actually unblocks a caller `await`ing a hung `write()`/`discoverServices()`:
+ * forcing the underlying connection closed doesn't guarantee the hung call's own promise ever
+ * settles, so the caller needs a second, independent way to move on.
+ */
+function withSessionWatchdog(conn, timeoutMs, forceClose) {
+    let killedError;
+    let resolveKilled;
+    const killed = new Promise((resolve) => {
+        resolveKilled = resolve;
+    });
+    let settled = false;
+    // `unref()` so this backstop timer never itself keeps the process alive (e.g. the CLI's `paint`
+    // command exiting naturally once its work is done) - it only ever needs to fire while something
+    // else is already keeping the event loop running anyway.
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        killedError = new Error(`GATT session watchdog fired after ${timeoutMs}ms with no completion - forcing disconnect`);
+        console.error(`${pluginVersion_1.PLUGIN_NAME}: ${killedError.message}`);
+        resolveKilled(killedError);
+        void forceClose().catch(() => { });
+    }, timeoutMs).unref();
+    function guard(op) {
+        if (killedError)
+            return Promise.reject(killedError);
+        const result = op();
+        result.catch(() => { }); // observed here too, so losing the race below never surfaces as an unhandled rejection
+        return Promise.race([result, killed.then((err) => Promise.reject(err))]);
+    }
+    return {
+        read: (serviceUuid, charUuid) => guard(() => conn.read(serviceUuid, charUuid)),
+        write: (serviceUuid, charUuid, data, withResponse) => guard(() => conn.write(serviceUuid, charUuid, data, withResponse)),
+        startNotifications: (serviceUuid, charUuid, callback) => guard(() => conn.startNotifications(serviceUuid, charUuid, callback)),
+        stopNotifications: (serviceUuid, charUuid) => guard(() => conn.stopNotifications(serviceUuid, charUuid)),
+        discoverServices: () => guard(() => conn.discoverServices()),
+        onDisconnect: conn.onDisconnect.bind(conn),
+        get connected() {
+            return conn.connected;
+        },
+        async disconnect() {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killedError)
+                return; // already forced closed by the watchdog above
+            await conn.disconnect();
+        },
+    };
+}
 function nodeBleBackend() {
     return {
         async connectGatt(address, timeoutMs) {
@@ -14,7 +86,14 @@ function nodeBleBackend() {
                 const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, address, DEVICE_DISCOVERY_TIMEOUT_MS);
                 await (0, bleDiscovery_1.connectWithTimeout)(device, timeoutMs);
                 const conn = (0, bleDiscovery_1.openNodeBleGattConnection)(device);
-                return {
+                let destroyed = false;
+                const destroyOnce = () => {
+                    if (destroyed)
+                        return;
+                    destroyed = true;
+                    destroy();
+                };
+                const gatt = {
                     read: conn.read.bind(conn),
                     write: conn.write.bind(conn),
                     startNotifications: conn.startNotifications.bind(conn),
@@ -25,10 +104,22 @@ function nodeBleBackend() {
                         return conn.connected;
                     },
                     async disconnect() {
-                        await conn.disconnect();
-                        destroy();
+                        try {
+                            await conn.disconnect();
+                        }
+                        finally {
+                            destroyOnce();
+                        }
                     },
                 };
+                return withSessionWatchdog(gatt, GATT_SESSION_WATCHDOG_MS, async () => {
+                    // `device.disconnect()` can hang for the same underlying reason the operations
+                    // `withSessionWatchdog` already guards can (see its doc comment) - race it briefly rather
+                    // than awaiting it unbounded here too, but tear down the D-Bus connection either way so
+                    // those resources don't leak even if BlueZ's disconnect itself never completes.
+                    await Promise.race([gatt.disconnect(), (0, bleDiscovery_1.sleep)(5000)]);
+                    destroyOnce();
+                });
             }
             catch (err) {
                 destroy();
@@ -48,10 +139,53 @@ function nodeBleBackend() {
         },
     };
 }
+/**
+ * Waits for the BLE Manager to know about `address` before a GATT connect is attempted against it -
+ * mirrors `getOrDiscoverDevice` in `bleDiscovery.ts`, which gives `nodeBleBackend` the same guarantee
+ * against BlueZ directly. Without this, a specifically-addressed device that the manager hasn't seen
+ * yet (e.g. this plugin's own `scanOnStart` is off and no other BLE plugin happens to be scanning)
+ * would sit on `bleApi.connectGATT()` until that call's own `timeoutMs` gives up, rather than the
+ * plugin quietly rediscovering it the way the direct-BlueZ backend already does.
+ */
+async function ensureDeviceVisible(bleApi, pluginId, address, timeoutMs) {
+    const known = await bleApi.getDevice(address).catch(() => null);
+    if (known)
+        return;
+    const seen = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            unsubscribe();
+            resolve(false);
+        }, timeoutMs);
+        const unsubscribe = bleApi.onAdvertisement(pluginId, (adv) => {
+            if (adv.mac !== address)
+                return;
+            clearTimeout(timer);
+            unsubscribe();
+            resolve(true);
+        });
+    });
+    if (!seen) {
+        throw new Error(`device ${address} isn't visible to the SignalK BLE Manager yet (out of range, asleep, or never seen) after waiting ${timeoutMs}ms`);
+    }
+}
+/** Upper bound on how long a timed-out `bleApi.connectGATT()` is given to settle server-side before a retry - see `bleApiBackend`. */
+const CONNECT_SETTLE_GRACE_MS = 30000;
+let bleManagerQueue = Promise.resolve();
+/**
+ * Runs `fn` only once every earlier caller has finished, so paints to different devices never hold
+ * BLE Manager GATT slots at the same time. The server's local provider defaults to just a couple of
+ * slots shared with every other BLE plugin (e.g. Bluetti), so two concurrent connects can leave the
+ * second with none free - which the server reports as the misleading "No provider with GATT support
+ * can see <mac>".
+ */
+function exclusiveBleManagerAccess(fn) {
+    const run = bleManagerQueue.then(fn, fn);
+    bleManagerQueue = run.catch(() => { });
+    return run;
+}
 /**
  * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
- * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs` and disconnects in the
- * background if it eventually resolves after the caller has already given up.
+ * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
  */
 function bleApiBackend(bleApi, pluginId) {
     return {
@@ -61,20 +195,58 @@ function bleApiBackend(bleApi, pluginId) {
             // "already claimed" until the server restarts - see signalk-bluetti-plugin's BleManagerDevice
             // for the same defensive call. A no-op if we don't currently hold the claim.
             await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            await ensureDeviceVisible(bleApi, pluginId, address, DEVICE_DISCOVERY_TIMEOUT_MS);
             const connecting = bleApi.connectGATT(address, pluginId);
             let timedOut = false;
             const conn = await Promise.race([connecting, (0, bleDiscovery_1.sleep)(timeoutMs).then(() => void (timedOut = true))]);
             if (timedOut || !conn) {
-                connecting.then((c) => c.disconnect()).catch(() => { });
+                // The server registers the claim as soon as `connectGATT()` is called, not once it succeeds -
+                // giving up here without releasing it would leave the claim (and, once/if the connect attempt
+                // does eventually land server-side, a live connection) orphaned indefinitely, since this
+                // plugin never gets a handle back to disconnect it itself. `releaseGATTDevice` tears down
+                // whatever the claim currently is, connected or still connecting, regardless of how the
+                // original `connectGATT()` promise eventually settles - disconnecting it too if it does still
+                // resolve afterwards, harmlessly, since a connection the server already released is a no-op to
+                // disconnect again. The release is awaited (only the late disconnect is left in the
+                // background) so a caller retrying straight away - `withRetries` - can't race it with a new
+                // `connectGATT()` and get rejected with "has a GATT claim in progress" for its trouble.
+                await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+                // ...except a claim still *connecting* isn't in the server's claim table yet, only its pending
+                // set, which `releaseGATTDevice` doesn't touch - so while the server's own connect is still in
+                // flight, a retry's `connectGATT()` is rejected outright with "has a GATT claim in progress".
+                // Give that connect a bounded chance to settle first, so the retry gets a clean slate.
+                const late = await Promise.race([
+                    connecting.catch(() => undefined),
+                    (0, bleDiscovery_1.sleep)(Math.min(timeoutMs, CONNECT_SETTLE_GRACE_MS)).then(() => undefined),
+                ]);
+                if (late) {
+                    await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), late.disconnect()]);
+                }
+                else {
+                    void connecting.then((c) => c.disconnect()).catch(() => { });
+                }
                 throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
             }
-            return conn;
+            return withSessionWatchdog(conn, GATT_SESSION_WATCHDOG_MS, async () => {
+                // Belt-and-suspenders, matching the timeout-cleanup above: `releaseGATTDevice` is the
+                // authoritative claim release, `disconnect()` a secondary teardown of this specific handle -
+                // do both regardless of which (if either) itself hangs or rejects.
+                await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), conn.disconnect()]);
+            });
         },
         async waitForManufacturerData(address, manufacturerId, timeoutMs) {
             // Unlike node-ble's `device.getManufacturerData()`, there's no cached-instant-read path here -
             // `BLEDeviceInfo` (from `getDevices()`/`getDevice()`) carries mac/name/rssi/seenBy but not
             // manufacturer data (see `BLEDeviceInfoSchema` in `@signalk/server-api`'s `ble-schemas.ts`) -
             // only the streamed `BLEAdvertisement` does. So this always actively waits on the stream.
+            //
+            // Same defensive release as `connectGatt`, and just as necessary here: a device the BLE Manager
+            // still thinks *we* hold a GATT claim on (e.g. from a crash/reload mid-paint, before this call
+            // ever reaches `connectGatt` below) stops advertising while claimed - which would otherwise wedge
+            // this wait forever, since nothing else in this path ever calls `connectGatt` (and so never gets a
+            // chance to release the stale claim) unless a fresh advertisement shows up first. A no-op if we
+            // don't currently hold the claim.
+            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
             return new Promise((resolve) => {
                 const timer = setTimeout(() => {
                     unsubscribe();

package/dist/devices/bleDiscovery.d.ts

@@ -34,9 +34,16 @@ export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertise
 /**
  * Retries `fn` up to `attempts` times (including the first try), returning on the first success -
  * shared by the repaint scheduler and the CLI's `paint` command so one flaky BLE connection
- * doesn't fail a whole repaint after a single bad attempt.
+ * doesn't fail a whole repaint after a single bad attempt. `delayMs` pauses between attempts, giving
+ * the adapter (and any BLE Manager claim the failed attempt held) a moment to settle rather than
+ * hitting the device again in the same tick. `onError` sees every failed attempt's error, not just the
+ * last one that's eventually thrown - an early attempt's error is often the real cause, with later
+ * ones just fallout from it.
  */
-export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>): Promise<T>;
+export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError }?: {
+    delayMs?: number;
+    onError?: (err: unknown, attempt: number) => void;
+}): Promise<T>;
 /**
  * Opens exactly one BLE discovery window and one D-Bus/BlueZ session, then hands the adapter to
  * `fn` - shared by `plugin.ts`'s startup scan and the CLI's `scan` command so scanning across

package/dist/devices/bleDiscovery.js

@@ -68,16 +68,25 @@ async function forEachAdvertisedDevice(adapter, fn) {
 /**
  * Retries `fn` up to `attempts` times (including the first try), returning on the first success -
  * shared by the repaint scheduler and the CLI's `paint` command so one flaky BLE connection
- * doesn't fail a whole repaint after a single bad attempt.
+ * doesn't fail a whole repaint after a single bad attempt. `delayMs` pauses between attempts, giving
+ * the adapter (and any BLE Manager claim the failed attempt held) a moment to settle rather than
+ * hitting the device again in the same tick. `onError` sees every failed attempt's error, not just the
+ * last one that's eventually thrown - an early attempt's error is often the real cause, with later
+ * ones just fallout from it.
  */
-async function withRetries(attempts, fn) {
+async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
+    const total = Math.max(1, attempts);
     let lastErr;
-    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt++) {
+    for (let attempt = 1; attempt <= total; attempt++) {
         try {
             return await fn(attempt);
         }
         catch (err) {
             lastErr = err;
+            onError?.(err, attempt);
+            if (attempt < total && delayMs > 0) {
+                await sleep(delayMs);
+            }
         }
     }
     throw lastErr;

package/dist/devices/discoveryCoordinator.d.ts

@@ -18,3 +18,21 @@ export declare function scanInProgressSince(): number | undefined;
  * one, which would make both fail.
  */
 export declare function ensureScan(app: ServerAPI, durationSeconds: number, useBleApi: boolean): Promise<ScanResult>;
+/**
+ * Keeps the "Device" picker (and `ALL_DEVICES`) current for as long as the plugin runs, without any
+ * bounded "scan" step at all - unlike `runScanViaBleApi`/`runScanViaBlueZ` above, which only ever look
+ * for new devices during an explicit, timed window (`scanOnStart`, or an on-demand `ALL_DEVICES` scan).
+ * BLE Manager already runs its own continuous scan server-side to build the device list the admin UI's
+ * "BLE Manager" page shows - a device that's visible there but never appears in *this* plugin's own
+ * picker unless `scanOnStart` happens to be ticked is exactly that mismatch: nothing was ever listening
+ * for BLE Manager's advertisements outside a bounded window. This instead subscribes once, for good,
+ * so a device shows up here as soon as BLE Manager itself has seen it - no manual scan required.
+ *
+ * Only runs a genuinely new (or long-expired, see `DISCOVERED_DEVICE_TTL_MS`) address through
+ * `driver.identifyDevice()` - a real GATT connect+read. A device already in the persisted store just
+ * gets `lastSeenAt` bumped via `touchDiscoveredDevice`, since re-identifying it on every ~1s
+ * advertisement would otherwise hammer it (and the shared GATT slots) for no reason. `pending` guards
+ * against two advertisements for the same brand-new device starting a second identify attempt while
+ * the first is still connecting.
+ */
+export declare function startBleApiDiscoveryListener(app: ServerAPI, pluginId: string): () => void;

package/dist/devices/discoveryCoordinator.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanInProgressSince = scanInProgressSince;
 exports.ensureScan = ensureScan;
+exports.startBleApiDiscoveryListener = startBleApiDiscoveryListener;
 const bleDiscovery_1 = require("./bleDiscovery");
 const bleBackend_1 = require("./bleBackend");
 const discoveredDevicesStore_1 = require("./discoveredDevicesStore");
@@ -67,43 +68,55 @@ async function runScanViaBlueZ(app, durationSeconds) {
     const merged = (0, discoveredDevicesStore_1.recordScanResults)(app, foundThisScan);
     return { foundThisScan, merged };
 }
+/**
+ * The `matchesAdvertisement`+`identifyDevice` half of processing one BLE Manager sighting - shared by
+ * `runScanViaBleApi`'s bounded scan and `startBleApiDiscoveryListener`'s indefinite one below. Doesn't
+ * decide *whether* to attempt identification (a bounded scan's own per-call `seen` set vs. the
+ * listener's persisted-store check need different answers to that) - just does the attempt and reports
+ * what it found, or `undefined` for "no matching driver"/"identify failed". `adv.manufacturerData`
+ * (from either an advertisement or, seeded, a `getDevices()` entry) is `Record<number, string>`
+ * (decimal company ID -> hex-encoded payload) rather than node-ble's `Buffer` - converted here so
+ * drivers never see the difference.
+ */
+async function identifyOne(app, backend, mac, name, rssi, manufacturerDataHex) {
+    const [manufacturerIdKey] = Object.keys(manufacturerDataHex ?? {});
+    const manufacturerId = manufacturerIdKey === undefined ? undefined : Number(manufacturerIdKey);
+    const manufacturerData = manufacturerId === undefined ? undefined : Buffer.from(manufacturerDataHex[manufacturerId], "hex");
+    const driver = (0, registry_1.allDrivers)().find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
+    if (!driver) {
+        return undefined;
+    }
+    const connect = () => backend.connectGatt(mac, SCAN_GATT_CONNECT_TIMEOUT_MS);
+    const found = await driver.identifyDevice({ address: mac, name, manufacturerId, manufacturerData, rssi }, connect).catch((err) => {
+        app.debug(`${driver.vendor} discovery failed for [${mac}]: ${err.message}\n${err.stack ?? ""}`);
+        return undefined;
+    });
+    if (found) {
+        const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, "0")}` : "unknown";
+        const hwid = found.hwVersion ?? "unknown";
+        app.debug(`discovered ${driver.vendor} device "${found.name ?? ""}" [${found.address}] pid=${pid} hwid=${hwid}`);
+    }
+    return found;
+}
 /**
  * Same as `runScanViaBlueZ` but sourced from the SignalK server's BLE Manager API instead of a direct
  * BlueZ discovery session - subscribes to the merged advertisement stream for `durationSeconds`,
  * seeded with whatever the server already knows about (mirrors `BleManagerScanner` in
- * signalk-bluetti-plugin). `app.bleApi.getDevices()`/advertisements don't carry manufacturer data
- * directly comparable to node-ble's `Buffer` - `adv.manufacturerData` is `Record<number, string>`
- * (decimal company ID -> hex-encoded payload), converted here so drivers never see the difference.
+ * signalk-bluetti-plugin).
  */
 async function runScanViaBleApi(app, durationSeconds) {
     const foundThisScan = [];
     const seen = new Set();
-    const drivers = (0, registry_1.allDrivers)();
     const backend = (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME);
     const identify = async (mac, name, rssi, manufacturerDataHex) => {
         if (seen.has(mac)) {
             return;
         }
-        const [manufacturerIdKey] = Object.keys(manufacturerDataHex ?? {});
-        const manufacturerId = manufacturerIdKey === undefined ? undefined : Number(manufacturerIdKey);
-        const manufacturerData = manufacturerId === undefined ? undefined : Buffer.from(manufacturerDataHex[manufacturerId], "hex");
-        const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
-        if (!driver) {
-            return;
-        }
         seen.add(mac);
-        const connect = () => backend.connectGatt(mac, SCAN_GATT_CONNECT_TIMEOUT_MS);
-        const found = await driver.identifyDevice({ address: mac, name, manufacturerId, manufacturerData, rssi }, connect).catch((err) => {
-            app.debug(`${driver.vendor} scan failed: ${err.message}\n${err.stack ?? ""}`);
-            return undefined;
-        });
-        if (!found) {
-            return;
+        const found = await identifyOne(app, backend, mac, name, rssi, manufacturerDataHex);
+        if (found) {
+            foundThisScan.push(found);
         }
-        foundThisScan.push(found);
-        const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, "0")}` : "unknown";
-        const hwid = found.hwVersion ?? "unknown";
-        app.debug(`discovered ${driver.vendor} device "${found.name ?? ""}" [${found.address}] pid=${pid} hwid=${hwid}`);
     };
     try {
         const unsubscribe = app.bleApi.onAdvertisement(pluginVersion_1.PLUGIN_NAME, (adv) => {
@@ -129,3 +142,57 @@ async function runScanViaBleApi(app, durationSeconds) {
     const merged = (0, discoveredDevicesStore_1.recordScanResults)(app, foundThisScan);
     return { foundThisScan, merged };
 }
+/**
+ * Keeps the "Device" picker (and `ALL_DEVICES`) current for as long as the plugin runs, without any
+ * bounded "scan" step at all - unlike `runScanViaBleApi`/`runScanViaBlueZ` above, which only ever look
+ * for new devices during an explicit, timed window (`scanOnStart`, or an on-demand `ALL_DEVICES` scan).
+ * BLE Manager already runs its own continuous scan server-side to build the device list the admin UI's
+ * "BLE Manager" page shows - a device that's visible there but never appears in *this* plugin's own
+ * picker unless `scanOnStart` happens to be ticked is exactly that mismatch: nothing was ever listening
+ * for BLE Manager's advertisements outside a bounded window. This instead subscribes once, for good,
+ * so a device shows up here as soon as BLE Manager itself has seen it - no manual scan required.
+ *
+ * Only runs a genuinely new (or long-expired, see `DISCOVERED_DEVICE_TTL_MS`) address through
+ * `driver.identifyDevice()` - a real GATT connect+read. A device already in the persisted store just
+ * gets `lastSeenAt` bumped via `touchDiscoveredDevice`, since re-identifying it on every ~1s
+ * advertisement would otherwise hammer it (and the shared GATT slots) for no reason. `pending` guards
+ * against two advertisements for the same brand-new device starting a second identify attempt while
+ * the first is still connecting.
+ */
+function startBleApiDiscoveryListener(app, pluginId) {
+    const backend = (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginId);
+    const pending = new Set();
+    const identify = async (mac, name, rssi, manufacturerDataHex) => {
+        const existing = (0, discoveredDevicesStore_1.loadDiscoveredDevices)(app)[mac];
+        if (existing) {
+            if (Date.now() - existing.lastSeenAt < discoveredDevicesStore_1.DISCOVERED_DEVICE_TTL_MS) {
+                (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, existing);
+                return;
+            }
+        }
+        if (pending.has(mac)) {
+            return;
+        }
+        pending.add(mac);
+        try {
+            const found = await identifyOne(app, backend, mac, name, rssi, manufacturerDataHex);
+            if (found) {
+                (0, discoveredDevicesStore_1.recordScanResults)(app, [found]);
+            }
+        }
+        finally {
+            pending.delete(mac);
+        }
+    };
+    const unsubscribe = app.bleApi.onAdvertisement(pluginId, (adv) => {
+        void identify(adv.mac, adv.name, adv.rssi, adv.manufacturerData);
+    });
+    // Seeds from whatever BLE Manager already knows about (e.g. a device it saw before this plugin
+    // subscribed) - same manufacturer-data caveat as `runScanViaBleApi`'s equivalent seed loop; a driver
+    // that needs it (rather than matching on name) picks it up once a fresh advertisement arrives above.
+    void app.bleApi
+        .getDevices()
+        .then((known) => Promise.all(known.map((device) => identify(device.mac, device.name, device.rssi, undefined))))
+        .catch((err) => app.debug(`discovery listener: could not read known devices: ${err.message}`));
+    return unsubscribe;
+}

package/dist/devices/gicisky/compression.d.ts

@@ -1,16 +1,29 @@
 /**
  * Wire framing for `packing: "chunked"` devices (the 7.5"/10.2" panels).
  *
- * The vendor firmware's real format supports each 64-byte chunk being either a `0x75`-tagged
- * QuickLZ-compressed block or a `0x74`-tagged raw one - see hass-gicisky's `gicisky_ble/compression.py`,
- * which ports a vendor-specific 64-bucket-hash variant of QuickLZ Level 1 to produce the smaller
- * `0x75` form. This driver always emits the `0x74` raw form instead: larger over the wire, but the
- * framing itself (chunk headers, the part1/part2 split) is unchanged, so a device that accepts
- * hass-gicisky's output accepts this too - it just costs more BLE writes per repaint than a real
- * compressor would.
+ * Each 64-byte chunk of a plane is sent either as a `0x75`-tagged QuickLZ-compressed block or a
+ * `0x74`-tagged raw one, whichever the compressor decides - a port of hass-gicisky's
+ * `gicisky_ble/compression.py`. That's QuickLZ Level 1, but with the vendor firmware's 6-bit
+ * (64-bucket) hash rather than stock QuickLZ's 12-bit one: match tokens carry a hash-table slot, not
+ * an offset, and the panel's decoder only ever fills 64 slots - a token naming a slot above that
+ * reads one that was never written and silently decodes garbage. So this must stay byte-compatible
+ * with the vendor's hash, not just any valid QuickLZ.
+ *
+ * One deliberate difference from hass-gicisky: `UNCONDITIONAL_MATCHLEN` is stock QuickLZ's 6, not
+ * its 12, so matches may start closer to a chunk's end. That's what the vendor's own app does - with
+ * 6 this reproduces 483 of the 486 distinct `0x75` chunks in Cabalist's BLE captures of the app
+ * (https://github.com/Cabalist/gicisky_image_notes) byte for byte, against 408 with 12. The other 3
+ * are chunks the app sends "compressed" despite them growing; this sends those raw (`0x74`) instead.
+ */
+/**
+ * QuickLZ L1 compression of one chunk, mirroring `_qlz_compress_core` step for step (including its
+ * quirks, e.g. the run-of-identical-bytes special case) so the output matches the vendor app's byte for
+ * byte. Returns `undefined` when compressing wouldn't save anything.
  */
+export declare function qlzCompressChunk(source: Buffer): Buffer | undefined;
 /**
  * Frames two equal-length bit-planes (e.g. BW and red) as `[4-byte LE length of planeB]` followed
- * by each plane's raw-chunked bytes, matching `compress()`'s output shape in the reference driver.
+ * by each plane's chunked bytes, matching `compress()`'s output shape in the reference driver.
+ * `compress: false` sends every chunk raw (`0x74`), like hass-gicisky's `force_raw`.
  */
-export declare function frameChunkedPlanes(planeA: Buffer, planeB: Buffer): Buffer;
+export declare function frameChunkedPlanes(planeA: Buffer, planeB: Buffer, compress?: boolean): Buffer;