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

package/dist/devices/bleDiscovery.d.ts

@@ -1,4 +1,5 @@
 import { Adapter, Bluetooth, Device } from "@naugehyde/node-ble";
+import { GattConnection } from "./gattConnection";
 export declare function sleep(ms: number): Promise<void>;
 /**
  * Drop-in replacement for `node-ble`'s `createBluetooth` that fails fast and clearly when
@@ -33,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
@@ -78,3 +86,13 @@ export declare function waitForManufacturerData(adapter: Adapter, device: Device
  * leaving it to retry forever in the background after the thing it was waiting to unblock is gone.
  */
 export declare function waitForAdapter(logDebug: (message: string) => void, cancelled?: () => boolean): Promise<boolean>;
+/**
+ * Adapts an already-connected node-ble `Device` to the `GattConnection` facade device drivers
+ * (`zhsunyco`/`gicisky`) talk to - the same shape `app.bleApi.connectGATT()` returns natively (see
+ * `gattConnection.ts`), so a driver's GATT logic runs unchanged under either backend. node-ble
+ * resolves one `GattCharacteristic` object per (service, characteristic) pair and expects callers to
+ * hold onto it for reads/writes/notifications - this caches that resolution keyed by
+ * `"<serviceUuid>:<charUuid>"` so repeated calls (e.g. one `write` per image chunk) don't re-walk
+ * `device.gatt()` every time.
+ */
+export declare function openNodeBleGattConnection(device: Device): GattConnection;

package/dist/devices/bleDiscovery.js

@@ -10,6 +10,7 @@ exports.connectWithTimeout = connectWithTimeout;
 exports.getOrDiscoverDevice = getOrDiscoverDevice;
 exports.waitForManufacturerData = waitForManufacturerData;
 exports.waitForAdapter = waitForAdapter;
+exports.openNodeBleGattConnection = openNodeBleGattConnection;
 const node_ble_1 = require("@naugehyde/node-ble");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -67,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;
@@ -236,3 +246,91 @@ async function waitForAdapter(logDebug, cancelled = () => false) {
     }
     return false;
 }
+/**
+ * Adapts an already-connected node-ble `Device` to the `GattConnection` facade device drivers
+ * (`zhsunyco`/`gicisky`) talk to - the same shape `app.bleApi.connectGATT()` returns natively (see
+ * `gattConnection.ts`), so a driver's GATT logic runs unchanged under either backend. node-ble
+ * resolves one `GattCharacteristic` object per (service, characteristic) pair and expects callers to
+ * hold onto it for reads/writes/notifications - this caches that resolution keyed by
+ * `"<serviceUuid>:<charUuid>"` so repeated calls (e.g. one `write` per image chunk) don't re-walk
+ * `device.gatt()` every time.
+ */
+function openNodeBleGattConnection(device) {
+    const characteristics = new Map();
+    const notificationListeners = new Map();
+    let gattServer;
+    let connected = true;
+    const key = (serviceUuid, charUuid) => `${serviceUuid}:${charUuid}`;
+    async function resolveCharacteristic(serviceUuid, charUuid) {
+        const cacheKey = key(serviceUuid, charUuid);
+        const cached = characteristics.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        gattServer ?? (gattServer = device.gatt());
+        const service = await (await gattServer).getPrimaryService(serviceUuid);
+        const characteristic = await service.getCharacteristic(charUuid);
+        characteristics.set(cacheKey, characteristic);
+        return characteristic;
+    }
+    device.on("disconnect", () => {
+        connected = false;
+    });
+    return {
+        async read(serviceUuid, charUuid) {
+            const characteristic = await resolveCharacteristic(serviceUuid, charUuid);
+            return characteristic.readValue();
+        },
+        async write(serviceUuid, charUuid, data, withResponse = true) {
+            const characteristic = await resolveCharacteristic(serviceUuid, charUuid);
+            if (withResponse === false) {
+                await characteristic.writeValueWithoutResponse(data);
+            }
+            else {
+                await characteristic.writeValueWithResponse(data);
+            }
+        },
+        async startNotifications(serviceUuid, charUuid, callback) {
+            const characteristic = await resolveCharacteristic(serviceUuid, charUuid);
+            notificationListeners.set(key(serviceUuid, charUuid), callback);
+            characteristic.on("valuechanged", callback);
+            await characteristic.startNotifications();
+        },
+        async stopNotifications(serviceUuid, charUuid) {
+            const cacheKey = key(serviceUuid, charUuid);
+            const characteristic = characteristics.get(cacheKey);
+            const listener = notificationListeners.get(cacheKey);
+            if (characteristic && listener) {
+                characteristic.removeListener("valuechanged", listener);
+                notificationListeners.delete(cacheKey);
+                await characteristic.stopNotifications().catch(() => { });
+            }
+        },
+        async discoverServices() {
+            gattServer ?? (gattServer = device.gatt());
+            const server = await gattServer;
+            const services = [];
+            for (const serviceUuid of await server.services()) {
+                const service = await server.getPrimaryService(serviceUuid);
+                const characteristicInfos = [];
+                for (const charUuid of await service.characteristics()) {
+                    const characteristic = await service.getCharacteristic(charUuid);
+                    characteristics.set(key(serviceUuid, charUuid), characteristic);
+                    const properties = await characteristic.getFlags().catch(() => []);
+                    characteristicInfos.push({ uuid: charUuid, properties });
+                }
+                services.push({ uuid: serviceUuid, characteristics: characteristicInfos });
+            }
+            return services;
+        },
+        async disconnect() {
+            await device.disconnect();
+        },
+        get connected() {
+            return connected;
+        },
+        onDisconnect(callback) {
+            device.on("disconnect", () => callback());
+        },
+    };
+}

