@rhizomatics/signalk-einklabel-plugin 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# 1.2.1
+
+- Additional tide template for 296x128
+
+# 1.2.0
+
+- Added support for Gicisky labels (also known by other brands), tested with a 2.9" BWRY model
+- CLI render command use template height and width as defaults, can still be overridden by arguments to preview particular size of label
+- CLI paint commands use label height and width as defaults, overridden by arguments if needed
+- CLI paint command now has a `--reframe` option for labels that don't match template size, so can quickly test a label without having perfect template right away
+
+# 1.1.0
+
+- Label images can now optionally be emailed to an address every time they change, including a table of fields and values used to complete the template, or the prompt if genai based
+
 # 1.0.0
 
 ## Full Release

package/README.md

@@ -6,6 +6,7 @@
 [![codecov](https://img.shields.io/codecov/c/github/rhizomatics/signalk-einklabel-plugin)](https://codecov.io/gh/rhizomatics/signalk-einklabel-plugin)
 [![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-blue.svg)](https://github.com)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/LICENSE)
+[![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
 
 A SignalK plugin to display data from SignalK paths, Resource APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates, or optionally created from a crafted prompt by GenAI if the companion [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin) is installed.
 
@@ -17,7 +18,7 @@ Electronic Shelf Labels are [eInk](https://en.wikipedia.org/wiki/E_Ink) devices
 
 Since they are designed to be used in large quantity in small shops, they are cheap and simple devices. Earlier models required dedicated controllers, or updates over Wifi or NFC, whereas many modern ones are standalone BLE devices that can be updated from a phone or server.
 
-Being battery operated, they can be stuck on anywhere without wiring - the only location constraints are bluetooth range, visibility (they need ambient light since the display is more like paper than a traditional lit-up electronic display) and out of the weather since the devices are intended for indoor use.
+Being battery operated, they can be stuck on anywhere without wiring - the only location constraints are bluetooth range, visibility (they need ambient light since the display is more like paper than a traditional lit-up electronic display) and, for some labels, being out of the weather if they are not waterproof, although IP65 labels are available.
 
 ## Pre-requisites
 
@@ -34,8 +35,9 @@ Most of requirements below are to make SignalK work with Bluetooth Low Energy, w
 
 - Bluetooth adapters for Linux can be tricky, TP-Link UB400 and Asus USB-BT500 are two well-known and available ones
 - Some Raspberry Pi models come with suitable Bluetooth built in
-- Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
-- Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
+
+> - Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
+> - Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
 
 3. `bluez` package installed in Linux
 
@@ -44,7 +46,7 @@ Most of requirements below are to make SignalK work with Bluetooth Low Energy, w
 
 4. One or more supported Electronic Shelf Labels
 
-- The label used for testing this is the [Zhsunyco 3.7" BWRY](https://www.aliexpress.com/item/1005010050104435.html)
+- The labels used for testing this are the [Zhsunyco 3.7" BWRY](https://www.aliexpress.com/item/1005010050104435.html) and a [Gicisky 2.9" BWRY](https://www.aliexpress.com/item/1005012933325056.html)
 
 5. Correct time zone set on server if local time is to be shown on display
 
@@ -147,6 +149,14 @@ Also known as 'Suny' and 'WOLink'.
 
 Python code for a variety of their labels at https://github.com/roxburghm/zhsunyco-esl and https://github.com/NickWaterton/Wolink
 
+### Gicisky
+
+Known by other names, e.g. 'Picksmart', and with white label brands
+
+- BLE ESLs
+  - Official store is on [AliExpress](https://www.aliexpress.com/store/911771479/pages/all-items.html?productGroupId=40000001654819&spm=a2g0o.store_pc_home.pcShopHead_6000727597996.1_1)
+  - Cheapest labels under £10 GBP / $13 USD
+
 ## Templating
 
 Templates are simply SVG files, to which expressions can be added to use SignalK data, with options to make it easier to read, like rounding or simplifying dates and times. The template can have sample data in the placeholder, so is easy to layout and visualize.
@@ -270,7 +280,15 @@ See also the commands useful for debugging under [Developing Templates]
 - `render` - transform an SVG template and data into a PNG
 - `paint` - render an SVG template and data to a selected ESL
 
-The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line with `-w/--width`, `--height`, `--voffset` and `--colours`. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+
+Left unset, both `render` and `paint` default `-w/--width`/`--height` to the template's own declared `width`/`height` (or `viewBox`) - neither command connects to a device just to size the render, since that would mean an extra BLE connect ahead of `paint`'s own, and doing two back-to-back is exactly the kind of churn that trips real BLE hardware.
+
+`paint` also takes `--reframe <mode>`, applied once it has connected and identified the device, for when the rendered image doesn't come out the same size as its actual panel:
+
+- `fixed` (default) - no adjustment; a size mismatch is rejected with an error, as it always has been
+- `scale` - stretches the rendered image onto the panel's exact dimensions (independently per axis, not preserving aspect ratio)
+- `crop` - keeps pixels 1:1, placed from the top-left; a bigger render is truncated to fit, a smaller one leaves the extra panel space blank
 
 `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.
 
@@ -328,8 +346,40 @@ The `esl-cli` can be used to debug and validate templates quickly:
 - `fields` - List the fields in the template, with the source specification and the rendered data value
 - `field` - Accept a source specification (outside of any template context) and return the rendered value if available
 
+Use `--help` to get the full set of arguments for any of the commands.
+
 ### Examples
 
+#### Paint Image Directly
+
+The label address previously discovered via `esl-cli scan`
+
+```bash
+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:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --reframe scale
+```
+
+#### 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).
+
+```bash
+npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -u http://localhost
+```
+
+and this version will work even without a running SignalK server, using some pre-packaged example data:
+
+```bash
+npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -e examples
+```
+
+
+
 #### List all Fields and Rendered Values
 
 ```bash

package/dist/cli/index.d.ts

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { Colour } from "../devices/types";
+import { ReframeMode } from "../render/reframe";
 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;
 /** 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

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.program = exports.DEFAULT_SIGNALK_URLS = void 0;
 exports.parseColours = parseColours;
+exports.parseReframeMode = parseReframeMode;
 exports.assembleContext = assembleContext;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
@@ -10,6 +11,7 @@ const commander_1 = require("commander");
 const xmldom_1 = require("@xmldom/xmldom");
 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 svgRenderer_1 = require("../render/svgRenderer");
 const png_1 = require("../render/png");
@@ -20,6 +22,7 @@ const liveContext_1 = require("./liveContext");
 const httpJson_1 = require("../httpJson");
 const log_1 = require("./log");
 (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
+(0, registry_1.registerDriver)(new gicisky_1.GiciskyDriver());
 const VENDOR_IDENTIFY_TIMEOUT_MS = 30000;
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
 exports.DEFAULT_SIGNALK_URLS = ["http://localhost", "http://localhost:3000", "https://localhost"];
@@ -35,6 +38,13 @@ function parseColours(code) {
     }
     return colours;
 }
+const REFRAME_MODES = ["fixed", "scale", "crop"];
+function parseReframeMode(value) {
+    if (!REFRAME_MODES.includes(value)) {
+        throw new Error(`unknown --reframe value "${value}" - expected one of ${REFRAME_MODES.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) {
@@ -49,6 +59,14 @@ async function resolveDefaultUrl() {
     }
     throw new Error(`no -u/--url given and none of ${exports.DEFAULT_SIGNALK_URLS.join(", ")} answered - specify the server explicitly with -u/--url`);
 }
+const DEFAULT_RENDER_WIDTH = 416;
+const DEFAULT_RENDER_HEIGHT = 240;
+/** Shared by every command's -w/--width and --height: an explicit flag always wins; otherwise the first defined value in `sources` (in order); otherwise a generic last-resort default. */
+function resolveDimension(explicit, sources, fallback) {
+    if (explicit !== undefined)
+        return Number(explicit);
+    return sources.find((value) => value !== undefined) ?? fallback;
+}
 /** 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. */
 async function assembleContext(opts, bindings) {
     if (opts.exampleData)
@@ -148,7 +166,7 @@ exports.program
 exports.program
     .command("scan")
     .description("Scan for supported BLE ESL devices across all registered vendor drivers")
-    .option("-d, --duration <seconds>", "scan duration in seconds", "10")
+    .option("-d, --duration <seconds>", "scan duration in seconds", "30")
     .option("-a, --all-devices", "list every nearby BLE device, not just ones a registered driver recognised - unmatched devices show address/name/mfr/rssi only, since there's no driver to do a vendor-specific read like battery")
     .action(async (opts) => {
     const durationMs = Number(opts.duration) * 1000;
@@ -203,10 +221,11 @@ exports.program
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .option("-k, --aes-key <hex>", "AES-128 key for device authentication, as 32 hex characters - defaults to the vendor's stock key if omitted")
-    .option("-w, --width <px>", "render width", "416")
-    .option("--height <px>", "render height", "240")
+    .option("-w, --width <px>", "render width - defaults to the template's declared width/viewBox - see --reframe for fitting onto a differently-sized panel")
+    .option("--height <px>", "render height - defaults to the template's declared height/viewBox - see --reframe for fitting onto a differently-sized panel")
     .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: fixed (default - reject the mismatch, as always), scale (stretch the template to the panel), crop (place at top-left, truncating or leaving the rest blank)", "fixed")
     .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) => {
@@ -215,19 +234,30 @@ exports.program
     if (!driver) {
         throw new Error(`no driver registered for vendor "${vendor}"`);
     }
+    const svgSource = await (0, promises_1.readFile)(opts.template, "utf-8");
+    // Defaults from the template's own declared size, same as `render` - not from the device's real
+    // panel size, which would need its own identify connect ahead of driver.paint()'s own connect;
+    // two back-to-back BLE connects on the same device is exactly the kind of churn that trips BlueZ
+    // (confirmed: identifyDevice() does a full connect+disconnect for zhsunyco, to read its PID off a
+    // GATT characteristic - immediately followed by paint()'s own connect crashed with a raw D-Bus
+    // "recipient disconnected from message bus without replying" on real hardware). --reframe below
+    // covers a mismatch against the real panel size within paint()'s own single connect instead.
+    const declared = (0, binding_1.readTemplateDimensions)(svgSource);
+    const width = resolveDimension(opts.width, [declared.width], DEFAULT_RENDER_WIDTH);
+    const height = resolveDimension(opts.height, [declared.height], DEFAULT_RENDER_HEIGHT);
     const modelOverride = opts.colours
         ? {
             label: "manual override",
-            width: Number(opts.width),
-            height: Number(opts.height),
+            width,
+            height,
             voffset: Number(opts.voffset),
             colours: parseColours(opts.colours),
         }
         : undefined;
-    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, "utf-8"));
+    const bindings = (0, binding_1.findBindings)(svgSource);
     const context = await assembleContext(opts, bindings);
     const renderer = new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height), (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
     const connectTimeoutMs = Number(opts.connectTimeout) * 1000;
     await (0, bleDiscovery_1.withRetries)(Number(opts.retries), async (attempt) => {
         if (attempt > 1) {
@@ -238,6 +268,7 @@ exports.program
             aesKey: opts.aesKey,
             modelOverride,
             connectTimeoutMs,
+            reframe: parseReframeMode(opts.reframe),
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
@@ -251,16 +282,20 @@ exports.program
     exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
-    .option("-w, --width <px>", "render width", "416")
-    .option("--height <px>", "render height", "240")
+    .option("-w, --width <px>", "render width - defaults to the template's declared width/viewBox")
+    .option("--height <px>", "render height - defaults to the template's declared height/viewBox")
     .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])
     .action(async (opts) => {
-    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, "utf-8"));
+    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);
+    const height = resolveDimension(opts.height, [declared.height], DEFAULT_RENDER_HEIGHT);
+    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, Number(opts.width), Number(opts.height), (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });

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

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export declare function frameChunkedPlanes(planeA: Buffer, planeB: Buffer): Buffer;

package/dist/devices/gicisky/compression.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.frameChunkedPlanes = frameChunkedPlanes;
+const CHUNK_SIZE = 64;
+const RAW_CHUNK_TAG = 0x74;
+function chunkRaw(data) {
+    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);
+    }
+    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.
+ */
+function frameChunkedPlanes(planeA, planeB) {
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(planeB.length, 0);
+    return Buffer.concat([header, chunkRaw(planeA), chunkRaw(planeB)]);
+}

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

@@ -0,0 +1,10 @@
+import { Bitmap } from "../../render/types";
+import { DeviceMetadata } from "../types";
+import { GiciskyLayout } from "./layout";
+/**
+ * Quantises a common RGBA bitmap and packs it into the wire format this model's `GiciskyLayout`
+ * calls for. Mirrors `GiciskyClient._make_image_packet` (hass-gicisky's `writer.py`), except
+ * 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;

package/dist/devices/gicisky/encode.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBitmap = encodeBitmap;
+const compression_1 = require("./compression");
+/**
+ * Nearest-colour classification into a device's actual palette - same decision tree and
+ * fallback-through-the-palette approach as `zhsunyco/encode.ts`'s `nearestColour`, duplicated
+ * rather than shared since each vendor package here is self-contained (see README's
+ * "ESL Vendor - Sub-package per vendor").
+ */
+const FALLBACK = {
+    yellow: "red",
+    red: "black",
+};
+function classifyColour(r, g, b, supported) {
+    let colour = "black";
+    if (r > 150 && g > 150 && b > 150)
+        colour = "white";
+    else if (r > 150 && g > 100 && b < 80)
+        colour = "yellow";
+    else if (r > 150 && g < 80 && b < 80)
+        colour = "red";
+    while (!supported.includes(colour)) {
+        const fallback = FALLBACK[colour];
+        if (!fallback)
+            break;
+        colour = fallback;
+    }
+    return colour;
+}
+/**
+ * Rotates a bitmap 90 degrees counter-clockwise once (in the raster sense: x right, y down) -
+ * equivalent to Pillow's `Image.rotate(90, expand=True)` / `numpy.rot90`, which the reference
+ * driver relies on. `rotateBitmap` below composes this to cover 0/90/180/270.
+ */
+function rotate90(bitmap) {
+    const { width, height, data } = bitmap;
+    const outWidth = height;
+    const outHeight = width;
+    const out = new Uint8Array(outWidth * outHeight * 4);
+    for (let oy = 0; oy < outHeight; oy++) {
+        for (let ox = 0; ox < outWidth; ox++) {
+            const ix = width - 1 - oy;
+            const iy = ox;
+            const srcOffset = (iy * width + ix) * 4;
+            const dstOffset = (oy * outWidth + ox) * 4;
+            out.set(data.subarray(srcOffset, srcOffset + 4), dstOffset);
+        }
+    }
+    return { width: outWidth, height: outHeight, data: out };
+}
+function rotateBitmap(bitmap, degrees) {
+    let result = bitmap;
+    for (let turns = degrees / 90; turns > 0; turns--) {
+        result = rotate90(result);
+    }
+    return result;
+}
+/**
+ * Packs one 1-bit plane, MSB-first, row-major (8 pixels/byte) - `predicate` decides whether a
+ * given pixel's classified colour sets the bit.
+ */
+function packPlane(bitmap, layout, supported, predicate) {
+    const { width, height } = bitmap;
+    const bytesPerRow = Math.ceil(width / 8);
+    const plane = Buffer.alloc(bytesPerRow * height);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const sx = layout.mirrorX ? width - 1 - x : x;
+            const sy = layout.mirrorY ? height - 1 - y : y;
+            const offset = (sy * width + sx) * 4;
+            const colour = classifyColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], supported);
+            if (predicate(colour)) {
+                const byteIndex = y * bytesPerRow + (x >> 3);
+                plane[byteIndex] |= 0x80 >> (x % 8);
+            }
+        }
+    }
+    return plane;
+}
+/** 2-bit packing across the full palette, MSB-first, 4 pixels/byte, row-major: black=0, white=1, yellow=2, red=3. */
+const FOUR_COLOUR_CODE = { black: 0, white: 1, yellow: 2, red: 3 };
+function packFourColour(bitmap, layout, supported) {
+    const { width, height } = bitmap;
+    const pixelsPerByte = 4;
+    const bytesPerRow = Math.ceil(width / pixelsPerByte);
+    const plane = Buffer.alloc(bytesPerRow * height);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const sx = layout.mirrorX ? width - 1 - x : x;
+            const sy = layout.mirrorY ? height - 1 - y : y;
+            const offset = (sy * width + sx) * 4;
+            const colour = classifyColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], supported);
+            const code = FOUR_COLOUR_CODE[colour];
+            const byteIndex = y * bytesPerRow + Math.floor(x / pixelsPerByte);
+            const shift = 6 - (x % pixelsPerByte) * 2;
+            plane[byteIndex] |= code << shift;
+        }
+    }
+    return plane;
+}
+/**
+ * Quantises a common RGBA bitmap and packs it into the wire format this model's `GiciskyLayout`
+ * calls for. Mirrors `GiciskyClient._make_image_packet` (hass-gicisky's `writer.py`), except
+ * 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) {
+    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)`);
+    }
+    if (bitmap.width !== metadata.width || bitmap.height !== metadata.height) {
+        throw new Error(`gicisky paint: bitmap is ${bitmap.width}x${bitmap.height}, device "${metadata.label}" expects ${metadata.width}x${metadata.height}`);
+    }
+    const rotated = rotateBitmap(bitmap, layout.rotation);
+    const supported = metadata.colours;
+    if (layout.fourColour) {
+        return packFourColour(rotated, layout, supported);
+    }
+    const isWhite = (colour) => (layout.invertLuminance ? colour !== "white" : colour === "white");
+    const bwPlane = packPlane(rotated, layout, supported, isWhite);
+    if (!supported.includes("red")) {
+        return bwPlane;
+    }
+    const redPlane = packPlane(rotated, layout, supported, (colour) => colour === "red");
+    if (layout.packing === "chunked") {
+        return (0, compression_1.frameChunkedPlanes)(bwPlane, redPlane);
+    }
+    return Buffer.concat([bwPlane, redPlane]);
+}

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

@@ -0,0 +1,11 @@
+import { Device } from "@naugehyde/node-ble";
+import { Bitmap } from "../../render/types";
+import { DeviceMetadata, DiscoveredDevice, VendorDeviceConfig, VendorDriver } from "../types";
+export declare class GiciskyDriver implements VendorDriver {
+    readonly vendor = "gicisky";
+    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>;
+    paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
+}