@rhizomatics/signalk-einklabel-plugin 1.0.0 → 1.2.0

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[];

package/dist/devices/gicisky/metadata.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GICISKY_PID_METADATA = void 0;
+/**
+ * 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.
+ */
+exports.GICISKY_PID_METADATA = [
+    {
+        pid: 0x00a0,
+        manufacturer: "Gicisky",
+        label: '2.1" TFT BW',
+        width: 250,
+        height: 132,
+        voffset: 0,
+        colours: bw(),
+    },
+    {
+        pid: 0x000b,
+        manufacturer: "Gicisky",
+        label: '2.1" BWR',
+        width: 212,
+        height: 104,
+        voffset: 0,
+        colours: bwr(),
+    },
+    {
+        pid: 0x010b,
+        manufacturer: "Gicisky",
+        label: '2.1" BWR',
+        width: 250,
+        height: 128,
+        voffset: 0,
+        colours: bwr(),
+    },
+    {
+        pid: 0x0028,
+        manufacturer: "Gicisky",
+        label: '2.9" BW',
+        width: 296,
+        height: 128,
+        voffset: 0,
+        colours: bw(),
+    },
+    {
+        pid: 0x0033,
+        manufacturer: "Gicisky",
+        label: '2.9" BWR',
+        width: 296,
+        height: 128,
+        voffset: 0,
+        colours: bwr(),
+    },
+    {
+        pid: 0x002e,
+        manufacturer: "Gicisky",
+        label: '2.9" BWRY',
+        width: 296,
+        height: 128,
+        voffset: 0,
+        colours: bwry(),
+    },
+    {
+        pid: 0x022b,
+        manufacturer: "Gicisky",
+        label: '3.7" BWR',
+        width: 240,
+        height: 416,
+        voffset: 0,
+        colours: bwr(),
+    },
+    {
+        pid: 0x004b,
+        manufacturer: "Gicisky",
+        label: '4.2" BWR',
+        width: 400,
+        height: 300,
+        voffset: 0,
+        colours: bwr(),
+    },
+    {
+        pid: 0x004e,
+        manufacturer: "Gicisky",
+        label: '4.2" BWRY',
+        width: 400,
+        height: 300,
+        voffset: 0,
+        colours: bwry(),
+    },
+    {
+        pid: 0x012b,
+        manufacturer: "Gicisky",
+        label: '7.5" BWR',
+        width: 800,
+        height: 480,
+        voffset: 0,
+        colours: bwr(),
+    },
+    {
+        pid: 0x008b,
+        manufacturer: "Gicisky",
+        label: '10.2" BWR',
+        width: 960,
+        height: 640,
+        voffset: 0,
+        colours: bwr(),
+    },
+];
+function bw() {
+    return ["black", "white"];
+}
+function bwr() {
+    return ["black", "white", "red"];
+}
+function bwry() {
+    return ["black", "white", "red", "yellow"];
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Gicisky ESL BLE protocol, transcribed from two reference implementations in the sibling
+ * `lab` checkouts:
+ *  - gicisky-tag (github.com/xxxxx/gicisky-tag) - a minimal CLI writer/scanner.
+ *  - hass-gicisky (github.com/eigger/hass-gicisky) - the more actively maintained Home
+ *    Assistant integration, whose `gicisky_ble` package this mostly follows.
+ */
+/** BLE manufacturer ID Gicisky devices advertise under (20563 decimal). */
+export declare const GICISKY_MANUFACTURER_ID = 20563;
+/**
+ * The two GATT characteristics used for painting, found dynamically rather than hardcoded:
+ * both reference drivers walk every service whose UUID starts `0000f...`, collect their
+ * characteristics, and sort by the 16-bit UUID value - the lowest (observed as `fef1`) is the
+ * command/status characteristic, the next (observed as `fef2`) carries image data. Doing the
+ * same walk here (see `findCommandAndImageCharacteristics` in `index.ts`) survives a firmware
+ * that puts these under a different parent service UUID than expected.
+ */
+export declare const CANDIDATE_SERVICE_UUID_PREFIX = "0000f";
+export interface AdvertisedInfo {
+    /** `((data[4] << 8) | data[0]) & 0x3FFF` - matches this driver's `GICISKY_PID_METADATA` keys. */
+    deviceId: number;
+    /** Un-masked `(data[4] << 8) | data[0])`, kept only for logging - not currently used to disambiguate models. */
+    hardware: number;
+    firmware: number;
+    batteryMv: number;
+}
+/**
+ * Decodes the 5-byte manufacturer-data payload Gicisky devices advertise. Mirrors
+ * `GiciskyBluetoothDeviceData._parse_gicisky` (hass-gicisky's `parser.py`).
+ */
+export declare function decodeAdvertisedInfo(data: Buffer): AdvertisedInfo | undefined;
+export declare const COMMAND: {
+    readonly requestBlockSize: 1;
+    readonly writeScreen: 2;
+    readonly startImageTransfer: 3;
+};
+/** `write_start_with_response`'s ack: `[0x01, <blockSize LE16>]` - observed as 244 on real hardware. */
+export declare function decodeBlockSize(ack: Buffer): number | undefined;
+/**
+ * Builds the `writeScreen` command announcing the total encoded payload size.
+ *
+ * `compression2` devices (7.5"/10.2") expect a 6-byte packet with a trailing `0x01` flag byte;
+ * every other device expects an 8-byte packet with 3 trailing zero bytes. Mirrors
+ * `GiciskyClient._make_cmd_packet` (hass-gicisky's `writer.py`).
+ */
+export declare function writeScreenCommand(payloadLength: number, compression2: boolean): Buffer;
+/** Builds one image-data packet: a 4-byte LE part index followed by that part's chunk. */
+export declare function imageChunkPacket(part: number, chunk: Buffer): Buffer;
+/** Ack shared by `startImageTransfer` and every image-data chunk: `[0x05, 0x00, <nextPart LE32>]`. */
+export declare function decodeTransferAck(ack: Buffer): {
+    ok: boolean;
+    nextPart: number;
+} | undefined;

package/dist/devices/gicisky/protocol.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Gicisky ESL BLE protocol, transcribed from two reference implementations in the sibling
+ * `lab` checkouts:
+ *  - gicisky-tag (github.com/xxxxx/gicisky-tag) - a minimal CLI writer/scanner.
+ *  - hass-gicisky (github.com/eigger/hass-gicisky) - the more actively maintained Home
+ *    Assistant integration, whose `gicisky_ble` package this mostly follows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND = exports.CANDIDATE_SERVICE_UUID_PREFIX = exports.GICISKY_MANUFACTURER_ID = void 0;
+exports.decodeAdvertisedInfo = decodeAdvertisedInfo;
+exports.decodeBlockSize = decodeBlockSize;
+exports.writeScreenCommand = writeScreenCommand;
+exports.imageChunkPacket = imageChunkPacket;
+exports.decodeTransferAck = decodeTransferAck;
+/** BLE manufacturer ID Gicisky devices advertise under (20563 decimal). */
+exports.GICISKY_MANUFACTURER_ID = 0x5053;
+/**
+ * The two GATT characteristics used for painting, found dynamically rather than hardcoded:
+ * both reference drivers walk every service whose UUID starts `0000f...`, collect their
+ * characteristics, and sort by the 16-bit UUID value - the lowest (observed as `fef1`) is the
+ * command/status characteristic, the next (observed as `fef2`) carries image data. Doing the
+ * same walk here (see `findCommandAndImageCharacteristics` in `index.ts`) survives a firmware
+ * that puts these under a different parent service UUID than expected.
+ */
+exports.CANDIDATE_SERVICE_UUID_PREFIX = "0000f";
+/**
+ * Decodes the 5-byte manufacturer-data payload Gicisky devices advertise. Mirrors
+ * `GiciskyBluetoothDeviceData._parse_gicisky` (hass-gicisky's `parser.py`).
+ */
+function decodeAdvertisedInfo(data) {
+    if (data.length !== 5) {
+        return undefined;
+    }
+    const hardware = (data[4] << 8) | data[0];
+    return {
+        deviceId: hardware & 0x3fff,
+        hardware,
+        firmware: (data[2] << 8) | data[3],
+        batteryMv: data[1] * 100,
+    };
+}
+exports.COMMAND = {
+    requestBlockSize: 0x01,
+    writeScreen: 0x02,
+    startImageTransfer: 0x03,
+};
+/** `write_start_with_response`'s ack: `[0x01, <blockSize LE16>]` - observed as 244 on real hardware. */
+function decodeBlockSize(ack) {
+    if (ack.length < 3 || ack[0] !== exports.COMMAND.requestBlockSize) {
+        return undefined;
+    }
+    return ack.readUInt16LE(1);
+}
+/**
+ * Builds the `writeScreen` command announcing the total encoded payload size.
+ *
+ * `compression2` devices (7.5"/10.2") expect a 6-byte packet with a trailing `0x01` flag byte;
+ * every other device expects an 8-byte packet with 3 trailing zero bytes. Mirrors
+ * `GiciskyClient._make_cmd_packet` (hass-gicisky's `writer.py`).
+ */
+function writeScreenCommand(payloadLength, compression2) {
+    if (compression2) {
+        const packet = Buffer.alloc(6);
+        packet[0] = exports.COMMAND.writeScreen;
+        packet.writeUInt32LE(payloadLength, 1);
+        packet[5] = 0x01;
+        return packet;
+    }
+    const packet = Buffer.alloc(8);
+    packet[0] = exports.COMMAND.writeScreen;
+    packet.writeUInt32LE(payloadLength, 1);
+    return packet;
+}
+/** Builds one image-data packet: a 4-byte LE part index followed by that part's chunk. */
+function imageChunkPacket(part, chunk) {
+    const packet = Buffer.alloc(4 + chunk.length);
+    packet.writeUInt32LE(part, 0);
+    chunk.copy(packet, 4);
+    return packet;
+}
+/** Ack shared by `startImageTransfer` and every image-data chunk: `[0x05, 0x00, <nextPart LE32>]`. */
+function decodeTransferAck(ack) {
+    if (ack.length < 6 || ack[0] !== 0x05) {
+        return undefined;
+    }
+    return { ok: ack[1] === 0x00, nextPart: ack.readUInt32LE(2) };
+}

package/dist/devices/types.d.ts

@@ -1,5 +1,6 @@
 import { Device } from "@naugehyde/node-ble";
 import { Bitmap } from "../render/types";
+import { ReframeMode } from "../render/reframe";
 export type Colour = "black" | "white" | "red" | "yellow";
 /**
  * Static facts about one device model, keyed by (vendor, pid) by the registry —
@@ -57,6 +58,8 @@ export interface VendorDeviceConfig {
     modelOverride?: DeviceModelOverride;
     /** How long to wait for the BLE connect step before giving up - if omitted, the driver picks its own default. */
     connectTimeoutMs?: number;
+    /** How to fit the bitmap onto the panel when its size doesn't already match - see `ReframeMode`. Defaults to `"fixed"`, i.e. unchanged (encoding then rejects the mismatch, as it always has). */
+    reframe?: ReframeMode;
 }
 export interface VendorDriver {
     vendor: string;

package/dist/devices/zhsunyco/index.js

@@ -5,6 +5,7 @@ const bleDiscovery_1 = require("../bleDiscovery");
 const pluginVersion_1 = require("../../pluginVersion");
 const metadata_1 = require("./metadata");
 const encode_1 = require("./encode");
+const reframe_1 = require("../../render/reframe");
 const protocol_1 = require("./protocol");
 /** node-ble has no MTU API; this matches the reference driver's mtu(247)-9 default. */
 const UPLOAD_CHUNK_SIZE = 238;
@@ -86,7 +87,8 @@ class ZhsunycoDriver {
                 const challenge = await authChar.readValue();
                 await authChar.writeValueWithoutResponse((0, protocol_1.authResponse)(challenge, aesKey));
                 await (0, bleDiscovery_1.sleep)(AUTH_SETTLE_DELAY_MS);
-                const pixelData = (0, encode_1.encodeBitmap)(bitmap, metadata);
+                const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "fixed");
+                const pixelData = (0, encode_1.encodeBitmap)(framed, metadata);
                 for (let offset = 0; offset < pixelData.length; offset += UPLOAD_CHUNK_SIZE) {
                     const chunk = pixelData.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
                     await dataChar.writeValueWithResponse(Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]));

