@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.2.0

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
+exports.RENDER_FALLBACK_TEMPLATE_NAME = exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
 exports.defaultConfig = defaultConfig;
 exports.readCurrentConfig = readCurrentConfig;
 exports.healNestedConfig = healNestedConfig;
@@ -12,6 +12,7 @@ exports.configUiSchema = configUiSchema;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const templateProviders_1 = require("./render/templateProviders");
 const resolveApiUrl_1 = require("./resolveApiUrl");
 /**
  * Special `device` value meaning "every currently-known discovered device" instead of one specific
@@ -31,6 +32,18 @@ exports.ALL_DEVICES = "ALL";
  * `templates/.assets/lunar_phases`) just to keep a binding the override never touched working.
  */
 exports.BUNDLED_TEMPLATES_DIR = (0, path_1.join)(__dirname, "..", "templates");
+/**
+ * Bundled template family pushed instead of a device's real content whenever a repaint fails - a broken
+ * hand-authored template, or a registered `TemplateProvider`'s `render()` rejecting (e.g.
+ * `@rhizomatics/signalk-einklabel-genai-plugin`'s LLM call failing) - see `considerRepaint` in
+ * `./repaintScheduler.ts`. Generic on purpose: it has no idea *why* the render failed, only that it
+ * did, and that the previous, possibly now-wrong, content must never be left on screen unmarked.
+ *
+ * Dot-prefixed like `.assets`/`.blank` so `listTemplateFamilies` excludes it from the "Template"
+ * dropdown - it's an internal fallback mechanism, not something a user should ever pick as a device's
+ * own template.
+ */
+exports.RENDER_FALLBACK_TEMPLATE_NAME = ".error";
 const SIGNALK_HOME_DIR = (0, path_1.join)((0, os_1.homedir)(), ".signalk");
 const DEFAULT_TEMPLATES_DIR = (0, path_1.join)(SIGNALK_HOME_DIR, "einklabel", "templates");
 function defaultConfig() {
@@ -117,18 +130,21 @@ function healNestedConfig(app) {
     });
 }
 /**
- * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
- * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative
- * path is resolved against `~/.signalk` (where SignalK itself stores its config by default), and
- * an absolute path is used as-is.
+ * Resolves a user-facing `<x>Dir` setting to an actual directory, mirroring signalk-parquet's
+ * `outputDirectory` convention: empty means `defaultDir`, a relative path is resolved against
+ * `~/.signalk` (where SignalK itself stores its config by default), and an absolute path is used as-is.
  */
