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

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

@@ -1,4 +1,3 @@
-import { Device } from "@naugehyde/node-ble";
 import { Bitmap } from "../../render/types";
 import { DeviceMetadata, DiscoveredDevice, VendorDeviceConfig, VendorDriver } from "../types";
 export declare class GiciskyDriver implements VendorDriver {
@@ -6,6 +5,12 @@ export declare class GiciskyDriver implements VendorDriver {
     matchesAdvertisement(_name: string | undefined, manufacturerId: number | undefined): boolean;
     metadataForPid(pid: number): DeviceMetadata | undefined;
     supportedDevices(): DeviceMetadata[];
-    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }: {
+        address: string;
+        name: string | undefined;
+        manufacturerId: number | undefined;
+        manufacturerData: Buffer | undefined;
+        rssi: number | undefined;
+    }): Promise<DiscoveredDevice>;
     paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
 }

package/dist/devices/gicisky/index.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GiciskyDriver = void 0;
-const bleDiscovery_1 = require("../bleDiscovery");
+const bleBackend_1 = require("../bleBackend");
 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");
-const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
-/** How long to actively rescan for a fresh advertisement when the cached one is missing/stale - see `waitForManufacturerData`. */
+/** 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;
 const DEFAULT_PAINT_CONNECT_TIMEOUT_MS = 60000;
 const ACK_TIMEOUT_MS = 15000;
@@ -30,7 +30,7 @@ class GiciskyDriver {
     supportedDevices() {
         return metadata_1.GICISKY_PID_METADATA;
     }
-    async identifyDevice(device, address, name, manufacturerId, manufacturerData) {
+    async identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }) {
         const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
         return {
             address,
@@ -40,128 +40,150 @@ class GiciskyDriver {
             metadata: info ? this.metadataForPid(info.deviceId) : undefined,
             manufacturerId,
             batteryMv: info?.batteryMv,
-            rssi: await device
-                .getRSSI()
-                .then((value) => (value === undefined ? undefined : Number(value)))
-                .catch(() => undefined),
+            rssi,
         };
     }
     async paint(bitmap, config) {
-        const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+        const backend = config.gattBackend ?? (0, bleBackend_1.nodeBleBackend)();
+        /**
+         * Unlike zhsunyco, there's no GATT characteristic that reports the device's PID on demand -
+         * the only source for it is the advertisement. That cache can be empty or stale (e.g. nothing
+         * has actively scanned since the adapter/provider last restarted) even though a connect below
+         * would succeed instantly via BlueZ's/the BLE Manager's own device cache - so rescan for a fresh
+         * advertisement here rather than failing on the first read.
+         */
+        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: pid ?? 0, ...config.modelOverride }
+            : pid !== undefined
+                ? this.metadataForPid(pid)
+                : undefined;
+        if (!metadata) {
+            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${pid.toString(16).padStart(4, "0")} - ` +
+                    "pass --width/--height/--voffset/--colours to describe it manually");
+        }
+        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 adapter = await bluetooth.defaultAdapter();
-            const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, config.address, DEVICE_DISCOVERY_TIMEOUT_MS);
-            /**
-             * Unlike zhsunyco, there's no GATT characteristic that reports the device's PID on demand -
-             * the only source for it is the advertisement, cached on the `Device` object by BlueZ from
-             * the last time it was seen (the same cache `identifyDevice`/a scan reads, just without
-             * connecting first - see `forEachAdvertisedDevice` in `bleDiscovery.ts`). That cache can be
-             * empty or stale (e.g. nothing has actively scanned since `bluetoothd` last restarted) even
-             * though `getOrDiscoverDevice` above found the device instantly via BlueZ's own cache of
-             * *devices* - so rescan for a fresh advertisement here rather than failing on the first read.
-             */
-            const manufacturerData = await (0, bleDiscovery_1.waitForManufacturerData)(adapter, device, protocol_1.GICISKY_MANUFACTURER_ID, MANUFACTURER_DATA_RESCAN_TIMEOUT_MS);
-            const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
-            const metadata = config.modelOverride
-                ? { pid: info?.deviceId ?? 0, ...config.modelOverride }
-                : info
-                    ? this.metadataForPid(info.deviceId)
-                    : undefined;
-            if (!metadata) {
-                throw new Error(info === 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")} - ` +
-                        "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);
-            await (0, bleDiscovery_1.connectWithTimeout)(device, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+            const { cmdServiceUuid, cmdUuid, imgServiceUuid, imgUuid } = await findCommandAndImageCharacteristics(conn);
+            const ack = new AckChannel();
+            await conn.startNotifications(cmdServiceUuid, cmdUuid, ack.onNotify);
             try {
-                const gatt = await device.gatt();
-                const { cmd, img } = await findCommandAndImageCharacteristics(gatt);
-                await cmd.startNotifications();
-                try {
-                    const startAck = await writeAndAwaitAck(cmd, cmd, Buffer.from([0x01]));
-                    const chunkSize = ((0, protocol_1.decodeBlockSize)(startAck) ?? DEFAULT_BLOCK_SIZE) - PART_INDEX_HEADER_LENGTH;
-                    await writeAndAwaitAck(cmd, cmd, (0, protocol_1.writeScreenCommand)(payload.length, layout.packing === "chunked"));
-                    const startImageAck = await writeAndAwaitAck(cmd, cmd, Buffer.from([0x03]));
-                    const started = (0, protocol_1.decodeTransferAck)(startImageAck);
-                    if (!started?.ok) {
-                        throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
+                const startAck = await writeAndAwaitAck(conn, cmdServiceUuid, cmdUuid, Buffer.from([0x01]), ack);
+                const chunkSize = ((0, protocol_1.decodeBlockSize)(startAck) ?? DEFAULT_BLOCK_SIZE) - PART_INDEX_HEADER_LENGTH;
+                await writeAndAwaitAck(conn, cmdServiceUuid, cmdUuid, (0, protocol_1.writeScreenCommand)(payload.length, layout.packing === "chunked"), ack);
+                const startImageAck = await writeAndAwaitAck(conn, cmdServiceUuid, cmdUuid, Buffer.from([0x03]), ack);
+                const started = (0, protocol_1.decodeTransferAck)(startImageAck);
+                if (!started?.ok) {
+                    throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
+                }
+                let part = started.nextPart;
+                let lastPart = -1;
+                let repeats = 0;
+                while (part * chunkSize < payload.length) {
+                    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;
                     }
-                    let part = started.nextPart;
-                    let lastPart = -1;
-                    let repeats = 0;
-                    while (part * chunkSize < payload.length) {
-                        const chunk = payload.subarray(part * chunkSize, Math.min(part * chunkSize + chunkSize, payload.length));
-                        const ack = await writeAndAwaitAck(img, cmd, (0, protocol_1.imageChunkPacket)(part, chunk));
-                        const decoded = (0, protocol_1.decodeTransferAck)(ack);
-                        if (!decoded?.ok) {
-                            throw new Error(`gicisky device reported an error transferring image part ${part}: ${ack.toString("hex")}`);
-                        }
-                        if (decoded.nextPart === lastPart) {
-                            repeats++;
-                            if (repeats >= MAX_STALLED_REPEATS) {
-                                throw new Error(`gicisky image transfer stalled - device kept re-requesting part ${decoded.nextPart}`);
-                            }
-                        }
-                        else {
-                            repeats = 0;
-                            lastPart = decoded.nextPart;
+                    if (!decoded?.ok) {
+                        throw new Error(`gicisky device reported an error transferring image part ${part}: ${ackData.toString("hex")}`);
+                    }
+                    if (decoded.nextPart === lastPart) {
+                        repeats++;
+                        if (repeats >= MAX_STALLED_REPEATS) {
+                            throw new Error(`gicisky image transfer stalled - device kept re-requesting part ${decoded.nextPart}`);
                         }
-                        part = decoded.nextPart;
                     }
-                }
-                finally {
-                    await cmd.stopNotifications().catch(() => { });
+                    else {
+                        repeats = 0;
+                        lastPart = decoded.nextPart;
+                    }
+                    part = decoded.nextPart;
                 }
             }
             finally {
-                await device.disconnect();
+                await conn.stopNotifications(cmdServiceUuid, cmdUuid).catch(() => { });
             }
         }
         finally {
-            destroy();
+            await conn.disconnect();
         }
     }
 }
 exports.GiciskyDriver = GiciskyDriver;
+/**
+ * Single-slot "await the next notification" dispatcher - the gicisky protocol is strictly
+ * request/response (never more than one write in flight), so a persistent `startNotifications`
+ * callback (`GattConnection`'s shape, unlike node-ble's per-call `.once("valuechanged")`) just needs
+ * to hand its next delivery to whichever `waitForAck` call is currently pending. Mirrors how
+ * signalk-bluetti-plugin's `ProtocolSession.feed()` dispatches notification bytes to a single
+ * pending request.
+ */
+class AckChannel {
+    constructor() {
+        this.onNotify = (data) => {
+            const pending = this.pending;
+            if (!pending)
+                return;
+            this.pending = undefined;
+            clearTimeout(pending.timer);
+            pending.resolve(data);
+        };
+    }
+    waitForAck(timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending = undefined;
+                reject(new Error("gicisky device did not acknowledge in time"));
+            }, timeoutMs);
+            this.pending = { resolve, timer };
+        });
+    }
+}
+/** Writes `data` to `(writeServiceUuid, writeUuid)`, then awaits the next ack delivered to `ack`. */
+async function writeAndAwaitAck(conn, writeServiceUuid, writeUuid, data, ack) {
+    const pending = ack.waitForAck(ACK_TIMEOUT_MS);
+    await conn.write(writeServiceUuid, writeUuid, data, false);
+    return pending;
+}
 /**
  * Walks every service whose UUID starts `0000f`, collecting their characteristics and sorting by
  * 16-bit UUID value - mirrors both reference drivers, which locate their command/image
  * characteristics this way rather than by a hardcoded service UUID (see `protocol.ts`).
  */