package/dist/devices/discoveryCoordinator.d.ts

@@ -10,10 +10,29 @@ export interface ScanResult {
 /** epoch ms a scan was started at, if one is currently running - `undefined` otherwise. */
 export declare function scanInProgressSince(): number | undefined;
 /**
- * Runs one BLE discovery scan and persists what it finds. node-ble/BlueZ has no scan-cancellation
- * API and can't run two discovery sessions at once, so a caller that arrives while a scan is
- * already running (e.g. the startup scan and an on-demand scan for a `device: "ALL"` repaint both
- * wanting to scan at the same moment) is hooked into that *same* in-flight scan's eventual result
- * instead of starting a second BlueZ session, which would make both fail.
+ * Runs one BLE discovery scan and persists what it finds. Neither backend can run two discovery
+ * sessions at once (node-ble/BlueZ has no scan-cancellation API; the BLE Manager API tracks one
+ * subscription per plugin), so a caller that arrives while a scan is already running (e.g. the
+ * startup scan and an on-demand scan for a `device: "ALL"` repaint both wanting to scan at the same
+ * moment) is hooked into that *same* in-flight scan's eventual result instead of starting a second
+ * one, which would make both fail.
  */
-export declare function ensureScan(app: ServerAPI, durationSeconds: number): Promise<ScanResult>;
+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,32 +2,38 @@
 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");
 const registry_1 = require("./registry");
+const pluginVersion_1 = require("../pluginVersion");
 let inFlight;
 /** epoch ms a scan was started at, if one is currently running - `undefined` otherwise. */
 function scanInProgressSince() {
     return inFlight?.startedAt;
 }
+/** How long a `connect()` closure built during a scan waits for the GATT connect step itself - a scan may be enumerating several devices, so kept short relative to `paint()`'s own connect timeout. */
+const SCAN_GATT_CONNECT_TIMEOUT_MS = 10000;
 /**
- * Runs one BLE discovery scan and persists what it finds. node-ble/BlueZ has no scan-cancellation
- * API and can't run two discovery sessions at once, so a caller that arrives while a scan is
- * already running (e.g. the startup scan and an on-demand scan for a `device: "ALL"` repaint both
- * wanting to scan at the same moment) is hooked into that *same* in-flight scan's eventual result
- * instead of starting a second BlueZ session, which would make both fail.
+ * Runs one BLE discovery scan and persists what it finds. Neither backend can run two discovery
+ * sessions at once (node-ble/BlueZ has no scan-cancellation API; the BLE Manager API tracks one
+ * subscription per plugin), so a caller that arrives while a scan is already running (e.g. the
+ * startup scan and an on-demand scan for a `device: "ALL"` repaint both wanting to scan at the same
+ * moment) is hooked into that *same* in-flight scan's eventual result instead of starting a second
+ * one, which would make both fail.
  */
-function ensureScan(app, durationSeconds) {
+function ensureScan(app, durationSeconds, useBleApi) {
     if (inFlight) {
         return inFlight.promise;
     }
-    const promise = runScan(app, durationSeconds).finally(() => {
+    const promise = (useBleApi && !!app.bleApi ? runScanViaBleApi(app, durationSeconds) : runScanViaBlueZ(app, durationSeconds)).finally(() => {
         inFlight = undefined;
     });
     inFlight = { startedAt: Date.now(), promise };
     return promise;
 }
-async function runScan(app, durationSeconds) {
+async function runScanViaBlueZ(app, durationSeconds) {
     const foundThisScan = [];
     const drivers = (0, registry_1.allDrivers)();
     try {
@@ -37,7 +43,12 @@ async function runScan(app, durationSeconds) {
                 if (!driver) {
                     return;
                 }
-                const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData).catch((err) => {
+                const rssi = await device
+                    .getRSSI()
+                    .then((value) => (value === undefined ? undefined : Number(value)))
+                    .catch(() => undefined);
+                const connect = () => (0, bleDiscovery_1.connectWithTimeout)(device, SCAN_GATT_CONNECT_TIMEOUT_MS).then(() => (0, bleDiscovery_1.openNodeBleGattConnection)(device));
+                const found = await driver.identifyDevice({ address, name, manufacturerId, manufacturerData, rssi }, connect).catch((err) => {
                     app.debug(`${driver.vendor} scan failed: ${err.message}\n${err.stack ?? ""}`);
                     return undefined;
                 });
@@ -57,3 +68,131 @@ async function runScan(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).
+ */
+async function runScanViaBleApi(app, durationSeconds) {
+    const foundThisScan = [];
+    const seen = new Set();
+    const backend = (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME);
+    const identify = async (mac, name, rssi, manufacturerDataHex) => {
+        if (seen.has(mac)) {
+            return;
+        }
+        seen.add(mac);
+        const found = await identifyOne(app, backend, mac, name, rssi, manufacturerDataHex);
+        if (found) {
+            foundThisScan.push(found);
+        }
+    };
+    try {
+        const unsubscribe = app.bleApi.onAdvertisement(pluginVersion_1.PLUGIN_NAME, (adv) => {
+            void identify(adv.mac, adv.name, adv.rssi, adv.manufacturerData);
+        });
+        try {
+            const known = await app.bleApi.getDevices();
+            for (const device of known) {
+                // BLEDeviceInfo (from getDevices()) doesn't carry manufacturer data - see `bleBackend.ts`'s
+                // waitForManufacturerData doc comment. A driver that needs it to identify (e.g. gicisky) will
+                // still show up once its advertisement arrives on the stream above during this scan window.
+                await identify(device.mac, device.name, device.rssi, undefined);
+            }
+            await (0, bleDiscovery_1.sleep)(durationSeconds * 1000);
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+    catch (err) {
+        app.debug(`scan failed: ${err.message}\n${err.stack ?? ""}`);
+    }
+    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/gattConnection.d.ts

@@ -0,0 +1,9 @@
+import { BLEGattConnection } from "@signalk/server-api";
+/**
+ * Service+characteristic-UUID-keyed GATT surface both BLE backends satisfy - `app.bleApi.connectGATT()`
+ * already returns exactly this shape (it *is* `BLEGattConnection`), and `openNodeBleGattConnection`
+ * (`bleDiscovery.ts`) adapts a node-ble `Device` to it. Device drivers (`zhsunyco`/`gicisky`) talk to
+ * this instead of either BLE library directly, so they work unchanged under whichever backend a caller
+ * hands them - see `bleBackend.ts`.
+ */
+export type GattConnection = BLEGattConnection;

package/dist/devices/gattConnection.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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;

package/dist/devices/gicisky/compression.js

@@ -2,33 +2,148 @@
 /**
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.qlzCompressChunk = qlzCompressChunk;
 exports.frameChunkedPlanes = frameChunkedPlanes;
 const CHUNK_SIZE = 64;
 const RAW_CHUNK_TAG = 0x74;
-function chunkRaw(data) {
+const COMPRESSED_CHUNK_TAG = 0x75;
+const CWORD_LEN = 4;
+const HASH_VALUES = 64;
+const NO_ENTRY = -1;
+const MIN_OFFSET = 2;
+const UNCONDITIONAL_MATCHLEN = 6;
+const UNCOMPRESSED_END = 4;
+/** Control-word sentinel: the top bit marks where the 31 flag bits below it run out. */
+const CWORD_SENTINEL = 0x80000000;
+function hashOf(fetch) {
+    return ((fetch >>> 12) ^ fetch) & (HASH_VALUES - 1);
+}
+function read3(data, pos) {
+    return pos + 3 > data.length ? 0 : data[pos] | (data[pos + 1] << 8) | (data[pos + 2] << 16);
+}
+/** Whether the `n + 1` bytes from `pos` are all equal. */
+function allSame(data, pos, n) {
+    if (pos < 0 || pos + n >= data.length)
+        return false;
+    for (let i = 1; i <= n; i++) {
+        if (data[pos + i] !== data[pos])
+            return false;
+    }
+    return true;
+}
+/**
+ * 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.
+ */
+function qlzCompressChunk(source) {
+    const size = source.length;
+    const lastByte = size - 1;
+    const lastMatchStart = lastByte - UNCONDITIONAL_MATCHLEN - UNCOMPRESSED_END;
+    if (lastMatchStart < 0)
+        return undefined;
+    const out = Buffer.alloc(size * 2 + 400);
+    let cwordPtr = 0;
+    let dst = CWORD_LEN;
+    let cword = CWORD_SENTINEL;
+    let src = 0;
+    let lits = 0;
+    const hashOffset = new Int32Array(HASH_VALUES).fill(NO_ENTRY);
+    const hashCache = new Int32Array(HASH_VALUES);
+    const flushCword = () => {
+        out.writeUInt32LE(((cword >>> 1) | CWORD_SENTINEL) >>> 0, cwordPtr);
+        cwordPtr = dst;
+        dst += CWORD_LEN;
+        cword = CWORD_SENTINEL;
+    };
+    while (src <= lastMatchStart) {
+        if ((cword & 1) === 1) {
+            if (src > size >> 1 && dst > src - (src >> 5))
+                return undefined;
+            flushCword();
+        }
+        const fetch = read3(source, src);
+        const h = hashOf(fetch);
+        const cached = fetch ^ hashCache[h];
+        hashCache[h] = fetch;
+        const o = hashOffset[h];
+        hashOffset[h] = src;
+        if ((cached & 0xffffff) === 0 &&
+            o !== NO_ENTRY &&
+            (src - o > MIN_OFFSET || (src === o + 1 && lits >= 3 && src > 3 && allSame(source, src - 3, 6)))) {
+            let matchLen = 3;
+            const remaining = Math.min(255, lastByte - UNCOMPRESSED_END - src + 1);
+            while (matchLen < remaining && source[src + matchLen] === source[o + matchLen])
+                matchLen++;
+            const hShifted = h << 4;
+            cword = ((cword >>> 1) | CWORD_SENTINEL) >>> 0;
+            if (matchLen < 18) {
+                out.writeUInt16LE((matchLen - 2) | hShifted, dst);
+                dst += 2;
+            }
+            else {
+                out.writeUInt16LE(hShifted, dst);
+                out[dst + 2] = matchLen;
+                dst += 3;
+            }
+            src += matchLen;
+            lits = 0;
+        }
+        else {
+            lits++;
+            out[dst++] = source[src++];
+            cword >>>= 1;
+        }
+    }
+    while (src <= lastByte) {
+        if ((cword & 1) === 1)
+            flushCword();
+        if (src <= lastByte - 2) {
+            const f = read3(source, src);
+            const hh = hashOf(f);
+            hashCache[hh] = f;
+            hashOffset[hh] = src;
+        }
+        out[dst++] = source[src++];
+        cword >>>= 1;
+    }
+    while ((cword & 1) !== 1)
+        cword >>>= 1;
+    out.writeUInt32LE(((cword >>> 1) | CWORD_SENTINEL) >>> 0, cwordPtr);
+    return dst >= size ? undefined : out.subarray(0, dst);
+}
+function chunkPlane(data, compress) {
     const chunks = [];
     for (let offset = 0; offset < data.length; offset += CHUNK_SIZE) {
         const chunk = data.subarray(offset, Math.min(offset + CHUNK_SIZE, data.length));
-        const header = Buffer.from([RAW_CHUNK_TAG, 3 + chunk.length, chunk.length]);
-        chunks.push(header, chunk);
+        const compressed = compress ? qlzCompressChunk(chunk) : undefined;
+        const body = compressed ?? chunk;
+        chunks.push(Buffer.from([compressed ? COMPRESSED_CHUNK_TAG : RAW_CHUNK_TAG, 3 + body.length, chunk.length]), body);
     }
     return Buffer.concat(chunks);
 }
 /**
  * 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`.
  */
-function frameChunkedPlanes(planeA, planeB) {
+function frameChunkedPlanes(planeA, planeB, compress = true) {
     const header = Buffer.alloc(4);
     header.writeUInt32LE(planeB.length, 0);
-    return Buffer.concat([header, chunkRaw(planeA), chunkRaw(planeB)]);
+    return Buffer.concat([header, chunkPlane(planeA, compress), chunkPlane(planeB, compress)]);
 }

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

@@ -7,4 +7,4 @@ import { GiciskyLayout } from "./layout";
  * colour selection uses palette-nearest classification (matching this codebase's `zhsunyco`
  * driver) rather than the reference driver's raw-luminance thresholds.
  */
-export declare function encodeBitmap(bitmap: Bitmap, metadata: DeviceMetadata, layout: GiciskyLayout): Buffer;
+export declare function encodeBitmap(bitmap: Bitmap, metadata: DeviceMetadata, layout: GiciskyLayout, compress?: boolean): Buffer;

package/dist/devices/gicisky/encode.js

@@ -115,7 +115,7 @@ function packFourColour(bitmap, layout, supported) {
  * colour selection uses palette-nearest classification (matching this codebase's `zhsunyco`
  * driver) rather than the reference driver's raw-luminance thresholds.
  */
-function encodeBitmap(bitmap, metadata, layout) {
+function encodeBitmap(bitmap, metadata, layout, compress = true) {
     if (layout.packing === "unsupported") {
         throw new Error(`gicisky paint: device "${metadata.label}" isn't supported yet (needs compression/resize support this driver doesn't implement)`);
     }
@@ -134,7 +134,7 @@ function encodeBitmap(bitmap, metadata, layout) {
     }
     const redPlane = packPlane(rotated, layout, supported, (colour) => colour === "red");
     if (layout.packing === "chunked") {
-        return (0, compression_1.frameChunkedPlanes)(bwPlane, redPlane);
+        return (0, compression_1.frameChunkedPlanes)(bwPlane, redPlane, compress);
     }
     return Buffer.concat([bwPlane, redPlane]);
 }