-function resolveTemplatesDir(templatesDir) {
-    const trimmed = templatesDir?.trim();
+function resolveDir(dir, defaultDir) {
+    const trimmed = dir?.trim();
     if (!trimmed) {
-        return DEFAULT_TEMPLATES_DIR;
+        return defaultDir;
     }
     return (0, path_1.isAbsolute)(trimmed) ? trimmed : (0, path_1.join)(SIGNALK_HOME_DIR, trimmed);
 }
+/** See `resolveDir` - `templatesDir`'s own resolution. */
+function resolveTemplatesDir(templatesDir) {
+    return resolveDir(templatesDir, DEFAULT_TEMPLATES_DIR);
+}
 /**
  * Enum for the combined "device" field, built from recently scanned devices - including ones a
  * driver identified as its vendor but whose PID isn't in its metadata table yet (clearly labelled,
@@ -219,11 +235,18 @@ function listTemplateFamilies(dir) {
         .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && listTemplateVariants((0, path_1.join)(dir, entry.name)).length > 0)
         .map((entry) => entry.name);
 }
-/** Local templates (files or template-family directories) take priority over a same-named bundled one; both show up as options. */
+/**
+ * Local templates (files or template-family directories) take priority over a same-named bundled one;
+ * both show up as options, followed by every registered `TemplateProvider`'s own entries (e.g.
+ * `signalk-einklabel-genai-plugin` contributing `"forecast (GenAI)"` - see `./render/templateProviders.ts`)
+ * - so a provider-backed "template" is picked from this exact same dropdown, distinguished only by its
+ * `suffix`, with no separate render-mode field at all.
+ */
 function templateNameOptions(templatesDir) {
     const local = [...listSvgFiles(templatesDir), ...listTemplateFamilies(templatesDir)];
     const bundled = [...listSvgFiles(exports.BUNDLED_TEMPLATES_DIR), ...listTemplateFamilies(exports.BUNDLED_TEMPLATES_DIR)].filter((name) => !local.includes(name));
-    return [...local, ...bundled];
+    const provided = (0, templateProviders_1.allTemplateProviders)().flatMap((provider) => provider.listTemplates());
+    return [...local, ...bundled, ...provided];
 }
 function sameColours(a, b) {
     if (a.length !== b.length)
@@ -350,6 +373,12 @@ function configSchema(app, discovered = []) {
                                 'address, or "All discovered devices" to paint this same template/trigger to every device the plugin currently ' +
                                 "knows about - simplest for a single label, and also covers several identical labels without listing each one.",
                         }, deviceValues, deviceLabels),
+                        description: {
+                            type: "string",
+                            title: "Location/description (optional)",
+                            description: 'Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m ' +
+                                'in poor light" - available to any template as source=einklabel,path=description or source=label,path=description.',
+                        },
                         templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: {
                             type: "string",
@@ -392,6 +421,7 @@ function configUiSchema() {
     return {
         devices: {
             items: {
+                description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
             },
         },

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

package/dist/devices/gicisky/index.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GiciskyDriver = void 0;
+const bleDiscovery_1 = require("../bleDiscovery");
+const metadata_1 = require("./metadata");
+const layout_1 = require("./layout");
+const encode_1 = require("./encode");
+const reframe_1 = require("../../render/reframe");
+const protocol_1 = require("./protocol");
+const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+const DEFAULT_PAINT_CONNECT_TIMEOUT_MS = 60000;
+const ACK_TIMEOUT_MS = 15000;
+/** Fallback if a device's `requestBlockSize` ack doesn't decode - matches the block size both reference drivers assume. */
+const DEFAULT_BLOCK_SIZE = 244;
+/** Bytes of image data per chunk: block size minus the 4-byte part-index header each chunk is prefixed with. */
+const PART_INDEX_HEADER_LENGTH = 4;
+const MAX_STALLED_REPEATS = 3;
+class GiciskyDriver {
+    constructor() {
+        this.vendor = "gicisky";
+    }
+    matchesAdvertisement(_name, manufacturerId) {
+        return manufacturerId === protocol_1.GICISKY_MANUFACTURER_ID;
+    }
+    metadataForPid(pid) {
+        return metadata_1.GICISKY_PID_METADATA.find((model) => model.pid === pid);
+    }
+    supportedDevices() {
+        return metadata_1.GICISKY_PID_METADATA;
+    }
+    async identifyDevice(device, address, name, manufacturerId, manufacturerData) {
+        const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
+        return {
+            address,
+            name,
+            vendor: this.vendor,
+            pid: info?.deviceId,
+            metadata: info ? this.metadataForPid(info.deviceId) : undefined,
+            manufacturerId,
+            batteryMv: info?.batteryMv,
+            rssi: await device
+                .getRSSI()
+                .then((value) => (value === undefined ? undefined : Number(value)))
+                .catch(() => undefined),
+        };
+    }
+    async paint(bitmap, config) {
+        const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+        try {
+            const adapter = await bluetooth.defaultAdapter();
+            const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, config.address, DEVICE_DISCOVERY_TIMEOUT_MS);
+            /**
+             * Unlike zhsunyco, there's no GATT characteristic that reports the device's PID on demand -
+             * the only source for it is the advertisement, cached on the `Device` object by BlueZ from
+             * the last time it was seen (the same cache `identifyDevice`/a scan reads, just without
+             * connecting first - see `forEachAdvertisedDevice` in `bleDiscovery.ts`).
+             */
+            const manufacturerData = await device
+                .getManufacturerData()
+                .then((data) => data[protocol_1.GICISKY_MANUFACTURER_ID.toString()])
+                .catch(() => undefined);
+            const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
+            const metadata = config.modelOverride
+                ? { pid: info?.deviceId ?? 0, ...config.modelOverride }
+                : info
+                    ? this.metadataForPid(info.deviceId)
+                    : undefined;
+            if (!metadata) {
+                throw new Error(info === undefined
+                    ? "gicisky device has no cached advertisement to identify it from - scan for it first, or pass --width/--height/--voffset/--colours to describe it manually"
+                    : `gicisky device reports unrecognised deviceId 0x${info.deviceId.toString(16).padStart(4, "0")} - ` +
+                        "pass --width/--height/--voffset/--colours to describe it manually");
+            }
+            const layout = (info && layout_1.GICISKY_PID_LAYOUT[info.deviceId]) || (0, layout_1.defaultLayoutFor)(metadata.colours);
+            const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "fixed");
+            const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout);
+            await (0, bleDiscovery_1.connectWithTimeout)(device, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+            try {
+                const gatt = await device.gatt();
+                const { cmd, img } = await findCommandAndImageCharacteristics(gatt);
+                await cmd.startNotifications();
+                try {
+                    const startAck = await writeAndAwaitAck(cmd, cmd, Buffer.from([0x01]));
+                    const chunkSize = ((0, protocol_1.decodeBlockSize)(startAck) ?? DEFAULT_BLOCK_SIZE) - PART_INDEX_HEADER_LENGTH;
+                    await writeAndAwaitAck(cmd, cmd, (0, protocol_1.writeScreenCommand)(payload.length, layout.packing === "chunked"));
+                    const startImageAck = await writeAndAwaitAck(cmd, cmd, Buffer.from([0x03]));
+                    const started = (0, protocol_1.decodeTransferAck)(startImageAck);
+                    if (!started?.ok) {
+                        throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
+                    }
+                    let part = started.nextPart;
+                    let lastPart = -1;
+                    let repeats = 0;
+                    while (part * chunkSize < payload.length) {
+                        const chunk = payload.subarray(part * chunkSize, Math.min(part * chunkSize + chunkSize, payload.length));
+                        const ack = await writeAndAwaitAck(img, cmd, (0, protocol_1.imageChunkPacket)(part, chunk));
+                        const decoded = (0, protocol_1.decodeTransferAck)(ack);
+                        if (!decoded?.ok) {
+                            throw new Error(`gicisky device reported an error transferring image part ${part}: ${ack.toString("hex")}`);
+                        }
+                        if (decoded.nextPart === lastPart) {
+                            repeats++;
+                            if (repeats >= MAX_STALLED_REPEATS) {
+                                throw new Error(`gicisky image transfer stalled - device kept re-requesting part ${decoded.nextPart}`);
+                            }
+                        }
+                        else {
+                            repeats = 0;
+                            lastPart = decoded.nextPart;
+                        }
+                        part = decoded.nextPart;
+                    }
+                }
+                finally {
+                    await cmd.stopNotifications().catch(() => { });
+                }
+            }
+            finally {
+                await device.disconnect();
+            }
+        }
+        finally {
+            destroy();
+        }
+    }
+}
+exports.GiciskyDriver = GiciskyDriver;
+/**
+ * Walks every service whose UUID starts `0000f`, collecting their characteristics and sorting by
+ * 16-bit UUID value - mirrors both reference drivers, which locate their command/image
+ * characteristics this way rather than by a hardcoded service UUID (see `protocol.ts`).
+ */
+async function findCommandAndImageCharacteristics(gatt) {
+    const candidates = [];
+    for (const serviceUuid of await gatt.services()) {
+        if (!serviceUuid.toLowerCase().startsWith(protocol_1.CANDIDATE_SERVICE_UUID_PREFIX)) {
+            continue;
+        }
+        const service = await gatt.getPrimaryService(serviceUuid);
+        for (const charUuid of await service.characteristics()) {
+            candidates.push({ uuid: charUuid, char: await service.getCharacteristic(charUuid) });
+        }
+    }
+    candidates.sort((a, b) => parseInt(a.uuid.slice(4, 8), 16) - parseInt(b.uuid.slice(4, 8), 16));
+    if (candidates.length < 2) {
+        throw new Error(`gicisky device exposes ${candidates.length} candidate characteristic(s) under a "0000f..." service, expected at least 2`);
+    }
+    return { cmd: candidates[0].char, img: candidates[1].char };
+}
+/** Writes `data` to `writeChar`, then awaits the next notification on `notifyChar` (which may be the same characteristic). */
+function writeAndAwaitAck(writeChar, notifyChar, data) {
+    const ack = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            notifyChar.removeListener("valuechanged", onValue);
+            reject(new Error("gicisky device did not acknowledge in time"));
+        }, ACK_TIMEOUT_MS);
+        function onValue(value) {
+            clearTimeout(timer);
+            resolve(value);
+        }
+        notifyChar.once("valuechanged", onValue);
+    });
+    return writeChar.writeValueWithoutResponse(data).then(() => ack);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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 -
+ * `DeviceMetadata.width`/`.height` is the pre-rotation "visual" canvas (what a template is
+ * designed at); this table says how `encode.ts` turns that into the physical byte layout each
+ * model actually expects. Transcribed from `DeviceEntry`/`GiciskyClient._make_image_packet` in
+ * hass-gicisky's `gicisky_ble/devices.py` and `gicisky_ble/writer.py`.
+ */
+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. */
+ | "chunked"
+/**
+ * A panel this driver can identify (for `scan`/discovery) but can't paint correctly yet - either
+ * its vendor-firmware "compressed" line framing doesn't reconcile with the row-major bit-packing
+ * `_make_image_packet` otherwise produces (the 3.7" panel, and the 7.5" panel on pre-`0x8101`
+ * firmware, both of which use this legacy `compression=True` mode rather than `compression2`),
+ * or it needs a resize/resample step this driver doesn't implement (the TFT panel).
+ */
+ | "unsupported";
+export interface GiciskyLayout {
+    /** Degrees the composed image is rotated (always a multiple of 90) before bit-packing. */
+    rotation: 0 | 90 | 180 | 270;
+    mirrorX: boolean;
+    mirrorY: boolean;
+    /** Swaps which bit value means "white" in the BW plane - some panels' controllers wire the panel's polarity the other way round. */
+    invertLuminance: boolean;
+    /** 2 bits/pixel across the device's full 4-colour palette, rather than separate 1-bit BW/red planes. */
+    fourColour: boolean;
+    packing: GiciskyPacking;
+}
+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;

