@rhizomatics/signalk-einklabel-plugin 1.3.0-beta7 → 1.3.0-beta9

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # 1.3.0
 
-First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services. Off by default until longer term stability demonstrated.
+## BLE Manager
+
+First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services.
+
+- Off by default until longer term stability demonstrated.
+- It may be less reliable for some devices that can be reached with direct bluez access - try it and fall back to the direct mode if so.
+- BLE Manager use reduces interference between plugins competing for same BLE devices
+- Recommend using SignalK at least release v2.33.0.
+
+## Compression
+
+Images are now compressed before sending - no change to what's displayed, but send time is massively reduced for labels with lots of empty space, so less battery is used and sends are less likely to fail.
+
+- On by default for Zhsunyco labels and Gicisky 7.5"/10.2" labels; can be turned off per label, or with `--no-compress` on the CLI
+- Experimental opt-in _Wire format_ `chunked` sends a Gicisky 4.2" BWR compressed too (`--compression-format chunked` on the CLI)
+
+## Mirroring
+
+Some labels may need images flipped, so a per-label _Mirror_ option can flip the image horizontally, vertically, or both (rotate 180°, for a label mounted upside down). Also available as `--mirror` on the CLI `paint` and `render` commands.
 
 # 1.2.3
 

package/README.md

@@ -178,6 +178,14 @@ Templates are simply SVG files, to which expressions can be added to use SignalK
 
 There's some wiggle room with the `reframe` options to use a template that's a bit too small, or too large, for the label, although best results come from a template that's precisely matching the pixel height and width of the label. Next best is template that has the same aspect ratio, so it can be cleanly scaled. `crop` is the 2nd least worst, though if its only a handful of pixels its often not worth worring about a separate template and `crop` is just fine. `scale` is likely to look worst, since it will force an image in regardless of aspect ratio.
 