package/dist/plugin.js

@@ -4,6 +4,7 @@ exports.createPlugin = createPlugin;
 const config_1 = require("./config");
 const registry_1 = require("./devices/registry");
 const zhsunyco_1 = require("./devices/zhsunyco");
+const gicisky_1 = require("./devices/gicisky");
 const discoveryCoordinator_1 = require("./devices/discoveryCoordinator");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
@@ -33,6 +34,7 @@ async function runStartupScan(app, durationSeconds) {
 }
 function createPlugin(app) {
     (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
+    (0, registry_1.registerDriver)(new gicisky_1.GiciskyDriver());
     let scheduler;
     const plugin = {
         id: "signalk-einklabel-plugin",

package/dist/render/binding.d.ts

@@ -76,6 +76,15 @@ export declare function resourceContextKey(binding: Pick<Binding, "resource" | "
  * way as a `<text>` binding.
  */
 export declare function findBindings(svgSource: string): Binding[];
+/**
+ * Reads the root `<svg>` element's declared `width`/`height` (falling back to the 3rd/4th `viewBox`
+ * numbers when either attribute is missing) - lets a caller default a render size to what the template
+ * itself was authored for, e.g. the CLI's -w/--width and --height options.
+ */
+export declare function readTemplateDimensions(svgSource: string): {
+    width?: number;
+    height?: number;
+};
 /** Resolves a parsed `Binding` against the render context assembled by `assembleRawContext`. */
 export declare function resolveBinding(binding: Binding, context: TemplateContext): unknown;
 /**

package/dist/render/binding.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseBinding = parseBinding;
 exports.resourceContextKey = resourceContextKey;
 exports.findBindings = findBindings;
+exports.readTemplateDimensions = readTemplateDimensions;
 exports.resolveBinding = resolveBinding;
 exports.renderBinding = renderBinding;
 exports.buildLabelContext = buildLabelContext;
@@ -99,6 +100,26 @@ function findBindings(svgSource) {
     }
     return bindings;
 }
+/**
+ * Reads the root `<svg>` element's declared `width`/`height` (falling back to the 3rd/4th `viewBox`
+ * numbers when either attribute is missing) - lets a caller default a render size to what the template
+ * itself was authored for, e.g. the CLI's -w/--width and --height options.
+ */
+function readTemplateDimensions(svgSource) {
+    const doc = new xmldom_1.DOMParser().parseFromString(svgSource, "image/svg+xml");
+    const svg = doc.getElementsByTagName("svg").item(0);
+    if (!svg)
+        return {};
+    const viewBox = svg.getAttribute("viewBox")?.trim().split(/\s+/).map(Number);
+    const viewBoxWidth = viewBox?.length === 4 && Number.isFinite(viewBox[2]) ? viewBox[2] : undefined;
+    const viewBoxHeight = viewBox?.length === 4 && Number.isFinite(viewBox[3]) ? viewBox[3] : undefined;
+    const width = parseFloat(svg.getAttribute("width") ?? "");
+    const height = parseFloat(svg.getAttribute("height") ?? "");
+    return {
+        width: Number.isFinite(width) ? width : viewBoxWidth,
+        height: Number.isFinite(height) ? height : viewBoxHeight,
+    };
+}
 /** Supports both `a.[0].b` and `a[0].b` array index notation, matching `setAtPath` in repaintScheduler.ts. */
 function getAtPath(obj, path) {
     const segments = path

package/dist/render/reframe.d.ts

@@ -0,0 +1,12 @@
+import { Bitmap } from "./types";
+/**
+ * How a rendered bitmap is fitted onto a device's actual panel size when the two don't match -
+ * `"fixed"` (the default, and the only behaviour before this existed) makes no change, leaving each
+ * vendor driver's own exact-size check in `encodeBitmap` to reject the mismatch; `"scale"` scales
+ * the source onto the target dimensions independently per axis (not preserving aspect ratio);
+ * `"crop"` keeps source pixels 1:1, placing them from the top-left and either truncating whatever
+ * doesn't fit (source bigger than target) or leaving the extra target space blank (source smaller).
+ */
+export type ReframeMode = "fixed" | "scale" | "crop";
+/** Applies `mode` to fit `bitmap` onto a `targetWidth`x`targetHeight` panel - a no-op whenever the size already matches, regardless of mode. */
+export declare function reframeBitmap(bitmap: Bitmap, targetWidth: number, targetHeight: number, mode: ReframeMode): Bitmap;