package/dist/devices/gicisky/layout.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GICISKY_PID_LAYOUT = void 0;
+exports.defaultLayoutFor = defaultLayoutFor;
+const DEFAULT_LAYOUT = {
+    rotation: 0,
+    mirrorX: false,
+    mirrorY: false,
+    invertLuminance: false,
+    fourColour: false,
+    packing: "plain",
+};
+exports.GICISKY_PID_LAYOUT = {
+    0x00a0: { ...DEFAULT_LAYOUT, packing: "unsupported" },
+    0x000b: { ...DEFAULT_LAYOUT, rotation: 270, mirrorX: true },
+    0x010b: { ...DEFAULT_LAYOUT, rotation: 270, mirrorX: true },
+    0x0028: { ...DEFAULT_LAYOUT, rotation: 90 },
+    0x0033: { ...DEFAULT_LAYOUT, rotation: 90 },
+    0x002e: { ...DEFAULT_LAYOUT, rotation: 90, fourColour: true },
+    0x022b: { ...DEFAULT_LAYOUT, rotation: 180, mirrorX: true, packing: "unsupported" },
+    0x004b: { ...DEFAULT_LAYOUT },
+    0x004e: { ...DEFAULT_LAYOUT, fourColour: true },
+    /**
+     * Only the newer (post-`0x8101`) firmware's `compression2` framing is implemented (see
+     * `packing: "chunked"` above) - a 7.5" panel still on `0x8101` needs the legacy `compression`
+     * framing this driver doesn't support yet, and `paint()` has no way to tell the two apart
+     * without re-reading the advertised firmware version at paint time.
+     */
+    0x012b: { ...DEFAULT_LAYOUT, mirrorY: true, invertLuminance: true, packing: "chunked" },
+    0x008b: { ...DEFAULT_LAYOUT, packing: "chunked" },
+};
+/** Best-effort layout for a `modelOverride`d PID this table has no entry for - assumes the common case. */
+function defaultLayoutFor(colours) {
+    return { ...DEFAULT_LAYOUT, fourColour: colours.includes("yellow") };
+}

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

@@ -0,0 +1,16 @@
+import { DeviceMetadata } from "../types";
+/**
+ * Keyed by the 14-bit `deviceId` decoded from the advertisement (see `decodeAdvertisedInfo` in
+ * `protocol.ts`) - Gicisky's own namespace, not shared with other vendors' PID spaces.
+ *
+ * Sourced from `DEVICE_TYPES` in hass-gicisky's `gicisky_ble/devices.py`, the more actively
+ * maintained of the two reference implementations in the sibling `lab` checkouts. That file also
+ * carries a much longer comment table of `deviceId`s seen in the wild that aren't yet mapped to
+ * physical panel facts (`width`/`height`/colours) - those aren't reproduced here since there'd be
+ * nothing to paint correctly for them yet.
+ *
+ * `width`/`height` are the pre-rotation "visual" canvas size - what a template should be designed
+ * at - matching `DeviceEntry.width`/`.height` there; `paintLayout` (`layout.ts`) then rotates/mirrors
+ * during encoding to produce the physical wire layout.
+ */
+export declare const GICISKY_PID_METADATA: DeviceMetadata[];