@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.2.0

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 —
@@ -13,6 +14,14 @@ export interface DeviceMetadata {
      * that should be treated as the default/fallback for that PID.
      */
     hwVersion?: string;
+    /**
+     * Real-world brand name (e.g. "Zhsunyco") - distinct from `VendorDriver.vendor` (e.g. also
+     * "zhsunyco"), which is this codebase's internal BLE-protocol driver key rather than a name meant
+     * for display. Optional since a CLI/config `DeviceModelOverride` for unsupported hardware has no
+     * table entry to source it from - `considerLlmPromptRepaint` (repaintScheduler.ts) falls back to
+     * the driver's own `vendor` key when unset, for a `source=label,path=manufacturer` prompt binding.
+     */
+    manufacturer?: string;
     label: string;
     width: number;
     height: number;
@@ -49,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/devices/zhsunyco/metadata.js

@@ -22,6 +22,7 @@ exports.ZHSUNYCO_PID_METADATA = void 0;
 exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x0008,
+        manufacturer: "Zhsunyco",
         label: '1.54"',
         width: 200,
         height: 200,
@@ -30,6 +31,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x000a,
+        manufacturer: "Zhsunyco",
         label: '2.13"',
         width: 250,
         height: 128,
@@ -38,6 +40,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x000e,
+        manufacturer: "Zhsunyco",
         label: '3.7"',
         width: 416,
         height: 240,
@@ -47,6 +50,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x000e,
         hwVersion: "0103",
+        manufacturer: "Zhsunyco",
         label: '2.13"',
         width: 250,
         height: 128,
@@ -56,6 +60,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x000e,
         hwVersion: "0201",
+        manufacturer: "Zhsunyco",
         label: '3.5"',
         width: 384,
         height: 184,
@@ -65,6 +70,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x000e,
         hwVersion: "0203",
+        manufacturer: "Zhsunyco",
         label: '7.5"',
         width: 800,
         height: 480,
@@ -73,6 +79,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x0012,
+        manufacturer: "Zhsunyco",
         label: '2.9"',
         width: 296,
         height: 128,
@@ -81,6 +88,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x0016,
+        manufacturer: "Zhsunyco",
         label: '4.2"',
         width: 400,
         height: 300,
@@ -89,6 +97,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x001a,
+        manufacturer: "Zhsunyco",
         label: '5.8"',
         width: 648,
         height: 480,

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 import { ServerAPI, Plugin } from "@signalk/server-api";
 import { registerDriver, getDriver, allDrivers } from "./devices/registry";
+import { registerTemplateProvider as registerTemplateProviderImpl, findTemplateProvider as findTemplateProviderImpl, allTemplateProviders as allTemplateProvidersImpl } from "./render/templateProviders";
+import { SvgRenderer } from "./render/svgRenderer";
+import { bitmapToPng as bitmapToPngImpl } from "./render/png";
+import { buildLabelContext, findTextBindings, substituteTextBindings } from "./render/binding";
 import type { VendorDriver as VendorDriverType, DeviceMetadata as DeviceMetadataType, DiscoveredDevice as DiscoveredDeviceType, VendorDeviceConfig as VendorDeviceConfigType, Colour as ColourType } from "./devices/types";
+import type { TemplateProvider as TemplateProviderType, TemplateRenderRequest as TemplateRenderRequestType } from "./render/templateProviders";
+import type { LabelMeta as LabelMetaType } from "./render/binding";
+import type { Bitmap as BitmapType, TemplateContext as TemplateContextType } from "./render/types";
 /**
  * Public extension point for vendor packages. A package that adds support for a new
  * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
@@ -8,19 +15,45 @@ import type { VendorDriver as VendorDriverType, DeviceMetadata as DeviceMetadata
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a `peerDependency` (not a regular dependency) in the
- * extension package, so npm resolves a single shared copy - otherwise the extension
- * would register into a different registry instance than the one this plugin reads from.
+ * Declare this package as a regular `dependency` in the extension package (**not** a
+ * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
+ * interacts poorly with the server's plugin install layout), and declare the SignalK-level
+ * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
+ * extension's own package.json instead, so the App Store can install/report the dependency.
  */
 declare function plugin(app: ServerAPI): Plugin;
 declare namespace plugin {
     const registerVendorDriver: typeof registerDriver;
     const getVendorDriver: typeof getDriver;
     const allVendorDrivers: typeof allDrivers;
+    /**
+     * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
+     * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
+     * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
+     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     */
+    const registerTemplateProvider: typeof registerTemplateProviderImpl;
+    const getTemplateProvider: typeof findTemplateProviderImpl;
+    const allTemplateProviders: typeof allTemplateProvidersImpl;
+    /** Rasterizes an SVG string to a `Bitmap` - a template provider needs this to turn whatever SVG it produces (e.g. an LLM's response) into paintable pixels, exactly as a bundled template is rendered. */
+    const Renderer: typeof SvgRenderer;
+    /** Encodes a `Bitmap` as PNG bytes - useful for a CLI extension writing a preview file, same as the core plugin's own `render`/`generate` commands. */
+    const bitmapToPng: typeof bitmapToPngImpl;
+    /** Facts about one physical label (`source=label,path=...` bindings resolve against these) - see `./render/binding.ts`. */
+    const buildLabel: typeof buildLabelContext;
+    /** Every `{...}` placeholder referenced across one or more text fragments, parsed as bindings - see `./render/binding.ts`. */
+    const findBindingsInText: typeof findTextBindings;
+    /** Substitutes every `{...}` placeholder in `text` with its resolved binding value - see `./render/binding.ts`. */
+    const substituteBindingsInText: typeof substituteTextBindings;
     type VendorDriver = VendorDriverType;
     type DeviceMetadata = DeviceMetadataType;
     type DiscoveredDevice = DiscoveredDeviceType;
     type VendorDeviceConfig = VendorDeviceConfigType;
     type Colour = ColourType;
+    type TemplateProvider = TemplateProviderType;
+    type TemplateRenderRequest = TemplateRenderRequestType;
+    type LabelMeta = LabelMetaType;
+    type Bitmap = BitmapType;
+    type TemplateContext = TemplateContextType;
 }
 export = plugin;

package/dist/index.js

@@ -1,6 +1,10 @@
 "use strict";
 const plugin_1 = require("./plugin");
 const registry_1 = require("./devices/registry");
+const templateProviders_1 = require("./render/templateProviders");
+const svgRenderer_1 = require("./render/svgRenderer");
+const png_1 = require("./render/png");
+const binding_1 = require("./render/binding");
 /**
  * Public extension point for vendor packages. A package that adds support for a new
  * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
@@ -8,9 +12,11 @@ const registry_1 = require("./devices/registry");
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a `peerDependency` (not a regular dependency) in the
- * extension package, so npm resolves a single shared copy - otherwise the extension
- * would register into a different registry instance than the one this plugin reads from.
+ * Declare this package as a regular `dependency` in the extension package (**not** a
+ * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
+ * interacts poorly with the server's plugin install layout), and declare the SignalK-level
+ * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
+ * extension's own package.json instead, so the App Store can install/report the dependency.
  */
 function plugin(app) {
     return (0, plugin_1.createPlugin)(app);
@@ -19,5 +25,24 @@ function plugin(app) {
     plugin.registerVendorDriver = registry_1.registerDriver;
     plugin.getVendorDriver = registry_1.getDriver;
     plugin.allVendorDrivers = registry_1.allDrivers;
+    /**
+     * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
+     * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
+     * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
+     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     */
+    plugin.registerTemplateProvider = templateProviders_1.registerTemplateProvider;
+    plugin.getTemplateProvider = templateProviders_1.findTemplateProvider;
+    plugin.allTemplateProviders = templateProviders_1.allTemplateProviders;
+    /** Rasterizes an SVG string to a `Bitmap` - a template provider needs this to turn whatever SVG it produces (e.g. an LLM's response) into paintable pixels, exactly as a bundled template is rendered. */
+    plugin.Renderer = svgRenderer_1.SvgRenderer;
+    /** Encodes a `Bitmap` as PNG bytes - useful for a CLI extension writing a preview file, same as the core plugin's own `render`/`generate` commands. */
+    plugin.bitmapToPng = png_1.bitmapToPng;
+    /** Facts about one physical label (`source=label,path=...` bindings resolve against these) - see `./render/binding.ts`. */
+    plugin.buildLabel = binding_1.buildLabelContext;
+    /** Every `{...}` placeholder referenced across one or more text fragments, parsed as bindings - see `./render/binding.ts`. */
+    plugin.findBindingsInText = binding_1.findTextBindings;
+    /** Substitutes every `{...}` placeholder in `text` with its resolved binding value - see `./render/binding.ts`. */
+    plugin.substituteBindingsInText = binding_1.substituteTextBindings;
 })(plugin || (plugin = {}));
 module.exports = plugin;

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

@@ -1,5 +1,6 @@
+import { Colour } from "../devices/types";
 import { TemplateContext } from "./types";
-declare const SOURCES: readonly ["signalk", "resources", "einklabel"];
+declare const SOURCES: readonly ["signalk", "resources", "einklabel", "label"];
 type Source = (typeof SOURCES)[number];
 /**
  * Parsed form of a `<desc>`'s `key=value,key=value` content - see `parseBinding` for the grammar.
@@ -19,7 +20,12 @@ export interface Binding {
      * for). Set this to pin a template to one provider regardless of what else is installed.
      */
     provider?: string;
-    /** For `source === 'einklabel'`, a dotted path into the plugin's own injected `meta` (e.g. `repainted`), rather than into vessel/resource data. */
+    /**
+     * For `source === 'einklabel'`, a dotted path into the plugin's own injected `meta` (e.g. `repainted`);
+     * for `source === 'label'`, a dotted path into the physical label's own facts (`manufacturer`, `label`,
+     * `width`, `height`, `colours`, `fonts`, `description`, `position` - see `buildLabelContext` below)
+     * rather than into vessel/resource data.
+     */
     path: string;
     /** A named formatter (see `./formatters.ts`), or `'raw'` to suppress automatic unit conversion (see `renderBinding`). */
     format?: string;
@@ -35,6 +41,14 @@ export interface Binding {
      * template doesn't also require duplicating its bundled asset sets.
      */
     assets?: string;
+    /**
+     * Substituted in place of the resolved value when that value is missing (`undefined`/`null`,
+     * e.g. an unpublished SignalK path) - see `renderBinding`. Distinct from an *unset* default (this
+     * field itself being `undefined`), which falls through to the pre-existing "" fallback - explicitly
+     * writing `default=` (an empty value) still counts as "given", so a binding can deliberately default
+     * to blank rather than to `substituteTextBindings`' own "???" below.
+     */
+    default?: string;
 }
 /**
  * Parses a `<desc>` element's text content into a `Binding`, e.g.
@@ -62,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;
 /**
@@ -69,6 +92,8 @@ export declare function resolveBinding(binding: Binding, context: TemplateContex
  * the CLI's `field`/`fields` commands show the same thing a real render would.
  *
  * Precedence for a numeric value:
+ * 0. A missing value (`undefined`/`null`, e.g. an unpublished path) with an explicit `default=` given -
+ *    that default, verbatim, bypassing every step below (there's nothing to format).
  * 1. An explicit named `format=` (anything other than `raw`) - `local_time`/`utc_offset`/`position`.
  * 2. An explicit `category=` - for values with no path metadata of their own, e.g. a `source=resources`
  *    value.
@@ -76,7 +101,65 @@ export declare function resolveBinding(binding: Binding, context: TemplateContex
  *    `context.pathMeta`) by default - `format=raw` opts out of this step only.
  * 4. Falls through to `round=` (`toFixed`), `JSON.stringify` for an unformatted object/array value
  *    (e.g. a path that resolved to a whole sub-tree rather than a leaf) instead of the useless
- *    `String(value)` -> `"[object Object]"`, else `String`.
+ *    `String(value)` -> `"[object Object]"`, else `String`. A missing value with no `default=` given
+ *    still falls through to the pre-existing "" here, unchanged from before `default=` existed.
  */
 export declare function renderBinding(binding: Binding, context: TemplateContext): string;
+/** Facts about one physical label a `source=label,path=...` binding can reference - see `buildLabelContext`. */
+export interface LabelMeta {
+    manufacturer: string;
+    /** The physical panel's own size label, e.g. `'3.7"'` - `DeviceMetadata.label` verbatim, see `../devices/types.ts`. */
+    label: string;
+    width: number;
+    height: number;
+    colours: Colour[];
+    description?: string;
+    position?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/**
+ * Builds the `context.label` object a `source=label,path=...` binding addresses (e.g.
+ * `{source=label,path=width}` in free text, or a `<desc>source=label,path=width</desc>` in an SVG
+ * template - every `{...}`/`<desc>` placeholder is a real binding, so a `label` path always needs the
+ * explicit `source=label,path=` form to disambiguate it from a `signalk` self path). `colours`/`fonts`
+ * are left as arrays (each colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`)
+ * rather than joined into a single string, so a caller can either use them bare (renders as JSON) or add
+ * `format=csv` (see `./formatters.ts`) for a plain comma-separated list. `position`, if given, is rounded
+ * to ~2 decimal places (~1.1km) - fine-grained enough to be meaningfully "for here", coarse enough that
+ * ordinary GPS jitter at anchor doesn't change it tick to tick, which matters because `considerRepaint`
+ * (`../repaintScheduler.ts`) folds this whole object into every device's dedup hash - full-precision
+ * jitter here would otherwise force a repaint (and, for a provider-rendered template, a fresh paid API
+ * call) far more often than the underlying position has actually meaningfully changed.
+ */
+export declare function buildLabelContext(meta: LabelMeta): Record<string, unknown>;
+/**
+ * Every binding referenced across one or more free-text fragments - every `{...}` placeholder,
+ * deduplicated across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding` above), so a bare path (`{design.length}`, `source=signalk,context=self` shorthand),
+ * the full binding grammar (`{source=signalk,path=navigation.position,format=position}`), and a
+ * `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
+ * (`../repaintScheduler.ts`) exactly as a template's own bindings are - it fetches the `signalk`/
+ * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
+ * against `context.label`/`context.meta` instead (built by the caller, not fetched).
+ *
+ * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
+ * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
+ * binding, so one malformed placeholder doesn't take down the whole text. `substituteTextBindings` hits
+ * the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+export declare function findTextBindings(...texts: string[]): Binding[];
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findTextBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for anything
+ * that resolves to no value at all (missing path, invalid binding grammar) rather than "" - prose with a
+ * silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the reader would
+ * notice. Two things override that "???": a binding that resolves successfully to a legitimately empty
+ * string (e.g. an unset `{source=label,path=description}`) is left as empty, since that's a real answer,
+ * not a miss; and a binding with an explicit `default=` uses that default instead, since the caller has
+ * already said what a missing value should read as.
+ */
+export declare function substituteTextBindings(text: string, context: TemplateContext): string;
 export {};