@rhizomatics/signalk-einklabel-plugin 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# 1.2.3
+
+- Improved example tide template for 2.9" Gicisky, and added blank and error templates
+
+# 1.2.2
+
+- Fully implemented the backoff and retry logic on failed paint, by default after 30s
+- Auto reframe now happens in main plugin as well as CLI
+- Auto reframe now defaults to `crop` for CLI, can be overidden back to `fixed`
+- Handle Gicisky stale cache paint failures by prompting a re-scan when necessary
+- Improve background default for `crop` reframing
+
 # 1.2.1
 
 - Additional tide template for 296x128

package/README.md

@@ -8,7 +8,7 @@
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/LICENSE)
 [![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
 
-A SignalK plugin to display data from SignalK paths, Resource APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates, or optionally created from a crafted prompt by GenAI if the companion [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin) is installed.
+A SignalK plugin to display data from SignalK paths, Resource APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates, or optionally created from a crafted prompt by GenAI if the companion [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin) is installed. Supports ESLs from two of the major Chinese manufacturers, and requires no firmware or hardware modifications, switch on and go.
 
 ![Companionway Tidal Clock](docs/assets/images/real_tidal_clock.jpg)
 
@@ -161,6 +161,10 @@ Known by other names, e.g. 'Picksmart', and with white label brands
 
 Templates are simply SVG files, to which expressions can be added to use SignalK data, with options to make it easier to read, like rounding or simplifying dates and times. The template can have sample data in the placeholder, so is easy to layout and visualize.
 
+### Reframing
+
+There's some wiggle room with the `reframe` options to use a template that's a bit too small, or too large, for the label, although best results come from a template that's precisely matching the pixel height and width of the label. Next best is template that has the same aspect ratio, so it can be cleanly scaled. `crop` is the 2nd least worst, though if its only a handful of pixels its often not worth worring about a separate template and `crop` is just fine. `scale` is likely to look worst, since it will force an image in regardless of aspect ratio.
+
 ### Template Families (multiple panel sizes/colours)
 
 A "Template" selection can either be one specific `.svg` file, or a _directory_ holding several versions of the same template for different panel sizes/colour-sets, e.g. `templates/tides/416x240-BWRY.svg` and `templates/tides/250x128-BWRY.svg` both implement the tide clock, just at different sizes.
@@ -284,11 +288,13 @@ The width, height, vertical offset and colour palette for the device are taken f
 
 Left unset, both `render` and `paint` default `-w/--width`/`--height` to the template's own declared `width`/`height` (or `viewBox`) - neither command connects to a device just to size the render, since that would mean an extra BLE connect ahead of `paint`'s own, and doing two back-to-back is exactly the kind of churn that trips real BLE hardware.
 
-`paint` also takes `--reframe <mode>`, applied once it has connected and identified the device, for when the rendered image doesn't come out the same size as its actual panel:
+`paint` also takes `--reframe <mode>`, applied once it has connected and identified the device, for when the rendered image doesn't come out the same size as its actual panel (see [Reframing](#reframing) above):
 
-- `fixed` (default) - no adjustment; a size mismatch is rejected with an error, as it always has been
+- `crop` (default) - keeps pixels 1:1, placed from the top-left; a bigger render is truncated to fit, a smaller one leaves the extra panel space blank
 - `scale` - stretches the rendered image onto the panel's exact dimensions (independently per axis, not preserving aspect ratio)
-- `crop` - keeps pixels 1:1, placed from the top-left; a bigger render is truncated to fit, a smaller one leaves the extra panel space blank
+- `fixed` - no adjustment; rejects a size mismatch with an error instead
+
+The main SignalK plugin offers the same choice per device (defaulting to `crop` there too) in each device's own config - "If the render doesn't match the panel size".
 
 `esl-cli` can also be extended with new subcommands by a `-r/--require`'d package - see [Extending](#extending) below - which is how [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) adds its own `prompt`/`generate` commands for testing prompts without a device.
 
@@ -378,8 +384,6 @@ and this version will work even without a running SignalK server, using some pre
 npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -e examples
 ```
 
-
-
 #### List all Fields and Rendered Values
 
 ```bash

package/dist/cli/index.js

@@ -38,7 +38,7 @@ function parseColours(code) {
     }
     return colours;
 }
-const REFRAME_MODES = ["fixed", "scale", "crop"];
+const REFRAME_MODES = ["crop", "scale", "fixed"];
 function parseReframeMode(value) {
     if (!REFRAME_MODES.includes(value)) {
         throw new Error(`unknown --reframe value "${value}" - expected one of ${REFRAME_MODES.join(", ")}`);
@@ -225,7 +225,7 @@ exports.program
     .option("--height <px>", "render height - defaults to the template's declared height/viewBox - see --reframe for fitting onto a differently-sized panel")
     .option("--voffset <px>", "vertical pixel offset of the panel - overrides the looked-up model for unsupported hardware (requires --colours)", "0")
     .option("--colours <code>", "device colour palette for unsupported hardware: BW, BWR, or BWRY - overrides the looked-up model (uses --width/--height/--voffset)")
-    .option("--reframe <mode>", "how to fit the rendered image onto the device's actual panel size when it doesn't match: fixed (default - reject the mismatch, as always), scale (stretch the template to the panel), crop (place at top-left, truncating or leaving the rest blank)", "fixed")
+    .option("--reframe <mode>", "how to fit the rendered image onto the device's actual panel size when it doesn't match: crop (default - place at top-left, truncating or leaving the rest blank), scale (stretch the template to the panel), fixed (reject the mismatch instead)", "crop")
     .option("--connect-timeout <seconds>", "BLE connect timeout before giving up on an attempt", "30")
     .option("--retries <n>", "number of paint attempts (including the first) before giving up", "3")
     .action(async (opts) => {

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { ServerAPI } from "@signalk/server-api";
 import { Colour, DiscoveredDevice } from "./devices/types";
+import { ReframeMode } from "./render/reframe";
 /**
  * Special `device` value meaning "every currently-known discovered device" instead of one specific
  * BLE address - lets a single `DeviceConfig` entry (one template, one trigger) broadcast to every
@@ -49,6 +50,14 @@ export interface DeviceConfig {
     intervalMinute?: number;
     /** One-shot override to repaint even if the data is unchanged; cleared automatically once that repaint completes. */
     forceRepaint?: boolean;
+    /**
+     * How to fit the rendered image onto the device's actual panel size when it doesn't match (see
+     * `ReframeMode`) - e.g. a template family with no variant sized for this particular label. Left
+     * unset, `driver.paint()` defaults to `"crop"` itself (see `VendorDeviceConfig.reframe`'s doc
+     * comment) - place from the top-left, truncating or leaving the rest blank - since a live label
+     * showing *something*, even off-size, beats a repaint that just fails outright.
+     */
+    reframe?: ReframeMode;
 }
 export interface PluginConfig {
     /**

package/dist/config.js

@@ -411,6 +411,13 @@ function configSchema(app, discovered = []) {
                             description: "Repaint even if the data is unchanged - clears itself automatically once that repaint completes",
                             default: false,
                         },
+                        reframe: {
+                            type: "string",
+                            title: "If the render doesn't match the panel size",
+                            description: "Crop: place at the top-left, truncating anything too big or leaving the rest blank if too small. Scale: stretch to fit exactly (may distort). Fixed: fail the repaint instead of showing an off-size image.",
+                            enum: ["crop", "scale", "fixed"],
+                            default: "crop",
+                        },
                     },
                 },
             },
@@ -423,6 +430,7 @@ function configUiSchema() {
             items: {
                 description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
+                reframe: { "ui:widget": "radio" },
             },
         },
     };

package/dist/devices/bleDiscovery.d.ts

@@ -52,3 +52,29 @@ export declare function withDiscovery<T>(durationMs: number, fn: (adapter: Adapt
 export declare function connectWithTimeout(device: Device, timeoutMs: number): Promise<void>;
 /** Uses an already-known device if BlueZ has one cached, otherwise scans until it appears. */
 export declare function getOrDiscoverDevice(adapter: Adapter, address: string, timeoutMs: number): Promise<Device>;
+/**
+ * Returns `device`'s manufacturer data under `manufacturerId` if BlueZ already has it cached, else
+ * actively (re)scans for it - covers a device BlueZ already knows about (so `getOrDiscoverDevice`'s
+ * cheap `adapter.getDevice()` path returns it immediately, never triggering a scan) but whose
+ * advertisement cache is empty or stale, e.g. it hasn't actually been seen since `bluetoothd`
+ * restarted. BlueZ updates the *same* `Device` object's properties in place as fresh adverts arrive
+ * during a discovery window, so this just starts one (unless already running) and polls the existing
+ * `device` handle rather than re-resolving it. Bounded by `timeoutMs`; returns undefined rather than
+ * throwing if nothing arrives in time, so a caller can fall back to its own error/manual-override path.
+ */
+export declare function waitForManufacturerData(adapter: Adapter, device: Device, manufacturerId: number, timeoutMs: number): Promise<Buffer | undefined>;
+/**
+ * Blocks until `bluetooth.defaultAdapter()` actually succeeds, retrying with exponential backoff
+ * (2s, doubling, capped at 30s) rather than failing once and giving up - covers the boot-time race
+ * where SignalK starts before bluetoothd/D-Bus is up (see the README's "SignalK starts before the
+ * Bluetooth daemon" FAQ), and equally a later transient loss (e.g. `bluetoothd` restarting) if a
+ * caller invokes this again rather than just once at startup.
+ *
+ * A non-Linux platform is `createBluetooth`'s own hard incompatibility, not a transient readiness
+ * race, so it returns `false` immediately there instead of retrying forever - preserves this
+ * plugin's "everything except scan/paint still works" story for template development off a real
+ * device (see README's Pre-requisites). `cancelled` is polled between backoff waits so a caller
+ * with its own lifecycle (e.g. the plugin's own `stop()`) can abandon an in-progress wait instead of
+ * leaving it to retry forever in the background after the thing it was waiting to unblock is gone.
+ */
+export declare function waitForAdapter(logDebug: (message: string) => void, cancelled?: () => boolean): Promise<boolean>;

package/dist/devices/bleDiscovery.js

@@ -8,6 +8,8 @@ exports.withRetries = withRetries;
 exports.withDiscovery = withDiscovery;
 exports.connectWithTimeout = connectWithTimeout;
 exports.getOrDiscoverDevice = getOrDiscoverDevice;
+exports.waitForManufacturerData = waitForManufacturerData;
+exports.waitForAdapter = waitForAdapter;
 const node_ble_1 = require("@naugehyde/node-ble");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -157,3 +159,80 @@ async function getOrDiscoverDevice(adapter, address, timeoutMs) {
         }
     }
 }
+const MANUFACTURER_DATA_POLL_MS = 500;
+/**
+ * Returns `device`'s manufacturer data under `manufacturerId` if BlueZ already has it cached, else
+ * actively (re)scans for it - covers a device BlueZ already knows about (so `getOrDiscoverDevice`'s
+ * cheap `adapter.getDevice()` path returns it immediately, never triggering a scan) but whose
+ * advertisement cache is empty or stale, e.g. it hasn't actually been seen since `bluetoothd`
+ * restarted. BlueZ updates the *same* `Device` object's properties in place as fresh adverts arrive
+ * during a discovery window, so this just starts one (unless already running) and polls the existing
+ * `device` handle rather than re-resolving it. Bounded by `timeoutMs`; returns undefined rather than
+ * throwing if nothing arrives in time, so a caller can fall back to its own error/manual-override path.
+ */
+async function waitForManufacturerData(adapter, device, manufacturerId, timeoutMs) {
+    const key = manufacturerId.toString();
+    const existing = await device.getManufacturerData().catch(() => undefined);
+    if (existing?.[key]) {
+        return existing[key];
+    }
+    const wasDiscovering = await adapter.isDiscovering();
+    if (!wasDiscovering) {
+        await adapter.startDiscovery();
+    }
+    try {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const data = await device.getManufacturerData().catch(() => undefined);
+            if (data?.[key]) {
+                return data[key];
+            }
+            await sleep(MANUFACTURER_DATA_POLL_MS);
+        }
+        return undefined;
+    }
+    finally {
+        if (!wasDiscovering) {
+            await adapter.stopDiscovery();
+        }
+    }
+}
+const ADAPTER_WAIT_BASE_DELAY_MS = 2000;
+const ADAPTER_WAIT_MAX_DELAY_MS = 30000;
+/**
+ * Blocks until `bluetooth.defaultAdapter()` actually succeeds, retrying with exponential backoff
+ * (2s, doubling, capped at 30s) rather than failing once and giving up - covers the boot-time race
+ * where SignalK starts before bluetoothd/D-Bus is up (see the README's "SignalK starts before the
+ * Bluetooth daemon" FAQ), and equally a later transient loss (e.g. `bluetoothd` restarting) if a
+ * caller invokes this again rather than just once at startup.
+ *
+ * A non-Linux platform is `createBluetooth`'s own hard incompatibility, not a transient readiness
+ * race, so it returns `false` immediately there instead of retrying forever - preserves this
+ * plugin's "everything except scan/paint still works" story for template development off a real
+ * device (see README's Pre-requisites). `cancelled` is polled between backoff waits so a caller
+ * with its own lifecycle (e.g. the plugin's own `stop()`) can abandon an in-progress wait instead of
+ * leaving it to retry forever in the background after the thing it was waiting to unblock is gone.
+ */
+async function waitForAdapter(logDebug, cancelled = () => false) {
+    if (process.platform !== "linux")
+        return false;
+    let delayMs = ADAPTER_WAIT_BASE_DELAY_MS;
+    while (!cancelled()) {
+        let destroy;
+        try {
+            const created = createBluetooth();
+            destroy = created.destroy;
+            await created.bluetooth.defaultAdapter();
+            return true;
+        }
+        catch (err) {
+            logDebug(`BLE adapter not ready (${err.message}) - retrying in ${delayMs / 1000}s...`);
+            await sleep(delayMs);
+            delayMs = Math.min(delayMs * 2, ADAPTER_WAIT_MAX_DELAY_MS);
+        }
+        finally {
+            destroy?.();
+        }
+    }
+    return false;
+}

package/dist/devices/gicisky/encode.js

@@ -12,9 +12,19 @@ const FALLBACK = {
     yellow: "red",
     red: "black",
 };
-function classifyColour(r, g, b, supported) {
+/** Below this, a pixel counts as "blank" rather than whatever colour its (possibly meaningless, for a fully transparent pixel) RGB happens to hold. */
+const TRANSPARENT_ALPHA_THRESHOLD = 128;
+/**
+ * A mostly-transparent pixel - undrawn SVG canvas, e.g. a template resized without its background
+ * rect following - classifies as white (blank paper), not the RGB-thresholds' own default of black:
+ * resvg-wasm leaves transparent pixels at RGB (0,0,0), and without this check that reads as
+ * ink-black rather than the blank label surface it actually represents.
+ */
+function classifyColour(r, g, b, a, supported) {
     let colour = "black";
-    if (r > 150 && g > 150 && b > 150)
+    if (a < TRANSPARENT_ALPHA_THRESHOLD)
+        colour = "white";
+    else if (r > 150 && g > 150 && b > 150)
         colour = "white";
     else if (r > 150 && g > 100 && b < 80)
         colour = "yellow";
@@ -69,7 +79,7 @@ function packPlane(bitmap, layout, supported, predicate) {
             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 colour = classifyColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], bitmap.data[offset + 3], supported);
             if (predicate(colour)) {
                 const byteIndex = y * bytesPerRow + (x >> 3);
                 plane[byteIndex] |= 0x80 >> (x % 8);
@@ -90,7 +100,7 @@ function packFourColour(bitmap, layout, supported) {
             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 colour = classifyColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], bitmap.data[offset + 3], supported);
             const code = FOUR_COLOUR_CODE[colour];
             const byteIndex = y * bytesPerRow + Math.floor(x / pixelsPerByte);
             const shift = 6 - (x % pixelsPerByte) * 2;

package/dist/devices/gicisky/index.js

@@ -8,6 +8,8 @@ const encode_1 = require("./encode");
 const reframe_1 = require("../../render/reframe");
 const protocol_1 = require("./protocol");
 const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+/** How long to actively rescan for a fresh advertisement when the cached one is missing/stale - see `waitForManufacturerData`. */
+const MANUFACTURER_DATA_RESCAN_TIMEOUT_MS = 15000;
 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. */
@@ -53,12 +55,12 @@ class GiciskyDriver {
              * 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`).
+             * connecting first - see `forEachAdvertisedDevice` in `bleDiscovery.ts`). That cache can be
+             * empty or stale (e.g. nothing has actively scanned since `bluetoothd` last restarted) even
+             * though `getOrDiscoverDevice` above found the device instantly via BlueZ's own cache of
+             * *devices* - so rescan for a fresh advertisement here rather than failing on the first read.
              */
-            const manufacturerData = await device
-                .getManufacturerData()
-                .then((data) => data[protocol_1.GICISKY_MANUFACTURER_ID.toString()])
-                .catch(() => undefined);
+            const manufacturerData = await (0, bleDiscovery_1.waitForManufacturerData)(adapter, device, protocol_1.GICISKY_MANUFACTURER_ID, MANUFACTURER_DATA_RESCAN_TIMEOUT_MS);
             const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
             const metadata = config.modelOverride
                 ? { pid: info?.deviceId ?? 0, ...config.modelOverride }
@@ -67,12 +69,13 @@ class GiciskyDriver {
                     : 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 isn't advertising - rescanned but got nothing back (out of range, asleep, or already connected " +
+                        "elsewhere) - 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 framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop");
             const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout);
             await (0, bleDiscovery_1.connectWithTimeout)(device, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
             try {

package/dist/devices/types.d.ts

@@ -58,7 +58,7 @@ 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). */
+    /** How to fit the bitmap onto the panel when its size doesn't already match - see `ReframeMode`. Defaults to `"crop"` - a live label showing *something*, even off-size, beats a repaint that just fails outright; pass `"fixed"` explicitly to get the old reject-the-mismatch behaviour back. */
     reframe?: ReframeMode;
 }
 export interface VendorDriver {

package/dist/devices/zhsunyco/encode.js

@@ -16,10 +16,21 @@ const FALLBACK = {
     yellow: "red",
     red: "black",
 };
-/** Mirrors the reference driver's `from_pillow` nearest-colour decision tree, then maps the result down onto whatever colours this particular device's panel actually supports (see `DeviceMetadata.colours`). */
-function nearestColour(r, g, b, supported) {
+/** Below this, a pixel counts as "blank" rather than whatever colour its (possibly meaningless, for a fully transparent pixel) RGB happens to hold. */
+const TRANSPARENT_ALPHA_THRESHOLD = 128;
+/**
+ * Mirrors the reference driver's `from_pillow` nearest-colour decision tree, then maps the result
+ * down onto whatever colours this particular device's panel actually supports (see
+ * `DeviceMetadata.colours`). A mostly-transparent pixel - undrawn SVG canvas, e.g. a template resized
+ * without its background rect following - classifies as white (blank paper), not the RGB-thresholds'
+ * own default of black: resvg-wasm leaves transparent pixels at RGB (0,0,0), and without this check
+ * that reads as ink-black rather than the blank label surface it actually represents.
+ */
+function nearestColour(r, g, b, a, supported) {
     let colour = "black";
-    if (r > 150 && g > 150 && b > 150)
+    if (a < TRANSPARENT_ALPHA_THRESHOLD)
+        colour = "white";
+    else if (r > 150 && g > 150 && b > 150)
         colour = "white";
     else if (r > 150 && g > 100 && b < 80)
         colour = "yellow";
@@ -65,5 +76,5 @@ function encodeBitmap(bitmap, metadata) {
 }
 function samplePixel(bitmap, x, y, supported) {
     const offset = (y * bitmap.width + x) * 4;
-    return nearestColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], supported);
+    return nearestColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], bitmap.data[offset + 3], supported);
 }

package/dist/devices/zhsunyco/index.js

@@ -87,7 +87,7 @@ 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 framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "fixed");
+                const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop");
                 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);

package/dist/email/emailSender.d.ts

@@ -0,0 +1,27 @@
+import { EmailConfig } from "../config";
+import { Bitmap } from "../render/types";
+import { FieldRow } from "../render/fieldsTable";
+/** Either the SVG template's field-by-field table (`buildFieldsTable`), a `TemplateProvider`'s own rendered-content text (`describeContent`), or neither (a provider offered no `describeContent`). */
+export type EmailContentBody = {
+    kind: "table";
+    rows: FieldRow[];
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "none";
+};
+export interface LabelEmailContent {
+    friendlyName: string;
+    description?: string;
+    bitmap: Bitmap;
+    body: EmailContentBody;
+}
+/**
+ * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
+ * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
+ * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
+ * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
+ * device's `emailTo` is set and its render succeeds.
+ */
+export declare function sendLabelEmail(emailConfig: EmailConfig, to: string, content: LabelEmailContent): Promise<void>;

package/dist/email/emailSender.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendLabelEmail = sendLabelEmail;
+const nodemailer_1 = __importDefault(require("nodemailer"));
+const png_1 = require("../render/png");
+const DOCS_URL = "https://rhizomatics.github.io/signalk-einklabel-plugin/";
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function bodyHtml(body) {
+    if (body.kind === "table") {
+        if (body.rows.length === 0)
+            return "";
+        const rows = body.rows
+            .map((row) => `<tr><td>${escapeHtml(row.id)}</td><td>${escapeHtml(row.spec)}</td><td>${escapeHtml(row.value)}</td></tr>`)
+            .join("");
+        return ('<table border="1" cellpadding="4" cellspacing="0" style="border-collapse:collapse;font-family:monospace;font-size:13px">' +
+            `<thead><tr><th>id</th><th>spec</th><th>value</th></tr></thead><tbody>${rows}</tbody></table>`);
+    }
+    if (body.kind === "text") {
+        return `<pre style="white-space:pre-wrap;font-family:monospace;font-size:13px">${escapeHtml(body.text)}</pre>`;
+    }
+    return "";
+}
+/**
+ * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
+ * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
+ * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
+ * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
+ * device's `emailTo` is set and its render succeeds.
+ */
+async function sendLabelEmail(emailConfig, to, content) {
+    const transporter = nodemailer_1.default.createTransport({
+        host: emailConfig.smtpHost,
+        port: emailConfig.smtpPort,
+        secure: emailConfig.smtpSecure,
+        auth: emailConfig.smtpUser ? { user: emailConfig.smtpUser, pass: emailConfig.smtpPassword } : undefined,
+    });
+    const png = (0, png_1.bitmapToPng)(content.bitmap);
+    const html = [
+        '<div style="font-family:sans-serif">',
+        `<h2>${escapeHtml(content.friendlyName)}</h2>`,
+        content.description ? `<p>${escapeHtml(content.description)}</p>` : "",
+        `<p><img src="cid:label-image" alt="${escapeHtml(content.friendlyName)}" style="border:1px solid #ccc" /></p>`,
+        bodyHtml(content.body),
+        `<p><a href="${DOCS_URL}">${DOCS_URL}</a></p>`,
+        "</div>",
+    ].join("\n");
+    await transporter.sendMail({
+        from: emailConfig.fromAddress,
+        to,
+        subject: `eInk Label: ${content.friendlyName}`,
+        html,
+        attachments: [
+            {
+                filename: "label.png",
+                content: png,
+                contentType: "image/png",
+                cid: "label-image",
+            },
+        ],
+    });
+}

package/dist/plugin.js

@@ -6,6 +6,7 @@ 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 bleDiscovery_1 = require("./devices/bleDiscovery");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
 /** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
@@ -36,6 +37,7 @@ function createPlugin(app) {
     (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
     (0, registry_1.registerDriver)(new gicisky_1.GiciskyDriver());
     let scheduler;
+    let stopped = false;
     const plugin = {
         id: "signalk-einklabel-plugin",
         name: "eInk ESL (Electronic Shelf Label)",
@@ -52,12 +54,22 @@ function createPlugin(app) {
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
             (0, config_1.healNestedConfig)(app);
-            if (pluginConfig.scanOnStart) {
-                void runStartupScan(app, pluginConfig.scanDurationSeconds);
-            }
-            scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
+            stopped = false;
+            // Waits (with backoff, indefinitely on Linux) for a BLE adapter before the startup scan or the
+            // repaint scheduler touch BLE at all - see `waitForAdapter`'s doc comment on the boot-time race
+            // this covers. `stopped` is checked after, not just passed as `cancelled`, since the wait can
+            // also resolve `true` on its own right as `stop()` runs.
+            void (0, bleDiscovery_1.waitForAdapter)((message) => app.debug(message), () => stopped).then(() => {
+                if (stopped)
+                    return;
+                if (pluginConfig.scanOnStart) {
+                    void runStartupScan(app, pluginConfig.scanDurationSeconds);
+                }
+                scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
+            });
         },
         stop() {
+            stopped = true;
             scheduler?.stop();
             scheduler = undefined;
             app.debug("stopped");

package/dist/render/fieldsTable.d.ts

@@ -0,0 +1,15 @@
+import { TemplateContext } from "./types";
+export interface FieldRow {
+    id: string;
+    spec: string;
+    value: string;
+}
+/**
+ * Synchronous counterpart to the CLI's `fields` command (`../cli/index.ts`) - same three columns (id,
+ * spec, resolved value), but resolved against a single already-assembled `context` rather than
+ * re-fetching per binding, since a caller like `considerRepaint` (`../repaintScheduler.ts`) already has
+ * the full context its render used. Only meaningful for a hand-authored SVG template - a
+ * `TemplateProvider`-backed template (e.g. GenAI) has no `<desc>` bindings to walk; see
+ * `TemplateProvider.describeContent` (`./templateProviders.ts`) for that case's own text summary instead.
+ */
+export declare function buildFieldsTable(svgSource: string, context: TemplateContext, templatesDir: string, bundledTemplatesDir: string): FieldRow[];

package/dist/render/fieldsTable.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFieldsTable = buildFieldsTable;
+const path_1 = require("path");
+const xmldom_1 = require("@xmldom/xmldom");
+const assets_1 = require("./assets");
+const binding_1 = require("./binding");
+function resolveFieldValue(tag, desc, context, templatesDir, bundledTemplatesDir) {
+    try {
+        const binding = (0, binding_1.parseBinding)(desc);
+        if (tag !== "image") {
+            return (0, binding_1.renderBinding)(binding, context);
+        }
+        if (!binding.assets) {
+            return 'ERROR: an <image> binding requires an "assets" key';
+        }
+        const key = (0, assets_1.normalizeAssetKey)((0, binding_1.resolveBinding)(binding, context));
+        if (!key)
+            return "(no usable value - image would be omitted)";
+        const assetPath = (0, assets_1.resolveAssetPath)(templatesDir, bundledTemplatesDir, binding.assets, key);
+        return assetPath ? `"${key}" -> ${(0, path_1.basename)(assetPath)}` : `"${key}" -> no matching asset file (image would be omitted)`;
+    }
+    catch (err) {
+        return `ERROR: ${err.message}`;
+    }
+}
+/**
+ * Synchronous counterpart to the CLI's `fields` command (`../cli/index.ts`) - same three columns (id,
+ * spec, resolved value), but resolved against a single already-assembled `context` rather than
+ * re-fetching per binding, since a caller like `considerRepaint` (`../repaintScheduler.ts`) already has
+ * the full context its render used. Only meaningful for a hand-authored SVG template - a
+ * `TemplateProvider`-backed template (e.g. GenAI) has no `<desc>` bindings to walk; see
+ * `TemplateProvider.describeContent` (`./templateProviders.ts`) for that case's own text summary instead.
+ */
+function buildFieldsTable(svgSource, context, templatesDir, bundledTemplatesDir) {
+    const doc = new xmldom_1.DOMParser().parseFromString(svgSource, "image/svg+xml");
+    const rows = [];
+    for (const tag of ["text", "image"]) {
+        const elements = doc.getElementsByTagName(tag);
+        for (let i = 0; i < elements.length; i++) {
+            const element = elements.item(i);
+            if (!element)
+                continue;
+            const id = element.getAttribute("id") ?? `${tag}#${i}`;
+            const desc = element.getElementsByTagName("desc").item(0);
+            if (!desc?.textContent)
+                continue;
+            rows.push({ id, spec: desc.textContent, value: resolveFieldValue(tag, desc.textContent, context, templatesDir, bundledTemplatesDir) });
+        }
+    }
+    return rows;
+}