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

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.

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

@@ -15,6 +15,8 @@ export declare const WOLINK_CHARACTERISTIC_UUIDS: {
 export declare const COMMAND: {
     readonly uploadBlock: 42240;
     readonly refreshUncompressed: 42241;
+    /** Refresh after uploading a `compressWolinkBlocks` payload rather than the raw buffer. */
+    readonly refreshCompressed: 42242;
 };
 export interface AdvertisedDeviceInfo {
     pid: number;

package/dist/devices/zhsunyco/protocol.js

@@ -25,6 +25,8 @@ exports.WOLINK_CHARACTERISTIC_UUIDS = {
 exports.COMMAND = {
     uploadBlock: 0xa500,
     refreshUncompressed: 0xa501,
+    /** Refresh after uploading a `compressWolinkBlocks` payload rather than the raw buffer. */
+    refreshCompressed: 0xa502,
 };
 /** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
 function decodeAdvertisedInfo(data) {

package/dist/plugin.js

@@ -9,6 +9,7 @@ const discoveryCoordinator_1 = require("./devices/discoveryCoordinator");
 const bleDiscovery_1 = require("./devices/bleDiscovery");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
+const pluginVersion_1 = require("./pluginVersion");
 /** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
 async function runStartupScan(app, durationSeconds, useBleApi) {
     const alreadyRunning = (0, discoveryCoordinator_1.scanInProgressSince)();
@@ -41,6 +42,7 @@ function createPlugin(app) {
     // enough to have added it - checked at runtime rather than trusted from the type.
     const bleApiAvailable = !!app.bleApi;
     let scheduler;
+    let stopDiscoveryListener;
     let stopped = false;
     const plugin = {
         id: "signalk-einklabel-plugin",
@@ -54,10 +56,10 @@ function createPlugin(app) {
         start(config) {
             const pluginConfig = {
                 ...(0, config_1.defaultConfig)(),
-                ...config,
+                ...(0, config_1.migrateConfig)(config).config,
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
-            (0, config_1.healNestedConfig)(app);
+            (0, config_1.healStoredConfig)(app);
             stopped = false;
             const useBleApi = pluginConfig.useBleApi && bleApiAvailable;
             if (pluginConfig.useBleApi && !bleApiAvailable) {
@@ -73,6 +75,11 @@ function createPlugin(app) {
                 scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
             };
             if (useBleApi) {
+                // BLE Manager already runs its own continuous scan server-side (that's what populates its own
+                // admin UI device list) - unlike direct BlueZ access below, discovery here doesn't need a
+                // bounded scan window at all, so this listens for as long as the plugin runs rather than only
+                // during `scanOnStart`/an on-demand `ALL_DEVICES` scan. See its own doc comment.
+                stopDiscoveryListener = (0, discoveryCoordinator_1.startBleApiDiscoveryListener)(app, pluginVersion_1.PLUGIN_NAME);
                 // The server/provider governs its own local-adapter readiness once BLE Manager mode owns
                 // `hci0` (or has none at all, behind a remote gateway) - waiting on a *local* BlueZ adapter
                 // here would be waiting on something this mode may never even need.
@@ -90,6 +97,8 @@ function createPlugin(app) {
             stopped = true;
             scheduler?.stop();
             scheduler = undefined;
+            stopDiscoveryListener?.();
+            stopDiscoveryListener = undefined;
             app.debug("stopped");
         },
     };

package/dist/render/mirror.d.ts

@@ -0,0 +1,11 @@
+import { Bitmap } from "./types";
+/**
+ * Flips the rendered image before it's encoded for the panel - for hardware whose RAM layout is
+ * mirrored relative to what a driver's encoder assumes (the Wolink HA integration found the 2.9"
+ * and 3.5" panels differ from the 3.7" this plugin's zhsunyco encoder was confirmed against), or a
+ * label that's simply mounted upside down (`"both"` is a 180° rotation).
+ */
+export type MirrorMode = "none" | "horizontal" | "vertical" | "both";
+export declare const MIRROR_MODES: MirrorMode[];
+/** Returns `bitmap` unchanged for `"none"`, otherwise a flipped copy. */
+export declare function mirrorBitmap(bitmap: Bitmap, mode: MirrorMode): Bitmap;

package/dist/render/mirror.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIRROR_MODES = void 0;
+exports.mirrorBitmap = mirrorBitmap;
+exports.MIRROR_MODES = ["none", "horizontal", "vertical", "both"];
+/** Returns `bitmap` unchanged for `"none"`, otherwise a flipped copy. */
+function mirrorBitmap(bitmap, mode) {
+    if (mode === "none") {
+        return bitmap;
+    }
+    const { width, height } = bitmap;
+    const flipX = mode === "horizontal" || mode === "both";
+    const flipY = mode === "vertical" || mode === "both";
+    const data = new Uint8Array(bitmap.data.length);
+    for (let y = 0; y < height; y++) {
+        const srcY = flipY ? height - 1 - y : y;
+        for (let x = 0; x < width; x++) {
+            const srcX = flipX ? width - 1 - x : x;
+            const srcOffset = (srcY * width + srcX) * 4;
+            data.set(bitmap.data.subarray(srcOffset, srcOffset + 4), (y * width + x) * 4);
+        }
+    }
+    return { width, height, data };
+}

package/dist/repaintScheduler.js

@@ -23,6 +23,8 @@ const pluginVersion_1 = require("./pluginVersion");
 const httpJson_1 = require("./httpJson");
 const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
+/** Pause between paint attempts - see `withRetries`' `delayMs`. */
+const PAINT_RETRY_DELAY_MS = 5000;
 const RESOURCES_API_PATH = "/signalk/v2/api/resources";
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -173,7 +175,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
 }
 function clearForceRepaint(app, friendlyName) {
     const current = (0, config_1.readCurrentConfig)(app);
-    const devices = (current.devices ?? []).map((device) => device.friendlyName === friendlyName ? { ...device, forceRepaint: false } : device);
+    const devices = (current.devices ?? []).map((device) => device.friendlyName === friendlyName ? { ...device, advanced: { ...device.advanced, forceRepaint: false } } : device);
     app.savePluginOptions({ ...current, devices }, (err) => {
         if (err)
             app.debug(`failed to clear forceRepaint for "${friendlyName}": ${err.message}`);
@@ -307,7 +309,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
         // scheduled tick" (e.g. a regenerated forecast) is the whole point of one - which is exactly why a
         // provider-backed device should use `repaintTrigger: "interval"`, not `subscription`, for
         // cost/battery reasons (each repaint may be a paid API call on the provider's side).
-        if (!provider && !templateChanged && !dataChanged && !device.forceRepaint) {
+        if (!provider && !templateChanged && !dataChanged && !device.advanced?.forceRepaint) {
             app.debug(`${label}: data unchanged, skipping repaint`);
             return;
         }
@@ -325,7 +327,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
             : await renderer.render(templatePath, renderContext, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
         succeeded = true;
-        repaintReason = device.forceRepaint
+        repaintReason = device.advanced?.forceRepaint
             ? "forced"
             : provider
                 ? "provider-rendered"
@@ -344,16 +346,29 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
         });
         bitmap = await renderer.render(fallbackPath, { meta: { repainted: new Date().toISOString(), plugin_version: pluginVersion_1.PLUGIN_VERSION, description: device.description ?? "" } }, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
     }
-    const connectTimeoutMs = config.paintConnectTimeoutSeconds * 1000;
-    await (0, bleDiscovery_1.withRetries)(config.paintRetries, async (attempt) => {
-        if (attempt > 1) {
-            app.debug(`${label}: attempting paint ${attempt}/${config.paintRetries}`);
-        }
+    const connectTimeoutMs = (device.advanced?.paintConnectTimeoutSeconds ?? config.paintConnectTimeoutSeconds) * 1000;
+    const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
+    const attempts = Math.max(1, device.advanced?.paintRetries ?? config.paintRetries);
+    const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
+        app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
         const startedAt = Date.now();
-        const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
-        await driver.paint(bitmap, { address, aesKey: device.aesKey, connectTimeoutMs, reframe: device.reframe, gattBackend });
+        await driver.paint(bitmap, {
+            address,
+            pid: target.pid,
+            aesKey: device.advanced?.aesKey,
+            connectTimeoutMs,
+            reframe: device.reframe,
+            mirror: device.advanced?.mirror,
+            compress: device.advanced?.compress,
+            compressionFormat: device.advanced?.compressionFormat,
+            gattBackend,
+        });
         paintDurationMs = Date.now() - startedAt;
+    }, {
+        delayMs: PAINT_RETRY_DELAY_MS,
+        onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
     });
+    await (gattBackend ? (0, bleBackend_1.exclusiveBleManagerAccess)(paintWithRetries) : paintWithRetries());
     (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, { address, vendor: target.vendor, pid: target.pid, hwVersion: target.hwVersion, metadata });
     // Only a successful render counts as "repainted" for dedup/catch-up purposes - a failure must not be
     // recorded here (see this function's doc comment on why).
@@ -393,7 +408,7 @@ function startRepaintScheduler(app, config) {
         // A single `forceRepaint` flag covers every target under `ALL_DEVICES` too - only clear it once
         // every target has actually succeeded, so a target that failed still gets forced again next time
         // instead of quietly reverting to ordinary hash-based dedup.
-        if (device.forceRepaint && results.every((result) => result.status === "fulfilled")) {
+        if (device.advanced?.forceRepaint && results.every((result) => result.status === "fulfilled")) {
             clearForceRepaint(app, device.friendlyName);
         }
     };
@@ -440,7 +455,7 @@ function startRepaintScheduler(app, config) {
     // still avoids a redundant paint once targets are resolved.
     const startupCheckTimer = setTimeout(() => {
         for (const device of config.devices) {
-            if (device.repaintTrigger === "interval" && !device.forceRepaint && device.device !== config_1.ALL_DEVICES) {
+            if (device.repaintTrigger === "interval" && !device.advanced?.forceRepaint && device.device !== config_1.ALL_DEVICES) {
                 const hours = device.intervalHours ?? 1;
                 const minute = device.intervalMinute ?? 0;
                 const dueSlot = mostRecentScheduledSlot(new Date(), hours, minute);