+### Other Image Options
+
+Each label has a few more settings for how the image is sent. The CLI `paint` command has matching options (see [Command Line Interface](#command-line-interface)), so you can try them on a label before changing the plugin config.
+
+- _Compress upload_ - on by default. Sends much less data over Bluetooth, so painting is quicker, uses less of the label's battery and is less likely to time out. Works for Zhsunyco labels and Gicisky 7.5"/10.2" labels, and is ignored for others. Turn it off if a label stops updating.
+- _Wire format (Gicisky, experimental)_ - `auto` by default. `chunked` sends a Gicisky 4.2" BWR label compressed, the same way as the 7.5"/10.2". The vendor's own app has been seen doing this, but it hasn't been tested on current firmware. Set it back to `auto` if the label stops updating.
+- _Mirror_ - `none` by default. `horizontal` or `vertical` fixes a label model whose image comes out mirrored. `both` rotates the image 180°, for a label that has to be mounted upside down.
+
 ### Template Families (multiple panel sizes/colours)
 
 A "Template" selection can either be one specific `.svg` file, or a _directory_ holding several versions of the same template for different panel sizes/colour-sets, e.g. `templates/tides/416x240-BWRY.svg` and `templates/tides/250x128-BWRY.svg` both implement the tide clock, just at different sizes.
@@ -309,6 +317,12 @@ Left unset, both `render` and `paint` default `-w/--width`/`--height` to the tem
 
 The main SignalK plugin offers the same choice per device (defaulting to `crop` there too) in each device's own config - "If the render doesn't match the panel size".
 
+`paint` has matching options for the other per-label image settings too (see [Other Image Options](#other-image-options)):
+
+- `--mirror <mode>` - `none` (default), `horizontal`, `vertical`, or `both` (rotate 180°). `render` also takes `--mirror`, to preview the flip as a PNG without a label
+- `--no-compress` - send the image uncompressed, to rule compression out if a label won't update
+- `--compression-format <format>` - `auto` (default) or `chunked`, to try the experimental compressed format on a Gicisky 4.2" BWR
+
 `esl-cli` can also be extended with new subcommands by a `-r/--require`'d package - see [Extending](#extending) below - which is how [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) adds its own `prompt`/`generate` commands for testing prompts without a device.
 
 ( The CLI can also be run from a checked out module, or by opening a terminal shell at `~/.signalk/node_modules/@rhizomatics/signalk-einklabel-plugin`, as `npx esl-cli command --args` )
@@ -377,12 +391,24 @@ The label address previously discovered via `esl-cli scan`
 npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93
 ```
 
-If the label turns out to be a different size than the template (e.g. it's a 250x128 template on a 416x240 panel), that's normally rejected as a mismatch - add `--reframe` to fit it instead:
+If the label turns out to be a different size than the template (e.g. it's a 250x128 template on a 416x240 panel), it's cropped to fit by default - add `--reframe scale` to stretch it instead:
 
 ```bash
 npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --reframe scale
 ```
 
+If a label doesn't update, try sending it uncompressed to see whether compression is the cause:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --no-compress
+```
+
+If the image comes out mirrored, try each `--mirror` mode until it looks right, then set the same _Mirror_ option in the label's config:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --mirror horizontal
+```
+
 #### Test Template Without Updating Label
 
 This will work even if you don't have a label, or even bluetooth. (The `-u` can be left out if your SignalK server running locally on default ports).
@@ -537,6 +563,8 @@ USB_DENYLIST="0b05:190e"
 
 ## Other ESL and General eInk Resources
 
+### Components
+
 - [Open ePaper Link](https://openepaperlink.de) - Alternative open source firmware to flash onto eInk shelf labels, with Home Assistant integration.
 - [zhsunyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface
 - [WoLink](https://github.com/NickWaterton/Wolink) - Python interface and protocol analysis
@@ -545,9 +573,14 @@ USB_DENYLIST="0b05:190e"
 - [esp32-esl-system](https://github.com/giobauermeister/esp32-esl-system) - Docker and ESP32 based system for updating ESLs.
 - [hass-gicisky](https://github.com/eigger/hass-gicisky) - Home Assistant integration for Gicisky ESLs ( a similar vendor to Zhsunyco). Uses [imagespec](https://github.com/eigger/imagespec) for templating.
 - [ha-panda](https://github.com/moryoav/ha-panda) - Home Assistant integration for Panda ESLs ( a similar vendor to Zhsunyco).
+
+### Notes and Experiences
+
+- [Cabalist Gicisky Image Notes](https://github.com/Cabalist/gicisky_image_notes)
 - [Dmitry.gr](https://dmitry.gr/?r=05.Projects&proj=29.%20eInk%20Price%20Tags) - Personal site of an ESL hacker
 - [Aaron Christobel](https://www.youtube.com/@atc1441) - YouTube channel of an ESL hacker.
 - [rbaron.net](https://rbaron.net/blog/2022/07/29/Daisy-chaining-multiple-electronic-shelf-labels) - Blog of an early ESL hacker.
+  ### Retail
 - [Pimoroni](https://shop.pimoroni.com/collections/displays?tags=e-ink%20Displays) - All shapes and sizes of eInk displays, aimed at hackers, and with an [inky](https://github.com/pimoroni/inky) GitHub project to support them.
 - [WaveShare](https://www.waveshare.com/product/displays/e-paper.htm) - Wide range of eInk displays for hardware projects, not limited to ESLs.
 

package/dist/cli/index.d.ts

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { Colour } from "../devices/types";
+import { Colour, CompressionFormat } from "../devices/types";
 import { ReframeMode } from "../render/reframe";
+import { MirrorMode } from "../render/mirror";
 import { Binding } from "../render/binding";
 import { TemplateContext } from "../render/types";
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
 export declare const DEFAULT_SIGNALK_URLS: string[];
 export declare function parseColours(code: string): Colour[];
 export declare function parseReframeMode(value: string): ReframeMode;
+export declare function parseMirrorMode(value: string): MirrorMode;
+export declare function parseCompressionFormat(value: string): CompressionFormat;
 /** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
 export declare function assembleContext(opts: {
     url?: string;

package/dist/cli/index.js

@@ -4,6 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.program = exports.DEFAULT_SIGNALK_URLS = void 0;
 exports.parseColours = parseColours;
 exports.parseReframeMode = parseReframeMode;
+exports.parseMirrorMode = parseMirrorMode;
+exports.parseCompressionFormat = parseCompressionFormat;
 exports.assembleContext = assembleContext;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
@@ -13,6 +15,8 @@ const registry_1 = require("../devices/registry");
 const zhsunyco_1 = require("../devices/zhsunyco");
 const gicisky_1 = require("../devices/gicisky");
 const bleDiscovery_1 = require("../devices/bleDiscovery");
+const types_1 = require("../devices/types");
+const mirror_1 = require("../render/mirror");
 const svgRenderer_1 = require("../render/svgRenderer");
 const png_1 = require("../render/png");
 const binding_1 = require("../render/binding");
@@ -45,6 +49,18 @@ function parseReframeMode(value) {
     }
     return value;
 }
+function parseMirrorMode(value) {
+    if (!mirror_1.MIRROR_MODES.includes(value)) {
+        throw new Error(`unknown --mirror value "${value}" - expected one of ${mirror_1.MIRROR_MODES.join(", ")}`);
+    }
+    return value;
+}
+function parseCompressionFormat(value) {
+    if (!types_1.COMPRESSION_FORMATS.includes(value)) {
+        throw new Error(`unknown --compression-format value "${value}" - expected one of ${types_1.COMPRESSION_FORMATS.join(", ")}`);
+    }
+    return value;
+}
 /** Probes DEFAULT_SIGNALK_URLS in order and returns the first that answers a plain GET - used when -u/--url is omitted. */
 async function resolveDefaultUrl() {
     for (const candidate of exports.DEFAULT_SIGNALK_URLS) {
@@ -226,6 +242,9 @@ exports.program
     .option("--voffset <px>", "vertical pixel offset of the panel - overrides the looked-up model for unsupported hardware (requires --colours)", "0")
     .option("--colours <code>", "device colour palette for unsupported hardware: BW, BWR, or BWRY - overrides the looked-up model (uses --width/--height/--voffset)")
     .option("--reframe <mode>", "how to fit the rendered image onto the device's actual panel size when it doesn't match: crop (default - place at top-left, truncating or leaving the rest blank), scale (stretch the template to the panel), fixed (reject the mismatch instead)", "crop")
+    .option("--mirror <mode>", "flip the image before sending: none (default), horizontal, vertical, or both (rotate 180°)", "none")
+    .option("--no-compress", 'send the image uncompressed (zhsunyco; gicisky 7.5"/10.2" or --compression-format chunked - compression is on by default)')
+    .option("--compression-format <format>", 'gicisky wire format: auto (default - the model\'s usual format) or chunked (experimental - send a 4.2" BWR compressed like the 7.5"/10.2")', "auto")
     .option("--connect-timeout <seconds>", "BLE connect timeout before giving up on an attempt", "30")
     .option("--retries <n>", "number of paint attempts (including the first) before giving up", "3")
     .action(async (opts) => {
@@ -269,6 +288,9 @@ exports.program
             modelOverride,
             connectTimeoutMs,
             reframe: parseReframeMode(opts.reframe),
+            mirror: parseMirrorMode(opts.mirror),
+            compress: opts.compress,
+            compressionFormat: parseCompressionFormat(opts.compressionFormat),
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
@@ -287,7 +309,9 @@ exports.program
     .option("-f, --font <path>", "override a bundled font with this file (repeatable) - defaults to the bundled monospace/sans-serif/serif trio", 
 // See the -r/--require option above for why `| undefined` is needed here despite commander's typings.
 (value, previous = []) => [...previous, value])
+    .option("--mirror <mode>", "flip the PNG the same way paint --mirror would: none (default), horizontal, vertical, or both", "none")
     .action(async (opts) => {
+    const mirror = parseMirrorMode(opts.mirror);
     const svgSource = await (0, promises_1.readFile)(opts.template, "utf-8");
     const declared = (0, binding_1.readTemplateDimensions)(svgSource);
     const width = resolveDimension(opts.width, [declared.width], DEFAULT_RENDER_WIDTH);
@@ -295,7 +319,7 @@ exports.program
     const bindings = (0, binding_1.findBindings)(svgSource);
     const context = await assembleContext(opts, bindings);
     const renderer = opts.font ? new svgRenderer_1.SvgRenderer(opts.font) : new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = (0, mirror_1.mirrorBitmap)(await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR), mirror);
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 import { ServerAPI } from "@signalk/server-api";
 import { Colour, DiscoveredDevice } from "./devices/types";
 import { ReframeMode } from "./render/reframe";
+import { MirrorMode } from "./render/mirror";
+import { CompressionFormat } from "./devices/types";
 /**
  * Special `device` value meaning "every currently-known discovered device" instead of one specific
  * BLE address - lets a single `DeviceConfig` entry (one template, one trigger) broadcast to every
@@ -58,6 +60,16 @@ export interface DeviceConfig {
      * showing *something*, even off-size, beats a repaint that just fails outright.
      */
     reframe?: ReframeMode;
+    /** Flip the image before sending - for a panel whose layout is mirrored, or one mounted upside down (`"both"`). Unset means `"none"`. */
+    mirror?: MirrorMode;
+    /** Compress the upload (zhsunyco, and gicisky's chunked 7.5"/10.2" panels - ignored otherwise). Unset means on; turn off if a device fails to show compressed images. */
+    compress?: boolean;
+    /**
+     * Experimental opt-in wire format (gicisky only) - `"chunked"` sends a 4.2" BWR (or another plain
+     * two-plane panel) QuickLZ-compressed like the 7.5"/10.2". Unset means `"auto"`, the model's own
+     * format. See `CompressionFormat`.
+     */
+    compressionFormat?: CompressionFormat;
 }
 export interface PluginConfig {
     /**

package/dist/config.js

@@ -12,6 +12,8 @@ exports.configUiSchema = configUiSchema;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const mirror_1 = require("./render/mirror");
+const types_1 = require("./devices/types");
 const templateProviders_1 = require("./render/templateProviders");
 const resolveApiUrl_1 = require("./resolveApiUrl");
 /**
@@ -433,6 +435,27 @@ function configSchema(app, discovered = []) {
                             enum: ["crop", "scale", "fixed"],
                             default: "crop",
                         },
+                        mirror: {
+                            type: "string",
+                            title: "Mirror",
+                            description: "Flip the image if it shows up mirrored on the label. Both = rotate 180°, e.g. for a label mounted upside down.",
+                            enum: mirror_1.MIRROR_MODES,
+                            default: "none",
+                        },
+                        compress: {
+                            type: "boolean",
+                            title: 'Compress upload (Zhsunyco, Gicisky 7.5"/10.2")',
+                            description: "Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating.",
+                            default: true,
+                        },
+                        compressionFormat: {
+                            type: "string",
+                            title: "Wire format (Gicisky, experimental)",
+                            description: 'Auto: the model\'s usual format. Chunked: send compressed like the 7.5"/10.2" panels - may speed up a 4.2" BWR, ' +
+                                "but untested on current firmware. Needs Compress upload on to actually compress. Switch back to Auto if the label stops updating.",
+                            enum: types_1.COMPRESSION_FORMATS,
+                            default: "auto",
+                        },
                     },
                 },
             },
@@ -446,6 +469,8 @@ function configUiSchema() {
                 description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
                 reframe: { "ui:widget": "radio" },
+                mirror: { "ui:widget": "radio" },
+                compressionFormat: { "ui:widget": "radio" },
             },
         },
     };

package/dist/devices/bleBackend.js

@@ -168,6 +168,8 @@ async function ensureDeviceVisible(bleApi, pluginId, address, timeoutMs) {
         throw new Error(`device ${address} isn't visible to the SignalK BLE Manager yet (out of range, asleep, or never seen) after waiting ${timeoutMs}ms`);
     }
 }
+/** Upper bound on how long a timed-out `bleApi.connectGATT()` is given to settle server-side before a retry - see `bleApiBackend`. */
+const CONNECT_SETTLE_GRACE_MS = 30000;
 let bleManagerQueue = Promise.resolve();
 /**
  * Runs `fn` only once every earlier caller has finished, so paints to different devices never hold
@@ -209,7 +211,20 @@ function bleApiBackend(bleApi, pluginId) {
                 // background) so a caller retrying straight away - `withRetries` - can't race it with a new
                 // `connectGATT()` and get rejected with "has a GATT claim in progress" for its trouble.
                 await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
-                void connecting.then((c) => c.disconnect()).catch(() => { });
+                // ...except a claim still *connecting* isn't in the server's claim table yet, only its pending
+                // set, which `releaseGATTDevice` doesn't touch - so while the server's own connect is still in
+                // flight, a retry's `connectGATT()` is rejected outright with "has a GATT claim in progress".
+                // Give that connect a bounded chance to settle first, so the retry gets a clean slate.
+                const late = await Promise.race([
+                    connecting.catch(() => undefined),
+                    (0, bleDiscovery_1.sleep)(Math.min(timeoutMs, CONNECT_SETTLE_GRACE_MS)).then(() => undefined),
+                ]);
+                if (late) {
+                    await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), late.disconnect()]);
+                }
+                else {
+                    void connecting.then((c) => c.disconnect()).catch(() => { });
+                }
                 throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
             }
             return withSessionWatchdog(conn, GATT_SESSION_WATCHDOG_MS, async () => {

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;
@@ -69,9 +70,9 @@ class GiciskyDriver {
                 : `gicisky device reports unrecognised deviceId 0x${pid.toString(16).padStart(4, "0")} - ` +
                     "pass --width/--height/--voffset/--colours to describe it manually");
         }
-        const layout = (pid !== undefined && layout_1.GICISKY_PID_LAYOUT[pid]) || (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);

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" };
+}