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

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;

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]);
 }

package/dist/devices/gicisky/index.js

@@ -6,6 +6,7 @@ const metadata_1 = require("./metadata");
 const layout_1 = require("./layout");
 const encode_1 = require("./encode");
 const reframe_1 = require("../../render/reframe");
+const mirror_1 = require("../../render/mirror");
 const protocol_1 = require("./protocol");
 /** How long to actively rescan for a fresh advertisement when the cached one is missing/stale - see `BleBackend.waitForManufacturerData`. */
 const MANUFACTURER_DATA_RESCAN_TIMEOUT_MS = 15000;
@@ -53,21 +54,25 @@ class GiciskyDriver {
          */
         const manufacturerData = await backend.waitForManufacturerData(config.address, protocol_1.GICISKY_MANUFACTURER_ID, MANUFACTURER_DATA_RESCAN_TIMEOUT_MS);
         const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
+        // A device that's quiet right now (e.g. still refreshing from the last paint) can still be painted
+        // when its PID is already known from config/a previous scan - the connect below doesn't need the
+        // advertisement, only this lookup does.
+        const pid = info?.deviceId ?? config.pid;
         const metadata = config.modelOverride
-            ? { pid: info?.deviceId ?? 0, ...config.modelOverride }
-            : info
-                ? this.metadataForPid(info.deviceId)
+            ? { pid: pid ?? 0, ...config.modelOverride }
+            : pid !== undefined
+                ? this.metadataForPid(pid)
                 : undefined;
         if (!metadata) {
-            throw new Error(info === undefined
+            throw new Error(pid === undefined
                 ? "gicisky device isn't advertising - rescanned but got nothing back (out of range, asleep, or already connected " +
                     "elsewhere) - pass --width/--height/--voffset/--colours to describe it manually"
-                : `gicisky device reports unrecognised deviceId 0x${info.deviceId.toString(16).padStart(4, "0")} - ` +
+                : `gicisky device reports unrecognised deviceId 0x${pid.toString(16).padStart(4, "0")} - ` +
                     "pass --width/--height/--voffset/--colours to describe it manually");
         }
-        const layout = (info && layout_1.GICISKY_PID_LAYOUT[info.deviceId]) || (0, layout_1.defaultLayoutFor)(metadata.colours);
-        const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop");
-        const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout);
+        const layout = (0, layout_1.withCompressionFormat)((pid !== undefined && layout_1.GICISKY_PID_LAYOUT[pid]) || (0, layout_1.defaultLayoutFor)(metadata.colours), config.compressionFormat ?? "auto", metadata.colours);
+        const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop"), config.mirror ?? "none");
+        const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout, config.compress ?? true);
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
         try {
             const { cmdServiceUuid, cmdUuid, imgServiceUuid, imgUuid } = await findCommandAndImageCharacteristics(conn);
@@ -89,6 +94,12 @@ class GiciskyDriver {
                     const chunk = payload.subarray(part * chunkSize, Math.min(part * chunkSize + chunkSize, payload.length));
                     const ackData = await writeAndAwaitAck(conn, imgServiceUuid, imgUuid, (0, protocol_1.imageChunkPacket)(part, chunk), ack);
                     const decoded = (0, protocol_1.decodeTransferAck)(ackData);
+                    if (decoded && !decoded.ok && part * chunkSize + chunk.length >= payload.length) {
+                        // The device answers the final chunk with a non-zero status (seen: `05 08 00000000`) once
+                        // it has the whole image and starts refreshing - the transfer's done, not failed. Matches
+                        // hass-gicisky's writer, which ends the transfer on any non-zero status rather than erroring.
+                        break;
+                    }
                     if (!decoded?.ok) {
                         throw new Error(`gicisky device reported an error transferring image part ${part}: ${ackData.toString("hex")}`);
                     }

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

@@ -1,3 +1,4 @@
+import { CompressionFormat } from "../types";
 /**
  * Per-model wire-layout quirks, keyed the same way as `GICISKY_PID_METADATA` (by `deviceId`).
  * These aren't part of the shared `DeviceMetadata` shape since no other vendor needs them -
@@ -9,7 +10,7 @@
 export type GiciskyPacking = 
 /** Plain concatenated bit-planes, no framing - covers most panels. */
 "plain"
-/** Two bit-planes each split into raw 64-byte chunks framed per `compression.ts`'s `compress()` - the 7.5"/10.2" panels. */
+/** Two bit-planes each split into 64-byte chunks (QuickLZ-compressed or raw) framed per `compression.ts` - the 7.5"/10.2" panels. */
  | "chunked"
 /**
  * A panel this driver can identify (for `scan`/discovery) but can't paint correctly yet - either
@@ -33,3 +34,14 @@ export interface GiciskyLayout {
 export declare const GICISKY_PID_LAYOUT: Record<number, GiciskyLayout>;
 /** Best-effort layout for a `modelOverride`d PID this table has no entry for - assumes the common case. */
 export declare function defaultLayoutFor(colours: string[]): GiciskyLayout;
+/**
+ * Applies a user's opt-in `compressionFormat: "chunked"` - switching a `"plain"` two-plane (BW + red)
+ * layout to the QuickLZ-chunked framing, with the flagged `writeScreen` command that goes with it.
+ * Opt-in rather than a model default because only one data point says a plain panel accepts it:
+ * Cabalist's 2023 BLE captures (https://github.com/Cabalist/gicisky_image_notes) of the vendor app
+ * sending a 4.2" BWR exactly this way, on firmware that may not match what's shipping now.
+ *
+ * Throws for layouts the framing can't carry, rather than quietly sending plain anyway - the user
+ * asked for chunked, so a repaint error says why they're not getting it.
+ */
+export declare function withCompressionFormat(layout: GiciskyLayout, format: CompressionFormat, colours: string[]): GiciskyLayout;

package/dist/devices/gicisky/layout.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GICISKY_PID_LAYOUT = void 0;
 exports.defaultLayoutFor = defaultLayoutFor;
+exports.withCompressionFormat = withCompressionFormat;
 const DEFAULT_LAYOUT = {
     rotation: 0,
     mirrorX: false,
@@ -33,3 +34,23 @@ exports.GICISKY_PID_LAYOUT = {
 function defaultLayoutFor(colours) {
     return { ...DEFAULT_LAYOUT, fourColour: colours.includes("yellow") };
 }
+/**
+ * Applies a user's opt-in `compressionFormat: "chunked"` - switching a `"plain"` two-plane (BW + red)
+ * layout to the QuickLZ-chunked framing, with the flagged `writeScreen` command that goes with it.
+ * Opt-in rather than a model default because only one data point says a plain panel accepts it:
+ * Cabalist's 2023 BLE captures (https://github.com/Cabalist/gicisky_image_notes) of the vendor app
+ * sending a 4.2" BWR exactly this way, on firmware that may not match what's shipping now.
+ *
+ * Throws for layouts the framing can't carry, rather than quietly sending plain anyway - the user
+ * asked for chunked, so a repaint error says why they're not getting it.
+ */
+function withCompressionFormat(layout, format, colours) {
+    if (format === "auto" || layout.packing === "chunked") {
+        return layout;
+    }
+    if (layout.packing !== "plain" || layout.fourColour || !colours.includes("red")) {
+        throw new Error('gicisky paint: compressionFormat "chunked" needs a panel sent as separate black/white and red planes - ' +
+            'this model isn\'t (four-colour, black/white only, or unsupported) - set it back to "auto"');
+    }
+    return { ...layout, packing: "chunked" };
+}

package/dist/devices/types.d.ts

@@ -1,8 +1,17 @@
 import { Bitmap } from "../render/types";
 import { ReframeMode } from "../render/reframe";
+import { MirrorMode } from "../render/mirror";
 import { BleBackend } from "./bleBackend";
 import { GattConnection } from "./gattConnection";
 export type Colour = "black" | "white" | "red" | "yellow";
+/**
+ * Which wire format to send in - `"auto"` uses whatever the driver's model table says;
+ * `"chunked"` opts a gicisky panel with separate BW/red planes (e.g. the 4.2" BWR, normally sent
+ * plain) into the QuickLZ-compressed chunk framing the 7.5"/10.2" use - see `withCompressionFormat`
+ * in `gicisky/layout.ts`. Ignored by other vendors.
+ */
+export type CompressionFormat = "auto" | "chunked";
+export declare const COMPRESSION_FORMATS: CompressionFormat[];
 /**
  * Static facts about one device model, keyed by (vendor, pid) by the registry —
  * PID alone is not assumed unique across vendors.
@@ -53,6 +62,13 @@ export type DeviceModelOverride = Omit<DeviceMetadata, "pid">;
 /** Per-device settings the user supplies when registering a device, beyond what's in DeviceMetadata. */
 export interface VendorDeviceConfig {
     address: string;
+    /**
+     * The PID already known for this device (from the configured `"<vendor>:<pid>@<address>"` or a
+     * previous scan) - a fallback for drivers that otherwise only learn it from a fresh advertisement
+     * (gicisky), so a device that's quiet at paint time can still be painted. A live advertised PID
+     * takes precedence when there is one.
+     */
+    pid?: number;
     /** AES key for vendors that need it, entered by the user. If omitted, vendors that have one may fall back to a stock/manufacturer-default key instead of failing. */
     aesKey?: string;
     /** Forces the device model facts instead of looking up the advertised PID - for hardware not yet in the driver's table. */
@@ -61,6 +77,12 @@ export interface VendorDeviceConfig {
     connectTimeoutMs?: number;
     /** How to fit the bitmap onto the panel when its size doesn't already match - see `ReframeMode`. Defaults to `"crop"` - a live label showing *something*, even off-size, beats a repaint that just fails outright; pass `"fixed"` explicitly to get the old reject-the-mismatch behaviour back. */
     reframe?: ReframeMode;
+    /** Flips the image after reframing, before encoding - see `MirrorMode`. Defaults to `"none"`. */
+    mirror?: MirrorMode;
+    /** Compress the upload where the vendor protocol supports it (zhsunyco; gicisky's chunked 7.5"/10.2" panels); ignored otherwise. Defaults to `true`. */
+    compress?: boolean;
+    /** Overrides the model's own wire format - see `CompressionFormat`. Defaults to `"auto"`. */
+    compressionFormat?: CompressionFormat;
     /**
      * How `paint()` reaches the device's BLE hardware - omitted (always true for the CLI, which has no
      * `ServerAPI`/`app.bleApi` to source one from) means direct BlueZ access via a fresh

package/dist/devices/types.js

@@ -1,2 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPRESSION_FORMATS = void 0;
+exports.COMPRESSION_FORMATS = ["auto", "chunked"];

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

@@ -0,0 +1 @@
+export declare function compressWolinkBlocks(data: Buffer): Buffer;

package/dist/devices/zhsunyco/compression.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compressWolinkBlocks = compressWolinkBlocks;
+const zlib_1 = require("zlib");
+/**
+ * Wolink block-deflate payload format, ported from the `zhsunyco_esl` package bundled with the
+ * Home Assistant Wolink ESL integration (`zhsunyco_esl/protocol.py`):
+ *
+ *   A5 A6 <blockCount u8> 02, then per block: <1-based index u8> <compressedLength u16le> <raw deflate>
+ *
+ * Each block holds up to 8 KB of the uncompressed 2bpp buffer. Sent in place of the raw buffer,
+ * followed by `COMMAND.refreshCompressed` carrying the compressed length.
+ */
+const WOLINK_BLOCK_SIZE = 8192;
+const WOLINK_BLOCK_FORMAT = 0x02;
+function compressWolinkBlocks(data) {
+    const blockCount = Math.ceil(data.length / WOLINK_BLOCK_SIZE);
+    if (blockCount > 0xff) {
+        throw new Error(`zhsunyco compression: ${data.length} bytes needs ${blockCount} blocks, format allows at most 255`);
+    }
+    const parts = [Buffer.from([0xa5, 0xa6, blockCount, WOLINK_BLOCK_FORMAT])];
+    for (let i = 0; i < blockCount; i++) {
+        const deflated = (0, zlib_1.deflateRawSync)(data.subarray(i * WOLINK_BLOCK_SIZE, (i + 1) * WOLINK_BLOCK_SIZE), { level: 9 });
+        const header = Buffer.alloc(3);
+        header[0] = i + 1;
+        header.writeUInt16LE(deflated.length, 1);
+        parts.push(header, deflated);
+    }
+    return Buffer.concat(parts);
+}

package/dist/devices/zhsunyco/index.js

@@ -7,6 +7,8 @@ const pluginVersion_1 = require("../../pluginVersion");
 const metadata_1 = require("./metadata");
 const encode_1 = require("./encode");
 const reframe_1 = require("../../render/reframe");
+const mirror_1 = require("../../render/mirror");
+const compression_1 = require("./compression");
 const protocol_1 = require("./protocol");
 /** node-ble has no MTU API; this matches the reference driver's mtu(247)-9 default. */
 const UPLOAD_CHUNK_SIZE = 238;
@@ -77,14 +79,18 @@ class ZhsunycoDriver {
                 const challenge = await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate);
                 await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate, (0, protocol_1.authResponse)(challenge, aesKey), false);
                 await (0, bleDiscovery_1.sleep)(AUTH_SETTLE_DELAY_MS);
-                const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop");
+                const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop"), config.mirror ?? "none");
                 const pixelData = (0, encode_1.encodeBitmap)(framed, metadata);
-                for (let offset = 0; offset < pixelData.length; offset += UPLOAD_CHUNK_SIZE) {
-                    const chunk = pixelData.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
+                const compress = config.compress ?? true;
+                // Upload offsets and the refresh length both count bytes of whatever's actually sent - the
+                // compressed payload when compressing, not the raw buffer it inflates back to.
+                const payload = compress ? (0, compression_1.compressWolinkBlocks)(pixelData) : pixelData;
+                for (let offset = 0; offset < payload.length; offset += UPLOAD_CHUNK_SIZE) {
+                    const chunk = payload.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
                     await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), true);
                     await (0, bleDiscovery_1.sleep)(CHUNK_WRITE_DELAY_MS);
                 }
-                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(protocol_1.COMMAND.refreshUncompressed, pixelData.length), true);
+                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), true);
                 // `Promise.race` can't cancel its loser, so once `statusReceived` settles (the common case)
                 // this timer would otherwise sit alive for the rest of its 60s regardless - see the identical
                 // reasoning on `readDeviceDetails`'s own race, below.