-async function findCommandAndImageCharacteristics(gatt) {
+async function findCommandAndImageCharacteristics(conn) {
     const candidates = [];
-    for (const serviceUuid of await gatt.services()) {
-        if (!serviceUuid.toLowerCase().startsWith(protocol_1.CANDIDATE_SERVICE_UUID_PREFIX)) {
+    for (const service of await conn.discoverServices()) {
+        if (!service.uuid.toLowerCase().startsWith(protocol_1.CANDIDATE_SERVICE_UUID_PREFIX)) {
             continue;
         }
-        const service = await gatt.getPrimaryService(serviceUuid);
-        for (const charUuid of await service.characteristics()) {
-            candidates.push({ uuid: charUuid, char: await service.getCharacteristic(charUuid) });
+        for (const characteristic of service.characteristics) {
+            candidates.push({ serviceUuid: service.uuid, uuid: characteristic.uuid });
         }
     }
     candidates.sort((a, b) => parseInt(a.uuid.slice(4, 8), 16) - parseInt(b.uuid.slice(4, 8), 16));
     if (candidates.length < 2) {
         throw new Error(`gicisky device exposes ${candidates.length} candidate characteristic(s) under a "0000f..." service, expected at least 2`);
     }
-    return { cmd: candidates[0].char, img: candidates[1].char };
-}
-/** Writes `data` to `writeChar`, then awaits the next notification on `notifyChar` (which may be the same characteristic). */
-function writeAndAwaitAck(writeChar, notifyChar, data) {
-    const ack = new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            notifyChar.removeListener("valuechanged", onValue);
-            reject(new Error("gicisky device did not acknowledge in time"));
-        }, ACK_TIMEOUT_MS);
-        function onValue(value) {
-            clearTimeout(timer);
-            resolve(value);
-        }
-        notifyChar.once("valuechanged", onValue);
-    });
-    return writeChar.writeValueWithoutResponse(data).then(() => ack);
+    return {
+        cmdServiceUuid: candidates[0].serviceUuid,
+        cmdUuid: candidates[0].uuid,
+        imgServiceUuid: candidates[1].serviceUuid,
+        imgUuid: candidates[1].uuid,
+    };
 }

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,7 +1,17 @@
-import { Device } from "@naugehyde/node-ble";
 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.
@@ -52,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. */
@@ -60,6 +77,20 @@ 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
+     * `nodeBleBackend()` (`bleBackend.ts`). The SignalK plugin (`plugin.ts`/`repaintScheduler.ts`) passes
+     * a `bleApiBackend()` here instead when the user has opted into the SignalK BLE Manager API
+     * (`PluginConfig.useBleApi`) and the server offers `app.bleApi`.
+     */
+    gattBackend?: BleBackend;
 }
 export interface VendorDriver {
     vendor: string;
@@ -70,12 +101,23 @@ export interface VendorDriver {
     /** All device models this driver currently has confirmed metadata for. */
     supportedDevices(): DeviceMetadata[];
     /**
-     * Identifies one device the shared caller (see `bleDiscovery.ts`'s `forEachAdvertisedDevice`)
-     * has already matched to this vendor via `matchesAdvertisement` - only called for matches, so a
-     * device gets at most one vendor-specific connect/read regardless of how many drivers are
-     * registered, not one attempt per driver.
+     * Identifies one device the shared caller (`discoveryCoordinator.ts`'s `runScan`, backed by either
+     * `forEachAdvertisedDevice` over direct BlueZ or the BLE Manager API's advertisement stream) has
+     * already matched to this vendor via `matchesAdvertisement` - only called for matches, so a device
+     * gets at most one vendor-specific connect/read regardless of how many drivers are registered, not
+     * one attempt per driver.
+     *
+     * `connect` opens a `GattConnection` to this device on whichever backend the scan is using - call it
+     * lazily, only when the advertisement alone doesn't carry enough to identify the device (e.g.
+     * zhsunyco's battery/config read fallback); most matches never need it.
      */
-    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    identifyDevice(advertisement: {
+        address: string;
+        name: string | undefined;
+        manufacturerId: number | undefined;
+        manufacturerData: Buffer | undefined;
+        rssi: number | undefined;
+    }, connect: () => Promise<GattConnection>): Promise<DiscoveredDevice>;
     /** Quantise the common bitmap to this device's palette/encoding and send it over BLE. */
     paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
 }

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.d.ts

@@ -1,11 +1,17 @@
-import { Device } from "@naugehyde/node-ble";
 import { Bitmap } from "../../render/types";
 import { DeviceMetadata, DiscoveredDevice, VendorDeviceConfig, VendorDriver } from "../types";
+import { GattConnection } from "../gattConnection";
 export declare class ZhsunycoDriver implements VendorDriver {
     readonly vendor = "zhsunyco";
     matchesAdvertisement(name: string | undefined, manufacturerId: number | undefined): boolean;
     metadataForPid(pid: number, hwVersion?: string): DeviceMetadata | undefined;
     supportedDevices(): DeviceMetadata[];
-    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }: {
+        address: string;
+        name: string | undefined;
+        manufacturerId: number | undefined;
+        manufacturerData: Buffer | undefined;
+        rssi: number | undefined;
+    }, connect: () => Promise<GattConnection>): Promise<DiscoveredDevice>;
     paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
 }